@ultimat3/auth 1.0.0

package/src/session.ts

@@ -0,0 +1,253 @@
+// Single responsibility: session lifetime and the cookie that carries it. Two expiries are
+// evaluated independently — `absoluteExpiresAt` is a ceiling activity can never push out, and
+// `idleTtlMs` measures from `lastSeenAt` — because sliding-only expiry means a stolen session
+// lives forever. `RequestLike`/`CookieJar` are structural on purpose: `@ultimat3/http` binds
+// to them without this package importing it (same-tier packages must not depend on each other).
+
+import type { Clock } from '@ultimat3/core';
+import type { AuthSession, SessionStore } from './adapter';
+import { sessionExpired, sessionUnknown } from './errors';
+import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
+
+export interface SessionPolicy {
+  /** Hard ceiling from creation. Never extended. */
+  readonly absoluteTtlMs: number;
+  /** Measured from `lastSeenAt`, refreshed on every verified request. */
+  readonly idleTtlMs: number;
+  readonly cookieName: string;
+  /** Mint a new session id whenever roles/scopes change — closes session fixation. */
+  readonly rotateOnPrivilegeChange: boolean;
+}
+
+export const DEFAULT_SESSION_POLICY: SessionPolicy = Object.freeze({
+  absoluteTtlMs: 30 * 24 * 60 * 60 * 1000,
+  idleTtlMs: 7 * 24 * 60 * 60 * 1000,
+  // `__Host-` is a browser-enforced contract: the cookie must be Secure, Path=/ and carry no
+  // Domain. A subdomain (or an XSS on one) therefore cannot overwrite it — session fixation.
+  cookieName: '__Host-x_session',
+  rotateOnPrivilegeChange: true,
+});
+
+export interface SessionRuntime {
+  readonly store: SessionStore;
+  readonly policy: SessionPolicy;
+  readonly clock: Clock;
+}
+
+export interface RequestLike {
+  readonly headers: { get(name: string): string | null };
+}
+
+export interface CookieJar {
+  get(name: string): string | undefined;
+  set(name: string, value: string, attributes?: Readonly<Record<string, unknown>>): void;
+  delete(name: string): void;
+}
+
+export interface SessionDevice {
+  readonly sessionId: string;
+  readonly ip: string | null;
+  readonly userAgent: string | null;
+  readonly lastSeenAt: Date;
+  readonly createdAt: Date;
+  readonly current: boolean;
+}
+
+export interface SessionExpiry {
+  readonly absoluteExpired: boolean;
+  readonly idleExpired: boolean;
+}
+
+export interface IssuedSession {
+  readonly session: AuthSession;
+  /** Shown once, set as a cookie, never stored. Only its SHA-256 reaches the row. */
+  readonly token: string;
+}
+
+export interface CreateSessionInput {
+  readonly userId: string;
+  readonly ip?: string | null | undefined;
+  readonly userAgent?: string | null | undefined;
+  readonly mfaSatisfied?: boolean | undefined;
+}
+
+/** `<id>.<secret>`: the id is the row key, the secret is the half that is hashed. */
+export function parseSessionToken(token: string): { id: string; secret: string } | null {
+  const dot = token.indexOf('.');
+  if (dot <= 0 || dot === token.length - 1) return null;
+  return { id: token.slice(0, dot), secret: token.slice(dot + 1) };
+}
+
+export async function createSession(
+  runtime: SessionRuntime,
+  input: CreateSessionInput,
+): Promise<IssuedSession> {
+  const now = runtime.clock.now();
+  const id = randomToken(12);
+  const secret = randomToken(32);
+  const session = await runtime.store.createSession({
+    id,
+    userId: input.userId,
+    tokenHash: sha256Hex(secret),
+    createdAt: now,
+    absoluteExpiresAt: new Date(now.getTime() + runtime.policy.absoluteTtlMs),
+    lastSeenAt: now,
+    ip: input.ip ?? null,
+    userAgent: input.userAgent ?? null,
+    mfaSatisfied: input.mfaSatisfied ?? false,
+  });
+  return { session, token: `${id}.${secret}` };
+}
+
+/** The two clocks are computed separately; neither can mask the other. */
+export function sessionExpiry(
+  session: AuthSession,
+  policy: SessionPolicy,
+  now: Date,
+): SessionExpiry {
+  return {
+    absoluteExpired: now.getTime() >= session.absoluteExpiresAt.getTime(),
+    idleExpired: now.getTime() - session.lastSeenAt.getTime() >= policy.idleTtlMs,
+  };
+}
+
+/**
+ * Resolve a cookie value to a live session, sliding the idle window forward. Throws
+ * `X_SESSION_EXPIRED` for either clock and `X_UNAUTHENTICATED` for anything unknown —
+ * a forged id and a deleted session are indistinguishable to the caller.
+ */
+export async function verifySession(
+  runtime: SessionRuntime,
+  token: string,
+  observed?: { readonly ip?: string | null | undefined; readonly userAgent?: string | null },
+): Promise<AuthSession> {
+  const parsed = parseSessionToken(token);
+  if (parsed === null) throw sessionUnknown();
+  const session = await runtime.store.getSession(parsed.id);
+  if (session === null) throw sessionUnknown();
+  if (!timingSafeEqual(sha256Hex(parsed.secret), session.tokenHash)) throw sessionUnknown();
+
+  const now = runtime.clock.now();
+  const expiry = sessionExpiry(session, runtime.policy, now);
+  if (expiry.absoluteExpired || expiry.idleExpired) {
+    await runtime.store.deleteSession(session.id);
+    throw sessionExpired(expiry.absoluteExpired ? 'absolute' : 'idle', session.id);
+  }
+
+  const touched = await runtime.store.updateSession(session.id, {
+    lastSeenAt: now,
+    ip: observed?.ip ?? session.ip,
+    userAgent: observed?.userAgent ?? session.userAgent,
+  });
+  return touched ?? session;
+}
+
+/**
+ * Privilege change (role grant, MFA satisfied, password change) must not reuse the old id:
+ * whoever already holds the old cookie would inherit the new privileges.
+ */
+export async function rotateSession(
+  runtime: SessionRuntime,
+  session: AuthSession,
+  patch?: { readonly mfaSatisfied?: boolean | undefined },
+): Promise<IssuedSession> {
+  await runtime.store.deleteSession(session.id);
+  return await createSession(runtime, {
+    userId: session.userId,
+    ip: session.ip,
+    userAgent: session.userAgent,
+    mfaSatisfied: patch?.mfaSatisfied ?? session.mfaSatisfied,
+  });
+}
+
+export async function revokeSession(runtime: SessionRuntime, sessionId: string): Promise<boolean> {
+  return await runtime.store.deleteSession(sessionId);
+}
+
+export async function revokeOtherSessions(
+  runtime: SessionRuntime,
+  userId: string,
+  keepSessionId: string,
+): Promise<number> {
+  return await runtime.store.deleteOtherSessions(userId, keepSessionId);
+}
+
+/** What the "your devices" screen renders. Never includes the token hash. */
+export async function listDevices(
+  runtime: SessionRuntime,
+  userId: string,
+  currentSessionId?: string,
+): Promise<readonly SessionDevice[]> {
+  const sessions = await runtime.store.listSessions(userId);
+  return sessions.map((session) => ({
+    sessionId: session.id,
+    ip: session.ip,
+    userAgent: session.userAgent,
+    lastSeenAt: session.lastSeenAt,
+    createdAt: session.createdAt,
+    current: session.id === currentSessionId,
+  }));
+}
+
+export interface SessionCookieOptions {
+  readonly name?: string | undefined;
+  readonly maxAgeSeconds?: number | undefined;
+}
+
+/**
+ * Every attribute is load-bearing:
+ * - `HttpOnly`  — script cannot read it, so an XSS cannot exfiltrate the session.
+ * - `Secure`    — never sent over plaintext, so a network attacker cannot lift it.
+ * - `SameSite=Lax` — not attached to cross-site POSTs, which is CSRF's whole mechanism.
+ * - `Path=/`, no `Domain` — required by `__Host-`; a sibling subdomain cannot set or read it.
+ * - `Max-Age`   — the client drops it at the absolute expiry, matching the server's ceiling.
+ */
+export function sessionCookie(
+  token: string,
+  policy: SessionPolicy,
+  options?: SessionCookieOptions,
+): string {
+  const name = options?.name ?? policy.cookieName;
+  const maxAge = options?.maxAgeSeconds ?? Math.floor(policy.absoluteTtlMs / 1000);
+  return `${name}=${token}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
+}
+
+/** Same attributes, empty value, `Max-Age=0` — a mismatched attribute set leaves a live twin. */
+export function clearSessionCookie(policy: SessionPolicy, name?: string): string {
+  return `${name ?? policy.cookieName}=; Path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax`;
+}
+
+/**
+ * The one `Cookie:` parser in this package — the oauth handshake reads through it too, so it never
+ * throws: a missing or unreadable cookie is `null` or the raw value, never an exception.
+ */
+export function readCookie(request: RequestLike, name: string): string | null {
+  const header = request.headers.get('cookie');
+  if (header === null) return null;
+  for (const part of header.split(';')) {
+    const equals = part.indexOf('=');
+    if (equals < 0) continue;
+    if (part.slice(0, equals).trim() !== name) continue;
+    return decodeCookieValue(part.slice(equals + 1).trim());
+  }
+  return null;
+}
+
+/**
+ * A `Cookie:` header is attacker-controlled, and `decodeURIComponent('%')` throws a bare
+ * `URIError` — which escapes every coded path that reads through here: an OAuth callback would
+ * answer 500 instead of `X_OAUTH_STATE_INVALID`. The raw value is returned instead, so the
+ * caller's own rejection stays the readable failure. Nothing is loosened by it: a raw value is
+ * still checked against a signature or a stored hash, and neither matches a mangled one.
+ */
+function decodeCookieValue(raw: string): string {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+
+export function readSessionCookie(request: RequestLike, policy: SessionPolicy): string | null {
+  return readCookie(request, policy.cookieName);
+}

package/src/tables.ts

@@ -0,0 +1,86 @@
+// Single responsibility: the DDL `BuiltinAdapter` expects. Exported as plain strings so an app
+// can paste them into a migration and read exactly what auth stores — no column holds a
+// plaintext secret, and that is meant to be verifiable by reading, not by trusting.
+
+export const X_USERS_TABLE = `create table if not exists x_users (
+  id                    uuid primary key,
+  email                 text not null unique,
+  email_verified_at     timestamptz,
+  password_hash         text,
+  org_id                uuid,
+  roles                 text[] not null default '{}',
+  permissions           text[] not null default '{}',
+  mfa_secret            text,
+  recovery_code_hashes  text[] not null default '{}',
+  disabled_at           timestamptz,
+  created_at            timestamptz not null default now()
+)`;
+
+// `id` is the public half of the cookie; `token_hash` is sha256 of the secret half.
+export const X_SESSIONS_TABLE = `create table if not exists x_sessions (
+  id                    text primary key,
+  user_id               uuid not null references x_users (id) on delete cascade,
+  token_hash            text not null,
+  created_at            timestamptz not null default now(),
+  absolute_expires_at   timestamptz not null,
+  last_seen_at          timestamptz not null default now(),
+  ip                    text,
+  user_agent            text,
+  mfa_satisfied         boolean not null default false
+);
+create index if not exists x_sessions_user_id_idx on x_sessions (user_id);
+create index if not exists x_sessions_absolute_expires_at_idx on x_sessions (absolute_expires_at)`;
+
+export const X_ACCOUNTS_TABLE = `create table if not exists x_accounts (
+  id                    uuid primary key,
+  user_id               uuid not null references x_users (id) on delete cascade,
+  provider              text not null,
+  provider_account_id   text not null,
+  access_token          text,
+  refresh_token         text,
+  expires_at            timestamptz,
+  created_at            timestamptz not null default now(),
+  unique (provider, provider_account_id)
+)`;
+
+// One live token per (purpose, identifier): issuing a new one overwrites the old.
+export const X_VERIFICATIONS_TABLE = `create table if not exists x_verifications (
+  id                    text primary key,
+  purpose               text not null,
+  identifier            text not null,
+  token_hash            text not null,
+  expires_at            timestamptz not null,
+  consumed_at           timestamptz,
+  created_at            timestamptz not null default now(),
+  unique (purpose, identifier)
+)`;
+
+export const X_API_KEYS_TABLE = `create table if not exists x_api_keys (
+  id                    text primary key,
+  prefix                text not null unique,
+  key_hash              text not null,
+  user_id               uuid,
+  org_id                uuid,
+  scopes                text[] not null default '{}',
+  last_used_at          timestamptz,
+  expires_at            timestamptz,
+  revoked_at            timestamptz,
+  created_at            timestamptz not null default now()
+)`;
+
+/** Ordered by foreign-key dependency — run them top to bottom. */
+export const AUTH_TABLES: readonly string[] = Object.freeze([
+  X_USERS_TABLE,
+  X_SESSIONS_TABLE,
+  X_ACCOUNTS_TABLE,
+  X_VERIFICATIONS_TABLE,
+  X_API_KEYS_TABLE,
+]);
+
+export const AUTH_TABLE_NAMES: readonly string[] = Object.freeze([
+  'x_users',
+  'x_sessions',
+  'x_accounts',
+  'x_verifications',
+  'x_api_keys',
+]);

package/src/tokens.ts

@@ -0,0 +1,51 @@
+// Single responsibility: the secret primitives every other file in this package shares —
+// CSPRNG tokens, SHA-256 hashing and a comparison whose duration does not depend on where
+// two strings first differ. Centralised so no call site can quietly reach for `===` on a
+// secret, which leaks the shared prefix length one request at a time.
+
+const BASE64URL_UNSAFE = /[+/=]/g;
+const BASE64URL_REPLACEMENTS: Readonly<Record<string, string>> = { '+': '-', '/': '_', '=': '' };
+
+export function randomBytes(length: number): Uint8Array {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+export function base64Url(bytes: Uint8Array): string {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(BASE64URL_UNSAFE, (char) => BASE64URL_REPLACEMENTS[char] ?? '');
+}
+
+/** 32 bytes -> 43 base64url chars. Opaque by construction: it encodes nothing about the user. */
+export function randomToken(byteLength = 32): string {
+  return base64Url(randomBytes(byteLength));
+}
+
+export function sha256Hex(value: string): string {
+  return new Bun.CryptoHasher('sha256').update(value).digest('hex');
+}
+
+export function sha256Bytes(value: string): Uint8Array {
+  return Uint8Array.from(new Bun.CryptoHasher('sha256').update(value).digest());
+}
+
+/**
+ * Length is compared first and non-constant-time on purpose: every secret this package
+ * compares is a fixed-width hash or token, so the length carries no information, and the
+ * XOR accumulator below is what has to be branch-free.
+ */
+export function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let index = 0; index < a.length; index += 1) {
+    diff |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return diff === 0;
+}
+
+/** Hash-then-compare. The plaintext never has to be held next to the stored value. */
+export function matchesHash(plaintext: string, storedHash: string): boolean {
+  return timingSafeEqual(sha256Hex(plaintext), storedHash);
+}

package/src/verify.ts

@@ -0,0 +1,127 @@
+// Single responsibility: email verification and password reset — the two flows where a link in
+// an inbox is a credential. Tokens are single-use, expiring, stored hashed and compared in
+// constant time. Mail leaves through an injected `MailSender` port: the app wires
+// `@ultimat3/mail`'s `send` into it, because auth must not depend on a sideways tier-3 package.
+
+import type { Clock } from '@ultimat3/core';
+import type { AuthVerification, VerificationStore } from './adapter';
+import { AuthError } from './errors';
+import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
+
+/**
+ * `locale` is required, not optional: an inferred locale is how a user gets a security email
+ * in a language they cannot read. `@ultimat3/mail`'s `send` is the production binding.
+ */
+export interface MailSender {
+  send(
+    template: string,
+    to: string,
+    data: Readonly<Record<string, unknown>>,
+    locale: string,
+  ): Promise<void>;
+}
+
+export const VERIFICATION_PURPOSES = ['email-verify', 'password-reset'] as const;
+
+export type VerificationPurpose = (typeof VERIFICATION_PURPOSES)[number];
+
+/** Catalog keys, not copy. The template body lives in the app's i18n catalog. */
+export const VERIFICATION_TEMPLATES: Readonly<Record<VerificationPurpose, string>> = {
+  'email-verify': 'auth.email-verify',
+  'password-reset': 'auth.password-reset',
+};
+
+/** Short by default: a reset link is a password, and a password that lives a day is a liability. */
+export const DEFAULT_VERIFICATION_TTL_MS: Readonly<Record<VerificationPurpose, number>> = {
+  'email-verify': 24 * 60 * 60 * 1000,
+  'password-reset': 60 * 60 * 1000,
+};
+
+export interface VerificationRuntime {
+  readonly store: VerificationStore;
+  readonly clock: Clock;
+  readonly mail: MailSender;
+}
+
+export interface IssueVerificationInput {
+  readonly purpose: VerificationPurpose;
+  /** The email address. Also the store key — one live token per purpose per address. */
+  readonly identifier: string;
+  readonly locale: string;
+  readonly ttlMs?: number | undefined;
+  /** Builds the URL that carries the token. Defaults to the token alone. */
+  readonly link?: ((token: string) => string) | undefined;
+  readonly data?: Readonly<Record<string, unknown>> | undefined;
+}
+
+export interface IssuedVerification {
+  /** Returned so a test or a CLI can assert on it. Production only ever mails it. */
+  readonly token: string;
+  readonly expiresAt: Date;
+}
+
+export async function issueVerification(
+  runtime: VerificationRuntime,
+  input: IssueVerificationInput,
+): Promise<IssuedVerification> {
+  const now = runtime.clock.now();
+  const token = randomToken(32);
+  const ttl = input.ttlMs ?? DEFAULT_VERIFICATION_TTL_MS[input.purpose];
+  const expiresAt = new Date(now.getTime() + ttl);
+  await runtime.store.putVerification({
+    id: randomToken(12),
+    purpose: input.purpose,
+    identifier: input.identifier,
+    tokenHash: sha256Hex(token),
+    expiresAt,
+    consumedAt: null,
+    createdAt: now,
+  });
+  await runtime.mail.send(
+    VERIFICATION_TEMPLATES[input.purpose],
+    input.identifier,
+    {
+      ...(input.data ?? {}),
+      link: input.link?.(token) ?? token,
+      expiresAt: expiresAt.toISOString(),
+    },
+    input.locale,
+  );
+  return { token, expiresAt };
+}
+
+/**
+ * One error for "no such token", "already used", "expired" and "wrong token". Distinguishing
+ * them tells an attacker which address has a live reset in flight.
+ */
+const verificationInvalid = (purpose: string): AuthError =>
+  new AuthError({
+    code: 'X_UNAUTHENTICATED',
+    cause: `the ${purpose} token is unknown, already used, expired or does not match`,
+    fix: `request a new link — ${purpose} tokens are single-use`,
+  });
+
+export interface ConsumeVerificationInput {
+  readonly purpose: VerificationPurpose;
+  readonly identifier: string;
+  readonly token: string;
+}
+
+/**
+ * The store consumes the row atomically, so a second redemption finds nothing even if it
+ * races the first. The hash comparison happens after, on the row we already own.
+ */
+export async function consumeVerification(
+  runtime: VerificationRuntime,
+  input: ConsumeVerificationInput,
+): Promise<AuthVerification> {
+  const record = await runtime.store.takeVerification(input.purpose, input.identifier);
+  if (record === null) throw verificationInvalid(input.purpose);
+  if (runtime.clock.now().getTime() >= record.expiresAt.getTime()) {
+    throw verificationInvalid(input.purpose);
+  }
+  if (!timingSafeEqual(sha256Hex(input.token), record.tokenHash)) {
+    throw verificationInvalid(input.purpose);
+  }
+  return record;
+}