my-durable 0.0.0-stage → 0.0.2

package/apps/dpi-playground/apps/dpi-playground-hub/src/credentials.ts

@@ -0,0 +1,265 @@
+/**
+ * Credential issuance service (spec 03 §8.1, 07 §5.2, plan P2-10).
+ *
+ * The PairingService calls issue() exactly once per approved enrollment.
+ * Everything secret is prepared in RAM first; then ONE synchronous SQLite
+ * transaction writes devices + pairings + tunnel_credentials + the audit row
+ * and only afterwards does the TokenIssue (with plaintext token) leave this
+ * process. node:sqlite is synchronous, so check/consume/commit cannot
+ * interleave in-process.
+ *
+ * - The device never chooses its registry ID: unique device_uid reuses the
+ *   existing row, fresh identities get a stripped-UUID id.
+ * - Re-pair revokes EVERY credential of the old epoch (tombstones retained)
+ *   and starts a new epoch at generation 1.
+ * - Receipt cache validation: a cached TokenIssue is only served again while
+ *   its credential is still current/previous AND its epoch is still the
+ *   active pairing. Revoked/re-paired → never return the stale secret.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import type { NetworkRegistry } from "../../../../dpi-sdk/src/node/registry.js";
+import type { Audit } from "./audit.js";
+import { observeIdentity } from "./identity.js";
+import { newTunnelToken } from "./tunnel-token.js";
+import type { TokenIssue } from "../../../../dpi-sdk/src/protocol/pairing.js";
+
+export interface IssueInput {
+  enrollmentId: string;
+  codeId: string;
+  deviceUid: string;
+  deviceName: string;
+  publicKeyPem: string;
+  keyFingerprint: string;
+  replaceKey: boolean;
+  /**
+   * `observeIdentity().stamp` the operator approved against. Re-checked inside the issuance
+   * transaction: if the identity moved since (revoke, re-pair, key replacement), nothing is issued.
+   * PairingService always supplies it; omit only for trusted in-process seeding.
+   */
+  expectedIdentity?: string;
+}
+
+export type IssueFailPoint = "preflight" | "after-prepare" | "after-commit";
+
+const UUID_CANONICAL = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+export class CredentialService {
+  constructor(
+    private readonly registry: NetworkRegistry,
+    private readonly audit: Audit,
+    private readonly hubOrigin: string,
+    private readonly hubId: string,
+    private readonly failAt?: IssueFailPoint,
+  ) {}
+
+  /**
+   * Resolve + validate identity BEFORE any mutation. Throws identity_conflict
+   * for duplicate UID rows or non-canonical UIDs (operator resolves manually).
+   */
+  private preflight(deviceUid: string): { existingRowId?: string; newId: string } {
+    if (!UUID_CANONICAL.test(deviceUid))
+      throw Object.assign(new Error(`non-canonical deviceUid ${deviceUid}`), {
+        code: "identity_conflict",
+      });
+    const rows = this.registry.db
+      .prepare("SELECT id FROM devices WHERE device_uid=?")
+      .all(deviceUid) as { id: string }[];
+    if (rows.length > 1)
+      throw Object.assign(
+        new Error(`device_uid ${deviceUid} maps to ${rows.length} rows; operator must resolve`),
+        { code: "identity_conflict" },
+      );
+    const newId = randomUUID().replace(/-/g, "");
+    if (this.registry.get(newId))
+      throw Object.assign(new Error(`registry id collision on ${newId}`), {
+        code: "identity_conflict",
+      });
+    return { existingRowId: rows[0]?.id, newId };
+  }
+
+  async issue(input: IssueInput): Promise<TokenIssue> {
+    const identity = this.preflight(input.deviceUid);
+    if (this.failAt === "preflight")
+      throw Object.assign(new Error("injected: preflight"), { code: "injected" });
+
+    // ---- prepare everything in RAM (secrets never touch the DB as plaintext)
+    const token = newTunnelToken();
+    const tokenHash = createHash("sha256").update(token).digest("hex");
+    const credentialId = randomUUID();
+    const pairingEpoch = randomUUID();
+    const now = Date.now();
+    const deviceId = identity.existingRowId ?? identity.newId;
+
+    if (this.failAt === "after-prepare")
+      throw Object.assign(new Error("injected: after-prepare"), { code: "injected" });
+
+    // ---- one synchronous transaction: identity + pairing + credential + audit
+    this.audit.withTransaction(() => {
+      // GA-05: judged inside the write lock, against what the operator actually approved.
+      const current = observeIdentity(this.registry, input.deviceUid);
+      if (input.expectedIdentity !== undefined && input.expectedIdentity !== current.stamp)
+        throw Object.assign(
+          new Error("device identity changed since approval; a new approval is required"),
+          { code: "identity_changed" },
+        );
+      const replacedKeyFingerprint =
+        current.storedFingerprint && current.storedFingerprint !== input.keyFingerprint
+          ? current.storedFingerprint
+          : undefined;
+      if (replacedKeyFingerprint && !input.replaceKey)
+        throw Object.assign(
+          new Error("a different key is on record for this device; replaceKey is required"),
+          { code: "key_replacement_required" },
+        );
+
+      if (identity.existingRowId) {
+        const row = this.registry.get(identity.existingRowId)!;
+        if (row.transport === "lan") {
+          // Converting a LAN row: identity stays, endpoint/token are cleared,
+          // and the audit row records the conversion for the operator.
+          this.registry.setTransportTunnel(identity.existingRowId);
+        } else {
+          // Re-pair over an existing tunnel row: retire the old epoch first.
+          this.registry.db
+            .prepare(
+              `UPDATE tunnel_credentials SET status='revoked', revoked_at=? WHERE device_id=? AND status IN ('current','previous','retired')`,
+            )
+            .run(now, identity.existingRowId);
+          this.registry.db
+            .prepare(
+              `UPDATE pairings SET status='revoked', updated_at=? WHERE device_id=? AND status='paired'`,
+            )
+            .run(now, identity.existingRowId);
+        }
+        this.registry.db
+          .prepare("UPDATE devices SET name=?, updated_at=? WHERE id=?")
+          .run(input.deviceName, now, identity.existingRowId);
+      } else {
+        this.registry.db
+          .prepare(
+            `INSERT INTO devices(id,name,kind,url,token,source,position,device_uid,last_status,created_at,updated_at,transport)
+             VALUES(?,?,'url',NULL,NULL,'ui',0,?,'checking',?,?,'tunnel')`,
+          )
+          .run(deviceId, input.deviceName || deviceId, input.deviceUid, now, now);
+      }
+      // pairings is one row per device (PK): upsert the CURRENT epoch.
+      this.registry.db
+        .prepare(
+          `INSERT INTO pairings(device_id,pairing_epoch,public_key,key_fingerprint,status,credential_generation,paired_at,created_at,updated_at)
+           VALUES(?,?,?,?,'paired',1,?,?,?)
+           ON CONFLICT(device_id) DO UPDATE SET pairing_epoch=excluded.pairing_epoch,
+             public_key=excluded.public_key, key_fingerprint=excluded.key_fingerprint,
+             status='paired', credential_generation=1, paired_at=excluded.paired_at, updated_at=excluded.updated_at,
+             rotation_id=NULL, rotation_target_credential_id=NULL, rotation_started_at=NULL, rotation_requested_at=NULL`,
+        )
+        .run(deviceId, pairingEpoch, input.publicKeyPem, input.keyFingerprint, now, now, now);
+      this.registry.db
+        .prepare(
+          `INSERT INTO tunnel_credentials(credential_id,device_id,pairing_epoch,generation,token_hash,status,created_at)
+           VALUES(?,?,?,1,?,'current',?)`,
+        )
+        .run(credentialId, deviceId, pairingEpoch, tokenHash, now);
+      this.audit.append({
+        actor: "hub",
+        action: "pair.success",
+        outcome: "ok",
+        detail: {
+          codeId: input.codeId,
+          enrollmentId: input.enrollmentId,
+          deviceId,
+          pairingEpoch,
+          credentialId,
+          keyFingerprint: input.keyFingerprint,
+          replaceKey: input.replaceKey,
+          ...(replacedKeyFingerprint ? { replacedKeyFingerprint } : {}),
+        },
+      });
+    });
+
+    if (this.failAt === "after-commit")
+      throw Object.assign(new Error("injected: after-commit"), { code: "injected" });
+
+    // Response precomputed above; returned only after the commit succeeded.
+    return {
+      type: "pair.token",
+      v: 1,
+      enrollmentId: input.enrollmentId,
+      deviceUid: input.deviceUid,
+      deviceId,
+      pairingEpoch,
+      credentialId,
+      generation: 1,
+      hubId: this.hubId,
+      hubOrigin: this.hubOrigin,
+      hubUrl: `${this.hubOrigin}/api/tunnel`,
+      tunnelToken: token,
+      issuedAt: now,
+      expiresAt: null,
+    };
+  }
+
+  /**
+   * Durable revoke (03 §8.3, P2-20): pairing paired→revoked, EVERY credential
+   * hash (current/previous/retired) → revoked with tombstones retained, one
+   * audit row, all in ONE transaction. The caller is responsible for cutting
+   * the live transport right after commit — authorization is already dead:
+   * the upgrade path consults these rows directly, so a revoked bearer is
+   * 401 within the same tick, notice ACK or not.
+   */
+  revoke(deviceId: string, reason: "user" | "compromise" | "hub_migrated", actor: string): void {
+    const now = Date.now();
+    const pairing = this.registry.db
+      .prepare("SELECT pairing_epoch, status FROM pairings WHERE device_id=?")
+      .get(deviceId) as { pairing_epoch: string; status: string } | undefined;
+    if (!pairing || pairing.status !== "paired")
+      throw Object.assign(new Error(`No active pairing for ${deviceId}`), { status: 404 });
+    this.audit.withTransaction(() => {
+      this.registry.db
+        .prepare("UPDATE pairings SET status='revoked', updated_at=? WHERE device_id=?")
+        .run(now, deviceId);
+      this.registry.db
+        .prepare(
+          "UPDATE tunnel_credentials SET status='revoked', revoked_at=? WHERE device_id=? AND status IN ('current','previous','retired')",
+        )
+        .run(now, deviceId);
+      this.registry.db.prepare("DELETE FROM tunnel_state WHERE device_id=?").run(deviceId);
+      this.audit.append({
+        actor,
+        action: "pair.revoke",
+        outcome: "ok",
+        detail: { deviceId, pairingEpoch: pairing.pairing_epoch, reason },
+      });
+    });
+  }
+
+  /**
+   * A cached TokenIssue may only be replayed while its credential is still
+   * current/previous AND its epoch is the active pairing. Never return a
+   * revoked or superseded secret just because the receipt TTL is still open.
+   */
+  receiptStillValid(
+    tokenIssue: Pick<TokenIssue, "credentialId" | "pairingEpoch" | "deviceId">,
+  ): boolean {
+    const cred = this.registry.db
+      .prepare("SELECT status FROM tunnel_credentials WHERE credential_id=?")
+      .get(tokenIssue.credentialId) as { status: string } | undefined;
+    if (!cred || !["current", "previous"].includes(cred.status)) return false;
+    const pairing = this.registry.db
+      .prepare("SELECT status, pairing_epoch FROM pairings WHERE device_id=?")
+      .get(tokenIssue.deviceId) as { status: string; pairing_epoch: string } | undefined;
+    return (
+      !!pairing && pairing.status === "paired" && pairing.pairing_epoch === tokenIssue.pairingEpoch
+    );
+  }
+
+  /** Which failure to surface for a stale receipt. */
+  receiptFailure(
+    tokenIssue: Pick<TokenIssue, "pairingEpoch" | "deviceId">,
+  ): "paired_elsewhere" | "invalid" {
+    const pairing = this.registry.db
+      .prepare("SELECT status, pairing_epoch FROM pairings WHERE device_id=?")
+      .get(tokenIssue.deviceId) as { status: string; pairing_epoch: string } | undefined;
+    if (pairing && pairing.pairing_epoch !== tokenIssue.pairingEpoch) return "paired_elsewhere";
+    return "invalid";
+  }
+}

package/apps/dpi-playground/apps/dpi-playground-hub/src/guard.ts

@@ -0,0 +1,43 @@
+import type { RequestHandler } from "express";
+import { viaTls } from "./client-ip.js";
+
+const err = (code: string, message: string) => ({ error: { code, message } });
+
+/**
+ * The hub holds every device token and has no login of its own, so it only answers requests
+ * whose Host is one it serves (blocks DNS rebinding) from its own origin (blocks CSRF), and
+ * only accepts JSON writes (forces a CORS preflight that cross-origin pages cannot pass).
+ */
+export function guard(allowedHosts: Set<string>): RequestHandler {
+  return (req, res, next) => {
+    const host = (req.headers.host ?? "").toLowerCase();
+    if (!allowedHosts.has(host))
+      return void res.status(421).json(err("invalid", `Unknown Host header: ${host}`));
+    const origin = req.headers.origin;
+    if (origin) {
+      let originHost = "";
+      try {
+        originHost = new URL(origin).host.toLowerCase();
+      } catch {}
+      if (originHost !== host)
+        return void res
+          .status(403)
+          .json(err("unauthorized", "Cross-origin requests are not allowed"));
+    }
+    if (["POST", "PUT", "PATCH"].includes(req.method) && !req.is("application/json"))
+      return void res.status(415).json(err("invalid", "JSON required"));
+    next();
+  };
+}
+
+/**
+ * Second line behind the TLS proxy (spec 05 §4.2): refuse whatever cannot show it came through it
+ * over TLS. A plain-HTTP request, a LAN peer that sets its own X-Forwarded-Proto and a local process
+ * that skipped the proxy all end here instead of being served as if they were secure.
+ */
+export function requireTls(): RequestHandler {
+  return (req, res, next) => {
+    if (viaTls(req)) return void next();
+    res.status(403).json(err("tls_required", "This hub is only served over HTTPS"));
+  };
+}

package/apps/dpi-playground/apps/dpi-playground-hub/src/http-errors.ts

@@ -0,0 +1,156 @@
+/**
+ * One error contract for the whole HTTP surface: `{ error: { code, message } }` with a stable
+ * code and a short message. Framework error pages (stack frames, module paths, absolute paths)
+ * never reach a client, and an unexpected fault is a generic 500 whose detail stays in the log.
+ */
+import type { ErrorRequestHandler, Request, RequestHandler, Response } from "express";
+import { AuditUnavailableError, scrubSecrets } from "./audit.js";
+
+export interface HttpFailure {
+  status: number;
+  code: string;
+  message: string;
+}
+
+const CODE_BY_STATUS: Record<number, string> = {
+  400: "invalid",
+  401: "unauthorized",
+  403: "forbidden",
+  404: "not_found",
+  405: "method_not_allowed",
+  409: "conflict",
+  410: "gone",
+  413: "payload_too_large",
+  415: "unsupported_media_type",
+  421: "misdirected",
+  429: "rate_limited",
+};
+
+const MESSAGE_BY_STATUS: Record<number, string> = {
+  400: "Bad request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not found",
+  405: "Method not allowed",
+  409: "Conflict",
+  410: "Gone",
+  413: "Request body is too large",
+  415: "Unsupported media type",
+  421: "Misdirected request",
+  429: "Too many requests; slow down",
+};
+
+const MESSAGE_MAX = 200;
+const LOG_INTERVAL_MS = 10_000;
+let loggedAt = 0;
+
+interface Thrown {
+  status?: unknown;
+  statusCode?: unknown;
+  type?: unknown;
+  expose?: unknown;
+  message?: unknown;
+}
+
+const clientStatus = (n: unknown): number | undefined =>
+  typeof n === "number" && Number.isInteger(n) && n >= 400 && n <= 499 ? n : undefined;
+
+/**
+ * Map anything thrown to a client-safe failure.
+ *
+ * - Audit storage refusal → 503 `audit_unavailable`.
+ * - Body-parser / router / static errors (they carry `type` or `expose`) → fixed text per cause or
+ *   status, never the library's own message.
+ * - Errors our code raises on purpose with a 4xx `status` → their (short, scrubbed) message.
+ * - Anything else → `plainStatus`: a 4xx keeps the message (handlers that validate input by
+ *   throwing); the default 500 hides it and logs it.
+ */
+export function describeFailure(e: unknown, plainStatus = 500): HttpFailure {
+  if (e instanceof AuditUnavailableError)
+    return {
+      status: 503,
+      code: "audit_unavailable",
+      message: "Audit storage is unavailable; the change was not applied",
+    };
+
+  const t = (e && typeof e === "object" ? e : {}) as Thrown;
+  switch (t.type) {
+    case "entity.parse.failed":
+    case "entity.verify.failed":
+      return { status: 400, code: "invalid_json", message: "Request body is not valid JSON" };
+    case "entity.too.large":
+      return { status: 413, code: "payload_too_large", message: MESSAGE_BY_STATUS[413]! };
+    case "charset.unsupported":
+    case "encoding.unsupported":
+      return {
+        status: 415,
+        code: "unsupported_media_type",
+        message: "Unsupported request encoding",
+      };
+    case "request.aborted":
+    case "request.size.invalid":
+    case "parameters.too.many":
+      return { status: 400, code: "invalid", message: "Request body could not be read" };
+  }
+
+  const status = clientStatus(t.status) ?? clientStatus(t.statusCode);
+  // body-parser/send/http-errors set `type` or `expose`; the router flags an undecodable path param as a URIError.
+  const fromFramework =
+    typeof t.type === "string" || typeof t.expose === "boolean" || e instanceof URIError;
+  if (status && fromFramework)
+    return {
+      status,
+      code: CODE_BY_STATUS[status] ?? "invalid",
+      message: MESSAGE_BY_STATUS[status] ?? MESSAGE_BY_STATUS[400]!,
+    };
+
+  const own = status ?? clientStatus(plainStatus);
+  if (own) {
+    const text =
+      typeof t.message === "string" && t.message
+        ? t.message
+        : (MESSAGE_BY_STATUS[own] ?? "Bad request");
+    const code = own === 404 ? "not_found" : (CODE_BY_STATUS[own] ?? "invalid");
+    return {
+      status: own,
+      code: own === 400 ? "invalid" : code,
+      message: scrubSecrets(text).slice(0, MESSAGE_MAX),
+    };
+  }
+
+  logUnexpected(e);
+  return { status: 500, code: "internal", message: "Internal error" };
+}
+
+function logUnexpected(e: unknown): void {
+  const now = Date.now();
+  if (now - loggedAt < LOG_INTERVAL_MS) return;
+  loggedAt = now;
+  const text = e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+  console.error(`hub: unhandled request error: ${scrubSecrets(text).slice(0, MESSAGE_MAX)}`);
+}
+
+export const body = (f: HttpFailure) => ({ error: { code: f.code, message: f.message } });
+
+/**
+ * Wrap a route handler so that whatever it throws is answered in the contract above. A handler
+ * that rejects on purpose carries a 4xx `status`; any other throw is our fault, so it is a 500.
+ */
+export const safe =
+  (fn: (req: Request, res: Response) => unknown): RequestHandler =>
+  async (req, res) => {
+    try {
+      await fn(req, res);
+    } catch (e) {
+      if (res.headersSent) return;
+      const failure = describeFailure(e);
+      res.status(failure.status).json(body(failure));
+    }
+  };
+
+/** Last middleware: every error that reaches it is answered in the contract above. */
+export const errorMiddleware: ErrorRequestHandler = (e, _req, res, next) => {
+  if (res.headersSent) return next(e); // too late for a body; Express closes the socket
+  const f = describeFailure(e);
+  res.status(f.status).json(body(f));
+};

package/apps/dpi-playground/apps/dpi-playground-hub/src/identity.ts

@@ -0,0 +1,60 @@
+/**
+ * The registry's view of one device UID, shared by the approval gate (PairingService) and the
+ * issuance transaction (CredentialService) so both judge "has this identity changed?" the same way.
+ *
+ * A revoked pairing keeps its key (spec 03 §8.3), so the stored key is read in ANY pairing state:
+ * a different key after a revoke is still a key replacement and needs the operator's replaceKey.
+ */
+import { createHash, createPublicKey } from "node:crypto";
+import type { NetworkRegistry } from "../../../../dpi-sdk/src/node/registry.js";
+
+export interface IdentityObservation {
+  /**
+   * Opaque digest of every registry fact an approval depends on (device row, pairing epoch,
+   * pairing status, stored key). It is compared verbatim again inside the issuance transaction:
+   * any change in between (revoke, re-pair, key replacement, a second enrollment) voids the approval.
+   */
+  stamp: string;
+  /** Fingerprint of the key on record for this UID in any pairing state; absent when none exists. */
+  storedFingerprint?: string;
+}
+
+interface Row {
+  id: string;
+  epoch: string | null;
+  status: string | null;
+  publicKey: string | null;
+  keyFingerprint: string | null;
+}
+
+/** SPKI fingerprint recomputed from the stored PEM, so a formatting difference is not a key change. */
+function fingerprintOfStoredKey(row: Row): string | undefined {
+  if (row.publicKey === null) return undefined;
+  try {
+    const der = createPublicKey(row.publicKey).export({ format: "der", type: "spki" }) as Buffer;
+    return `sha256:${createHash("sha256").update(der).digest("hex")}`;
+  } catch {
+    return (
+      row.keyFingerprint ??
+      `unparseable:${createHash("sha256").update(row.publicKey).digest("hex")}`
+    );
+  }
+}
+
+export function observeIdentity(registry: NetworkRegistry, deviceUid: string): IdentityObservation {
+  const rows = registry.db
+    .prepare(
+      `SELECT d.id AS id, p.pairing_epoch AS epoch, p.status AS status, p.public_key AS publicKey,
+              p.key_fingerprint AS keyFingerprint
+         FROM devices d LEFT JOIN pairings p ON p.device_id = d.id
+        WHERE d.device_uid=? ORDER BY d.id`,
+    )
+    .all(deviceUid) as unknown as Row[];
+  const fingerprints = rows.map(fingerprintOfStoredKey);
+  const stamp = createHash("sha256")
+    .update(JSON.stringify(rows.map((r, i) => [r.id, r.epoch, r.status, fingerprints[i] ?? null])))
+    .digest("hex");
+  // Several rows for one UID is an operator-resolved conflict (CredentialService preflight): no single stored key.
+  const storedFingerprint = rows.length === 1 ? fingerprints[0] : undefined;
+  return { stamp, ...(storedFingerprint ? { storedFingerprint } : {}) };
+}

package/apps/dpi-playground/apps/dpi-playground-hub/src/limiter.ts

@@ -0,0 +1,165 @@
+/**
+ * Bounded per-key limiters (spec 05 §4.3): at most `maxKeys` keys, an idle TTL, and a full table
+ * refuses NEW keys. A live counter is never evicted to make room — doing so would hand an attacker
+ * who can mint many keys (IPv6 sources) a free quota reset for any key they want to attack.
+ *
+ * The only entries reclaimed early are the ones whose loss is invisible: a token bucket that has
+ * refilled to capacity is indistinguishable from a brand-new one.
+ */
+
+const FULL_RETRY_MS = 60_000;
+/** A full table is scanned at most this often, so a flood of new keys cannot turn each request into an O(n) walk. */
+const RECLAIM_MIN_INTERVAL_MS = 1_000;
+const WINDOW_ENTRIES_PER_KEY = 1_024;
+
+export interface BucketPolicy {
+  capacity: number;
+  perMinute: number;
+  maxKeys: number;
+  /** A key untouched this long is forgotten. */
+  idleTtlMs: number;
+}
+
+export type Take = { ok: true } | { ok: false; reason: "limited" | "full"; retryAfterMs: number };
+
+interface Bucket {
+  /** Tokens held right after the last ACCEPTED request. */
+  tokens: number;
+  /** Time of the last accepted request; refill is measured from here, never from a refusal. */
+  last: number;
+  touched: number;
+}
+
+export class TokenBuckets {
+  private readonly map = new Map<string, Bucket>();
+  private lastReclaim = Number.NEGATIVE_INFINITY;
+
+  constructor(
+    private readonly policy: BucketPolicy,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  size(): number {
+    return this.map.size;
+  }
+
+  take(key: string): Take {
+    const t = this.now();
+    let b = this.map.get(key);
+    if (b && t - b.touched >= this.policy.idleTtlMs) {
+      this.map.delete(key);
+      b = undefined;
+    }
+    if (!b) {
+      if (this.map.size >= this.policy.maxKeys) this.reclaim(t);
+      if (this.map.size >= this.policy.maxKeys)
+        return { ok: false, reason: "full", retryAfterMs: FULL_RETRY_MS };
+      b = { tokens: this.policy.capacity, last: t, touched: t };
+      this.map.set(key, b);
+    }
+    const have = this.available(b, t);
+    b.touched = t;
+    if (have < 1) {
+      const retryAfterMs = Math.ceil(((1 - have) / this.policy.perMinute) * 60_000);
+      return { ok: false, reason: "limited", retryAfterMs: Math.max(1, retryAfterMs) };
+    }
+    b.tokens = have - 1;
+    b.last = t;
+    return { ok: true };
+  }
+
+  /** Forget keys idle for the TTL (housekeeping timer; lookups also honour the TTL). */
+  sweep(): void {
+    const t = this.now();
+    for (const [key, b] of this.map)
+      if (t - b.touched >= this.policy.idleTtlMs) this.map.delete(key);
+  }
+
+  /**
+   * Tokens `b` holds at `t`. Pure: a refused request must not move `last`, or a client that keeps
+   * knocking would shave a rounding crumb off its own refill each time. Multiply before dividing so
+   * a whole refill interval comes out as exactly 1.
+   */
+  private available(b: Bucket, t: number): number {
+    const elapsed = Math.max(0, t - b.last);
+    return Math.min(this.policy.capacity, b.tokens + (elapsed * this.policy.perMinute) / 60_000);
+  }
+
+  private reclaim(t: number): void {
+    if (t - this.lastReclaim < RECLAIM_MIN_INTERVAL_MS) return;
+    this.lastReclaim = t;
+    for (const [key, b] of this.map) {
+      const idle = t - b.touched >= this.policy.idleTtlMs;
+      const refilled = this.available(b, t) >= this.policy.capacity;
+      if (idle || refilled) this.map.delete(key);
+    }
+  }
+}
+
+export interface WindowPolicy {
+  windowMs: number;
+  maxKeys: number;
+}
+
+/** Sliding-window event counter per key, with the same bounds and the same full-table rule. */
+export class SlidingWindows {
+  private readonly map = new Map<string, number[]>();
+  private lastReclaim = Number.NEGATIVE_INFINITY;
+
+  constructor(
+    private readonly policy: WindowPolicy,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  size(): number {
+    return this.map.size;
+  }
+
+  /** Events for `key` inside the window. */
+  count(key: string): number {
+    const list = this.map.get(key);
+    if (!list) return 0;
+    const live = this.prune(key, list, this.now());
+    return live.length;
+  }
+
+  /** False when `key` is new and the table is full: the event could not be tracked. */
+  record(key: string): boolean {
+    const t = this.now();
+    const known = this.map.get(key);
+    const list = known ? this.prune(key, known, t) : [];
+    if (!this.map.has(key)) {
+      if (this.map.size >= this.policy.maxKeys) this.reclaim(t);
+      if (this.map.size >= this.policy.maxKeys) return false;
+    }
+    // Past the cap the oldest entries are kept: the key stays over any sane threshold until they expire.
+    if (list.length < WINDOW_ENTRIES_PER_KEY) list.push(t);
+    this.map.set(key, list);
+    return true;
+  }
+
+  /** A key the table has no room to track (callers fail closed for it). */
+  saturatedFor(key: string): boolean {
+    if (this.map.has(key) || this.map.size < this.policy.maxKeys) return false;
+    this.reclaim(this.now());
+    return this.map.size >= this.policy.maxKeys;
+  }
+
+  sweep(): void {
+    const t = this.now();
+    for (const [key, list] of this.map) this.prune(key, list, t);
+  }
+
+  private prune(key: string, list: number[], t: number): number[] {
+    const live = list.filter((ts) => t - ts < this.policy.windowMs);
+    if (live.length === 0) this.map.delete(key);
+    else if (live.length !== list.length) this.map.set(key, live);
+    return live;
+  }
+
+  private reclaim(t: number): void {
+    if (t - this.lastReclaim < RECLAIM_MIN_INTERVAL_MS) return;
+    this.lastReclaim = t;
+    for (const [key, list] of this.map) this.prune(key, list, t);
+  }
+}