authentication-authorization

Files (1)

• SKILL.md

SKILL.md (first lines)

# Authentication & Authorization

## First Decision: Stateless vs Stateful

| | JWT (Stateless) | Sessions (Stateful) |
|---|---|---|
| **Storage** | Client (token) | Server (DB/Redis) |
| **Scale** | No server state — easy horizontal scale | Need shared session store (Redis) |
| **Revoke** | Hard — wait for expiry or maintain blocklist | Instant — delete session |
| **Payload** | Visible to client (don't put secrets) | Opaque to client |
| **Best for** | APIs, mobile, SPAs, microservices | Server-rendered apps, high-security |
| **Library** | `jsonwebtoken`, `jose` | `express-session`, `iron-session` |

**Default for Meta-Architect projects:** JWT with refresh tokens (stateless API + stateful refresh).

## JWT Pattern (Default)

### Token Structure

```typescript
interface JwtPayload {
  sub: string;        // user id — never email (emails change)
  role: string;       // for quick authz checks
  iat: number;        // issued at
  exp: number;        // expiry
  jti?: string;       // token id (for revocation)
}
```

### Implementation

```typescript
// auth.service.ts
import jwt from 'jsonwebtoken';

const ACCESS_SECRET = process.env.JWT_ACCESS_SECRET!;
const REFRESH_SECRET = process.env.JWT_REFRESH_SECRET!;
const ACCESS_EXPIRY = '15m';
const REFRESH_EXPIRY = '7d';

export function generateTokens(user: { id: string; role: string }) {
  const accessToken = jwt.sign(
    { sub: user.id, role: user.role },
    ACCESS_SECRET,
    { expiresIn: ACCESS_EXPIRY }
  );
  const refreshToken = jwt.sign(
    { sub: user.id, jti: crypto.randomUUID() },
    REFRESH_SECRET,
    { expiresIn: REFRESH_EXPIRY }
  );
  return { accessToken, refreshToken, expiresIn: 900 };
}

export function verifyAccessToken(token: string): JwtPayload {
  return jwt.verify(token, ACCESS_SECRET) as JwtPayload;
}

export function verifyRefreshToken(token: string): { sub: string; jti: string } {
  return jwt.verify(token, REFRESH_SECRET) as { sub: string; jti: string };
}
```

### Refresh Token Rotation

```typescript
// On every refresh: issue new pair, invalidate old refresh token
export async function refreshTokens(oldRefreshToken: string, prisma: PrismaClient) {
  const payload = verifyRefreshToken(oldRefreshToken);

  // Check if token was already used (rotation prevents replay)
  const stored = await prisma.refreshToken.findUnique({ where: { jti: payload.jti } });
  if (!stored) throw new Error('Token revoked — possible theft');

  // Delete old token, issue new pair
  await prisma.refreshToken.delete({ where: { jti: payload.jti } });

  const user = await prisma.user.findUniqueOrThrow({ where: { id: payload.sub } });
  const tokens = generateTokens(user);

  await prisma.refreshToken.create({
    data: { jti: jwt.decode(tokens.refreshToken)!.jti, userId: user.id, expiresAt: new Date(Date.now() + 7 * 86400000) },
  });

  return tokens;
}
```

### Auth Middleware

```typescript
// auth.middleware.ts
export function authenticate(req: Request, res: Response, next: NextFunction) {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer ')) return res.status(401).json({ error: 'unauthorized' });

  try {
    const payload = verifyAccessToken(header.split(' ')[1]);
    req.user = { id: payload.sub, role: payload.role };
    next();
  } catch {
    return res.status(401).json({ error: 'token_expired' });
  }
}
```

## Password Hashing

```typescript
import bcrypt from 'bcryptjs';

const SALT_ROUNDS = 12;  // ~250ms — balance security vs speed

export async function hashPassword(password: string): Promise<string> {
  return bcrypt.hash(password, SALT_ROUNDS);
}

export async function verifyPassword(password: string, hash: string): Promise<boolean> {
  return bcrypt.compare(password, hash);

From UgochukwuChidera/Opencode-Agents, GPL-3.0.

More from UgochukwuChidera/Opencode-Agents