serverless-ircd 0.9.0 → 0.11.0

package/packages/irc-core/src/ports.ts

@@ -7,6 +7,12 @@
  */
 
 import { caseFold } from './case-fold.js';
+import {
+  CERT_FP_PREFIX,
+  type CertIdentity,
+  canonicalizeCertSubject,
+  certFingerprintId,
+} from './certfp.js';
 import {
   type HashedAccountCredential,
   hashAccountCredential,
@@ -15,6 +21,8 @@ import {
 import type { ChannelState } from './state/channel.js';
 import type { ConnId, ConnectionState } from './state/connection.js';
 
+export type { CertIdentity } from './certfp.js';
+
 /** Read-only wall clock, epoch milliseconds. */
 export interface Clock {
   now(): number;
@@ -63,10 +71,11 @@ export interface IdFactory {
 }
 
 /**
- * Production id factory. Generates UUIDv4-shaped strings without relying
- * on `crypto` so the same code runs on Node 24, Cloudflare Workers, and
- * Lambda without per-platform type wrangling. Uniqueness is statistical;
- * for cryptographic IDs, adapters can supply their own {@link IdFactory}.
+ * Production id factory. Generates UUIDv4-shaped strings from a CSPRNG
+ * (`globalThis.crypto.getRandomValues`), which is available on Node 19+
+ * and Cloudflare Workers as a global. The randomness is cryptographic-
+ * grade, so generated ids are suitable as unforgeable msgids / session
+ * ids as well as opaque batch references.
  */
 export class UuidIdFactory implements IdFactory {
   batchId(): string {
@@ -83,22 +92,29 @@ export class UuidIdFactory implements IdFactory {
   }
 }
 
-// RFC 4122 v4 shape (random). Six fixed bits identify the version/variant;
-// the remaining 122 bits come from Math.random. Good enough for non-security
-// identifiers like BATCH ref ids and msgid tags.
 const HEX = '0123456789abcdef';
+
+/**
+ * RFC 4122 v4 (random) UUID. Six fixed bits identify the version/variant;
+ * the remaining 122 bits are sourced from `globalThis.crypto.getRandomValues`
+ * as a single 16-byte buffer (one syscall per id). The global is used — not
+ * `node:crypto` — so the same code runs unmodified on Node and Cloudflare
+ * Workers.
+ */
 function uuidV4(): string {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
   let out = '';
-  for (let i = 0; i < 36; i++) {
-    if (i === 8 || i === 13 || i === 18 || i === 23) {
-      out += '-';
-    } else if (i === 14) {
-      out += '4';
-    } else if (i === 19) {
-      out += HEX[(Math.random() * 4) | 0 | 0x8];
-    } else {
-      out += HEX[(Math.random() * 16) | 0];
-    }
+  let i = 0;
+  for (let b of bytes) {
+    // Version nibble (bits 48-51 of the 128-bit id) = 0b0100 (v4).
+    if (i === 6) b = (b & 0x0f) | 0x40;
+    // Variant nibble (bits 64-65) = 0b10 (RFC 4122 / Leach-Salz).
+    else if (i === 8) b = (b & 0x3f) | 0x80;
+    // Dashes sit at byte offsets 4, 6, 8, 10 between the 4-2-2-2-6 byte groups.
+    if (i === 4 || i === 6 || i === 8 || i === 10) out += '-';
+    out += HEX.charAt(b >> 4);
+    out += HEX.charAt(b & 0x0f);
+    i++;
   }
   return out;
 }
@@ -124,6 +140,31 @@ export class SequentialIdFactory implements IdFactory {
   }
 }
 
+/**
+ * Constant-time string equality.
+ *
+ * Walks both inputs position by position (UTF-16 code units, a bijection
+ * with UTF-8 bytes for equality purposes) out to the longer input's length,
+ * XOR-accumulating every difference. The amount of work — and therefore the
+ * wall-clock profile — does not depend on where the first mismatch sits, so
+ * a remote timing attacker cannot recover a matching-prefix length the way a
+ * short-circuiting `===` would reveal. `charCodeAt` past the end yields
+ * `NaN`, which XOR-folds to 0, so a length mismatch is caught purely by the
+ * length-difference seed in `diff`.
+ *
+ * Deliberately free of `node:crypto` (pure arithmetic) so the same code
+ * runs unmodified on Node and Cloudflare Workers. Used for secret
+ * comparisons such as the server-password gate at registration.
+ */
+export function constantTimeEquals(a: string, b: string): boolean {
+  const maxLen = Math.max(a.length, b.length);
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < maxLen; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
 /**
  * Port supplying the server's Message-of-the-Day text.
  *
@@ -169,121 +210,6 @@ export class StaticMotdProvider implements MotdProvider {
 /** Convenience: a {@link MotdProvider} that always reports "no MOTD". */
 export const EmptyMotdProvider: MotdProvider = new StaticMotdProvider([]);
 
-/**
- * Parsed SASL credentials handed to an {@link AccountStore}.
- *
- * `PLAIN` is the structured form produced by base64-decoding and splitting
- * the `\0authzid\0authcid\0passwd` payload. `RAW` carries the decoded bytes
- * for any other mechanism the server wants to forward verbatim.
- */
-export type SaslPayload =
-  | { kind: 'PLAIN'; username: string; password: string }
-  | { kind: 'RAW'; data: string }
-  | { kind: 'EXTERNAL'; identity: string };
-
-/**
- * Outcome of an {@link AccountStore.verify} call: either the canonical
- * account name to record on the connection, or a human-readable reason
- * for the failure that surfaces as `904 ERR_SASLFAIL`.
- */
-export type SaslResult = { ok: true; account: string } | { ok: false; reason: string };
-
-/**
- * Port that verifies SASL credentials against the deployment's account
- * backend.
- *
- * The method is **synchronous** on purpose: reducers must stay pure and
- * cannot await. Adapters that need an async lookup (D1, DynamoDB, Secrets
- * Manager) pre-load the credentials they need into a synchronously-readable
- * store (mirroring the {@link MotdProvider} pattern). For Phase 1 the
- * in-memory reference adapter and tests inject a fake directly.
- */
-export interface AccountStore {
-  verify(mech: string, payload: SaslPayload): SaslResult;
-}
-
-/**
- * One SASL PLAIN credential entry seeded into an {@link InMemoryAccountStore}.
- * The `username` is also the canonical account name recorded on the
- * connection for `extended-join` / `account-tag`.
- */
-export interface SaslAccountCredential {
-  username: string;
-  password: string;
-  /**
-   * Optional mTLS client-certificate subject (e.g. `CN=alice` or a
-   * fingerprint hash). When set, SASL `EXTERNAL` authentications that
-   * present this subject are mapped to {@link username} as the account.
-   */
-  certSubject?: string;
-}
-
-/**
- * Reference in-memory {@link AccountStore} backed by a static list of PLAIN
- * credentials seeded at construction.
- *
- * Mirrors the {@link InMemoryMessageStore} / {@link StaticMotdProvider}
- * pattern: the port is synchronous, so adapters that need an async backend
- * (D1, DynamoDB, Secrets Manager) pre-load their credentials into this store
- * at boot. All three adapters (local-cli, CF, AWS) use this as the minimum
- * viable `AccountStore`; a persistent variant (DynamoDB `Accounts` table, D1)
- * is a documented follow-up that swaps in by replacing the construction call.
- *
- * Password comparison is constant-time to avoid the early-return timing
- * oracle a naive `===` would expose. Only `PLAIN` is verified; any other
- * mechanism returns failure (matching the reducer's mech gating).
- */
-export class InMemoryAccountStore implements AccountStore {
-  private readonly creds: ReadonlyMap<string, string>;
-  private readonly certMap: ReadonlyMap<string, string>;
-
-  constructor(credentials: ReadonlyArray<SaslAccountCredential>) {
-    this.creds = new Map(credentials.map((c) => [c.username, c.password]));
-    this.certMap = new Map(
-      credentials
-        .filter((c) => c.certSubject !== undefined)
-        .map((c) => [c.certSubject as string, c.username]),
-    );
-  }
-
-  verify(mech: string, payload: SaslPayload): SaslResult {
-    const m = mech.toUpperCase();
-    if (m === 'PLAIN' && payload.kind === 'PLAIN') {
-      const expected = this.creds.get(payload.username);
-      if (expected === undefined) {
-        return { ok: false, reason: 'invalid credentials' };
-      }
-      if (!constantTimeEquals(payload.password, expected)) {
-        return { ok: false, reason: 'invalid credentials' };
-      }
-      return { ok: true, account: payload.username };
-    }
-    if (m === 'EXTERNAL' && payload.kind === 'EXTERNAL') {
-      const account = this.certMap.get(payload.identity);
-      if (account === undefined) {
-        return { ok: false, reason: 'untrusted certificate' };
-      }
-      return { ok: true, account };
-    }
-    return { ok: false, reason: `unsupported mechanism: ${mech}` };
-  }
-}
-
-/**
- * Constant-time string equality. Compares every byte regardless of early
- * mismatches so a remote attacker cannot short-circuit the comparison via a
- * timing side-channel. Returns `false` when the lengths differ (the length
- * is not considered secret for SASL PLAIN passwords).
- */
-function constantTimeEquals(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) {
-    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  }
-  return diff === 0;
-}
-
 // ============================================================================
 // mTLS identity (SASL EXTERNAL)
 // ============================================================================
@@ -294,9 +220,13 @@ function constantTimeEquals(a: string, b: string): boolean {
  *
  * At the edge (CF API Shield mTLS, AWS API Gateway custom-domain mTLS) the
  * platform terminates TLS, validates the client certificate against the
- * configured trust store, and surfaces the certificate subject to the
+ * configured trust store, and surfaces the certificate identity to the
  * Worker/Lambda. The adapter captures this at connection-admission time
- * and stores it keyed by connection ID.
+ * and stores it keyed by connection ID as a {@link CertIdentity}: the raw
+ * subject string, its canonical DN, and — where the platform provides one
+ * (Cloudflare: `cf.tlsClientAuth.certFingerprintSHA256`) — the SHA-256
+ * fingerprint of the certificate DER, which is the preferred account
+ * binding. See `docs/SASL-EXTERNAL.md`.
  *
  * The method is **synchronous** — adapters pre-populate the identity at
  * admission time (before the first reducer runs), so the SASL EXTERNAL
@@ -306,26 +236,26 @@ function constantTimeEquals(a: string, b: string): boolean {
  */
 export interface MtlsIdentityProvider {
   /**
-   * @returns the verified client-cert subject for `connId`, or `undefined`
+   * @returns the verified client-cert identity for `connId`, or `undefined`
    *   when no trusted certificate was presented.
    */
-  getIdentity(connId: string): string | undefined;
+  getIdentity(connId: string): CertIdentity | undefined;
 }
 
 /**
  * Reference in-memory {@link MtlsIdentityProvider} backed by a static map
- * of connection IDs to certificate subjects. Useful for tests and the
+ * of connection IDs to certificate identities. Useful for tests and the
  * local-cli adapter; cloud adapters replace this with a lookup keyed by
  * the platform's connection identifier.
  */
 export class InMemoryMtlsIdentityProvider implements MtlsIdentityProvider {
-  private readonly identities: ReadonlyMap<string, string>;
+  private readonly identities: ReadonlyMap<string, CertIdentity>;
 
-  constructor(entries: ReadonlyArray<{ connId: string; identity: string }>) {
+  constructor(entries: ReadonlyArray<{ connId: string; identity: CertIdentity }>) {
     this.identities = new Map(entries.map((e) => [e.connId, e.identity]));
   }
 
-  getIdentity(connId: string): string | undefined {
+  getIdentity(connId: string): CertIdentity | undefined {
     return this.identities.get(connId);
   }
 }
@@ -395,7 +325,7 @@ export interface TargetEntry {
 /**
  * Persistence port for IRCv3 `draft/chathistory` playback.
  *
- * Mirrors the {@link MotdProvider} / {@link AccountStore} pattern: the port
+ * Mirrors the {@link MotdProvider} pattern: the port
  * is **synchronous** (reducers must stay pure and free of IO) and injected
  * via {@link Ctx}. Adapters that need async storage (D1, R2, DynamoDB)
  * pre-load the relevant slice into a synchronously-readable store; Phase 1
@@ -744,6 +674,22 @@ export type NickEnforcePolicy = 'none' | 'ghost' | 'kill';
  * lands). Lookups against the store are case-insensitive (rfc1459-folded);
  * the returned `nick` / `account` preserve the original spelling so the
  * wire renders the user's preferred casing.
+ *
+ * `certSubjects` is the list of mTLS client-certificate bindings attached
+ * to the account via {@link ServicesStore.addCertFP} /
+ * {@link ServicesStore.addCertFingerprint}. An entry is either a DER
+ * SHA-256 fingerprint binding (`fp:<hex>`, the preferred identifier where
+ * the platform surfaces a fingerprint) or a subject DN. SASL EXTERNAL
+ * resolves the verified edge identity against this list via
+ * {@link ServicesStore.verifyCertFP}: the fingerprint arm matches
+ * byte-exactly, DN entries compare on the canonical DN (values
+ * case-sensitive), and legacy verbatim subject spellings are rewritten to
+ * their canonical form on first use. Defaults to an empty array on a
+ * fresh registration; an upcoming NickServ `CERT` command (Atheme parity)
+ * will surface the mutators to the user. Until then bindings are attached
+ * out-of-band via {@link ServicesStore.addCertFP} /
+ * {@link ServicesStore.addCertFingerprint} (seed tooling or direct
+ * backend access) — the seam is the store API, not the wire.
  */
 export interface RegisteredNick {
   /** Display spelling stored at registration. */
@@ -756,6 +702,14 @@ export interface RegisteredNick {
   createdAt: number;
   /** Per-account nick-enforcement policy. */
   enforce: NickEnforcePolicy;
+  /**
+   * Client-certificate bindings attached to this account for SASL EXTERNAL
+   * (CertFP): `fp:<hex>` DER SHA-256 fingerprint bindings and/or subject
+   * DNs (compared via their canonical form; values never case-folded).
+   * Empty on a fresh registration; populated via
+   * {@link ServicesStore.addCertFP} / {@link ServicesStore.addCertFingerprint}.
+   */
+  certSubjects: string[];
 }
 
 /**
@@ -929,6 +883,11 @@ export interface ServicesStore {
    * `{ ok: true, account }` on a match (the canonical spelling), or
    * `{ ok: false, reason }` when the nick is unknown or the password is
    * wrong.
+   *
+   * Timing contract: implementations MUST cost the unknown-nick and
+   * wrong-password paths equally (one scrypt verify each — see
+   * {@link VERIFY_NICK_PRECOMPUTED_DUMMY}) so latency never reveals
+   * whether a nick is registered.
    */
   verifyNick(nick: string, password: string): ServicesAuthResult;
   /**
@@ -943,6 +902,14 @@ export interface ServicesStore {
    * not registered (the policy stays {@link NickEnforcePolicy.None}).
    */
   setNickEnforce(nick: string, policy: NickEnforcePolicy): void;
+  /**
+   * Overwrites the stored credential for `nick` with a fresh scrypt hash of
+   * `newPassword` (the plaintext is NEVER persisted). Used by NickServ
+   * `SET PASSWORD`. No-op when the nick is not registered. Write-behind
+   * persistent subclasses re-persist the full nick row (hashed credential
+   * included) so a backend reload keeps `verifyNick` working.
+   */
+  setNickPassword(nick: string, newPassword: string): void;
   /**
    * Returns the nick-enforcement policy for `nick`, or
    * {@link NickEnforcePolicy.None} when the nick is not registered.
@@ -956,6 +923,94 @@ export interface ServicesStore {
    */
   getNick(nick: string): RegisteredNick | undefined;
 
+  /**
+   * Records a failed `IDENTIFY` attempt against `nick`: appends the
+   * current clock timestamp to the sliding-window failure list and bumps
+   * the pending owner-notice counter. No-op when the nick is not
+   * registered. Called by the NickServ IDENTIFY reducer AFTER a failed
+   * `verifyNick` (frozen rejections never reach this method — they are
+   * short-circuited before scrypt runs).
+   */
+  recordIdentifyFailure(nick: string): void;
+  /**
+   * Returns `true` iff `nick` is identify-frozen: at least
+   * `opts.maxFailures` failed identifies were recorded within the last
+   * `opts.windowMs` milliseconds. Prunes expired timestamps from the
+   * stored list in place (the sliding window), so the freeze lifts once
+   * the failures age out of the window. Returns `false` for an unknown
+   * nick. Called BEFORE `verifyNick` so a frozen attempt never runs
+   * scrypt.
+   */
+  isNickIdentifyFrozen(nick: string, opts: { maxFailures: number; windowMs: number }): boolean;
+  /**
+   * Clears the failed-identify state for `nick` (the sliding-window
+   * timestamps and the pending owner-notice counter) and returns the
+   * number of failed identifies that were queued for the owner NOTICE
+   * (`0` when none were pending, including for an unknown nick). Called
+   * by the NickServ IDENTIFY reducer on a SUCCESSFUL `verifyNick` — a
+   * successful login both resets the freeze counter and delivers the
+   * queued owner notice.
+   */
+  clearIdentifyFailures(nick: string): number;
+
+  /**
+   * Verifies a client-certificate identity (CertFP) for SASL EXTERNAL.
+   *
+   * Matching arms, in preference order:
+   * 1. **Fingerprint (primary):** when `identity.fingerprint` is present
+   *    (Cloudflare surfaces the DER SHA-256), the normalised
+   *    `fp:<hex>` form is matched byte-exactly against the account's
+   *    {@link RegisteredNick.certSubjects} entries.
+   * 2. **Canonical DN (fallback):** each stored DN entry is canonicalised
+   *    (lowercased attribute types, sorted RDNs/AVAs, collapsed
+   *    whitespace — values stay case-sensitive) and compared to
+   *    `identity.canonicalDn`. This is the only arm available on
+   *    platforms that surface just the subject DN (AWS API Gateway).
+   *
+   * First-use migration: a stored DN entry kept in a legacy verbatim
+   * spelling is rewritten to its canonical form, and — when the platform
+   * supplied a fingerprint — the `fp:<hex>` binding is pinned alongside
+   * it, so subsequent verifies hit the fingerprint arm. Both rewrites
+   * notify {@link onCertBindingsChanged} (write-behind subclasses
+   * re-persist the nick row).
+   *
+   * The edge (CF API Shield / AWS APIGW mTLS) still resolves the verified
+   * identity via {@link MtlsIdentityProvider}; only the identity→account
+   * lookup lives here.
+   *
+   * @returns `{ ok: true, account }` on a match, or `{ ok: false, reason }`
+   *   when no registered nick carries a binding for the certificate.
+   */
+  verifyCertFP(identity: CertIdentity): ServicesAuthResult;
+  /**
+   * Attaches a client-certificate subject DN to `nick` for SASL EXTERNAL.
+   * No-op (and returns `false`) when the nick is not registered.
+   * Byte-exact: a duplicate subject (case-sensitive) is a no-op (idempotent
+   * returns `true`). Canonicalisation happens at verify time (with the
+   * first-use migration above). Future NickServ `CERT ADD` will surface
+   * this. Returns `true` when the subject was newly attached (or already
+   * present), `false` when the nick is unknown.
+   */
+  addCertFP(nick: string, subject: string): boolean;
+  /**
+   * Attaches a DER SHA-256 fingerprint binding (`fp:<hex>` — the primary
+   * CertFP identifier where the platform surfaces a fingerprint) to
+   * `nick`. The fingerprint is normalised (lowercased, colon-free) before
+   * storing, so `AA:11` and `aa11` are the same binding. Idempotent.
+   * Returns `true` when the binding was newly attached (or already
+   * present), `false` when the nick is unknown.
+   */
+  addCertFingerprint(nick: string, fingerprint: string): boolean;
+  /**
+   * Detaches a client-certificate binding from `nick`. `subject` matches
+   * the stored entry byte-exactly — pass either a stored DN entry or a
+   * stored `fp:<hex>` entry as read from {@link RegisteredNick.certSubjects}.
+   * Returns `true` when an entry was removed, `false` when the nick is
+   * unknown or the entry was not attached. Future NickServ `CERT DEL` will
+   * surface this.
+   */
+  removeCertFP(nick: string, subject: string): boolean;
+
   // ----- ChanServ -----
 
   /**
@@ -1180,6 +1235,29 @@ export interface ServicesStore {
   listJupes(): ReadonlyArray<JupeEntry>;
 }
 
+/**
+ * Per-account failed-IDENTIFY throttle state persisted on the nick row.
+ *
+ * Shape decision: a small append-only array of recent failure timestamps
+ * (`identifyFailures`, epoch-ms) plus a pending owner-notice counter. The
+ * timestamp array makes the sliding-window freeze test trivially correct
+ * (prune entries older than the configured window, then compare the
+ * surviving count against the threshold) without a separate "window
+ * start" bookkeeping field, and stays small in practice: once the
+ * threshold is reached the account is frozen (no further failures are
+ * recorded), so the array holds at most threshold + a handful of entries
+ * at any time.
+ */
+export interface IdentifyThrottleState {
+  /** Epoch-ms timestamps of recent failed IDENTIFY attempts. */
+  identifyFailures: number[];
+  /**
+   * Failed-identify count queued for the owner NOTICE delivered on the
+   * next successful identify. Reset to 0 once the notice is delivered.
+   */
+  pendingIdentifyFailureNotice: number;
+}
+
 /**
  * Snapshot row for a NickServ registration, persisted by adapter backends
  * (D1 / DynamoDB) and round-tripped through {@link ServicesSnapshot}.
@@ -1197,9 +1275,13 @@ export interface ServicesStore {
  * The credential never leaves the store via
  * {@link InMemoryServicesStore.getNick} (which returns a defensive copy
  * without it), but it MUST be present in the snapshot so the
- * `verifyNick` round-trip keeps working across a reload.
+ * `verifyNick` round-trip keeps working across a reload. The same holds
+ * for the {@link IdentifyThrottleState} fields: the failed-identify
+ * counter survives connections and deploys so a re-identify from a fresh
+ * connection still sees the freeze.
  */
-export type ServicesNickRow = RegisteredNick & { credential: HashedAccountCredential };
+export type ServicesNickRow = RegisteredNick &
+  IdentifyThrottleState & { credential: HashedAccountCredential };
 
 /**
  * Snapshot row for a ChanServ access entry: `(channel, account, level)`.
@@ -1337,6 +1419,77 @@ type StoredAkill = AkillEntry & { maskKey: string };
  */
 type StoredJupe = JupeEntry & { nameKey: string };
 
+// ============================================================================
+// verifyNick timing equalisation — unknown-nick lookups must cost the same
+// scrypt work as a wrong-password verify so latency cannot enumerate
+// registered nicks. Mirrors the OPER_PRECOMPUTED_DUMMY_HASHED pattern in
+// commands/oper.ts (and the PASS-auth dummy verify in commands/account-auth.ts).
+// ============================================================================
+
+/**
+ * Fixed salt used to bake the precomputed dummy credential below. 16 bytes
+ * of `0x42` so the resulting scrypt derivation is deterministic across Node
+ * versions and test runs (the salt is never used to verify real traffic —
+ * only the dummy entry).
+ */
+const VERIFY_NICK_FIXTURE_SALT = new Uint8Array(16).fill(0x42);
+
+/**
+ * Nick baked into the precomputed dummy credential. Contains a NUL so it can
+ * never be a registered nick (registration rejects control characters) and
+ * the dummy verify never collides with a real credential.
+ */
+const VERIFY_NICK_DUMMY_NICK = '\u0000nick-verify-timing-dummy';
+
+/**
+ * Password baked into the precomputed dummy credential. Contains a NUL so
+ * the dummy verify always fails — its purpose is to spend the same scrypt
+ * work as the known-nick-wrong-password path, NOT to authenticate.
+ */
+const VERIFY_NICK_DUMMY_PASSWORD = '\u0000nick-verify-timing-dummy';
+
+/**
+ * Fixed random scrypt digest (precomputed once at module load from the
+ * NUL-prefixed dummy pair above — never derived from any real credential)
+ * used to equalise timing on the unknown-nick path of
+ * {@link InMemoryServicesStore.verifyNick}. Every caller of `verifyNick`
+ * (SASL PLAIN, PASS-based account auth, NickServ IDENTIFY/SETPASS) then
+ * costs exactly one scrypt verify whether the nick is known or not, so a
+ * remote attacker measuring latency cannot distinguish "nick exists, wrong
+ * password" from "nick unknown".
+ */
+export const VERIFY_NICK_PRECOMPUTED_DUMMY: HashedAccountCredential = hashAccountCredential(
+  VERIFY_NICK_DUMMY_NICK,
+  VERIFY_NICK_DUMMY_PASSWORD,
+  { salt: VERIFY_NICK_FIXTURE_SALT },
+);
+
+/**
+ * Indirection over {@link verifyHashedPassword} so tests can swap in a stub
+ * to assert call counts (timing-equalisation parity tests). Defaults to the
+ * real primitive; `null` restores the default.
+ */
+let verifyNickHashedPasswordFn: (password: string, entry: HashedAccountCredential) => boolean =
+  verifyHashedPassword;
+
+/**
+ * Test seam: replaces the verify primitive with `fn` (or restores the
+ * default when `fn === null`). Exported for tests; production callers MUST
+ * NOT use.
+ *
+ * @internal
+ */
+export function setVerifyNickHashedPassword(
+  fn: ((password: string, entry: HashedAccountCredential) => boolean) | null,
+): void {
+  verifyNickHashedPasswordFn = fn ?? verifyHashedPassword;
+}
+
+/** @internal test seam: clears any spy registered above. */
+export function resetVerifyNickTimingSpy(): void {
+  verifyNickHashedPasswordFn = verifyHashedPassword;
+}
+
 /**
  * Reference in-memory {@link ServicesStore} used by the local CLI,
  * integration tests, and any deployment that has not bound a distributed
@@ -1344,7 +1497,7 @@ type StoredJupe = JupeEntry & { nameKey: string };
  *
  * Backed by plain `Map`s keyed by rfc1459-folded nick / account / channel.
  * Password verification uses the same scrypt path as the SASL
- * {@link HashedAccountStore} ({@link verifyHashedPassword}) so a NickServ
+ * {@link verifyHashedPassword} so a NickServ
  * registration IS a SASL account — both stores carry credentials in the
  * same hashed shape, and SASL PLAIN's services fallback verifies against
  * a row created by `NickServ REGISTER` without a second registration.
@@ -1405,7 +1558,13 @@ export class InMemoryServicesStore implements ServicesStore {
    */
   protected hydrate(snap: ServicesSnapshot): void {
     for (const row of snap.nicks) {
-      this.nicks.set(folded(row.nick), { ...row, credential: { ...row.credential } });
+      this.nicks.set(folded(row.nick), {
+        ...row,
+        certSubjects: [...(row.certSubjects ?? [])],
+        identifyFailures: [...(row.identifyFailures ?? [])],
+        pendingIdentifyFailureNotice: row.pendingIdentifyFailureNotice ?? 0,
+        credential: { ...row.credential },
+      });
     }
     for (const row of snap.channels) {
       const stored: RegisteredChannel = { ...row };
@@ -1477,7 +1636,12 @@ export class InMemoryServicesStore implements ServicesStore {
   snapshot(): ServicesSnapshot {
     const nicks: ServicesNickRow[] = [];
     for (const rec of this.nicks.values()) {
-      nicks.push({ ...rec, credential: { ...rec.credential } });
+      nicks.push({
+        ...rec,
+        certSubjects: [...rec.certSubjects],
+        identifyFailures: [...rec.identifyFailures],
+        credential: { ...rec.credential },
+      });
     }
     const channels: RegisteredChannel[] = [];
     for (const rec of this.channels.values()) {
@@ -1554,6 +1718,9 @@ export class InMemoryServicesStore implements ServicesStore {
       email,
       createdAt: now,
       enforce: 'none',
+      certSubjects: [],
+      identifyFailures: [],
+      pendingIdentifyFailureNotice: 0,
       credential,
     });
     return { ok: true, account: nick };
@@ -1562,9 +1729,15 @@ export class InMemoryServicesStore implements ServicesStore {
   verifyNick(nick: string, password: string): ServicesAuthResult {
     const rec = this.nicks.get(folded(nick));
     if (rec === undefined) {
+      // Equalise timing: unknown-nick must cost the same scrypt work as a
+      // wrong password so callers (SASL PLAIN, PASS auth, NickServ
+      // IDENTIFY/SETPASS) cannot leak nick existence via latency. The
+      // dummy verify runs against a fixed precomputed digest — the result
+      // is discarded, the cost is the point.
+      verifyNickHashedPasswordFn(password, VERIFY_NICK_PRECOMPUTED_DUMMY);
       return { ok: false, reason: 'invalid credentials' };
     }
-    if (!verifyHashedPassword(password, rec.credential)) {
+    if (!verifyNickHashedPasswordFn(password, rec.credential)) {
       return { ok: false, reason: 'invalid credentials' };
     }
     return { ok: true, account: rec.account };
@@ -1585,6 +1758,12 @@ export class InMemoryServicesStore implements ServicesStore {
     rec.enforce = policy;
   }
 
+  setNickPassword(nick: string, newPassword: string): void {
+    const rec = this.nicks.get(folded(nick));
+    if (rec === undefined) return;
+    rec.credential = hashAccountCredential(rec.account, newPassword);
+  }
+
   getNickEnforce(nick: string): NickEnforcePolicy {
     return this.nicks.get(folded(nick))?.enforce ?? 'none';
   }
@@ -1600,46 +1779,113 @@ export class InMemoryServicesStore implements ServicesStore {
       email: rec.email,
       createdAt: rec.createdAt,
       enforce: rec.enforce,
+      certSubjects: [...rec.certSubjects],
     };
   }
 
-  /**
-   * Adopts a pre-hashed SASL account credential as a registered nick.
-   *
-   * This is the unification seam: an account seeded into the SASL
-   * `AccountStore` (the `accounts`/`Accounts` table, populated by the
-   * seed tooling) is treated as a NickServ registration so `INFO`
-   * resolves it, `SET ENFORCE` applies, and NickServ `IDENTIFY` succeeds
-   * with the seeded password. The resulting {@link RegisteredNick} carries
-   * an empty email, the default `'none'` enforcement policy, and
-   * `createdAt = clock.now()`; the supplied {@link HashedAccountCredential}
-   * is stored verbatim so `verifyNick` re-derives via the same scrypt
-   * path as `registerNick`.
-   *
-   * Returns `true` when a new registration was created; `false` when the
-   * nick (case-insensitive) is already registered — the existing record
-   * wins and the supplied credential is NOT overwritten. Idempotent in
-   * the sense that re-ingesting the same credential is a no-op.
-   *
-   * Adapters call this once per cold start, after both the SASL store and
-   * the services store have been loaded, to merge the SASL account set
-   * into the unified services account set.
-   */
-  ingestAccountCredential(credential: HashedAccountCredential): boolean {
-    const key = folded(credential.account);
-    if (this.nicks.has(key)) return false;
-    const account = credential.account;
-    this.nicks.set(key, {
-      nick: account,
-      account,
-      email: '',
-      createdAt: this.clock.now(),
-      enforce: 'none',
-      credential: { ...credential },
-    });
+  recordIdentifyFailure(nick: string): void {
+    const rec = this.nicks.get(folded(nick));
+    if (rec === undefined) return;
+    rec.identifyFailures.push(this.clock.now());
+    rec.pendingIdentifyFailureNotice += 1;
+  }
+
+  isNickIdentifyFrozen(nick: string, opts: { maxFailures: number; windowMs: number }): boolean {
+    const rec = this.nicks.get(folded(nick));
+    if (rec === undefined) return false;
+    // Sliding window: drop failures that have aged out (age >= windowMs),
+    // then freeze iff the surviving count still meets the threshold. The
+    // prune is in place, so the freeze lifts automatically as failures
+    // expire even if no further attempts arrive.
+    const cutoff = this.clock.now() - opts.windowMs;
+    rec.identifyFailures = rec.identifyFailures.filter((t) => t > cutoff);
+    return rec.identifyFailures.length >= opts.maxFailures;
+  }
+
+  clearIdentifyFailures(nick: string): number {
+    const rec = this.nicks.get(folded(nick));
+    if (rec === undefined) return 0;
+    const pending = rec.pendingIdentifyFailureNotice;
+    rec.pendingIdentifyFailureNotice = 0;
+    rec.identifyFailures = [];
+    return pending;
+  }
+
+  verifyCertFP(identity: CertIdentity): ServicesAuthResult {
+    // Arm 1 — fingerprint (primary identifier where the platform surfaces
+    // the DER SHA-256, e.g. Cloudflare's tlsClientAuth.certFingerprintSHA256).
+    const fpId =
+      identity.fingerprint !== undefined ? certFingerprintId(identity.fingerprint) : undefined;
+    if (fpId !== undefined) {
+      for (const rec of this.nicks.values()) {
+        if (rec.certSubjects.includes(fpId)) {
+          return { ok: true, account: rec.account };
+        }
+      }
+    }
+    // Arm 2 — canonical DN (the only arm on subject-DN-only platforms like
+    // API Gateway). Stored DN entries are canonicalised at compare time so
+    // legacy verbatim spellings still match; first use rewrites them (and
+    // pins the fingerprint, when available).
+    for (const rec of this.nicks.values()) {
+      const idx = rec.certSubjects.findIndex(
+        (entry) =>
+          !entry.startsWith(CERT_FP_PREFIX) &&
+          canonicalizeCertSubject(entry) === identity.canonicalDn,
+      );
+      if (idx === -1) continue;
+      let mutated = false;
+      if (rec.certSubjects[idx] !== identity.canonicalDn) {
+        rec.certSubjects[idx] = identity.canonicalDn;
+        mutated = true;
+      }
+      if (fpId !== undefined && !rec.certSubjects.includes(fpId)) {
+        rec.certSubjects.push(fpId);
+        mutated = true;
+      }
+      if (mutated) this.onCertBindingsChanged(rec.nick);
+      return { ok: true, account: rec.account };
+    }
+    return { ok: false, reason: 'untrusted certificate' };
+  }
+
+  addCertFP(nick: string, subject: string): boolean {
+    const rec = this.nicks.get(folded(nick));
+    if (rec === undefined) return false;
+    if (rec.certSubjects.includes(subject)) return true;
+    rec.certSubjects.push(subject);
+    return true;
+  }
+
+  addCertFingerprint(nick: string, fingerprint: string): boolean {
+    const rec = this.nicks.get(folded(nick));
+    if (rec === undefined) return false;
+    const fpId = certFingerprintId(fingerprint);
+    if (rec.certSubjects.includes(fpId)) return true;
+    rec.certSubjects.push(fpId);
+    return true;
+  }
+
+  removeCertFP(nick: string, subject: string): boolean {
+    const rec = this.nicks.get(folded(nick));
+    if (rec === undefined) return false;
+    const idx = rec.certSubjects.indexOf(subject);
+    if (idx === -1) return false;
+    rec.certSubjects.splice(idx, 1);
     return true;
   }
 
+  /**
+   * Hook fired when a `verifyCertFP` call rewrote the account's stored
+   * cert bindings (legacy-spelling migration and/or fingerprint pinning).
+   * No-op in the plain in-memory store; the write-behind
+   * {@link PersistentServicesStore} subclass overrides it to re-persist
+   * the nick row so the migration survives a backend reload.
+   */
+  protected onCertBindingsChanged(nick: string): void {
+    void nick;
+  }
+
   /**
    * Returns the full stored nick row (including the scrypt-hashed
    * credential), or `undefined` when the nick is not registered. Defensive
@@ -1654,7 +1900,14 @@ export class InMemoryServicesStore implements ServicesStore {
    */
   protected getStoredNick(nick: string): ServicesNickRow | undefined {
     const rec = this.nicks.get(folded(nick));
-    return rec === undefined ? undefined : { ...rec, credential: { ...rec.credential } };
+    return rec === undefined
+      ? undefined
+      : {
+          ...rec,
+          certSubjects: [...rec.certSubjects],
+          identifyFailures: [...rec.identifyFailures],
+          credential: { ...rec.credential },
+        };
   }
 
   // ----- ChanServ -----
@@ -2127,13 +2380,99 @@ export abstract class PersistentServicesStore extends InMemoryServicesStore {
     this.enqueue({ kind: 'upsertNick', row });
   }
 
-  override ingestAccountCredential(credential: HashedAccountCredential): boolean {
-    const created = super.ingestAccountCredential(credential);
-    if (created) {
-      const row = this.getStoredNick(credential.account) as ServicesNickRow | undefined;
-      if (row !== undefined) this.enqueue({ kind: 'upsertNick', row });
+  override setNickPassword(nick: string, newPassword: string): void {
+    if (!this.isRegisteredNick(nick)) return;
+    super.setNickPassword(nick, newPassword);
+    // The `isRegisteredNick` guard above guarantees the nick is present, so
+    // `getStoredNick` is defined — read it back to capture the freshly-hashed
+    // credential so a backend reload keeps `verifyNick` working.
+    const row = this.getStoredNick(nick) as ServicesNickRow;
+    this.enqueue({ kind: 'upsertNick', row });
+  }
+
+  override recordIdentifyFailure(nick: string): void {
+    if (!this.isRegisteredNick(nick)) return;
+    super.recordIdentifyFailure(nick);
+    // Re-persist the full row so the failure timestamps + pending owner
+    // notice survive a deploy: a re-identify from a fresh connection (or
+    // store) must still see the freeze.
+    const row = this.getStoredNick(nick) as ServicesNickRow;
+    this.enqueue({ kind: 'upsertNick', row });
+  }
+
+  override clearIdentifyFailures(nick: string): number {
+    if (!this.isRegisteredNick(nick)) return 0;
+    // Suppress the spurious write when there is no throttle state queued
+    // (the common case on an unmolested account). The `isRegisteredNick`
+    // guard above guarantees the stored row is defined.
+    const before = this.getStoredNick(nick) as ServicesNickRow;
+    if (before.identifyFailures.length === 0 && before.pendingIdentifyFailureNotice === 0) {
+      return 0;
+    }
+    const pending = super.clearIdentifyFailures(nick);
+    const row = this.getStoredNick(nick) as ServicesNickRow;
+    this.enqueue({ kind: 'upsertNick', row });
+    return pending;
+  }
+
+  // NOTE: `isNickIdentifyFrozen` is intentionally NOT overridden. Its only
+  // mutation is pruning timestamps that have aged out of the window — a
+  // deterministic function of the stored timestamps and the clock, so a
+  // reloaded backend row re-prunes to the same state on the next check.
+  // Skipping its write keeps every read-only IDENTIFY attempt off the
+  // write-behind queue.
+
+  override addCertFP(nick: string, subject: string): boolean {
+    if (!this.isRegisteredNick(nick)) return false;
+    // Suppress the spurious write on an idempotent re-add (the subject is
+    // already attached → super is a no-op). `getNick` returns a defensive
+    // copy, so this check reflects the pre-call state. The
+    // `isRegisteredNick` guard above guarantees the nick is present, so
+    // `getNick` returns a defined record.
+    const before = this.getNick(nick);
+    const alreadyPresent = before?.certSubjects.includes(subject) === true;
+    const attached = super.addCertFP(nick, subject);
+    if (attached && !alreadyPresent) {
+      const row = this.getStoredNick(nick) as ServicesNickRow;
+      this.enqueue({ kind: 'upsertNick', row });
+    }
+    return attached;
+  }
+
+  override addCertFingerprint(nick: string, fingerprint: string): boolean {
+    if (!this.isRegisteredNick(nick)) return false;
+    // Suppress the spurious write on an idempotent re-add (the normalised
+    // fingerprint is already attached → super is a no-op). Mirrors the
+    // addCertFP override above.
+    const before = this.getNick(nick);
+    const fpId = certFingerprintId(fingerprint);
+    const alreadyPresent = before?.certSubjects.includes(fpId) === true;
+    const attached = super.addCertFingerprint(nick, fingerprint);
+    if (attached && !alreadyPresent) {
+      const row = this.getStoredNick(nick) as ServicesNickRow;
+      this.enqueue({ kind: 'upsertNick', row });
     }
-    return created;
+    return attached;
+  }
+
+  override removeCertFP(nick: string, subject: string): boolean {
+    const removed = super.removeCertFP(nick, subject);
+    if (removed) {
+      const row = this.getStoredNick(nick) as ServicesNickRow;
+      this.enqueue({ kind: 'upsertNick', row });
+    }
+    return removed;
+  }
+
+  /**
+   * Re-persists the nick row after a `verifyCertFP` first-use migration
+   * (legacy DN spelling rewrite and/or fingerprint pinning) so the
+   * upgraded binding survives a backend reload. The hook only fires for
+   * a record `verifyCertFP` just iterated, so `getStoredNick` is defined.
+   */
+  protected override onCertBindingsChanged(nick: string): void {
+    const row = this.getStoredNick(nick) as ServicesNickRow;
+    this.enqueue({ kind: 'upsertNick', row });
   }
 
   // ----- ChanServ -----
@@ -2454,7 +2793,7 @@ export interface MonitorPush {
  * (nick → set of watcher connIds) and the **online set** the actor consults
  * when synchronously resolving `MONITOR +` / `MONITOR S`.
  *
- * Mirrors the {@link MessageStore} / {@link AccountStore} pattern: the port
+ * Mirrors the {@link MessageStore} pattern: the port
  * is **synchronous** (reducers must stay pure and free of IO). The actor
  * layer drains pending pushes after each command via {@link drainPushes};
  * adapters that need to fan notifications out across processes (CF
@@ -2681,7 +3020,7 @@ export interface ServerStatsSnapshot {
 /**
  * Port that aggregates network-wide statistics for `LUSERS` and `STATS`.
  *
- * Unlike the synchronous {@link MotdProvider} / {@link AccountStore} ports
+ * Unlike the synchronous {@link MotdProvider} ports
  * (which reducers consume directly via {@link Ctx}), this port is
  * **asynchronous** (`Promise`-returning) because the aggregation crosses
  * every connection and channel in the deployment — it cannot be pre-loaded