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

package/apps/storefront/src/lib/dev/rendezvousBroker.ts

@@ -0,0 +1,241 @@
+/**
+ * The storefront (cockpit) half of the browserless CLI sign-in RENDEZVOUS — the
+ * server-to-server calls into the MCP's device-rendezvous endpoints, authenticated
+ * by the storefront's SIGNED CLIENT ASSERTION (private_key_jwt, RFC 7523), NOT the
+ * retired `x-mcp-service-secret`. The developer's cockpit (already authenticated as
+ * that developer) drives these; the MCP verifies the assertion against the
+ * storefront's published JWKS and admits only a client registered to broker CLI
+ * sign-in.
+ *
+ *   createRendezvous  → POST /oauth/device/rendezvous          (start; returns the
+ *                       NON-SECRET rendezvous_code rendered into `tot login --code`)
+ *   rendezvousStatus  → POST /oauth/device/rendezvous/status   (poll for a terminal
+ *                       attaching → { state, fingerprint })
+ *   approveRendezvous → POST /oauth/device/rendezvous/approve  (the human confirmed
+ *                       the fingerprint; carries the dev's fresh subject_token proof)
+ *   denyRendezvous    → POST /oauth/device/rendezvous/deny
+ *
+ * All four endpoints verify the SAME assertion audience — `<mcpBase>/oauth/device/rendezvous`
+ * (the MCP derives the expected audience from that fixed path, not the sub-path), so
+ * one minted assertion shape covers every call. SERVER-SIDE ONLY.
+ */
+import { readEnv } from "@/lib/env";
+import { mintMcpClientAssertion, McpClientAssertionError } from "@/lib/auth/mcpClientAssertion";
+
+const JWT_BEARER_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+/** The path whose audience the MCP binds EVERY rendezvous assertion to. */
+const RENDEZVOUS_AUDIENCE_PATH = "/oauth/device/rendezvous";
+
+/** Injectable transport so the broker calls unit-test with no network. */
+export interface HttpTransport {
+  post(
+    url: string,
+    headers: Record<string, string>,
+    body: unknown,
+  ): Promise<{ status: number; json(): Promise<unknown> }>;
+}
+
+// Bound every rendezvous call to the MCP. The MCP runs on AppRunner (scale-to-zero),
+// so the FIRST call after idle hits a cold instance that can take many seconds to
+// answer. Without a bound the storefront Worker's subrequest hangs and the browser's
+// POST to /api/dev/cli-signin-code eventually dies at the transport layer — the cockpit
+// shows the opaque catch-branch "Couldn't reach the sign-in service" and the button is
+// simply dead. Aborting at a fixed deadline turns that silent hang into a fast, RETRYABLE
+// 502 ("having a moment — try again"); the retry lands on a now-warm MCP and succeeds.
+const RENDEZVOUS_FETCH_TIMEOUT_MS = 12_000;
+
+export class FetchHttpTransport implements HttpTransport {
+  async post(url: string, headers: Record<string, string>, body: unknown) {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...headers },
+      body: JSON.stringify(body),
+      // A timeout/abort rejects the fetch → callRendezvous's catch → a 502 the cockpit
+      // renders as a retryable error, instead of a hung request the browser gives up on.
+      signal: AbortSignal.timeout(RENDEZVOUS_FETCH_TIMEOUT_MS),
+    });
+    return { status: res.status, json: () => res.json() };
+  }
+}
+
+export interface RendezvousDeps {
+  transport?: HttpTransport;
+  /** Override the assertion minter in tests (defaults to the real private-key signer). */
+  mintAssertion?: (audience: string) => Promise<string>;
+}
+
+/** A resolved MCP target: the origin to POST to + the assertion audience. */
+interface McpTarget {
+  origin: string;
+  audience: string;
+}
+
+/**
+ * Resolve the MCP origin from `MCP_BASE_URL` (its ORIGIN). MCP_BASE_URL is the MCP
+ * this storefront authenticates to with its private_key_jwt client assertion (kid
+ * storefront-mcp-client-1) — the SAME credential + tier the confidential broker
+ * client (canBrokerCliSignin) is registered under (e.g. mcp.qa for preview). NOT
+ * MCP_APP_BINDING_URL, which the retired shared-secret shim used and which may point
+ * at a different MCP tier. Returns null when unset/malformed (route maps that to 503).
+ */
+export async function resolveMcpTarget(): Promise<McpTarget | null> {
+  const baseUrl = await readEnv("MCP_BASE_URL");
+  if (!baseUrl) return null;
+  try {
+    const origin = new URL(baseUrl).origin;
+    return { origin, audience: `${origin}${RENDEZVOUS_AUDIENCE_PATH}` };
+  } catch {
+    return null;
+  }
+}
+
+async function callRendezvous(
+  target: McpTarget,
+  path: string,
+  extra: Record<string, unknown>,
+  deps: RendezvousDeps,
+): Promise<{ status: number; body: Record<string, unknown> }> {
+  const mint = deps.mintAssertion ?? ((aud: string) => mintMcpClientAssertion(aud));
+  const clientAssertion = await mint(target.audience);
+  const transport = deps.transport ?? new FetchHttpTransport();
+  const res = await transport.post(
+    `${target.origin}${path}`,
+    {},
+    {
+      client_assertion: clientAssertion,
+      client_assertion_type: JWT_BEARER_ASSERTION_TYPE,
+      ...extra,
+    },
+  );
+  let body: Record<string, unknown> = {};
+  try {
+    body = (await res.json()) as Record<string, unknown>;
+  } catch {
+    body = {};
+  }
+  return { status: res.status, body };
+}
+
+export type RendezvousCreateResult =
+  | { ok: true; rendezvousCode: string; expiresIn: number | null }
+  | { ok: false; status: 502 | 503; reason: string };
+
+/**
+ * Start a rendezvous for the signed-in developer's OWN email (+ their vendor tenant).
+ * Fail-closed mapping mirrors the retired mint: an unconfigured seam or a 401/403
+ * (assertion rejected / client not entitled to broker) is a 503 ("not wired up on
+ * this environment"); any other fault is a 502.
+ */
+export async function createRendezvous(
+  email: string,
+  tenant: string | null,
+  deps: RendezvousDeps = {},
+): Promise<RendezvousCreateResult> {
+  const target = await resolveMcpTarget();
+  if (!target) return { ok: false, status: 503, reason: "not-configured" };
+  let res: { status: number; body: Record<string, unknown> };
+  try {
+    res = await callRendezvous(
+      target,
+      RENDEZVOUS_AUDIENCE_PATH,
+      { email: email.toLowerCase(), ...(tenant ? { tenant: tenant.toLowerCase() } : {}) },
+      deps,
+    );
+  } catch (cause) {
+    if (cause instanceof McpClientAssertionError) return { ok: false, status: 503, reason: "assertion-unconfigured" };
+    return { ok: false, status: 502, reason: "mcp request failed: " + (cause instanceof Error ? cause.message : String(cause)) };
+  }
+  if (res.status < 200 || res.status >= 300) {
+    // 401 invalid_client / 403 unauthorized_client|not_entitled = "not wired up /
+    // not entitled on this environment" → 503; a fault is 502.
+    const notConfigured = res.status === 401 || res.status === 403;
+    return { ok: false, status: notConfigured ? 503 : 502, reason: `rendezvous create returned ${res.status}` };
+  }
+  const rendezvousCode = typeof res.body.rendezvous_code === "string" ? res.body.rendezvous_code : "";
+  if (!rendezvousCode) return { ok: false, status: 502, reason: "rendezvous create returned no code" };
+  return {
+    ok: true,
+    rendezvousCode,
+    expiresIn: typeof res.body.expires_in === "number" ? res.body.expires_in : null,
+  };
+}
+
+export type RendezvousState = "pending" | "attached" | "approved" | "denied" | "expired";
+export type RendezvousStatusResult =
+  | { ok: true; state: RendezvousState; fingerprint: string | null }
+  | { ok: false; status: 502 | 503; reason: string };
+
+/** Poll for a terminal attaching. `fingerprint` is present once state is `attached`. */
+export async function rendezvousStatus(
+  rendezvousCode: string,
+  deps: RendezvousDeps = {},
+): Promise<RendezvousStatusResult> {
+  const target = await resolveMcpTarget();
+  if (!target) return { ok: false, status: 503, reason: "not-configured" };
+  let res: { status: number; body: Record<string, unknown> };
+  try {
+    res = await callRendezvous(target, `${RENDEZVOUS_AUDIENCE_PATH}/status`, { rendezvous_code: rendezvousCode }, deps);
+  } catch (cause) {
+    if (cause instanceof McpClientAssertionError) return { ok: false, status: 503, reason: "assertion-unconfigured" };
+    return { ok: false, status: 502, reason: "mcp request failed" };
+  }
+  if (res.status < 200 || res.status >= 300) {
+    const notConfigured = res.status === 401 || res.status === 403;
+    return { ok: false, status: notConfigured ? 503 : 502, reason: `rendezvous status returned ${res.status}` };
+  }
+  const state = String(res.body.state ?? "expired") as RendezvousState;
+  return { ok: true, state, fingerprint: typeof res.body.fingerprint === "string" ? res.body.fingerprint : null };
+}
+
+export type RendezvousDecisionResult =
+  | { ok: true }
+  | { ok: false; status: 403 | 409 | 502 | 503; reason: string };
+
+/**
+ * Approve the attached terminal. Carries the developer's fresh `subject_token`
+ * (Part A / Finding 3) so the MCP can bind the approval to the dev's own identity —
+ * a 403 `approver_mismatch` means the proof didn't match the rendezvous developer;
+ * a 409 `not_approvable` means the fingerprint didn't match a waiting terminal.
+ */
+export async function approveRendezvous(
+  rendezvousCode: string,
+  fingerprint: string,
+  subjectToken: string,
+  deps: RendezvousDeps = {},
+): Promise<RendezvousDecisionResult> {
+  const target = await resolveMcpTarget();
+  if (!target) return { ok: false, status: 503, reason: "not-configured" };
+  let res: { status: number; body: Record<string, unknown> };
+  try {
+    res = await callRendezvous(
+      target,
+      `${RENDEZVOUS_AUDIENCE_PATH}/approve`,
+      { rendezvous_code: rendezvousCode, fingerprint, subject_token: subjectToken },
+      deps,
+    );
+  } catch (cause) {
+    if (cause instanceof McpClientAssertionError) return { ok: false, status: 503, reason: "assertion-unconfigured" };
+    return { ok: false, status: 502, reason: "mcp request failed" };
+  }
+  if (res.status >= 200 && res.status < 300) return { ok: true };
+  if (res.status === 403) return { ok: false, status: 403, reason: String(res.body.error ?? "approver_mismatch") };
+  if (res.status === 409) return { ok: false, status: 409, reason: String(res.body.error ?? "not_approvable") };
+  const notConfigured = res.status === 401;
+  return { ok: false, status: notConfigured ? 503 : 502, reason: `rendezvous approve returned ${res.status}` };
+}
+
+/** Reject the attached terminal (the human said "not me"). */
+export async function denyRendezvous(
+  rendezvousCode: string,
+  deps: RendezvousDeps = {},
+): Promise<RendezvousDecisionResult> {
+  const target = await resolveMcpTarget();
+  if (!target) return { ok: false, status: 503, reason: "not-configured" };
+  try {
+    const res = await callRendezvous(target, `${RENDEZVOUS_AUDIENCE_PATH}/deny`, { rendezvous_code: rendezvousCode }, deps);
+    if (res.status >= 200 && res.status < 300) return { ok: true };
+    return { ok: false, status: res.status === 401 ? 503 : 502, reason: `rendezvous deny returned ${res.status}` };
+  } catch {
+    return { ok: false, status: 502, reason: "mcp request failed" };
+  }
+}

package/apps/storefront/src/lib/dev/subjectReissue.ts

@@ -0,0 +1,67 @@
+/**
+ * Re-issue a FRESH tot20-signed id_token for an already-signed-in developer — the
+ * `subject_token` proof the cockpit sends when APPROVING a browserless CLI sign-in
+ * rendezvous (Part A / Finding 3).
+ *
+ * WHY re-issue: the storefront verifies tot20's id_token OFFLINE at sign-in and then
+ * DISCARDS it (only derived claims live in the KV session), and it's short-lived —
+ * long expired by the time the developer approves. So at approve time we MINT a fresh
+ * single-use sign-in token for the session's VERIFIED email and exchange it for a
+ * freshly-signed id_token.
+ *
+ * WHY it closes Finding 3: the mint + exchange authenticate with the storefront's tot20
+ * CORE machine credential (TOT_API_KEY/TOT_SECRET_KEY) — a DIFFERENT secret from the MCP
+ * broker key. A compromised broker key alone cannot produce this proof.
+ *
+ * WHY mint, NOT developerInvites: tot20's access-code `/mint` is NOT operator-grant-gated
+ * per tenant, whereas developerInvites is (it 403s `notGranted` for a non-staff developer
+ * re-attesting themselves on a tenant the storefront doesn't operate). `/mint` binds the
+ * token to (email, aud = the storefront's OWN appDomain) — which equals the storefront's
+ * MCP client_id, exactly what the MCP binds the subject_token audience to. This is the
+ * same non-gated mint the MCP itself uses to power rendezvous creation.
+ */
+import { getAccessClient } from "@/lib/auth/route";
+import type { TotAccessClient } from "@/lib/auth/totAccessClient";
+
+/** Short — the proof is minted and used immediately at approve time. */
+const SUBJECT_TOKEN_TTL_SECONDS = 120;
+
+export type SubjectReissueResult =
+  | { ok: true; idToken: string }
+  | { ok: false; reason: string };
+
+export interface SubjectReissueDeps {
+  accessClient?: TotAccessClient | null;
+}
+
+/**
+ * Produce a fresh subject id_token for `email`. Fail-closed: any gap (unconfigured seam,
+ * mint refused, exchange failed / step-up required) returns a typed `{ ok:false, reason }`
+ * and NEVER throws — the caller maps that to a refusal to approve. The id_token is returned
+ * only to the server; it is never logged.
+ */
+export async function reissueSubjectToken(
+  email: string,
+  deps: SubjectReissueDeps = {},
+): Promise<SubjectReissueResult> {
+  if (!email) return { ok: false, reason: "missing-identity" };
+
+  const accessClient =
+    deps.accessClient !== undefined ? deps.accessClient : await getAccessClient();
+  if (!accessClient) return { ok: false, reason: "access-client-unconfigured" };
+
+  // Mint a fresh single-use sign-in token for the developer's OWN email (bound to the
+  // storefront's appDomain as audience — not grant-gated per tenant).
+  const minted = await accessClient.mintSignInToken(email, SUBJECT_TOKEN_TTL_SECONDS);
+  if (!minted.ok || !minted.token) {
+    return { ok: false, reason: minted.ok ? "no-signin-token" : `mint-${minted.reason}` };
+  }
+
+  // Exchange (single-use; tot20 burns it) → a signed federated id_token whose aud is the
+  // storefront appDomain and whose email is this developer.
+  const exchanged = await accessClient.exchangeSignInToken(minted.token);
+  if (!exchanged.ok || !exchanged.id_token) {
+    return { ok: false, reason: exchanged.ok ? "no-id-token" : `exchange-${exchanged.reason}` };
+  }
+  return { ok: true, idToken: exchanged.id_token };
+}

package/apps/storefront/src/lib/email/magicLinkInviteEmail.ts

@@ -40,20 +40,20 @@ export function renderMagicLinkInviteEmail(input: MagicLinkInviteEmailInput): {
   const html = `<!doctype html>
 <html lang="en">
   <head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /></head>
-  <body style="margin:0;padding:0;background:#f5f4f0;">
-    <div style="max-width:520px;margin:0 auto;padding:32px 20px;font:16px/1.6 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#1c1c1c;">
-      <div style="font:600 12px/1 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.12em;text-transform:uppercase;color:#0f7b6c;margin:0 0 24px;">
+  <body style="margin:0;padding:0;background:#f7f9fc;">
+    <div style="max-width:520px;margin:0 auto;padding:32px 20px;font:16px/1.6 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#33415b;">
+      <div style="font:600 12px/1 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.12em;text-transform:uppercase;color:#0b7a6d;margin:0 0 24px;">
         Token of Trust&#169; &middot; ${esc(store)}
       </div>
-      <h1 style="font-size:22px;line-height:1.3;letter-spacing:-.01em;margin:0 0 12px;color:#0b1f3a;">You've been invited</h1>
-      <p style="margin:0 0 8px;color:#3a3a3a;">You've been given developer access to <strong>${esc(store)}</strong>. Click below to sign in — no password needed.</p>
-      ${note ? `<div style="margin:16px 0;padding:12px 14px;background:#eef4ff;border:1px solid #c3d4f5;border-radius:8px;color:#234;font-size:14px;"><strong>Note from your inviter:</strong><br>${note}</div>` : ""}
+      <h1 style="font-size:22px;line-height:1.3;letter-spacing:-.02em;margin:0 0 12px;color:#0a2540;">You've been invited</h1>
+      <p style="margin:0 0 8px;color:#33415b;">You've been given developer access to <strong>${esc(store)}</strong>. Click below to sign in — no password needed.</p>
+      ${note ? `<div style="margin:16px 0;padding:12px 14px;background:#e7f6f4;border:1px solid #b8e6df;border-radius:10px;color:#0a2540;font-size:14px;"><strong>Note from your inviter:</strong><br>${note}</div>` : ""}
       <div style="margin:28px 0;">
-        <a href="${url}" style="display:inline-block;background:#0f7b6c;color:#ffffff;text-decoration:none;font-weight:600;font-size:16px;padding:14px 28px;border-radius:9px;">Sign in to ${esc(store)}</a>
+        <a href="${url}" style="display:inline-block;background:#0b7a6d;color:#ffffff;text-decoration:none;font-weight:600;font-size:16px;padding:14px 28px;border-radius:999px;">Sign in to ${esc(store)}</a>
       </div>
-      <p style="margin:0 0 4px;font-size:13px;color:#6a6a6a;">Or paste this link into your browser:</p>
-      <p style="margin:0 0 24px;font-size:13px;word-break:break-all;"><a href="${url}" style="color:#0f7b6c;">${url}</a></p>
-      <p style="margin:0;font-size:12px;color:#9a9a9a;border-top:1px solid #e6e4de;padding-top:16px;">This is a single-use sign-in link. If you didn't expect this invitation, you can ignore this email.</p>
+      <p style="margin:0 0 4px;font-size:13px;color:#55637a;">Or paste this link into your browser:</p>
+      <p style="margin:0 0 24px;font-size:13px;word-break:break-all;"><a href="${url}" style="color:#0b7a6d;">${url}</a></p>
+      <p style="margin:0;font-size:12px;color:#8593a8;border-top:1px solid #e3e8ef;padding-top:16px;">This is a single-use sign-in link. If you didn't expect this invitation, you can ignore this email.</p>
     </div>
   </body>
 </html>`;

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

@@ -58,3 +58,15 @@ export async function readR2(binding: string): Promise<R2Bucket | undefined> {
   const w = await getWorkerEnv();
   return (w?.[binding] as R2Bucket | undefined) ?? undefined;
 }
+
+/**
+ * Cloudflare Queue producer binding (e.g. WEBHOOK_DELIVERY_QUEUE), if present.
+ * Untyped (`unknown`) deliberately — callers cast to their own minimal
+ * queue-shape interface (see `webhooks/cloudflareQueueDispatcher.ts`'s
+ * `CloudflareQueueSender`) rather than this module taking a types dep on a
+ * specific binding's shape.
+ */
+export async function readQueue(binding: string): Promise<unknown | undefined> {
+  const w = await getWorkerEnv();
+  return w?.[binding] ?? undefined;
+}

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

@@ -9,8 +9,13 @@ export function organizationLd(tenant: TenantConfig, base: string) {
   // Logo sourced from the migrated brand assets (og image / logo), so the
   // Organization schema reflects the real merchant brand, not a generic favicon.
   const brand = tenant.theme_tokens?.brand;
-  const logo =
-    brand?.ogImage ?? brand?.logoLight ?? new URL("/favicon.svg", base + "/").toString();
+  // Absolutize the logo: schema.org wants an absolute URL, and tenant brand
+  // assets are stored as site-relative paths (e.g. /tenants/<id>/brand/og.svg).
+  // new URL() leaves an already-absolute value untouched.
+  const logo = new URL(
+    brand?.ogImage ?? brand?.logoLight ?? "/favicon.svg",
+    base + "/",
+  ).toString();
   return {
     "@context": "https://schema.org",
     "@type": "Organization",
@@ -97,10 +102,11 @@ export function productLd(
     url,
   }));
 
-  const ratingMf = p.metafields.find(
-    (m) => m.namespace === "reviews" && m.key === "rating",
-  );
-
+  // NO aggregateRating/review here — those are emitted ONLY from real sourced
+  // numbers by reviewLd(), which callers merge over this Product graph. Emitting
+  // a rating from a bare `reviews.rating` metafield (with a placeholder count)
+  // fabricates rich-result markup for stores with no real reviews (e.g. PVC),
+  // which violates the review-markup policy (docs/architecture/review-markup-policy.md).
   return {
     "@context": "https://schema.org",
     "@type": "Product",
@@ -121,17 +127,6 @@ export function productLd(
         : "https://schema.org/OutOfStock",
       offers,
     },
-    ...(ratingMf
-      ? {
-          aggregateRating: {
-            "@type": "AggregateRating",
-            ratingValue: ratingMf.value,
-            bestRating: "5",
-            // ASSUMPTION: review count placeholder; real capture is Phase 2.
-            ratingCount: 24,
-          },
-        }
-      : {}),
   };
 }
 

package/apps/storefront/src/lib/membership/eligibility.ts

@@ -0,0 +1,37 @@
+/**
+ * Shopper membership eligibility — the request-scoped seam that resolves whether
+ * the current shopper is a member, and which tier (F10).
+ *
+ * Phase 1 storefronts have NO shopper-login/account source (member accounts are
+ * a Phase-2 managed-checkout capability), so this resolves anonymous
+ * (`{ isMember: false }`) by default. The pricing engine in
+ * `@tot/public-runtime` is real and unit-tested regardless; member pricing only
+ * RENDERS once a real eligibility signal flows through here.
+ *
+ * Production wires the signal from the resolved account claim (e.g. a
+ * member-tier cookie/JWT set by the Phase-2 login), so the whole storefront gets
+ * member pricing by threading one function — no per-page auth logic.
+ */
+import type { MemberContext } from "@tot/public-runtime";
+import { ANONYMOUS_MEMBER } from "@tot/public-runtime";
+
+/**
+ * The minimal membership signal a request carries. Phase 1 never populates it;
+ * production derives it from the shopper's resolved account (a member-tier
+ * claim). Kept tiny + framework-free so it is trivially testable.
+ */
+export interface MembershipSignal {
+  /** The shopper's membership tier id, if they are a signed-in member. */
+  memberTierId?: string | null;
+}
+
+/**
+ * Resolve the shopper's {@link MemberContext} from an optional membership signal.
+ * No signal (Phase 1, or an anonymous shopper) → non-member.
+ */
+export function resolveMemberContext(signal?: MembershipSignal | null): MemberContext {
+  if (signal?.memberTierId) {
+    return { isMember: true, tierId: signal.memberTierId };
+  }
+  return ANONYMOUS_MEMBER;
+}