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

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).
  */

package/apps/storefront/src/lib/apps/widgets/eligibility.ts

@@ -1,10 +1,10 @@
 /**
- * Widget eligibility — PrivateApps epic, D5 (Chunk C). Mirrors
+ * Widget eligibility. Mirrors
  * `webhooks/emit.ts`'s `isEligibleTarget` discipline: an install is eligible
  * to render its widget at `slot` only while it is LIVE — `active`, scoped for
  * `widgets:launch`, and carrying a validated placement for that slot. This
  * live check is what makes suspending an install actually stop it rendering
- * on the very next page load — the D8 "suspension kills widgets"
+ * on the very next page load — the "suspension kills widgets"
  * enforcement — with no separate revoke step; it's just this gate re-run on
  * every request.
  */

package/apps/storefront/src/lib/apps/widgets/frameProps.ts

@@ -1,7 +1,7 @@
 /**
- * Pure prop-building for `<AppWidgetFrame>` — PrivateApps epic, D5 (Chunk D).
- * Split out of the `.astro` component so the query-param handoff and the
- * sandbox attrs are unit-testable: `vitest.config.ts` deliberately does NOT
+ * Pure prop-building for `<AppWidgetFrame>`. The query-param handoff and the
+ * sandbox attrs live here (not in the `.astro` component) so they are
+ * unit-testable: `vitest.config.ts` deliberately does NOT
  * render `.astro` components (Astro Container API breaks under vitest@2 +
  * astro@7 — see that file's docstring), so render *logic* lives here and
  * rendered output is verified on a live preview instead.

package/apps/storefront/src/lib/apps/widgets/launchToken.ts

@@ -1,7 +1,7 @@
 /**
- * Widget launch-token minting — PrivateApps epic, D5 Chunk B. Mints the
+ * Widget launch-token minting. Mints the
  * short-lived RS256 JWT a platform-managed sandboxed widget iframe carries at
- * SSR render time: Chunk D calls `mintWidgetLaunchToken` while rendering the
+ * SSR render time: the page-render path calls `mintWidgetLaunchToken` while rendering the
  * page for each declared placement, and the resulting token is what the
  * widget's own endpoint receives as proof it was launched by THIS platform,
  * for THIS install, at THIS placement — never a merchant-forged or replayed
@@ -31,10 +31,10 @@ import {
 export interface MintWidgetLaunchTokenInput {
   /**
    * Only `installId`/`tenantId`/`env` are read. Narrowed from `AppInstall` to
-   * this `Pick` so Chunk D's render path — which has `placements.ts`'s
+   * this `Pick` so the render path — which has `placements.ts`'s
    * `ResolvedPlacement` (installId/appOrigin/endpoint), not the full
    * `AppInstall` — can build the minimal object itself instead of re-fetching
-   * the install; a full `AppInstall` still satisfies this shape unchanged.
+   * the install; a full `AppInstall` still satisfies this shape.
    */
   install: Pick<AppInstall, "installId" | "tenantId" | "env">;
   slot: WidgetPlacement;

package/apps/storefront/src/lib/apps/widgets/placements.ts

@@ -1,6 +1,6 @@
 /**
- * Widget placement resolution — PrivateApps epic, D5 (Chunk C). Turns "which
- * apps have a live widget at this slot" into the concrete list Chunk D needs
+ * Widget placement resolution. Turns "which
+ * apps have a live widget at this slot" into the concrete list the render path needs
  * to render sandboxed iframes and mint launch tokens: reads
  * `registry.listByTenant`, filters to the requested `env` and
  * {@link isWidgetEligible}, then reads each eligible install's `endpoint`

package/apps/storefront/src/lib/apps/widgets/renderSlot.ts

@@ -1,5 +1,5 @@
 /**
- * Widget slot render composition — PrivateApps epic, D5 (Chunk D). The one
+ * Widget slot render composition. The one
  * call a page/layout makes to turn "render slot X for this request" into the
  * concrete, launch-token-bearing list `AppWidgetFrame` needs: resolves live
  * placements (`placements.ts`), mints each one a launch token

package/apps/storefront/src/lib/auth/adminEntry.ts

@@ -1,10 +1,10 @@
 /**
- * Admin session-entry resolution (unit dg6) — the SERVER-SIDE decision that puts
+ * Admin session-entry resolution — the SERVER-SIDE decision that puts
  * an authenticated owner/team member into the CORRECT tenant admin context, and
  * keeps a non-member / unauthenticated visitor on the legitimate sign-in gate.
  *
- * NARROW to auth/session ENTRY: it CONSUMES the go-live admin tab UX
- * (`pages/admin.astro` + `components/admin/AdminPublishTab.astro`) and u10's
+ * NARROW to auth/session ENTRY: it CONSUMES the admin tab UX
+ * (`pages/admin.astro` + `components/admin/AdminPublishTab.astro`) and the
  * ship-capability model (`change/shipCapabilities` + `change/route` decideIsOwner)
  * rather than reimplementing either. Everything it resolves is bound to the
  * RESOLVED tenant, never taken from client input, and never requires a
@@ -14,15 +14,15 @@
  *   - `hostCapability` — the viewer's owner/admin/member standing FOR THIS host,
  *     from {@link sessionHostCapability} (tenants[] membership → resource-scoped
  *     session → live staff selection). null ⇒ not a member of this tenant.
- *   - `isOwnerViewer` / `shipCapabilities` — u10's {@link decideIsOwner} +
+ *   - `isOwnerViewer` / `shipCapabilities` — {@link decideIsOwner} +
  *     {@link resolveShipCapabilities} over that host-bound capability. This is the
- *     OWNER VIEWER identity (decision `owner-identity-narrow-viewer-not-bearer-console`):
+ *     OWNER VIEWER identity:
  *     a signed-in owner/admin viewer over the resolved tenant, NOT the bearer
  *     operator console. The ship-axis `capability` is the fail-closed
  *     `preview-access` — a viewer session carries no operator ship grant, so the
  *     owner is the ONLY source of `shipOnBehalf`/`apexCutover` here.
  *
- * The distinguishing logic the go-live "definition of done" demands: `admitted`
+ * The distinguishing logic: `admitted`
  * separates an authenticated OWNER/member (a host-bound capability, or ToT-staff
  * scope) — who must NEVER see the "Coming soon" holding page at their own admin —
  * from an authenticated NON-member and an anonymous visitor, who legitimately do
@@ -56,9 +56,9 @@ export interface AdminEntryDecision {
   admitted: boolean;
   /** The owner/admin/member standing bound to this host, or null. */
   hostCapability: string | null;
-  /** u10: the acting viewer IS the tenant owner/admin (superset of ship-on-behalf). */
+  /** The acting viewer IS the tenant owner/admin (superset of ship-on-behalf). */
   isOwnerViewer: boolean;
-  /** u10: the two derived ship-gate capabilities for this viewer entry. */
+  /** The two derived ship-gate capabilities for this viewer entry. */
   shipCapabilities: ShipCapabilities;
   /** Which of the four entry cases this is. */
   principal: AdminEntryPrincipal;
@@ -90,7 +90,7 @@ export function resolveAdminEntry(input: {
   const staffScope = Array.isArray(record?.staff) && record!.staff.length > 0;
   const admitted = hostCapability !== null || staffScope;
 
-  // u10 owner resolution — the OWNER VIEWER, not the bearer console: authorized
+  // Owner resolution — the OWNER VIEWER, not the bearer console: authorized
   // (a member/staff viewer of THIS tenant) AND holding an owner/admin capability.
   const isOwnerViewer = decideIsOwner({
     authorized: admitted,