@kedge/server 0.0.0-stage → 0.9.0

package/src/app.ts

@@ -0,0 +1,798 @@
+// The HTTP layer (docs/06): /store, /admin, /health. Platform-agnostic; the
+// runtime supplies the cart gateway and stores.
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import {
+  actorOf,
+  CustomFields,
+  checkedView,
+  deriveToken,
+  ERROR_CODES,
+  type ErrorCode,
+  holds,
+  isKedgeError,
+  isPluginErrorCode,
+  KedgeError,
+  logCodeOf,
+  type OrderView,
+  type Principal,
+  type StoreOrder,
+  UncertainOutcomeError,
+  verifyToken,
+} from "@kedge/core";
+import type { Context, MiddlewareHandler } from "hono";
+import { cors } from "hono/cors";
+import { HTTPException } from "hono/http-exception";
+import { AdminPermissions, adminGate, type KedgeEnv, sessionCookie, storeGate } from "./access";
+import { adminRoutes, orderRecordJson } from "./admin-routes";
+import { AUTHZ_HEADER, checkAdminBuild, SESSION_HEADER } from "./admin-shell";
+import { authRoutes } from "./auth-routes";
+import { capacityRoutes } from "./capacity-routes";
+import { entityRoutes } from "./entity-routes";
+import { jsonBody, ok } from "./http";
+import { metaRoutes } from "./meta-routes";
+import { pluginRoutes } from "./plugin-routes";
+import { relayRoutes } from "./relay-routes";
+import { trackRoutes } from "./track-routes";
+import type { AppDeps, CartView, Result } from "./types";
+import defaultOrderView from "./units/store.order.view";
+import defaultProductView from "./units/store.product.view";
+import { webhookRoutes } from "./webhook-routes";
+
+const CART_ID = /^cart_[0-9A-HJKMNP-TV-Z]{26}$/;
+const ORDER_ID = /^ord_[0-9A-HJKMNP-TV-Z]{26}$/;
+
+const money = (amount: number, currency_code: string) => ({ amount, currency_code });
+
+const iso = (ms: number | null) => (ms === null ? null : new Date(ms).toISOString());
+
+/**
+ * A cart view as JSON. During the first deployment of P0.3 (`legacy`), the
+ * view can come from an object still running P0.2, which has none of P0.3's
+ * fields: each defaults to what a P0.2 cart means (§1.6), so the response of a
+ * mutation that saved is never an error.
+ */
+function cartJson(c: CartView) {
+  const m = (a: number | null | undefined) => (a === null || a === undefined ? null : money(a, c.currency_code));
+  const t = c.totals;
+  return {
+    id: c.id,
+    status: c.status,
+    currency_code: c.currency_code,
+    email: c.email,
+    revision: c.revision,
+    locale: c.locale ?? "en",
+    custom: c.custom ?? {},
+    consents: c.consents ?? {},
+    pricing: c.pricing ?? "ok",
+    lines: c.lines.map((l) => ({
+      id: l.id ?? null,
+      variant_id: l.variant_id,
+      kind: l.kind ?? "item",
+      parent_line_id: l.parent_line_id ?? null,
+      quantity_mode: l.quantity_mode ?? "own",
+      quantity_per_parent: l.quantity_per_parent ?? null,
+      period_start: iso(l.period_start ?? null),
+      period_end: iso(l.period_end ?? null),
+      custom: l.custom ?? {},
+      sku: l.sku,
+      title: l.title,
+      charge_class: l.charge_class ?? "revenue",
+      unit_price: m(l.unit_amount),
+      quantity: l.quantity,
+      total: m(l.line_total),
+      breakdown: l.breakdown ?? null,
+    })),
+    totals: t && {
+      subtotal: m(t.subtotal),
+      discount_total: m(t.discount_total),
+      shipping_total: m(t.shipping_total),
+      fee_total: m(t.fee_total),
+      tax_total: m(t.tax_total),
+      total: m(t.total),
+      revenue_total: m(t.revenue_total ?? t.total),
+      deposit_total: m(t.deposit_total ?? 0),
+    },
+    requirements: c.requirements,
+    order_id: c.order_id,
+  };
+}
+
+/** An ISO instant in the API, epoch ms inside (§1.1). */
+const Instant = z.iso.datetime({ offset: true }).transform((v) => Date.parse(v));
+const LINE_ID = /^cl_[0-9A-Za-z_]{1,64}$/;
+// Custom-field values arrive as parsed JSON and are checked by core's field
+// rules (P0.3 §4.1). Not `z.json()`: its recursive schema overflows the stack
+// when the OpenAPI document is generated (the P0.7 build found the document
+// had never rendered).
+const Custom = z.record(z.string().max(64), z.unknown());
+
+/**
+ * An order as JSON for one reader: its fields projected by read scope (§4.2),
+ * so a staff-only field reaches the admin API and never the store API.
+ */
+function orderJson(o: OrderView, fields: CustomFields, reader: Principal): StoreOrder {
+  const m = (a: number) => money(a, o.currency);
+  return {
+    id: o.id,
+    status: o.status,
+    payment_status: o.paymentStatus,
+    number: o.number,
+    currency_code: o.currency,
+    email: o.email,
+    locale: o.locale ?? "en",
+    subtotal: m(o.subtotal),
+    tax_total: m(o.taxTotal ?? 0),
+    total: m(o.total),
+    revenue_total: m(o.revenueTotal ?? o.total),
+    deposit_total: m(o.depositTotal ?? 0),
+    expires_at: o.expiresAt,
+    placed_at: o.placedAt,
+    place_by: iso(o.placeBy ?? null),
+    custom: fields.project("order", o.custom ?? {}, reader),
+    lines: o.lines.map((l) => ({
+      id: l.id,
+      variant_id: l.variantId,
+      kind: l.kind ?? "item",
+      parent_line_id: l.parentLineId ?? null,
+      quantity_mode: l.quantityMode ?? "own",
+      quantity_per_parent: l.quantityPerParent ?? null,
+      period_start: iso(l.periodStart ?? null),
+      period_end: iso(l.periodEnd ?? null),
+      charge_class: l.chargeClass ?? "revenue",
+      sku: l.sku,
+      title: l.title,
+      unit_price: m(l.unitAmount),
+      quantity: l.quantity,
+      custom: fields.project("order_line", l.custom ?? {}, reader),
+    })),
+  };
+}
+
+/** Errors returned as data by the Durable Object become KedgeErrors again here. */
+function unwrap<T>(r: Result<T>): T {
+  if (r.ok) return r.value;
+  const { code, message, status, details } = r.error;
+  // A plugin's registered refusal keeps its code and status (409 for spent
+  // points), never a 500: the error map is the plugin's contract with shoppers.
+  if (isPluginErrorCode(code) && status !== undefined && status >= 400 && status <= 599)
+    throw KedgeError.plugin(code, status, message, details ?? {});
+  throw new KedgeError((Object.hasOwn(ERROR_CODES, code) ? code : "INTERNAL") as ErrorCode, message, details ?? {});
+}
+
+const CartIdParam = z.object({ id: z.string().regex(CART_ID) });
+
+export function createApp(deps: AppDeps) {
+  const { secrets, carts, products, orders, ids, settings, auth } = deps;
+  const productView = deps.overrides?.["store.product.view"] ?? defaultProductView;
+  const orderView = deps.overrides?.["store.order.view"] ?? defaultOrderView;
+  const now = () => deps.clock.now();
+  const features = deps.lineFeatures ?? "on";
+  /** In `legacy` mode the P0.3 routes don't exist yet: the previous object may be serving (§1.6). */
+  const notInLegacy = () => {
+    if (features === "legacy") throw new KedgeError("NOT_FOUND", "Not found");
+  };
+  /** In `frozen` mode nothing P0.2 couldn't represent is created; existing state stays usable (§1.6). */
+  const frozen = (creates: boolean) => {
+    if (features === "frozen" && creates)
+      throw new KedgeError("FEATURE_FROZEN", "This store isn't accepting new kinds of lines right now");
+  };
+  const identityKeys = new Set(deps.identityKeys ?? []);
+  const setsIdentity = (custom: Record<string, unknown> | undefined) =>
+    Object.keys(custom ?? {}).some((k) => identityKeys.has(k));
+  const app = new OpenAPIHono<KedgeEnv>({
+    defaultHook: (result) => {
+      if (!result.success) {
+        throw new KedgeError("BAD_REQUEST", "Invalid request", {
+          issues: result.error.issues.map((i) => ({ path: i.path.join("."), message: i.message })),
+        });
+      }
+    },
+  });
+
+  app.onError((err, c) => {
+    if (isKedgeError(err)) {
+      if (err.code === "OVERLOADED" || err.code === "OUTCOME_UNKNOWN" || err.code === "TIMEOUT")
+        c.header("Retry-After", "1");
+      return c.json(err.toJSON(), err.status as 400);
+    }
+    // Framework errors below 500 (e.g. a malformed JSON body) are the caller's: 400, not 500.
+    if (err instanceof HTTPException && err.status < 500) {
+      return c.json(new KedgeError("BAD_REQUEST", "Malformed request").toJSON(), 400);
+    }
+    if (err instanceof UncertainOutcomeError) {
+      c.header("Retry-After", "1");
+      return c.json(
+        new KedgeError("OUTCOME_UNKNOWN", "The write may or may not have happened; check before retrying").toJSON(),
+        503,
+      );
+    }
+    // Unknown failures keep their message out of the response (it may carry internals).
+    // Its code only: an unexpected error's message can carry whatever the code that threw it held (p0.8 §4.5).
+    // kedge-allow no-console: named fields and the error's code only
+    console.error(JSON.stringify({ level: "error", event: "unhandled", code: logCodeOf(err) }));
+    return c.json(new KedgeError("INTERNAL", "Internal error").toJSON(), 500);
+  });
+  app.notFound(() => {
+    throw new KedgeError("NOT_FOUND", "Not found");
+  });
+
+  // `maintenance` is the cutover's signal (p0.8 §6.3): the maintenance Worker answers true.
+  app.get("/health", (c) => c.json({ ok: true, maintenance: false }));
+
+  // CORS runs before authentication: a browser's preflight carries no credentials,
+  // so a credential check first would refuse it and the real request would never be sent.
+  // The headers it sets stay on every response, errors included.
+  const headers = ["Authorization", "Content-Type", "Idempotency-Key", "X-Kedge-CSRF", "X-Kedge-Session-Mode"];
+  const methods = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+  const admin = new Set(auth.adminOrigins);
+  // An admin on another origin speaks P0.9's protocol too (p0.9 §4.1): its two
+  // request headers allowed, and the two answer headers it compares exposed.
+  const adminCors = cors({
+    origin: (origin) => (admin.has(origin) ? origin : null),
+    allowMethods: methods,
+    allowHeaders: [...headers, "X-Kedge-Admin-Build", "X-Kedge-Authz-Expect"],
+    exposeHeaders: [SESSION_HEADER, AUTHZ_HEADER],
+    credentials: true,
+    maxAge: 600,
+  });
+  app.use("/admin/*", adminCors);
+  app.use("/auth/admin/*", adminCors);
+  // A stale admin's ceremony is refused before it runs, as its admin calls are (p0.9 §2.4).
+  app.use("/auth/admin/*", async (c, next) => {
+    if (c.req.method !== "OPTIONS") checkAdminBuild(c, auth.adminBuild ?? null);
+    await next();
+  });
+  // A preflight carries no key, so it is answered for an origin any storefront
+  // with an unrevoked key lists (§6.2). The actual request's origin is echoed:
+  // the store gate refuses an origin its own key's storefront doesn't list
+  // before anything is read, so the echo never exposes a response to it.
+  const storeCors = cors({
+    origin: async (origin, c) => {
+      if (c.req.method !== "OPTIONS") return origin;
+      return (await auth.access.storefrontOrigins(now())).has(origin) ? origin : null;
+    },
+    allowMethods: methods,
+    allowHeaders: [...headers, "X-Cart-Token", "X-Order-Token", "X-Kedge-Key"],
+    credentials: true,
+    maxAge: 600,
+  });
+  app.use("/store/*", storeCors);
+  app.use("/auth/store/*", storeCors);
+  const perms = new AdminPermissions();
+  app.use("/admin/*", adminGate(auth, perms, now));
+  app.use("/store/*", storeGate(auth, now));
+  authRoutes(app, auth, now);
+
+  // The cart token is checked here, before the cart's Durable Object is touched:
+  // touching it would create it, so a check inside the object comes too late.
+  const cartToken: MiddlewareHandler = async (c, next) => {
+    const id = c.req.param("id") ?? "";
+    if (!CART_ID.test(id) || !(await verifyToken(secrets.cartTokenSecret, "cart", id, c.req.header("x-cart-token")))) {
+      throw new KedgeError("UNAUTHORIZED", "Missing or invalid cart token");
+    }
+    await next();
+  };
+  app.use("/store/carts/:id", cartToken);
+  app.use("/store/carts/:id/*", cartToken);
+
+  const token = (c: Context) => c.req.header("x-cart-token") ?? "";
+  /** A cart call's result; a session the cart renewed refreshes the customer's cookie (§2.3). */
+  const unwrapCart = <T>(c: Context<KedgeEnv>, r: Result<T>): T => {
+    const cookie = c.var.cartCookie;
+    if (r.ok && r.session && cookie)
+      c.header("set-cookie", sessionCookie("customer", cookie, r.session.expiresAt, now()), { append: true });
+    return unwrap(r);
+  };
+  const fields = deps.fields ?? CustomFields.none;
+  const withOrderToken = async (order: OrderView) => ({
+    ...orderJson(order, fields, "store"),
+    token: await deriveToken(secrets.orderTokenSecret, "order", order.id),
+  });
+
+  // --- store ---
+  app.openapi(
+    createRoute({
+      method: "get",
+      path: "/store/products/{handle}",
+      request: { params: z.object({ handle: z.string().min(1) }), query: z.object({ currency: z.string().length(3) }) },
+      responses: ok("A product"),
+    }),
+    async (c) => {
+      const { handle } = c.req.valid("param");
+      const { currency } = c.req.valid("query");
+      const p = await products.productByHandle(handle, currency);
+      if (!p) throw new KedgeError("NOT_FOUND", "Product not found");
+      // The store's own view, if it ejected one (p0.8 §7), over what any shopper may see.
+      const id = p.id;
+      return c.json(checkedView("store.product.view", id, productView(p)), 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/store/carts",
+      request: jsonBody(
+        z.object({
+          currency_code: z.string().length(3),
+          email: z.email().nullable().optional(),
+          locale: z.string().min(2).max(35).optional(),
+        }),
+      ),
+      responses: ok("A new cart and its token"),
+    }),
+    async (c) => {
+      const body = c.req.valid("json");
+      const id = ids.next("cart");
+      const cart = unwrapCart(
+        c,
+        await carts.create(id, c.var.proof, {
+          currency: body.currency_code,
+          email: body.email ?? null,
+          ...(features !== "legacy" && body.locale ? { locale: body.locale } : {}),
+        }),
+      );
+      return c.json({ ...cartJson(cart), token: await deriveToken(secrets.cartTokenSecret, "cart", id) }, 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "get",
+      path: "/store/carts/{id}",
+      request: { params: CartIdParam },
+      responses: ok("A cart"),
+    }),
+    async (c) => c.json(cartJson(unwrapCart(c, await carts.get(c.req.valid("param").id, token(c), c.var.proof))), 200),
+  );
+
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/store/carts/{id}/lines",
+      request: {
+        params: CartIdParam,
+        ...jsonBody(
+          z.object({
+            variant_id: z.string().min(1),
+            quantity: z.number().int().min(1).max(100_000).optional(),
+            kind: z.string().min(1).max(64).optional(),
+            parent_line_id: z.string().regex(LINE_ID).optional(),
+            quantity_mode: z.enum(["own", "per_parent"]).optional(),
+            quantity_per_parent: z.number().int().min(1).max(100_000).optional(),
+            period_start: Instant.optional(),
+            period_end: Instant.optional(),
+            custom: Custom.optional(),
+          }),
+        ),
+      },
+      responses: ok("The cart"),
+    }),
+    async (c) => {
+      const b = c.req.valid("json");
+      const id = c.req.valid("param").id;
+      if (features === "legacy") {
+        if (b.quantity === undefined) throw new KedgeError("BAD_REQUEST", "quantity is required");
+        return c.json(
+          cartJson(unwrapCart(c, await carts.setLine(id, token(c), c.var.proof, b.variant_id, b.quantity, "add"))),
+          200,
+        );
+      }
+      frozen(
+        (b.kind !== undefined && b.kind !== "item") ||
+          b.parent_line_id !== undefined ||
+          b.period_start !== undefined ||
+          setsIdentity(b.custom),
+      );
+      const cart = await carts.addLine(id, token(c), c.var.proof, {
+        variantId: b.variant_id,
+        kind: b.kind,
+        parentId: b.parent_line_id ?? null,
+        quantityMode: b.quantity_mode,
+        quantity: b.quantity,
+        quantityPerParent: b.quantity_per_parent ?? null,
+        periodStart: b.period_start ?? null,
+        periodEnd: b.period_end ?? null,
+        custom: b.custom as Record<string, never> | undefined,
+      });
+      return c.json(cartJson(unwrapCart(c, cart)), 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/store/carts/{id}/lines/remove",
+      request: {
+        params: CartIdParam,
+        ...jsonBody(z.object({ line_ids: z.array(z.string().regex(LINE_ID)).min(1).max(100) })),
+      },
+      responses: ok("The cart"),
+    }),
+    async (c) => {
+      notInLegacy();
+      const cart = await carts.removeLines(
+        c.req.valid("param").id,
+        token(c),
+        c.var.proof,
+        c.req.valid("json").line_ids,
+      );
+      return c.json(cartJson(unwrapCart(c, cart)), 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "delete",
+      path: "/store/carts/{id}/lines/{line_id}",
+      request: { params: CartIdParam.extend({ line_id: z.string().regex(LINE_ID) }) },
+      responses: ok("The cart"),
+    }),
+    async (c) => {
+      notInLegacy();
+      const p = c.req.valid("param");
+      return c.json(cartJson(unwrapCart(c, await carts.removeLines(p.id, token(c), c.var.proof, [p.line_id]))), 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "patch",
+      // A line id from P0.3 on; a variant id in `legacy` mode, as P0.2 served it (§1.6).
+      path: "/store/carts/{id}/lines/{line}",
+      request: {
+        params: CartIdParam.extend({ line: z.string().min(1) }),
+        ...jsonBody(
+          z.object({
+            quantity: z.number().int().min(0).max(100_000).optional(),
+            quantity_per_parent: z.number().int().min(1).max(100_000).optional(),
+            period_start: Instant.nullable().optional(),
+            period_end: Instant.nullable().optional(),
+            custom: Custom.optional(),
+          }),
+        ),
+      },
+      responses: ok("The cart"),
+    }),
+    async (c) => {
+      const p = c.req.valid("param");
+      const b = c.req.valid("json");
+      if (features === "legacy") {
+        if (b.quantity === undefined) throw new KedgeError("BAD_REQUEST", "quantity is required");
+        return c.json(
+          cartJson(unwrapCart(c, await carts.setLine(p.id, token(c), c.var.proof, p.line, b.quantity, "set"))),
+          200,
+        );
+      }
+      if (!LINE_ID.test(p.line))
+        throw new KedgeError("LINE_NOT_FOUND", "No such line in this cart", { line_id: p.line });
+      frozen((b.period_start !== undefined && b.period_start !== null) || setsIdentity(b.custom));
+      const cart = await carts.changeLine(p.id, token(c), c.var.proof, p.line, {
+        quantity: b.quantity,
+        quantityPerParent: b.quantity_per_parent,
+        periodStart: b.period_start,
+        periodEnd: b.period_end,
+        custom: b.custom as Record<string, never> | undefined,
+      });
+      return c.json(cartJson(unwrapCart(c, cart)), 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "patch",
+      path: "/store/carts/{id}",
+      request: {
+        params: CartIdParam,
+        ...jsonBody(
+          z.object({
+            email: z.email().nullable().optional(),
+            locale: z.string().min(2).max(35).optional(),
+            custom: Custom.optional(),
+            consents: z
+              .record(
+                z.string().max(40),
+                z.object({ revision_id: z.string().max(40), typed_name: z.string().max(400) }).nullable(),
+              )
+              .optional(),
+          }),
+        ),
+      },
+      responses: ok("The cart"),
+    }),
+    async (c) => {
+      const id = c.req.valid("param").id;
+      const b = c.req.valid("json");
+      if (features === "legacy") {
+        if (b.email === undefined) throw new KedgeError("BAD_REQUEST", "email is required");
+        return c.json(cartJson(unwrapCart(c, await carts.setEmail(id, token(c), c.var.proof, b.email))), 200);
+      }
+      const cart = await carts.update(id, token(c), c.var.proof, {
+        ...(b.email !== undefined ? { email: b.email } : {}),
+        ...(b.locale !== undefined ? { locale: b.locale } : {}),
+        ...(b.custom !== undefined ? { custom: b.custom as Record<string, never> } : {}),
+        ...(b.consents !== undefined ? { consents: b.consents } : {}),
+      });
+      return c.json(cartJson(unwrapCart(c, cart)), 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "get",
+      path: "/store/policies/{policy}",
+      request: {
+        params: z.object({ policy: z.string().regex(/^[a-z][a-z0-9_]{0,39}$/) }),
+        query: z.object({ locale: z.string().min(2).max(35).default("en") }),
+      },
+      responses: ok("The current revision"),
+    }),
+    async (c) => {
+      const r = await settings.currentRevision(c.req.valid("param").policy, c.req.valid("query").locale);
+      if (!r) throw new KedgeError("NOT_FOUND", "No revision of this policy in this locale");
+      return c.json(
+        { id: r.id, policy: r.policy, version: r.version, locale: r.locale, body: r.body, digest: r.digest },
+        200,
+      );
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/store/carts/{id}/complete",
+      request: { params: CartIdParam, ...jsonBody(z.object({ expected_total: z.number().int() })) },
+      responses: ok("The order and its token"),
+    }),
+    async (c) => {
+      const { order } = unwrapCart(
+        c,
+        await carts.complete(c.req.valid("param").id, token(c), c.var.proof, c.req.valid("json").expected_total),
+      );
+      return c.json(await withOrderToken(order), 200);
+    },
+  );
+
+  app.openapi(
+    createRoute({
+      method: "get",
+      path: "/store/orders/{id}",
+      request: { params: z.object({ id: z.string().regex(ORDER_ID) }) },
+      responses: ok("An order"),
+    }),
+    async (c) => {
+      const { id } = c.req.valid("param");
+      // The order token, or the owning customer's session (§6.2). Another
+      // customer's order is NOT_FOUND, never FORBIDDEN, so ids can't be probed.
+      const presented = c.req.header("x-order-token");
+      const principal = c.var.access.ctx.principal;
+      if (presented !== undefined || principal.kind !== "customer") {
+        if (!(await verifyToken(secrets.orderTokenSecret, "order", id, presented)))
+          throw new KedgeError("UNAUTHORIZED", "Missing or invalid order token");
+      }
+      const order = await orders.get(id);
+      if (!order) throw new KedgeError("NOT_FOUND", "Order not found");
+      if (presented === undefined && order.customerId !== (principal.kind === "customer" ? principal.id : undefined))
+        throw new KedgeError("NOT_FOUND", "Order not found");
+      // Ownership proved by session reads as the customer (§5.4); a token alone reads as its holder.
+      const owner = presented === undefined;
+      // Projected for its reader first, then the store's view, if it ejected one (p0.8 §7.1).
+      const projected = orderJson(order, fields, owner ? "customer" : "store");
+      const viewed = projected.id;
+      return c.json(checkedView("store.order.view", viewed, orderView(projected)), 200);
+    },
+  );
+
+  /** A store route only a signed-in customer reaches. */
+  const customerOf = (c: Context<KedgeEnv>) => {
+    const p = c.var.access.ctx.principal;
+    if (p.kind !== "customer") throw new KedgeError("UNAUTHORIZED", "Sign in first");
+    return p;
+  };
+  app.openapi(
+    createRoute({ method: "get", path: "/store/customers/me", responses: ok("The signed-in customer") }),
+    async (c) => {
+      const me = await auth.ceremonies.customerProfile(customerOf(c).id);
+      if (!me) throw new KedgeError("UNAUTHORIZED", "Sign in first");
+      return c.json({ id: me.id, email: me.email, created_at: new Date(me.createdAt).toISOString() }, 200);
+    },
+  );
+  if (deps.orderQuery) {
+    const orderQuery = deps.orderQuery;
+    app.openapi(
+      createRoute({
+        method: "get",
+        path: "/store/customers/me/orders",
+        request: {
+          query: z.object({
+            cursor: z.string().max(2048).optional(),
+            limit: z.coerce.number().int().min(1).max(100).optional(),
+          }),
+        },
+        responses: ok("The customer's own orders, newest first"),
+      }),
+      async (c) => {
+        customerOf(c);
+        const q = c.req.valid("query");
+        // Owner-scoped through the registry (§5.1): the customer's rows, nobody else's.
+        const page = await orderQuery.list(c.var.access.ctx, {
+          sort: { field: "created_at", direction: "desc" },
+          expand: ["lines"],
+          cursor: q.cursor ?? null,
+          ...(q.limit !== undefined ? { limit: q.limit } : {}),
+        });
+        return c.json({ ...page, data: page.data.map(orderRecordJson) }, 200);
+      },
+    );
+  }
+
+  // --- admin ---
+  /** A creating command's retry scope (p0.5 §8): the caller and its required Idempotency-Key. */
+  const retry = (c: Context<KedgeEnv>) => ({
+    principal: actorOf(c.var.access.ctx.principal),
+    key: c.req.header("idempotency-key") ?? null,
+  });
+  const NewProduct = z.object({
+    title: z.string().min(1),
+    handle: z.string().regex(/^[a-z0-9-]+$/),
+    variants: z
+      .array(
+        z.object({
+          sku: z.string().min(1),
+          title: z.string().min(1),
+          prices: z.record(z.string().length(3), z.number().int().min(0)),
+          stock: z.record(z.string().min(1), z.number().int().min(0)),
+          allowed_kinds: z.array(z.string().min(1).max(64)).min(1).max(32).optional(),
+          inventory: z.boolean().optional(),
+        }),
+      )
+      .min(1)
+      .max(100),
+  });
+  app.openapi(
+    perms.declare(
+      { permission: "product:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/products",
+        request: jsonBody(NewProduct),
+        responses: ok("The product's ids"),
+      }),
+    ),
+    async (c) => {
+      const b = c.req.valid("json");
+      return c.json(
+        await products.createProduct(
+          { ...b, variants: b.variants.map(({ allowed_kinds, ...v }) => ({ ...v, allowedKinds: allowed_kinds })) },
+          retry(c),
+        ),
+        200,
+      );
+    },
+  );
+
+  app.openapi(
+    perms.declare(
+      "product:write",
+      createRoute({
+        method: "patch",
+        path: "/admin/variants/{id}",
+        request: {
+          params: z.object({ id: z.string().min(1) }),
+          ...jsonBody(z.object({ allowed_kinds: z.array(z.string().min(1).max(64)).min(1).max(32) })),
+        },
+        responses: ok("The variant's kinds"),
+      }),
+    ),
+    async (c) => {
+      const kinds = c.req.valid("json").allowed_kinds;
+      await products.setAllowedKinds(c.req.valid("param").id, kinds);
+      return c.json({ id: c.req.valid("param").id, allowed_kinds: [...new Set(kinds)] }, 200);
+    },
+  );
+
+  // P0.3: the store's tax rate pair (§3.2) and its policies (§5.1).
+  const Tax = z.object({
+    inclusive: z.boolean(),
+    rates: z.object({
+      revenue: z.number().int().min(0).max(1_000_000),
+      deposit: z.number().int().min(0).max(1_000_000),
+    }),
+  });
+  app.openapi(
+    perms.declare("tax:read", createRoute({ method: "get", path: "/admin/tax", responses: ok("The tax setting") })),
+    async (c) => c.json(await settings.tax(), 200),
+  );
+  app.openapi(
+    perms.declare(
+      "tax:write",
+      createRoute({ method: "put", path: "/admin/tax", request: jsonBody(Tax), responses: ok("The tax setting") }),
+    ),
+    async (c) => c.json(await settings.setTax(c.req.valid("json")), 200),
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "policy:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/policies/{policy}/revisions",
+        request: {
+          params: z.object({ policy: z.string().regex(/^[a-z][a-z0-9_]{0,39}$/) }),
+          ...jsonBody(z.object({ locale: z.string().min(2).max(35), body: z.string().min(1).max(200_000) })),
+        },
+        responses: ok("The new revision"),
+      }),
+    ),
+    async (c) =>
+      c.json(await settings.publishRevision(c.req.valid("param").policy, c.req.valid("json"), retry(c)), 200),
+  );
+  app.openapi(
+    perms.declare(
+      "settings:read",
+      createRoute({ method: "get", path: "/admin/checkout/policies", responses: ok("The required policies") }),
+    ),
+    async (c) => c.json({ policies: await settings.requiredPolicies() }, 200),
+  );
+  app.openapi(
+    perms.declare(
+      "settings:write",
+      createRoute({
+        method: "put",
+        path: "/admin/checkout/policies",
+        request: jsonBody(z.object({ policies: z.array(z.string()).max(5) })),
+        responses: ok("The required policies"),
+      }),
+    ),
+    async (c) => c.json({ policies: await settings.setRequiredPolicies(c.req.valid("json").policies) }, 200),
+  );
+
+  // Staff placement: a stand-in for payment confirmation that records no payment (§2.1).
+  app.openapi(
+    perms.declare(
+      "order:place",
+      createRoute({
+        method: "post",
+        path: "/admin/orders/{id}/place",
+        request: { params: z.object({ id: z.string().regex(ORDER_ID) }) },
+        responses: ok("The placed order"),
+      }),
+    ),
+    async (c) => {
+      const id = c.req.valid("param").id;
+      const { placed } = await orders.place(id, actorOf(c.var.access.ctx.principal));
+      // The placed order as this caller may see it. Placing doesn't need order:read
+      // (codex code r3): a caller without it gets the outcome and the id, never a 403
+      // for a placement that committed.
+      const readable = holds(c.var.access.ctx.grants, "order:read");
+      const row = readable && deps.orderQuery ? await deps.orderQuery.get(c.var.access.ctx, id) : null;
+      return c.json({ placed, order: row ? orderRecordJson(row) : { id } }, 200);
+    },
+  );
+
+  capacityRoutes(app, deps, perms);
+  if (deps.deliveries) relayRoutes(app, deps.deliveries, perms);
+  webhookRoutes(app, perms, {
+    ...(deps.admin ? { admin: deps.admin } : {}),
+    ...(deps.webhooks ? { webhooks: deps.webhooks } : {}),
+    ...(deps.calendar ? { calendar: deps.calendar } : {}),
+    ...(deps.previewCaptures ? { previewCaptures: deps.previewCaptures } : {}),
+    now,
+  });
+  adminRoutes(app, perms, deps.admin, deps.orderQuery, deps.keyring, now);
+  if (deps.tracks) trackRoutes(app, perms, deps.tracks);
+  if (deps.entities) entityRoutes(app, perms, deps.entities);
+  // P0.9 (§4.4, §5): who the caller is, and the resources the admin is built from.
+  metaRoutes(app, perms, {
+    auth,
+    ...(deps.entities ? { entities: deps.entities } : {}),
+    ...(deps.adminMeta?.tracksOn ? { tracksOn: deps.adminMeta.tracksOn } : {}),
+    orders: deps.orderQuery !== undefined,
+    auditLog: deps.admin !== undefined,
+  });
+  if (deps.plugins) pluginRoutes(app, perms, deps.plugins);
+
+  app.doc("/admin/openapi.json", { openapi: "3.1.0", info: { title: "Kedge", version: "0.0.0" } });
+  // Boot refuses an /admin route without a declared permission (§3.3).
+  perms.verify(app.routes);
+  return Object.assign(app, { permissions: perms });
+}