cursedbelt-server 1.0.0

package/src/server/guard/sessionSigner.ts

@@ -0,0 +1,425 @@
+/**
+ * The production session signer (02 §4.2) — Ed25519-signed `CCUserClaims` plus
+ * the jti denylist that makes `lock()` mean something.
+ *
+ * The verify harness ships an HMAC stand-in because a probe suite tests the
+ * DECISION table (signature validity, expiry, revocation), not the algorithm.
+ * This is the real one, and the differences are the parts a stand-in cannot
+ * model:
+ *
+ *   * **Asymmetric.** Only the server that holds the private key can mint a
+ *     session. A verifier can be handed the public key alone, so a read-only
+ *     replica or an edge worker can verify without being able to forge.
+ *   * **Revocation is bounded, not unbounded.** A denylist that only ever grows
+ *     is a memory leak wearing a security hat. An entry is dropped once its
+ *     token would have expired anyway, because after `exp` the signature check
+ *     already refuses it.
+ *   * **Expiry before revocation.** An expired token is expired whether or not
+ *     anyone bothered to revoke it — checking in the other order makes the
+ *     denylist load-bearing for a case it does not need to cover.
+ */
+import { createPrivateKey, createPublicKey, generateKeyPairSync, type KeyObject, sign, verify } from 'node:crypto';
+import { type CCUserClaims, CCUserClaimsSchema } from 'cursedbelt-core/session/claims';
+import { AppError } from '../errors';
+import type { GuardVerification, GuardVerifier } from './verifier';
+import type { AsyncRevocationStore } from './revocationStore';
+
+export interface SessionSignerOptions {
+  /**
+   * Ed25519 private key (PEM/DER/`KeyObject`). Omitted ⇒ an ephemeral pair is
+   * generated, which is correct ONLY for a single-process dev server: every
+   * restart invalidates every session, and a second process cannot verify.
+   */
+  privateKey?: KeyObject | string | Buffer;
+  /** Public half, when the verifier is separate from the minter. */
+  publicKey?: KeyObject | string | Buffer;
+  /** Default session lifetime. `guard.features.sessionTtlMinutes` feeds this. */
+  ttlSeconds?: number;
+  /** Clock injection for deterministic tests. */
+  now?: () => number;
+  /** Id generator for `jti`. */
+  mintJti?: () => string;
+  /**
+   * The cross-node denylist (03 §4a). Absent ⇒ the in-process `Map` is the whole
+   * story, which is correct for the local profile. Present (saas) ⇒ a `revoke`
+   * ALSO writes through to the shared store, and `verify` consults it for jtis
+   * revoked on OTHER nodes — so `lock()` on node A closes the token everywhere,
+   * not just where the request landed.
+   */
+  revocationStore?: AsyncRevocationStore;
+  /**
+   * How long a store verdict is trusted before `verify` re-reads it (ms). This is
+   * the cross-node revocation LATENCY BOUND: a jti revoked on another node is
+   * seen here within this window (plus the store's own read latency), because
+   * `verify` stays synchronous — it answers from the cache and refreshes it off
+   * the hot path rather than awaiting a network round trip on every route.
+   * Default 5000 (03 §4a's ≤5s). Ignored when no `revocationStore` is set.
+   */
+  revocationCacheTtlMs?: number;
+  /**
+   * Reports a store read/write that failed. A failed write-through means a
+   * revocation did not reach other nodes — the local Map still refuses the token
+   * HERE, but the host needs to know propagation failed (and may retry). Default:
+   * swallow, because a signer must never throw out of `verify`/`revoke` on the
+   * request path.
+   */
+  onRevocationStoreError?: (op: 'get' | 'set' | 'prune', error: unknown) => void;
+}
+
+/**
+ * One live session this signer minted (02 §4) — the `(userId, tenantId,
+ * deviceLabel)` association the spec asks for, keyed by `jti`.
+ *
+ * The device label is deliberately NOT a claim: `CCUserClaimsSchema` is
+ * `.strict()`, and widening the SIGNED payload with a human-readable string a
+ * client supplies would put attacker-controlled text inside the token every
+ * verifier parses. It is display metadata for "your devices", so it lives here,
+ * server-side, beside the jti it describes.
+ */
+export interface SessionRecord {
+  jti: string;
+  userId: string;
+  tenantId: string;
+  /** What the client called itself (`x-cc-device`), if anything. */
+  deviceLabel?: string;
+  /** Epoch SECONDS, matching `exp`'s unit. */
+  issuedAt: number;
+  exp: number;
+}
+
+/** Non-claim session metadata recorded at mint time (02 §4). */
+export interface SessionMintMeta {
+  /** Free-text device name for the sessions panel. Never signed, never trusted. */
+  deviceLabel?: string;
+}
+
+export interface SessionSigner extends GuardVerifier {
+  /** Mint a signed session token. `exp`/`jti` are stamped here, never by a caller. */
+  mint(
+    claims: Omit<CCUserClaims, 'exp' | 'jti'> & Partial<Pick<CCUserClaims, 'exp' | 'jti'>>,
+    meta?: SessionMintMeta,
+  ): {
+    token: string;
+    claims: CCUserClaims;
+  };
+  /**
+   * Revoke every live session this signer minted for `userId`, returning the
+   * jtis it closed. The primitive behind a role/permission change taking effect
+   * NOW (02 §3 — authorization is decided from the token's claims, so a grant
+   * change that leaves the old token alive is a grant change that did not
+   * happen) and behind "log out everywhere" (02 §4).
+   *
+   * Node-local by construction: it can only enumerate what THIS process minted.
+   * Each revocation still writes through to the shared `revocationStore`, so the
+   * jtis it does know about die fleet-wide; a session minted on another node is
+   * closed when that node calls this (or by its own next login).
+   */
+  revokeUser(userId: string): readonly string[];
+  /**
+   * The live sessions this signer minted for `userId`, newest first — the
+   * "your devices" list (02 §4). Node-local for the same reason `revokeUser` is:
+   * a process can only enumerate what it minted. Expired and revoked entries are
+   * dropped, so what it returns is what a request would still be accepted on.
+   */
+  sessionsOf(userId: string): readonly SessionRecord[];
+  /** Revoked-but-not-yet-expired jtis. Exposed for the shutdown/handover path. */
+  activeRevocations(): readonly string[];
+  /** The public half, for a verifier in another process. */
+  publicKeyPem(): string;
+  /**
+   * Settle every pending revocation-store read and write, then prune the store.
+   *
+   * The store writes on `revoke` and the read-through refreshes on `verify` are
+   * fire-and-forget so neither blocks the request path. This awaits them — for
+   * the shutdown/handover path (a node draining must not lose an unwritten
+   * revocation), for the two-signer replay probe, and for any test that needs the
+   * cross-node state to have settled. A no-op when no `revocationStore` is wired.
+   */
+  flushRevocations(): Promise<void>;
+}
+
+const b64url = (input: string | Buffer | Uint8Array): string => Buffer.from(input).toString('base64url');
+
+/** Ceiling on a client-supplied device label — display text, not a payload. */
+const MAX_DEVICE_LABEL = 64;
+
+let jtiSequence = 0;
+const defaultJti = (): string => {
+  jtiSequence += 1;
+  return `jti_${Date.now().toString(36)}_${jtiSequence.toString(36)}`;
+};
+
+export const createSessionSigner = (options: SessionSignerOptions = {}): SessionSigner => {
+  const now = options.now ?? (() => Date.now());
+  const mintJti = options.mintJti ?? defaultJti;
+  const ttlSeconds = options.ttlSeconds ?? 30 * 60;
+
+  let privateKey: KeyObject | null = null;
+  let publicKey: KeyObject;
+
+  if (options.privateKey !== undefined) {
+    privateKey =
+      typeof options.privateKey === 'string' || Buffer.isBuffer(options.privateKey)
+        ? createPrivateKey(options.privateKey)
+        : options.privateKey;
+    publicKey =
+      options.publicKey === undefined
+        ? createPublicKey(privateKey)
+        : typeof options.publicKey === 'string' || Buffer.isBuffer(options.publicKey)
+          ? createPublicKey(options.publicKey)
+          : options.publicKey;
+  } else if (options.publicKey !== undefined) {
+    publicKey =
+      typeof options.publicKey === 'string' || Buffer.isBuffer(options.publicKey)
+        ? createPublicKey(options.publicKey)
+        : options.publicKey;
+  } else {
+    const pair = generateKeyPairSync('ed25519');
+    privateKey = pair.privateKey;
+    publicKey = pair.publicKey;
+  }
+
+  /** jti → the epoch-seconds `exp` after which the entry is pointless. */
+  const revoked = new Map<string, number>();
+
+  /**
+   * Live jtis this signer minted, per user — the index behind
+   * {@link SessionSigner.revokeUser} (02 §3's role change, 02 §4's "log out
+   * everywhere"). Deliberately NOT the cross-node picture: a node can only
+   * enumerate what it minted, so under saas the authority for "is this token
+   * dead" stays the shared `revocationStore` that `revokeUser` writes through
+   * to. Entries are dropped as they expire (`pruneMinted`), so this is bounded
+   * by live sessions, not by all sessions ever.
+   */
+  const mintedByUser = new Map<string, Map<string, SessionRecord>>();
+  /** jti → its minter, so a revoke can drop the record without scanning users. */
+  const userByJti = new Map<string, string>();
+
+  const rememberMinted = (record: SessionRecord): void => {
+    const forUser = mintedByUser.get(record.userId) ?? new Map<string, SessionRecord>();
+    forUser.set(record.jti, record);
+    mintedByUser.set(record.userId, forUser);
+    userByJti.set(record.jti, record.userId);
+  };
+
+  /**
+   * Drop a jti from the live index. Called on every revoke, so a revoked session
+   * stops being a live one for BOTH `sessionsOf` (the panel) and `revokeUser`
+   * (whose count is then "sessions actually closed", not "jtis ever minted").
+   */
+  const forgetMinted = (jti: string): void => {
+    const userId = userByJti.get(jti);
+    if (userId === undefined) return;
+    userByJti.delete(jti);
+    const forUser = mintedByUser.get(userId);
+    forUser?.delete(jti);
+    if (forUser && forUser.size === 0) mintedByUser.delete(userId);
+  };
+
+  const pruneMinted = (): void => {
+    const cutoff = Math.floor(now() / 1000);
+    for (const [userId, sessions] of mintedByUser) {
+      for (const [jti, record] of sessions)
+        if (record.exp <= cutoff) {
+          sessions.delete(jti);
+          userByJti.delete(jti);
+        }
+      if (sessions.size === 0) mintedByUser.delete(userId);
+    }
+  };
+
+  // ── the cross-node denylist (03 §4a) ────────────────────────────────────────
+  const store = options.revocationStore;
+  const cacheTtlMs = options.revocationCacheTtlMs ?? 5000;
+  const onStoreError = options.onRevocationStoreError ?? (() => undefined);
+  /** jti → the last store verdict and when it was read, so `verify` stays sync. */
+  const storeCache = new Map<string, { exp: number | null; readAtMs: number }>();
+  /** In-flight async work, so `flushRevocations` (and shutdown) can await it. */
+  const pending = new Set<Promise<unknown>>();
+  /** Reads in flight per jti, so a burst of verifies coalesces into one store read. */
+  const inflightReads = new Map<string, Promise<void>>();
+
+  const track = (work: Promise<unknown>): void => {
+    pending.add(work);
+    void work.finally(() => pending.delete(work));
+  };
+
+  /** Read the store for `jti` off the hot path and fold the verdict into the cache. */
+  const refreshFromStore = (jti: string): void => {
+    if (!store || inflightReads.has(jti)) return;
+    const read = store
+      .get(jti)
+      .then((exp) => {
+        storeCache.set(jti, { exp, readAtMs: now() });
+        // A confirmed revocation is promoted into the authoritative Map so every
+        // later verify is instant and `activeRevocations()` (the handover set)
+        // includes jtis this node learned about from its peers.
+        if (exp !== null) {
+          revoked.set(jti, exp);
+          // A peer revoked it, so it is no longer a live session here either.
+          forgetMinted(jti);
+        }
+      })
+      .catch((error) => onStoreError('get', error))
+      .finally(() => inflightReads.delete(jti));
+    inflightReads.set(jti, read);
+    track(read);
+  };
+
+  /**
+   * Is `jti` revoked, per the shared store? Answered synchronously from the cache;
+   * a stale or missing entry schedules a refresh but does NOT block. The bound on
+   * how stale the answer can be is `cacheTtlMs` — the cross-node latency the seam
+   * documents.
+   */
+  const storeSaysRevoked = (jti: string): boolean => {
+    if (!store) return false;
+    const cached = storeCache.get(jti);
+    if (cached === undefined || now() - cached.readAtMs >= cacheTtlMs) refreshFromStore(jti);
+    // A fresh cached exp that is still in the future ⇒ revoked. An expired cached
+    // exp is treated as not-revoked: the signature check already refuses the
+    // token past `exp`, so the denylist has nothing left to add.
+    return cached?.exp != null && cached.exp * 1000 > now();
+  };
+
+  /**
+   * The one revocation write path — a free function rather than a method so
+   * `revokeUser` cannot depend on `this` (a destructured `const { revokeUser } =
+   * signer` would silently lose it, and losing a revocation is the one bug this
+   * seam must not have).
+   */
+  const revokeJti = (jti: string): void => {
+    pruneRevocations();
+    // An unknown jti is still recorded: `lock()` may revoke a token this
+    // process never minted (another node in the fleet did), and refusing to
+    // remember it would let that token keep working here.
+    const exp = Math.floor(now() / 1000) + ttlSeconds;
+    revoked.set(jti, exp);
+    forgetMinted(jti);
+    // Write through so every OTHER node sees it too. Fire-and-forget: `revoke`
+    // is called on the request path (a `lock`), and the local Map already
+    // refuses the token HERE the instant this returns — propagation is what the
+    // store adds, and `flushRevocations`/the error hook cover its durability.
+    if (store) {
+      storeCache.set(jti, { exp, readAtMs: now() });
+      track(store.set(jti, exp).catch((error) => onStoreError('set', error)));
+    }
+  };
+
+  const pruneRevocations = (): void => {
+    const cutoff = Math.floor(now() / 1000);
+    for (const [jti, exp] of revoked) if (exp <= cutoff) revoked.delete(jti);
+    for (const [jti, cached] of storeCache) if (cached.exp !== null && cached.exp <= cutoff) storeCache.delete(jti);
+  };
+
+  return {
+    mint(input, meta) {
+      if (privateKey === null)
+        throw new AppError('This session signer holds only a public key and cannot mint tokens.', {
+          code: 'GUARD_SIGNER_READONLY',
+          status: 500,
+          category: 'security',
+          isOperational: false,
+        });
+
+      const claims: CCUserClaims = CCUserClaimsSchema.parse({
+        ...input,
+        exp: input.exp ?? Math.floor(now() / 1000) + ttlSeconds,
+        jti: input.jti ?? mintJti(),
+      });
+      const payload = b64url(JSON.stringify(claims));
+      const signature = b64url(sign(null, Buffer.from(payload), privateKey));
+      pruneMinted();
+      rememberMinted({
+        jti: claims.jti,
+        userId: claims.userId,
+        tenantId: claims.tenantId,
+        // A label is truncated rather than rejected: it is display text, and a
+        // login must never fail because a browser sent a long device string.
+        ...(meta?.deviceLabel ? { deviceLabel: meta.deviceLabel.slice(0, MAX_DEVICE_LABEL) } : {}),
+        issuedAt: Math.floor(now() / 1000),
+        exp: claims.exp,
+      });
+      return { token: `${payload}.${signature}`, claims };
+    },
+
+    verify(token: string | undefined): GuardVerification {
+      if (!token) return { ok: false, failure: 'missing' };
+      const dot = token.indexOf('.');
+      if (dot <= 0 || dot === token.length - 1) return { ok: false, failure: 'malformed' };
+      const payload = token.slice(0, dot);
+      const signature = token.slice(dot + 1);
+
+      let valid = false;
+      try {
+        valid = verify(null, Buffer.from(payload), publicKey, Buffer.from(signature, 'base64url'));
+      } catch {
+        // A signature that is not even decodable is malformed, not merely wrong.
+        return { ok: false, failure: 'malformed' };
+      }
+      if (!valid) return { ok: false, failure: 'invalid-signature' };
+
+      let parsedJson: unknown;
+      try {
+        parsedJson = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+      } catch {
+        return { ok: false, failure: 'malformed' };
+      }
+      const parsed = CCUserClaimsSchema.safeParse(parsedJson);
+      // `.strict()`: an unknown claim key is a forged or version-skewed token,
+      // and silently ignoring it is how a `permissions` typo becomes a grant.
+      if (!parsed.success) return { ok: false, failure: 'malformed' };
+
+      if (parsed.data.exp * 1000 <= now()) return { ok: false, failure: 'expired' };
+      // Local Map first (this node's own revokes, and peers' revokes it has
+      // already learned) — always authoritative and free. Then the shared store,
+      // consulted through the sync cache, for a jti revoked on another node.
+      if (revoked.has(parsed.data.jti) || storeSaysRevoked(parsed.data.jti)) return { ok: false, failure: 'revoked' };
+      return { ok: true, claims: parsed.data };
+    },
+
+    revoke(jti: string): void {
+      revokeJti(jti);
+    },
+
+    revokeUser(userId: string): readonly string[] {
+      pruneMinted();
+      const jtis = [...(mintedByUser.get(userId)?.keys() ?? [])];
+      for (const jti of jtis) revokeJti(jti);
+      mintedByUser.delete(userId);
+      return jtis;
+    },
+
+    sessionsOf(userId: string): readonly SessionRecord[] {
+      pruneMinted();
+      pruneRevocations();
+      return [...(mintedByUser.get(userId)?.values() ?? [])]
+        // A revoked-but-unexpired jti is a dead session; listing it would invite
+        // "log this device out" on a device that is already out.
+        .filter((record) => !revoked.has(record.jti) && !storeSaysRevoked(record.jti))
+        .sort((left, right) => right.issuedAt - left.issuedAt);
+    },
+
+    isRevoked(jti: string): boolean {
+      pruneRevocations();
+      return revoked.has(jti) || storeSaysRevoked(jti);
+    },
+
+    activeRevocations(): readonly string[] {
+      pruneRevocations();
+      return [...revoked.keys()];
+    },
+
+    async flushRevocations(): Promise<void> {
+      // Settle in-flight work, then whatever it scheduled (a read can resolve
+      // after we snapshot), so the caller sees a fully-quiesced state.
+      while (pending.size > 0) await Promise.allSettled([...pending]);
+      if (store) track(store.prune(Math.floor(now() / 1000)).catch((error) => onStoreError('prune', error)));
+      while (pending.size > 0) await Promise.allSettled([...pending]);
+    },
+
+    publicKeyPem(): string {
+      return publicKey.export({ type: 'spki', format: 'pem' }).toString();
+    },
+  };
+};

package/src/server/guard/verifier.ts

@@ -0,0 +1,27 @@
+/*
+ * The per-request session-verification contract. Moved here from the cc engine's
+ * `mixins/types.ts` at the 2026-09-15 split: `sessionSigner` — the production
+ * implementation, which every app-tier login door uses — must not depend on the
+ * SaaS engine package for its own return type. `cursedbelt-cc` re-exports these
+ * from here, so the engine and the app tier keep speaking the same words.
+ */
+import type { CCUserClaims } from 'cursedbelt-core/session/claims';
+
+/** Why a presented session token was refused. Mapped to status by `guardVerify`. */
+export type GuardFailure = 'missing' | 'malformed' | 'invalid-signature' | 'expired' | 'revoked';
+
+export type GuardVerification =
+	| { ok: true; claims: CCUserClaims }
+	| { ok: false; failure: GuardFailure };
+
+/**
+ * Per-request token verification (02 §4.2). The wire only signals; this is what
+ * decides. `verify` is called on every private or mutating route — a pane's
+ * unlock is never cached for another pane's request.
+ */
+export interface GuardVerifier {
+	verify(token: string | undefined): GuardVerification;
+	/** Revoke a jti until its `exp` — what lock does, across every tab. */
+	revoke(jti: string): void;
+	isRevoked(jti: string): boolean;
+}