@tokenoftrust/storefront-runner 2.0.17 → 2.0.18

package/apps/storefront/src/middleware/controlPlane.ts

@@ -0,0 +1,270 @@
+/**
+ * The control-plane branch: everything a route reaches only with authorization,
+ * plus every route on a login-gated host.
+ *
+ * It owns the three request-time D1 reads (managed installs, consent, the catalog
+ * edge replica), the sign-in gate and its admin landing, and the `/dev` alias —
+ * then delegates to the shared render chain with those values supplied.
+ */
+import type { APIContext, MiddlewareNext } from "astro";
+import { readEnv, readD1, readKv } from "@/lib/env";
+import { fromD1, type D1Like } from "@/lib/d1/catalog";
+import { readCurrentTenantConsentConfig } from "@/lib/apps/consentConfigRead";
+import { loadActiveManagedInstallDeclarations } from "@/lib/integration/managedInstallDeclarations";
+import { buildTenantConsentBroker, verifyPreviewToken } from "@tot/public-runtime";
+import type { ConsentSnapshot, IntegrationDeclarationInput, TenantConfig } from "@tot/public-runtime";
+import {
+  evaluateLoginGate,
+  isAuthPath,
+  isAdminPath,
+  sessionAdmitsHost,
+  sessionHostCapability,
+  PUBLIC_HOME_TENANT_ID,
+  type GateMode,
+} from "@/lib/auth/loginGate";
+import { resolveAdminLanding, isAdminSelectPath } from "@/lib/auth/adminLanding";
+import { resolveAdminTenantMode } from "@/lib/adminTenantEnvelope";
+import { gatedHoldingResponse } from "@/lib/auth/gatePage";
+import { readSession, KvSessionStore, SESSION_COOKIE } from "@/lib/auth/session";
+import { runRenderChain } from "./renderChain.js";
+
+export interface ControlPlaneInput {
+  context: APIContext;
+  next: MiddlewareNext;
+  host: string;
+  url: URL;
+  tenant: TenantConfig;
+  basePath: string;
+  renderPath: string;
+  cache: Cache | undefined;
+  kv: KVNamespace | undefined;
+  gateMode: GateMode;
+  /** `DEMO_GATE_HOSTS`, raw. */
+  demoGateHosts: string | null | undefined;
+  /** True when this host is withheld behind sign-in — see `resolveMiddlewareBranchV1`. */
+  hostLoginGated: boolean;
+}
+
+export async function serveControlPlane(input: ControlPlaneInput): Promise<Response> {
+  const { context, next, host, url, tenant, basePath, renderPath, cache, kv } = input;
+  const { request, locals } = context;
+
+  // Login-gate enforcement (DEMO_GATE_MODE="login"): runs before the render so a
+  // gated page is never served to an unauthenticated viewer. The platform's own
+  // "self" home tenant is EXEMPT — it renders publicly (browse + sign up); every
+  // other tenant on a gated host is withheld behind sign-in. A valid,
+  // resource-bound tot_session sets locals.viewer (email + roles) for chrome;
+  // otherwise an unauthenticated visitor gets a "Coming soon" holding page with
+  // a Sign-in button (auth paths are exempt so sign-in itself is reachable). The
+  // grant `resource` is the tenant's appDomain — never input.
+  if (input.hostLoginGated) {
+    const tenantExempt = tenant.tenant_id === PUBLIC_HOME_TENANT_ID;
+    // UNIFIED on the federated session: read the FULL session (no resource filter —
+    // federated sign-in's aud is the storefront app, not this tenant) and admit the
+    // viewer iff they hold a MEMBERSHIP for the host's tenant. One session model for
+    // the console + the preview gate. Deny-closed: no session / no membership → gate.
+    let viewerRecord = null;
+    if (!isAuthPath(url.pathname)) {
+      const sessionKv = await readKv("SESSION");
+      if (sessionKv) {
+        const sid = context.cookies.get(SESSION_COOKIE)?.value ?? null;
+        viewerRecord = await readSession(
+          new KvSessionStore(sessionKv),
+          sid,
+          Math.floor(Date.now() / 1000),
+        );
+      }
+    }
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const admitted = sessionAdmitsHost(viewerRecord, tenant.appDomain, nowSeconds);
+    // QA content-bypass: only when the server has configured DEMO_GATE_BYPASS_TOKEN
+    // (never in a prod slot) AND the request presents a matching X-Demo-Gate-Bypass
+    // header. Unset token ⇒ false ⇒ fully inert; a client cannot self-grant. The
+    // public-content-only restriction (admin/cockpit/api excluded) is enforced
+    // inside evaluateLoginGate via isBypassPrivilegedPath.
+    const bypassToken = await readEnv("DEMO_GATE_BYPASS_TOKEN");
+    const qaBypass =
+      !!bypassToken && request.headers.get("x-demo-gate-bypass") === bypassToken;
+
+    // Customization-preview admission, available to EVERY tenant: a signed,
+    // unexpired `?__preview=` token (or the `tot_preview` cookie it persists as)
+    // whose `tenantId` claim matches THIS tenant admits the viewer to that
+    // tenant's public content. Verified here — before the gate decides — because
+    // previewing an unpublished storefront is the token's whole purpose, and a
+    // viewer holding one must not be handed the "Coming soon" holding page.
+    // Tenant-bound and HMAC-signed, so one tenant's token never opens another's,
+    // and an absent CUSTOMIZATION_PREVIEW_SECRET leaves it false (fail-closed).
+    // The admin/cockpit/api exclusion is enforced in evaluateLoginGate.
+    const gatePreviewSecret = await readEnv("CUSTOMIZATION_PREVIEW_SECRET");
+    const gatePreviewToken =
+      url.searchParams.get("__preview") ??
+      context.cookies.get("tot_preview")?.value ??
+      null;
+    let previewTokenValid = false;
+    if (gatePreviewSecret && gatePreviewToken) {
+      const verifiedPreview = await verifyPreviewToken(
+        gatePreviewSecret,
+        gatePreviewToken,
+        nowSeconds,
+      );
+      previewTokenValid =
+        verifiedPreview.ok && verifiedPreview.claims.tenantId === tenant.tenant_id;
+    }
+
+    // Canonical admin tenant landing: an AUTHENTICATED viewer who is not a
+    // member/staff of THIS host's tenant must be routed to their OWN tenant
+    // (auto when sole) or the tenant picker (when several / none) — never bounced
+    // into a sign-in loop and never silently shown the wrong tenant. Only for
+    // admin paths, only for an authed non-member, and never on the /admin/select
+    // picker itself (whose whole purpose is to be reachable by such a viewer).
+    if (
+      isAdminPath(url.pathname) &&
+      !isAdminSelectPath(url.pathname) &&
+      !admitted &&
+      viewerRecord &&
+      !qaBypass
+    ) {
+      const landing = resolveAdminLanding({
+        record: viewerRecord,
+        routedTenant: tenant.appDomain,
+        basePath,
+        intended: url.pathname + url.search,
+        nowSeconds,
+      });
+      if (landing.action === "auto" || landing.action === "select") {
+        return context.redirect(landing.location, 303);
+      }
+    }
+
+    // The /admin/select picker requires only a VALID SESSION (any authed viewer),
+    // not membership of the routed tenant — it lists the viewer's OWN tenants. So
+    // it passes the gate on the strength of the session alone.
+    const hasValidSession =
+      admitted || (isAdminSelectPath(url.pathname) && !!viewerRecord);
+    const decision = evaluateLoginGate({
+      host,
+      pathname: url.pathname,
+      search: url.search,
+      mode: input.gateMode,
+      gatedHosts: input.demoGateHosts,
+      hasValidSession,
+      tenantExempt,
+      qaBypass,
+      previewTokenValid,
+    });
+    if (decision.action === "redirect") {
+      // ADMIN (and any privileged surface) hard-redirects to sign-in rather than
+      // rendering the merchant-facing "Coming soon" holding page: an unauthenticated
+      // admin visitor must land on the sign-in prompt, never an ambiguous 200 that
+      // reads as "this store isn't ready." The holding page's whole audience is a
+      // public browser of a gated STOREFRONT; it is the wrong signal for /admin. The
+      // gate already decided to withhold — this only changes HOW (303 vs holding
+      // page); it never weakens the gate. `decision.location` already carries
+      // `?next=` so the admin returns to exactly where they were headed.
+      if (isAdminPath(url.pathname)) {
+        return context.redirect(decision.location, 303);
+      }
+      // Withhold content but offer sign-in (carrying the intended destination).
+      return gatedHoldingResponse(decision.location);
+    }
+    if (admitted && viewerRecord) {
+      // Surface the viewer's standing FOR THIS host's tenant as chrome, BOUND to
+      // the host so a capability the session holds for another tenant never leaks
+      // in: a member sees their tenants[] role; the owner of their own tenant sees
+      // the resource-scoped session's capability; a ToT-staff viewer admitted via
+      // an explicit vendor selection sees the staffRoles-scoped capability. The
+      // ship gates (decideIsOwner/resolveShipPrincipal) read this capability,
+      // so binding it here keeps owner-resolution server-side + tenant-correct.
+      //
+      // On an admin path, "the host" a staff viewer is really acting on is the
+      // ?asTenant= impersonation target (mirrors admin.astro/AdminPublishTab.astro's
+      // own resolveAdminTenantMode call) — resolving capability against the routed
+      // host instead left a staff viewer who selected another tenant reading as
+      // "not an owner" of it even while holding a real grant, because their
+      // staffSelection is bound to the SELECTED tenant, never the host app.
+      const capabilityHost = isAdminPath(url.pathname)
+        ? resolveAdminTenantMode({
+            session: viewerRecord,
+            adminAppTenant: tenant.appDomain,
+            requestedTarget: url.searchParams.get("asTenant"),
+            nowSeconds,
+          }).envelope.targetTenant
+        : tenant.appDomain;
+      const hostCapability = sessionHostCapability(viewerRecord, capabilityHost, nowSeconds);
+      locals.viewer = {
+        email: viewerRecord.email,
+        roles: hostCapability ? [hostCapability] : viewerRecord.roles,
+        capability: hostCapability ?? viewerRecord.capability,
+      };
+    }
+  }
+
+  // /dev was renamed to /cockpit (2026-07-20). 302-redirect any old /dev link —
+  // host-routed (/dev) or path-routed (/<vendor>/dev) — to the new path, preserving
+  // the tenant prefix + query. Temporary (302) while the cockpit UX is still evolving.
+  if (renderPath === "/dev" || renderPath.startsWith("/dev/")) {
+    const rest = renderPath.slice("/dev".length); // "" or "/sub…"
+    return Response.redirect(`${url.origin}${basePath}/cockpit${rest}${url.search}`, 302);
+  }
+
+  // Active managed installs share the same declaration/resolver/CSP/broker/cache
+  // plane as tenant-config integrations. Read only canonical active rows and their
+  // current immutable snapshot; candidates, suspended rows, and drafts produce no
+  // declaration. A missing/unmigrated binding fails closed to no managed effects.
+  const appsD1 = await readD1("STOREFRONT_APPS_DB");
+  let managedIntegrationDeclarations: IntegrationDeclarationInput[] = [];
+  if (appsD1) {
+    try {
+      managedIntegrationDeclarations = await loadActiveManagedInstallDeclarations(
+        fromD1(appsD1),
+        tenant.tenant_id,
+      );
+    } catch {
+      managedIntegrationDeclarations = [];
+    }
+  }
+
+  return runRenderChain({
+    context,
+    next,
+    host,
+    url,
+    tenant,
+    basePath,
+    renderPath,
+    cache,
+    kv,
+    managedIntegrationDeclarations,
+    readTenantConsentSnapshot: () => readSavedConsentSnapshot(tenant.tenant_id),
+    // The D1 catalog edge read replica, when this deploy opts into it. Deferred to
+    // the chain's own catalog build so a request the static bundle or the edge
+    // cache answers never pays for it. The public branch never resolves it at all
+    // — see `publicRender`.
+    readCatalogD1: async (): Promise<D1Like | undefined> =>
+      (await readEnv("USE_D1_CATALOG")) === "1" ? await readD1("CATALOG_DB") : undefined,
+  });
+}
+
+/**
+ * The live Worker serving preview/admin/gated areas (NOT the public path per ADR
+ * 0013) reads the current consent from D1. Kept FAIL-SOFT: a bound D1 whose schema
+ * is absent (a schemaless ephemeral preview D1) must never 500 the render — it
+ * returns null and the caller keeps the essential-only default. Fail-soft, NOT
+ * fail-quiet: consent silently downgrading on a regulated storefront is its own
+ * incident class, so log loudly. Expected only against an ephemeral preview D1;
+ * against a production D1 it is a real signal to investigate.
+ */
+async function readSavedConsentSnapshot(tenantId: string): Promise<ConsentSnapshot | null> {
+  const consentD1 = await readD1("STOREFRONT_APPS_DB");
+  if (!consentD1) return null;
+  try {
+    const config = await readCurrentTenantConsentConfig(fromD1(consentD1), tenantId);
+    return config ? buildTenantConsentBroker(config).getSnapshot() : null;
+  } catch (err) {
+    console.error(
+      `consent snapshot read failed for tenant ${tenantId}; serving the ` +
+        `fail-closed essential-only default: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return null;
+  }
+}