Authentication model

JWT-based authentication system with dual-level access control

OOOC Fête Finder implements a dual-tier authentication system: user authentication for content access and admin authentication for administrative functions.

User authentication

User authentication is email-based and uses JWT tokens stored in HTTP-only cookies.

Authentication flow

1. User submits email via POST /api/auth/verify
2. Server validates email format and rate limits
3. User record created/updated in user collection store
4. JWT token generated and signed with AUTH_SECRET
5. Cookie set with HTTP-only flag

User session token

User sessions are signed JWT tokens with the following structure:

interface UserSessionPayload {
  email: string;
  v: 1; // Token version
  iat: number; // Issued at
  exp: number; // Expires at
  aud: 'oooc-fete-finder:user';
  iss: 'oooc-fete-finder';
}

Algorithm · HS256

HMAC-SHA256 symmetric signing

TTL · 30 days

Tokens expire after 2,592,000 seconds (30 days)

Cookie name · oooc_user_session

HTTP-only cookie with SameSite=lax

See token signing in features/auth/user-session-cookie.ts:32.

Security requirements

AUTH_SECRET must be at least 32 characters long. The application will throw an error on startup if this requirement is not met.

The secret is validated in getUserAuthSecret() at features/auth/user-session-cookie.ts:17.

Cookie configuration

{
  httpOnly: true,
  secure: env.NODE_ENV === 'production',
  sameSite: 'lax',
  path: '/',
  maxAge: 2592000 // 30 days in seconds
}

In production, cookies are restricted to HTTPS only (secure: true). In development, HTTP is allowed for local testing.

See cookie options in features/auth/user-session-cookie.ts:80.

Session verification

Session tokens are verified on each authenticated request:

verifyUserSessionToken(token) {
  jwt.verify(token, AUTH_SECRET, {
    algorithms: ['HS256'],
    audience: 'oooc-fete-finder:user',
    issuer: 'oooc-fete-finder'
  })
}

See verification in features/auth/user-session-cookie.ts:48.

Logout

Users can logout via DELETE /api/auth/session, which clears the session cookie by setting maxAge: 0.

See logout implementation in app/api/auth/session/route.ts:33.

Admin authentication

Admin authentication is more sophisticated, supporting multiple credential types and session management.

Credential types

Admins can authenticate using three methods:

Admin key · X-Admin-Key header

Direct key authentication using ADMIN_KEY environment variable

Bearer token · Authorization: Bearer <token>

JWT bearer token for programmatic access

Session cookie · oooc-admin-auth cookie

HTTP-only cookie for browser sessions

See credential extraction in features/auth/admin-auth-token.ts:263.

Admin key authentication

The simplest form of admin authentication:

X-Admin-Key: <ADMIN_KEY value>

Admin key comparison uses constant-time comparison via timingSafeEqual to prevent timing attacks.

See secure comparison in features/auth/admin-auth-token.ts:55.

Admin JWT sessions

Admin sessions use JWT tokens with session tracking:

interface AdminTokenPayload {
  type: 'admin';
  jti: string; // Unique session ID
  tv: number;  // Token version (for revocation)
  iat: number; // Issued at
  exp: number; // Expires at
  aud: 'admin-api';
  iss: 'oooc-fete-finder';
}

Algorithm · HS256

HMAC-SHA256 symmetric signing

TTL · 1 hour

Admin tokens expire after 3,600 seconds

JTI · UUID v4

Unique session identifier for tracking and revocation

See token signing in features/auth/admin-auth-token.ts:319.

Session tracking

All admin sessions are tracked in either:

• Postgres: app_admin_sessions table (preferred)
• KV Store: Fallback for environments without Postgres

Tracked metadata:

interface AdminTokenSessionRecord {
  jti: string;
  tv: number;
  iat: number;
  exp: number;
  ip: string;  // Client IP address
  ua: string;  // User agent
  status: 'active' | 'expired' | 'revoked' | 'invalidated';
}

See session registration in features/auth/admin-auth-token.ts:220.

Token versioning

Admin tokens include a version number (tv) that enables mass revocation:

Incrementing the global token version instantly invalidates all existing admin sessions. This is useful for security incidents or credential rotation.

See version management in features/auth/admin-auth-token.ts:112.

Session revocation

Admin sessions can be revoked in two ways:

Individual revocation:

revokeAdminSessionByJti(jti: string)

Marks a specific session as revoked. The revocation is stored in:

• Postgres: revoked_until column in app_admin_sessions
• KV Store: admin-auth:revoked:{jti} key

See individual revocation in features/auth/admin-auth-token.ts:659.

Mass revocation:

revokeAllAdminSessions()

Increments the token version, instantly invalidating all sessions.

See mass revocation in features/auth/admin-auth-token.ts:692.

Session cleanup

Expired admin sessions are automatically cleaned up by a cron job:

Grace period · 7 days

Sessions are kept for 7 days after expiry for audit purposes

Cleanup window · exp + 604,800 seconds

Only sessions expired beyond the grace window are deleted

See cleanup in features/auth/admin-auth-token.ts:626.

Session status endpoint

Check authentication status via GET /api/auth/session:

{
  "success": true,
  "isAuthenticated": true,
  "isAdminAuthenticated": false,
  "email": "[e-mail]"
}

This endpoint returns both user and admin authentication status in a single request.

See session status in app/api/auth/session/route.ts:10.

Security best practices

Environment variables:

• AUTH_SECRET: Must be at least 32 characters, randomly generated
• ADMIN_KEY: Strong, randomly generated key
• Never commit these values to source control

Token security:

• All tokens use HMAC-SHA256 signing
• Tokens include audience and issuer claims to prevent misuse
• Tokens are validated on every request
• Expired tokens are automatically rejected

Cookie security:

• HTTP-only flag prevents JavaScript access
• SameSite=lax prevents CSRF attacks
• Secure flag enforces HTTPS in production
• Path restriction limits cookie scope

Rate limiting:

• Authentication endpoints are rate limited (see rate limiting)
• Failed attempts are tracked by IP and email combination
• Prevents brute force and enumeration attacks