@mandujs/core 0.21.0 → 0.22.0

package/src/id/__tests__/id.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect } from "bun:test";
+import { newId, newShortId, _resolveGenerator } from "../index";
+
+const UUID_REGEX =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const HEX8_REGEX = /^[0-9a-f]{8}$/i;
+
+interface CryptoLike {
+  randomUUIDv7?: () => string;
+  randomUUID: () => string;
+}
+
+describe("@mandujs/core/id — newId", () => {
+  it("returns a canonical UUID string", () => {
+    const id = newId();
+    expect(id).toMatch(UUID_REGEX);
+    expect(id.length).toBe(36);
+  });
+
+  it("returns distinct values across calls", () => {
+    const seen = new Set<string>();
+    for (let i = 0; i < 1000; i++) {
+      seen.add(newId());
+    }
+    expect(seen.size).toBe(1000);
+  });
+
+  it("is monotonic: lexicographic sort preserves generation order (v7 property)", async () => {
+    // Skip this invariant if neither global exposes v7 — the v4 fallback is
+    // correctly non-monotonic by design.
+    const c = globalThis.crypto as unknown as CryptoLike;
+    const bun = (globalThis as unknown as { Bun?: { randomUUIDv7?: () => string } }).Bun;
+    const v7Available =
+      typeof c.randomUUIDv7 === "function" ||
+      (bun !== undefined && typeof bun.randomUUIDv7 === "function");
+    if (!v7Available) {
+      return;
+    }
+
+    const generated: string[] = [];
+    for (let i = 0; i < 1000; i++) {
+      generated.push(newId());
+      // Force sub-millisecond spread across a few ticks so the time component
+      // advances at least once during the run. UUID v7 counter handles
+      // intra-millisecond monotonicity on its own.
+      if (i % 200 === 0) {
+        await new Promise((r) => setTimeout(r, 1));
+      }
+    }
+
+    const sorted = [...generated].sort();
+
+    // Require overall monotonic trend: the full sorted list equals the
+    // generation order. Bun's v7 implementation uses a per-millisecond
+    // monotonic counter, so ties within the same ms remain ordered.
+    expect(sorted).toEqual(generated);
+  });
+});
+
+describe("@mandujs/core/id — newShortId", () => {
+  it("returns exactly 8 hex characters", () => {
+    const short = newShortId();
+    expect(short).toMatch(HEX8_REGEX);
+    expect(short.length).toBe(8);
+  });
+
+  it("matches the prefix of the underlying UUID", () => {
+    // The short form is defined as the first 8 chars of the full ID, which is
+    // the first hex group of the UUID (pre-hyphen).
+    for (let i = 0; i < 50; i++) {
+      const short = newShortId();
+      expect(short).not.toContain("-");
+    }
+  });
+});
+
+describe("@mandujs/core/id — generator resolution", () => {
+  it("prefers crypto.randomUUIDv7 when present", () => {
+    const sentinel = "01912345-6789-7abc-def0-123456789abc";
+    const fakeCrypto = {
+      randomUUIDv7: () => sentinel,
+      randomUUID: () => "00000000-0000-4000-8000-000000000000",
+    };
+    const fakeBun = { randomUUIDv7: () => "SHOULD_NOT_BE_CALLED" };
+    const gen = _resolveGenerator(fakeCrypto, fakeBun);
+    expect(gen()).toBe(sentinel);
+  });
+
+  it("uses Bun.randomUUIDv7 when crypto.randomUUIDv7 is absent", () => {
+    const sentinel = "01abcdef-0123-7456-8789-abcdef012345";
+    const fakeCrypto = {
+      randomUUID: () => "00000000-0000-4000-8000-000000000000",
+    };
+    const fakeBun = { randomUUIDv7: () => sentinel };
+    const gen = _resolveGenerator(fakeCrypto, fakeBun);
+    expect(gen()).toBe(sentinel);
+  });
+
+  it("falls back to crypto.randomUUID when neither v7 source is available", () => {
+    const fakeCrypto = {
+      // No randomUUIDv7 — force fallback.
+      randomUUID: () => "00000000-0000-4000-8000-000000000000",
+    };
+    const fakeBun = {}; // also no randomUUIDv7
+    const gen = _resolveGenerator(fakeCrypto, fakeBun);
+    const id = gen();
+    expect(id).toMatch(UUID_REGEX);
+    expect(id.length).toBe(36);
+  });
+
+  it("falls back to crypto.randomUUID when Bun stub lacks randomUUIDv7", () => {
+    const fakeCrypto = {
+      randomUUID: () => "11111111-1111-4111-8111-111111111111",
+    };
+    // Pass an empty stub explicitly rather than `undefined` (which would
+    // trigger the default-parameter fallback to the real Bun global).
+    const gen = _resolveGenerator(fakeCrypto, {});
+    expect(gen()).toBe("11111111-1111-4111-8111-111111111111");
+  });
+});

package/src/id/index.ts

@@ -0,0 +1,105 @@
+/**
+ * @mandujs/core/id
+ *
+ * Centralized ID generation utilities.
+ *
+ * Uses `crypto.randomUUIDv7()` when available (Bun 1.3+) so that generated IDs
+ * are time-ordered — lexicographic string sort matches chronological creation
+ * order. This makes v7 UUIDs ideal for log correlation, database primary keys,
+ * and any context where sortability is useful.
+ *
+ * On older runtimes we fall back to `crypto.randomUUID()` (v4). The fallback
+ * emits a single dev-only warning so integrators notice the reduced guarantee,
+ * and remains silent in production.
+ */
+
+interface CryptoWithUUIDv7 {
+  randomUUIDv7?: () => string;
+  randomUUID: () => string;
+}
+
+interface BunWithUUIDv7 {
+  randomUUIDv7?: () => string;
+}
+
+const FALLBACK_WARNING =
+  "[@mandujs/core/id] randomUUIDv7 is unavailable — falling back to randomUUID (v4). IDs will not be time-ordered. Upgrade to Bun >= 1.3 for v7 support.";
+
+let fallbackWarned = false;
+
+function getCrypto(): CryptoWithUUIDv7 {
+  // `crypto` is available globally in Bun, Node 20+, Deno, and modern browsers.
+  // We type-assert via the narrow interface we actually use.
+  return globalThis.crypto as unknown as CryptoWithUUIDv7;
+}
+
+function getBun(): BunWithUUIDv7 | undefined {
+  // `Bun` is only present when running under the Bun runtime. Access via
+  // a dynamic lookup so the module stays importable in Node / browsers.
+  const g = globalThis as unknown as { Bun?: BunWithUUIDv7 };
+  return g.Bun;
+}
+
+function warnFallbackOnce(): void {
+  if (fallbackWarned) return;
+  fallbackWarned = true;
+  if (
+    typeof process !== "undefined" &&
+    process.env &&
+    process.env.NODE_ENV !== "production"
+  ) {
+    console.warn(FALLBACK_WARNING);
+  }
+}
+
+/**
+ * Resolves the concrete UUID generator function once per call. Exported
+ * internally so tests can validate the resolution order without monkey
+ * patching non-configurable globals.
+ *
+ * @internal
+ */
+export function _resolveGenerator(
+  c: CryptoWithUUIDv7 = getCrypto(),
+  bun: BunWithUUIDv7 | undefined = getBun(),
+): () => string {
+  if (typeof c.randomUUIDv7 === "function") {
+    return c.randomUUIDv7.bind(c);
+  }
+  if (bun && typeof bun.randomUUIDv7 === "function") {
+    return bun.randomUUIDv7.bind(bun);
+  }
+  warnFallbackOnce();
+  return c.randomUUID.bind(c);
+}
+
+/**
+ * Generates a UUID v7 — a time-ordered UUID whose string sort matches
+ * chronological order.
+ *
+ * Resolution order:
+ *   1. `crypto.randomUUIDv7()` — web standard, Node 24+, newer Bun
+ *   2. `Bun.randomUUIDv7()`    — Bun 1.3+ runtime API
+ *   3. `crypto.randomUUID()`   — v4 fallback (non-monotonic)
+ *
+ * The fallback path emits a one-time warning in dev mode.
+ *
+ * @returns A 36-character UUID string in canonical 8-4-4-4-12 form.
+ */
+export function newId(): string {
+  return _resolveGenerator()();
+}
+
+/**
+ * First 8 hex characters of a UUID v7 — suitable for log correlation IDs
+ * where collision risk is acceptable within a single request lifetime.
+ *
+ * Because v7 encodes the timestamp in its high bits, two short IDs generated
+ * within the same millisecond share a prefix; this is normal and expected.
+ * For strong uniqueness use {@link newId} instead.
+ *
+ * @returns Exactly 8 lowercase hex characters.
+ */
+export function newShortId(): string {
+  return newId().slice(0, 8);
+}

package/src/kitchen/index.ts

@@ -5,8 +5,8 @@
  * and architecture guard dashboard at /__kitchen.
  */
 
-export { KitchenHandler, KITCHEN_PREFIX, getKitchenErrors, clearKitchenErrors } from "./kitchen-handler";
-export type { KitchenOptions } from "./kitchen-handler";
+export { KitchenHandler, KITCHEN_PREFIX, getKitchenErrors, clearKitchenErrors, computeAgentStats } from "./kitchen-handler";
+export type { KitchenOptions, AgentStats, AgentStatsResponse } from "./kitchen-handler";
 export { ActivitySSEBroadcaster } from "./stream/activity-sse";
 export { FileTailer } from "./stream/file-tailer";
 export { GuardAPI } from "./api/guard-api";

package/src/kitchen/kitchen-handler.ts

@@ -93,6 +93,87 @@ function parseWindow(input: string): number {
   }
 }
 
+// ========== Per-Agent Stats ==========
+
+export interface AgentStats {
+  toolCalls: number;
+  failures: number;
+  topTools: Array<{ tool: string; count: number }>;
+  avgDuration: number;
+  firstSeen: number;
+  lastSeen: number;
+}
+
+export interface AgentStatsResponse {
+  agents: Record<string, AgentStats>;
+  totalAgents: number;
+  totalEvents: number;
+}
+
+/**
+ * Aggregate recent MCP events by sessionId to produce per-agent usage stats.
+ * Events without a sessionId are grouped under "unknown".
+ */
+export function computeAgentStats(): AgentStatsResponse {
+  const events = eventBus.getRecent(500, { type: "mcp" });
+  const agents: Record<string, AgentStats> = {};
+  const toolCounts: Record<string, Map<string, number>> = {};
+  const durations: Record<string, number[]> = {};
+
+  for (const e of events) {
+    const data = (e.data ?? {}) as Record<string, unknown>;
+    const sessionId = typeof data.sessionId === "string" && data.sessionId
+      ? data.sessionId
+      : "unknown";
+
+    let agent = agents[sessionId];
+    if (!agent) {
+      agent = {
+        toolCalls: 0,
+        failures: 0,
+        topTools: [],
+        avgDuration: 0,
+        firstSeen: e.timestamp,
+        lastSeen: e.timestamp,
+      };
+      agents[sessionId] = agent;
+      toolCounts[sessionId] = new Map();
+      durations[sessionId] = [];
+    }
+
+    agent.toolCalls++;
+    if (e.severity === "error") agent.failures++;
+    if (e.timestamp < agent.firstSeen) agent.firstSeen = e.timestamp;
+    if (e.timestamp > agent.lastSeen) agent.lastSeen = e.timestamp;
+
+    const tool = typeof data.tool === "string" && data.tool
+      ? data.tool
+      : e.source || "unknown";
+    toolCounts[sessionId].set(tool, (toolCounts[sessionId].get(tool) ?? 0) + 1);
+
+    if (typeof e.duration === "number") {
+      durations[sessionId].push(e.duration);
+    }
+  }
+
+  for (const [sessionId, agent] of Object.entries(agents)) {
+    agent.topTools = Array.from(toolCounts[sessionId].entries())
+      .map(([tool, count]) => ({ tool, count }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 5);
+    const ds = durations[sessionId];
+    agent.avgDuration = ds.length
+      ? ds.reduce((a, b) => a + b, 0) / ds.length
+      : 0;
+  }
+
+  return {
+    agents,
+    totalAgents: Object.keys(agents).length,
+    totalEvents: events.length,
+  };
+}
+
 export class KitchenHandler {
   private sse: ActivitySSEBroadcaster;
   private guardAPI: GuardAPI;
@@ -271,6 +352,11 @@ export class KitchenHandler {
       return Response.json({ events });
     }
 
+    // Agent Stats API — per-agent (sessionId) aggregation of MCP events
+    if (sub === "/api/agent-stats" && req.method === "GET") {
+      return Response.json(computeAgentStats());
+    }
+
     // Cache API — cache store stats
     if ((sub === "/api/cache" || sub === "/api/cache-stats") && req.method === "GET") {
       const store = getGlobalCache();

package/src/kitchen/stream/activity-sse.ts

@@ -9,6 +9,7 @@
 
 import path from "path";
 import { FileTailer } from "./file-tailer";
+import { newId } from "../../id";
 
 interface SSEClient {
   id: string;
@@ -82,7 +83,7 @@ export class ActivitySSEBroadcaster {
 
   /** Create an SSE Response for a new client connection */
   createResponse(): Response {
-    const clientId = crypto.randomUUID();
+    const clientId = newId();
 
     const stream = new ReadableStream<Uint8Array>({
       start: (controller) => {

package/src/middleware/csrf.ts

@@ -0,0 +1,328 @@
+/**
+ * CSRF Middleware Plugin
+ *
+ * Double-submit cookie pattern (stateless, no session required).
+ *
+ *   cookie:  __csrf=<token>
+ *   header:  x-csrf-token: <token>   (or form field _csrf)
+ *
+ * Both values MUST match AND the token's HMAC signature MUST verify.
+ *
+ * Internally delegates to `Bun.CSRF.generate` / `Bun.CSRF.verify` when
+ * available (Bun ≥ 1.3). Verified present and stable in Bun 1.3.10:
+ *   Bun.CSRF.generate(secret, { maxAge? }) → URL-safe base64 token
+ *   Bun.CSRF.verify(token, { secret, maxAge? }) → boolean
+ *
+ * A pure `crypto.subtle` + `crypto.getRandomValues` fallback is provided for
+ * compatibility. The exported `csrf()` API is identical either way.
+ *
+ * @example
+ * ```ts
+ * import { csrf } from "@mandujs/core/middleware";
+ *
+ * export default Mandu.filling()
+ *   .use(csrf({ secret: process.env.CSRF_SECRET! }))
+ *   .post((ctx) => ctx.ok({ ok: true }));
+ * ```
+ */
+import type { ManduContext, CookieOptions } from "../filling/context";
+
+// ========== Types ==========
+
+export interface CsrfMiddlewareOptions {
+  /** Required. Used to HMAC-sign CSRF tokens. */
+  secret: string;
+  /** Cookie name. Default: "__csrf". */
+  cookieName?: string;
+  /** Header name checked on unsafe methods. Default: "x-csrf-token". */
+  headerName?: string;
+  /** Form field name checked as fallback. Default: "_csrf". */
+  fieldName?: string;
+  /** Methods that skip validation. Default: ["GET","HEAD","OPTIONS"]. */
+  safeMethods?: string[];
+  /** Cookie attribute overrides (merged with sensible defaults). */
+  cookieOptions?: {
+    /** Default: false — client JS needs to read the token to submit it in a header. */
+    httpOnly?: boolean;
+    /** Default: NODE_ENV === "production". */
+    secure?: boolean;
+    /** Default: "lax". */
+    sameSite?: "strict" | "lax" | "none";
+    /** Default: "/". */
+    path?: string;
+    /** Default: 86400 (1 day). */
+    maxAge?: number;
+    /** Optional cookie domain. */
+    domain?: string;
+  };
+}
+
+/** Middleware signature matching `jwt.ts`. */
+type Middleware = (ctx: ManduContext) => Promise<Response | void>;
+
+// ========== Implementation ==========
+
+const DEFAULT_COOKIE_NAME = "__csrf";
+const DEFAULT_HEADER_NAME = "x-csrf-token";
+const DEFAULT_FIELD_NAME = "_csrf";
+const DEFAULT_SAFE_METHODS: readonly string[] = ["GET", "HEAD", "OPTIONS"];
+const DEFAULT_MAX_AGE = 86400; // 1 day
+/** Guard against memory-exhaustion attacks via oversized tokens. */
+const MAX_TOKEN_LENGTH = 512;
+
+/**
+ * CSRF protection middleware (double-submit cookie pattern).
+ *
+ * Behavior:
+ *  1. Ensures a signed CSRF token cookie is present. Issues a fresh one if
+ *     the existing cookie is missing or its signature fails to verify.
+ *  2. For safe methods (GET/HEAD/OPTIONS): continues without further checks.
+ *  3. For unsafe methods: reads the submitted token from the configured
+ *     header (preferred) or form field (fallback for form content types),
+ *     then confirms:
+ *       (a) submitted token === cookie token (constant-time equality)
+ *       (b) the token's HMAC signature still verifies with `secret`
+ *     Any failure returns 403 without leaking which check failed.
+ */
+export function csrf(options: CsrfMiddlewareOptions): Middleware {
+  if (!options.secret || typeof options.secret !== "string") {
+    throw new Error("[Mandu CSRF] `secret` is required and must be a non-empty string");
+  }
+
+  const {
+    secret,
+    cookieName = DEFAULT_COOKIE_NAME,
+    headerName = DEFAULT_HEADER_NAME,
+    fieldName = DEFAULT_FIELD_NAME,
+    safeMethods = DEFAULT_SAFE_METHODS,
+  } = options;
+
+  const normalizedSafeMethods = new Set(safeMethods.map((m) => m.toUpperCase()));
+  const cookieOptions = resolveCookieOptions(options.cookieOptions);
+  const maxAgeSec = cookieOptions.maxAge ?? DEFAULT_MAX_AGE;
+
+  return async (ctx: ManduContext): Promise<Response | void> => {
+    const method = ctx.request.method.toUpperCase();
+
+    // 1. Ensure a valid CSRF cookie is present for the next unsafe request.
+    const existing = ctx.cookies.get(cookieName);
+    let activeCookieToken: string | null = null;
+
+    if (typeof existing === "string" && isAcceptableToken(existing)) {
+      const valid = await verifyToken(existing, secret, maxAgeSec);
+      if (valid) {
+        // Keep existing token (no unnecessary rotation).
+        activeCookieToken = existing;
+      }
+    }
+
+    if (activeCookieToken === null) {
+      activeCookieToken = await generateToken(secret, maxAgeSec);
+      ctx.cookies.set(cookieName, activeCookieToken, cookieOptions);
+    }
+
+    // 2. Safe methods pass through.
+    if (normalizedSafeMethods.has(method)) {
+      return;
+    }
+
+    // 3. Unsafe methods: read + validate submitted token.
+    const submitted = await extractSubmittedToken(ctx, headerName, fieldName);
+
+    if (!submitted || !isAcceptableToken(submitted)) {
+      return ctx.forbidden("CSRF token missing or invalid");
+    }
+
+    // Constant-time equality between submitted token and cookie token.
+    if (!safeEqual(submitted, activeCookieToken)) {
+      return ctx.forbidden("CSRF token missing or invalid");
+    }
+
+    // HMAC verification on the submitted token (prevents forged cookies from
+    // sibling subdomains since they cannot sign with our secret).
+    const verified = await verifyToken(submitted, secret, maxAgeSec);
+    if (!verified) {
+      return ctx.forbidden("CSRF token missing or invalid");
+    }
+
+    // Valid — continue.
+  };
+}
+
+// ========== Helpers ==========
+
+/**
+ * Resolve cookie options with production-safe defaults.
+ *
+ * `httpOnly: false` by default: a CSRF token cookie needs to be readable by
+ * client-side JS so the app can echo it back in the header. Callers who set
+ * the token from the server (e.g. via a hidden form field) may opt into
+ * `httpOnly: true`.
+ */
+function resolveCookieOptions(overrides?: CsrfMiddlewareOptions["cookieOptions"]): CookieOptions {
+  const isProd = typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+  return {
+    httpOnly: overrides?.httpOnly ?? false,
+    secure: overrides?.secure ?? isProd,
+    sameSite: overrides?.sameSite ?? "lax",
+    path: overrides?.path ?? "/",
+    maxAge: overrides?.maxAge ?? DEFAULT_MAX_AGE,
+    domain: overrides?.domain,
+  };
+}
+
+/** Read submitted token from header, falling back to form field if applicable. */
+async function extractSubmittedToken(
+  ctx: ManduContext,
+  headerName: string,
+  fieldName: string
+): Promise<string | null> {
+  // Header wins when present (cheap, safe, no body consumption).
+  const headerVal = ctx.headers.get(headerName);
+  if (typeof headerVal === "string" && headerVal.length > 0) {
+    return headerVal;
+  }
+
+  // Form fallback: only when the request advertises a form-like content type.
+  // JSON bodies are NOT scanned — header submission is the canonical path.
+  const contentType = (ctx.headers.get("content-type") ?? "").toLowerCase();
+  const isForm =
+    contentType.includes("application/x-www-form-urlencoded") ||
+    contentType.includes("multipart/form-data");
+  if (!isForm) return null;
+
+  try {
+    // Clone so downstream handlers can still read the body.
+    const form = await ctx.request.clone().formData();
+    const fieldVal = form.get(fieldName);
+    return typeof fieldVal === "string" ? fieldVal : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Validate token shape before running expensive crypto. */
+function isAcceptableToken(token: string): boolean {
+  return (
+    typeof token === "string" &&
+    token.length > 0 &&
+    token.length <= MAX_TOKEN_LENGTH
+  );
+}
+
+/**
+ * Constant-time string comparison to avoid timing-oracle attacks.
+ * Returns `false` immediately on length mismatch (lengths themselves are not
+ * secret for our fixed-format tokens), then XORs character codes over the
+ * full length before folding into a single diff bit.
+ */
+function safeEqual(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;
+}
+
+// ========== Token crypto (Bun.CSRF preferred, fallback to crypto.subtle) ==========
+
+/**
+ * Runtime capability probe for `Bun.CSRF`. Done once at module load — avoids
+ * re-checking on every request and allows non-Bun runtimes to use the
+ * fallback implementation.
+ */
+const bunCsrf = resolveBunCsrf();
+
+function resolveBunCsrf():
+  | {
+      generate: (secret: string, options?: { maxAge?: number }) => string;
+      verify: (token: string, options: { secret: string; maxAge?: number }) => boolean;
+    }
+  | null {
+  if (typeof globalThis === "undefined") return null;
+  const bun = (globalThis as { Bun?: { CSRF?: unknown } }).Bun;
+  if (!bun || typeof bun !== "object" || bun === null) return null;
+  const csrfApi = (bun as { CSRF?: unknown }).CSRF;
+  if (!csrfApi || typeof csrfApi !== "object") return null;
+  const api = csrfApi as {
+    generate?: unknown;
+    verify?: unknown;
+  };
+  if (typeof api.generate !== "function" || typeof api.verify !== "function") {
+    return null;
+  }
+  return api as {
+    generate: (secret: string, options?: { maxAge?: number }) => string;
+    verify: (token: string, options: { secret: string; maxAge?: number }) => boolean;
+  };
+}
+
+async function generateToken(secret: string, maxAgeSec: number): Promise<string> {
+  if (bunCsrf) {
+    // Bun.CSRF handles timestamp + random + HMAC in native code.
+    return bunCsrf.generate(secret, { maxAge: maxAgeSec });
+  }
+  return fallbackGenerate(secret);
+}
+
+async function verifyToken(token: string, secret: string, maxAgeSec: number): Promise<boolean> {
+  if (bunCsrf) {
+    try {
+      return bunCsrf.verify(token, { secret, maxAge: maxAgeSec });
+    } catch {
+      return false;
+    }
+  }
+  return fallbackVerify(token, secret);
+}
+
+// ----- Fallback (no Bun.CSRF available) -----
+
+/**
+ * Token format: `<random-b64url>.<hmac-b64url>`
+ *   - random: 32 bytes via `crypto.getRandomValues`
+ *   - hmac:   HMAC-SHA256(random, secret)
+ *
+ * Same pattern as `packages/core/src/filling/session.ts` (`hmacSign`,
+ * line 216-227) so we don't introduce a second crypto code path.
+ */
+async function fallbackGenerate(secret: string): Promise<string> {
+  const random = new Uint8Array(32);
+  crypto.getRandomValues(random);
+  const randomPart = base64UrlEncode(random);
+  const sig = await hmacSignB64Url(randomPart, secret);
+  return `${randomPart}.${sig}`;
+}
+
+async function fallbackVerify(token: string, secret: string): Promise<boolean> {
+  const dotIdx = token.lastIndexOf(".");
+  if (dotIdx <= 0 || dotIdx === token.length - 1) return false;
+  const randomPart = token.slice(0, dotIdx);
+  const signature = token.slice(dotIdx + 1);
+  if (!randomPart || !signature) return false;
+  const expected = await hmacSignB64Url(randomPart, secret);
+  // Constant-time comparison on signatures.
+  return safeEqual(signature, expected);
+}
+
+async function hmacSignB64Url(data: string, secret: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(data));
+  return base64UrlEncode(new Uint8Array(sig));
+}
+
+function base64UrlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}