@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

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

@@ -0,0 +1,291 @@
+/**
+ * Offline dogfood of the eight v84 nonportable-code dispositions.
+ *
+ * This module sees only reviewed, redacted dossier metadata. It can emit typed
+ * semantic events into an in-memory callback, evaluate a pure path mapping, or
+ * record an inert retirement. It has no destination, browser, renderer,
+ * persistence, network, install, publish, or source-tenant capability.
+ */
+import {
+  CONSENT_CONFIG_SCHEMA_VERSION,
+  CommerceEventBroker,
+  ManagedAnalyticsEventBrokerBridge,
+  buildTenantConsentBroker,
+  validateConsentConfig,
+  validateTenantActionRegistry,
+  type CommerceEvent,
+} from "@tot/public-runtime";
+import type {
+  V84NonportableCodeIntentDossier,
+} from "./v84NonportableCodeCoaching.js";
+import type { V84CloneMigrationEvidence } from "./v84CloneMigrationEvidence.js";
+import { assertExactV84DogfoodContract } from "./v84NonportableRouteContract.js";
+import {
+  sameV84ReplayValue,
+  type V84CleanCloneReplayContext,
+} from "./v84CleanCloneReplayContext.js";
+
+const SOURCE = "tokenoftrust.com" as const;
+const CLONE = "tokenoftrust.com~clone~gtm-migration-v84" as const;
+const AT = "2026-08-30T00:00:00.000Z";
+const CORRELATION = { id: "corr-v84-nonportable-dogfood", expiresAt: "2026-08-30T02:00:00.000Z" };
+const PROTECTED = ["admin", "account", "identity", "age-assurance", "checkout", "payment"] as const;
+
+export type V84DogfoodOutcome = "converted" | "retired" | "evidence-rejected";
+
+export interface V84DogfoodLedgerRow {
+  readonly identity: string;
+  readonly intent: string;
+  readonly route: string;
+  readonly attemptedSteps: readonly string[];
+  readonly artifact: Readonly<Record<string, unknown>>;
+  readonly expectedVersusActual: { readonly expected: string; readonly actual: string };
+  readonly testsAndCloneQa: readonly string[];
+  readonly rollbackProof: string;
+  readonly finalOutcome: V84DogfoodOutcome;
+  readonly productRunbookGap: string | null;
+}
+
+function consentBroker() {
+  const checked = validateConsentConfig({
+    schemaVersion: CONSENT_CONFIG_SCHEMA_VERSION,
+    purposes: [{ purpose: "analytics", legalBasis: "consent", defaultState: "denied" }],
+    cmp: { mode: "none" },
+  });
+  if (!checked.ok) throw new Error("The fixed local consent policy is invalid.");
+  const broker = buildTenantConsentBroker(checked.value);
+  broker.setDecisions({ analytics: "granted" });
+  return broker;
+}
+
+function vendorAdapterId(dossier: V84NonportableCodeIntentDossier): string {
+  const ids: Readonly<Record<string, string>> = {
+    "tag:4": "platform.hubspot",
+    "tag:18": "platform.capterra",
+    "tag:29": "platform.linkedin",
+    "tag:31": "platform.g2",
+  };
+  const adapterId = ids[dossier.sourceObject.nodeKey];
+  if (!adapterId) throw new Error("The vendor destination route is not reviewed.");
+  return adapterId;
+}
+
+function exerciseNativeHook(dossier: V84NonportableCodeIntentDossier) {
+  const catalogLookup = { adapterId: vendorAdapterId(dossier), found: false } as const;
+  if (dossier.requiredContract.actionSelection === "owner-selection-required") {
+    return {
+      kind: "native-contract-refusal",
+      hook: dossier.recommendedTotPort.nativeHook,
+      approvedChoices: [...dossier.requiredContract.approvedActionNames],
+      deliveryCount: 0,
+      reason: "owner-action-selection-required",
+      catalogLookup,
+    } as const;
+  }
+  const registry = validateTenantActionRegistry({
+    schemaVersion: 1,
+    actions: dossier.requiredContract.approvedActionNames.map((name) => ({ name })),
+  });
+  if (!registry.ok) throw new Error("The dossier action contract is invalid.");
+  const consent = consentBroker();
+  const delivered: CommerceEvent[] = [];
+  const broker = new CommerceEventBroker({
+    trusted: { tenant: CLONE, environment: "candidate", siteSurface: "marketing" },
+    source: `urn:tot:storefront:v84-dogfood:${dossier.dossierId}`,
+    consentSnapshot: () => consent.getSnapshot(),
+    tenantActionRegistry: registry.value,
+    now: () => AT,
+  });
+  broker.subscribe({
+    id: `fake-local-${dossier.dossierId}`,
+    consentPurpose: "analytics",
+    types: dossier.recommendedTotPort.nativeHook ? [dossier.recommendedTotPort.nativeHook] : [],
+    sink: { kind: "callback", handler: (event) => delivered.push(event) },
+  });
+  const bridge = new ManagedAnalyticsEventBrokerBridge({ broker });
+  let results;
+  if (dossier.recommendedTotPort.nativeHook === "storefront.action.activated.v1") {
+    const initialized = bridge.initialize({ logicalId: `${dossier.dossierId}-document`, path: "/v84-dogfood", correlation: CORRELATION });
+    if (!initialized.ok || !initialized.emitted) throw new Error("The local action bridge did not initialize safely.");
+    results = dossier.requiredContract.approvedActionNames.map((name, index) =>
+      bridge.activate({ logicalId: `${dossier.dossierId}-action-${index + 1}`, name, correlation: CORRELATION }));
+  } else {
+    results = [bridge.initialize({ logicalId: dossier.dossierId, path: "/v84-dogfood", correlation: CORRELATION })];
+  }
+  bridge.dispose();
+  if (results.some((result) => !result.ok || !result.emitted) || delivered.length !== results.length) {
+    throw new Error("The local native-hook exercise did not deliver the exact typed event set.");
+  }
+  if (delivered.some((event) => event.storefront.tenant !== CLONE || event.storefront.environment === "live")) {
+    throw new Error("The local native-hook exercise escaped the diagnostic clone.");
+  }
+  return {
+    kind: "in-memory-native-event-proof",
+    hook: delivered[0]?.type,
+    payloads: delivered.map((event) => event.data),
+    payloadKeys: [...new Set(delivered.flatMap((event) => Object.keys(event.data)))].sort(),
+    deliveryCount: delivered.length,
+    destination: "fake-local-callback",
+    disposed: true,
+    catalogLookup,
+  } as const;
+}
+
+function retire(dossier: V84NonportableCodeIntentDossier, replayContext?: V84CleanCloneReplayContext) {
+  if (dossier.recommendedTotPort.nativeHook !== null) {
+    throw new Error("A retirement dossier unexpectedly requested runtime authority.");
+  }
+  const cloneLocalMarkers = new Set<string>();
+  const marker = `${CLONE}:retired:${dossier.sourceObject.nodeKey}`;
+  const markerKey = `stage/dogfood/retirement/${dossier.sourceObject.nodeKey}`;
+  if (replayContext) replayContext.write(markerKey, marker);
+  else cloneLocalMarkers.add(marker);
+  const markerObserved = replayContext
+    ? replayContext.read<string>(markerKey) === marker
+    : cloneLocalMarkers.has(marker);
+  if (replayContext) replayContext.delete(markerKey);
+  else cloneLocalMarkers.delete(marker);
+  const markerRemoved = replayContext
+    ? replayContext.read<string>(markerKey) === undefined
+    : !cloneLocalMarkers.has(marker);
+  if (!markerObserved || !markerRemoved) throw new Error("The inert retirement marker was not reversible.");
+  return {
+    kind: "inert-retirement-record",
+    retained: { nodeKey: dossier.sourceObject.nodeKey, dossierId: dossier.dossierId },
+    runtimeAuthority: "none",
+    installCreated: false,
+    markerObserved,
+    markerRemoved,
+  } as const;
+}
+
+function rejectedGap(dossier: V84NonportableCodeIntentDossier): string {
+  if (dossier.sourceObject.nodeKey === "variable:38") {
+    return "consumer decision required: name the consumer and approve a closed output enum before conversion";
+  }
+  const gap = dossier.recommendedTotPort.owningProductGap;
+  if (!gap) throw new Error("A non-retirement route lacks an exact owning-product gap.");
+  const ownerGap = dossier.requiredContract.actionSelection === "owner-selection-required"
+    ? "; consumer owner must select one approved action name"
+    : "";
+  return `owning product capability unavailable: ${gap}${ownerGap}`;
+}
+
+function exercise(
+  dossier: V84NonportableCodeIntentDossier,
+  replayContext?: V84CleanCloneReplayContext,
+): V84DogfoodLedgerRow {
+  if (dossier.recommendedTotPort.route === "retire") {
+    return {
+      identity: dossier.sourceObject.nodeKey,
+      intent: dossier.recoveredBusinessIntent,
+      route: "retire",
+      attemptedSteps: ["matched the exact redacted identity and graph role", "asserted no native hook", "created and observed a clone-local inert marker", "removed the marker"],
+      artifact: retire(dossier, replayContext),
+      expectedVersusActual: {
+        expected: "retain audit identity with zero runtime behavior",
+        actual: "inert retirement recorded; no install, hook, destination, or runtime authority created",
+      },
+      testsAndCloneQa: ["identity accounted once", "dependency graph checked", "marker observed then removed", "no hook requested", "clone effect counters remain zero"],
+      rollbackProof: "No runtime state exists to restore; removing the inert record leaves behavior unchanged.",
+      finalOutcome: "retired",
+      productRunbookGap: null,
+    };
+  }
+  const isMapping = dossier.recommendedTotPort.route === "declarative-typed-mapping";
+  const artifact = isMapping ? {
+    kind: "declarative-conversion-refusal",
+    observedGraph: { consumer: "trigger:39", variable: "variable:38", consumingTagCount: 0 },
+    mappingCreated: false,
+    reason: "named-consumer-and-output-enum-unresolved",
+  } as const : exerciseNativeHook(dossier);
+  const gap = rejectedGap(dossier);
+  return {
+    identity: dossier.sourceObject.nodeKey,
+    intent: dossier.recoveredBusinessIntent,
+    route: dossier.recommendedTotPort.route,
+    attemptedSteps: isMapping
+      ? ["verified trigger:39 references variable:38", "verified no tag consumes trigger:39", "looked for a named consumer and approved output enum", "refused to invent a mapping"]
+      : dossier.requiredContract.actionSelection === "owner-selection-required"
+        ? ["validated the closed action choice set", "refused to choose for the owner", "confirmed zero delivery", "looked up the owned destination"]
+        : ["validated the closed native event contract", "granted local analytics consent", "delivered the exact typed event set to an in-memory callback", "disposed the bridge", "looked up the owned destination"],
+    artifact,
+    expectedVersusActual: {
+      expected: dossier.recommendedTotPort.saferAlternative,
+      actual: dossier.requiredContract.actionSelection === "owner-selection-required"
+        ? `closed choice set validated with zero emission; exercise stopped: ${gap}`
+        : isMapping
+          ? `no mapping was created; exercise stopped: ${gap}`
+          : `safe local native contract exercise passed, but conversion stopped: ${gap}`,
+    },
+    testsAndCloneQa: isMapping
+      ? ["exact graph edge is present", "consumer tag count is zero", "no mapping or destination effect exists"]
+      : dossier.requiredContract.actionSelection === "owner-selection-required"
+        ? ["all approved choices retained", "zero events emitted before owner selection", "managed vendor adapter absent"]
+        : ["typed payload set delivered exactly once each", "clone tenant and candidate environment pinned", "fake callback disposed", "protected surfaces excluded"],
+    rollbackProof: isMapping
+      ? "Discarding the refusal artifact leaves the prior no-mapping state unchanged; no consumer was connected."
+      : dossier.requiredContract.actionSelection === "owner-selection-required"
+        ? "No subscriber, event, install, or destination state was created before the required owner decision."
+        : "Disposal removes the only in-memory subscriber; no install or destination state exists.",
+    finalOutcome: "evidence-rejected",
+    productRunbookGap: gap,
+  };
+}
+
+/** Exercise every reviewed route and return a terminal eight-row ledger. */
+export function buildV84NonportableRouteDogfood(
+  evidence: V84CloneMigrationEvidence,
+  catalogAdapterIds: readonly string[],
+  replayContext?: V84CleanCloneReplayContext,
+) {
+  if (replayContext && !sameV84ReplayValue(
+    replayContext.read<V84CloneMigrationEvidence>("stage/import/handoff"),
+    evidence,
+  )) {
+    throw new Error("The dogfood proof did not receive the shared import handoff.");
+  }
+  const safe = assertExactV84DogfoodContract(evidence, catalogAdapterIds);
+  const coaching = safe.evidence.nonportableCodeCoaching;
+  if (!coaching.policy.sourceReadOnly || !coaching.policy.importedArtifactsInert || coaching.policy.installsOrPublishes) {
+    throw new Error("The coaching policy is outside the inert diagnostic scope.");
+  }
+  if (coaching.dossiers.length !== 8 || new Set(coaching.dossiers.map((item) => item.sourceObject.nodeKey)).size !== 8) {
+    throw new Error("The dogfood gate requires exactly eight unique dossiers.");
+  }
+  if (coaching.dossiers.some((item) => item.recommendedTotPort.status !== "not-installed")) {
+    throw new Error("The dogfood input must be the reviewed pre-install coaching state.");
+  }
+  const ledger = coaching.dossiers.map((dossier) => exercise(dossier, replayContext));
+  if (ledger.some((row) => !["converted", "retired", "evidence-rejected"].includes(row.finalOutcome))) {
+    throw new Error("Every dogfood route must end in an explicit terminal outcome.");
+  }
+  const result = {
+    schemaVersion: 1 as const,
+    scope: { sourceTenant: SOURCE, sourceMode: "read-only-fixture" as const, cloneTenant: CLONE, destinationMode: "fake-local-only" as const },
+    ledger,
+    summary: {
+      total: ledger.length,
+      converted: ledger.filter((row) => row.finalOutcome === "converted").length,
+      retired: ledger.filter((row) => row.finalOutcome === "retired").length,
+      evidenceRejected: ledger.filter((row) => row.finalOutcome === "evidence-rejected").length,
+      unexplainedNotInstalled: 0,
+    },
+    catalogLookup: {
+      presentAdapterIds: [...safe.catalogAdapterIds].sort(),
+      requestedVendorAdapterIds: ["platform.hubspot", "platform.capterra", "platform.linkedin", "platform.g2"],
+      missingVendorAdapterIds: ["platform.hubspot", "platform.capterra", "platform.linkedin", "platform.g2"],
+    },
+    safety: {
+      sourceReads: 0, sourceWrites: 0, clonePersistentWrites: 0, externalNetworkRequests: 0,
+      liveSecretsUsed: 0, productionActions: 0, importedCodeExecuted: false,
+      originalMarkupRendered: false, runtimeLoaderInitialized: false, dataLayerTouched: false,
+    },
+    protectedSurfaces: [...PROTECTED],
+  };
+  if (replayContext) {
+    for (const row of ledger) replayContext.write(`stage/dogfood/artifacts/${row.identity}`, row.artifact);
+    replayContext.write("stage/dogfood/handoff", result);
+  }
+  return result;
+}

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/apps/ws1ManagedAnalyticsClient.ts

@@ -0,0 +1,95 @@
+/**
+ * The EDGE transport for the pinned managed-analytics v1 contract: a thin HTTP
+ * adapter that satisfies {@link Ws1ManagedAnalyticsClient} by POSTing each
+ * pinned request to WS1's lifecycle service and returning the pinned response
+ * shape. WS1 owns the actual service; this file only carries the request over
+ * the wire.
+ *
+ * Tenant authority is server-derived, exactly as the pinned contract demands
+ * ("no request in this module accepts a tenant id"): the tenant is sent as a
+ * server-to-server header alongside the service credential — NEVER in a request
+ * body, and NEVER read from the caller's request body. Unconfigured service URL
+ * -> `null` (the route answers 503), never a guess.
+ */
+import type { APIContext } from "astro";
+import {
+  MANAGED_ANALYTICS_API_V1_VERSION_POLICY,
+  type CreateMigrationDraftRequest,
+  type CreateMigrationDraftResponse,
+} from "@tot/public-runtime";
+import { readEnv } from "../env.js";
+import type { Ws1ManagedAnalyticsClient } from "./gtmMigrationInstall.js";
+
+export interface Ws1ManagedAnalyticsMigrationClient extends Ws1ManagedAnalyticsClient {
+  createMigrationDraft(request: CreateMigrationDraftRequest): Promise<CreateMigrationDraftResponse>;
+}
+
+export type Ws1Fetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+/** Base URL of WS1's managed-analytics lifecycle service (scheme + host). */
+const SERVICE_URL_ENV = "MANAGED_ANALYTICS_API_URL";
+/** Server-to-server bearer credential for WS1 (scopes the tenant server-side). */
+const SERVICE_SECRET_ENV = "MANAGED_ANALYTICS_API_SECRET";
+
+/** The versioned base path, taken from the pinned version policy — never hard-coded twice. */
+const V1_PATH = MANAGED_ANALYTICS_API_V1_VERSION_POLICY.path;
+
+/** POST one pinned request to `<base><v1>/<operation>` and return the parsed pinned response. */
+function post<TReq, TRes>(
+  fetchImpl: Ws1Fetch,
+  baseUrl: string,
+  operation: string,
+  headers: Record<string, string>,
+): (request: TReq) => Promise<TRes> {
+  return async (request: TReq): Promise<TRes> => {
+    const res = await fetchImpl(`${baseUrl}${V1_PATH}/${operation}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headers },
+      body: JSON.stringify(request),
+    });
+    // WS1 returns the pinned success OR error envelope as JSON for every status.
+    return (await res.json()) as TRes;
+  };
+}
+
+/** Build the tenant-bound public WS1 HTTP client; tests may inject a no-network fetch. */
+export function createWs1ManagedAnalyticsClient(input: {
+  readonly baseUrl: string;
+  readonly tenantId: string;
+  readonly authorization?: string;
+  readonly fetchImpl?: Ws1Fetch;
+}): Ws1ManagedAnalyticsMigrationClient {
+  const baseUrl = input.baseUrl.replace(/\/$/, "");
+  const headers: Record<string, string> = { "x-tot-tenant": input.tenantId };
+  if (input.authorization) headers.authorization = input.authorization;
+  const fetchImpl = input.fetchImpl ?? fetch;
+  return {
+    getMigrationDraft: post(fetchImpl, baseUrl, "getMigrationDraft", headers),
+    createMigrationDraft: post(fetchImpl, baseUrl, "createMigrationDraft", headers),
+    getAdapterDefinition: post(fetchImpl, baseUrl, "getAdapterDefinition", headers),
+    getIntegrationInstall: post(fetchImpl, baseUrl, "getIntegrationInstall", headers),
+    createIntegrationInstall: post(fetchImpl, baseUrl, "createIntegrationInstall", headers),
+    reviseIntegrationInstall: post(fetchImpl, baseUrl, "reviseIntegrationInstall", headers),
+  };
+}
+
+/**
+ * Build an HTTP-backed {@link Ws1ManagedAnalyticsClient} for `tenantId`, or
+ * `null` when WS1's service URL isn't configured in this runtime. `tenantId`
+ * comes from the resolved operator session — never the request body — and is
+ * sent as a server-to-server header, keeping every request body tenant-free per
+ * the pinned contract.
+ */
+export async function resolveWs1ManagedAnalyticsClient(
+  _context: APIContext,
+  tenantId: string,
+): Promise<Ws1ManagedAnalyticsClient | null> {
+  const baseUrl = (await readEnv(SERVICE_URL_ENV))?.replace(/\/$/, "");
+  if (!baseUrl) return null;
+  const secret = await readEnv(SERVICE_SECRET_ENV);
+  return createWs1ManagedAnalyticsClient({
+    baseUrl,
+    tenantId,
+    ...(secret ? { authorization: `Bearer ${secret}` } : {}),
+  });
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Fail-closed access guard for tenant-scoped admin APIs (`/api/admin/**`).
+ *
+ * The admin JSON routes must NOT trust the ambient login gate for their auth:
+ * that gate is conditional (`DEMO_GATE_MODE="login"` on a gated host), so a route
+ * that leans on it is wide open on any non-gated host. This guard makes each
+ * admin API validate the caller EXPLICITLY, bound to the Host-resolved tenant
+ * (`locals.tenant.appDomain` — never a client value, never a default), and
+ * deny-closed on absence:
+ *
+ *   no session                        → 401 sign_in_required
+ *   session, but no standing for THIS tenant → 403 not_authorized
+ *   member/owner (or staff) of THIS tenant   → allowed, entry returned
+ *
+ * The decision core is PURE (unit-testable); `requireAdminApiEntry` is the thin
+ * Astro/I-O wrapper the routes call.
+ */
+import type { APIContext } from "astro";
+import { readViewerSession } from "@/lib/auth/route";
+import { resolveAdminEntry, type AdminEntryDecision } from "@/lib/auth/adminEntry";
+import type { SessionRecord } from "./session.js";
+
+export type AdminApiAccess =
+  | { ok: true; entry: AdminEntryDecision }
+  | { ok: false; status: 401 | 403; reason: "sign_in_required" | "not_authorized" };
+
+/**
+ * PURE fail-closed decision for a tenant-scoped admin API caller.
+ *
+ * @param requireOwner when true, only an owner/admin viewer OR a ToT-staff viewer
+ *   passes (a plain team member is refused) — for routes that mutate/expose
+ *   owner-level operational surfaces. Default (false) admits any member/owner/staff
+ *   of the tenant, matching who reaches the admin shell.
+ */
+export function decideAdminApiAccess(input: {
+  record: SessionRecord | null | undefined;
+  hostResource: string;
+  nowSeconds: number;
+  requireOwner?: boolean;
+}): AdminApiAccess {
+  const { record, hostResource, nowSeconds, requireOwner } = input;
+  if (!record) return { ok: false, status: 401, reason: "sign_in_required" };
+
+  const entry = resolveAdminEntry({ record, hostResource, nowSeconds });
+  const staffScope = Array.isArray(record.staff) && record.staff.length > 0;
+  const authorized = requireOwner
+    ? entry.isOwnerViewer || staffScope
+    : entry.admitted;
+  if (!authorized) return { ok: false, status: 403, reason: "not_authorized" };
+
+  return { ok: true, entry };
+}
+
+/** Astro wrapper: read the viewer session and decide, bound to the routed tenant. */
+export async function requireAdminApiEntry(
+  context: APIContext,
+  opts?: { requireOwner?: boolean },
+): Promise<AdminApiAccess> {
+  const record = await readViewerSession(context);
+  return decideAdminApiAccess({
+    record,
+    hostResource: context.locals.tenant?.appDomain ?? "",
+    nowSeconds: Math.floor(Date.now() / 1000),
+    requireOwner: opts?.requireOwner,
+  });
+}

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
@@ -30,11 +30,11 @@
  */
 import type { SessionRecord } from "./session.js";
 import { sessionHostCapability } from "./loginGate.js";
-import { decideIsOwner } from "@/lib/change/route";
+import { decideIsOwner } from "@/lib/change/route/route";
 import {
   resolveShipCapabilities,
   type ShipCapabilities,
-} from "@/lib/change/shipCapabilities";
+} from "@/lib/change/route/ship-capabilities";
 import type { Capability } from "@/lib/change/types";
 import { OWNER_CAPABILITIES } from "@/lib/grants/session";
 
@@ -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,