@somewhatintelligent/kit 0.0.1-beta.1783705886.297c5be

package/src/react-start/service-clients.ts

@@ -0,0 +1,246 @@
+/**
+ * Service-client factories for TanStack Start apps.
+ *
+ * Three DI-correct factories — kit owns no concrete guestlist/roadie client
+ * type. Apps inject the constructor (`createGuestlistClient`, `createRoadieClient`)
+ * so kit doesn't take a dependency on platform service packages. Cookie
+ * adapters, request-id and actor wiring are sourced from kit primitives
+ * (`@tanstack/react-start/server`, `@somewhatintelligent/kit/request-context`).
+ *
+ * All three return `createServerOnlyFn`-wrapped callables: importing the
+ * surface from a route file (which bundles for both client and server) is
+ * safe; calling it from the client throws.
+ */
+import { createServerOnlyFn } from "@tanstack/react-start";
+import { getCookies, getRequest, setCookie } from "@tanstack/react-start/server";
+import {
+  extractRequestId,
+  getRequestContext,
+  updateRequestContext,
+  type Actor,
+} from "../request-context";
+
+// --- Guestlist ----------------------------------------------------------------
+
+/**
+ * Caller-supplied factory for the guestlist client. Apps pass
+ * `createGuestlistClient` from `@somewhatintelligent/guestlist-service/client` (kit doesn't
+ * depend on it directly).
+ */
+type GuestlistClientFactory<C> = (opts: {
+  baseURL: string;
+  callerApp: string;
+  fetchOptions: {
+    customFetchImpl: typeof fetch;
+    headers?: Record<string, string>;
+  };
+  cookies: {
+    getAll: () => ReadonlyArray<{ name: string; value: string }>;
+    setAll: (
+      cookies: ReadonlyArray<{
+        name: string;
+        value: string;
+        options?: Record<string, unknown>;
+      }>,
+    ) => void;
+  };
+  getRequestId: () => string;
+  getActor: () => Actor | null;
+}) => C;
+
+export interface GuestlistFactoryOpts<C> {
+  /** App identifier (`"identity"`, `"guestlist"`, etc.). Threaded into guestlist logs as `caller_app`. */
+  callerApp: string;
+  /** App-supplied guestlist client constructor. */
+  createClient: GuestlistClientFactory<C>;
+  /**
+   * Thunk returning a fetch implementation. Apps typically pass
+   * `() => env.GUESTLIST.fetch.bind(env.GUESTLIST)` so the binding lookup happens
+   * lazily inside the server-only path.
+   */
+  fetcher: () => typeof fetch;
+  /**
+   * Optional baseURL override. Defaults to `"http://guestlist.internal"` (the
+   * placeholder used for service-binding routing).
+   */
+  baseURL?: string;
+}
+
+/**
+ * Build an app's `getGuestlist` factory.
+ *
+ * Returns `(originRequest?: Request) => C` wrapped in `createServerOnlyFn`.
+ * Pass `originRequest` when calling Better Auth mutations from a server-route
+ * handler to forward the inbound `Origin` header (BA's CSRF check requires
+ * it on POST routes).
+ */
+export function createGuestlistFactory<C>(opts: GuestlistFactoryOpts<C>) {
+  const { callerApp, createClient, fetcher, baseURL = "http://guestlist.internal" } = opts;
+
+  return createServerOnlyFn((originRequest?: Request): C => {
+    const origin = originRequest?.headers.get("origin") ?? undefined;
+    return createClient({
+      baseURL,
+      callerApp,
+      fetchOptions: {
+        customFetchImpl: fetcher(),
+        ...(origin && { headers: { origin } }),
+      },
+      cookies: {
+        getAll: () => Object.entries(getCookies()).map(([name, value]) => ({ name, value })),
+        setAll: (cookies) => {
+          for (const { name, value, options } of cookies) {
+            setCookie(name, value, options as Parameters<typeof setCookie>[2]);
+          }
+        },
+      },
+      getRequestId: () => extractRequestId(getRequest()),
+      getActor: () => {
+        const ctx = getRequestContext();
+        return ctx?.actorKind === "user" && ctx.actorId
+          ? { kind: "user", userId: ctx.actorId }
+          : null;
+      },
+    });
+  });
+}
+
+// --- Roadie -----------------------------------------------------------------
+
+/**
+ * Caller-supplied factory for the roadie client. The exact `Binding` and
+ * `RoadieActor` types live in `@somewhatintelligent/roadie-service/client`; kit takes
+ * `Binding` as a generic so no import is needed here.
+ */
+type RoadieClientFactory<C, B> = (
+  binding: B,
+  opts: {
+    callerApp: string;
+    getRequestId: () => string;
+    getActor: () => RoadieActorLike;
+  },
+) => C;
+
+/**
+ * Mirror of `RoadieActor` from `@somewhatintelligent/roadie-service/client`. Kit doesn't
+ * import the platform package, so we restate the union here. Apps pass the
+ * real type via the generic `C`/`B`.
+ */
+type RoadieActorLike =
+  | { kind: "user"; userId: string }
+  | { kind: "service"; serviceName: string }
+  | { kind: "anonymous"; label: string };
+
+export interface RoadieFactoryOpts<C, B> {
+  /** App identifier — sets `meta.callerApp` and forms the anon-actor service prefix. */
+  callerApp: string;
+  /** App-supplied roadie client constructor. */
+  createClient: RoadieClientFactory<C, B>;
+  /** Thunk returning the roadie service binding (`() => env.ROADIE`). */
+  getBinding: () => B;
+  /**
+   * Optional anonymous-actor label deriver. When set and the request has no
+   * authenticated user, the returned label feeds `{ kind: "anonymous", label }`.
+   * Defaults to `"unauthenticated"`.
+   */
+  deriveAnonymousLabel?: (request: Request) => string;
+}
+
+/**
+ * Build an app's `getRoadie` factory.
+ *
+ * Returns `() => C` wrapped in `createServerOnlyFn`. Lazy: the binding
+ * thunk and any per-request state (active request, ALS context) are read
+ * each call, so the same factory works across requests in a single CF
+ * isolate.
+ */
+export function createRoadieFactory<C, B>(opts: RoadieFactoryOpts<C, B>) {
+  const { callerApp, createClient, getBinding, deriveAnonymousLabel } = opts;
+
+  return createServerOnlyFn((): C => {
+    return createClient(getBinding(), {
+      callerApp,
+      getRequestId: () => extractRequestId(getRequest()),
+      getActor: (): RoadieActorLike => {
+        const ctx = getRequestContext();
+        if (ctx?.actorKind === "user" && ctx.actorId) {
+          return { kind: "user", userId: ctx.actorId };
+        }
+        const label = deriveAnonymousLabel?.(getRequest()) ?? "unauthenticated";
+        return { kind: "anonymous", label };
+      },
+    });
+  });
+}
+
+// --- Session ----------------------------------------------------------------
+
+export interface SessionFactoryOpts<S extends { user: { id: string; role?: string | null } }> {
+  /**
+   * Guestlist fallback session reader. Apps wire
+   * `() => getGuestlist().getSession()`. Errors are swallowed and treated as
+   * unauthenticated.
+   */
+  getGuestlistFallback: () => Promise<S | null>;
+}
+
+/**
+ * Build an app's `getSession` server-only reader.
+ *
+ * `getSession(headers)` is WeakMap-memoised per Headers reference (so N
+ * callers in the same request share at most one guestlist service-binding RPC).
+ * On success, the resolved actor is patched into the active request-context
+ * ALS so canonical log lines emit with `actor_*` populated.
+ *
+ * In the target topology, the bouncer attestation envelope is the fast path
+ * — apps that wire `createPlatformStartApp` get envelope-first resolution
+ * for free. This raw factory exists for the non-Start path and for apps that
+ * want to compose `getSession` manually.
+ *
+ * **`loadSession` is intentionally NOT shipped from the kit**: TSS's compile
+ * plugin requires `createServerFn(...).handler(...)` to live at module
+ * top-level (see start-plugin-core's handleCreateServerFn). Wrapping it
+ * inside this factory body confuses the AST extraction. Apps build their
+ * own `loadSession` in a `lib/session.functions.ts` file instead:
+ *
+ * ```ts
+ * import { createServerFn } from "@tanstack/react-start";
+ * import { getRequestHeaders } from "@tanstack/react-start/server";
+ * import { platform } from "@/lib/platform";
+ *
+ * export const loadSession = createServerFn({ method: "GET" }).handler(
+ *   async () => platform.getSession(getRequestHeaders()),
+ * );
+ * ```
+ */
+export function createSessionFactory<S extends { user: { id: string; role?: string | null } }>(
+  opts: SessionFactoryOpts<S>,
+) {
+  const { getGuestlistFallback } = opts;
+
+  // Per-request memoization. The Headers reference is stable across all
+  // reads inside one TanStack request (single `getRequest()` instance), so
+  // caching the promise on the Headers means N callers share one guestlist
+  // service-binding RPC. Across requests the Headers object is GC'd and the
+  // entry vanishes.
+  const inflight = new WeakMap<Headers, Promise<S | null>>();
+
+  return createServerOnlyFn(function getSession(headers: Headers): Promise<S | null> {
+    const cached = inflight.get(headers);
+    if (cached) return cached;
+    const promise = (async () => {
+      let session: S | null = null;
+      try {
+        session = await getGuestlistFallback();
+      } catch {
+        session = null;
+      }
+      if (getRequestContext() && session) {
+        updateRequestContext({ actorKind: "user", actorId: session.user.id });
+      }
+      return session;
+    })();
+    inflight.set(headers, promise);
+    return promise;
+  });
+}

package/src/request-context/__tests__/index.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "vitest";
+import {
+  getActorId,
+  getActorKind,
+  getCallerApp,
+  getRequestContext,
+  getRequestId,
+  withRequestContext,
+} from "../index";
+
+describe("withRequestContext / getRequestContext", () => {
+  test("getRequestContext() returns the active context inside scope", async () => {
+    let captured: ReturnType<typeof getRequestContext> = null;
+    await withRequestContext({ requestId: "req_01" }, async () => {
+      captured = getRequestContext();
+    });
+    expect(captured).toEqual({ requestId: "req_01" });
+  });
+
+  test("getRequestContext() returns null outside any scope", () => {
+    expect(getRequestContext()).toBeNull();
+  });
+
+  test("getRequestId() reads request_id from active scope", async () => {
+    let id: string | null = null;
+    await withRequestContext({ requestId: "req_42" }, async () => {
+      id = getRequestId();
+    });
+    expect(id).toBe("req_42");
+  });
+
+  test("convenience readers return their respective fields", async () => {
+    let captured: { kind: string | null; id: string | null; caller: string | null } | null = null;
+    await withRequestContext(
+      {
+        requestId: "req_01",
+        actorKind: "user",
+        actorId: "user_123",
+        callerApp: "chat",
+      },
+      async () => {
+        captured = {
+          kind: getActorKind(),
+          id: getActorId(),
+          caller: getCallerApp(),
+        };
+      },
+    );
+    expect(captured).toEqual({ kind: "user", id: "user_123", caller: "chat" });
+  });
+
+  test("scope propagates through nested awaits", async () => {
+    async function deep() {
+      await new Promise((r) => setTimeout(r, 5));
+      return getRequestId();
+    }
+    async function middle() {
+      return deep();
+    }
+    let result: string | null = null;
+    await withRequestContext({ requestId: "req_deep" }, async () => {
+      result = await middle();
+    });
+    expect(result).toBe("req_deep");
+  });
+
+  test("nested withRequestContext shadows outer", async () => {
+    const ids: (string | null)[] = [];
+    await withRequestContext({ requestId: "outer" }, async () => {
+      ids.push(getRequestId());
+      await withRequestContext({ requestId: "inner" }, async () => {
+        ids.push(getRequestId());
+      });
+      ids.push(getRequestId());
+    });
+    expect(ids).toEqual(["outer", "inner", "outer"]);
+  });
+
+  test("readers return null for fields not set", async () => {
+    let captured: { kind: string | null; id: string | null; caller: string | null } | null = null;
+    await withRequestContext({ requestId: "req_01" }, async () => {
+      captured = {
+        kind: getActorKind(),
+        id: getActorId(),
+        caller: getCallerApp(),
+      };
+    });
+    expect(captured).toEqual({ kind: null, id: null, caller: null });
+  });
+});

package/src/request-context/index.ts

@@ -0,0 +1,189 @@
+/**
+ * Request-scoped context — request_id, actor, callerApp — propagated via
+ * AsyncLocalStorage. Distinct from `@somewhatintelligent/kit/log`'s `logStorage`
+ * (which holds the CanonicalLogBuilder for the active emit scope) — this
+ * holds the request-level identity that any number of canonical-log lines
+ * inside the same request might want to read.
+ *
+ * Why two ALSes:
+ *   - logStorage scope opens/closes per `withCanonicalLog` call (often
+ *     once per RPC method, server-fn, or HTTP handler).
+ *   - requestContextStorage scope opens/closes per inbound request and
+ *     persists across multiple log emissions inside that request.
+ *
+ * Consumers open the scope at the fetch boundary:
+ *
+ *   import { withRequestContext, getRequestId } from "@somewhatintelligent/kit/request-context";
+ *   import { ulid } from "@somewhatintelligent/kit/ids";
+ *
+ *   export default {
+ *     async fetch(request, _env, ctx) {
+ *       const requestId = request.headers.get("cf-request-id") ?? ulid();
+ *       return withRequestContext({ requestId }, () => app.fetch(request));
+ *     },
+ *   };
+ *
+ * Then anywhere in the request lifecycle:
+ *
+ *   const requestId = getRequestId();  // reads from ALS, no parameter threading
+ *
+ * This is the minimal primitive. `withCanonicalLog` may grow to read
+ * request_id from this storage when its ctx arg doesn't supply one
+ * (cleaner boundary instrumentation), but that's a follow-up — for now
+ * boundary wrappers pass request_id explicitly.
+ */
+/// <reference types="node" />
+// Namespace import (not `{ AsyncLocalStorage }`) so Vite's client transform
+// doesn't emit a top-level `stub["AsyncLocalStorage"]` property access. The
+// kit/react-start barrel is reachable from app client bundles in dev via
+// `.middleware([...])` runtime references that TSS can't strip; the named
+// destructure form crashes the browser at module init because Vite
+// externalizes `node:async_hooks` to a Proxy that throws on any get. The
+// namespace binding stays inert until `storage()` is called server-side.
+import * as nodeAsyncHooks from "node:async_hooks";
+import type { AsyncLocalStorage as ALS } from "node:async_hooks";
+import { ulid } from "../ids";
+
+/**
+ * Adopt a request id from inbound headers, falling back to a fresh ULID.
+ * Prefers an already-open `withRequestContext` scope so calls made deep in
+ * the request lifecycle return the same id the boundary adopted; falls
+ * back to header probe (`cf-request-id`, then `x-request-id`) and finally
+ * a synthesized ulid.
+ *
+ * **Use this only at bouncer's public-edge boundary** — bouncer is the
+ * platform's sole translator of `cf-*` headers. Every other worker (apps
+ * + internal services) reaches request context via `extractPlatformRequestId`
+ * below, which speaks the internal `x-platform-rid` contract.
+ *
+ *   import { extractRequestId } from "@somewhatintelligent/kit/request-context";
+ *   const requestId = extractRequestId(request);
+ */
+export function extractRequestId(req: Request): string {
+  return (
+    storage().getStore()?.requestId ??
+    req.headers.get("cf-request-id") ??
+    req.headers.get("x-request-id") ??
+    ulid()
+  );
+}
+
+/**
+ * Adopt a request id from the platform's internal header contract.
+ *
+ * Reads `x-platform-rid` (set by bouncer, or by an upstream platform worker
+ * forwarding through service binding), otherwise mints a fresh ULID. The
+ * canonical reader for any worker that participates in the platform but is
+ * not the public-edge bouncer — apps, guestlist, roadie, promoter — should
+ * use this rather than `extractRequestId`.
+ *
+ * Apps run alone in development without bouncer in front; in that topology
+ * there is no `x-platform-rid`, the mint branch fires, and logs key off the
+ * minted id for the lifetime of that one request.
+ *
+ *   import { extractPlatformRequestId } from "@somewhatintelligent/kit/request-context";
+ *   const requestId = extractPlatformRequestId(request);
+ */
+export function extractPlatformRequestId(req: Request): string {
+  return storage().getStore()?.requestId ?? req.headers.get("x-platform-rid") ?? ulid();
+}
+
+/**
+ * THE canonical "extract the routing host from a request" rule — the single
+ * definition shared by bouncer (the public-edge ingress), the dev-envelope
+ * stamper that emulates it, and the apps that resolve a host → brand. One place,
+ * so the envelope's attested host, the edge routing decision, and an app's
+ * host→brand lookup can never disagree.
+ *
+ * `x-forwarded-host` is the proxy's signal for the ORIGINAL client host (portless
+ * in dev rewrites `Host` to the proxy target and moves the real host here).
+ * Trusting it in production would let a client spoof the routing host, so it is
+ * honored ONLY when `trustForwardedHost` is set (development). Lowercased,
+ * port-stripped; null when nothing resolves.
+ */
+export function routingHostFromHeaders(
+  headers: { get(name: string): string | null },
+  opts: { trustForwardedHost: boolean; fallbackHost?: string | null },
+): string | null {
+  const forwarded = opts.trustForwardedHost ? headers.get("x-forwarded-host") : null;
+  const raw = forwarded ?? headers.get("host") ?? opts.fallbackHost ?? null;
+  return raw ? raw.toLowerCase().split(":")[0]! : null;
+}
+
+/**
+ * Narrow Actor kind for service-binding RPC. Apps may have richer actor
+ * models at their own boundary (e.g. `anonymous` for unauthenticated transfer
+ * viewers); they fold those into `user` or `service` when calling RPC.
+ */
+export type Actor = { kind: "user"; userId: string } | { kind: "service"; serviceName: string };
+
+export interface RequestContext {
+  /** Request ID. Adopted from `cf-request-id` (or W3C traceparent) at the entry Worker, propagated through every layer. */
+  requestId: string;
+  /** Actor identity kind — typically `"user" | "service" | "anonymous"`. */
+  actorKind?: string;
+  /** Actor identifier — userId for user actors, serviceName for service actors, label for anonymous. Null when unresolved. */
+  actorId?: string | null;
+  /** For RPC events: which app/service called this method. */
+  callerApp?: string;
+  /** W3C Trace Context — paves the path to OTEL adoption. Free now (just propagated as-is). */
+  traceparent?: string;
+}
+
+let _storage: ALS<RequestContext> | undefined;
+function storage(): ALS<RequestContext> {
+  return (_storage ??= new nodeAsyncHooks.AsyncLocalStorage<RequestContext>());
+}
+
+/**
+ * Open a request-scoped context. The fn (and everything in its async
+ * call stack) can read the context via `getRequestContext()`,
+ * `getRequestId()`, etc. The scope closes when fn resolves; nested
+ * `withRequestContext` calls shadow the outer (inner returns its own
+ * context until it closes).
+ */
+export function withRequestContext<T>(ctx: RequestContext, fn: () => Promise<T>): Promise<T> {
+  return storage().run(ctx, fn);
+}
+
+/**
+ * Patch the active request context in place. Useful at the boundary when
+ * the request id is known immediately but actor info isn't resolved until
+ * after a session lookup — open the scope with `{ requestId }` first so
+ * any I/O during resolution sees the id, then `updateRequestContext({
+ * actorKind, actorId })` once the lookup returns. ALS stores a reference,
+ * so all readers downstream see the mutation. Throws if called outside
+ * a scope.
+ */
+export function updateRequestContext(patch: Partial<RequestContext>): void {
+  const ctx = storage().getStore();
+  if (!ctx) {
+    throw new Error("updateRequestContext called outside any withRequestContext scope");
+  }
+  Object.assign(ctx, patch);
+}
+
+/** Read the active request context, or `null` if no scope is open. */
+export function getRequestContext(): RequestContext | null {
+  return storage().getStore() ?? null;
+}
+
+/** Convenience reader. Returns the request_id from the active scope, or `null`. */
+export function getRequestId(): string | null {
+  return storage().getStore()?.requestId ?? null;
+}
+
+/** Convenience reader. Returns the active actor kind, or `null`. */
+export function getActorKind(): string | null {
+  return storage().getStore()?.actorKind ?? null;
+}
+
+/** Convenience reader. Returns the active actor id, or `null`. */
+export function getActorId(): string | null {
+  return storage().getStore()?.actorId ?? null;
+}
+
+/** Convenience reader. Returns the active caller_app, or `null`. */
+export function getCallerApp(): string | null {
+  return storage().getStore()?.callerApp ?? null;
+}

package/src/roles.ts

@@ -0,0 +1,25 @@
+/**
+ * Role helpers.
+ *
+ * `user.role` (Better Auth's admin plugin) is a COMMA-SEPARATED string
+ * (e.g. `"admin,user"`) or a `string[]` — the admin plugin splits on commas
+ * before matching `adminRoles`. Never compare the raw value with `=== "admin"`:
+ * a multi-role user (`"admin,user"`) silently loses access.
+ *
+ * Client-safe: no imports, no server-only references.
+ */
+
+/** True when the role value (csv string or array) contains `role`. */
+export function hasRole(
+  roles: string | readonly string[] | null | undefined,
+  role: string,
+): boolean {
+  if (!roles) return false;
+  const list = Array.isArray(roles) ? roles : String(roles).split(",");
+  return list.map((r) => r.trim()).includes(role);
+}
+
+/** Convenience: `hasRole(roles, "admin")`. */
+export function isAdminRole(roles: string | readonly string[] | null | undefined): boolean {
+  return hasRole(roles, "admin");
+}

package/src/version/__tests__/index.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from "vitest";
+import { VERSION_PATH, handleVersionRequest, versionInfo, versionResponse } from "../index";
+
+const req = (url: string, method = "GET") => new Request(url, { method });
+
+describe("versionInfo", () => {
+  test("reads the package stamp + ENVIRONMENT from env", () => {
+    expect(
+      versionInfo({
+        worker: "guestlist",
+        env: { ENVIRONMENT: "staging" },
+        pkg: { version: "1.2.3", commit: "abc1234" },
+      }),
+    ).toEqual({
+      worker: "guestlist",
+      version: "1.2.3",
+      commit: "abc1234",
+      environment: "staging",
+    });
+  });
+
+  test("falls back safely when nothing is injected", () => {
+    expect(versionInfo({ worker: "bouncer" })).toEqual({
+      worker: "bouncer",
+      version: "0.0.0-dev",
+      commit: "unknown",
+      environment: "development",
+    });
+  });
+
+  test("ignores a non-string ENVIRONMENT var; deploy vars are NOT consulted", () => {
+    const info = versionInfo({
+      worker: "roadie",
+      // WORKER_VERSION/WORKER_COMMIT vars are dead — the package stamp is
+      // the source of truth; a stray var must not shadow it.
+      env: { WORKER_VERSION: "9.9.9", WORKER_COMMIT: "sneaky", ENVIRONMENT: null },
+    });
+    expect(info.version).toBe("0.0.0-dev");
+    expect(info.commit).toBe("unknown");
+    expect(info.environment).toBe("development");
+  });
+
+  test("tolerates a non-object env", () => {
+    expect(versionInfo({ worker: "promoter", env: "nope" }).version).toBe("0.0.0-dev");
+  });
+
+  test("overrides win over the pkg stamp (vite-define apps)", () => {
+    const info = versionInfo({
+      worker: "identity",
+      env: { ENVIRONMENT: "staging" },
+      pkg: { version: "9.9.9", commit: "zzz" },
+      overrides: { version: "1.0.0", commit: "def5678" },
+    });
+    expect(info.version).toBe("1.0.0");
+    expect(info.commit).toBe("def5678");
+    expect(info.environment).toBe("staging"); // un-overridden field still reads env
+  });
+});
+
+describe("versionResponse", () => {
+  test("serializes as uncacheable JSON", async () => {
+    const res = versionResponse({
+      worker: "bouncer",
+      version: "1.0.0",
+      commit: "abc",
+      environment: "production",
+    });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("application/json");
+    expect(res.headers.get("cache-control")).toBe("no-store");
+    expect(await res.json()).toEqual({
+      worker: "bouncer",
+      version: "1.0.0",
+      commit: "abc",
+      environment: "production",
+    });
+  });
+});
+
+describe("handleVersionRequest", () => {
+  test(`answers GET ${VERSION_PATH} on any host`, async () => {
+    const res = handleVersionRequest(req("https://anything.example/__version"), {
+      worker: "bouncer",
+      env: { ENVIRONMENT: "staging" },
+    });
+    expect(res).not.toBeNull();
+    expect(((await res!.json()) as { worker: string }).worker).toBe("bouncer");
+  });
+
+  test("returns null for other paths (routing proceeds)", () => {
+    expect(
+      handleVersionRequest(req("https://x.example/health"), { worker: "guestlist" }),
+    ).toBeNull();
+    // No prefix matching — only exact paths answer.
+    expect(
+      handleVersionRequest(req("https://x.example/__version/extra"), { worker: "guestlist" }),
+    ).toBeNull();
+  });
+
+  test("returns null for non-GET/HEAD methods", () => {
+    expect(
+      handleVersionRequest(req("https://x.example/__version", "POST"), { worker: "roadie" }),
+    ).toBeNull();
+  });
+
+  test("answers HEAD", () => {
+    expect(
+      handleVersionRequest(req("https://x.example/__version", "HEAD"), { worker: "roadie" }),
+    ).not.toBeNull();
+  });
+
+  test("extra mounted paths answer (guestlist behind bouncer's /api passthrough)", async () => {
+    const opts = {
+      worker: "guestlist",
+      paths: ["/__version", "/api/__version"],
+    } as const;
+    const direct = handleVersionRequest(req("https://x.example/__version"), opts);
+    const mounted = handleVersionRequest(req("https://x.example/api/__version"), opts);
+    expect(direct).not.toBeNull();
+    expect(mounted).not.toBeNull();
+    expect(((await mounted!.json()) as { worker: string }).worker).toBe("guestlist");
+  });
+});
+
+describe("versionInfo pkg stamp", () => {
+  test("chain: overrides > pkg stamp > dev placeholders", () => {
+    const pkg = { version: "1.2.3", commit: "abc1234" };
+    expect(versionInfo({ worker: "w", env: {}, pkg })).toMatchObject({
+      version: "1.2.3",
+      commit: "abc1234",
+    });
+    expect(
+      versionInfo({ worker: "w", env: {}, pkg, overrides: { version: "o" } }),
+    ).toMatchObject({ version: "o", commit: "abc1234" });
+    expect(versionInfo({ worker: "w", env: {} })).toMatchObject({
+      version: "0.0.0-dev",
+      commit: "unknown",
+    });
+  });
+});