@tokenoftrust/storefront-runner 1.3.2

package/apps/storefront/src/lib/admin/viewmodels/settings.ts

@@ -0,0 +1,64 @@
+/**
+ * Settings view model (baseline §Settings) — admin policy, AI guardrails,
+ * regulated storefront policy, and audited changes. `ApprovalMode` and
+ * `SettingsAuditEvent` reuse the canonical substrate types from
+ * `lib/admin/ai` (ai-evidence-substrate) now that both domains live in the
+ * same lib/admin/** area.
+ */
+
+import type { CheckoutStyle } from "@tot/public-runtime";
+import type { ApprovalMode } from "../ai/approvalMode";
+import type { AuditEvent } from "../ai/audit";
+
+export type { ApprovalMode };
+export type { CheckoutStyle };
+
+export type SettingsSectionKey =
+  | "store"
+  | "checkout"
+  | "cart_appearance"
+  | "payments"
+  | "shipping"
+  | "taxes"
+  | "products"
+  | "customers"
+  | "notifications"
+  | "users_access"
+  | "integrations"
+  | "compliance"
+  | "ai_admin_policy";
+
+export interface SettingsSection {
+  key: SettingsSectionKey;
+  label: string;
+  summary: string;
+  riskyChangeReview: boolean;
+}
+
+export interface ShippingRestriction {
+  region: string;
+  reason: string;
+}
+
+export interface SettingsAuditEvent extends AuditEvent {
+  /** Human-readable summary of what changed — `AuditEvent.action` is the machine-facing form. */
+  change: string;
+}
+
+export interface SettingsViewModel {
+  targetTenant: string;
+  sections: SettingsSection[];
+  shippingRestrictions: ShippingRestriction[];
+  aiPolicyMode: ApprovalMode;
+  internalTenantPickerEnabled: boolean;
+  auditTrail: SettingsAuditEvent[];
+  /**
+   * The target tenant's current checkout styling — the editable descriptor the
+   * "Checkout styling" section (U12) renders in its editor and saves back through
+   * the versioned publish spine (`POST /api/admin/checkout-style` →
+   * `publishToTest` on `tenants/<id>/checkout-style.json`). Always a complete
+   * `CheckoutStyle` (the resolved default merged with any published override), so
+   * the editor never has to reason about missing fields.
+   */
+  checkoutStyle: CheckoutStyle;
+}

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

@@ -0,0 +1,90 @@
+/**
+ * The admin console's tenant envelope — { adminAppTenant, targetTenant } —
+ * per docs/handoffs/admin-app-implementation-baseline.md §Admin App As Tenant.
+ *
+ * PURE (no I/O, no Astro) so the staff-only override + its authorization are
+ * unit-testable in isolation. Reuses the EXISTING staff/membership machinery
+ * from `@/lib/dashboard/tenantSelection` and `@/lib/dashboard/staffAdmission`
+ * rather than inventing a parallel access model:
+ *
+ *   - `adminAppTenant` is always the routed tenant (`Astro.locals.tenant`) —
+ *     whichever domain actually served the request.
+ *   - `targetTenant` defaults to `adminAppTenant`. Only a session carrying
+ *     real ToT-staff scope (`isStaffSession`) may override it, and only to a
+ *     tenant the viewer already has real access to — a `tenants[]` membership
+ *     or a LIVE `staffSelection` (the same distinct staff-admission path the
+ *     dashboard vendor picker uses). Deny-by-default: an unauthorized or
+ *     unrecognized override is REFUSED (`denied: true`), never silently
+ *     dropped-and-hidden — the caller renders that refusal, it doesn't just
+ *     fall back quietly.
+ *   - Non-staff viewers never see an override honored, regardless of what a
+ *     request asks for: the staff check gates evaluation of the request
+ *     entirely, not just the picker's visibility.
+ */
+import type { SessionRecord } from "@/lib/auth/session";
+import { isStaffSession } from "@/lib/dashboard/staffAdmission";
+import { membershipFor, normalizeMemberships, type TenantMembership } from "@/lib/dashboard/tenantSelection";
+
+export interface AdminTenantEnvelope {
+  /** The tenant that actually served this request. */
+  adminAppTenant: string;
+  /** The tenant this page's data/actions are scoped to. */
+  targetTenant: string;
+  /** The signed-in viewer's email, or null when anonymous. */
+  operator: string | null;
+}
+
+export interface AdminTenantModeResult {
+  envelope: AdminTenantEnvelope;
+  /** Whether the picker should render at all. */
+  isStaff: boolean;
+  /** Tenants the picker can offer — the viewer's real memberships, deduped. */
+  pickerTenants: TenantMembership[];
+  /** Set when a requested override was refused for lack of authorization. */
+  deniedTarget: string | null;
+}
+
+export function resolveAdminTenantMode(input: {
+  session: SessionRecord | null | undefined;
+  adminAppTenant: string;
+  requestedTarget: string | null | undefined;
+  nowSeconds: number;
+}): AdminTenantModeResult {
+  const { session, adminAppTenant, nowSeconds } = input;
+  const isStaff = isStaffSession(session);
+  const operator = session?.email ?? null;
+  const requestedTarget = (input.requestedTarget ?? "").trim() || null;
+
+  const staffAdmission = session?.staffSelection
+    ? { selection: session.staffSelection, nowSeconds }
+    : undefined;
+
+  const pickerTenants = normalizeMemberships(session?.tenants);
+
+  // Non-staff: the override is never evaluated, not merely hidden from the UI.
+  if (!isStaff || !requestedTarget || requestedTarget === adminAppTenant) {
+    return {
+      envelope: { adminAppTenant, targetTenant: adminAppTenant, operator },
+      isStaff,
+      pickerTenants,
+      deniedTarget: null,
+    };
+  }
+
+  const membership = membershipFor(session?.tenants, requestedTarget, staffAdmission);
+  if (!membership) {
+    return {
+      envelope: { adminAppTenant, targetTenant: adminAppTenant, operator },
+      isStaff,
+      pickerTenants,
+      deniedTarget: requestedTarget,
+    };
+  }
+
+  return {
+    envelope: { adminAppTenant, targetTenant: requestedTarget, operator },
+    isStaff,
+    pickerTenants,
+    deniedTarget: null,
+  };
+}

package/apps/storefront/src/lib/analytics/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Privacy-friendly analytics (brief §5 Analytics).
+ *
+ * Phase 1 ships TWO layers:
+ *  1. Pageviews — Cloudflare Web Analytics, a single beacon script injected in
+ *     Layout.astro when PUBLIC_CF_ANALYTICS_TOKEN is set (no cookies, no PII).
+ *  2. Commerce events — product impression/click/PDP-view instrumented NOW to a
+ *     NO-OP sink, so Phase 2 conversion work inherits the call sites for free.
+ *
+ * The event API is intentionally tiny and synchronous-looking; swap the sink
+ * (e.g. to a Workers Analytics Engine writer or a beacon) without touching call
+ * sites. See DECISIONS.md.
+ */
+
+export type CommerceEvent =
+  | { type: "product_impression"; handle: string; list?: string; position?: number }
+  | { type: "product_click"; handle: string; list?: string }
+  | { type: "pdp_view"; handle: string; variant_id?: string }
+  | { type: "search"; query: string; results: number }
+  | { type: "collection_view"; handle: string }
+  | { type: "newsletter_signup"; source: string };
+
+export interface AnalyticsSink {
+  track(event: CommerceEvent): void;
+}
+
+/** Default sink: discard. Visible in dev console when ?debugAnalytics is set. */
+export class NoOpSink implements AnalyticsSink {
+  constructor(private readonly debug = false) {}
+  track(event: CommerceEvent): void {
+    if (this.debug && typeof console !== "undefined") {
+      // eslint-disable-next-line no-console
+      console.debug("[analytics]", event);
+    }
+  }
+}
+
+let sink: AnalyticsSink = new NoOpSink();
+
+/** Phase 2: call setAnalyticsSink(new RealSink()) once at boot. */
+export function setAnalyticsSink(next: AnalyticsSink): void {
+  sink = next;
+}
+
+export function track(event: CommerceEvent): void {
+  sink.track(event);
+}

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

@@ -0,0 +1,136 @@
+/**
+ * Broker-assertion MINTER — the storefront half of the "staff proven by a signed
+ * assertion, not a plaintext field" contract (#8453, decision
+ * `staff-invite-proof-via-broker`).
+ *
+ * The earlier flow sent the signed-in staff email to tot20 as a PLAINTEXT
+ * `actorEmail`/`email` field and asked tot20 to trust it — a spoof: anything that
+ * can reach the operator endpoint could name any staff email. This module instead
+ * MINTS a short-lived, storefront-signed RS256 JWT (the "broker assertion") that
+ * PROVES the storefront asserts this staff actor. It is presented to tot20 in the
+ * `X-ToT-Broker-Assertion` header; tot20 verifies the signature (against the
+ * storefront's PUBLISHED public key) + replay (`jti`/`exp`) and derives the staff
+ * actor from the VERIFIED `sub` — never from an untrusted field.
+ *
+ * SERVER-SIDE ONLY. The RS256 PRIVATE key (`STOREFRONT_BROKER_PRIVATE_KEY_B64`)
+ * lives only in the Worker/server env and is used only here; it MUST NEVER reach
+ * the client bundle. Callers are the server-side API routes (they hold the
+ * verified `session.email`), which mint per call and hand the compact JWT to the
+ * tot20 client to attach as the header. The clients themselves never see the key.
+ *
+ * Mirrors the jose usage in `./identityToken.ts` (that module VERIFIES tot's
+ * ES256 assertion; this one SIGNS the storefront's RS256 assertion — the inverse
+ * direction of the same decoupled-authZ pattern).
+ */
+import { SignJWT, importPKCS8, type CryptoKey } from "jose";
+import { readEnv } from "@/lib/env";
+
+/** The audience tot20's broker verifier pins. */
+export const BROKER_AUDIENCE = "tot20-broker";
+
+/** The only algorithm the storefront broker signs with (tot20 rejects anything else). */
+export const BROKER_ALG = "RS256";
+
+/** Default key id (overridable via `STOREFRONT_BROKER_KID`). Names the published key. */
+export const DEFAULT_BROKER_KID = "storefront-qa-1";
+
+/** Default issuer (overridable via `STOREFRONT_BROKER_ISSUER`). */
+export const DEFAULT_BROKER_ISSUER = "storefront";
+
+/** Assertion lifetime — deliberately short (replay window). */
+export const BROKER_TTL_SECONDS = 300;
+
+/** Env keys the minter reads (server-only). */
+export const BROKER_PRIVATE_KEY_ENV = "STOREFRONT_BROKER_PRIVATE_KEY_B64";
+export const BROKER_KID_ENV = "STOREFRONT_BROKER_KID";
+export const BROKER_ISSUER_ENV = "STOREFRONT_BROKER_ISSUER";
+
+/**
+ * Thrown when the minter can't sign — the private key env is absent/malformed, or
+ * no subject was supplied. Routes map this to a 503 ("integration not configured")
+ * and FAIL CLOSED: with no proof of the staff actor, the staff call must not go out.
+ */
+export class BrokerAssertionError extends Error {}
+
+/** Optional test/DI overrides (avoids touching process env in unit tests). */
+export interface MintBrokerAssertionOverrides {
+  /** base64 of the PKCS8 PEM private key (defaults to the env value). */
+  privateKeyB64?: string;
+  kid?: string;
+  issuer?: string;
+}
+
+// Import the signing key once per distinct PEM (importPKCS8 is not free). Keyed on
+// the base64 string so a key rotation (new env value) transparently re-imports.
+const keyCache = new Map<string, CryptoKey>();
+
+async function loadSigningKey(privateKeyB64: string): Promise<CryptoKey> {
+  const cached = keyCache.get(privateKeyB64);
+  if (cached) return cached;
+  let pem: string;
+  try {
+    pem = Buffer.from(privateKeyB64, "base64").toString("utf8");
+  } catch (cause) {
+    throw new BrokerAssertionError(
+      "broker assertion: STOREFRONT_BROKER_PRIVATE_KEY_B64 is not valid base64 " +
+        (cause instanceof Error ? cause.message : String(cause)),
+    );
+  }
+  if (!/-----BEGIN (RSA )?PRIVATE KEY-----/.test(pem)) {
+    throw new BrokerAssertionError(
+      "broker assertion: decoded STOREFRONT_BROKER_PRIVATE_KEY_B64 is not a PEM private key",
+    );
+  }
+  let key: CryptoKey;
+  try {
+    key = (await importPKCS8(pem, BROKER_ALG)) as CryptoKey;
+  } catch (cause) {
+    throw new BrokerAssertionError(
+      "broker assertion: failed to import the RS256 private key " +
+        (cause instanceof Error ? cause.message : String(cause)),
+    );
+  }
+  keyCache.set(privateKeyB64, key);
+  return key;
+}
+
+/**
+ * Mint a fresh, storefront-signed broker assertion PROVING `subjectEmail` is the
+ * staff actor. Returns the compact RS256 JWT to place in `X-ToT-Broker-Assertion`.
+ *
+ * Claims: `{ iss, sub:<subjectEmail>, aud:'tot20-broker', jti:<uuid>, iat, exp:iat+300 }`.
+ * Header: `{ alg:'RS256', kid, typ:'JWT' }`.
+ *
+ * FAILS CLOSED: throws {@link BrokerAssertionError} when the private key env is
+ * absent/malformed or no subject is supplied — the caller must NOT fall back to an
+ * unproven call.
+ */
+export async function mintBrokerAssertion(
+  subjectEmail: string,
+  overrides: MintBrokerAssertionOverrides = {},
+): Promise<string> {
+  const sub = (subjectEmail ?? "").trim().toLowerCase();
+  if (!sub) {
+    throw new BrokerAssertionError("broker assertion: a subject email is required");
+  }
+  const privateKeyB64 = overrides.privateKeyB64 ?? (await readEnv(BROKER_PRIVATE_KEY_ENV));
+  if (!privateKeyB64) {
+    throw new BrokerAssertionError(
+      `broker assertion: ${BROKER_PRIVATE_KEY_ENV} is not configured (fail closed)`,
+    );
+  }
+  const kid = overrides.kid ?? (await readEnv(BROKER_KID_ENV)) ?? DEFAULT_BROKER_KID;
+  const issuer = overrides.issuer ?? (await readEnv(BROKER_ISSUER_ENV)) ?? DEFAULT_BROKER_ISSUER;
+
+  const key = await loadSigningKey(privateKeyB64);
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  return new SignJWT({})
+    .setProtectedHeader({ alg: BROKER_ALG, kid, typ: "JWT" })
+    .setIssuer(issuer)
+    .setSubject(sub)
+    .setAudience(BROKER_AUDIENCE)
+    .setJti(crypto.randomUUID())
+    .setIssuedAt(nowSeconds)
+    .setExpirationTime(nowSeconds + BROKER_TTL_SECONDS)
+    .sign(key);
+}

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

@@ -0,0 +1,90 @@
+/**
+ * Local dev auth — the SINGLE, auditable home for the localhost sign-in bypass.
+ *
+ * On localhost tot20 isn't reachable, so real sign-in/invite emails can't be sent
+ * or verified. This module lets a developer complete sign-in locally: `/api/auth/send`
+ * prints a one-time code to the server console + stores it here; `/api/auth/verify`
+ * consumes it and mints a session WITHOUT tot20/JWKS.
+ *
+ * SECURITY — this must never exist in a deployed build:
+ *   1. EVERY call site MUST wrap use in `if (import.meta.env.DEV)`. That is a STATIC
+ *      boolean Vite/Astro evaluates at build time, so the whole branch (and this
+ *      module's imports) are dead-code-eliminated from the production bundle — the
+ *      same mechanism the middleware dev guards rely on.
+ *   2. `devAuthEnabled()` adds a runtime opt-in (`DEV_AUTH=1` in `.dev.vars`) so even
+ *      a local dev build does nothing unless the developer explicitly turned it on.
+ * Keeping the bypass in one file means "does prod contain the bypass?" is a single
+ * grep (`devAuth`), and the production path in send/verify is never weakened.
+ */
+import { readEnv } from "@/lib/env";
+import { devTenantResources } from "@/config/devTenants";
+import { createSession } from "./session.js";
+
+/** SESSION-KV key prefix for the one-time dev code (distinct from `authsession:`). */
+export const DEV_AUTH_CODE_PREFIX = "devauthcode:";
+/** Dev code lifetime (KV clamps expirationTtl to >= 60). */
+export const DEV_AUTH_CODE_TTL_SECONDS = 600;
+
+/** Minimal KV seam (the `SESSION` binding). */
+interface CodeKv {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+/**
+ * Runtime opt-in. Call ONLY inside `if (import.meta.env.DEV)` so the whole thing is
+ * tree-shaken from prod regardless of any env var.
+ */
+export async function devAuthEnabled(): Promise<boolean> {
+  return (await readEnv("DEV_AUTH")) === "1";
+}
+
+/** A 6-digit numeric one-time code (WebCrypto). */
+export function devAuthCode(): string {
+  const n = new Uint32Array(1);
+  crypto.getRandomValues(n);
+  return String((n[0] ?? 0) % 1_000_000).padStart(6, "0");
+}
+
+/** Store a freshly-minted code for `email`. */
+export async function storeDevCode(kv: CodeKv, email: string, code: string): Promise<void> {
+  await kv.put(`${DEV_AUTH_CODE_PREFIX}${email}`, code, {
+    expirationTtl: DEV_AUTH_CODE_TTL_SECONDS,
+  });
+}
+
+/**
+ * One-time consume: returns true iff `code` matches the stored code for `email`,
+ * deleting it on success so a code can't be replayed.
+ */
+export async function consumeDevCode(kv: CodeKv, email: string, code: string): Promise<boolean> {
+  const stored = await kv.get(`${DEV_AUTH_CODE_PREFIX}${email}`);
+  if (!stored || stored !== code) return false;
+  await kv.delete(`${DEV_AUTH_CODE_PREFIX}${email}`);
+  return true;
+}
+
+/**
+ * Session fields for a local dev sign-in (option (c)): membership on EVERY registered
+ * tenant AND a staff scope, so the dashboard picker, every tenant, and the staff
+ * (any-tenant) paths are all exercisable locally. `resource` mirrors the real path's
+ * verified `aud` (the storefront app identity, `STOREFRONT_APP_DOMAIN`).
+ */
+export async function devSessionFields(
+  email: string,
+): Promise<Parameters<typeof createSession>[1]> {
+  const resource = (await readEnv("STOREFRONT_APP_DOMAIN")) || "storefront";
+  const tenants = devTenantResources().map((resource) => ({
+    resource,
+    role: "developer",
+  }));
+  return {
+    email: email.toLowerCase(),
+    resource,
+    roles: [],
+    capability: "member",
+    tenants,
+    staff: ["staff"],
+  };
+}

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

@@ -0,0 +1,81 @@
+/**
+ * "Coming soon" holding page served to UNAUTHENTICATED visitors of a login-gated
+ * tenant (every non-self tenant on a gated host — see `loginGate.ts`).
+ *
+ * Instead of hard-redirecting to /auth/login, we serve a friendly holding page
+ * that withholds the tenant's content but offers a Sign-in button. The button
+ * carries the same `?next=` destination the gate would have redirected to, so a
+ * successful sign-in lands the visitor back where they started.
+ *
+ * The platform's own home ("self") tenant is exempt and never sees this — it
+ * renders publicly so people can browse + sign up.
+ */
+
+/** Escape a string for safe interpolation into an HTML attribute value. */
+function escapeAttr(s: string): string {
+  return s
+    .replace(/&/g, "&")
+    .replace(/"/g, """)
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+export function gatedHoldingHtml(loginHref: string): string {
+  const href = escapeAttr(loginHref);
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex, nofollow" />
+<title>Coming soon</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; margin: 0; }
+  body {
+    display: flex; align-items: center; justify-content: center;
+    min-height: 100%; padding: 2rem;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    background: radial-gradient(1200px 800px at 50% -10%, #1e293b, #0f172a 60%, #020617);
+    color: #e2e8f0;
+  }
+  main { max-width: 34rem; text-align: center; }
+  .badge {
+    display: inline-block; letter-spacing: .18em; text-transform: uppercase;
+    font-size: .72rem; font-weight: 600; color: #94a3b8;
+    border: 1px solid rgba(148,163,184,.35); border-radius: 999px;
+    padding: .35rem .8rem; margin-bottom: 1.75rem;
+  }
+  h1 { font-size: clamp(2rem, 6vw, 3rem); line-height: 1.1; margin: 0 0 1rem; color: #f8fafc; }
+  p { font-size: 1.05rem; line-height: 1.6; color: #cbd5e1; margin: 0 auto 2rem; max-width: 28rem; }
+  a.btn {
+    display: inline-block; text-decoration: none; font-weight: 600; font-size: 1rem;
+    color: #04121f; background: #38bdf8; border-radius: 10px; padding: .8rem 1.6rem;
+    transition: background .15s ease;
+  }
+  a.btn:hover { background: #7dd3fc; }
+</style>
+</head>
+<body>
+  <main>
+    <span class="badge">Token of Trust</span>
+    <h1>Coming soon</h1>
+    <p>This storefront isn't open to the public yet. If you have access, sign in to preview it.</p>
+    <a class="btn" href="${href}">Sign in</a>
+  </main>
+</body>
+</html>`;
+}
+
+/** A `200 OK` holding page — never indexed, never cached. */
+export function gatedHoldingResponse(loginHref: string): Response {
+  return new Response(gatedHoldingHtml(loginHref), {
+    status: 200,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+      "x-robots-tag": "noindex, nofollow",
+    },
+  });
+}