@tokenoftrust/storefront-runner 1.3.4-rc.4 → 1.4.0

package/apps/storefront/src/pages/api/compliance/preflight.ts

@@ -0,0 +1,206 @@
+/**
+ * POST /api/compliance/preflight — the checkout ENFORCEMENT gate.
+ *
+ * Checkout completion + order creation happen in the EXTERNAL managed cart, so
+ * this route is the storefront's authoritative "may this cart proceed?" decision,
+ * evaluated SERVER-SIDE against the tenant's data-driven ruleset. The client posts
+ * the cart handles + a ship-to state + the verification state; the server resolves
+ * each product's compliance profile from the catalog (never trusting client-
+ * supplied attributes), evaluates, and returns a structured decision.
+ *
+ * Fail-closed by construction: a regulated tenant with no resolvable ruleset, an
+ * unconfigured verification provider, or an unsatisfied excise obligation returns
+ * `status: "blocked"`. A malformed body on a regulated tenant blocks too — it
+ * never falls through to "clear".
+ */
+import type { APIContext } from "astro";
+import {
+  deriveProductProfile,
+  evaluateCartCompliance,
+  type CartComplianceLine,
+  type ShipDestination,
+  type VerificationState,
+  type CartComplianceDecision,
+} from "@tot/public-runtime";
+import {
+  isRegulatedTenant,
+  isSandboxVerificationProvider,
+  resolveTenantRuleset,
+} from "@/lib/compliance/enforcement";
+
+export const prerender = false;
+
+interface PreflightLineInput {
+  handle: string;
+  sku?: string;
+  variantId?: string;
+  quantity?: number;
+}
+
+interface PreflightBody {
+  lines?: PreflightLineInput[];
+  destination?: { region?: string; country?: string; postalCode?: string } | null;
+  verification?: {
+    outcome?: string;
+    verifiedAge?: number;
+    evidenceRef?: string;
+  } | null;
+  ageAffirmed?: boolean;
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    },
+  });
+}
+
+/** A fail-closed BLOCK decision for regulated tenants when the request is unusable. */
+function blockedDecision(message: string): CartComplianceDecision {
+  return {
+    status: "blocked",
+    blocks: [{ code: "ruleset_unavailable", failedClosed: true, message }],
+    requirements: {
+      ageVerification: "blocked",
+      adultSignature: false,
+      exciseHandling: "not_required",
+      destination: "not_required",
+    },
+    purchaseLimit: null,
+    failedClosed: true,
+  };
+}
+
+const VALID_OUTCOMES = new Set(["verified", "failed", "pending", "unknown"]);
+
+function normalizeVerification(
+  v: PreflightBody["verification"],
+): VerificationState | null {
+  if (!v || typeof v !== "object") return null;
+  const outcome = VALID_OUTCOMES.has(String(v.outcome))
+    ? (v.outcome as VerificationState["outcome"])
+    : "unknown";
+  return {
+    outcome,
+    verifiedAge:
+      typeof v.verifiedAge === "number" ? v.verifiedAge : undefined,
+    evidenceRef:
+      typeof v.evidenceRef === "string" ? v.evidenceRef : undefined,
+  };
+}
+
+function normalizeDestination(
+  d: PreflightBody["destination"],
+): ShipDestination | null {
+  if (!d || typeof d !== "object") return null;
+  const region = String(d.region ?? "").trim();
+  const country = String(d.country ?? "US").trim() || "US";
+  if (!region) return null;
+  return {
+    region,
+    country,
+    postalCode:
+      typeof d.postalCode === "string" ? d.postalCode.trim() : undefined,
+  };
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const { tenant, tot } = context.locals;
+  const regulated = isRegulatedTenant(tenant);
+
+  let body: PreflightBody;
+  try {
+    body = (await context.request.json()) as PreflightBody;
+  } catch {
+    // A regulated tenant must never proceed on an unreadable request.
+    return regulated
+      ? json({ decision: blockedDecision("Malformed preflight request.") }, 400)
+      : json({ decision: evaluateEmpty() });
+  }
+
+  const ruleset = await resolveTenantRuleset(tenant);
+  let verification = normalizeVerification(body.verification);
+  const destination = normalizeDestination(body.destination);
+
+  // Test/sandbox verification profile (the mode the 8501 demo/preview runs in):
+  // when the resolved provider is an explicit sandbox value and no live provider
+  // outcome was supplied, the front-door 21+ affirmation SIMULATES a passed
+  // verification so the regulated checkout is exercisable end-to-end without a
+  // real provider. Gated on the sandbox provider (test-tier only) — production
+  // never reaches here (unset provider → fail-closed; live provider → real
+  // outcome required). See enforcement.ts for the invariant.
+  if (
+    ruleset &&
+    isSandboxVerificationProvider(ruleset.verification.provider) &&
+    body.ageAffirmed === true &&
+    (!verification || verification.outcome === "unknown")
+  ) {
+    verification = { outcome: "verified", verifiedAge: ruleset.verification.minAge };
+  }
+
+  // Resolve each line's compliance profile SERVER-SIDE from the catalog.
+  const lines: CartComplianceLine[] = [];
+  for (const raw of body.lines ?? []) {
+    if (!raw || typeof raw.handle !== "string" || !raw.handle) continue;
+    const quantity =
+      typeof raw.quantity === "number" && raw.quantity > 0
+        ? Math.floor(raw.quantity)
+        : 1;
+    const product = await tot.getProductByHandle(raw.handle);
+    if (!product) {
+      // A line we can't resolve on a regulated tenant is a fail-closed block:
+      // we can't prove it's shippable, so we don't let it through.
+      if (regulated) {
+        return json(
+          {
+            decision: blockedDecision(
+              `Product "${raw.handle}" could not be resolved for compliance evaluation.`,
+            ),
+          },
+          200,
+        );
+      }
+      continue;
+    }
+    const variant =
+      product.variants.find(
+        (v) => v.id === raw.variantId || (raw.sku && v.sku === raw.sku),
+      ) ?? null;
+    const profile = deriveProductProfile(product, variant);
+    lines.push({
+      sku: variant?.sku ?? raw.sku ?? product.handle,
+      quantity,
+      profile,
+      title: product.title,
+    });
+  }
+
+  const decision = evaluateCartCompliance({
+    ruleset,
+    regulated,
+    lines,
+    destination,
+    verification,
+    ageAffirmed: body.ageAffirmed === true,
+  });
+
+  return json({ decision });
+}
+
+/** The trivial "nothing to enforce" decision for an unregulated empty request. */
+function evaluateEmpty(): CartComplianceDecision {
+  return evaluateCartCompliance({
+    ruleset: null,
+    regulated: false,
+    lines: [],
+    destination: null,
+    verification: null,
+  });
+}
+
+export async function GET(): Promise<Response> {
+  return json({ error: "method_not_allowed" }, 405);
+}

package/apps/storefront/src/pages/api/rum/vitals.ts

@@ -0,0 +1,54 @@
+/**
+ * Field Web Vitals (F14 RUM) ingest — the sink the browser beacon POSTs to.
+ *
+ * `webVitals.ts#startWebVitals` sends one JSON `WebVitalsSample` here (via
+ * `navigator.sendBeacon`) as each Core Web Vital finalizes. This endpoint is the
+ * server side of that contract: validate the sample, record it, return 204.
+ *
+ * Phase 1 records to the worker log (like `csp-report.ts`). The regression alert
+ * (`rumAlert.detectRegressions`) runs over a WINDOW of samples, not one — so the
+ * durable step is to forward each sample to a queryable store (Workers Analytics
+ * Engine / a KV rollup), then run `detectRegressions` on the per-route/hour p75
+ * and dispatch any `RegressionAlert` to F16's `core-web-vitals` monitor. That
+ * store/forward is the documented follow-up; the SHAPE it stores is fixed here.
+ */
+import type { APIRoute } from "astro";
+import { rateMetric, type WebVitalName, type WebVitalsSample } from "@/lib/analytics/webVitals";
+
+export const prerender = false;
+
+const METRICS: readonly WebVitalName[] = ["lcp", "inp", "cls"];
+
+/** Narrow an untrusted beacon body to a WebVitalsSample, or null if malformed. */
+function parseSample(raw: unknown): WebVitalsSample | null {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw as Record<string, unknown>;
+  if (typeof o.metric !== "string" || !METRICS.includes(o.metric as WebVitalName)) return null;
+  if (typeof o.value !== "number" || !Number.isFinite(o.value) || o.value < 0) return null;
+  if (typeof o.route !== "string" || typeof o.path !== "string") return null;
+  const metric = o.metric as WebVitalName;
+  return {
+    metric,
+    value: o.value,
+    // Re-derive rating server-side — never trust the client's label.
+    rating: rateMetric(metric, o.value),
+    route: o.route as WebVitalsSample["route"],
+    path: o.path,
+    ...(typeof o.navigationType === "string" ? { navigationType: o.navigationType } : {}),
+  };
+}
+
+export const POST: APIRoute = async ({ request }) => {
+  try {
+    const sample = parseSample(await request.json());
+    if (sample) {
+      // eslint-disable-next-line no-console
+      console.info("[rum:web-vitals]", JSON.stringify(sample));
+      // TODO(F14 follow-up): forward to Analytics Engine and run
+      // rumAlert.detectRegressions on the per-route/hour rollup.
+    }
+  } catch {
+    /* never fail a telemetry beacon */
+  }
+  return new Response(null, { status: 204 });
+};

package/apps/storefront/src/pages/api/test/dev-session.ts

@@ -0,0 +1,133 @@
+/**
+ * POST /api/test/dev-session — E2E-ONLY hands-off sign-in for automated tests.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The hosted /cockpit `hostedActivity` flow can only be driven by a signed-in,
+ * store-LINKED developer session, and the real sign-in paths (`/api/auth/verify`
+ * OTP code, `/auth/magic` token) deliver their secret ONLY by email — so an
+ * automated regression test can never bootstrap itself without a human relaying a
+ * code/link out of an inbox. This endpoint mints that session directly for a test
+ * developer + tenant so `e2e/cockpit-signal-rail.spec.ts` can run unattended.
+ *
+ * IT DOES NOT WEAKEN THE REAL AUTH FLOW. It is a SEPARATE, secret-gated door used
+ * only as a test PRECONDITION — auth-flow fidelity (does invite→email→magic→session
+ * actually work?) is a different concern and must still be tested against the real
+ * path with a real/test inbox. See e2e/README.md §"Why a mint endpoint, not a flag".
+ *
+ * SAFETY — fail CLOSED, three independent gates (a env-detection bug alone can't open it):
+ *   1. `E2E_TEST_SECRET` must be provisioned. Unset → 404 (route behaves as if it
+ *      does not exist). PROVISION IT ONLY IN THE TEST/PREVIEW TIER, NEVER PROD.
+ *   2. `NODE_ENV === "production"` → 404 regardless of anything else (defense in depth;
+ *      preview/qa run NODE_ENV=test, so this permits them and blocks prod).
+ *   3. The `x-e2e-secret` header must match `E2E_TEST_SECRET` (constant-time compare).
+ * Blast radius is further bounded: the tenant must resolve via resolvePreviewTenant
+ * (a known store), and the minted session/token are the ordinary revocable KV
+ * artifacts (deleting the KV entry revokes them) — nothing new or long-lived.
+ *
+ * This mirrors the existing shared-secret seam the storefront already uses for
+ * cli-signin-code (lib/dev/cliSignInCode.ts → MCP `MCP_SERVICE_SHARED_SECRET`): a
+ * capability-gated internal door, not an ambient env-mode branch.
+ */
+import type { APIContext } from "astro";
+import { getSessionStore, setSessionCookie } from "@/lib/auth/route";
+import { createSession, DEFAULT_SESSION_TTL_SECONDS } from "@/lib/auth/session";
+import { readEnv, readKv } from "@/lib/env";
+import { mintActivityIngestToken } from "@/lib/dev/activityIngestToken";
+import { resolvePreviewTenant } from "@/config/previewTenantLookup";
+
+export const prerender = false;
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+/** Length-independent constant-time string compare (avoids leaking the secret by timing). */
+function timingSafeEqual(a: string, b: string): boolean {
+  // XOR the SHA-equalised inputs isn't necessary here; compare fixed-work over the
+  // longer length so mismatched lengths still take constant time relative to input.
+  const len = Math.max(a.length, b.length);
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < len; i++) {
+    diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  }
+  return diff === 0;
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  // GATE 1 — secret must be provisioned; absent ⇒ pretend the route doesn't exist.
+  const secret = await readEnv("E2E_TEST_SECRET");
+  if (!secret) return json({ error: "not found" }, 404);
+
+  // GATE 2 — never in the production tier, even if a secret leaked into it.
+  const nodeEnv = ((await readEnv("NODE_ENV")) ?? "").toLowerCase();
+  if (nodeEnv === "production") return json({ error: "not found" }, 404);
+
+  // GATE 3 — present the secret.
+  const presented = context.request.headers.get("x-e2e-secret") ?? "";
+  if (!timingSafeEqual(presented, secret)) return json({ error: "forbidden" }, 403);
+
+  let body: { email?: unknown; tenant?: unknown };
+  try {
+    body = (await context.request.json()) as typeof body;
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+  const email = typeof body.email === "string" ? body.email.trim().toLowerCase() : "";
+  const tenantId = typeof body.tenant === "string" ? body.tenant.trim().toLowerCase() : "";
+  if (!email || !tenantId) return json({ error: "email and tenant are required" }, 400);
+
+  // Bound to a KNOWN store — never mints against an arbitrary/unknown tenant.
+  const tenant = await resolvePreviewTenant(tenantId);
+  if (!tenant) return json({ error: "unknown tenant" }, 404);
+
+  const store = await getSessionStore();
+  if (!store) return json({ error: "session store unavailable" }, 503);
+
+  // Mint a store-LINKED developer session (tenants[0].resource is what the
+  // /api/dev/activity poll resolves — see api/dev/activity.ts GET).
+  const now = Math.floor(Date.now() / 1000);
+  const resource = tenant.appDomain;
+  const { id } = await createSession(
+    store,
+    {
+      email,
+      resource,
+      roles: ["developer"],
+      capability: "developer",
+      tenants: [{ resource, role: "developer" }],
+      staff: [],
+    },
+    DEFAULT_SESSION_TTL_SECONDS,
+    now,
+  );
+  setSessionCookie(context, id, DEFAULT_SESSION_TTL_SECONDS);
+
+  // Also hand back an activity-ingest token so the test can POST heartbeat / save /
+  // obstacle events the way the local `tot dev` loop would (bearer-authed, not cookie).
+  const kv = await readKv("SESSION");
+  let activityToken: string | null = null;
+  let activityExpiresAt: string | null = null;
+  if (kv) {
+    const minted = await mintActivityIngestToken(kv, {
+      email,
+      tenant: tenant.tenant_id,
+      capability: "developer",
+    });
+    activityToken = minted.token;
+    activityExpiresAt = minted.expiresAt;
+  }
+
+  return json({
+    ok: true,
+    email,
+    tenant: tenant.tenant_id,
+    resource,
+    activityToken,
+    activityExpiresAt,
+    activityUrl: new URL(context.request.url).origin,
+  });
+}