@tokenoftrust/storefront-runner 0.1.0

package/apps/storefront/src/pages/api/auth/magic-exchange.ts

@@ -0,0 +1,107 @@
+/**
+ * POST /api/auth/magic-exchange — exchange a magic-link token for a signed-in session.
+ *
+ * The POST half of the magic-link flow (see /auth/magic for the GET-safe landing). The
+ * one-time `signInToken` (minted by tot20 via developerInvites `issueSignInToken:true`,
+ * embedded in the storefront's branded email) is exchanged HERE — only on a POST, only
+ * from the human clicking "Confirm sign in", never on a GET (inbox link-scanners fire
+ * GET and would burn the token).
+ *
+ * tot20 verifies + BURNS the token (single-use), resolves memberships fresh, and returns
+ * a signed federated `id_token` — identical contract to /api/auth/verify. We verify that
+ * assertion OFFLINE against tot's JWKS and derive the session from its claims (never trust
+ * unsigned JSON). Fail closed on any gap.
+ */
+import type { APIContext } from "astro";
+import {
+  getAccessClient,
+  getSessionStore,
+  setSessionCookie,
+  safeNext,
+} from "@/lib/auth/route";
+import {
+  getFederatedVerifier,
+  sessionFromFederatedClaims,
+} from "@/lib/auth/identityToken";
+import { createSession, DEFAULT_SESSION_TTL_SECONDS } from "@/lib/auth/session";
+
+export const prerender = false;
+
+/** Back to the landing page carrying an error (no token in the URL on failure). */
+function magicRedirect(
+  context: APIContext,
+  params: { error?: string; next?: string },
+): Response {
+  const q = new URLSearchParams();
+  if (params.error) q.set("error", params.error);
+  if (params.next && params.next !== "/dashboard") q.set("next", params.next);
+  const qs = q.toString();
+  return context.redirect(`/auth/magic${qs ? `?${qs}` : ""}`, 303);
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  let token = "";
+  let next = "/dashboard";
+  try {
+    const form = await context.request.formData();
+    token = String(form.get("token") ?? "").trim();
+    next = safeNext(String(form.get("next") ?? "/dashboard"));
+  } catch {
+    return magicRedirect(context, { error: "invalid", next });
+  }
+  if (!token) return magicRedirect(context, { error: "missing", next });
+
+  const client = await getAccessClient();
+  const store = await getSessionStore();
+  if (!client || !store) {
+    return magicRedirect(context, { error: "unconfigured", next });
+  }
+
+  // Consume the token (single-use; burned server-side by tot20).
+  const result = await client.exchangeSignInToken(token);
+  if (!result.ok) {
+    // reason ∈ invalid|expired|error (tot20's "used" normalizes to invalid).
+    const error = result.reason === "expired" ? "expired" : "invalid";
+    return magicRedirect(context, { error, next });
+  }
+
+  // Prove authorization offline — fail closed with no flat-JSON fallback.
+  const idToken = result.id_token;
+  if (!idToken) {
+    console.error("auth/magic-exchange: no id_token on exchange; failing closed");
+    return magicRedirect(context, { error: "verify_failed", next });
+  }
+  const verifier = await getFederatedVerifier();
+  if (!verifier) {
+    console.error("auth/magic-exchange: federated verifier unconfigured");
+    return magicRedirect(context, { error: "unconfigured", next });
+  }
+
+  let derived;
+  try {
+    const claims = await verifier.verify(idToken); // enforces aud === STOREFRONT_APP_DOMAIN
+    derived = sessionFromFederatedClaims(claims);
+  } catch (err) {
+    console.error("auth/magic-exchange: id_token verification failed; failing closed", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return magicRedirect(context, { error: "verify_failed", next });
+  }
+
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const { id } = await createSession(
+    store,
+    {
+      email: derived.email,
+      resource: derived.resource,
+      roles: [],
+      capability: "member",
+      tenants: derived.tenants,
+      staff: derived.staff,
+    },
+    DEFAULT_SESSION_TTL_SECONDS,
+    nowSeconds,
+  );
+  setSessionCookie(context, id, DEFAULT_SESSION_TTL_SECONDS);
+  return context.redirect(next, 303);
+}

package/apps/storefront/src/pages/api/auth/send.ts

@@ -0,0 +1,85 @@
+/**
+ * POST /api/auth/send — ask tot20 to email a one-time access code (FEDERATED).
+ *
+ * Federated multi-tenant sign-in: storefront authenticates as its OWN operator
+ * identity and asks tot20 to mail a code to the email if it holds a role on ANY
+ * tenant — no `resource` is sent (the resource-scoped `/access-code/send` stays
+ * for preview-host gating; console sign-in is federated). ENUMERATION-RESISTANT:
+ * the response is identical whether or not the email is eligible — we always
+ * redirect to the "enter your code" step. Accepts an HTML form post (no JS needed).
+ */
+import type { APIContext } from "astro";
+import { readKv } from "@/lib/env";
+import {
+  EMAIL_RE,
+  getAccessClient,
+  safeNext,
+  loginRedirect,
+} from "@/lib/auth/route";
+import {
+  devAuthEnabled,
+  devAuthCode,
+  storeDevCode,
+  DEV_AUTH_CODE_TTL_SECONDS,
+} from "@/lib/auth/devAuth";
+
+export const prerender = false;
+
+export async function POST(context: APIContext): Promise<Response> {
+  let email = "";
+  let next = "/";
+  try {
+    const form = await context.request.formData();
+    email = String(form.get("email") ?? "").trim().toLowerCase();
+    next = safeNext(String(form.get("next") ?? "/"));
+  } catch {
+    return loginRedirect(context, { error: "invalid", next });
+  }
+
+  // Bad address → send them back to step 1 with a gentle error (no code step).
+  if (!EMAIL_RE.test(email)) {
+    return loginRedirect(context, { error: "bad_email", next });
+  }
+
+  // LOCAL DEV AUTH (send side). `import.meta.env.DEV` is a STATIC boolean — this
+  // whole branch is tree-shaken out of the production build (same mechanism as the
+  // dev guards in middleware/index.ts). It NEVER weakens the hosted path.
+  //
+  // On localhost tot20 isn't reachable, so no email can be sent. When a developer
+  // opts in with `DEV_AUTH=1` in `.dev.vars`, we instead mint a one-time code,
+  // store it in the SESSION KV, and PRINT it to the server console so the developer
+  // can complete sign-in locally. (The verify side that ACCEPTS this code + mints a
+  // session without tot20 is the security-sensitive half — see the handoff
+  // `2026-07-09-storefront-local-dev-auth-mode.md`; until it lands, the code is
+  // stored + printed but sign-in completes only once that verify path is wired.)
+  if (import.meta.env.DEV && (await devAuthEnabled())) {
+    const kv = await readKv("SESSION");
+    if (kv) {
+      const code = devAuthCode();
+      await storeDevCode(kv, email, code);
+      // eslint-disable-next-line no-console -- dev-only server-console code delivery
+      console.log(
+        `\n  🔑 [DEV AUTH] sign-in code for ${email}: ${code}\n` +
+          `     valid ${DEV_AUTH_CODE_TTL_SECONDS / 60}m · printed here only (no email in local dev)\n`,
+      );
+    } else {
+      // eslint-disable-next-line no-console -- dev-only diagnostic
+      console.warn(
+        "[DEV AUTH] DEV_AUTH=1 but no SESSION KV is bound — cannot store a dev code.",
+      );
+    }
+    // Same opaque redirect as the real path (keeps the UX identical).
+    return loginRedirect(context, { sent: true, email, next });
+  }
+
+  const client = await getAccessClient();
+  if (!client) {
+    // Integration not configured — don't pretend we sent a code.
+    return loginRedirect(context, { error: "unconfigured", email, next });
+  }
+
+  // Fire-and-neutral: even a failure here resolves opaque so we never leak
+  // whether the address is a role-holder.
+  await client.sendFederatedCode(email);
+  return loginRedirect(context, { sent: true, email, next });
+}

package/apps/storefront/src/pages/api/auth/verify.ts

@@ -0,0 +1,135 @@
+/**
+ * POST /api/auth/verify — verify the one-time code and mint the FEDERATED,
+ * multi-tenant signed-in session.
+ *
+ * Federated sign-in: storefront calls tot20's `/access-code/federated-verify`
+ * (as its own operator identity, no `resource`). tot20 checks the code and returns
+ * a signed `id_token` whose `aud` = the STOREFRONT app identity (not a tenant) and
+ * whose `tenants[]` carries ALL of the email's memberships.
+ *
+ * We verify that assertion OFFLINE against tot's JWKS with `aud` pinned to the
+ * storefront's configured app identity (`STOREFRONT_APP_DOMAIN`), then bind EVERY
+ * membership into the session — so the dashboard picker sees every vendor. Fail
+ * closed if the signed assertion is missing or verification fails (never trust the
+ * flat JSON). See `@/lib/auth/identityToken`.
+ */
+import type { APIContext } from "astro";
+import { readKv } from "@/lib/env";
+import {
+  getAccessClient,
+  getSessionStore,
+  setSessionCookie,
+  safeNext,
+  loginRedirect,
+} from "@/lib/auth/route";
+import {
+  getFederatedVerifier,
+  sessionFromFederatedClaims,
+} from "@/lib/auth/identityToken";
+import { createSession, DEFAULT_SESSION_TTL_SECONDS } from "@/lib/auth/session";
+import { devAuthEnabled, consumeDevCode, devSessionFields } from "@/lib/auth/devAuth";
+
+export const prerender = false;
+
+export async function POST(context: APIContext): Promise<Response> {
+  let email = "";
+  let code = "";
+  let next = "/";
+  try {
+    const form = await context.request.formData();
+    email = String(form.get("email") ?? "").trim().toLowerCase();
+    code = String(form.get("code") ?? "").trim();
+    next = safeNext(String(form.get("next") ?? "/"));
+  } catch {
+    return loginRedirect(context, { error: "invalid", next });
+  }
+
+  if (!email || !code) {
+    return loginRedirect(context, { sent: true, email, error: "invalid", next });
+  }
+
+  // LOCAL DEV AUTH (verify side). `import.meta.env.DEV` is a STATIC boolean — this
+  // whole branch (and the devAuth imports) are tree-shaken out of the production
+  // build, so the hosted path below (offline JWKS verification, fail-closed) is
+  // never weakened. Second gate: the DEV_AUTH opt-in. Consume the console-printed
+  // code stored by /api/auth/send and mint a local session WITHOUT tot20 — the
+  // localhost completion of the invite→sign-in loop. See @/lib/auth/devAuth.
+  if (import.meta.env.DEV && (await devAuthEnabled())) {
+    const store = await getSessionStore();
+    const kv = await readKv("SESSION");
+    if (!store || !kv) {
+      return loginRedirect(context, { sent: true, email, error: "unconfigured", next });
+    }
+    if (!(await consumeDevCode(kv, email, code))) {
+      // Same "code didn't match" UX as the real path (wrong/expired/replayed code).
+      return loginRedirect(context, { sent: true, email, error: "invalid", next });
+    }
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const { id } = await createSession(
+      store,
+      await devSessionFields(email),
+      DEFAULT_SESSION_TTL_SECONDS,
+      nowSeconds,
+    );
+    setSessionCookie(context, id, DEFAULT_SESSION_TTL_SECONDS);
+    return context.redirect(next, 303);
+  }
+
+  const client = await getAccessClient();
+  const store = await getSessionStore();
+  if (!client || !store) {
+    return loginRedirect(context, { sent: true, email, error: "unconfigured", next });
+  }
+
+  const result = await client.verifyFederatedCode(email, code);
+  if (!result.ok) {
+    // Show the code step again with the specific reason (invalid/expired/too_many_attempts).
+    return loginRedirect(context, { sent: true, email, error: result.reason, next });
+  }
+
+  // Prove authorization offline. Fail closed (no flat-JSON fallback) if the signed
+  // assertion is missing or fails verification.
+  const idToken = result.id_token;
+  if (!idToken) {
+    console.error("auth/verify: no id_token on federated result; failing closed");
+    return loginRedirect(context, { sent: true, email, error: "verify_failed", next });
+  }
+
+  // aud is the STOREFRONT app identity (STOREFRONT_APP_DOMAIN), not a tenant.
+  const verifier = await getFederatedVerifier();
+  if (!verifier) {
+    console.error("auth/verify: federated verifier unconfigured (TOT_CORE_URL/STOREFRONT_APP_DOMAIN)");
+    return loginRedirect(context, { sent: true, email, error: "unconfigured", next });
+  }
+
+  let derived;
+  try {
+    const claims = await verifier.verify(idToken); // enforces aud === STOREFRONT_APP_DOMAIN
+    // Bind EVERY membership — no single-tenant scoping (multi-vendor picker input).
+    derived = sessionFromFederatedClaims(claims);
+  } catch (err) {
+    console.error("auth/verify: federated id_token verification failed; failing closed", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return loginRedirect(context, { sent: true, email, error: "verify_failed", next });
+  }
+
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const { id } = await createSession(
+    store,
+    {
+      email: derived.email,
+      // The verified aud (storefront app identity) — the console session's scope.
+      resource: derived.resource,
+      // Per-tenant roles live in tenants[]; the console session itself is role-neutral.
+      roles: [],
+      capability: "member",
+      tenants: derived.tenants,
+      staff: derived.staff,
+    },
+    DEFAULT_SESSION_TTL_SECONDS,
+    nowSeconds,
+  );
+  setSessionCookie(context, id, DEFAULT_SESSION_TTL_SECONDS);
+  return context.redirect(next, 303);
+}

package/apps/storefront/src/pages/api/cache-purge.ts

@@ -0,0 +1,44 @@
+/**
+ * POST /api/cache-purge — bump a tenant's edge page-cache version.
+ *
+ * The ETL load step calls this per tenant after a (re)migration so freshly
+ * migrated content is visible immediately, rather than waiting out the page
+ * TTL. This closes the loop that HttpToTClient.purgeTenant() (catalog API cache)
+ * only half-covered: that purges the data cache; this purges the rendered HTML.
+ *
+ * Auth: `Authorization: Bearer <CACHE_PURGE_SECRET>`. JSON bodies are exempt from
+ * Astro's CSRF origin check, so the server-to-server ETL caller works.
+ */
+import type { APIContext } from "astro";
+import { readEnv, readKv } from "@/lib/env";
+import { bumpCacheVersion } from "@/lib/edgeCache";
+
+export const prerender = false;
+
+export async function POST(context: APIContext): Promise<Response> {
+  const secret = await readEnv("CACHE_PURGE_SECRET");
+  const auth = context.request.headers.get("authorization");
+  if (!secret || auth !== `Bearer ${secret}`) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  const kv = await readKv("TENANT_CACHE");
+  if (!kv) {
+    return new Response("No cache store bound", { status: 503 });
+  }
+
+  let tenantId: string | undefined;
+  try {
+    tenantId = ((await context.request.json()) as { tenantId?: string })?.tenantId;
+  } catch {
+    /* fall through to 400 */
+  }
+  if (!tenantId) {
+    return new Response("tenantId required", { status: 400 });
+  }
+
+  const version = await bumpCacheVersion(kv, tenantId);
+  return new Response(JSON.stringify({ tenantId, version }), {
+    headers: { "content-type": "application/json" },
+  });
+}

package/apps/storefront/src/pages/api/content-edit/ai-edit.ts

@@ -0,0 +1,64 @@
+/**
+ * POST /api/content-edit/ai-edit — the `/dev` page's "Build with Claude" live demo
+ * (WS5 G4). Same shape as `tot dev`'s inline-AI loop (G1): a prompt turns into
+ * a reviewable per-file diff via tot-mcp's `content_edit` tool.
+ *
+ * AUTH (see the G4 design note — pending WS2/beta confirmation): `/dev`'s own
+ * signed-in-viewer session (`readViewerSession`) is the developer-level gate,
+ * same as the rest of `/dev`; the MCP call itself authenticates as the
+ * storefront's own TENANT-OPERATOR credential (`getContentEditClient`, the
+ * SAME credential_validate path `/api/changes/accept` already uses) — a
+ * server-to-server trust boundary, not the individual developer's identity.
+ *
+ * CONTENT SOURCE (flagged, not yet real): this demo edits a small, fixed
+ * SANDBOX fixture below — NOT the caller's real tenant content. Wiring a real
+ * sandbox tenant's live content/theme through the customization/publish
+ * pipeline (LookFoundation) is follow-up work; this proves the live loop
+ * (prompt → content_edit → diff) end to end without that dependency.
+ */
+import type { APIContext } from "astro";
+import { readViewerSession } from "@/lib/auth/route";
+import { getContentEditClient } from "@/lib/content-edit";
+import { json } from "@/lib/grants/route.js";
+
+export const prerender = false;
+
+/** The `/dev` demo's fixed sandbox content — see the module header. */
+const SANDBOX_FILES = [
+  {
+    path: "content/home.html",
+    content: "<!doctype html>\n<title>Sandbox Store</title>\n<h1>Welcome to Sandbox Store</h1>\n",
+  },
+  {
+    path: "theme.json",
+    content: JSON.stringify({ color: { bg: "#faf9f5", text: "#16191d", accent: "#e07a5f" } }, null, 2),
+  },
+];
+
+export async function POST(context: APIContext): Promise<Response> {
+  const session = await readViewerSession({ cookies: context.cookies });
+  if (!session) return json({ error: "sign in required" }, 401);
+  if (!session.capability || session.capability === "none") {
+    return json({ error: "no developer capability on this account" }, 403);
+  }
+
+  let body: { prompt?: unknown };
+  try {
+    body = (await context.request.json()) as typeof body;
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+  const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
+  if (!prompt) return json({ error: "prompt is required" }, 400);
+
+  const client = await getContentEditClient();
+  if (client instanceof Response) return client;
+
+  try {
+    const result = await client.editContent(prompt, SANDBOX_FILES);
+    return json({ ok: true, ...result });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return json({ ok: false, error: message }, 502);
+  }
+}

package/apps/storefront/src/pages/api/csp-report.ts

@@ -0,0 +1,25 @@
+/**
+ * CSP violation collector (enables the report-only → enforce
+ * rollout). Browsers POST violation reports here (via `report-to` /
+ * `report-uri`); we log them so platform + tenant-script CSP violations surface
+ * before we flip the policy from Report-Only to enforcing. Returns 204.
+ *
+ * Phase 1: log to the worker console. A later iteration can forward to an
+ * analytics/observability sink.
+ */
+import type { APIRoute } from "astro";
+
+export const prerender = false;
+
+export const POST: APIRoute = async ({ request }) => {
+  try {
+    const body = await request.text();
+    if (body) {
+      // Reports can be `application/csp-report` or `application/reports+json`.
+      console.warn("[csp-report]", body.slice(0, 4000));
+    }
+  } catch {
+    /* never fail a report submission */
+  }
+  return new Response(null, { status: 204 });
+};

package/apps/storefront/src/pages/api/dashboard/enter-vendor.ts

@@ -0,0 +1,124 @@
+/**
+ * POST /api/dashboard/enter-vendor { vendorAppDomain } — the ToT-STAFF admission
+ * endpoint (#8425 staff access). Phase 2 of two-phase admission: on the staff
+ * viewer explicitly selecting a searched vendor, tot20 writes the server-side
+ * AUDIT row and returns the staffRoles-scoped capability; we then stamp a
+ * short-lived {@link StaffSelection} on the session and admit the viewer to
+ * `/dashboard/<appDomain>` scoped to that capability.
+ *
+ * AUTHORIZATION — two independent axes:
+ *   NEAR (this endpoint): a valid `tot_session` carrying ToT-STAFF scope
+ *     (`staff[]` non-empty). No session → 401; no staff scope → 403.
+ *   FAR (tot20): `/clients/staffVendorAccess`, operator-authed as storefront,
+ *     presenting a storefront-signed staff broker assertion in the
+ *     `X-ToT-Broker-Assertion` header (minted from the verified session email).
+ *     tot20 verifies it, re-checks staff scope from its `sub`, scopes the capability,
+ *     and writes the audit row — it is the authority. No plaintext email on the wire.
+ *
+ * The staff selection is a DISTINCT access path from `tenants[]`: we NEVER
+ * synthesize a membership. The dashboard guard + login gate consult the marker
+ * separately (see tenantSelection.staffAdmits / loginGate.sessionAdmitsHost).
+ */
+import type { APIContext } from "astro";
+import { readViewerSession, getSessionMutationHandle } from "@/lib/auth/route";
+import { updateSession } from "@/lib/auth/session";
+import { isStaffSession, buildStaffSelection } from "@/lib/dashboard/staffAdmission";
+import {
+  createStaffVendorAccessClient,
+  staffAccessHttpStatus,
+  StaffVendorAccessClientError,
+} from "@/lib/dashboard/staffVendorAccess";
+import { mintBrokerAssertion, BrokerAssertionError } from "@/lib/auth/brokerAssertion";
+
+export const prerender = false;
+
+/** JSON response with no-store (staff access state must never be edge-cached). */
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const session = await readViewerSession(context);
+  if (!session) return json({ error: "not signed in" }, 401);
+  if (!isStaffSession(session)) {
+    return json({ error: "staff access required", reason: "notStaff" }, 403);
+  }
+
+  let body: { vendorAppDomain?: unknown };
+  try {
+    body = (await context.request.json()) as typeof body;
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+  const vendorAppDomain =
+    typeof body.vendorAppDomain === "string" ? body.vendorAppDomain.trim() : "";
+  if (!vendorAppDomain) return json({ error: "vendorAppDomain is required" }, 400);
+
+  let client;
+  try {
+    client = await createStaffVendorAccessClient();
+  } catch (err) {
+    if (err instanceof StaffVendorAccessClientError) {
+      return json({ error: "staff-access integration not configured" }, 503);
+    }
+    throw err;
+  }
+
+  // #8453 `staff-invite-proof-via-broker`: prove the staff actor with a fresh
+  // storefront-signed assertion minted from the VERIFIED session email. Fail closed
+  // (503) if the signing key is unconfigured.
+  let brokerAssertion: string;
+  try {
+    brokerAssertion = await mintBrokerAssertion(session.email);
+  } catch (err) {
+    if (err instanceof BrokerAssertionError) {
+      return json({ error: "staff-proof signing not configured" }, 503);
+    }
+    throw err;
+  }
+
+  // FAR authority: tot20 verifies the assertion, derives the staff actor, scopes the
+  // capability, and writes the audit row. We admit ONLY on its ok.
+  const result = await client.grantStaffAccess(brokerAssertion, vendorAppDomain);
+  if (!result.ok) {
+    return json(
+      { error: result.message, reason: result.reason, code: result.code },
+      staffAccessHttpStatus(result.reason, result.status),
+    );
+  }
+
+  // Stamp the distinct staff-selection marker on the session (short-lived, scoped
+  // to the returned capability). Never a tenants[] entry.
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const selection = buildStaffSelection({
+    resource: vendorAppDomain,
+    capability: result.capability,
+    nowSeconds,
+  });
+  const handle = await getSessionMutationHandle(context);
+  if (!handle) {
+    // No SESSION KV / no cookie (e.g. plain `astro dev`) — the audit row is
+    // written but we can't persist the marker. Fail closed so the viewer isn't
+    // told they're admitted when the guard can't see it.
+    return json({ error: "session store unavailable; cannot persist admission" }, 503);
+  }
+  const updated = await updateSession(
+    handle.store,
+    handle.id,
+    (rec) => ({ ...rec, staffSelection: selection }),
+    nowSeconds,
+  );
+  if (!updated) {
+    return json({ error: "session expired; sign in again" }, 401);
+  }
+
+  return json({
+    ok: true,
+    appDomain: vendorAppDomain,
+    capability: result.capability,
+    redirect: `/dashboard/${encodeURIComponent(vendorAppDomain)}`,
+  });
+}