@ultimat3/auth 1.0.0

package/src/memory-adapter.ts

@@ -0,0 +1,170 @@
+// Single responsibility: an in-memory `AuthAdapter`. It is the driver `x new` uses before a
+// database exists and the one every test in this package runs against — the same interface
+// Postgres and Better Auth implement, so a flow that works here works there or the seam is wrong.
+
+import type {
+  AuthAccount,
+  AuthAdapter,
+  AuthApiKeyRecord,
+  AuthSession,
+  AuthUser,
+  AuthVerification,
+  CreateUserInput,
+  SessionPatch,
+  UserPatch,
+} from './adapter';
+
+const verificationKey = (purpose: string, identifier: string): string => `${purpose}:${identifier}`;
+
+export class MemoryAdapter implements AuthAdapter {
+  readonly name = 'memory';
+  readonly #users = new Map<string, AuthUser>();
+  readonly #sessions = new Map<string, AuthSession>();
+  readonly #accounts = new Map<string, AuthAccount>();
+  readonly #verifications = new Map<string, AuthVerification>();
+  readonly #apiKeys = new Map<string, AuthApiKeyRecord>();
+
+  async findUserByEmail(email: string): Promise<AuthUser | null> {
+    const wanted = email.trim().toLowerCase();
+    for (const user of this.#users.values()) {
+      if (user.email === wanted) return user;
+    }
+    return null;
+  }
+
+  async findUserById(id: string): Promise<AuthUser | null> {
+    return this.#users.get(id) ?? null;
+  }
+
+  async createUser(input: CreateUserInput): Promise<AuthUser> {
+    const user: AuthUser = {
+      id: input.id,
+      email: input.email.trim().toLowerCase(),
+      emailVerifiedAt: null,
+      passwordHash: input.passwordHash,
+      orgId: input.orgId,
+      roles: [...input.roles],
+      permissions: [],
+      mfaSecret: null,
+      recoveryCodeHashes: [],
+      disabledAt: null,
+      createdAt: input.createdAt,
+    };
+    this.#users.set(user.id, user);
+    return user;
+  }
+
+  async updateUser(id: string, patch: UserPatch): Promise<AuthUser | null> {
+    const user = this.#users.get(id);
+    if (user === undefined) return null;
+    const next: AuthUser = {
+      ...user,
+      passwordHash: patch.passwordHash === undefined ? user.passwordHash : patch.passwordHash,
+      emailVerifiedAt:
+        patch.emailVerifiedAt === undefined ? user.emailVerifiedAt : patch.emailVerifiedAt,
+      mfaSecret: patch.mfaSecret === undefined ? user.mfaSecret : patch.mfaSecret,
+      recoveryCodeHashes: patch.recoveryCodeHashes ?? user.recoveryCodeHashes,
+      disabledAt: patch.disabledAt === undefined ? user.disabledAt : patch.disabledAt,
+      roles: patch.roles ?? user.roles,
+    };
+    this.#users.set(id, next);
+    return next;
+  }
+
+  async getSession(id: string): Promise<AuthSession | null> {
+    return this.#sessions.get(id) ?? null;
+  }
+
+  async createSession(session: AuthSession): Promise<AuthSession> {
+    this.#sessions.set(session.id, session);
+    return session;
+  }
+
+  async updateSession(id: string, patch: SessionPatch): Promise<AuthSession | null> {
+    const session = this.#sessions.get(id);
+    if (session === undefined) return null;
+    const next: AuthSession = {
+      ...session,
+      lastSeenAt: patch.lastSeenAt ?? session.lastSeenAt,
+      ip: patch.ip === undefined ? session.ip : patch.ip,
+      userAgent: patch.userAgent === undefined ? session.userAgent : patch.userAgent,
+      mfaSatisfied: patch.mfaSatisfied ?? session.mfaSatisfied,
+    };
+    this.#sessions.set(id, next);
+    return next;
+  }
+
+  async deleteSession(id: string): Promise<boolean> {
+    return this.#sessions.delete(id);
+  }
+
+  async deleteOtherSessions(userId: string, keepSessionId: string): Promise<number> {
+    let killed = 0;
+    for (const [id, session] of this.#sessions) {
+      if (session.userId !== userId || id === keepSessionId) continue;
+      this.#sessions.delete(id);
+      killed += 1;
+    }
+    return killed;
+  }
+
+  async listSessions(userId: string): Promise<readonly AuthSession[]> {
+    return [...this.#sessions.values()]
+      .filter((session) => session.userId === userId)
+      .sort((a, b) => b.lastSeenAt.getTime() - a.lastSeenAt.getTime());
+  }
+
+  async linkAccount(account: AuthAccount): Promise<AuthAccount> {
+    this.#accounts.set(`${account.provider}:${account.providerAccountId}`, account);
+    return account;
+  }
+
+  async findAccount(provider: string, providerAccountId: string): Promise<AuthAccount | null> {
+    return this.#accounts.get(`${provider}:${providerAccountId}`) ?? null;
+  }
+
+  async listAccounts(userId: string): Promise<readonly AuthAccount[]> {
+    return [...this.#accounts.values()].filter((account) => account.userId === userId);
+  }
+
+  async putVerification(record: AuthVerification): Promise<void> {
+    this.#verifications.set(verificationKey(record.purpose, record.identifier), record);
+  }
+
+  async takeVerification(purpose: string, identifier: string): Promise<AuthVerification | null> {
+    const key = verificationKey(purpose, identifier);
+    const record = this.#verifications.get(key);
+    if (record === undefined || record.consumedAt !== null) return null;
+    const consumed: AuthVerification = { ...record, consumedAt: new Date(record.createdAt) };
+    this.#verifications.set(key, consumed);
+    return consumed;
+  }
+
+  async putApiKey(record: AuthApiKeyRecord): Promise<AuthApiKeyRecord> {
+    this.#apiKeys.set(record.id, record);
+    return record;
+  }
+
+  async findApiKeyById(id: string): Promise<AuthApiKeyRecord | null> {
+    return this.#apiKeys.get(id) ?? null;
+  }
+
+  async listApiKeys(ownerId: string): Promise<readonly AuthApiKeyRecord[]> {
+    return [...this.#apiKeys.values()].filter(
+      (key) => key.userId === ownerId || key.orgId === ownerId,
+    );
+  }
+
+  async touchApiKey(id: string, at: Date): Promise<void> {
+    const key = this.#apiKeys.get(id);
+    if (key === undefined) return;
+    this.#apiKeys.set(id, { ...key, lastUsedAt: at });
+  }
+
+  async revokeApiKey(id: string, at: Date): Promise<boolean> {
+    const key = this.#apiKeys.get(id);
+    if (key === undefined || key.revokedAt !== null) return false;
+    this.#apiKeys.set(id, { ...key, revokedAt: at });
+    return true;
+  }
+}

package/src/mfa.ts

@@ -0,0 +1,209 @@
+// Single responsibility: TOTP (RFC 6238) and recovery codes. The drift window is explicit and
+// small, and every accepted step is remembered: without replay rejection a code shouted over a
+// phishing page stays valid for the rest of its 30 seconds. Recovery codes are hashed at rest
+// and single-use, so a database dump is not a permanent MFA bypass.
+
+import { randomBytes, sha256Hex, timingSafeEqual } from './tokens';
+
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+
+export const TOTP_STEP_SECONDS = 30;
+export const TOTP_DIGITS = 6;
+/** ±1 step. Two steps is a minute of validity; that is a window, not a clock tolerance. */
+export const TOTP_DRIFT_STEPS = 1;
+
+export function base32Encode(bytes: Uint8Array): string {
+  let bits = 0;
+  let value = 0;
+  let out = '';
+  for (const byte of bytes) {
+    value = (value << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      out += BASE32_ALPHABET[(value >>> (bits - 5)) & 31] as string;
+      bits -= 5;
+    }
+  }
+  if (bits > 0) out += BASE32_ALPHABET[(value << (5 - bits)) & 31] as string;
+  return out;
+}
+
+/**
+ * Tolerant by design: padding, spaces and the dashes authenticator apps display are skipped,
+ * and any other character fails the decode closed (empty output -> no code ever matches).
+ */
+export function base32Decode(value: string): Uint8Array {
+  const bytes: number[] = [];
+  let bits = 0;
+  let acc = 0;
+  for (const char of value.toUpperCase()) {
+    if (char === '=' || char === ' ' || char === '-') continue;
+    const index = BASE32_ALPHABET.indexOf(char);
+    if (index < 0) return new Uint8Array(0);
+    acc = (acc << 5) | index;
+    bits += 5;
+    if (bits >= 8) {
+      bytes.push((acc >>> (bits - 8)) & 0xff);
+      bits -= 8;
+    }
+  }
+  return Uint8Array.from(bytes);
+}
+
+/** 160 bits — the HMAC-SHA1 block size every authenticator app agrees on. */
+export function generateTotpSecret(): string {
+  return base32Encode(randomBytes(20));
+}
+
+export interface TotpEnrolment {
+  readonly secret: string;
+  readonly uri: string;
+  readonly digits: number;
+  readonly periodSeconds: number;
+}
+
+export interface EnrolTotpInput {
+  readonly issuer: string;
+  readonly account: string;
+  readonly secret?: string | undefined;
+}
+
+export function enrolTotp(input: EnrolTotpInput): TotpEnrolment {
+  const secret = input.secret ?? generateTotpSecret();
+  const label = `${encodeURIComponent(input.issuer)}:${encodeURIComponent(input.account)}`;
+  const query = new URLSearchParams({
+    secret,
+    issuer: input.issuer,
+    algorithm: 'SHA1',
+    digits: String(TOTP_DIGITS),
+    period: String(TOTP_STEP_SECONDS),
+  });
+  return {
+    secret,
+    uri: `otpauth://totp/${label}?${query.toString()}`,
+    digits: TOTP_DIGITS,
+    periodSeconds: TOTP_STEP_SECONDS,
+  };
+}
+
+export function totpStep(at: Date, stepSeconds: number = TOTP_STEP_SECONDS): number {
+  return Math.floor(at.getTime() / 1000 / stepSeconds);
+}
+
+function counterBytes(step: number): Uint8Array {
+  const bytes = new Uint8Array(8);
+  let remaining = step;
+  for (let index = 7; index >= 0; index -= 1) {
+    bytes[index] = remaining % 256;
+    remaining = Math.floor(remaining / 256);
+  }
+  return bytes;
+}
+
+/** HMAC-SHA1 + RFC 4226 dynamic truncation. SHA1 here is a spec requirement, not a choice. */
+export function totpCode(secret: string, step: number, digits: number = TOTP_DIGITS): string {
+  const key = base32Decode(secret);
+  const mac = Uint8Array.from(
+    new Bun.CryptoHasher('sha1', key).update(counterBytes(step)).digest(),
+  );
+  const offset = (mac[mac.length - 1] ?? 0) & 0x0f;
+  const binary =
+    (((mac[offset] ?? 0) & 0x7f) << 24) |
+    (((mac[offset + 1] ?? 0) & 0xff) << 16) |
+    (((mac[offset + 2] ?? 0) & 0xff) << 8) |
+    ((mac[offset + 3] ?? 0) & 0xff);
+  return String(binary % 10 ** digits).padStart(digits, '0');
+}
+
+export interface TotpVerification {
+  readonly ok: boolean;
+  /** The step the code belonged to — feed it to `TotpReplayGuard.remember()`. */
+  readonly step: number | null;
+}
+
+export interface VerifyTotpInput {
+  readonly secret: string;
+  readonly code: string;
+  readonly at: Date;
+  readonly drift?: number | undefined;
+  /** Steps already spent by this subject. A match inside the set is a replay, not a login. */
+  readonly usedSteps?: ReadonlySet<number> | undefined;
+}
+
+export function verifyTotp(input: VerifyTotpInput): TotpVerification {
+  const drift = input.drift ?? TOTP_DRIFT_STEPS;
+  const current = totpStep(input.at);
+  const candidate = input.code.replaceAll(' ', '');
+  for (let offset = -drift; offset <= drift; offset += 1) {
+    const step = current + offset;
+    if (!timingSafeEqual(totpCode(input.secret, step), candidate)) continue;
+    if (input.usedSteps?.has(step) === true) return { ok: false, step };
+    return { ok: true, step };
+  }
+  return { ok: false, step: null };
+}
+
+export interface TotpReplayGuard {
+  isUsed(subject: string, step: number): boolean;
+  remember(subject: string, step: number, at: Date): void;
+}
+
+/**
+ * In-memory by default because a single web process is the common case; a multi-process
+ * deployment passes a Redis-backed guard with the same two methods. Steps older than the
+ * drift window are dropped — nothing outside it can be replayed anyway.
+ */
+export function createTotpReplayGuard(drift: number = TOTP_DRIFT_STEPS): TotpReplayGuard {
+  const used = new Map<string, Set<number>>();
+  return {
+    isUsed: (subject, step) => used.get(subject)?.has(step) === true,
+    remember: (subject, step, at) => {
+      const steps = used.get(subject) ?? new Set<number>();
+      const floor = totpStep(at) - drift;
+      for (const known of steps) {
+        if (known < floor) steps.delete(known);
+      }
+      steps.add(step);
+      used.set(subject, steps);
+    },
+  };
+}
+
+export interface RecoveryCodeSet {
+  /** Shown once, at enrolment. Never persisted, never re-derivable. */
+  readonly codes: readonly string[];
+  readonly hashes: readonly string[];
+}
+
+const normaliseRecoveryCode = (code: string): string =>
+  code.replaceAll('-', '').replaceAll(' ', '').toUpperCase();
+
+export function generateRecoveryCodes(count = 10): RecoveryCodeSet {
+  const codes: string[] = [];
+  for (let index = 0; index < count; index += 1) {
+    const raw = base32Encode(randomBytes(10)).slice(0, 16);
+    codes.push(`${raw.slice(0, 4)}-${raw.slice(4, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}`);
+  }
+  return { codes, hashes: codes.map((code) => sha256Hex(normaliseRecoveryCode(code))) };
+}
+
+/**
+ * Returns the remaining hashes with the redeemed one removed, or `null` if nothing matched.
+ * The caller persists the result — that write is what makes a code single-use.
+ */
+export function redeemRecoveryCode(
+  code: string,
+  hashes: readonly string[],
+): readonly string[] | null {
+  const candidate = sha256Hex(normaliseRecoveryCode(code));
+  let matched = false;
+  const remaining: string[] = [];
+  for (const hash of hashes) {
+    if (!matched && timingSafeEqual(hash, candidate)) {
+      matched = true;
+      continue;
+    }
+    remaining.push(hash);
+  }
+  return matched ? remaining : null;
+}

package/src/oauth-cookie.ts

@@ -0,0 +1,209 @@
+// Single responsibility: where the handshake lives between the redirect and the callback. The
+// two legs of an authorization-code login are separate HTTP requests, so `beginOAuth`'s state,
+// nonce and PKCE verifier have to survive the round trip — and a framework that leaves that to
+// the app gets one hand-rolled store per app, which is exactly where PKCE quietly stops proving
+// anything. Sealed here and opened here, so the cookie below and a server-side store share one
+// format at one trust level.
+
+import type { Clock } from '@ultimat3/core';
+import { EnvMissingError, systemClock } from '@ultimat3/core';
+import { oauthStateInvalid } from './errors';
+import { OAUTH_PROVIDERS, type OAuthHandshake, type OAuthProviderId } from './oauth';
+import { type RequestLike, readCookie } from './session';
+import { base64Url, timingSafeEqual } from './tokens';
+
+/** `__Host-` for the same reason the session cookie carries it: no subdomain can plant one. */
+export const OAUTH_HANDSHAKE_COOKIE_PREFIX = '__Host-x_oauth';
+
+/**
+ * One cookie per provider, because a browser is one cookie jar and a user is allowed two tabs.
+ * Under a single shared name, starting a `google` login while a `github` one is mid-flight
+ * overwrites the github handshake — and the github callback then opens google's, fails
+ * `X_OAUTH_STATE_INVALID` and tells the user to restart the flow that just collided again.
+ * Scoping the name makes the two handshakes independent instead of the last writer's.
+ */
+export function handshakeCookieName(provider: OAuthProviderId): string {
+  return `${OAUTH_HANDSHAKE_COOKIE_PREFIX}_${provider}`;
+}
+
+/** Long enough to read a consent screen, short enough that a lifted cookie is already stale. */
+export const DEFAULT_HANDSHAKE_TTL_MS = 10 * 60 * 1000;
+
+/** `wiki/Configuration.md` requires it at >=32 chars for the `web` role; this is that gate. */
+const MIN_SECRET_LENGTH = 32;
+
+/**
+ * The app secret, read at call time rather than module scope so importing this file still reads
+ * no env — the same rule `oauthCredentials()` follows for the client id and secret.
+ */
+export function handshakeSecret(
+  env: Readonly<Record<string, string | undefined>> = Bun.env,
+): string {
+  const secret = env['SESSION_SECRET']?.trim() ?? '';
+  if (secret.length < MIN_SECRET_LENGTH) {
+    throw new EnvMissingError({
+      cause:
+        secret === ''
+          ? 'SESSION_SECRET is not set, so an oauth handshake cannot be signed'
+          : `SESSION_SECRET is ${secret.length} characters and at least ${MIN_SECRET_LENGTH} are required`,
+      fix: 'export SESSION_SECRET="$(openssl rand -hex 32)"',
+      meta: { key: 'SESSION_SECRET', minLength: MIN_SECRET_LENGTH },
+    });
+  }
+  return secret;
+}
+
+export interface HandshakeSealOptions {
+  /** Defaults to `SESSION_SECRET`. */
+  readonly secret?: string | undefined;
+  /** No `Date.now()` in this package: the handshake's age is measured against this. */
+  readonly clock?: Clock | undefined;
+  readonly ttlMs?: number | undefined;
+}
+
+export interface HandshakeCookieOptions extends HandshakeSealOptions {
+  /**
+   * Defaults to `handshakeCookieName(provider)`. Overriding it opts out of the per-provider
+   * scoping, so both legs have to pass the same one — a name set on the redirect and defaulted on
+   * the callback reads a cookie that is not there.
+   */
+  readonly name?: string | undefined;
+}
+
+/**
+ * Signed, not encrypted, for the reason the cursor codec is: every field here is already the
+ * browser's own — `state` travelled in the URL it was just sent to, and the verifier and nonce
+ * are that browser's halves of this handshake. What the signature buys is that the browser
+ * cannot *invent* a handshake, which is what would let an attacker's code land in a victim's
+ * session. What secrecy is needed against everyone else is the cookie's `HttpOnly; Secure`.
+ */
+export function sealHandshake(handshake: OAuthHandshake, options?: HandshakeSealOptions): string {
+  const clock = options?.clock ?? systemClock;
+  const body = base64Url(
+    new TextEncoder().encode(
+      JSON.stringify([
+        handshake.provider,
+        handshake.state,
+        handshake.nonce,
+        handshake.verifier,
+        handshake.redirectUri,
+        handshake.authorizeUrl,
+        clock.now().getTime(),
+      ]),
+    ),
+  );
+  return `${body}.${sign(body, options?.secret ?? handshakeSecret())}`;
+}
+
+/**
+ * The only way back. `provider` is required rather than read from the payload because a
+ * handshake opened without one is a github handshake finishing a google callback — and an
+ * optional check is one a call site can forget.
+ *
+ * Every rejection is `X_OAUTH_STATE_INVALID`, like `assertOAuthCallback`'s: the handshake is one
+ * object, and naming which field failed tells an attacker which field to keep guessing at.
+ */
+export function openHandshake(
+  sealed: string,
+  provider: OAuthProviderId,
+  options?: HandshakeSealOptions,
+): OAuthHandshake {
+  const dot = sealed.lastIndexOf('.');
+  if (dot <= 0) throw oauthStateInvalid(provider, 'the stored handshake is not signed');
+
+  const body = sealed.slice(0, dot);
+  const expected = sign(body, options?.secret ?? handshakeSecret());
+  if (!timingSafeEqual(expected, sealed.slice(dot + 1))) {
+    throw oauthStateInvalid(
+      provider,
+      'the stored handshake was tampered with, or the secret rotated',
+    );
+  }
+
+  const parsed = parseBody(body, provider);
+  if (!Array.isArray(parsed) || parsed.length !== 7) {
+    throw oauthStateInvalid(provider, 'the stored handshake is not a handshake');
+  }
+  const [sealedProvider, state, nonce, verifier, redirectUri, authorizeUrl, issuedAt] =
+    parsed as readonly unknown[];
+  if (
+    typeof sealedProvider !== 'string' ||
+    typeof state !== 'string' ||
+    typeof nonce !== 'string' ||
+    typeof verifier !== 'string' ||
+    typeof redirectUri !== 'string' ||
+    typeof authorizeUrl !== 'string' ||
+    typeof issuedAt !== 'number' ||
+    !Number.isFinite(issuedAt)
+  ) {
+    throw oauthStateInvalid(provider, 'the stored handshake is not a handshake');
+  }
+  if (!Object.hasOwn(OAUTH_PROVIDERS, sealedProvider) || sealedProvider !== provider) {
+    throw oauthStateInvalid(provider, 'the stored handshake belongs to a different provider');
+  }
+
+  // The cookie's own `Max-Age` is the client's copy of this deadline, and a client is free to
+  // ignore it — so the age that decides is measured here, against the server's clock.
+  const clock = options?.clock ?? systemClock;
+  if (clock.now().getTime() - issuedAt > (options?.ttlMs ?? DEFAULT_HANDSHAKE_TTL_MS)) {
+    throw oauthStateInvalid(provider, 'the stored handshake expired before the callback arrived');
+  }
+
+  return { provider, state, nonce, verifier, redirectUri, authorizeUrl };
+}
+
+/**
+ * Set on the redirect. `SameSite=Lax` is the one attribute that differs in reasoning from the
+ * session cookie's: the callback is a top-level cross-site GET from the provider, which `Lax`
+ * still attaches the cookie to and `Strict` would strip — leaving every login to fail its state
+ * check. A provider answering with `response_mode=form_post` POSTs instead, and this cookie
+ * would not reach it; no provider in `OAUTH_PROVIDERS` is configured that way.
+ */
+export function handshakeCookie(
+  handshake: OAuthHandshake,
+  options?: HandshakeCookieOptions,
+): string {
+  const maxAge = Math.floor((options?.ttlMs ?? DEFAULT_HANDSHAKE_TTL_MS) / 1000);
+  // The handshake already names its provider, so the two legs cannot disagree about the name.
+  const name = options?.name ?? handshakeCookieName(handshake.provider);
+  return `${name}=${sealHandshake(handshake, options)}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
+}
+
+/**
+ * Send this with the callback's response, always — an authorization code is single-use, so the
+ * handshake that authorised it must not outlive it. A mismatched attribute set leaves a live twin.
+ *
+ * `provider` is required for the reason `openHandshake`'s is: clearing the unscoped name would
+ * clear nothing, and clearing every provider's would cancel a login running in another tab.
+ */
+export function clearHandshakeCookie(provider: OAuthProviderId, name?: string): string {
+  return `${name ?? handshakeCookieName(provider)}=; Path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax`;
+}
+
+/** Reads the cookie set on the redirect and returns the handshake `completeOAuthLogin` takes. */
+export function readHandshakeCookie(
+  request: RequestLike,
+  provider: OAuthProviderId,
+  options?: HandshakeCookieOptions,
+): OAuthHandshake {
+  const sealed = readCookie(request, options?.name ?? handshakeCookieName(provider));
+  if (sealed === null) {
+    throw oauthStateInvalid(provider, 'no handshake cookie arrived with the callback');
+  }
+  return openHandshake(sealed, provider, options);
+}
+
+/** Keyed SHA-256. Untruncated, unlike a cursor's: a cookie has room and this authorises a login. */
+function sign(body: string, secret: string): string {
+  return new Bun.CryptoHasher('sha256', secret).update(body).digest('hex');
+}
+
+function parseBody(body: string, provider: OAuthProviderId): unknown {
+  const padded = body.replaceAll('-', '+').replaceAll('_', '/');
+  try {
+    const binary = atob(padded.padEnd(padded.length + ((4 - (padded.length % 4)) % 4), '='));
+    return JSON.parse(new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0))));
+  } catch {
+    throw oauthStateInvalid(provider, 'the stored handshake is not readable');
+  }
+}