authentication-skill

Files (1)

• SKILL.md

SKILL.md (first lines)

# Authentication — Founder OS

## Framework 1: Auth Strategy Selection

| Method | Best For | Complexity | Use When |
|--------|---------|-----------|---------|
| JWT (stateless) | APIs, SPAs, mobile | Medium | Microservices, need to verify without DB lookup |
| Session (stateful) | Traditional web apps | Low | Simpler to revoke, server-side rendering |
| OAuth2 (social) | User acquisition | Medium | Want Google/GitHub login, reduce friction |
| Magic link | Low-friction onboarding | Low | No password friction, B2C products |
| Passkeys (WebAuthn) | Modern, passwordless | High | Future-proofing, security-focused products |

**Recommendation for most SaaS founders:** Start with a managed auth provider (Clerk, Auth0, Supabase Auth, NextAuth). Don't build auth from scratch — it's a security liability.

---

## Framework 2: JWT Implementation

### JWT Structure
```
Header.Payload.Signature

Header: { "alg": "HS256", "typ": "JWT" }
Payload: {
  "sub": "user_123",          // Subject (user ID)
  "iat": 1704067200,          // Issued at (Unix timestamp)
  "exp": 1704153600,          // Expiry (Unix timestamp)
  "jti": "unique_token_id",   // JWT ID (for revocation)
  "role": "admin",            // Custom claims
  "orgId": "org_456"          // Custom claims
}
```

### Token Rotation Pattern
```typescript
// Access token: short-lived (15 minutes)
// Refresh token: long-lived (7-30 days), stored in httpOnly cookie

// On login
const accessToken = jwt.sign(
  { sub: user.id, role: user.role, orgId: user.orgId },
  process.env.JWT_SECRET,
  { expiresIn: '15m' }
);

const refreshToken = crypto.randomBytes(32).toString('hex');
await db.refreshToken.create({
  data: {
    token: hashToken(refreshToken),  // Hash before storing
    userId: user.id,
    expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)
  }
});

// Set refresh token as httpOnly cookie (not accessible to JS)
res.cookie('refresh_token', refreshToken, {
  httpOnly: true,
  secure: true,       // HTTPS only
  sameSite: 'strict',
  maxAge: 30 * 24 * 60 * 60 * 1000
});

// On refresh
// 1. Validate refresh token from cookie
// 2. Delete old refresh token (rotation)
// 3. Issue new access token + new refresh token
// 4. Set new refresh token cookie
```

### Auth Middleware
```typescript
export async function requireAuth(req: Request, res: Response, next: NextFunction) {
  const token = req.headers.authorization?.replace('Bearer ', '');

  if (!token) {
    return res.status(401).json({
      success: false,
      error: { code: 'UNAUTHORIZED', message: 'Authentication required' }
    });
  }

  try {
    const payload = jwt.verify(token, process.env.JWT_SECRET!) as JWTPayload;
    req.user = { id: payload.sub, role: payload.role, orgId: payload.orgId };
    next();
  } catch {
    return res.status(401).json({
      success: false,
      error: { code: 'TOKEN_INVALID', message: 'Token is invalid or expired' }
    });
  }
}
```

---

## Framework 3: OAuth2 / Social Login

### OAuth2 Flow (Google example)
```
1. User clicks "Sign in with Google"
2. Redirect to Google: GET /oauth2/auth?client_id=...&redirect_uri=...&scope=email+profile
3. User authenticates with Google
4. Google redirects back: GET /auth/callback?code=xyz123
5. Exchange code for tokens: POST /oauth2/token
6. Get user info: GET /userinfo (with access_token)
7. Create/find user in your DB, issue your own session/JWT
```

### State Parameter (CSRF protection — required)
```typescript
// Before redirecting to OAuth provider
const state = crypto.randomBytes(16).toString('hex');
req.session.oauthState = state;

const authUrl = new URL('https://accounts.google.com/o/oauth2/v2/auth');
authUrl.searchParams.set('state', state);  // Include state

// On callback

From The13thNode/VibeCorp_PromptCEO, MIT.

More from The13thNode/VibeCorp_PromptCEO