@kedge/server 0.0.0-stage → 0.10.0

package/src/admin-routes.ts

@@ -0,0 +1,813 @@
+// P0.5's admin surface (p0.5-auth-and-access.md §3, §4, §5.2, §7.2): staff,
+// roles, invites, storefronts, API keys, the audit log, and order reads
+// through the resource registry. Each route declares its permission; the
+// store re-proves every authority rule inside its batch, so the route's check
+// is only the fast refusal.
+import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
+import { actorOf, ENTITY_LIMITS, KedgeError, ORDER, ORDER_LINE, type Resource } from "@kedge/core";
+import type { Context } from "hono";
+import { type AdminPermissions, clientOf, type KedgeEnv } from "./access";
+import { jsonBody, ok } from "./http";
+import type { AdminRequest, AdminStore, KeyringAdmin, OrderFilter, OrderQuery } from "./types";
+
+const ID = z.string().min(1).max(64);
+
+interface AuditEntry {
+  id: string;
+  batchId: string;
+  actor: string;
+  action: string;
+  entityType: string | null;
+  entityId: string | null;
+  changes: unknown;
+  ip: string | null;
+  userAgent: string | null;
+  createdAt: number;
+}
+const Instant = z.iso.datetime({ offset: true }).transform((v) => Date.parse(v));
+const iso = (ms: unknown) => (typeof ms === "number" ? new Date(ms).toISOString() : null);
+const Grant = z.object({
+  permission: z.string().min(3).max(128),
+  row_scope: z.enum(["all", "self", "location"]).default("all"),
+});
+const Grants = z.array(Grant).max(128);
+const RoleRefs = z.array(z.object({ id: ID, version: z.number().int().min(1) })).max(16);
+const Origins = z.array(z.url().max(255)).max(16);
+const grants = (g: z.infer<typeof Grants>) => g.map((x) => ({ permission: x.permission, rowScope: x.row_scope }));
+
+/** Instants the order API has always given as ISO strings (the cart's and P0.3's order view). */
+const ISO_FIELDS = new Set(["period_start", "period_end", "place_by"]);
+
+/** A registry row in the API's conventions: money as `{ amount, currency_code }`, never a bare integer. */
+function moneyFields(resource: Resource, row: Record<string, unknown>, currency: unknown): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(row)) {
+    const f = resource.fields[k];
+    if (f?.class === "financial" && typeof v === "number") out[k] = { amount: v, currency_code: currency };
+    else if (ISO_FIELDS.has(k)) out[k] = iso(v);
+    else out[k] = v;
+  }
+  return out;
+}
+
+export function orderRecordJson(row: Record<string, unknown>): Record<string, unknown> {
+  const currency = row.currency_code;
+  const out = moneyFields(ORDER, row, currency);
+  if (Array.isArray(row.lines))
+    out.lines = (row.lines as Record<string, unknown>[]).map((l) => moneyFields(ORDER_LINE, l, currency));
+  return out;
+}
+
+/**
+ * An issued invite, with the admin's link to it (p0.9 §3.5) on the origin the
+ * request came to, which is always an admin origin (§4.1). The token rides in
+ * the fragment, so opening the link puts it in no server log or Referer.
+ */
+const issuedInvite = (c: Context, i: { id: string; token: string; expiresAt: number }) => ({
+  id: i.id,
+  token: i.token,
+  expires_at: iso(i.expiresAt),
+  invite_url: `${new URL(c.req.url).origin}/app/invite#${i.token}`,
+});
+const issuedKey = (k: { id: string; key: string; tokenPrefix: string }) => ({
+  id: k.id,
+  key: k.key,
+  token_prefix: k.tokenPrefix,
+});
+
+export function adminRoutes(
+  app: OpenAPIHono<KedgeEnv>,
+  perms: AdminPermissions,
+  admin: AdminStore | undefined,
+  orderQuery: OrderQuery | undefined,
+  keyring: KeyringAdmin | undefined,
+  now: () => number,
+): void {
+  const ctx = (c: Context<KedgeEnv>) => c.var.access.ctx;
+  const req = (c: Context<KedgeEnv>): AdminRequest => {
+    const client = clientOf(c);
+    return { idempotencyKey: c.req.header("idempotency-key") ?? null, ip: client.ip, userAgent: client.userAgent };
+  };
+  /**
+   * A creating command requires its key (docs/06, p0.5 §8): a key, an invite
+   * or a role made twice by a retry whose response was lost would leave a live
+   * credential nobody holds, or exhaust a storefront's four keys.
+   */
+  const keyed = (c: Context<KedgeEnv>): AdminRequest => {
+    const r = req(c);
+    const k = r.idempotencyKey;
+    if (!k || new TextEncoder().encode(k).length > 255)
+      throw new KedgeError("BAD_REQUEST", "An Idempotency-Key header (1 to 255 bytes) is required", {
+        requirement: "idempotency_key",
+      });
+    return r;
+  };
+  /** Credentials leave once, and no cache may keep them. */
+  const once = (c: Context) => c.header("cache-control", "no-store");
+
+  if (orderQuery) {
+    app.openapi(
+      perms.declare(
+        { permission: "order:read", scoped: true },
+        createRoute({
+          method: "get",
+          path: "/admin/orders/{id}",
+          request: { params: z.object({ id: z.string().regex(/^ord_[0-9A-HJKMNP-TV-Z]{26}$/) }) },
+          responses: ok("An order, scoped and projected for the caller"),
+        }),
+      ),
+      async (c) => {
+        // Outside the caller's scope is NOT_FOUND, never FORBIDDEN, so ids can't be probed (§6.2).
+        const row = await orderQuery.get(ctx(c), c.req.valid("param").id);
+        if (!row) throw new KedgeError("NOT_FOUND", "Order not found");
+        return c.json(orderRecordJson(row), 200);
+      },
+    );
+    app.openapi(
+      perms.declare(
+        { permission: "order:read", scoped: true },
+        createRoute({
+          method: "get",
+          path: "/admin/orders",
+          request: {
+            query: z.object({
+              status: z.string().max(200).optional(),
+              payment_status: z.string().max(200).optional(),
+              location: ID.optional(),
+              created_from: Instant.optional(),
+              created_to: Instant.optional(),
+              placed_from: Instant.optional(),
+              placed_to: Instant.optional(),
+              sort: z.enum(["created_at", "-created_at", "total", "-total"]).optional(),
+              expand: z.literal("lines").optional(),
+              cursor: z.string().max(2048).optional(),
+              limit: z.coerce.number().int().min(1).max(100).optional(),
+            }),
+          },
+          responses: ok("A page of orders the caller may see"),
+        }),
+      ),
+      async (c) => {
+        const q = c.req.valid("query");
+        const filters: OrderFilter[] = [];
+        const set = (field: string, v: string | undefined) => {
+          if (v === undefined) return;
+          const values = v.split(",").filter(Boolean);
+          filters.push(values.length > 1 ? { field, op: "in", value: values } : { field, op: "eq", value: v });
+        };
+        set("status", q.status);
+        set("payment_status", q.payment_status);
+        if (q.location) filters.push({ field: "location", op: "eq", value: q.location });
+        if (q.created_from !== undefined) filters.push({ field: "created_at", op: "gte", value: q.created_from });
+        if (q.created_to !== undefined) filters.push({ field: "created_at", op: "lt", value: q.created_to });
+        if (q.placed_from !== undefined) filters.push({ field: "placed_at", op: "gte", value: q.placed_from });
+        if (q.placed_to !== undefined) filters.push({ field: "placed_at", op: "lt", value: q.placed_to });
+        const page = await orderQuery.list(ctx(c), {
+          filters,
+          ...(q.sort
+            ? {
+                sort: {
+                  field: q.sort.replace(/^-/, ""),
+                  direction: q.sort.startsWith("-") ? ("desc" as const) : ("asc" as const),
+                },
+              }
+            : {}),
+          ...(q.expand ? { expand: ["lines"] } : {}),
+          cursor: q.cursor ?? null,
+          ...(q.limit !== undefined ? { limit: q.limit } : {}),
+        });
+        return c.json({ ...page, data: page.data.map(orderRecordJson) }, 200);
+      },
+    );
+
+    // Totals and emails are classified values, which never go in a URL (§5.2).
+    const Filter = z.object({
+      field: z.string().max(64),
+      op: z.enum(["eq", "in", "gte", "lt"]),
+      value: z.union([z.string().max(320), z.number(), z.array(z.union([z.string().max(320), z.number()])).max(50)]),
+    });
+    app.openapi(
+      perms.declare(
+        { permission: "order:read", read: true, scoped: true },
+        createRoute({
+          method: "post",
+          path: "/admin/orders/search",
+          request: jsonBody(
+            z.object({
+              filters: z.array(Filter).max(20).optional(),
+              sort: z.object({ field: z.string().max(64), direction: z.enum(["asc", "desc"]) }).optional(),
+              search: z
+                .object({
+                  fields: z.array(z.string().max(64)).min(1).max(ENTITY_LIMITS.SEARCH_FIELDS_MAX),
+                  term: z.string().min(1).max(320),
+                })
+                .optional(),
+              expand: z.array(z.literal("lines")).max(1).optional(),
+              cursor: z.string().max(2048).optional(),
+              limit: z.number().int().min(1).max(100).optional(),
+            }),
+          ),
+          responses: ok("A page of matching orders"),
+        }),
+      ),
+      async (c) => {
+        const b = c.req.valid("json");
+        const page = await orderQuery.search(ctx(c), {
+          ...(b.filters ? { filters: b.filters } : {}),
+          ...(b.sort ? { sort: b.sort } : {}),
+          ...(b.search ? { search: b.search } : {}),
+          ...(b.expand ? { expand: b.expand } : {}),
+          cursor: b.cursor ?? null,
+          ...(b.limit !== undefined ? { limit: b.limit } : {}),
+        });
+        return c.json({ ...page, data: page.data.map(orderRecordJson) }, 200);
+      },
+    );
+  }
+
+  if (keyring) {
+    // The keyring steps keep their own envelope, ordered around their checks (codex code r14).
+    const retryOf = (c: Context<KedgeEnv>) => ({
+      principal: actorOf(c.var.access.ctx.principal),
+      key: c.req.header("idempotency-key") ?? null,
+    });
+    // The keyring protocol (§4.1, §9): Owner only, each step audited and asserted in its batch.
+    const keyringJson = (k: Awaited<ReturnType<KeyringAdmin["state"]>>[number]) => ({
+      family: k.family,
+      active: k.active,
+      retiring: k.retiring,
+      activated_at: iso(k.activatedAt),
+      held: k.held,
+    });
+    const Family = z.object({ family: z.enum(["pepper", "totp", "auth"]) });
+    app.openapi(
+      perms.declare(
+        "owner:manage",
+        createRoute({ method: "get", path: "/admin/keyring", responses: ok("Each secret's versions") }),
+      ),
+      async (c) => c.json({ keyring: (await keyring.state()).map(keyringJson) }, 200),
+    );
+    app.openapi(
+      perms.declare(
+        { permission: "owner:manage", own: true },
+        createRoute({
+          method: "post",
+          path: "/admin/keyring/{family}/activate",
+          request: { params: Family, ...jsonBody(z.object({ version: z.number().int().min(2) })) },
+          responses: ok("The new version is active; the old one is retiring"),
+        }),
+      ),
+      async (c) =>
+        c.json(
+          keyringJson(
+            await keyring.activate(c.req.valid("param").family, c.req.valid("json").version, now(), retryOf(c)),
+          ),
+          200,
+        ),
+    );
+    for (const step of ["complete", "rollback"] as const)
+      app.openapi(
+        perms.declare(
+          { permission: "owner:manage", own: true },
+          createRoute({
+            method: "post",
+            path: `/admin/keyring/{family}/${step}`,
+            request: { params: Family },
+            responses: ok(step === "complete" ? "The retiring version is retired" : "Back to the retiring version"),
+          }),
+        ),
+        async (c) => c.json(keyringJson(await keyring[step](c.req.valid("param").family, now(), retryOf(c))), 200),
+      );
+  }
+
+  if (!admin) return;
+  const StaffParam = z.object({ id: ID });
+
+  // ---- staff and invites --------------------------------------------------------------
+
+  app.openapi(
+    perms.declare("staff:read", createRoute({ method: "get", path: "/admin/staff", responses: ok("Staff") })),
+    async (c) => c.json({ staff: await admin.staffList(ctx(c)) }, 200),
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "staff:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/staff/invites",
+        request: jsonBody(z.object({ email: z.email().max(320), roles: RoleRefs.min(1) })),
+        responses: ok("The invite and its one-time token"),
+      }),
+    ),
+    async (c) => {
+      once(c);
+      const b = c.req.valid("json");
+      return c.json(
+        issuedInvite(c, await admin.createInvite(ctx(c), { email: b.email, roleIds: b.roles }, keyed(c))),
+        200,
+      );
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "staff:write", own: true },
+      createRoute({
+        method: "put",
+        path: "/admin/staff/{id}/roles",
+        request: { params: StaffParam, ...jsonBody(z.object({ roles: RoleRefs })) },
+        responses: ok("The member's roles"),
+      }),
+    ),
+    async (c) => {
+      const { id } = c.req.valid("param");
+      const { roles } = c.req.valid("json");
+      await admin.assignRoles(ctx(c), id, { roleIds: roles }, req(c));
+      return c.json({ id, role_ids: roles.map((r) => r.id) }, 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "staff:write", own: true },
+      createRoute({
+        method: "put",
+        path: "/admin/staff/{id}/locations",
+        request: { params: StaffParam, ...jsonBody(z.object({ location_ids: z.array(ID).max(64) })) },
+        responses: ok("The member's locations"),
+      }),
+    ),
+    async (c) => {
+      const { id } = c.req.valid("param");
+      const { location_ids } = c.req.valid("json");
+      await admin.setLocations(ctx(c), { staffId: id }, location_ids, req(c));
+      return c.json({ id, location_ids }, 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "staff:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/staff/{id}/deactivate",
+        request: { params: StaffParam },
+        responses: ok("Deactivated; every session ended"),
+      }),
+    ),
+    async (c) => {
+      const { id } = c.req.valid("param");
+      await admin.deactivateStaff(ctx(c), id, req(c));
+      return c.json({ id, status: "deactivated" }, 200);
+    },
+  );
+  // The one staff reset in this slice: an owner's reenrol invite (D-053, §3.4).
+  app.openapi(
+    perms.declare(
+      { permission: "staff:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/staff/{id}/reset",
+        request: { params: StaffParam },
+        responses: ok("A reenrol invite and its one-time token"),
+      }),
+    ),
+    async (c) => {
+      once(c);
+      return c.json(issuedInvite(c, await admin.resetFactors(ctx(c), c.req.valid("param").id, keyed(c))), 200);
+    },
+  );
+
+  // ---- roles ----------------------------------------------------------------------------
+
+  app.openapi(
+    perms.declare("role:read", createRoute({ method: "get", path: "/admin/roles", responses: ok("Roles") })),
+    async (c) => c.json({ roles: await admin.rolesList(ctx(c)) }, 200),
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "role:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/roles",
+        request: jsonBody(
+          z.object({
+            code: z.string().regex(/^[a-z][a-z0-9_]{1,39}$/),
+            name: z.string().min(1).max(80),
+            grants: Grants,
+            strong_auth: z.boolean().optional(),
+          }),
+        ),
+        responses: ok("The new role"),
+      }),
+    ),
+    async (c) => {
+      const b = c.req.valid("json");
+      return c.json(
+        await admin.createRole(
+          ctx(c),
+          { code: b.code, name: b.name, grants: grants(b.grants), strongAuth: b.strong_auth === true },
+          keyed(c),
+        ),
+        200,
+      );
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "role:write", own: true },
+      createRoute({
+        method: "put",
+        path: "/admin/roles/{id}/grants",
+        request: {
+          params: z.object({ id: ID }),
+          ...jsonBody(z.object({ expected_version: z.number().int().min(1), grants: Grants })),
+        },
+        responses: ok("The role's new version"),
+      }),
+    ),
+    async (c) => {
+      const b = c.req.valid("json");
+      return c.json(
+        await admin.setRoleGrants(
+          ctx(c),
+          c.req.valid("param").id,
+          { expectedVersion: b.expected_version, grants: grants(b.grants) },
+          req(c),
+        ),
+        200,
+      );
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "role:write", own: true },
+      createRoute({
+        method: "delete",
+        path: "/admin/roles/{id}",
+        request: { params: z.object({ id: ID }) },
+        responses: ok("Deleted"),
+      }),
+    ),
+    async (c) => {
+      await admin.deleteRole(ctx(c), c.req.valid("param").id, req(c));
+      return c.json({ id: c.req.valid("param").id, deleted: true }, 200);
+    },
+  );
+
+  // ---- storefronts and their publishable keys ------------------------------------------
+
+  app.openapi(
+    perms.declare(
+      "storefront:read",
+      createRoute({ method: "get", path: "/admin/storefronts", responses: ok("Storefronts") }),
+    ),
+    async (c) => c.json({ storefronts: await admin.storefrontsList(ctx(c)) }, 200),
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "storefront:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/storefronts",
+        request: jsonBody(z.object({ name: z.string().min(1).max(80), allowed_origins: Origins })),
+        responses: ok("The new storefront"),
+      }),
+    ),
+    async (c) => {
+      const b = c.req.valid("json");
+      return c.json(
+        await admin.createStorefront(ctx(c), { name: b.name, allowedOrigins: b.allowed_origins }, keyed(c)),
+        200,
+      );
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "storefront:write", own: true },
+      createRoute({
+        method: "put",
+        path: "/admin/storefronts/{id}/origins",
+        request: {
+          params: z.object({ id: ID }),
+          // `expected`: the list as the caller read it; the write is refused CONFLICT if it changed since.
+          ...jsonBody(z.object({ allowed_origins: Origins, expected: Origins.optional() })),
+        },
+        responses: ok("The storefront's origins"),
+      }),
+    ),
+    async (c) => {
+      const { id } = c.req.valid("param");
+      const { allowed_origins, expected } = c.req.valid("json");
+      await admin.setOrigins(ctx(c), id, allowed_origins, req(c), expected);
+      return c.json({ id, allowed_origins }, 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "storefront:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/storefronts/{id}/keys",
+        request: { params: z.object({ id: ID }), ...jsonBody(z.object({ name: z.string().min(1).max(80) })) },
+        responses: ok("A publishable key, shown once"),
+      }),
+    ),
+    async (c) => {
+      once(c);
+      const key = await admin.createPublishableKey(
+        ctx(c),
+        { name: c.req.valid("json").name, storefrontId: c.req.valid("param").id },
+        keyed(c),
+      );
+      return c.json(issuedKey(key), 200);
+    },
+  );
+
+  // A publishable key is managed under storefront:write, as it was created (codex code r7);
+  // the store re-proves that and the key's managers inside its batch.
+  const StorefrontKey = z.object({ id: ID, key_id: ID });
+  app.openapi(
+    perms.declare(
+      { permission: "storefront:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/storefronts/{id}/keys/{key_id}/revoke",
+        request: { params: StorefrontKey, ...jsonBody(z.object({ at: Instant.optional() })) },
+        responses: ok("Revoked, now or at the given time"),
+      }),
+    ),
+    async (c) => {
+      const r = await admin.revokeKey(
+        ctx(c),
+        c.req.valid("param").key_id,
+        c.req.valid("json").at,
+        req(c),
+        c.req.valid("param").id,
+      );
+      return c.json({ id: r.id, revoked_at: iso(r.revokedAt) }, 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "storefront:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/storefronts/{id}/keys/{key_id}/rotate",
+        request: {
+          params: StorefrontKey,
+          ...jsonBody(
+            z.object({
+              overlap_seconds: z
+                .number()
+                .int()
+                .min(0)
+                .max(7 * 86_400),
+            }),
+          ),
+        },
+        responses: ok("The new key, shown once, and the old key's deadline"),
+      }),
+    ),
+    async (c) => {
+      once(c);
+      const r = await admin.rotateKey(
+        ctx(c),
+        c.req.valid("param").key_id,
+        { overlapMs: c.req.valid("json").overlap_seconds * 1000 },
+        keyed(c),
+        c.req.valid("param").id,
+      );
+      return c.json({ ...issuedKey(r), previous: { id: r.previous.id, revoked_at: iso(r.previous.revokedAt) } }, 200);
+    },
+  );
+
+  // ---- credential references (p0.10 §6.2) ----------------------------------------------
+  // The permission depends on the ref's kind (api_key:write for a secret key,
+  // storefront:write otherwise), so the store authorizes inside its own batch.
+
+  const Ref = z.object({ ref: z.string().regex(/^[A-Za-z0-9_-]{32,128}$/) });
+  const RefKind = z.enum(["secret", "publishable", "storefront"]);
+  const refJson = (r: {
+    ref: string;
+    kind: string;
+    state: string;
+    storefrontId: string | null;
+    keyId: string | null;
+  }) => ({ ref: r.ref, kind: r.kind, state: r.state, storefront_id: r.storefrontId, key_id: r.keyId });
+  app.openapi(
+    perms.declare(
+      { permission: "api_key:write", store: true },
+      createRoute({
+        method: "put",
+        path: "/admin/credential-refs/{ref}",
+        request: {
+          params: Ref,
+          ...jsonBody(
+            z.discriminatedUnion("kind", [
+              z.object({
+                kind: z.literal("secret"),
+                name: z.string().min(1).max(80),
+                grants: Grants.min(1),
+                location_ids: z.array(ID).max(64).optional(),
+              }),
+              z.object({ kind: z.literal("publishable"), name: z.string().min(1).max(80), storefront_id: ID }),
+              z.object({ kind: z.literal("storefront"), name: z.string().min(1).max(80), allowed_origins: Origins }),
+            ]),
+          ),
+        },
+        responses: ok("The key the ref made, shown once; CREDENTIAL_REF_TAKEN if it was used or voided"),
+      }),
+    ),
+    async (c) => {
+      once(c);
+      const b = c.req.valid("json");
+      const made = await admin.createByRef(
+        ctx(c),
+        c.req.valid("param").ref,
+        b.kind === "secret"
+          ? {
+              kind: "secret",
+              name: b.name,
+              grants: grants(b.grants),
+              ...(b.location_ids ? { locationIds: b.location_ids } : {}),
+            }
+          : b.kind === "publishable"
+            ? { kind: "publishable", name: b.name, storefrontId: b.storefront_id }
+            : { kind: "storefront", name: b.name, allowedOrigins: b.allowed_origins },
+        req(c),
+      );
+      return c.json({ ...refJson(made), key: made.key, token_prefix: made.tokenPrefix }, 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "api_key:write", store: true },
+      createRoute({
+        method: "post",
+        path: "/admin/credential-refs/{ref}/void",
+        request: { params: Ref, ...jsonBody(z.object({ kind: RefKind })) },
+        responses: ok("The ref's outcome, kept for ever: fenced, or revoked with what it made"),
+      }),
+    ),
+    async (c) =>
+      c.json(refJson(await admin.voidRef(ctx(c), c.req.valid("param").ref, c.req.valid("json").kind, req(c))), 200),
+  );
+
+  // ---- API keys ----------------------------------------------------------------------
+
+  const KeyParam = z.object({ id: ID });
+  app.openapi(
+    perms.declare(
+      "api_key:read",
+      createRoute({
+        method: "get",
+        path: "/admin/api-keys",
+        request: { query: z.object({ stale_pepper: z.enum(["1"]).optional() }) },
+        responses: ok("API keys, by display prefix"),
+      }),
+    ),
+    async (c) =>
+      c.json({ keys: await admin.keysList(ctx(c), { stalePepper: c.req.valid("query").stale_pepper === "1" }) }, 200),
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "api_key:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/api-keys",
+        request: jsonBody(
+          z.object({
+            name: z.string().min(1).max(80),
+            grants: Grants.min(1),
+            location_ids: z.array(ID).max(64).optional(),
+          }),
+        ),
+        responses: ok("A secret key, shown once"),
+      }),
+    ),
+    async (c) => {
+      once(c);
+      const b = c.req.valid("json");
+      const key = await admin.createSecretKey(
+        ctx(c),
+        { name: b.name, grants: grants(b.grants), ...(b.location_ids ? { locationIds: b.location_ids } : {}) },
+        keyed(c),
+      );
+      return c.json(issuedKey(key), 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "api_key:write", own: true },
+      createRoute({
+        method: "put",
+        path: "/admin/api-keys/{id}/locations",
+        request: { params: KeyParam, ...jsonBody(z.object({ location_ids: z.array(ID).max(64) })) },
+        responses: ok("The key's locations"),
+      }),
+    ),
+    async (c) => {
+      const { id } = c.req.valid("param");
+      const { location_ids } = c.req.valid("json");
+      await admin.setLocations(ctx(c), { apiKeyId: id }, location_ids, req(c));
+      return c.json({ id, location_ids }, 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "api_key:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/api-keys/{id}/revoke",
+        request: { params: KeyParam, ...jsonBody(z.object({ at: Instant.optional() })) },
+        responses: ok("Revoked, now or at the given time"),
+      }),
+    ),
+    async (c) => {
+      const r = await admin.revokeKey(ctx(c), c.req.valid("param").id, c.req.valid("json").at, req(c));
+      return c.json({ id: r.id, revoked_at: iso(r.revokedAt) }, 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "api_key:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/api-keys/{id}/rotate",
+        request: {
+          params: KeyParam,
+          ...jsonBody(
+            z.object({
+              overlap_seconds: z
+                .number()
+                .int()
+                .min(0)
+                .max(7 * 86_400),
+            }),
+          ),
+        },
+        responses: ok("The new key, shown once, and the old key's deadline"),
+      }),
+    ),
+    async (c) => {
+      once(c);
+      const r = await admin.rotateKey(
+        ctx(c),
+        c.req.valid("param").id,
+        { overlapMs: c.req.valid("json").overlap_seconds * 1000 },
+        keyed(c),
+      );
+      return c.json({ ...issuedKey(r), previous: { id: r.previous.id, revoked_at: iso(r.previous.revokedAt) } }, 200);
+    },
+  );
+
+  // ---- the audit log (§7.2) ----------------------------------------------------------------
+
+  app.openapi(
+    perms.declare(
+      "audit:read",
+      createRoute({
+        method: "get",
+        path: "/admin/audit-log",
+        request: {
+          query: z.object({
+            entity_type: z.string().max(64).optional(),
+            entity_id: ID.optional(),
+            actor: z.string().max(128).optional(),
+            before: z.string().max(200).optional(),
+            limit: z.coerce.number().int().min(1).max(100).optional(),
+          }),
+        },
+        responses: ok("Audit entries, newest first"),
+      }),
+    ),
+    async (c) => {
+      const q = c.req.valid("query");
+      // The cursor is `<created_at>.<id>`: nothing classified is in it.
+      let before: { createdAt: number; id: string } | undefined;
+      if (q.before) {
+        const m = /^(\d+)\.(.+)$/.exec(q.before);
+        if (!m) throw new KedgeError("BAD_REQUEST", "Invalid cursor", { cursor: "invalid" });
+        before = { createdAt: Number(m[1]), id: m[2] as string };
+      }
+      const r = await admin.auditLog(ctx(c), {
+        ...(q.entity_type ? { entityType: q.entity_type } : {}),
+        ...(q.entity_id ? { entityId: q.entity_id } : {}),
+        ...(q.actor ? { actor: q.actor } : {}),
+        ...(before ? { before } : {}),
+        ...(q.limit !== undefined ? { limit: q.limit } : {}),
+      });
+      const entries = (r.entries as AuditEntry[]).map((e) => ({
+        id: e.id,
+        batch_id: e.batchId,
+        actor: e.actor,
+        action: e.action,
+        entity_type: e.entityType,
+        entity_id: e.entityId,
+        changes: e.changes,
+        ip: e.ip,
+        user_agent: e.userAgent,
+        created_at: iso(e.createdAt),
+      }));
+      return c.json({ entries, next_cursor: r.next ? `${r.next.createdAt}.${r.next.id}` : null }, 200);
+    },
+  );
+}