@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

package/apps/storefront/src/pages/api/activity.ts

@@ -1,7 +1,7 @@
 /**
  * POST /api/activity — the ingest endpoint of the operational activity telemetry
- * spine (card D4). Accepts one `ActivityEvent` (or a batch array) as JSON from
- * the emitter cohorts — the CLI (D3) and the UI (D6), both posting the wire shape
+ * spine. Accepts one `ActivityEvent` (or a batch array) as JSON from
+ * the emitter cohorts — the CLI and the UI, both posting the wire shape
  * of `packages/public-runtime/src/activity/event.ts` — authenticates the caller,
  * re-redacts server-side, and fans each accepted event out to the sink(s) its
  * catalog entry declares. See DECISIONS.md §8 for the store decision.
@@ -18,7 +18,7 @@
  * DEFENSE IN DEPTH — every event is rebuilt through `createActivityEvent()`
  * (`ingestEvents`), re-applying the default-deny allowlist + canary scan even
  * though emitters already redacted. A value-canary trip is self-telemetried as
- * `system.ingest.rejected` so a leak attempt is visible (D6/D7 alert on it).
+ * `system.ingest.rejected` so a leak attempt is visible for alerting.
  *
  * OFF THE CRITICAL PATH — auth + parse + validate + redact are cheap synchronous
  * CPU; the sink WRITES (D1 + Analytics Engine) run past the response via
@@ -50,7 +50,7 @@ function json(body: unknown, status: number): Response {
 }
 
 export async function POST(context: APIContext): Promise<Response> {
-  // Kill switch (D8): telemetry off ⇒ accept-and-drop. Fail-open toward the EMITTER —
+  // Kill switch: telemetry off ⇒ accept-and-drop. Fail-open toward the EMITTER —
   // a 202 (never a 4xx/5xx) so a CLI/UI poster never errors, retries, or is delayed by
   // the switch; nothing is validated, stored, or fanned out.
   if (isActivityDisabled()) {
@@ -96,8 +96,8 @@ export async function POST(context: APIContext): Promise<Response> {
 
   // Self-telemetry: a value-canary trip during server-side redaction means an
   // emitter leaked (or tried to leak) a secret/PII into the payload. Emit a
-  // `system.ingest.rejected` event (itself routed to logs+analytics) so D6/D7 can
-  // alert — the fact of the trip, the action, never the offending value. Rejected
+  // `system.ingest.rejected` event (itself routed to logs+analytics) so it can be
+  // alerted on — the fact of the trip, the action, never the offending value. Rejected
   // events get the same self-telemetry so a spoof/unknown-action attempt is
   // visible. Built here (synchronously) but fanned out off-path below.
   const selfTelemetry = [
@@ -127,9 +127,9 @@ export async function POST(context: APIContext): Promise<Response> {
 
   // Fan every accepted event + the self-telemetry out to its sinks, PAST the
   // response. Best-effort per sink (never throws). The adapter's per-request
-  // ExecutionContext lives at `locals.runtime.ctx`; runAfterResponse floats the
+  // ExecutionContext lives at `locals.cfContext`; runAfterResponse floats the
   // promise in dev/Node when it is absent.
-  const cfContext = (context.locals as { runtime?: { ctx?: CfExecutionContextLike } })?.runtime?.ctx ?? null;
+  const cfContext = (context.locals as { cfContext?: CfExecutionContextLike })?.cfContext ?? null;
   const work = Promise.all([...accepted.map((a) => a.event), ...selfTelemetry].map((e) => fanOutActivity(e, sinks)));
   runAfterResponse(work, cfContext);
 

package/apps/storefront/src/pages/api/admin/activity-alerts.ts

@@ -25,9 +25,7 @@
  * ops-timeline; never a URL/query value.
  */
 import type { APIContext } from "astro";
-import { readViewerSession } from "@/lib/auth/route";
-import { resolveAdminEntry } from "@/lib/auth/adminEntry";
-import { resolveAdminTenantMode } from "@/lib/adminTenantEnvelope";
+import { requireAdminApiEntry } from "@/lib/auth/adminApiGuard";
 import { readD1 } from "@/lib/env";
 import { fromD1 } from "@/lib/d1/catalog";
 import { checkActivityAlerts } from "@/lib/activity/alerts";
@@ -46,24 +44,11 @@ function json(body: unknown, status = 200): Response {
 
 export async function GET(context: APIContext): Promise<Response> {
   const { tenant } = context.locals;
-  const nowSeconds = Math.floor(Date.now() / 1000);
 
-  const viewerSession = await readViewerSession(context);
-  if (!viewerSession) return json({ ok: false, reason: "sign_in_required" }, 401);
-
-  const adminEntry = resolveAdminEntry({
-    record: viewerSession,
-    hostResource: tenant.appDomain,
-    nowSeconds,
-  });
-  const { isStaff } = resolveAdminTenantMode({
-    session: viewerSession,
-    adminAppTenant: tenant.appDomain,
-    requestedTarget: null,
-    nowSeconds,
-  });
-  const authorized = adminEntry.isOwnerViewer || isStaff;
-  if (!authorized) return json({ ok: false, reason: "not_authorized" }, 403);
+  // Owner/admin-of-tenant or ToT-staff only — same bar as /admin/ops-timeline,
+  // fail-closed and bound to the Host-resolved tenant.
+  const access = await requireAdminApiEntry(context, { requireOwner: true });
+  if (!access.ok) return json({ ok: false, reason: access.reason }, access.status);
 
   const d1 = await readD1("STOREFRONT_APPS_DB");
   if (!d1) return json({ ok: true, dbAvailable: false, alerts: [] });

package/apps/storefront/src/pages/api/admin/orders/[id].ts

@@ -1,13 +1,14 @@
 /**
- * `GET /api/admin/orders/:id` — one order's full detail for the Orders tab (U2).
+ * `GET /api/admin/orders/:id` — one order's full detail for the Orders tab.
  *
  * Server-side proxy to checkout `GET /commerce/orders/:orderId` for the
  * resolved tenant + env. Bearer stays server-side; response is the CheckoutOrderDetail
- * DTO. `verificationDetail` is empty until U4 fills it — consumers tolerate that.
+ * DTO. `verificationDetail` is currently empty — consumers tolerate that.
  * Read-only (scope-locks).
  */
 import type { APIContext } from "astro";
 import { readEnv } from "@/lib/env";
+import { requireAdminApiEntry } from "@/lib/auth/adminApiGuard";
 import {
   createCheckoutOrderClient,
   orderApiBaseUrl,
@@ -31,6 +32,10 @@ function jsonError(code: string, status: number): Response {
 
 export async function GET(context: APIContext): Promise<Response> {
   const { tenant, customizationEnv } = context.locals;
+
+  const access = await requireAdminApiEntry(context);
+  if (!access.ok) return jsonError(access.reason, access.status);
+
   const orderId = context.params.id;
   if (!orderId) return jsonError("order_not_found", 404);
 

package/apps/storefront/src/pages/api/admin/orders.ts

@@ -1,10 +1,10 @@
 /**
- * `GET /api/admin/orders` — internal admin route backing the Orders tab (U2).
+ * `GET /api/admin/orders` — internal admin route backing the Orders tab.
  *
  * Server-side proxy to the checkout order READ API for the resolved tenant +
  * environment. The per-tenant bearer key stays on the Worker (never in the
  * response); the browser only ever sees order DTO JSON. Read-only (scope-locks).
- * U3 consumes this and maps the DTO → OrdersViewModel.
+ * The admin UI consumes this and maps the DTO → OrdersViewModel.
  *
  * Access control matches the rest of the admin surface (owned by the admin
  * host/approver layer) — same posture as `api/evidence.json.ts`; no new gate here.
@@ -12,6 +12,7 @@
 import type { APIContext } from "astro";
 import type { CheckoutOrderListFilters } from "@tot/public-runtime";
 import { readEnv } from "@/lib/env";
+import { requireAdminApiEntry } from "@/lib/auth/adminApiGuard";
 import {
   createCheckoutOrderClient,
   orderApiBaseUrl,
@@ -36,6 +37,11 @@ function jsonError(code: string, status: number): Response {
 export async function GET(context: APIContext): Promise<Response> {
   const { tenant, customizationEnv } = context.locals;
 
+  // Fail closed: require a signed-in member/owner of THIS tenant, bound to the
+  // Host-resolved appDomain — never trusting the conditional login gate for auth.
+  const access = await requireAdminApiEntry(context);
+  if (!access.ok) return jsonError(access.reason, access.status);
+
   const bearer = await readEnv("FOXY_ORDER_API_KEY");
   if (!bearer) {
     // Worker secret not provisioned for this env — a config error, not the

package/apps/storefront/src/pages/api/apps/admin/gtm-migration-install.ts

@@ -0,0 +1,174 @@
+/**
+ * POST /api/apps/admin/gtm-migration-install — the review->install surface of
+ * the GTM migration assistant. It takes a reviewed draft's `draftId`, LOADS the
+ * stored draft server-side, and converts it into a DISABLED desired
+ * managed-analytics install + draft revision, strictly through WS1's pinned
+ * PUBLIC contract. It returns the resulting disabled install/revision + a
+ * correlation id.
+ *
+ * Auth mirrors the read-only analyze route (`gtm-migration.ts`): the tenant is
+ * `auth.tenantId` from the resolved operator session — NEVER the request body.
+ *
+ * SECURITY BOUNDARY (a reviewer enforces this):
+ *   - LOAD-BY-ID ONLY: the body carries a `draftId` (+ optional
+ *     `targetInstallId` and its original `expectedRevision`), never a draft
+ *     object. The stable mutation identity comes from the required
+ *     `Idempotency-Key` header. A body that tries to smuggle draft data
+ *     (`proposedConfiguration`/`proposedAdapterId`/`findings`/`draft`/inline
+ *     `configuration`) is rejected — the stored draft is loaded from WS1 and
+ *     re-validated against the pinned validator; untrusted draft data never gets
+ *     past review.
+ *   - DISABLED-ONLY: the produced install is `status:"disabled"` with a
+ *     `status:"draft"` revision. Any attempt to force enable/publish/activate in
+ *     the body is refused. This route imports NO registry/D1/R2/materializer/
+ *     lifecycle dependency and writes NOTHING to storefront's own stores — every
+ *     effect goes through the pinned WS1 client, which exposes no enable op.
+ */
+import type { APIContext } from "astro";
+import {
+  validateGetIntegrationInstallRequest,
+  validateGetMigrationDraftRequest,
+  validateMutationRequest,
+} from "@tot/public-runtime";
+import { resolveOperatorSession } from "@/lib/apps/adminSession.js";
+import { json } from "@/lib/apps/adminService.js";
+import {
+  reviewInstallDraft,
+  type ReviewInstallResult,
+  type Ws1ManagedAnalyticsClient,
+} from "@/lib/apps/gtmMigrationInstall.js";
+import { resolveWs1ManagedAnalyticsClient } from "@/lib/apps/ws1ManagedAnalyticsClient.js";
+
+export const prerender = false;
+
+/** Fields that would smuggle inline draft data past review — a body may carry only ids. */
+const DRAFT_DATA_FIELDS = ["draft", "proposedConfiguration", "proposedAdapterId", "findings", "configuration"] as const;
+/** Fields that would try to enable/publish/activate — this path produces a disabled draft only. */
+const ENABLE_FIELDS = ["status", "enabled", "enable", "publish", "publishes", "activate"] as const;
+
+interface ParsedRequest {
+  readonly draftId: string;
+  readonly targetInstallId?: string;
+  readonly expectedRevision?: number;
+}
+
+/** Parse ids plus optional revise CAS state, and NOTHING that could enable or resubmit a draft. */
+function parseRequest(body: unknown): ParsedRequest | { error: string } {
+  if (!body || typeof body !== "object") return { error: "A JSON object body with a draftId is required." };
+  const o = body as Record<string, unknown>;
+
+  for (const field of DRAFT_DATA_FIELDS) {
+    if (field in o) {
+      return { error: "Submit a draftId only; the reviewed draft is loaded server-side and cannot be supplied inline." };
+    }
+  }
+  for (const field of ENABLE_FIELDS) {
+    if (field in o) {
+      return { error: "This path produces a disabled draft only; it cannot enable, publish, or activate." };
+    }
+  }
+
+  const rawDraftId = o.draftId;
+  if (typeof rawDraftId !== "string" || !rawDraftId.trim()) return { error: "A draftId is required." };
+  const draftCheck = validateGetMigrationDraftRequest({
+    apiVersion: "v1",
+    query: { draftId: rawDraftId },
+  });
+  if (!draftCheck.ok) {
+    return { error: "draftId must be a valid opaque identifier." };
+  }
+  const draftId = draftCheck.value.query.draftId;
+
+  let targetInstallId: string | undefined;
+  if ("targetInstallId" in o) {
+    const t = o.targetInstallId;
+    if (typeof t !== "string" || !t.trim()) return { error: "targetInstallId must be a non-empty string when present." };
+    const installCheck = validateGetIntegrationInstallRequest({
+      apiVersion: "v1",
+      query: { installId: t },
+    });
+    if (!installCheck.ok) {
+      return { error: "targetInstallId must be a valid opaque identifier." };
+    }
+    targetInstallId = installCheck.value.query.installId;
+  }
+  let expectedRevision: number | undefined;
+  if ("expectedRevision" in o) {
+    if (!Number.isInteger(o.expectedRevision) || (o.expectedRevision as number) < 0) {
+      return { error: "expectedRevision must be a non-negative integer when present." };
+    }
+    expectedRevision = o.expectedRevision as number;
+  }
+  if (targetInstallId !== undefined && expectedRevision === undefined) {
+    return { error: "expectedRevision is required when targetInstallId is present so retries preserve the original CAS request." };
+  }
+  if (targetInstallId === undefined && expectedRevision !== undefined) {
+    return { error: "expectedRevision is only accepted when targetInstallId is present." };
+  }
+  return { draftId, targetInstallId, expectedRevision };
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const url = new URL(context.request.url);
+  const requestedTenant = url.searchParams.get("tenant");
+  const auth = await resolveOperatorSession(context, requestedTenant);
+  if (!auth.ok) return json({ error: auth.message }, auth.status);
+
+  const correlationId = crypto.randomUUID();
+
+  let body: unknown;
+  try {
+    body = await context.request.json();
+  } catch {
+    return json({ ok: false, correlationId, error: "The request body must be JSON." }, 400);
+  }
+
+  const parsed = parseRequest(body);
+  if ("error" in parsed) return json({ ok: false, correlationId, error: parsed.error }, 400);
+
+  const idempotencyKey = context.request.headers.get("idempotency-key")?.trim();
+  const keyCheck = validateMutationRequest({
+    apiVersion: "v1",
+    idempotencyKey,
+    expectedRevision: 0,
+    body: {},
+  });
+  if (!keyCheck.ok) {
+    return json({ ok: false, correlationId, error: "A valid Idempotency-Key header is required." }, 400);
+  }
+
+  let client: Ws1ManagedAnalyticsClient | null;
+  try {
+    client = await resolveWs1ManagedAnalyticsClient(context, auth.tenantId);
+  } catch {
+    return json({ ok: false, correlationId, error: "Managed analytics service resolution failed safely.", code: "internal_error" }, 502);
+  }
+  if (!client) return json({ ok: false, correlationId, error: "Managed analytics service is not configured." }, 503);
+
+  let result: ReviewInstallResult;
+  try {
+    result = await reviewInstallDraft(client, {
+      draftId: parsed.draftId,
+      targetInstallId: parsed.targetInstallId,
+      expectedRevision: parsed.expectedRevision,
+      idempotencyKey: keyCheck.value.idempotencyKey,
+      correlationId,
+    });
+  } catch {
+    return json({ ok: false, correlationId, error: "Managed analytics review failed safely.", code: "internal_error" }, 502);
+  }
+
+  if (!result.ok) {
+    return json({ ok: false, correlationId, error: result.error, code: result.code }, result.status);
+  }
+  return json(
+    {
+      ok: true,
+      correlationId,
+      install: result.install,
+      revision: result.revision,
+      idempotencyReplayed: result.idempotencyReplayed,
+    },
+    200,
+  );
+}

package/apps/storefront/src/pages/api/apps/admin/gtm-migration.ts

@@ -0,0 +1,96 @@
+/**
+ * POST /api/apps/admin/gtm-migration — the READ-ONLY "Migrate from GTM" analyze
+ * surface. Accepts an uploaded GTM container export (a JSON request body, or a
+ * `multipart/form-data` file part), runs the SAFE `@tot/public-runtime` pipeline
+ * (parse -> graph -> classify) over it, and returns a REDACTED report: object
+ * accounting, the disposition summary, per-object dispositions, the dependency
+ * graph, unresolved findings, and recommendations. `?format=bundle` returns the
+ * same report as a downloadable JSON attachment with a provenance stamp.
+ *
+ * Auth mirrors the read-only `integrations` route: the tenant is `auth.tenantId`
+ * from the resolved operator session — NEVER the request body — and any tenant
+ * membership admits (analyze is a diagnostic read, not a manage action).
+ *
+ * READ-ONLY BOUNDARY (a reviewer enforces this): this route writes NOTHING,
+ * builds no integration or draft, publishes nothing, activates nothing, and
+ * emits no markup/script/network-to-third-parties/event-listener. It imports
+ * only the operator-session gate, the JSON responder, and the pure, inert
+ * pipeline + report builder — no registry, D1, R2, or lifecycle dependency is
+ * imported or reachable. It parses inert data and returns a report. Ids from a
+ * foreign container are reflected back only; they are never used to look
+ * anything up about this tenant.
+ */
+import type { APIContext } from "astro";
+import { resolveOperatorSession } from "@/lib/apps/adminSession.js";
+import { json } from "@/lib/apps/adminService.js";
+import { analyzeGtmExport } from "@/lib/apps/gtmMigrationReport.js";
+
+export const prerender = false;
+
+/** The multipart field name the upload UI posts the export file under. */
+const FILE_FIELD = "file";
+
+/** Read the uploaded export text from a JSON body or a multipart file part. */
+async function readUploadText(request: Request): Promise<string | { error: string }> {
+  const contentType = (request.headers.get("content-type") ?? "").toLowerCase();
+  if (contentType.includes("multipart/form-data")) {
+    let form: FormData;
+    try {
+      form = await request.formData();
+    } catch {
+      return { error: "could not read the uploaded form" };
+    }
+    const part = form.get(FILE_FIELD);
+    if (part == null) return { error: `no "${FILE_FIELD}" part in the upload` };
+    if (typeof part === "string") return part;
+    return await part.text();
+  }
+  // Any other content type: the raw request body IS the export document.
+  return await request.text();
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const url = new URL(context.request.url);
+  const requestedTenant = url.searchParams.get("tenant");
+  const auth = await resolveOperatorSession(context, requestedTenant);
+  if (!auth.ok) return json({ error: auth.message }, auth.status);
+
+  const upload = await readUploadText(context.request);
+  const correlationId = crypto.randomUUID();
+  const generatedAt = new Date().toISOString();
+
+  if (typeof upload !== "string") {
+    return json({ ok: false, correlationId, error: upload.error, violations: [] }, 400);
+  }
+  if (upload.trim() === "") {
+    return json(
+      { ok: false, correlationId, error: "The upload was empty.", violations: [] },
+      400,
+    );
+  }
+
+  const result = analyzeGtmExport(upload, { tenantId: auth.tenantId, correlationId, generatedAt });
+
+  if (!result.ok) {
+    // Structured parse violations + a stable, safe error and the correlation id.
+    return json(
+      { ok: false, correlationId, error: result.error, violations: result.violations },
+      422,
+    );
+  }
+
+  const wantsBundle = url.searchParams.get("format") === "bundle";
+  const responseBody = { ok: true, correlationId, report: result.report };
+  if (!wantsBundle) return json(responseBody, 200);
+
+  // Support-bundle download: the same redacted report as a JSON attachment.
+  const filename = `gtm-migration-report-${correlationId}.json`;
+  return new Response(JSON.stringify(responseBody, null, 2), {
+    status: 200,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store",
+      "content-disposition": `attachment; filename="${filename}"`,
+    },
+  });
+}

package/apps/storefront/src/pages/api/apps/admin/integration-lifecycle.ts

@@ -0,0 +1,118 @@
+/**
+ * POST /api/apps/admin/integration-lifecycle — execute an integration-config
+ * lifecycle write action (ext-admin-07): `preview` a candidate (its effective
+ * code/config/CSP/consent/assurance diff), `publish` it to live THROUGH the
+ * policy-06 promotion gate, or `rollback` live to a known-good revision. The
+ * install-status actions (`suspend` / `resume` / `uninstall`) keep their own
+ * registry-backed routes; this route owns the three that ride the
+ * candidate/change-control substrate.
+ *
+ * Authorization mirrors every mutating admin route: `resolveOperatorSession`
+ * resolves the tenant from the host/console session (never the body), and
+ * `requireManageRole` denies a read-only console `developer` — so a developer or
+ * vendor never holds tenant publish authority. `requireOwnedInstall` rejects a
+ * foreign-tenant `installId` with the same 404 a missing one gets.
+ *
+ * The pure {@link handleLifecycleRequest} decides and persists ONLY on success —
+ * a blocked publish leaves the ACTUAL last-good state untouched. The lifecycle
+ * state + candidate-evidence + gate-input materialization is the control plane's
+ * job (the same materialization ext-admin-02's read model resolves per install);
+ * until an install is materialized the controller answers a 409, never a
+ * fabricated success.
+ */
+import type { APIContext } from "astro";
+import { resolveOperatorSession } from "@/lib/apps/adminSession.js";
+import {
+  getRegistryService,
+  requireOwnedInstall,
+  requireManageRole,
+  parseInstallId,
+  json,
+} from "@/lib/apps/adminService.js";
+import {
+  handleLifecycleRequest,
+  type LifecycleDeps,
+  type LifecycleWriteAction,
+} from "@/lib/apps/integrationLifecycleController.js";
+import { parseEnvironment, type IntegrationEnvironment } from "@tot/public-runtime";
+import { loadTenantLocalLifecycleState } from "@/lib/apps/tenantIntegrationMaterialization.js";
+import { resolveAdminTenant } from "@/config/adminTenantLookup";
+
+export const prerender = false;
+
+const WRITE_ACTIONS: ReadonlySet<string> = new Set(["preview", "publish", "rollback"]);
+
+/**
+ * Build the control-plane materialization seam for one tenant's installs. A tenant's
+ * OWN (tenant-local) declaration is materialized through the interim bridge (ext-kernel-09):
+ * `load` returns its REAL live-by-config lifecycle state instead of the former blanket
+ * `null`, so a declared install is no longer reported `not_materialized`. It carries no
+ * separate candidate/promotion gate — an on-by-default declaration is already effective —
+ * so `resolveCandidateEvidence`/`resolveGate` stay null and a `preview`/`publish` refuses
+ * fail-closed (no candidate) rather than fabricating one. A managed-app install with a
+ * persisted candidate lifecycle remains the control plane's separate concern.
+ */
+function integrationLifecycleDeps(_context: APIContext, tenantId: string, stage: IntegrationEnvironment): LifecycleDeps {
+  return {
+    load: async (installId) => {
+      // Best-effort: a resolver hiccup answers "unmaterialized" (fail-closed 409),
+      // never a 500 — an install with no materialized declaration is null either way.
+      try {
+        const tenant = await resolveAdminTenant(tenantId);
+        if (!tenant || tenant.tenant_id !== tenantId) return null;
+        return loadTenantLocalLifecycleState(tenant, installId, stage);
+      } catch (err) {
+        console.error(`[integration-lifecycle] materialization skipped for ${tenantId}: ${String(err)}`);
+        return null;
+      }
+    },
+    save: async () => {},
+    resolveCandidateEvidence: async () => null,
+    resolveGate: async () => null,
+  };
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const requestUrl = new URL(context.request.url);
+  const requestedTenant = requestUrl.searchParams.get("tenant");
+  const auth = await resolveOperatorSession(context, requestedTenant);
+  if (!auth.ok) return json({ error: auth.message }, auth.status);
+  const manageDenied = requireManageRole(auth);
+  if (manageDenied) return manageDenied;
+
+  let body: unknown;
+  try {
+    body = await context.request.json();
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+
+  const action = (body as { action?: unknown }).action;
+  if (typeof action !== "string" || !WRITE_ACTIONS.has(action)) {
+    return json({ error: "action must be one of: preview, publish, rollback" }, 400);
+  }
+  const installId = parseInstallId(body);
+  if (!installId) return json({ error: "installId is required" }, 400);
+
+  const registry = await getRegistryService();
+  if (registry instanceof Response) return registry;
+
+  const owned = await requireOwnedInstall(registry, installId, auth.tenantId);
+  if (owned instanceof Response) return owned;
+
+  const { expectedLiveRevision, targetRevision } = body as {
+    expectedLiveRevision?: string | null;
+    targetRevision?: string;
+  };
+
+  const stage: IntegrationEnvironment = parseEnvironment(requestUrl.searchParams.get("stage")) ?? "live";
+  const deps = integrationLifecycleDeps(context, auth.tenantId, stage);
+  const result = await handleLifecycleRequest(deps, {
+    action: action as LifecycleWriteAction,
+    installId,
+    actor: auth.actor,
+    ...(expectedLiveRevision !== undefined ? { expectedLiveRevision } : {}),
+    ...(typeof targetRevision === "string" ? { targetRevision } : {}),
+  });
+  return json(result.body, result.status);
+}

package/apps/storefront/src/pages/api/apps/admin/integrations.ts

@@ -0,0 +1,89 @@
+/**
+ * GET /api/apps/admin/integrations — the effective integration admin read model
+ * (ext-admin-02): the tenant-scoped data behind ext-admin-01's `/admin#integrations`
+ * IA. Combines each install's desired config, resolved effective plan, compiled CSP,
+ * consent, assurance, candidate, and rollback availability into ONE safe view.
+ *
+ * Auth mirrors `list.ts` exactly: the `?tenant=` query param is only ever a CANDIDATE
+ * into `resolveOperatorSession` — the tenant actually used is `auth.tenantId` from the
+ * resolved session, never the raw param — so another tenant, or a vendor with no
+ * membership, is denied (401/403) before any read model is assembled. Read-only: any
+ * membership role admits. The pure {@link assembleIntegrationReadModel} is the second,
+ * defense-in-depth gate: it re-asserts every materialized input belongs to
+ * `auth.tenantId` and redacts secrets, so a mis-plumbed control plane cannot leak.
+ *
+ * The control-plane materialization of effective plans, candidate evidence, and
+ * assurance records is resolved per install where present; an install with none yet
+ * surfaces honestly as `configuring` (no effective authority, no rollback), never a
+ * fabricated live state.
+ */
+import type { APIContext } from "astro";
+import { resolveOperatorSession } from "@/lib/apps/adminSession.js";
+import { getRegistryService, json } from "@/lib/apps/adminService.js";
+import { parseEnvironment, type IntegrationEnvironment } from "@tot/public-runtime";
+import {
+  assembleIntegrationReadModel,
+  type IntegrationReadModelInputItem,
+} from "@/lib/apps/integrationReadModel.js";
+import { tenantLocalReadModelItems } from "@/lib/apps/tenantIntegrationMaterialization.js";
+import { resolveAdminTenant } from "@/config/adminTenantLookup";
+
+export const prerender = false;
+
+/** A merchant-legible purpose line for an install, never an internal adapter name. */
+function purposeFor(appId: string): string {
+  return `Integration: ${appId}`;
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const url = new URL(context.request.url);
+  const requestedTenant = url.searchParams.get("tenant");
+  const auth = await resolveOperatorSession(context, requestedTenant);
+  if (!auth.ok) return json({ error: auth.message }, auth.status);
+
+  const registry = await getRegistryService();
+  if (registry instanceof Response) return registry;
+
+  const stage: IntegrationEnvironment = parseEnvironment(url.searchParams.get("stage")) ?? "staged";
+
+  const installs = await registry.listByTenant(auth.tenantId);
+  const items: IntegrationReadModelInputItem[] = installs
+    .filter((install) => install.status !== "uninstalled")
+    .map((install) => ({
+      install: {
+        installId: install.installId,
+        appId: install.appId,
+        appVersion: install.appVersion,
+        tenantId: install.tenantId,
+        status: install.status,
+      },
+      purpose: purposeFor(install.appId),
+      // The desired config is the tenant's own input; when the manifest snapshot is not
+      // a structured object it contributes nothing — never a fabricated value.
+      desiredConfig: {},
+    }));
+
+  // ext-kernel-09: a tenant's OWN (tenant-local) declarations are materialized through
+  // the interim bridge and appended with their REAL effective plan + compiled CSP, so a
+  // declared integration surfaces effective state — not `configuring`. Resolved off the
+  // auth-bound tenant config only (the tenant id is `auth.tenantId`, never the param).
+  // Best-effort + additive: a resolver hiccup degrades to the managed-app view rather
+  // than failing the whole read model closed.
+  try {
+    const tenantConfig = await resolveAdminTenant(auth.tenantId);
+    if (tenantConfig && tenantConfig.tenant_id === auth.tenantId) {
+      items.push(...tenantLocalReadModelItems(tenantConfig, stage));
+    }
+  } catch (err) {
+    console.error(`[admin-integrations] tenant-local materialization skipped for ${auth.tenantId}: ${String(err)}`);
+  }
+
+  const result = assembleIntegrationReadModel({ tenantPublicId: auth.tenantId, stage, items });
+  if (!result.ok) {
+    // A cross-tenant input or surviving secret is a server-side integrity failure, not
+    // something to echo back field-by-field.
+    return json({ error: "integration read model failed integrity checks" }, 500);
+  }
+
+  return json({ readModel: result.value });
+}