@tokenoftrust/storefront-runner 2.0.2 → 2.0.4

package/apps/storefront/src/pages/api/apps/admin/credentials/rotate.ts

@@ -1,86 +0,0 @@
-/**
- * POST /api/apps/admin/credentials/rotate — rotate an install's client
- * secret, keeping the same `client_id` (PrivateApps epic, D2 Chunk C; D8
- * console-session auth added). The new secret is returned ONCE here and never
- * again — the same one-time-secret guarantee `install()` gives (see
- * `registryService.ts`'s `InstallResult` doc).
- *
- * `registryService.rotateCredentials()` takes a bare `installId` with no
- * tenant check of its own (Chunk A assumption #1) — so this route resolves
- * the install via `requireOwnedInstall` BEFORE calling it, rejecting a
- * foreign-tenant `installId` with the SAME 404 a truly-missing one gets (no
- * cross-tenant existence oracle). Mutating: `requireManageRole` gates a
- * console `developer` role out — the host-bound/Bearer path is exempt (no
- * `role`).
- */
-import type { APIContext } from "astro";
-import { resolveOperatorSession } from "@/lib/apps/adminSession.js";
-import {
-  getRegistryService,
-  registryErrorResponse,
-  requireOwnedInstall,
-  requireManageRole,
-  parseInstallId,
-  json,
-} from "@/lib/apps/adminService.js";
-import { RegistryError } from "@/lib/apps/registryService.js";
-import { resolveUiActor } from "@/lib/activity/uiActor";
-import { recordActivity } from "@/lib/activity/recordActivity";
-
-export const prerender = false;
-
-export async function POST(context: APIContext): Promise<Response> {
-  const requestedTenant = new URL(context.request.url).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 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;
-
-  // D10: acting cohort (merchant/admin), emitted source "server". SECURITY: the
-  // rotated secret (`issued.secret`) is NEVER placed in the payload — the allowlist
-  // names only the non-sensitive app handle (appId/env, from the owned install) +
-  // rotation time.
-  const activityActor = await resolveUiActor(context, { owner: auth.tenantId });
-
-  try {
-    const issued = await registry.rotateCredentials(installId, auth.actor);
-    recordActivity({
-      action: "app.credential.rotated",
-      actor: activityActor,
-      source: "server",
-      outcome: { status: "succeeded" },
-      scope: { tenantId: auth.tenantId },
-      payload: { args: { appId: owned.appId, env: owned.env, rotatedAt: new Date().toISOString() } },
-    });
-    return json({ credential: { clientId: issued.clientId, secret: issued.secret } });
-  } catch (err) {
-    if (err instanceof RegistryError) {
-      recordActivity({
-        action: "app.credential.rotated",
-        actor: activityActor,
-        source: "server",
-        outcome: { status: "failed", errorClass: err.code },
-        scope: { tenantId: auth.tenantId },
-        payload: { args: { appId: owned.appId, env: owned.env } },
-      });
-      return registryErrorResponse(err);
-    }
-    throw err;
-  }
-}

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

@@ -1,174 +0,0 @@
-/**
- * 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

@@ -1,96 +0,0 @@
-/**
- * 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/health.ts

@@ -1,44 +0,0 @@
-/**
- * GET /api/apps/admin/health — the console's per-install health rollup for
- * the resolved operator tenant (PrivateApps epic, D8 Chunk C). Read-only:
- * any membership role admits (mirrors `list.ts`'s `?tenant=`-as-candidate
- * scoping — the tenant actually queried is always `auth.tenantId`, never the
- * raw param).
- *
- * Folds `registryService.listByTenant` with `deliveryStore.getInstallHealth`
- * per install through `healthAggregate.ts`'s `buildInstallHealthView` — that
- * view is what data-minimizes `webhookEndpoint` down to `hasWebhookEndpoint`,
- * so this route never even holds the raw endpoint value to leak.
- */
-import type { APIContext } from "astro";
-import { resolveOperatorSession } from "@/lib/apps/adminSession.js";
-import { getRegistryService, json } from "@/lib/apps/adminService.js";
-import { WebhookDeliveryStore } from "@/lib/webhooks/deliveryStore.js";
-import { buildInstallHealthView, type AppInstallHealthView } from "@/lib/apps/healthAggregate.js";
-import { fromD1 } from "@/lib/d1/catalog.js";
-import { readD1 } from "@/lib/env";
-
-export const prerender = false;
-
-export async function GET(context: APIContext): Promise<Response> {
-  const requestedTenant = new URL(context.request.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 d1 = await readD1("STOREFRONT_APPS_DB");
-  if (!d1) return json({ error: "webhook store not configured" }, 503);
-  const deliveryStore = new WebhookDeliveryStore(fromD1(d1));
-
-  const installs = await registry.listByTenant(auth.tenantId);
-  const apps: AppInstallHealthView[] = await Promise.all(
-    installs.map(async (install) => {
-      const health = await deliveryStore.getInstallHealth(install.installId);
-      return buildInstallHealthView(install, health);
-    }),
-  );
-
-  return json({ apps });
-}

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

@@ -1,125 +0,0 @@
-/**
- * POST /api/apps/admin/install — install a private app for the resolved
- * operator tenant + a caller-chosen env (PrivateApps epic, D2 Chunk C).
- * Session-authed (see `@/lib/apps/adminSession`) — NOT the app JWT (D3's data
- * surface). `tenantId` comes only from the resolved session, never the body.
- *
- * The response's `credential.secret` is the ONE time the plaintext client
- * secret is ever surfaced — never logged, never returned again (see
- * `registryService.ts`'s `InstallResult` doc).
- */
-import type { APIContext } from "astro";
-import { resolveAdminSession } from "@/lib/apps/adminSession.js";
-import { getRegistryService, registryErrorResponse, json } from "@/lib/apps/adminService.js";
-import { RegistryError, type InstallInput } from "@/lib/apps/registryService.js";
-import { emitWebhookEvent } from "@/lib/webhooks/emit.js";
-import { resolveUiActor } from "@/lib/activity/uiActor";
-import { recordActivity } from "@/lib/activity/recordActivity";
-
-export const prerender = false;
-
-interface InstallBody {
-  appId?: unknown;
-  appVersion?: unknown;
-  env?: unknown;
-  scopes?: unknown;
-  manifest?: unknown;
-  webhookEndpoint?: unknown;
-  widgetPlacements?: unknown;
-}
-
-/** Validate + narrow the request body into `InstallInput`, or a 400 message. */
-function parseInstallInput(body: InstallBody): InstallInput | string {
-  if (typeof body.appId !== "string" || !body.appId.trim()) return "appId is required";
-  if (typeof body.appVersion !== "string" || !body.appVersion.trim()) return "appVersion is required";
-  if (typeof body.env !== "string" || !body.env.trim()) return "env is required";
-  if (!Array.isArray(body.scopes) || body.scopes.some((s) => typeof s !== "string")) {
-    return "scopes must be a string[]";
-  }
-  if (body.manifest === null || typeof body.manifest !== "object" || Array.isArray(body.manifest)) {
-    return "manifest is required and must be an object";
-  }
-  if (
-    body.webhookEndpoint !== undefined &&
-    body.webhookEndpoint !== null &&
-    typeof body.webhookEndpoint !== "string"
-  ) {
-    return "webhookEndpoint, when given, must be a string or null";
-  }
-  if (body.widgetPlacements !== undefined && !Array.isArray(body.widgetPlacements)) {
-    return "widgetPlacements, when given, must be an array";
-  }
-  return {
-    appId: body.appId,
-    appVersion: body.appVersion,
-    env: body.env,
-    scopes: body.scopes as string[],
-    manifest: body.manifest,
-    webhookEndpoint: (body.webhookEndpoint as string | null | undefined) ?? undefined,
-    widgetPlacements: body.widgetPlacements as unknown[] | undefined,
-  };
-}
-
-export async function POST(context: APIContext): Promise<Response> {
-  const auth = await resolveAdminSession(context);
-  if (!auth.ok) return json({ error: auth.message }, auth.status);
-
-  let body: InstallBody;
-  try {
-    body = (await context.request.json()) as InstallBody;
-  } catch {
-    return json({ error: "invalid JSON body" }, 400);
-  }
-
-  const input = parseInstallInput(body);
-  if (typeof input === "string") return json({ error: input }, 400);
-
-  const registry = await getRegistryService();
-  if (registry instanceof Response) return registry;
-
-  // D10: resolve the acting cohort ONCE (merchant/admin — a store owner managing
-  // their own app, or ToT staff operating-as). Emitted as source "server" (the
-  // app.* catalog source), best-effort, never alters control flow.
-  const activityActor = await resolveUiActor(context, { owner: auth.tenantId });
-
-  try {
-    const result = await registry.install(input, { tenantId: auth.tenantId, actor: auth.actor });
-    try {
-      // Best-effort: a webhook-plumbing hiccup must never turn a successful
-      // install into a failed response — see emit.ts's header.
-      await emitWebhookEvent("app.installed", auth.tenantId, {}, { installId: result.install.installId });
-    } catch (cause) {
-      console.warn(
-        "[diag:webhooks:emit]",
-        JSON.stringify({
-          topic: "app.installed",
-          tenantId: auth.tenantId,
-          installId: result.install.installId,
-          error: cause instanceof Error ? cause.message : String(cause),
-        }),
-      );
-    }
-    recordActivity({
-      action: "app.install",
-      actor: activityActor,
-      source: "server",
-      outcome: { status: "succeeded" },
-      scope: { tenantId: auth.tenantId },
-      payload: { args: { appId: input.appId, appVersion: input.appVersion, env: input.env } },
-    });
-    return json(result, 201);
-  } catch (err) {
-    if (err instanceof RegistryError) {
-      recordActivity({
-        action: "app.install",
-        actor: activityActor,
-        source: "server",
-        outcome: { status: err.code === "scope_denied" ? "refused" : "failed", errorClass: err.code },
-        scope: { tenantId: auth.tenantId },
-        payload: { args: { appId: input.appId, appVersion: input.appVersion, env: input.env } },
-      });
-      return registryErrorResponse(err);
-    }
-    throw err;
-  }
-}

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

@@ -1,118 +0,0 @@
-/**
- * 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);
-}