@kedge/server 0.0.0-stage → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Kedge Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@kedge/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.10.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chandeldivyam/Kedge.git",
+    "directory": "packages/server"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "description": "Hono app: /store, /admin, /health.",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "hono": "4.13.13",
+    "@hono/zod-openapi": "1.6.3",
+    "zod": "4.6.7",
+    "@kedge/core": "0.10.0",
+    "@kedge/plugin-sdk": "0.10.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "5.20261024.1"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p .",
+    "test": "vitest run"
+  }
 }

package/src/access.ts

@@ -0,0 +1,477 @@
+// Who is asking, resolved before routing (p0.5-auth-and-access.md §3.3, §2.9,
+// §6.2): a staff session (cookie or bearer) or a secret key on /admin/*, a
+// publishable key and an optional customer session on /store/*. Nothing here
+// caches a permission: each request reads them fresh, so a revoked grant, a
+// signed-out session or a revoked key is refused on the next request.
+import {
+  type AccessContext,
+  ANONYMOUS,
+  auditChanges,
+  digestToken,
+  holds,
+  isKedgeError,
+  KedgeError,
+  type StoreProof,
+} from "@kedge/core";
+import type { Context, MiddlewareHandler } from "hono";
+import { routePath } from "hono/route";
+import { adminOriginsFor, authzFingerprint, checkAdminBuild, checkView, nameAnswer } from "./admin-shell";
+import type { AccessKey, AccessSession, AdminScope, AuthDeps, ClientInfo, Pool, ResolvedAccess } from "./types";
+
+export const COOKIE: Record<Pool, string> = { staff: "__Host-kedge_staff", customer: "__Host-kedge_customer" };
+export const DEVICE_COOKIE = "__Host-kedge_device";
+
+/** What a request is, once resolved; set as `c.var.access`. */
+export interface RequestAccess {
+  ctx: AccessContext;
+  /** How the principal's credential came: a cookie needs CSRF on mutations, a bearer or key doesn't (§2.9). */
+  via: "cookie" | "bearer" | "key" | "none";
+  session?: AccessSession;
+  key?: AccessKey;
+  resolved?: ResolvedAccess;
+}
+
+/** The store's storefront, from its publishable key (§6.2); set as `c.var.storefront`. */
+export interface RequestStorefront {
+  keyId: string;
+  storefrontId: string;
+  origins: readonly string[];
+}
+
+export type KedgeEnv = {
+  Variables: {
+    access: RequestAccess;
+    storefront: RequestStorefront;
+    proof: StoreProof;
+    /** A cart route's customer cookie, to refresh when the cart renews its session. */
+    cartCookie?: string;
+  };
+};
+
+export const NONE: RequestAccess = { ctx: ANONYMOUS, via: "none" };
+
+/**
+ * Addresses past `key_fail` on a cart route, remembered by this isolate for
+ * the limit's window, so a flood of bad keys stops reaching cart objects;
+ * the D1 counter stays the authority across isolates.
+ */
+const keyBlocked = new Map<string, number>();
+const KEY_BLOCK_MS = 10 * 60_000;
+/** The address a limit counts, grouped as the D1 counters group it (IPv6 by /64 there; whole here, which only blocks less). */
+const addressOf = (c: Context) => c.req.header("cf-connecting-ip") ?? "unknown";
+
+const SAFE = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/** The client address limits count: `cf-connecting-ip`, never `x-forwarded-for` (§2.8). */
+export function clientOf(c: Context): ClientInfo {
+  return { ip: c.req.header("cf-connecting-ip") ?? null, userAgent: c.req.header("user-agent")?.slice(0, 256) ?? null };
+}
+
+/**
+ * Every value of one cookie. A request carrying two session cookies for a
+ * pool is refused, never guessed between (§2.1): a sibling host can plant a
+ * `Domain` cookie beside the `__Host-` one, and choosing would let it win.
+ */
+export function cookieValues(header: string | undefined, name: string): string[] {
+  if (!header) return [];
+  const out: string[] = [];
+  for (const part of header.split(";")) {
+    const i = part.indexOf("=");
+    if (i < 0) continue;
+    if (part.slice(0, i).trim() === name) out.push(part.slice(i + 1).trim());
+  }
+  return out;
+}
+
+function bearerOf(c: Context): string | null {
+  const h = c.req.header("authorization");
+  if (!h) return null;
+  if (!h.startsWith("Bearer ")) throw new KedgeError("UNAUTHORIZED", "Missing or invalid credentials");
+  return h.slice(7).trim();
+}
+
+/** Constant-time comparison of two presented tokens. */
+function same(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;
+}
+
+/**
+ * The session credential of a pool, if any. Cookie and bearer together must
+ * be the same session, and are then a cookie request (§2.9 rule 1), so a
+ * bearer header can't exempt a cookie request from CSRF.
+ */
+export function sessionCredential(c: Context, pool: Pool): { token: string; via: "cookie" | "bearer" } | null {
+  const cookies = cookieValues(c.req.header("cookie"), COOKIE[pool]);
+  if (cookies.length > 1) throw new KedgeError("UNAUTHORIZED", "More than one session cookie");
+  const cookie = cookies[0] || null;
+  const bearer = bearerOf(c);
+  if (cookie && bearer && !same(cookie, bearer))
+    throw new KedgeError("UNAUTHORIZED", "The cookie and the bearer token name different sessions");
+  if (cookie) return { token: cookie, via: "cookie" };
+  if (bearer) return { token: bearer, via: "bearer" };
+  return null;
+}
+
+/** Sets or clears a pool's session cookie: `__Host-`, so no `Domain` (§2.1). */
+export function sessionCookie(pool: Pool, token: string | null, expiresAt: number | null, now: number): string {
+  const same = pool === "staff" ? "Strict" : "Lax";
+  const age = token && expiresAt ? Math.max(0, Math.floor((expiresAt - now) / 1000)) : 0;
+  return `${COOKIE[pool]}=${token ?? ""}; Path=/; Secure; HttpOnly; SameSite=${same}; Max-Age=${age}`;
+}
+
+export function deviceCookie(token: string, maxAgeSeconds: number): string {
+  return `${DEVICE_COOKIE}=${token}; Path=/; Secure; HttpOnly; SameSite=Strict; Max-Age=${maxAgeSeconds}`;
+}
+
+/**
+ * Resolves a session of `pool` and does its maintenance when due: staff
+ * activity, or a customer's renewal, whose new expiry refreshes the cookie.
+ */
+export async function resolveSession(
+  c: Context,
+  auth: AuthDeps,
+  pool: Pool,
+  cred: { token: string; via: "cookie" | "bearer" },
+  now: number,
+): Promise<RequestAccess> {
+  const found = await auth.access.session(pool, cred.token, now);
+  if (!found?.session) throw new KedgeError("UNAUTHORIZED", "Your session has ended; sign in again");
+  if (auth.access.maintenanceDue(found.session, now)) {
+    const renewed = await auth.access.maintain(found.session, now);
+    if (renewed !== null && cred.via === "cookie")
+      c.header("set-cookie", sessionCookie(pool, cred.token, renewed, now), { append: true });
+  }
+  return { ctx: found.ctx, via: cred.via, session: found.session, resolved: found };
+}
+
+/** Verifies an API key; a failure counts against the address (§4.3). */
+export async function resolveKey(c: Context, auth: AuthDeps, presented: string, now: number) {
+  const found = await auth.access.apiKey(presented, now);
+  if (!found?.key) {
+    const within = await auth.access.keyFailure(clientOf(c).ip, now);
+    if (!within) throw new KedgeError("RATE_LIMITED", "Too many failed key attempts; wait a little");
+    throw new KedgeError("KEY_INVALID", "Missing or invalid API key");
+  }
+  if (auth.access.keyTouchDue(found.key, now)) await auth.access.touchKey(found.key.id, now);
+  return found;
+}
+
+/**
+ * The CSRF rule (§2.9) for a cookie request: JSON where the route takes a
+ * body, `X-Kedge-CSRF` (the literal `1` before a session exists, the
+ * session's token after) and an `Origin` on the pool's allow-list, whatever
+ * `Sec-Fetch-Site` says. The custom header forces a preflight that the
+ * origin list refuses, so an unlisted page can't post with the cookie.
+ */
+export async function checkCsrf(
+  c: Context,
+  auth: AuthDeps,
+  origins: readonly string[],
+  opts: { sessionToken: string | null; json: boolean },
+  now: number,
+): Promise<void> {
+  const origin = c.req.header("origin");
+  if (!origin || !origins.includes(origin))
+    throw new KedgeError("CSRF_REJECTED", "This origin may not send this request");
+  if (opts.json && !/^application\/json\b/i.test(c.req.header("content-type") ?? ""))
+    throw new KedgeError("CSRF_REJECTED", "Send Content-Type: application/json");
+  const header = c.req.header("x-kedge-csrf");
+  if (!header) throw new KedgeError("CSRF_REJECTED", "Missing X-Kedge-CSRF");
+  if (opts.sessionToken === null) {
+    if (header !== "1") throw new KedgeError("CSRF_REJECTED", "X-Kedge-CSRF must be 1 before a session exists");
+    return;
+  }
+  const v = await auth.access.csrf(opts.sessionToken, header, now);
+  if (v === "expired") throw new KedgeError("CSRF_EXPIRED", "The CSRF token expired; fetch the session and retry");
+  if (v !== "ok") throw new KedgeError("CSRF_REJECTED", "Invalid X-Kedge-CSRF");
+}
+
+export const isSafe = (method: string) => SAFE.has(method);
+
+// ---- every admin route declares its permission (§3.3) ------------------------------
+
+export interface Declared {
+  permission: string;
+  /** The audit action of a mutation (defaults to the method and path). */
+  action?: string;
+  /** A read sent as POST (a search whose values may not go in a URL, §5.2): CSRF still applies, the batch scope doesn't. */
+  read?: boolean;
+  /**
+   * The route's store keeps its own command envelope (capacity commands, the
+   * admin store, creations): the scope records no key for it. Every other
+   * mutation's Idempotency-Key is recorded by the scope (§8, codex code r8).
+   */
+  own?: boolean;
+  /**
+   * The route compiles its caller's row scopes into its query (the resource
+   * registry: orders). Any other read needs its permission unscoped, as a
+   * mutation does (codex code r9): a location-scoped capacity reader must not
+   * list every location's pools.
+   */
+  scoped?: boolean;
+  /**
+   * The route's store authorizes inside its own audited batch (p0.7 §3.4,
+   * §4.5): the permission depends on the request (a track's transition), and
+   * a row-scoped grant is compiled into the batch and re-proved there by the
+   * scoped guard. The gate authenticates and checks CSRF only; `permission`
+   * names the route's family for the docs, and is never checked here.
+   */
+  store?: boolean;
+}
+
+/**
+ * The declared permission of each `/admin/*` route. A route that isn't here
+ * is never reachable (404), and `verify` refuses to boot an app that
+ * registered one (§3.3), so a forgotten declaration fails loudly, not open.
+ */
+export class AdminPermissions {
+  private readonly map = new Map<string, Declared>();
+
+  /** Declares `route`'s permission; returns it, so a definition reads `app.openapi(admin.declare(p, createRoute(…)), h)`. */
+  declare<R extends { method: string; path: string }>(permission: string | Declared, route: R): R {
+    const d = typeof permission === "string" ? { permission } : permission;
+    this.map.set(key(route.method, honoPath(route.path)), d);
+    return route;
+  }
+
+  /** The permission of the route a request matched. */
+  of(c: Context): Declared | undefined {
+    return this.map.get(key(c.req.method, routePath(c, -1)));
+  }
+
+  /** Every registered `/admin/*` endpoint has a declaration (boot). */
+  verify(routes: readonly { method: string; path: string }[]): void {
+    const missing = routes
+      .filter((r) => r.path.startsWith("/admin/") && r.method !== "ALL")
+      .filter((r) => !this.map.has(key(r.method, r.path)))
+      .map((r) => `${r.method} ${r.path}`);
+    // The OpenAPI document is the one public /admin path.
+    const undeclared = missing.filter((m) => m !== "GET /admin/openapi.json");
+    // kedge-allow no-dynamic-throw: route paths, checked at boot
+    if (undeclared.length > 0) throw new Error(`admin routes without a permission: ${undeclared.join(", ")}`);
+  }
+
+  entries(): [string, Declared][] {
+    return [...this.map.entries()];
+  }
+}
+
+const key = (method: string, path: string) => `${method.toUpperCase()} ${path}`;
+
+/**
+ * A mutation's command identity for the scope's envelope (§8): the route, its
+ * path parameters (the targets) and its body. None without an Idempotency-Key.
+ */
+function commandOf(
+  c: Context,
+  route: string,
+  targets: readonly string[],
+  input: unknown,
+): { command?: AdminScope["command"] } {
+  const k = c.req.header("idempotency-key");
+  if (k === undefined) return {};
+  if (k.length === 0 || new TextEncoder().encode(k).length > 255)
+    throw new KedgeError("BAD_REQUEST", "An Idempotency-Key is 1 to 255 bytes");
+  return { command: { key: k, operation: route, targets, input } };
+}
+
+/**
+ * The final route's path parameters in template order, from its template: in a
+ * middleware Hono's `param()` answers for the middleware's own route, which has none.
+ */
+function targetsOf(c: Context): string[] {
+  const template = routePath(c, -1).split("/");
+  const actual = c.req.path.split("/");
+  return template.flatMap((seg, i) => (seg.startsWith(":") ? [decodeURIComponent(actual[i] ?? "")] : []));
+}
+/** OpenAPI's `{id}` is Hono's `:id`. */
+const honoPath = (path: string) => path.replace(/\{([^}]+)\}/g, ":$1");
+
+/**
+ * The /admin/* gate: a staff session or a secret key, CSRF for cookie
+ * mutations, the route's declared permission, and for a mutation the batch
+ * scope that audits and re-proves it in every batch (§7.1).
+ */
+export function adminGate(auth: AuthDeps, perms: AdminPermissions, now: () => number): MiddlewareHandler<KedgeEnv> {
+  return async (c, next) => {
+    if (c.req.method === "OPTIONS") return next();
+    if (c.req.path === "/admin/openapi.json") return next();
+    // A stale admin is refused before anything, reads included (p0.9 §2.4).
+    checkAdminBuild(c, auth.adminBuild ?? null);
+    const t = now();
+    const cred = sessionCredential(c, "staff");
+    let access: RequestAccess;
+    if (cred?.via === "bearer" && cred.token.startsWith("sk_")) {
+      const found = await resolveKey(c, auth, cred.token, t);
+      access = { ctx: found.ctx, via: "key", key: found.key, resolved: found };
+    } else if (cred?.via === "bearer" && cred.token.startsWith("kcs_")) {
+      // A CLI session (p0.10 §6.2): admitted here, on /admin/* only, never as a staff session.
+      const found = await auth.access.cliSession(cred.token, t);
+      if (!found) throw new KedgeError("UNAUTHORIZED", "This CLI session has ended; run the command again");
+      access = { ctx: found.ctx, via: "bearer", resolved: found };
+    } else if (cred) {
+      access = await resolveSession(c, auth, "staff", cred, t);
+    } else {
+      throw new KedgeError("UNAUTHORIZED", "Sign in first");
+    }
+    // Every staff answer, errors included, names the session and the authority that answered (p0.9 §9).
+    const fingerprint = await authzFingerprint(access.ctx, access.session?.method ?? null, auth.accessContract ?? "");
+    if (access.session) nameAnswer(c, access.session.id, fingerprint);
+    const declared = perms.of(c);
+    if (!declared) throw new KedgeError("NOT_FOUND", "Not found");
+    const mutation = !isSafe(c.req.method) && declared.read !== true;
+    if (!isSafe(c.req.method) && access.via === "cookie")
+      await checkCsrf(c, auth, adminOriginsFor(c, auth), { sessionToken: cred?.token ?? null, json: false }, t);
+    // A mutation made from a view this request no longer has runs nothing (p0.9 §6.3).
+    if (mutation) checkView(c, fingerprint);
+    // An invite's enrolment session may only enrol its first factor (§3.4).
+    if (access.session?.method.startsWith("invite:"))
+      throw new KedgeError("STRONG_AUTH_REQUIRED", "Enrol your authenticator first");
+    if (declared.store) {
+      c.set("access", access);
+      return next();
+    }
+    if (!holds(access.ctx.grants, declared.permission))
+      throw new KedgeError("FORBIDDEN", "You don't have permission for this", { permission: declared.permission });
+    c.set("access", access);
+    if (!mutation && !declared.scoped && access.ctx.grants.get(declared.permission)?.has("all") !== true)
+      throw new KedgeError("FORBIDDEN", "This read needs the permission for every row", {
+        permission: declared.permission,
+      });
+    if (!mutation) return next();
+    // A mutation needs its permission unscoped: P0.5 compiles no row-scoped
+    // write (§5.3 arrives with assignable resources), so a scoped holder is
+    // refused here and the guard re-proves `all` at commit.
+    if (access.ctx.grants.get(declared.permission)?.has("all") !== true)
+      throw new KedgeError("FORBIDDEN", "This change needs the permission for every row", {
+        permission: declared.permission,
+      });
+    const client = clientOf(c);
+    const route = `${c.req.method} ${routePath(c, -1)}`;
+    const target = targetsOf(c);
+    const input = await c.req.json().catch(() => null);
+    const scope: AdminScope = {
+      access: access.resolved as ResolvedAccess,
+      required: [declared.permission],
+      action: declared.action ?? route,
+      ip: client.ip,
+      userAgent: client.userAgent,
+      // The row names its target and the input, metadata only (§7.2, codex code r10).
+      entity: { type: c.req.path.split("/")[2] ?? "admin", id: target[0] ?? null },
+      changes: auditChanges(input),
+      ...(declared.own ? {} : commandOf(c, route, target, input)),
+    };
+    const { replayed } = await auth.scoped.run(scope, async () => {
+      await next();
+    });
+    // A retry of a recorded command answers its outcome and ids (§8); so does a
+    // send that lost the race for its key to a concurrent one.
+    const outcome = replayed ?? (c.res.status >= 400 ? await auth.scoped.replayed(scope) : null);
+    if (outcome) c.res = c.json({ replayed: true, outcome: outcome.outcome, ids: outcome.ids }, 200);
+  };
+}
+
+/**
+ * The /store/* gate (§6.2): a publishable key in `x-kedge-key`, whose
+ * storefront lists the request's `Origin` when one is sent (a same-origin
+ * GET or a server client sends none, and is judged by the key alone), and
+ * the customer's session if one is presented. A cookie mutation needs CSRF.
+ */
+export function storeGate(auth: AuthDeps, now: () => number): MiddlewareHandler<KedgeEnv> {
+  return async (c, next) => {
+    if (c.req.method === "OPTIONS") return next();
+    const t = now();
+    if (/^\/store\/carts(\/|$)/.test(c.req.path)) {
+      const address = addressOf(c);
+      if ((keyBlocked.get(address) ?? 0) > t)
+        throw new KedgeError("RATE_LIMITED", "Too many failed key attempts; wait a little");
+      // A failed key, refused here (malformed) or by the cart's batch, is counted
+      // against the address like any other failed verification (§4.3, codex code
+      // r7); a success costs nothing.
+      const failed = async (): Promise<boolean> => {
+        if (await auth.access.keyFailure(clientOf(c).ip, t)) return false;
+        keyBlocked.set(address, t + KEY_BLOCK_MS);
+        return true;
+      };
+      try {
+        c.set("proof", await cartProof(c, auth, t));
+      } catch (e) {
+        if (isKedgeError(e) && e.code === "KEY_INVALID" && (await failed()))
+          throw new KedgeError("RATE_LIMITED", "Too many failed key attempts; wait a little");
+        throw e;
+      }
+      const cred = sessionCredential(c, "customer");
+      if (cred?.via === "cookie") c.set("cartCookie", cred.token);
+      c.set("access", NONE);
+      await next();
+      if (c.res.status === 401) {
+        const body = (await c.res
+          .clone()
+          .json()
+          .catch(() => null)) as { error?: { code?: string } } | null;
+        if (body?.error?.code === "KEY_INVALID" && (await failed()))
+          c.res = c.json(new KedgeError("RATE_LIMITED", "Too many failed key attempts; wait a little").toJSON(), 429);
+      }
+      return;
+    }
+    c.set("storefront", await storefrontOf(c, auth, t));
+    const cred = sessionCredential(c, "customer");
+    if (!cred) {
+      c.set("access", NONE);
+      return next();
+    }
+    const access = await resolveSession(c, auth, "customer", cred, t);
+    if (!isSafe(c.req.method) && access.via === "cookie")
+      await checkCsrf(c, auth, c.var.storefront.origins, { sessionToken: cred.token, json: false }, t);
+    c.set("access", access);
+    return next();
+  };
+}
+
+/**
+ * A cart route's credentials, unread (§6.2): the cart object re-proves the
+ * key and the customer inside the batch it sends anyway, so checkout stays a
+ * claim and a commit. CSRF still comes first, here: the token binds the
+ * session token's digest, and a cookie mutation must carry an `Origin`,
+ * which the cart's batch then requires its storefront to list.
+ */
+async function cartProof(c: Context, auth: AuthDeps, now: number): Promise<StoreProof> {
+  const presented = c.req.header("x-kedge-key");
+  if (!presented) throw new KedgeError("UNAUTHORIZED", "Missing publishable key (x-kedge-key)");
+  const key = await auth.access.keyProof(presented);
+  if (!key) throw new KedgeError("KEY_INVALID", "x-kedge-key takes a publishable key");
+  const origin = c.req.header("origin") ?? null;
+  const cred = sessionCredential(c, "customer");
+  if (cred?.via === "cookie" && !isSafe(c.req.method))
+    await checkCsrf(c, auth, origin ? [origin] : [], { sessionToken: cred.token, json: false }, now);
+  if (cred && !cred.token.startsWith("kcu_"))
+    throw new KedgeError("UNAUTHORIZED", "Your session has ended; sign in again");
+  // A key is at most 255 bytes, refused before any mutation (§8, Spree's bound).
+  const idem = c.req.header("idempotency-key") ?? null;
+  if (idem !== null && (idem.length === 0 || new TextEncoder().encode(idem).length > 255))
+    throw new KedgeError("BAD_REQUEST", "An Idempotency-Key is 1 to 255 bytes");
+  return {
+    key: { ...key, origin },
+    customer: cred ? { tokenDigest: await digestToken(cred.token) } : null,
+    ...(idem !== null && !isSafe(c.req.method) ? { idempotencyKey: idem } : {}),
+  };
+}
+
+/** The publishable key's storefront, refusing an `Origin` it doesn't list. */
+export async function storefrontOf(c: Context, auth: AuthDeps, now: number): Promise<RequestStorefront> {
+  const presented = c.req.header("x-kedge-key");
+  if (!presented) throw new KedgeError("UNAUTHORIZED", "Missing publishable key (x-kedge-key)");
+  if (!presented.startsWith("pk_")) throw new KedgeError("KEY_INVALID", "x-kedge-key takes a publishable key");
+  const found = await resolveKey(c, auth, presented, now);
+  const key = found.key as AccessKey;
+  if (key.type !== "publishable" || !key.storefrontId)
+    throw new KedgeError("KEY_INVALID", "x-kedge-key takes a publishable key");
+  const origin = c.req.header("origin");
+  if (origin && !key.origins.includes(origin))
+    // The same answer a cart route's batch gives (§6.2): the key isn't valid from this origin.
+    throw new KedgeError("KEY_INVALID", "This key's storefront doesn't allow this origin");
+  return { keyId: key.id, storefrontId: key.storefrontId, origins: key.origins };
+}