oauth-state.ts

From the guide Supabase authentication in TypeScript: two safe ways, with code. Placeholder values only: put your own keys in environment variables, never in the code.

oauth-state.tsTypeScriptRawExternal
// oauth-state.ts: the `state` and the PKCE verifier of an OAuth sign-in. Server only.
// Three checks, so a forged callback fails whichever way it is made:
//  1. the state is signed (HMAC-SHA256 with SESSION_SECRET) and expires after 10 minutes;
//  2. its random nonce must equal the nonce in a short-lived HttpOnly cookie set when the sign-in started,
//     which ties the callback to the browser that began it (login CSRF);
//  3. PKCE (S256): the provider gets a hash of a random secret (the challenge) at the start, and the secret itself (the
//     verifier, kept in a cookie like the nonce) when the code is traded, so a stolen code is useless without it.
//     RFC 9700 section 2.1.1: clients must prevent authorization code injection, and PKCE is recommended for
//     confidential clients too (https://www.rfc-editor.org/rfc/rfc9700.html, read 2026-11-22).
// The HMAC input starts with a fixed label, so a state can never pass as a session cookie, nor the other way round.
import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';

export const STATE_TTL_MS = 10 * 60 * 1000;
export const STATE_COOKIE = 'oauth_state';
export const VERIFIER_COOKIE = 'oauth_verifier';
const LABEL = 'oauth-state-v1\n';

const secretOf = (secret?: string): string => {
  const s = secret ?? process.env.SESSION_SECRET;
  if (!s) throw new Error('SESSION_SECRET is not set');
  if (Buffer.byteLength(s) < 32) throw new Error('SESSION_SECRET must be at least 32 bytes');
  return s;
};
const mac = (part: string, secret: string): Buffer => createHmac('sha256', secret).update(LABEL + part).digest();

export const newNonce = (): string => randomBytes(18).toString('base64url');

/** The PKCE verifier: 32 random bytes, 43 characters (RFC 7636 asks for 43 to 128). */
export const newVerifier = (): string => randomBytes(32).toString('base64url');
/** The PKCE challenge sent to the provider: the S256 hash of the verifier (RFC 7636 section 4.2). */
export const challengeOf = (verifier: string): string => createHash('sha256').update(verifier).digest('base64url');

export function signState(nonce: string, expiresAt: number, secret?: string): string {
  const part = Buffer.from(JSON.stringify({ n: nonce, e: expiresAt })).toString('base64url');
  return `${part}.${mac(part, secretOf(secret)).toString('base64url')}`;
}

/** The state's nonce, or null for a bad format, a bad signature or an expired state. Never throws. */
export function verifyState(value: unknown, nowMs: number, secret?: string): string | null {
  if (typeof value !== 'string') return null;
  const dot = value.indexOf('.');
  if (dot <= 0 || dot !== value.lastIndexOf('.')) return null;
  const part = value.slice(0, dot);
  const sig = value.slice(dot + 1);
  if (!/^[A-Za-z0-9_-]+$/.test(part) || !/^[A-Za-z0-9_-]+$/.test(sig)) return null;
  const given = Buffer.from(sig, 'base64url');
  const expected = mac(part, secretOf(secret));
  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return null;
  let parsed: unknown;
  try {
    parsed = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
  } catch {
    return null;
  }
  if (typeof parsed !== 'object' || parsed === null) return null;
  const { n, e } = parsed as Record<string, unknown>;
  if (typeof n !== 'string' || n === '') return null;
  if (typeof e !== 'number' || !Number.isFinite(e) || e <= nowMs) return null;
  return n;
}

// These cookies are only sent to the sign-in routes: nothing else needs them.
export const stateCookie = (nonce: string): string =>
  `${STATE_COOKIE}=${nonce}; HttpOnly; Secure; SameSite=Lax; Path=/api/auth; Max-Age=${STATE_TTL_MS / 1000}`;
export const clearStateCookie = (): string => `${STATE_COOKIE}=; HttpOnly; Secure; SameSite=Lax; Path=/api/auth; Max-Age=0`;
export const verifierCookie = (verifier: string): string =>
  `${VERIFIER_COOKIE}=${verifier}; HttpOnly; Secure; SameSite=Lax; Path=/api/auth; Max-Age=${STATE_TTL_MS / 1000}`;
export const clearVerifierCookie = (): string => `${VERIFIER_COOKIE}=; HttpOnly; Secure; SameSite=Lax; Path=/api/auth; Max-Age=0`;

Back to the guide