@tokenoftrust/storefront-runner 1.4.0 → 1.4.2-rc.0

package/apps/storefront/src/lib/admin/services/orders.ts

@@ -1,22 +1,20 @@
 /**
- * REAL orders view model (card 8585 / U3) — replaces the deterministic mock as
- * the Orders tab's data source. Fetches the tenant's checkout orders via U2's
- * order client and maps the frozen DTO (`@tot/public-runtime` checkout-orders)
- * into the EXISTING `OrdersViewModel` shape, so `OrdersWorkspace.astro` renders
- * unchanged. Read-only (scope-locks) — no write paths.
+ * REAL orders view model — the Orders tab's data source. Fetches the tenant's
+ * checkout orders via the order client and maps the frozen DTO
+ * (`@tot/public-runtime` checkout-orders) into the `OrdersViewModel` shape that
+ * `OrdersWorkspace.astro` renders. Read-only (scope-locks) — no write paths.
  *
  * The mapping is a pure function (`mapOrdersToViewModel`) for testability; the
  * orchestration (`getOrdersViewModel`) lists orders, eagerly fetches each order's
  * detail (OrdersWorkspace renders `detailsById[row.id]` for every row), and maps.
- * On ANY upstream failure it returns a valid EMPTY view model so the tab renders
- * (rich loading/empty/error UX is U5). NOTE: the live "real qa data" path is
- * gated on ToT-core exposing `GET /api/exciseTax/orders` (see U1/U2 notes); until
- * then this yields the empty model on qa.
+ * On ANY upstream failure it returns a valid EMPTY view model so the tab renders.
+ * The live "real qa data" path is gated on ToT-core exposing
+ * `GET /api/exciseTax/orders`; until that exists this yields the empty model on qa.
  *
  * Identity/age fields (riskLevel, readiness "identity_and_age", evidence) are
- * derived provisionally from commerce facts here; U4 (the tot20 verification
- * join) fills them authoritatively via the DTO's null `verification` /
- * `verificationDetail` slots — no shape change needed.
+ * derived provisionally from commerce facts here; the tot20 verification join
+ * fills them authoritatively via the DTO's null `verification` /
+ * `verificationDetail` slots.
  */
 import type {
   CheckoutOrderDetail,
@@ -45,7 +43,7 @@ function deriveNextStep(fulfillment: OrderShipState, blocker: string | null): st
   return "Create label";
 }
 
-/** Provisional risk until U4 fills `verification`. Prefer a real riskLevel when present. */
+/** Provisional risk until the verification join fills `verification`. Prefer a real riskLevel when present. */
 function deriveRisk(
   verification: CheckoutOrderVerification | null,
   blocker: string | null,
@@ -75,7 +73,7 @@ export function mapSummaryToRow(s: CheckoutOrderSummary): OrderRow {
   };
 }
 
-/** Commerce-derived readiness checks (U4 enriches the identity dimension). */
+/** Commerce-derived readiness checks (the verification join enriches the identity dimension). */
 function deriveReadinessChecks(d: CheckoutOrderDetail): OrderReadinessCheck[] {
   const ageHold = d.blocker === "Age verification hold";
   return [
@@ -118,7 +116,7 @@ function deriveReadinessChecks(d: CheckoutOrderDetail): OrderReadinessCheck[] {
   ];
 }
 
-/** Base commerce evidence events (U4 replaces with the real verification timeline). */
+/** Base commerce evidence events (the verification join replaces with the real verification timeline). */
 function deriveEvidenceTimeline(d: CheckoutOrderDetail): OrderEvidenceEvent[] {
   const events: OrderEvidenceEvent[] = [
     { title: "Order imported", detail: "Storefront order became available in the admin queue.", at: d.placedAt },
@@ -226,7 +224,7 @@ export interface GetOrdersViewModelOptions {
  * the Orders tab always renders.
  */
 /**
- * Load outcome for the Orders tab (U5) — lets the UI pick the right state:
+ * Load outcome for the Orders tab — lets the UI pick the right state:
  * `loaded` (rows), `empty` (fetch OK, 0 orders), `error` (upstream failed), and
  * `not_configured` (produced by the caller when no bearer/client is available —
  * the service itself never returns it). `page` carries the pagination cursor.
@@ -240,7 +238,7 @@ export interface OrdersLoadResult {
 }
 
 /**
- * Parse server-backed list filters from a request's query string (U5). `queue`
+ * Parse server-backed list filters from a request's query string. `queue`
  * of `"all"` (or absent) means no server filter. Non-numeric `limit` is ignored.
  * `payment`/search are NOT here — they are client-side refinements (the DTO list
  * API has no payment filter, per contract §9).
@@ -263,7 +261,7 @@ export function parseOrderFilters(params: URLSearchParams): CheckoutOrderListFil
 }
 
 /**
- * Fetch + map the orders view model AND report the load outcome (U5). Lists,
+ * Fetch + map the orders view model AND report the load outcome. Lists,
  * eagerly fetches per-order detail, maps. Distinguishes empty from error so the
  * tab can degrade gracefully. Never throws.
  */
@@ -292,7 +290,7 @@ export async function getOrdersViewModelResult(
   }
 }
 
-/** Back-compat convenience: just the view model (see getOrdersViewModelResult). */
+/** Convenience wrapper: just the view model (see getOrdersViewModelResult). */
 export async function getOrdersViewModel(
   opts: GetOrdersViewModelOptions,
 ): Promise<OrdersViewModel> {

package/apps/storefront/src/lib/admin/viewmodels/aiWorkflows.ts

@@ -1,10 +1,8 @@
 /**
- * AI Workflows view model (baseline §AI Workflows) — the 8 named recurring
- * jobs as a control-plane record. No execution: this unit only defines the
- * read-oriented record shape (ai-workflows-scaffold/operational build the tab
- * + execution on top of it). `ApprovalMode`/`AuditEvent`/`AiRecommendation`
- * now come from the ai-evidence-substrate (`lib/admin/ai`), which formalizes
- * the approval/evidence models this view model originally stubbed.
+ * AI Workflows view model — the 8 named recurring jobs as a control-plane
+ * record. No execution: this defines only the read-oriented record shape; the
+ * tab + execution build on top of it. `ApprovalMode`/`AuditEvent`/`AiRecommendation`
+ * come from `lib/admin/ai`, which formalizes the approval/evidence models.
  */
 
 import type { ApprovalMode } from "../ai/approvalMode";

package/apps/storefront/src/lib/admin/viewmodels/settings.ts

@@ -54,7 +54,7 @@ export interface SettingsViewModel {
   auditTrail: SettingsAuditEvent[];
   /**
    * The target tenant's current checkout styling — the editable descriptor the
-   * "Checkout styling" section (U12) renders in its editor and saves back through
+   * "Checkout styling" section renders in its editor and saves back through
    * the versioned publish spine (`POST /api/admin/checkout-style` →
    * `publishToTest` on `tenants/<id>/checkout-style.json`). Always a complete
    * `CheckoutStyle` (the resolved default merged with any published override), so

package/apps/storefront/src/lib/apps/adminService.ts

@@ -1,8 +1,8 @@
 /**
- * Composition root + shared helpers for the `/api/apps/admin/*` routes
- * (PrivateApps epic, D2 Chunk C) — builds an `AppRegistryService` over the
+ * Composition root + shared helpers for the `/api/apps/admin/*` routes —
+ * builds an `AppRegistryService` over the
  * `STOREFRONT_APPS_DB` `Queryable` binding and a `D1CredentialStore`, the same
- * construction `api/apps/oauth/token.ts` (Chunk B) uses, and mirrors
+ * construction `api/apps/oauth/token.ts` uses, and mirrors
  * `../grants/route.ts`'s `getService()` + no-store `json()` + 503-when-
  * unconfigured pattern. Kept out of the pure service module so that stays
  * transport-free and unit-testable against a fake `Queryable`.
@@ -72,7 +72,7 @@ export function parseInstallId(body: unknown): string | null {
  * Resolve `installId` and verify it belongs to `tenantId` — every mutating
  * admin route (update/suspend/resume/uninstall/rotate) MUST call this BEFORE
  * invoking a service method, since those methods take a bare `installId` with
- * no tenant check of their own (Chunk A assumption #1). A foreign-tenant
+ * no tenant check of their own. A foreign-tenant
  * `installId` is reported IDENTICALLY to a truly-missing one — 404, same
  * body shape as `RegistryError("not_found")` — so there is no cross-tenant
  * existence oracle.

package/apps/storefront/src/lib/apps/adminSession.ts

@@ -1,6 +1,6 @@
 /**
  * Operator-session resolution for the Private Apps admin API
- * (`/api/apps/admin/*`, PrivateApps epic, D2 Chunk C). Adapted from
+ * (`/api/apps/admin/*`). Mirrors
  * `../grants/session.ts`'s owner-session resolution — same two paths, same
  * fail-closed shape — but resolves `{ tenantId, actor }` instead of `{ owner }`:
  *
@@ -38,7 +38,7 @@
  * Routes depend only on the `{ ok, tenantId, actor }` result. `authorizeAdmin`
  * is the pure core of path 2 (unit-testable, no I/O).
  *
- * D8 ADDITION — console admin session. The two paths above are host-bound:
+ * Console admin session. The two paths above are host-bound:
  * they resolve exactly one tenant (`context.locals.tenant`). The
  * `/api/apps/admin/*` surface is also reachable from the multi-tenant vendor
  * console, where a signed-in viewer may hold memberships on several vendors —
@@ -61,6 +61,11 @@ import { sha256Hex } from "@tot/public-runtime";
 import { readEnv } from "@/lib/env";
 import { readViewerSession } from "@/lib/auth/route.js";
 import { viewerCanAccess, membershipFor } from "@/lib/dashboard/tenantSelection.js";
+import {
+  authorizeBearerOperator,
+  resolveHostBoundSession,
+  type SessionFailure,
+} from "@/lib/auth/operatorSession.js";
 
 /** Capabilities that make a signed-in viewer an app-registry operator for their tenant. */
 const ADMIN_CAPABILITIES: ReadonlySet<string> = new Set(["owner", "admin"]);
@@ -88,33 +93,30 @@ export interface AdminAuthInput {
 
 export type AdminAuthResult =
   | { ok: true; tenantId: string; actor: string; role?: string }
-  | { ok: false; status: number; message: string };
+  | SessionFailure;
+
+/** The one authorized-success shape both host-bound and Bearer admin paths return. */
+type AdminAuthOk = Extract<AdminAuthResult, { ok: true }>;
 
 /**
  * Decide the authenticated tenant from env + request, with NO I/O —
  * unit-testable. Fail-closed: unconfigured gate → 503, bad/absent Bearer →
- * 401, no resolvable tenant → 400.
+ * 401, no resolvable tenant → 400. A thin adapter over the shared
+ * Bearer-operator core that maps its resolved `principal` to this surface's
+ * `tenantId` and stamps the fixed `BEARER_ACTOR` (no per-caller identity here).
  */
 export function authorizeAdmin(input: AdminAuthInput): AdminAuthResult {
-  if (!input.gateSecret) {
-    return {
-      ok: false,
-      status: 503,
-      message: "apps admin operator secret not configured",
-    };
-  }
-  if (input.authHeader !== `Bearer ${input.gateSecret}`) {
-    return { ok: false, status: 401, message: "Unauthorized" };
-  }
-  const tenantId = (input.configuredTenant ?? input.requestedTenant ?? "").trim();
-  if (!tenantId) {
-    return {
-      ok: false,
-      status: 400,
-      message: "tenant unresolved (set APPS_ADMIN_TENANT or X-Tot-Tenant)",
-    };
-  }
-  return { ok: true, tenantId, actor: BEARER_ACTOR };
+  const res = authorizeBearerOperator({
+    authHeader: input.authHeader,
+    gateSecret: input.gateSecret,
+    configuredPrincipal: input.configuredTenant,
+    requestedPrincipal: input.requestedTenant,
+    unconfiguredMessage: "apps admin operator secret not configured",
+    unresolvedMessage: "tenant unresolved (set APPS_ADMIN_TENANT or X-Tot-Tenant)",
+  });
+  return res.ok
+    ? { ok: true, tenantId: res.principal, actor: BEARER_ACTOR }
+    : res;
 }
 
 /** One-way, stable pseudonym for an audit `actor` — never the email itself. */
@@ -128,30 +130,37 @@ async function actorFromEmail(email: string): Promise<string> {
  * from the body.
  */
 export async function resolveAdminSession(context: APIContext): Promise<AdminAuthResult> {
-  // Path 1: a signed-in tenant-operator session. The tenant IS the resolved
-  // host's appDomain — never from the request body.
-  const viewer = context.locals?.viewer;
-  const tenantId = context.locals?.tenant?.appDomain;
-  if (viewer && tenantId) {
-    if (!ADMIN_CAPABILITIES.has(viewer.capability)) {
-      return {
+  return resolveHostBoundSession<AdminAuthOk>(context, {
+    capabilities: ADMIN_CAPABILITIES,
+    // A resolved-but-insufficient viewer fails closed with 403 and does NOT
+    // fall through to the Bearer gate — an authenticated-but-under-privileged
+    // caller must not be silently admitted by a secret it also presents.
+    onInsufficientCapability: {
+      mode: "failClosed",
+      failure: {
         ok: false,
         status: 403,
         message: "not authorized to manage apps for this tenant",
-      };
-    }
-    return { ok: true, tenantId, actor: await actorFromEmail(viewer.email) };
-  }
-
-  // Path 2 (fallback): the headless-console Bearer operator secret. Dedicated
-  // secret only — no fallback to another deployment's secret.
-  const gateSecret = await readEnv("APPS_ADMIN_SECRET");
-  const configuredTenant = await readEnv("APPS_ADMIN_TENANT");
-  return authorizeAdmin({
-    authHeader: context.request.headers.get("authorization"),
-    gateSecret,
-    configuredTenant,
-    requestedTenant: context.request.headers.get("x-tot-tenant"),
+      },
+    },
+    // Path 1: the tenant IS the resolved host's appDomain — never the body.
+    resolveViewer: async (viewer, tenantId) => ({
+      ok: true,
+      tenantId,
+      actor: await actorFromEmail(viewer.email),
+    }),
+    // Path 2 (fallback): the headless-console Bearer operator secret. Dedicated
+    // secret only — no fallback to another deployment's secret.
+    resolveBearer: async (ctx) => {
+      const gateSecret = await readEnv("APPS_ADMIN_SECRET");
+      const configuredTenant = await readEnv("APPS_ADMIN_TENANT");
+      return authorizeAdmin({
+        authHeader: ctx.request.headers.get("authorization"),
+        gateSecret,
+        configuredTenant,
+        requestedTenant: ctx.request.headers.get("x-tot-tenant"),
+      });
+    },
   });
 }
 

package/apps/storefront/src/lib/apps/apiAuth.ts

@@ -1,7 +1,7 @@
 /**
- * The D3 scoped-API authorization boundary (PrivateApps epic) — every
+ * The scoped-API authorization boundary — every
  * `/api/apps/v1/*` route calls `authorizeAppRequest` FIRST. Verifies the
- * app-gateway bearer JWT (D2's `AppTokenVerifier`), resolves the calling
+ * app-gateway bearer JWT (`AppTokenVerifier`), resolves the calling
  * install from the registry, and enforces the single scope the route
  * requires per `docs/private-apps/contract/openapi.yaml`'s `x-requiredScope`.
  *

package/apps/storefront/src/lib/apps/apiRoute.ts

@@ -1,6 +1,6 @@
 /**
- * Response helpers shared by every `/api/apps/v1/*` route (PrivateApps epic,
- * D3) — a no-store JSON responder (mirrors `../grants/route.ts` /
+ * Response helpers shared by every `/api/apps/v1/*` route — a no-store JSON
+ * responder (mirrors `../grants/route.ts` /
  * `./adminService.ts`'s pattern) plus the `tot-request-id` / `traceparent`
  * response headers `docs/private-apps/contract/openapi.yaml` documents on
  * every operation.

package/apps/storefront/src/lib/apps/catalogMapper.ts

@@ -1,5 +1,5 @@
 /**
- * Maps the internal `CatalogProduct` read model to the D3 contract's
+ * Maps the internal `CatalogProduct` read model to the scoped-API contract's
  * `Product` shape (`docs/private-apps/contract/openapi.yaml`, schema
  * `Product` — `additionalProperties: false`). Drops every internal field
  * the contract doesn't declare (variants, images, metafields, source, …) so

package/apps/storefront/src/lib/apps/credentials.ts

@@ -1,6 +1,6 @@
 /**
- * D1-backed `CredentialPort` implementation (PrivateApps epic, D2 Chunk B) —
- * issues/rotates/clears the OAuth2 client-credentials for an app install, and
+ * D1-backed `CredentialPort` implementation — issues/rotates/clears the
+ * OAuth2 client-credentials for an app install, and
  * verifies a presented `(clientId, secret)` pair for the token endpoint
  * (`tokenIssuer.ts`).
  *

package/apps/storefront/src/lib/apps/gatewayKeys.ts

@@ -1,7 +1,7 @@
 /**
- * RS256 signing-key loader for the Storefront App Gateway (PrivateApps epic,
- * D2 Chunk B) — the key that mints and verifies the OAuth2 client-credentials
- * JWTs a private app presents to the D3 scoped APIs.
+ * RS256 signing-key loader for the Storefront App Gateway — the key that mints
+ * and verifies the OAuth2 client-credentials
+ * JWTs a private app presents to the scoped APIs.
  *
  * Mirrors `../auth/brokerAssertion.ts`'s `loadSigningKey` caching + `readEnv`
  * usage EXACTLY, but over a SEPARATE key (`JWT_APP_GATEWAY_PRIVATE_KEY_B64`):
@@ -34,7 +34,7 @@ export const DEFAULT_APP_GATEWAY_ISSUER = "storefront-app-gateway";
 export const APP_TOKEN_TTL_SECONDS = 300;
 
 /**
- * Widget launch-token lifetime (PrivateApps epic, D5 Chunk B) — shorter than
+ * Widget launch-token lifetime — shorter than
  * {@link APP_TOKEN_TTL_SECONDS}: this token only needs to survive the SSR
  * render → iframe-load round trip, never a standing API session.
  */

package/apps/storefront/src/lib/apps/healthAggregate.ts

@@ -1,7 +1,7 @@
 /**
- * Admin Health view aggregation — PrivateApps epic, D8 (Chunk A + D). Folds
+ * Admin Health view aggregation. Folds
  * one `AppInstall` (`registryService.ts`) and its `InstallHealth` rollup
- * (`../webhooks/deliveryStore.ts`'s `getInstallHealth`, now including
+ * (`../webhooks/deliveryStore.ts`'s `getInstallHealth`, including
  * `p95DeliveryMs`) into the single `AppInstallHealthView` shape the admin
  * console renders. Deliberately transport-free — no D1/fetch here, so it's
  * unit-testable with fakes; the caller (the admin health route) owns
@@ -11,9 +11,9 @@
  * a raw URL here, only as `hasWebhookEndpoint` presence — the console shows
  * "configured or not", not the app's receiver address.
  *
- * `runtimeMode` is hardcoded to `"external"` for V1: there is no per-install
- * runtime-mode column yet (every install today IS an externally-hosted app;
- * an in-platform runtime mode is a D9+ concern).
+ * `runtimeMode` is hardcoded to `"external"`: there is no per-install
+ * runtime-mode column (every install IS an externally-hosted app;
+ * an in-platform runtime mode is out of scope).
  */
 import { validateWebhookEndpoint } from "../webhooks/endpointGuard.js";
 import type { InstallHealth } from "../webhooks/deliveryStore.js";

package/apps/storefront/src/lib/apps/orders/attributionService.ts

@@ -1,6 +1,6 @@
 /**
- * App-owned attribution/commission write model — PrivateApps epic, D6
- * (Chunk C). Owns the `app_attributions` rows `schema.ts` declares: the
+ * App-owned attribution/commission write model. Owns the
+ * `app_attributions` rows `schema.ts` declares: the
  * ledger `POST /attribution` (`docs/private-apps/contract/openapi.yaml`'s
  * `writeAttribution`) writes into. Writes only into the app's own
  * attribution namespace — this service never mutates `orders`, it only

package/apps/storefront/src/lib/apps/orders/customerHash.ts

@@ -1,5 +1,5 @@
 /**
- * Opaque customer hash — PrivateApps epic, D6 (Chunk A). The `customerHash`
+ * Opaque customer hash — the `customerHash`
  * every order/attribution surface exposes instead of a raw customer id (see
  * `docs/private-apps/api-event-reference.md`'s PII-minimization matrix and
  * `contract/openapi.yaml`'s `Order.customerHash`).

package/apps/storefront/src/lib/apps/orders/foxyOrderClient.ts

@@ -1,18 +1,18 @@
 /**
- * FoxyOrderClient — the boundary to tot-foxycart's order-read surface
- * (PrivateApps epic, D6 Chunk A/B). `ordersStore.ts` and the read
- * routes / event receiver (later chunks) never call `fetch` directly; they go
- * through this seam so a fake can stand in for tot-foxycart in tests.
+ * FoxyOrderClient — the boundary to tot-foxycart's order-read surface.
+ * `ordersStore.ts` and the read routes / event receiver never call `fetch`
+ * directly; they go through this seam so a fake can stand in for tot-foxycart
+ * in tests.
  *
- * RECONCILED (Chunk B) against the real service —
- * `tot-foxycart/routes/foxyOrderApi.js` + `modules/integrations/foxyOrderMapper.node.js`:
+ * The service is `tot-foxycart/routes/foxyOrderApi.js` +
+ * `modules/integrations/foxyOrderMapper.node.js`:
  * a `GET {baseUrl}/commerce/orders?appDomain=&limit=&offset=&since=&until=&status=`
  * list endpoint returning `{ orders, limit, offset, total, hasMore }` (limit/offset,
- * NOT page/pageSize — chunk A guessed page/pageSize), and a
+ * NOT page/pageSize), and a
  * `GET {baseUrl}/commerce/orders/{externalOrderId}?appDomain=` detail endpoint
- * returning `{ order }` (an envelope, not the bare order — chunk A guessed bare),
+ * returning `{ order }` (an envelope, not the bare order),
  * both Bearer-authenticated with the tenant's Foxy partner API key. `FoxyOrder`
- * below now mirrors `buildOrderPayload()`'s actual normalized DTO — NOT the
+ * below mirrors `buildOrderPayload()`'s actual normalized DTO — NOT the
  * contract's minimized `Order` shape (`contract/openapi.yaml`); mapping one to
  * the other is `orderMapper.ts`'s job.
  *
@@ -20,8 +20,8 @@
  * factory shape and `../../webhooks/deliveryEngine.ts`'s bounded-timeout
  * `fetch` (AbortController, injectable `fetchImpl`) — but adds a settable
  * test seam (`setFoxyOrderClientForTesting`) since this client, unlike
- * `messagesClient.ts`, is a shared singleton multiple later chunks (read
- * routes, event receiver) will each independently resolve.
+ * `messagesClient.ts`, is a shared singleton that multiple callers (read
+ * routes, event receiver) each independently resolve.
  */
 import { readEnv } from "@/lib/env";
 
@@ -174,7 +174,7 @@ export class HttpFoxyOrderClient implements FoxyOrderClient {
 }
 
 // --- Test seam ---------------------------------------------------------------
-// Later chunks (read routes, event receiver) each resolve their own client
+// Callers (read routes, event receiver) each resolve their own client
 // instance via `getFoxyOrderClient()`; a module-level override lets a single
 // `setFoxyOrderClientForTesting` call stand in for tot-foxycart across all of
 // them in one test, without threading a fake through every call site.

package/apps/storefront/src/lib/apps/orders/idempotency.ts

@@ -1,17 +1,17 @@
 /**
- * Idempotency-Key ledger — PrivateApps epic, D6 (Chunk C). Backs the
- * `idempotency_keys` table `schema.ts` declares: the FIRST real (not
+ * Idempotency-Key ledger. Backs the
+ * `idempotency_keys` table `schema.ts` declares: the one real (not
  * presence-only) idempotency ledger in this codebase, and the one
  * `POST /attribution` (`docs/private-apps/contract/openapi.yaml`'s
  * `writeAttribution`) requires — a reused key with a body hash that doesn't
  * match the one first stored is a 409, not a silent overwrite or a second
- * row. Contrast D4's replay endpoint (`webhooks/deliveries/{id}/replay.ts`),
+ * row. Contrast the webhook replay endpoint (`webhooks/deliveries/{id}/replay.ts`),
  * which only checks the header's presence because it has no request body to
- * hash and no table backing it yet.
+ * hash and no table backing it.
  *
- * Pure over the `Queryable` seam, same shape every other D6 store uses.
- * Route-agnostic by design: `attribution.ts` is the first caller, but any
- * future idempotent write route can reuse this unchanged.
+ * Pure over the `Queryable` seam, same shape every other orders store uses.
+ * Route-agnostic by design: `attribution.ts` is one caller, but any
+ * idempotent write route can reuse this.
  */
 import { sha256Hex } from "@tot/public-runtime";
 import type { Queryable } from "../../d1/catalog.js";

package/apps/storefront/src/lib/apps/orders/orderForwardReceiver.ts

@@ -1,5 +1,5 @@
 /**
- * Inbound order-forward receiver — PrivateApps epic, D6 (Chunk D). The
+ * Inbound order-forward receiver. The
  * transport-free core `pages/api/apps/internal/order-forward.ts` calls once
  * it has verified the HMAC signature: given one reconciled order from
  * tot-foxycart, upsert it into `ordersStore.ts` and decide whether that write

package/apps/storefront/src/lib/apps/orders/orderMapper.ts

@@ -1,7 +1,7 @@
 /**
  * Pure mapper: `FoxyOrderClient`'s `FoxyOrder` (tot-foxycart's normalized
- * transaction DTO) -> the contract's minimized `Order` shape (PrivateApps
- * epic, D6 Chunk B; `docs/private-apps/contract/openapi.yaml`'s `Order`).
+ * transaction DTO) -> the contract's minimized `Order` shape
+ * (`docs/private-apps/contract/openapi.yaml`'s `Order`).
  *
  * Drops everything the contract's `additionalProperties: false` Order
  * doesn't declare — no raw checkout payload, no signed-cart material, no tax

package/apps/storefront/src/lib/apps/orders/ordersStore.ts

@@ -1,9 +1,9 @@
 /**
- * `orders` read-model store — PrivateApps epic, D6 (Chunk A). Owns the
- * `orders` rows `schema.ts` declares: the diffing surface a later chunk's
- * event emission reads (`upsertOrder`'s returned `previousStatus` is how it
+ * `orders` read-model store. Owns the
+ * `orders` rows `schema.ts` declares: the diffing surface the event emission
+ * reads (`upsertOrder`'s returned `previousStatus` is how it
  * detects a created→fulfilled transition without a second query) and the
- * lookup surface the attribution route (also later) uses for its cross-tenant
+ * lookup surface the attribution route uses for its cross-tenant
  * ownership check.
  *
  * Pure over the `Queryable` seam (see `../../d1/catalog.ts`) — same shape
@@ -54,8 +54,8 @@ export interface UpsertOrderInput {
 
 /**
  * `upsertOrder`'s return: the row's status BEFORE this write (`null` for a
- * brand-new order) alongside the row as it now stands — the diffing signal a
- * later chunk's event emission needs to tell "just created" apart from
+ * brand-new order) alongside the row as it now stands — the diffing signal the
+ * event emission needs to tell "just created" apart from
  * "created → fulfilled" apart from "no-op re-delivery of the same status",
  * without a second round trip.
  */

package/apps/storefront/src/lib/apps/registryService.ts

@@ -1,8 +1,8 @@
 /**
- * App registry service — PrivateApps epic, D2 (Chunk A). Owns the
+ * App registry service. Owns the
  * `app_installs` / `app_audit_log` rows described in `schema.ts` and
  * orchestrates credential lifecycle through the {@link CredentialPort} seam
- * (Chunk B implements it; Chunk A only depends on the interface, mirroring
+ * (the credential store implements it; this service depends only on the interface, mirroring
  * how `D1VersionStore` implements `@tot/private-controlplane`'s `VersionStore`
  * contract without either side importing the other's internals).
  *
@@ -131,7 +131,7 @@ export interface IssuedCredential {
 
 /**
  * `IssuedCredential` plus the one-time plaintext secret. `issue`/`rotate` mint
- * the secret, hash it for storage (Chunk B: `sha256Hex`), and hand the
+ * the secret, hash it for storage (`sha256Hex`), and hand the
  * plaintext back exactly once here — there is no "show secret again" path by
  * design, so a caller that discards this return has lost it for good (see
  * `AppRegistryService.install`'s `InstallResult`, which is why this seam
@@ -140,10 +140,10 @@ export interface IssuedCredential {
 export type IssuedCredentialSecret = IssuedCredential & { secret: string };
 
 /**
- * Minimal seam for the credential lifecycle a later chunk (D2 Chunk B)
+ * Minimal seam for the credential lifecycle the credential store
  * implements against `app_credentials`. `AppRegistryService` orchestrates
  * through this interface only — it never touches credential storage directly,
- * so Chunk A can ship and be tested (with a fake) without Chunk B existing.
+ * so it can be tested with a fake.
  */
 export interface CredentialPort {
   /** Issue a fresh client-credential set for a newly installed app. */
@@ -155,7 +155,7 @@ export interface CredentialPort {
 }
 
 /**
- * The 3 platform-owned widget slots (D5 Chunk A). Mirrors the `widgets[].placement`
+ * The 3 platform-owned widget slots. Mirrors the `widgets[].placement`
  * enum in `docs/private-apps/contract/tot-app.schema.json` — widgets render in a
  * platform-managed sandboxed iframe at one of these fixed slots, never as
  * merchant-pasted script at an app-chosen location.

package/apps/storefront/src/lib/apps/scopes.ts

@@ -1,6 +1,6 @@
 /**
- * Scope validation — the compliance-floor gate for Storefront Private Apps
- * (PrivateApps epic, D2). See `docs/private-apps/feature-brief.md` §"The
+ * Scope validation — the compliance-floor gate for Storefront Private Apps.
+ * See `docs/private-apps/feature-brief.md` §"The
  * compliance floor" and the machine-readable contract:
  *   - `docs/private-apps/contract/scopes.json` — the 8-scope V1 catalog.
  *   - `docs/private-apps/contract/forbidden-scopes.json` — the 8 ids that map

package/apps/storefront/src/lib/apps/tokenIssuer.ts

@@ -1,7 +1,7 @@
 /**
  * OAuth2 client-credentials token issuer — the Storefront App Gateway's
- * `POST /oauth/token` grant (PrivateApps epic, D2 Chunk B). Mints the
- * short-lived RS256 JWT a private app presents as a bearer token to the D3
+ * `POST /oauth/token` grant. Mints the
+ * short-lived RS256 JWT a private app presents as a bearer token to the
  * scoped APIs.
  *
  * `tenant` and `env` are supplied by the CALLER (the route, from
@@ -97,8 +97,8 @@ export class AppTokenIssuer {
       tenant: install.tenantId,
       env: install.env,
       scopes: install.scopes,
-      // Discriminates this bearer token from a widget launch token (D5 Chunk
-      // B) so the two can never be replayed for each other even though both
+      // Discriminates this bearer token from a widget launch token so the two
+      // can never be replayed for each other even though both
       // are RS256 JWTs signed by the same gateway key — see tokenVerifier.ts.
       token_use: "access",
     })

package/apps/storefront/src/lib/apps/tokenVerifier.ts

@@ -1,7 +1,7 @@
 /**
  * Offline verification of the Storefront App Gateway's own OAuth2
- * client-credentials JWT (PrivateApps epic, D2 Chunk B) — this is what D3
- * imports at the scoped-API boundary to authorize an app's request.
+ * client-credentials JWT — this is what the scoped-API boundary
+ * imports to authorize an app's request.
  *
  * Modeled directly on `../auth/identityToken.ts`'s `IdentityAssertionVerifier`
  * (same `jwtVerify` + JWKS-by-`kid` shape, `aud`/`iss` pinning, alg allowlist),
@@ -25,7 +25,7 @@ import {
 } from "./gatewayKeys.js";
 import { readEnv } from "@/lib/env";
 
-/** The verified app-token claims (D3's authorization input). */
+/** The verified app-token claims (the scoped API's authorization input). */
 export interface AppTokenClaims {
   iss: string;
   sub: string; // install id
@@ -40,8 +40,8 @@ export interface AppTokenClaims {
 
 /** Normalize a jose JWT payload into typed {@link AppTokenClaims}, throwing on any missing claim. */
 function toAppTokenClaims(payload: Record<string, unknown>): AppTokenClaims {
-  // The security-critical discriminator: a widget launch token (D5 Chunk B,
-  // `token_use: "widget_launch"`) is signed by this SAME gateway key, so
+  // The security-critical discriminator: a widget launch token
+  // (`token_use: "widget_launch"`) is signed by this SAME gateway key, so
   // signature/aud/iss/exp checks alone can't tell it apart from a bearer
   // token. Requiring `token_use === "access"` here is what stops a launch
   // token — minted for a sandboxed iframe, short-TTL, no scopes checked —
@@ -128,7 +128,7 @@ export class AppTokenVerifier {
 /**
  * Get (or build) the verifier for one tenant, from the gateway's own
  * locally-derived JWKS. Returns `null` when the signing key isn't configured
- * — callers (D3 routes) fail closed with 503, mirroring `getIdentityVerifier`.
+ * — callers (the scoped-API routes) fail closed with 503, mirroring `getIdentityVerifier`.
  * Not cached across calls (unlike `identityToken.ts`'s remote-fetch verifier):
  * deriving the local JWKS is cheap (`gatewayKeys.ts` caches the export itself).
  */