This doc covers the security architecture — how we protect tokens, prevent CSRF, manage sessions, and verify webhooks.

Cookies

gh_session

The main session cookie. httpOnly, secure, sameSite=lax, path=/, maxAge=session expiry (~24h).

Set by GET /api/auth, cleared by POST /api/auth/logout.

Contains only the session ID (64-char hex). No JWT, no user data, no tokens.

sameSite=lax means it’s sent on top-level navigations (like GitHub redirects) but not on cross-site subrequests.

gh_auth_csrf

CSRF cookie for the OAuth flow. httpOnly, secure, sameSite=none, path=/, maxAge=600 (10 min).

32-byte base64url random value.

Set by GET /api/auth/start, cleared by GET /api/auth.

gh_install_csrf

CSRF cookie for the installation flow. httpOnly, secure, sameSite=none, path=/, maxAge=600 (10 min).

32-byte base64url random value.

Set by GET /api/install/start, cleared by GET /api/install/callback.

Both CSRF cookies use sameSite=none because OAuth redirect flows cross origins.

State tokens

Signed HS256 JWTs via jose (lib/auth/state.ts). Keyed by authEnv.sessionSecret (falls back to GITHUB_CLIENT_SECRET:GITHUB_APP_ID hash).

OAuth state

Created by: GET /api/auth/start. Verified by: GET /api/auth. 10-min expiry.

Install state

Created by: GET /api/install/start. Verified by: GET /api/install/callback. 10-min expiry.

Security properties

Token encryption

GitHub OAuth tokens are encrypted at rest using AES-256-GCM (lib/auth/server/crypto.ts).

Encryption process

plaintext (GitHub token)
    ↓
randomBytes(16) → IV
    ↓
createCipheriv('aes-256-gcm', key, iv)
    ↓
ciphertext + authTag (16 bytes)
    ↓
Store: { encrypted: ciphertext, iv, tag: authTag }

Key derivation

1. TOKEN_ENCRYPTION_KEY env var (preferred, 64+ hex chars)
2. Fallback: GITHUB_CLIENT_SECRET:GITHUB_APP_ID:GITHUB_CLIENT_ID concatenation

The key is hashed with SHA-256 to produce the 32-byte AES key.

Storage

Same pattern for refresh tokens (github_refresh_token_* columns).

Decryption

ciphertext + iv + tag
    ↓
createDecipheriv('aes-256-gcm', key, iv)
decipher.setAuthTag(tag)
    ↓
plaintext (GitHub token)

Decryption happens only server-side when a session is read. The decrypted token never leaves the server.

Security properties

Session management

ID generation

lib/auth/server/session.ts:

function randomSessionId(): string {
  return crypto.randomBytes(32).toString('hex');
}

64-char hex (256 bits entropy).

Storage

Supabase auth_sessions table with normalized foreign keys:

No embedded user data. Profile, organizations, and memberships are resolved via joins when the session is read.

Installations are stored in the session_installations join table (not an array column).

Expiry

24-hour TTL by default (session.ts), or the OAuth token’s expiresAt if shorter. Expired sessions are auto-deleted on read.

Token exposure

The OAuth token is stored in the database but never included in API responses. The SessionView type (types/auth/session.ts) explicitly omits githubToken.

Request authentication

lib/auth/request-session.ts:

1. Authorization: Bearer <sessionId> → getSession(x)
2. Fallback: gh_session cookie → getSession(cookie.value)
3. Both fail → null

getSession() (lib/auth/server/session.ts):

1. Query Supabase auth_sessions by ID
2. Check expiry (delete if expired)
3. Join users via user_id
4. Join organization_memberships + organizations for org list
5. Decrypt GitHub token
6. Return AuthSession or null

Webhook security

lib/auth/server/webhook.ts verifies HMAC-SHA256 signatures on GitHub webhook payloads.

Verification

expected = "sha256=" + HMAC-SHA256(GITHUB_WEBHOOK_SECRET, requestBody)
actual = X-Hub-Signature-256 header

timingSafeEqual(expected, actual) → boolean

Fallback

If GITHUB_WEBHOOK_SECRET isn’t set, verification is skipped with a console warning. Not recommended for production.

Error responses

All protected routes return: { "error": "..." }. Produced by lib/auth/response.ts:

export function jsonError(message: string, status = 400) {
  return NextResponse.json({ error: message }, { status });
}

Messages are user-facing. Sensitive details are logged server-side only via console.error.

Attack vector mitigations

Related

• Auth Routes — OAuth sign-in, session, logout endpoints
• Install Routes — GitHub App installation flow
• Webhook — GitHub App webhook handler
• Database Schema — auth_sessions, users, organizations tables