@tokenoftrust/storefront-runner 4.8.0 → 4.8.1

package/apps/storefront/astro.config.mjs

@@ -59,6 +59,7 @@ const gitSha = (() => {
 import preact from "@astrojs/preact";
 import tailwindcss from "@tailwindcss/vite";
 import { tenantHotReload } from "./dev-plugins/tenant-hot-reload.mjs";
+import { devAuthOutbox } from "./dev-plugins/dev-auth-outbox.mjs";
 import { materializeGuard } from "./integrations/materialize-guard.mjs";
 import { lifecycleHostAsset } from "./integrations/lifecycle-host-asset.mjs";
 import { googleMeasurementSandboxAsset } from "./integrations/google-measurement-sandbox-asset.mjs";
@@ -133,7 +134,7 @@ export default defineConfig({
       __CLI_INSTALL_SPEC__: JSON.stringify(cliInstallSpec),
       __GIT_SHA__: JSON.stringify(gitSha),
     },
-    plugins: [tailwindcss(), tenantHotReload()],
+    plugins: [tailwindcss(), tenantHotReload(), devAuthOutbox()],
     optimizeDeps: {
       // Vite's SSR optimizer can try to prebundle the Cloudflare adapter's
       // worker entrypoints, then the worker runner looks for a generated

package/apps/storefront/dev-plugins/dev-auth-outbox.mjs

@@ -0,0 +1,181 @@
+// @ts-check
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { appendFileSync, chmodSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// DEV_AUTH=1 local sign-in code delivery. Dev-only (`apply: "serve"`), never reaches
+// the production Worker.
+//
+// The one-time code is minted inside workerd (POST /api/auth/send), which has no host
+// filesystem, so it hands the code to this Node-side endpoint. The endpoint appends it to
+// apps/storefront/.dev-auth/outbox.txt (directory 0700, file 0600, gitignored) — readable
+// only by the developer who owns the checkout. The code and the address are never written
+// to the console or to any response.
+//
+// Wiring: on POST /api/auth/send this plugin stamps the request with the outbox URL and a
+// per-process token (`x-tot-dev-auth-outbox`, `x-tot-dev-auth-outbox-token`). Both headers
+// are overwritten on that route and stripped from every other request, so a browser can
+// neither forge them nor learn the token.
+
+export const OUTBOX_PATH = "/__tot/dev-auth-outbox";
+export const OUTBOX_URL_HEADER = "x-tot-dev-auth-outbox";
+export const OUTBOX_TOKEN_HEADER = "x-tot-dev-auth-outbox-token";
+const SEND_ROUTE = "/api/auth/send";
+
+const EMAIL_SHAPE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const CODE_SHAPE = /^\d{6}$/;
+
+/** Default outbox file: apps/storefront/.dev-auth/outbox.txt */
+export const DEFAULT_OUTBOX_FILE = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  ".dev-auth",
+  "outbox.txt",
+);
+
+/** @param {any} req @returns {Promise<string>} */
+function readBody(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (/** @type {any} */ c) => {
+      data += c;
+      if (data.length > 16 * 1024) req.destroy();
+    });
+    req.on("end", () => resolve(data));
+    req.on("error", () => resolve(data));
+  });
+}
+
+/** @param {string | undefined} address */
+export function isLoopback(address) {
+  if (!address) return false;
+  return address === "::1" || address === "::ffff:127.0.0.1" || address.startsWith("127.");
+}
+
+/** @param {string} a @param {string} b */
+function tokenMatches(a, b) {
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+/**
+ * The outbox endpoint as a plain function, so it is testable without a dev server.
+ * Returns the HTTP status it answered with.
+ *
+ * @param {{ outboxFile: string, token: string, log: (line: string) => void, now?: () => Date }} opts
+ */
+export function createOutboxHandler({ outboxFile, token, log, now = () => new Date() }) {
+  /**
+   * @param {{ remoteAddress?: string, headers: Record<string, string | string[] | undefined>, body: string }} input
+   * @returns {number}
+   */
+  return function handle({ remoteAddress, headers, body }) {
+    if (!isLoopback(remoteAddress)) return 403;
+    const presented = headers[OUTBOX_TOKEN_HEADER];
+    if (typeof presented !== "string" || !tokenMatches(presented, token)) return 403;
+    /** @type {any} */
+    let parsed;
+    try {
+      parsed = JSON.parse(body || "{}");
+    } catch {
+      return 400;
+    }
+    const email = typeof parsed?.email === "string" ? parsed.email : "";
+    const code = typeof parsed?.code === "string" ? parsed.code : "";
+    const ttl = Number.isInteger(parsed?.ttlSeconds) && parsed.ttlSeconds > 0 ? parsed.ttlSeconds : 0;
+    if (!EMAIL_SHAPE.test(email) || !CODE_SHAPE.test(code) || /[\r\n]/.test(email)) return 400;
+
+    const at = now();
+    const expires = ttl ? new Date(at.getTime() + ttl * 1000).toISOString() : "unknown";
+    mkdirSync(dirname(outboxFile), { recursive: true, mode: 0o700 });
+    chmodSync(dirname(outboxFile), 0o700);
+    appendFileSync(
+      outboxFile,
+      `${at.toISOString()}  ${email}  code ${code}  valid until ${expires}  (single use)\n`,
+      { mode: 0o600 },
+    );
+    chmodSync(outboxFile, 0o600);
+    log(`[DEV AUTH] sign-in code delivered to ${outboxFile} (owner-only)`);
+    return 204;
+  };
+}
+
+/**
+ * Remove any client-supplied outbox headers, then set `set`. Both `headers` and
+ * `rawHeaders` are rewritten, because request adapters differ in which one they read.
+ *
+ * @param {any} req @param {Record<string, string>} set
+ */
+export function stampHeaders(req, set) {
+  const names = [OUTBOX_URL_HEADER, OUTBOX_TOKEN_HEADER];
+  for (const n of names) delete req.headers[n];
+  if (Array.isArray(req.rawHeaders)) {
+    /** @type {string[]} */
+    const kept = [];
+    for (let i = 0; i + 1 < req.rawHeaders.length; i += 2) {
+      if (!names.includes(String(req.rawHeaders[i]).toLowerCase())) {
+        kept.push(req.rawHeaders[i], req.rawHeaders[i + 1]);
+      }
+    }
+    for (const [k, v] of Object.entries(set)) kept.push(k, v);
+    req.rawHeaders.length = 0;
+    req.rawHeaders.push(...kept);
+  }
+  for (const [k, v] of Object.entries(set)) req.headers[k] = v;
+}
+
+/** @param {any} server @returns {string} */
+function outboxUrl(server) {
+  const addr = server.httpServer?.address?.();
+  if (!addr || typeof addr === "string") return "";
+  const host = addr.family === "IPv6" || addr.family === 6 ? `[${addr.address === "::" ? "::1" : addr.address}]` : addr.address === "0.0.0.0" ? "127.0.0.1" : addr.address;
+  return `http://${host}:${addr.port}${OUTBOX_PATH}`;
+}
+
+/** @param {{ outboxFile?: string }} [opts] */
+export function devAuthOutbox(opts = {}) {
+  const outboxFile = opts.outboxFile ?? DEFAULT_OUTBOX_FILE;
+  const token = randomBytes(32).toString("hex");
+  const handle = createOutboxHandler({
+    outboxFile,
+    token,
+    // eslint-disable-next-line no-console -- pointer only; never the code or address
+    log: (line) => console.log(line),
+  });
+
+  /** @type {any} */
+  const plugin = {
+    name: "tot:dev-auth-outbox",
+    apply: "serve",
+    /** @param {any} server */
+    configureServer(server) {
+      server.middlewares.use(
+        async (/** @type {any} */ req, /** @type {any} */ res, /** @type {any} */ next) => {
+          const path = (req.url ?? "").split("?")[0];
+          if (path === OUTBOX_PATH) {
+            if (req.method !== "POST") {
+              res.statusCode = 405;
+              res.end();
+              return;
+            }
+            const status = handle({
+              remoteAddress: req.socket?.remoteAddress,
+              headers: req.headers,
+              body: await readBody(req),
+            });
+            res.statusCode = status;
+            res.setHeader("cache-control", "no-store");
+            res.end();
+            return;
+          }
+          const url = req.method === "POST" && path === SEND_ROUTE ? outboxUrl(server) : "";
+          stampHeaders(req, url ? { [OUTBOX_URL_HEADER]: url, [OUTBOX_TOKEN_HEADER]: token } : {});
+          next();
+        },
+      );
+    },
+  };
+  return plugin;
+}

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

@@ -3,8 +3,10 @@
  *
  * 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.
+ * stores a one-time code here and delivers it to the owner-private local outbox
+ * (`apps/storefront/.dev-auth/outbox.txt`, written by `dev-plugins/dev-auth-outbox.mjs`);
+ * `/api/auth/verify` consumes it and mints a session WITHOUT tot20/JWKS. The code is
+ * never printed to the console or returned in a response.
  *
  * 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
@@ -54,6 +56,36 @@ export async function storeDevCode(kv: CodeKv, email: string, code: string): Pro
   });
 }
 
+/** Headers the dev-auth-outbox Vite plugin stamps onto POST /api/auth/send. */
+export const DEV_AUTH_OUTBOX_URL_HEADER = "x-tot-dev-auth-outbox";
+export const DEV_AUTH_OUTBOX_TOKEN_HEADER = "x-tot-dev-auth-outbox-token";
+
+/**
+ * Hand `code` to the dev server's owner-private outbox. Returns false when the outbox
+ * plugin isn't wired (no stamped headers) or the write fails; never throws, and never
+ * logs the code or the address.
+ */
+export async function deliverDevCode(
+  request: Request,
+  email: string,
+  code: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<boolean> {
+  const url = request.headers.get(DEV_AUTH_OUTBOX_URL_HEADER);
+  const token = request.headers.get(DEV_AUTH_OUTBOX_TOKEN_HEADER);
+  if (!url || !token) return false;
+  try {
+    const res = await fetchImpl(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", [DEV_AUTH_OUTBOX_TOKEN_HEADER]: token },
+      body: JSON.stringify({ email, code, ttlSeconds: DEV_AUTH_CODE_TTL_SECONDS }),
+    });
+    return res.status === 204;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * One-time consume: returns true iff `code` matches the stored code for `email`,
  * deleting it on success so a code can't be replayed.

package/apps/storefront/src/lib/access/auth/route.ts

@@ -171,7 +171,41 @@ export function safeNext(next: string | null | undefined): string {
   return next;
 }
 
-/** Redirect back to the login page carrying step-2 state (email/error), no-JS-safe. */
+/**
+ * The address being signed in, carried between the login steps. It rides an HttpOnly
+ * cookie rather than the redirect URL, so it never lands in access logs, browser
+ * history, Referer headers or analytics. Its lifetime matches a sign-in code's.
+ */
+export const LOGIN_EMAIL_COOKIE = "tot_login_email";
+export const LOGIN_EMAIL_MAX_AGE_SECONDS = 600;
+
+type CookieContext = { cookies: APIContext["cookies"] };
+
+export function setLoginEmailCookie(context: CookieContext, email: string): void {
+  context.cookies.set(LOGIN_EMAIL_COOKIE, email, {
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax",
+    path: "/",
+    maxAge: LOGIN_EMAIL_MAX_AGE_SECONDS,
+  });
+}
+
+/** The in-progress sign-in address, or "" when absent or not email-shaped. */
+export function readLoginEmail(context: CookieContext): string {
+  const value = context.cookies.get(LOGIN_EMAIL_COOKIE)?.value ?? "";
+  return EMAIL_RE.test(value) ? value : "";
+}
+
+export function clearLoginEmailCookie(context: CookieContext): void {
+  context.cookies.delete(LOGIN_EMAIL_COOKIE, { path: "/" });
+}
+
+/**
+ * Redirect back to the login page carrying step-2 state, no-JS-safe. The query holds
+ * only finite state (`sent`, `error`, `reason`, `requiredAcr`, `next`); a supplied
+ * `email` goes to the HttpOnly login-email cookie, never the URL.
+ */
 export function loginRedirect(
   context: APIContext,
   params: {
@@ -189,9 +223,9 @@ export function loginRedirect(
     requiredAcr?: string;
   },
 ): Response {
+  if (params.email) setLoginEmailCookie(context, params.email);
   const q = new URLSearchParams();
   if (params.sent) q.set("sent", "1");
-  if (params.email) q.set("email", params.email);
   if (params.error) q.set("error", params.error);
   if (params.reason) q.set("reason", params.reason);
   if (params.requiredAcr) q.set("requiredAcr", params.requiredAcr);

package/apps/storefront/src/lib/access/auth/totAccessClient.ts

@@ -27,7 +27,6 @@
  * bodies, response shapes) is contract-fixed.
  */
 import { readEnv } from "@/lib/publication/shared/env";
-import { diagEmail } from "@/lib/observability/diag/redact";
 import { FetchHttpTransport, type HttpResponseLike, type HttpTransport } from "@/lib/developer-experience/http/fetchTransport";
 import { classifyStepUp, type StepUpChallenge, type StepUpObligation } from "./stepUpChallenge.js";
 
@@ -249,26 +248,15 @@ export class HttpTotAccessClient implements TotAccessClient {
         {},
         { email: email.toLowerCase(), ...this.credentialFields() },
       );
-      let body: unknown = "(unread)";
+      // Finite fields only: no address, domain, or upstream body content.
       try {
-        body = await res.json();
-      } catch {
-        body = "(non-JSON)";
-      }
-      try {
-        console.info(
-          "[diag:federated-send]",
-          JSON.stringify({ email: diagEmail(email.toLowerCase()), status: res.status, body }),
-        );
+        console.info("[diag:federated-send]", JSON.stringify({ status: res.status }));
       } catch {
         /* never break */
       }
     } catch (e) {
       try {
-        console.warn(
-          "[diag:federated-send] transport error",
-          e instanceof Error ? e.message : String(e),
-        );
+        console.warn("[diag:federated-send] transport error");
       } catch {
         /* never break */
       }
@@ -333,9 +321,9 @@ export class HttpTotAccessClient implements TotAccessClient {
           ...this.credentialFields(),
         },
       );
-    } catch (e) {
+    } catch {
       try {
-        console.warn("[diag:mint] transport error", e instanceof Error ? e.message : String(e));
+        console.warn("[diag:mint] transport error");
       } catch {
         /* never break */
       }
@@ -353,7 +341,7 @@ export class HttpTotAccessClient implements TotAccessClient {
     // (only present on success) is never in this branch, so nothing sensitive leaks.
     if (!result.ok) {
       try {
-        console.warn("[diag:mint]", JSON.stringify({ status: res.status, body }));
+        console.warn("[diag:mint]", JSON.stringify({ status: res.status }));
       } catch {
         /* never break */
       }

package/apps/storefront/src/lib/access/dashboard/staffStoreEntry.ts

@@ -21,6 +21,7 @@ import { updateSession } from "@/lib/access/auth/session";
 import { isStaffSession, buildStaffSelection } from "./staffAdmission";
 import {
   createStaffVendorAccessClient,
+  staffAccessFailureMessage,
   staffAccessHttpStatus,
   StaffVendorAccessClientError,
 } from "./staffVendorAccess";
@@ -89,7 +90,7 @@ export async function enterStoreAsStaff(input: StaffStoreEntryInput): Promise<St
     return {
       ok: false,
       status: staffAccessHttpStatus(result.reason, result.status),
-      body: { error: result.message, reason: result.reason, code: result.code },
+      body: { error: staffAccessFailureMessage(result.reason), reason: result.reason, code: result.code },
     };
   }
 

package/apps/storefront/src/lib/access/dashboard/staffVendorAccess.ts

@@ -188,9 +188,7 @@ export class HttpStaffVendorAccessClient implements StaffVendorAccessClient {
         ok: false,
         status: 0,
         reason: "error",
-        message:
-          "staffVendorAccess: transport failure searching vendors " +
-          (cause instanceof Error ? cause.message : String(cause)),
+        message: "staffVendorAccess: transport failure searching vendors",
       };
     }
     let parsed: unknown;
@@ -228,9 +226,7 @@ export class HttpStaffVendorAccessClient implements StaffVendorAccessClient {
         ok: false,
         status: 0,
         reason: "error",
-        message:
-          "staffVendorAccess: transport failure granting access " +
-          (cause instanceof Error ? cause.message : String(cause)),
+        message: "staffVendorAccess: transport failure granting access",
       };
     }
     let parsed: unknown;
@@ -295,9 +291,8 @@ function failure(
   c: Record<string, unknown>,
 ): { ok: false; status: number; reason: StaffAccessFailureReason; message: string; code?: string } {
   const code = typeof c.code === "string" ? c.code : undefined;
-  const message = typeof c.message === "string" ? c.message : undefined;
   const reason = reasonFor(code, status);
-  return { ok: false, status, reason, message: message ?? defaultMessage(reason, status), ...(code ? { code } : {}) };
+  return { ok: false, status, reason, message: staffAccessFailureMessage(reason), ...(code ? { code } : {}) };
 }
 
 function reasonFor(code: string | undefined, status: number): StaffAccessFailureReason {
@@ -340,7 +335,8 @@ export function staffAccessHttpStatus(reason: StaffAccessFailureReason, upstream
   }
 }
 
-function defaultMessage(reason: StaffAccessFailureReason, status: number): string {
+/** Finite staff-facing copy for a staff-access refusal — the only text a route returns. */
+export function staffAccessFailureMessage(reason: StaffAccessFailureReason): string {
   switch (reason) {
     case "notStaff":
       return "this account doesn't hold ToT-staff access to that vendor";
@@ -351,7 +347,7 @@ function defaultMessage(reason: StaffAccessFailureReason, status: number): strin
     case "invalid":
       return "a valid vendor is required";
     default:
-      return `staffVendorAccess: tot20 returned status ${status}`;
+      return "Token of Trust couldn't complete the staff-access request; try again shortly";
   }
 }
 

package/apps/storefront/src/lib/access/shared/accessExplain.ts

@@ -41,19 +41,109 @@ export interface AccessExplanation {
   steps: ExplainStep[];
 }
 
-/** The granter-facing verdict. */
+/** The steps tot-mcp's explain can fail on (tot-mcp access-explain-advice.ts `AccessStep`). */
+export const ACCESS_STEPS = [
+  "identity",
+  "broker",
+  "tenant-context",
+  "capability-row",
+  "row-resolution",
+  "repo-provisioned",
+  "session-scope",
+  "checkout",
+] as const;
+
+export type AccessStep = (typeof ACCESS_STEPS)[number];
+export type VerdictStep = AccessStep | "unknown";
+
+/**
+ * The reason and fix shown for each failed step. The storefront owns this copy: tot-mcp's
+ * own `reason`/`fix` are fixed text today, but the granter's page and its logs must not
+ * depend on a remote service never putting identity detail there.
+ */
+export const STEP_ADVICE = {
+  // Each value is ONE string literal: `"a" + "b"` widens to `string` even under
+  // `as const`, which would make StepReason/StepFix free text again.
+  identity: {
+    reason:
+      "This person has no Token of Trust identity enrolled with tot-mcp yet, so no session of theirs can resolve any store.",
+    fix: "Have them accept the invite and sign in once (`tot login`, or connect the tot MCP and complete sign-in). If they already have, run identity_link_begin from their session; enrollment did not happen at sign-in.",
+  },
+  broker: {
+    reason: "Token of Trust did not answer the store enumeration for this identity.",
+    fix: "Retry in a minute. If it persists, the broker is failing for this identity — file it with this result attached.",
+  },
+  "tenant-context": {
+    reason:
+      "Token of Trust does not list this store for this identity: the invite is still pending, or it was accepted under a different email address.",
+    fix: "Confirm the invitee accepted from the exact address invited. If they accepted from a different address, resend the invite to the address they sign in with.",
+  },
+  "capability-row": {
+    reason: "No invite record exists for this person on this store.",
+    fix: "Resend the invite.",
+  },
+  "row-resolution": {
+    reason:
+      "The invite record and the sign-in read disagree about this person — the two paths resolve different identities.",
+    fix: "This is a tot-mcp defect, not a setup problem. File it with this result attached.",
+  },
+  "repo-provisioned": {
+    reason: "The store has no provisioned code repository, so there is nothing to check out.",
+    fix: "Provision the store repository first (Team page \"Provision now\", or repo_provision).",
+  },
+  "session-scope": {
+    reason:
+      "Token of Trust lists the store for this identity, but a fresh session built from that answer does not hold it.",
+    fix: "This is a tot-mcp defect, not a setup problem. File it with this result attached.",
+  },
+  checkout: {
+    reason: "A session holds the store, but checkout cannot resolve its repository.",
+    fix: "Provision the store repository, or resend the invite so it records the app binding.",
+  },
+  unknown: {
+    reason: "Access does not resolve.",
+    fix: "Run access_explain for this developer and store.",
+  },
+} as const satisfies Record<VerdictStep, { reason: string; fix: string }>;
+
+export type StepReason = (typeof STEP_ADVICE)[VerdictStep]["reason"];
+export type StepFix = (typeof STEP_ADVICE)[VerdictStep]["fix"];
+
+/** Why a verification could not be completed; never upstream text. */
+export const UNAVAILABLE_REASONS = [
+  "verification is not configured here",
+  "the tot-mcp address is malformed",
+  "tot-mcp did not answer",
+  "tot-mcp refused the verification request",
+  "tot-mcp sent an unreadable answer",
+  "not verified",
+] as const;
+
+export type UnavailableReason = (typeof UNAVAILABLE_REASONS)[number];
+
+const STEPS: ReadonlySet<string> = new Set(ACCESS_STEPS);
+
+/** The finite step for a value tot-mcp sent ("unknown" when it is not one we know). */
+export function verdictStepOf(value: unknown): VerdictStep {
+  return typeof value === "string" && STEPS.has(value) ? (value as AccessStep) : "unknown";
+}
+
+/** The capability a verified invitee holds (the invite always writes this one). */
+const VERIFIED_CAPABILITY = "preview-access";
+
+/** The granter-facing verdict. Every string in it is storefront-owned, finite copy. */
 export type AccessVerification =
-  | { state: "verified"; capability: string; expiry: "none"; advice: "tot-mcp" }
+  | { state: "verified"; capability: typeof VERIFIED_CAPABILITY; expiry: "none"; advice: "tot-mcp" }
   | {
     state: "awaiting-acceptance";
     inviteStatus: "pending" | "accepted";
-    failedStep: string;
-    reason: string;
-    fix: string;
+    failedStep: VerdictStep;
+    reason: StepReason;
+    fix: StepFix;
     advice: "tot-mcp";
   }
-  | { state: "broken"; failedStep: string; reason: string; fix: string; advice: "tot-mcp" }
-  | { state: "unavailable"; reason: string; advice: "tot-mcp" };
+  | { state: "broken"; failedStep: VerdictStep; reason: StepReason; fix: StepFix; advice: "tot-mcp" }
+  | { state: "unavailable"; reason: UnavailableReason; advice: "tot-mcp" };
 
 /** POST transport seam (injectable for tests). */
 export interface ExplainTransport {
@@ -88,18 +178,14 @@ export function classifyExplanation(
   inviteStatus: "pending" | "accepted",
 ): AccessVerification {
   if (explanation.verified) {
-    return {
-      state: "verified",
-      capability: explanation.capability ?? "preview-access",
-      expiry: "none",
-      advice: "tot-mcp",
-    };
+    return { state: "verified", capability: VERIFIED_CAPABILITY, expiry: "none", advice: "tot-mcp" };
   }
   const failed = explanation.steps.find((s) => s.step === explanation.failedStep);
+  const failedStep = verdictStepOf(explanation.failedStep);
   const verdict = {
-    failedStep: explanation.failedStep ?? "unknown",
-    reason: explanation.reason ?? "Access does not resolve.",
-    fix: explanation.fix ?? "Run access_explain for this developer and store.",
+    failedStep,
+    reason: STEP_ADVICE[failedStep].reason,
+    fix: STEP_ADVICE[failedStep].fix,
     advice: "tot-mcp" as const,
   };
   // Accepting on the storefront does not enroll the tot identity — the developer's first
@@ -133,14 +219,10 @@ export async function explainDeveloperAccess(
     return { state: "unavailable", reason: "the tot-mcp address is malformed", advice: "tot-mcp" };
   }
   if (outcome.kind === "transport-error") {
-    return {
-      state: "unavailable",
-      reason: "tot-mcp did not answer: " + outcome.message,
-      advice: "tot-mcp",
-    };
+    return { state: "unavailable", reason: "tot-mcp did not answer", advice: "tot-mcp" };
   }
   if (outcome.kind === "misconfigured" || outcome.kind === "http-error") {
-    return { state: "unavailable", reason: `tot-mcp answered ${outcome.status}`, advice: "tot-mcp" };
+    return { state: "unavailable", reason: "tot-mcp refused the verification request", advice: "tot-mcp" };
   }
   const res = outcome;
   try {
@@ -149,11 +231,7 @@ export async function explainDeveloperAccess(
       return { state: "unavailable", reason: "tot-mcp sent an unreadable answer", advice: "tot-mcp" };
     }
     return classifyExplanation(explanation, inviteStatus);
-  } catch (cause) {
-    return {
-      state: "unavailable",
-      reason: "tot-mcp did not answer: " + (cause instanceof Error ? cause.message : String(cause)),
-      advice: "tot-mcp",
-    };
+  } catch {
+    return { state: "unavailable", reason: "tot-mcp sent an unreadable answer", advice: "tot-mcp" };
   }
 }

package/apps/storefront/src/lib/access/shared/developerInvites.ts

@@ -54,9 +54,9 @@
  */
 import { readEnv } from "@/lib/publication/shared/env";
 import { callMcpService } from "@/lib/developer-experience/http/mcpServiceCall";
-import { diagEmail } from "@/lib/observability/diag/redact";
 import { checkStorePreviewReady, type PreflightDecision } from "@/lib/access/shared/invitePreflight";
 import { explainDeveloperAccess, type AccessVerification } from "@/lib/access/shared/accessExplain";
+import { failureReasonForStatus, type FailureReason } from "@/lib/observability/diag/failureReason";
 
 /**
  * The header carrying the storefront-signed staff BROKER ASSERTION to tot20
@@ -444,8 +444,6 @@ export class HttpDeveloperInviteClient implements DeveloperInviteClient {
     // the email-send trace). `signInUrlHost` is the top allowlist suspect.
     logInviteDiag("request", {
       endpoint: `${this.baseUrl}/api/clients/developerInvites`,
-      tenant: input.tenant,
-      email: diagEmail(input.email.toLowerCase()),
       sendEmail: input.sendEmail ?? "(unset → tot20 default)",
       hasSignInUrl: !!input.signInUrl,
       signInUrlHost: safeHost(input.signInUrl),
@@ -460,14 +458,12 @@ export class HttpDeveloperInviteClient implements DeveloperInviteClient {
         headers,
         body,
       );
-    } catch (cause) {
+    } catch {
       return {
         ok: false,
         status: 0,
         reason: "error",
-        message:
-          "developerInvites: transport failure calling tot20 " +
-          (cause instanceof Error ? cause.message : String(cause)),
+        message: "developerInvites: transport failure calling tot20",
       };
     }
 
@@ -486,19 +482,17 @@ export class HttpDeveloperInviteClient implements DeveloperInviteClient {
     // DIAGNOSTIC: tot20's decision — the crux is `emailed`. `changed:false, emailed:false`
     // means tot20 authorized + already had the role but did NOT send (the gate we're hunting).
     logInviteDiag("response", {
-      tenant: input.tenant,
-      email: diagEmail(input.email.toLowerCase()),
       httpStatus: res.status,
       ok: result.ok,
       ...(result.ok
         ? {
             changed: result.changed,
             emailed: result.emailed,
-            emailReason: result.emailReason ?? "(none)",
-            emailDetail: result.emailDetail,
+            hasEmailReason: !!result.emailReason,
+            hasEmailDetail: !!result.emailDetail,
             signInEligible: result.signInEligible,
           }
-        : { reason: result.reason, code: result.code }),
+        : { reason: result.reason, hasCode: !!result.code }),
     });
     return result;
   }
@@ -529,14 +523,12 @@ export class HttpDeveloperInviteClient implements DeveloperInviteClient {
         `${this.baseUrl}/api/clients/developerInvites?${q.toString()}`,
         headers,
       );
-    } catch (cause) {
+    } catch {
       return {
         ok: false,
         status: 0,
         reason: "error",
-        message:
-          "developerInvites: transport failure listing invites " +
-          (cause instanceof Error ? cause.message : String(cause)),
+        message: "developerInvites: transport failure listing invites",
       };
     }
     let parsed: unknown;
@@ -576,14 +568,12 @@ export class HttpDeveloperInviteClient implements DeveloperInviteClient {
         `${this.baseUrl}/api/clients/developerInvites/${encodeURIComponent(inviteId)}`,
         headers,
       );
-    } catch (cause) {
+    } catch {
       return {
         ok: false,
         status: 0,
         reason: "error",
-        message:
-          "developerInvites: transport failure revoking invite " +
-          (cause instanceof Error ? cause.message : String(cause)),
+        message: "developerInvites: transport failure revoking invite",
       };
     }
     let parsed: unknown;
@@ -801,6 +791,29 @@ export function developerInviteHttpStatus(
   }
 }
 
+/**
+ * Client-facing copy for a developer-invite failure. Routes answer with this, never with
+ * the result's `message` (which can carry tot20's own text).
+ */
+export function developerInviteFailureMessage(reason: DeveloperInviteFailureReason): string {
+  switch (reason) {
+    case "notGranted":
+      return "storefront isn't authorized to manage developers on this vendor";
+    case "notAuthenticated":
+      return "storefront's operator credential was rejected";
+    case "tenantRequired":
+      return "a target vendor is required";
+    case "invalidEmail":
+      return "a valid developer email is required";
+    case "tenantNotFound":
+      return "this vendor isn't a resolvable Token of Trust app";
+    case "storeNotProvisioned":
+      return "this vendor's store repo isn't provisioned on this environment yet";
+    default:
+      return "Token of Trust couldn't complete the request; try again shortly";
+  }
+}
+
 function defaultMessage(
   reason: DeveloperInviteFailureReason,
   status: number,
@@ -1108,9 +1121,9 @@ export async function recordDeveloperAppBinding(
 export type AcceptInviteResult =
   | { accepted: true; changed: boolean }
   // Not attempted (seam unconfigured) or no invite to accept — not a hard failure.
-  | { accepted: false; skipped: true; reason: string }
+  | { accepted: false; skipped: true; reason: "no-tenant-or-email" | "not-configured" | "no-invite-for-email" }
   // Attempted but failed for a real reason (auth / store fault / transport).
-  | { accepted: false; skipped: false; reason: string };
+  | { accepted: false; skipped: false; reason: FailureReason };
 
 /**
  * Mark a developer invite ACCEPTED at the magic-link confirm (#8425 accept-before-
@@ -1167,19 +1180,9 @@ export async function acceptDeveloperInvite(
     if (res.status === 404) {
       return { accepted: false, skipped: true, reason: "no-invite-for-email" };
     }
-    return {
-      accepted: false,
-      skipped: false,
-      reason: `tot20 accept returned status ${res.status}`,
-    };
-  } catch (cause) {
-    return {
-      accepted: false,
-      skipped: false,
-      reason:
-        "developerInvites accept transport failure: " +
-        (cause instanceof Error ? cause.message : String(cause)),
-    };
+    return { accepted: false, skipped: false, reason: failureReasonForStatus(res.status) };
+  } catch {
+    return { accepted: false, skipped: false, reason: "transport" };
   }
 }
 
@@ -1258,9 +1261,8 @@ export async function inviteDeveloperToTenant(
   const preflight = deps.preflight ?? checkStorePreviewReady;
   const ready = await preflight(input.tenant);
   if (ready.block) {
-    console.warn(
-      `[developerInvites] invite BLOCKED by preflight for ${input.tenant}: ${ready.reason}`,
-    );
+    // Finite fields only: no tenant, no free-form preflight reason.
+    console.warn("[developerInvites] invite blocked by preflight");
     return {
       invite: {
         ok: false,

package/apps/storefront/src/lib/access/shared/invitePreflight.ts

@@ -82,7 +82,7 @@ export async function checkStorePreviewReady(
   if (outcome.kind === "not-configured") return { block: false, reason: "not-configured" };
   if (outcome.kind === "bad-url") return { block: false, reason: "bad-mcp-url" };
   if (outcome.kind === "transport-error") {
-    return { block: false, reason: "preflight request failed: " + outcome.message };
+    return { block: false, reason: "preflight request failed" };
   }
   if (outcome.kind === "misconfigured") {
     return { block: false, reason: `preflight misconfigured: status ${outcome.status}` };

package/apps/storefront/src/lib/access/shared/principalGrants.ts

@@ -76,7 +76,6 @@
  * swaps in the Http client with no call-site change.
  */
 import { readEnv } from "@/lib/publication/shared/env";
-import { diagEmail } from "@/lib/observability/diag/redact";
 import { BROKER_ASSERTION_HEADER, BROKER_PRIVATE_KEY_ENV } from "@/lib/access/auth/brokerAssertion";
 
 /** A human grantee — the only principal type this HTTP surface accepts. */
@@ -285,8 +284,6 @@ export class HttpPrincipalGrantClient implements PrincipalGrantClient {
 
     logGrantDiag("request", {
       endpoint: `${this.baseUrl}/api/clients/principalGrants`,
-      tenant: input.tenant,
-      email: diagEmail(input.principal.email.toLowerCase()),
       capability: input.capability,
       expiresAt: input.expiresAt,
     });
@@ -298,17 +295,18 @@ export class HttpPrincipalGrantClient implements PrincipalGrantClient {
         this.brokeredHeaders(assertion, false),
         body,
       );
-    } catch (cause) {
-      return transportFailure("creating principal grant", cause);
+    } catch {
+      return transportFailure("creating principal grant");
     }
     const parsed = await safeJson(res, "creating principal grant");
     if ("failed" in parsed) return parsed.failed;
     const result = normalizeCreateResponse(res.status, parsed.body);
     logGrantDiag("response", {
-      tenant: input.tenant,
       httpStatus: res.status,
       ok: result.ok,
-      ...(result.ok ? { ref: result.ref } : { reason: result.reason, code: result.code }),
+      ...(result.ok
+        ? { hasRef: !!result.ref }
+        : { reason: result.reason, hasCode: !!result.code }),
     });
     return result;
   }
@@ -324,8 +322,8 @@ export class HttpPrincipalGrantClient implements PrincipalGrantClient {
         `${this.baseUrl}/api/clients/principalGrants?tenant=${encodeURIComponent(tenant)}`,
         this.brokeredHeaders(assertion, true),
       );
-    } catch (cause) {
-      return transportFailure("listing principal grants", cause);
+    } catch {
+      return transportFailure("listing principal grants");
     }
     const parsed = await safeJson(res, "listing principal grants");
     if ("failed" in parsed) return parsed.failed;
@@ -345,8 +343,8 @@ export class HttpPrincipalGrantClient implements PrincipalGrantClient {
           `?tenant=${encodeURIComponent(tenant)}`,
         this.brokeredHeaders(assertion, true),
       );
-    } catch (cause) {
-      return transportFailure("revoking principal grant", cause);
+    } catch {
+      return transportFailure("revoking principal grant");
     }
     const parsed = await safeJson(res, "revoking principal grant");
     if ("failed" in parsed) return parsed.failed;
@@ -365,12 +363,12 @@ function brokerNotConfigured(): PrincipalGrantFailed {
   };
 }
 
-async function transportFailure(action: string, cause: unknown): Promise<PrincipalGrantFailed> {
+async function transportFailure(action: string): Promise<PrincipalGrantFailed> {
   return {
     ok: false,
     status: 0,
     reason: "error",
-    message: `principalGrants: transport failure ${action} ` + (cause instanceof Error ? cause.message : String(cause)),
+    message: `principalGrants: transport failure ${action}`,
   };
 }
 
@@ -458,11 +456,12 @@ function failureFrom(
   const code = typeof c.code === "string" ? c.code : undefined;
   const reason = reasonFor(code, status);
   const upstream = typeof c.message === "string" ? c.message : undefined;
-  const message = reason === "error" && upstream ? upstream : defaultMessage(reason, status);
+  const message = reason === "error" && upstream ? upstream : principalGrantFailureMessage(reason);
   return { status, reason, message, ...(code ? { code } : {}) };
 }
 
-function defaultMessage(reason: PrincipalGrantFailureReason, status: number): string {
+/** Finite operator-facing copy for a principal-grant refusal — the only text a route returns. */
+export function principalGrantFailureMessage(reason: PrincipalGrantFailureReason): string {
   switch (reason) {
     case "notAuthenticated":
       return "storefront isn't authorized to grant on this tenant";
@@ -486,7 +485,7 @@ function defaultMessage(reason: PrincipalGrantFailureReason, status: number): st
     case "brokerNotConfigured":
       return "delegation isn't available on this deployment";
     default:
-      return `principalGrants: tot20 returned status ${status}`;
+      return "Token of Trust couldn't complete the delegation; try again shortly";
   }
 }
 
@@ -578,7 +577,7 @@ export class MockPrincipalGrantClient implements PrincipalGrantClient {
       ok: false,
       status: 403,
       reason: "subjectNotTenantOwner",
-      message: defaultMessage("subjectNotTenantOwner", 403),
+      message: principalGrantFailureMessage("subjectNotTenantOwner"),
       code: "operatorGrants:subjectNotTenantOwner",
     };
   }

package/apps/storefront/src/lib/engagement/messaging/messagesClient.ts

@@ -16,6 +16,10 @@
  * Built like `@/lib/grants/developerInvites` (interface + Http impl + Mock + env factory).
  */
 import { readEnv } from "@/lib/publication/shared/env";
+import {
+  failureReasonForStatus,
+  type FailureReason,
+} from "@/lib/observability/diag/failureReason";
 
 export interface InlineEmail {
   /** Recipient address. */
@@ -26,9 +30,13 @@ export interface InlineEmail {
   html: string;
 }
 
+/**
+ * `reason` is a finite category. Upstream failure text (exception messages, tot20's
+ * `message`/`reason` fields) can echo the recipient address, so it never leaves this client.
+ */
 export type MessageSendResult =
   | { sent: true; id?: string }
-  | { sent: false; status: number; reason: string };
+  | { sent: false; status: number; reason: FailureReason };
 
 export interface MessagesClient {
   sendInlineEmail(msg: InlineEmail): Promise<MessageSendResult>;
@@ -97,14 +105,14 @@ export class HttpMessagesClient implements MessagesClient {
           ...this.credentialFields(),
         },
       );
-    } catch (cause) {
-      return { sent: false, status: 0, reason: cause instanceof Error ? cause.message : String(cause) };
+    } catch {
+      return { sent: false, status: 0, reason: "transport" };
     }
     let body: unknown;
     try {
       body = await res.json();
     } catch {
-      return { sent: false, status: res.status, reason: `non-JSON body (status ${res.status})` };
+      return { sent: false, status: res.status, reason: "non-json" };
     }
     return normalizeSend(res.status, body);
   }
@@ -117,9 +125,7 @@ export function normalizeSend(status: number, body: unknown): MessageSendResult
   if (c.sent === true || (status >= 200 && status < 300 && c.sent !== false)) {
     return { sent: true, ...(typeof c.id === "string" ? { id: c.id } : {}) };
   }
-  const reason =
-    typeof c.message === "string" ? c.message : typeof c.reason === "string" ? c.reason : `send failed (status ${status})`;
-  return { sent: false, status, reason };
+  return { sent: false, status, reason: failureReasonForStatus(status) };
 }
 
 // --- Mock (tests + local dev) -----------------------------------------------

package/apps/storefront/src/lib/observability/diag/failureReason.ts

@@ -0,0 +1,37 @@
+/**
+ * The finite set of failure categories a diagnostic line or client-facing response may
+ * carry. Upstream failure text (exception messages, response bodies, remote `message` /
+ * `reason` fields) can hold addresses, tokens or tenant detail, so it is mapped to one of
+ * these categories at the producer and never forwarded verbatim.
+ */
+export const FAILURE_REASONS = [
+  "transport",
+  "non-json",
+  "unauthorized",
+  "not-found",
+  "rate-limited",
+  "rejected",
+  "upstream-error",
+  "not-configured",
+  "unknown",
+] as const;
+
+export type FailureReason = (typeof FAILURE_REASONS)[number];
+
+const KNOWN: ReadonlySet<string> = new Set(FAILURE_REASONS);
+
+export function isFailureReason(value: unknown): value is FailureReason {
+  return typeof value === "string" && KNOWN.has(value);
+}
+
+/** Category for an HTTP status (0 = no response reached us). */
+export function failureReasonForStatus(status: number): FailureReason {
+  if (status === 0) return "transport";
+  if (status === 401 || status === 403) return "unauthorized";
+  if (status === 404) return "not-found";
+  if (status === 429) return "rate-limited";
+  if (status >= 400 && status < 500) return "rejected";
+  if (status >= 500 && status < 600) return "upstream-error";
+  if (status >= 200 && status < 300) return "rejected";
+  return "unknown";
+}

package/apps/storefront/src/lib/observability/diag/redact.ts

@@ -1,20 +1,17 @@
 /**
- * Redaction helpers for diagnostic logs — keep traces correlatable without persisting PII.
+ * Redaction helpers for diagnostic logs. An email address never appears in a diagnostic
+ * line in any build: not the local part, not its first character, not the domain.
+ * Correlate with an opaque reference (for example `hashActorId`) instead.
  */
 
-/** Mask an email for logs: keep the first char + the domain (`d***@example.com`). */
-export function maskEmail(email: string): string {
-  const at = email.indexOf("@");
-  if (at <= 0) return "***";
-  return `${email[0]}***${email.slice(at)}`;
+export const REDACTED_EMAIL = "[redacted-email]";
+
+/** A log-safe stand-in for an email address. Reveals nothing about the input. */
+export function maskEmail(_email: string): string {
+  return REDACTED_EMAIL;
 }
 
-/**
- * Email for a diagnostic line: the FULL address in local dev only (`import.meta.env.DEV`
- * is a static boolean → this branch is tree-shaken from the production worker), where logs
- * are local + gitignored and the raw address is needed for debugging; MASKED everywhere the
- * build is deployed, so prod/worker logs never persist raw recipient PII.
- */
-export function diagEmail(email: string): string {
-  return import.meta.env.DEV ? email : maskEmail(email);
+/** Email for a diagnostic line. Fully redacted in local dev and deployed builds alike. */
+export function diagEmail(_email: string): string {
+  return REDACTED_EMAIL;
 }

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

@@ -116,8 +116,9 @@ export async function POST(context: APIContext): Promise<Response> {
     const claims = await verifier.verify(idToken); // enforces aud === STOREFRONT_APP_DOMAIN
     derived = sessionFromFederatedClaims(claims);
   } catch (err) {
+    // The error class only: a verifier message can quote token claims (the address).
     console.error("auth/magic-exchange: id_token verification failed; failing closed", {
-      error: err instanceof Error ? err.message : String(err),
+      errorClass: err instanceof Error ? err.name : typeof err,
     });
     return magicRedirect(context, { error: "verify_failed", tenant, emailHint, next });
   }
@@ -148,14 +149,11 @@ export async function POST(context: APIContext): Promise<Response> {
   try {
     const accepted = await acceptDeveloperInvite(tenant, derived.email);
     if (!accepted.accepted && !accepted.skipped) {
-      console.warn("auth/magic-exchange: invite accept did not record", {
-        tenant,
-        reason: accepted.reason,
-      });
+      console.warn("auth/magic-exchange: invite accept did not record", { reason: accepted.reason });
     }
   } catch (err) {
     console.warn("auth/magic-exchange: invite accept threw (swallowed)", {
-      error: err instanceof Error ? err.message : String(err),
+      errorClass: err instanceof Error ? err.name : typeof err,
     });
   }
 
@@ -167,7 +165,6 @@ export async function POST(context: APIContext): Promise<Response> {
     const verification = await explainDeveloperAccess(tenant, derived.email, "accepted");
     if (verification.state === "broken") {
       console.warn("auth/magic-exchange: accepted invite does not resolve", {
-        tenant,
         failedStep: verification.failedStep,
       });
     }

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

@@ -20,7 +20,7 @@ import {
   devAuthEnabled,
   devAuthCode,
   storeDevCode,
-  DEV_AUTH_CODE_TTL_SECONDS,
+  deliverDevCode,
 } from "@/lib/access/auth/devAuth";
 
 export const prerender = false;
@@ -46,22 +46,22 @@ export async function POST(context: APIContext): Promise<Response> {
   // 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.)
+  // opts in with `DEV_AUTH=1` in `.dev.vars`, we instead mint a one-time code, store
+  // it in the SESSION KV, and deliver it to the owner-private local outbox
+  // (`apps/storefront/.dev-auth/outbox.txt`). The code and address never reach the
+  // console or the response. /api/auth/verify consumes it (single use, 10 minutes).
   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`,
-      );
+      if (!(await deliverDevCode(context.request, email, code))) {
+        // eslint-disable-next-line no-console -- dev-only diagnostic; no code, no address
+        console.warn(
+          "[DEV AUTH] could not deliver the sign-in code to the local outbox " +
+            "(is the dev-auth-outbox plugin registered in astro.config.mjs?).",
+        );
+      }
     } else {
       // eslint-disable-next-line no-console -- dev-only diagnostic
       console.warn(

package/apps/storefront/src/pages/api/auth/step-up-verify.ts

@@ -94,8 +94,9 @@ export async function POST(context: APIContext): Promise<Response> {
     const claims = await verifier.verify(result.idToken); // enforces aud === STOREFRONT_APP_DOMAIN
     derived = sessionFromFederatedClaims(claims);
   } catch (err) {
+    // The error class only: a verifier message can quote token claims (the address).
     console.error("auth/step-up-verify: id_token verification failed; failing closed", {
-      error: err instanceof Error ? err.message : String(err),
+      errorClass: err instanceof Error ? err.name : typeof err,
     });
     return loginRedirect(context, {
       sent: true,

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

@@ -19,6 +19,7 @@ import {
   getAccessClient,
   getSessionStore,
   setSessionCookie,
+  clearLoginEmailCookie,
   safeNext,
   loginRedirect,
 } from "@/lib/access/auth/route";
@@ -51,8 +52,8 @@ export async function POST(context: APIContext): Promise<Response> {
   // 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
+  // never weakened. Second gate: the DEV_AUTH opt-in. Consume the code stored by
+  // /api/auth/send (delivered to the private local outbox) 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();
@@ -72,6 +73,7 @@ export async function POST(context: APIContext): Promise<Response> {
       nowSeconds,
     );
     setSessionCookie(context, id, DEFAULT_SESSION_TTL_SECONDS);
+    clearLoginEmailCookie(context);
     return context.redirect(next, 303);
   }
 
@@ -127,8 +129,9 @@ export async function POST(context: APIContext): Promise<Response> {
     // Bind EVERY membership — no single-tenant scoping (multi-vendor picker input).
     derived = sessionFromFederatedClaims(claims);
   } catch (err) {
+    // The error class only: a verifier message can quote token claims (the address).
     console.error("auth/verify: federated id_token verification failed; failing closed", {
-      error: err instanceof Error ? err.message : String(err),
+      errorClass: err instanceof Error ? err.name : typeof err,
     });
     return loginRedirect(context, { sent: true, email, error: "verify_failed", next });
   }
@@ -155,5 +158,6 @@ export async function POST(context: APIContext): Promise<Response> {
     nowSeconds,
   );
   setSessionCookie(context, id, DEFAULT_SESSION_TTL_SECONDS);
+  clearLoginEmailCookie(context);
   return context.redirect(next, 303);
 }

package/apps/storefront/src/pages/auth/login.astro

@@ -11,7 +11,12 @@
  * reach the browser. Inline style carries the per-request CSP nonce.
  */
 import { normalizeEmailHint } from "@/lib/access/privacy/emailHint";
-import { safeNext } from "@/lib/access/auth/route";
+import {
+  EMAIL_RE,
+  safeNext,
+  readLoginEmail,
+  setLoginEmailCookie,
+} from "@/lib/access/auth/route";
 // Self-hosted web fonts (audit finding 6) — same-origin @fontsource, replacing
 // the render-blocking fonts.googleapis.com stylesheet. Covers Plus Jakarta Sans,
 // Inter, and JetBrains Mono used by this page's inline styles.
@@ -21,8 +26,19 @@ export const prerender = false;
 
 const cspNonce = Astro.locals.cspNonce;
 const url = new URL(Astro.request.url);
+// The in-progress address rides the HttpOnly login-email cookie, never the URL. A
+// legacy `?email=` link is canonicalized: the address moves to the cookie and the
+// page reloads without it, so it doesn't linger in history or Referer headers.
+if (url.searchParams.has("email")) {
+  const legacyEmail = (url.searchParams.get("email") ?? "").trim().toLowerCase();
+  if (EMAIL_RE.test(legacyEmail)) setLoginEmailCookie(Astro, legacyEmail);
+  const canonical = new URLSearchParams(url.searchParams);
+  canonical.delete("email");
+  const qs = canonical.toString();
+  return Astro.redirect(`/auth/login${qs ? `?${qs}` : ""}`, 302);
+}
 const sent = url.searchParams.get("sent") === "1";
-const email = (url.searchParams.get("email") ?? "").trim();
+const email = readLoginEmail(Astro);
 const emailHint = normalizeEmailHint(url.searchParams.get("email_hint")) ?? "";
 const errorCode = url.searchParams.get("error");
 // Same open-redirect chokepoint the verify endpoint + login gate use — never a
@@ -56,7 +72,8 @@ const errorMessage = errorCode ? (ERROR_MESSAGES[errorCode] ?? "Something went w
 // A stale/failed code should drop back to the email step so a new code can be requested.
 const showCodeStep = sent && errorCode !== "expired" && errorCode !== "too_many_attempts";
 // Local-dev banner (statically dropped from prod). The message depends on the mode:
-// DEV_AUTH=1 → the console bypass is active (no email; code printed to the server console);
+// DEV_AUTH=1 → local codes are active (no email; the code goes to the owner-private
+// outbox file named in the dev-server log);
 // DEV_AUTH=0 → the REAL path is active (a code IS emailed by the configured tot20/qa, but
 // only to an address that already holds a role). Read the toggle so the banner never lies.
 const devMode = import.meta.env.DEV;
@@ -235,12 +252,13 @@ if (devMode) {
       </span>
       <p class="eyebrow">Token of Trust© · Regulated Storefront</p>
       {devMode && (devAuthOn ? (
-        <p class="dev"><strong>Local dev — console bypass</strong> (<code>DEV_AUTH=1</code>). No email is sent;
-        your sign-in code is printed to the <strong>server console</strong>. Set <code>DEV_AUTH=0</code> to use real emails.</p>
+        <p class="dev"><strong>Local dev — private outbox</strong> (<code>DEV_AUTH=1</code>). No email is sent;
+        your sign-in code is written to <code>apps/storefront/.dev-auth/outbox.txt</code> (readable only by you).
+        Set <code>DEV_AUTH=0</code> to use real emails.</p>
       ) : (
         <p class="dev"><strong>Local dev — live email</strong> (<code>DEV_AUTH=0</code>). A code is emailed by the
         configured tot20 (<code>TOT_CORE_URL</code>), but only to an address that already holds a role. Set
-        <code>DEV_AUTH=1</code> for offline console codes.</p>
+        <code>DEV_AUTH=1</code> for offline local codes.</p>
       ))}
       {errorMessage && <p class="err">{errorMessage}</p>}
 

package/apps/storefront/src/pages/auth/magic.astro

@@ -9,7 +9,7 @@
  * the token before the user ever clicked. So: NEVER exchange on GET. The token rides
  * in a hidden form field and leaves only via the POST.
  */
-import { normalizeEmailHint, redactEmailForHint } from "@/lib/access/privacy/emailHint";
+import { normalizeEmailHint } from "@/lib/access/privacy/emailHint";
 // Self-hosted web fonts (audit finding 6) — same-origin @fontsource, replacing
 // the render-blocking fonts.googleapis.com stylesheet. Covers Plus Jakarta Sans,
 // Inter, and JetBrains Mono used by this page's inline styles.
@@ -20,15 +20,12 @@ export const prerender = false;
 const cspNonce = Astro.locals.cspNonce;
 const url = new URL(Astro.request.url);
 const token = url.searchParams.get("token") ?? "";
-const legacyEmail = (url.searchParams.get("email") ?? "").trim(); // legacy display hint only
-const emailHint =
-  normalizeEmailHint(url.searchParams.get("email_hint")) ??
-  redactEmailForHint(legacyEmail) ??
-  "";
+// An `email` query parameter is never read, echoed or used to prefill: the address is
+// stripped from the URL and sign-in proceeds on the token alone.
+const emailHint = normalizeEmailHint(url.searchParams.get("email_hint")) ?? "";
 if (url.searchParams.has("email")) {
   const canonical = new URLSearchParams(url.searchParams);
   canonical.delete("email");
-  if (emailHint) canonical.set("email_hint", emailHint);
   return Astro.redirect(
     `/auth/magic${canonical.toString() ? `?${canonical.toString()}` : ""}`,
     302,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.8.0",
+  "version": "4.8.1",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",