@tokenoftrust/storefront-runner 4.11.8 → 4.11.10

package/apps/storefront/public/js/dashboard-contact-capture.js

@@ -0,0 +1,52 @@
+/**
+ * Client behavior for the staff "Customer contact access" card on /dashboard/<appDomain>/team:
+ * a ToT staff member records the owner's out-of-band consent, which grants that staff member
+ * customer contact access through POST /api/grants/contact-capture.
+ *
+ * Served as a STATIC same-origin file (public/), same CSP rationale as dashboard-team.js. Only
+ * wires up when the card is present (ToT staff viewer only). The server decides everything; this
+ * file only collects the channel, ticket and expiry and shows the answer.
+ */
+(function () {
+  const $ = (id) => document.getElementById(id);
+  const card = $("contactCapture");
+  if (!card) return;
+  const tenant = card.dataset.tenant;
+
+  function showMsg(kind, text) {
+    const el = $("captureMsg");
+    el.className = "msg " + kind;
+    el.textContent = text;
+  }
+
+  async function capture() {
+    const channel = $("captureChannel").value;
+    const ticket = $("captureTicket").value.trim();
+    if (!ticket) { showMsg("err", "Enter the support ticket reference."); return; }
+    const ttlMs = Number($("captureTtl").value);
+    const btn = $("captureBtn");
+    btn.disabled = true;
+    showMsg("", "Recording…");
+    try {
+      const res = await fetch("/api/grants/contact-capture", {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify({ tenant, channel, ticket, ttlMs }),
+      });
+      const data = await res.json().catch(() => ({}));
+      if (res.ok) {
+        const until = data.expiresAt ? new Date(data.expiresAt).toLocaleString() : "";
+        showMsg("ok", "Recorded. You can read customer contact details on this store" + (until ? " until " + until : "") + ". The owner has been notified.");
+        $("captureTicket").value = "";
+      } else {
+        showMsg("err", data.message || data.error || ("Couldn't record consent (HTTP " + res.status + ")."));
+      }
+    } catch (e) {
+      showMsg("err", "Couldn't record consent. Try again.");
+    } finally {
+      btn.disabled = false;
+    }
+  }
+
+  $("captureBtn").addEventListener("click", capture);
+})();

package/apps/storefront/public/js/dashboard-delegate.js

@@ -1,17 +1,44 @@
 /**
- * Client behavior for the "Delegate ship-on-behalf" section of
- * /dashboard/<appDomain>/team (handoff 2026-09-03-storefront-owner-grants-a-developer).
+ * Client behavior for the owner's "Grant access" section of /dashboard/<appDomain>/team:
+ * ship-on-behalf or customer contact access, granted to a person by email, time-limited and
+ * revocable, through POST/GET/DELETE /api/grants/principal.
  *
  * Served as a STATIC same-origin file (public/), same CSP rationale as
- * dashboard-team.js — see that file's header. Only wires up when the delegation
- * section is present (real member only; absent for a staff-viewed tenant).
+ * dashboard-team.js — see that file's header. Only wires up when the section is present
+ * (store owner only).
  */
 (function () {
   const $ = (id) => document.getElementById(id);
   const body = $("delegations");
-  if (!body) return; // section not rendered (staff view) — nothing to wire up
+  if (!body) return; // section not rendered (not the owner) — nothing to wire up
   const tenant = body.dataset.tenant;
 
+  const DAY = 24 * 60 * 60 * 1000;
+  /** Expiry choices per capability; the server enforces the same bounds. */
+  const TTL_CHOICES = {
+    "ship-on-behalf": [[7 * DAY, "In 7 days"], [30 * DAY, "In 30 days", true], [90 * DAY, "In 90 days"]],
+    "customer-contact-read": [[1 * DAY, "In 1 day", true], [3 * DAY, "In 3 days"], [7 * DAY, "In 7 days"]],
+  };
+  const LABELS = { "ship-on-behalf": "Ship on behalf", "customer-contact-read": "Customer contacts" };
+
+  function capability() {
+    const el = $("delegateCapability");
+    return el && TTL_CHOICES[el.value] ? el.value : "ship-on-behalf";
+  }
+
+  function fillTtl() {
+    const ttlEl = $("delegateTtl");
+    if (!ttlEl) return;
+    ttlEl.replaceChildren();
+    for (const [ms, label, selected] of TTL_CHOICES[capability()]) {
+      const opt = document.createElement("option");
+      opt.value = String(ms);
+      opt.textContent = label;
+      if (selected) opt.selected = true;
+      ttlEl.appendChild(opt);
+    }
+  }
+
   function showMsg(kind, text) {
     const el = $("delegateMsg");
     el.className = "msg " + kind;
@@ -23,8 +50,8 @@
     if (!grants || !grants.length) {
       const tr = document.createElement("tr");
       const td = document.createElement("td");
-      td.colSpan = 3; td.className = "muted";
-      td.textContent = "No active delegations.";
+      td.colSpan = 4; td.className = "muted";
+      td.textContent = "No active grants.";
       tr.appendChild(td); body.appendChild(tr);
       return;
     }
@@ -32,6 +59,8 @@
       const tr = document.createElement("tr");
       const dev = document.createElement("td");
       dev.textContent = (g.principal && g.principal.email) || "";
+      const cap = document.createElement("td");
+      cap.textContent = LABELS[g.capability] || g.capability || "";
       const exp = document.createElement("td");
       exp.textContent = g.expiresAt ? new Date(g.expiresAt).toLocaleString() : "";
       const act = document.createElement("td");
@@ -40,9 +69,9 @@
       revokeBtn.type = "button";
       revokeBtn.className = "rowbtn";
       revokeBtn.textContent = "Revoke";
-      revokeBtn.addEventListener("click", () => revoke(g.ref, dev.textContent, revokeBtn));
+      revokeBtn.addEventListener("click", () => revoke(g.ref, dev.textContent, cap.textContent, revokeBtn));
       act.appendChild(revokeBtn);
-      tr.appendChild(dev); tr.appendChild(exp); tr.appendChild(act);
+      tr.appendChild(dev); tr.appendChild(cap); tr.appendChild(exp); tr.appendChild(act);
       body.appendChild(tr);
     }
   }
@@ -51,7 +80,7 @@
     body.replaceChildren();
     const tr = document.createElement("tr");
     const td = document.createElement("td");
-    td.colSpan = 3; td.className = "muted";
+    td.colSpan = 4; td.className = "muted";
     td.textContent = msg;
     tr.appendChild(td); body.appendChild(tr);
   }
@@ -63,15 +92,15 @@
       });
       const data = await res.json().catch(() => ({}));
       if (res.ok) renderRows(data.grants);
-      else renderError(data.error || ("Couldn't load delegations (HTTP " + res.status + ")."));
+      else renderError("Couldn't load grants (HTTP " + res.status + "). Reload to try again.");
     } catch (e) {
-      renderError("Couldn't load delegations: " + (e && e.message ? e.message : e));
+      renderError("Couldn't load grants. Reload to try again.");
     }
   }
 
-  async function revoke(ref, email, btn) {
+  async function revoke(ref, email, label, btn) {
     if (!ref) return;
-    if (!confirm("Revoke " + (email || "this developer") + "'s ship-on-behalf access?")) return;
+    if (!confirm("Revoke " + (email || "this person") + "'s " + (label || "access") + " access?")) return;
     if (btn) btn.disabled = true;
     try {
       const res = await fetch("/api/grants/principal", {
@@ -95,9 +124,10 @@
 
   async function grant() {
     const email = $("delegateEmail").value.trim();
-    if (!email) { showMsg("err", "Enter a developer email."); return; }
+    if (!email) { showMsg("err", "Enter an email."); return; }
+    const cap = capability();
     const ttlEl = $("delegateTtl");
-    const ttlMs = ttlEl ? Number(ttlEl.value) : 2592000000;
+    const ttlMs = ttlEl ? Number(ttlEl.value) : TTL_CHOICES[cap][0][0];
     const btn = $("delegateBtn");
     btn.disabled = true;
     showMsg("", "Granting…");
@@ -105,15 +135,15 @@
       const res = await fetch("/api/grants/principal", {
         method: "POST",
         headers: { "content-type": "application/json", accept: "application/json" },
-        body: JSON.stringify({ tenant, email, ttlMs }),
+        body: JSON.stringify({ tenant, email, capability: cap, ttlMs }),
       });
       const data = await res.json().catch(() => ({}));
       if (res.ok) {
-        showMsg("ok", "Granted ship-on-behalf to " + email + ".");
+        showMsg("ok", "Granted " + LABELS[cap].toLowerCase() + " access to " + email + ".");
         $("delegateEmail").value = "";
         loadDelegations();
       } else {
-        showMsg("err", data.error || ("Grant failed (HTTP " + res.status + ")."));
+        showMsg("err", data.message || data.error || ("Grant failed (HTTP " + res.status + ")."));
       }
     } catch (e) {
       showMsg("err", "Grant failed: " + (e && e.message ? e.message : e));
@@ -128,5 +158,8 @@
     delegateBtn.addEventListener("click", grant);
     emailInput.addEventListener("keydown", (e) => { if (e.key === "Enter") grant(); });
   }
+  const capEl = $("delegateCapability");
+  if (capEl) capEl.addEventListener("change", fillTtl);
+  fillTtl();
   loadDelegations();
 })();

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

@@ -1,5 +1,5 @@
 /**
- * The "Delegate ship-on-behalf" gate on /dashboard/<appDomain>/team, as a PURE
+ * The owner "Grant access" gate on /dashboard/<appDomain>/team, as a PURE
  * decision — who sees the control, and what everyone else is told instead.
  *
  * The gate itself is unchanged and stays OWNER-ONLY: `/api/grants/principal`

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

@@ -1,7 +1,7 @@
 /**
  * PrincipalGrantClient — the storefront's seam to tot20's principal-keyed grant
- * writer (ADR-0003, #8425): a scoped, revocable `ship-on-behalf` capability
- * issued to a HUMAN (by email), never a team role.
+ * writer (ADR-0003, #8425): a scoped, revocable, expiring capability (`ship-on-behalf`
+ * or `customer-contact-read`) issued to a HUMAN (by email), never a team role.
  *
  * This is the AUTHORIZATION (L2) surface — see docs/architecture/grant-surfaces.md
  * ("Let an operator app act on a store" row's owner-consent shape, generalized to
@@ -20,9 +20,13 @@
  * human/service principal). `ref` is opaque (never the raw email) and is what
  * `revoke`/list rows key on.
  *
- * GRANTOR MODE: OWNER-BROKERED SESSION. Merchants hold no ToT API keys — they sign
- * into storefront's dashboard. tot20's `resolveGrantorContext` accepts three grantor
- * provenances, and this client drives exactly one of them:
+ * GRANTOR MODES: BROKERED SESSION. Merchants hold no ToT API keys — they sign into
+ * storefront's dashboard. tot20's `resolveGrantorContext` accepts three grantor
+ * provenances, and this client drives the two brokered ones. The assertion's SUBJECT
+ * decides which: the store owner gives `owner-brokered-session` (/api/grants/principal);
+ * storefront-line ToT staff give `staff-consent-capture`, which tot20 audits with a
+ * `staff:<hash>` actor and notifies the owner of (/api/grants/contact-capture). Other
+ * staff roles are refused `staffScopeInsufficient`, and tot20 never lets staff list.
  *
  *   - Naming a `tenant` on the request switches tot20 OFF the owner-key path (where
  *     the grantor is the CALLER's own store — i.e. storefront itself) and onto the
@@ -30,9 +34,10 @@
  *   - The brokered path requires a VERIFIED broker assertion whose signed `tenant`
  *     claim matches the request's tenant EXACTLY (an unnormalized string compare, so
  *     both are built from the same value here) and whose SUBJECT is the signed-in
- *     owner. tot20 then resolves ownership from its OWN state (`ownsTenant` →
- *     `AccessCodeService.resolveEligibility`, strictly `capability === 'owner'`) —
- *     the assertion proves WHO the subject is, never WHAT they own.
+ *     person. tot20 then resolves ownership (`ownsTenant` →
+ *     `AccessCodeService.resolveEligibility`, strictly `capability === 'owner'`) or
+ *     staff role from its OWN state — the assertion proves WHO the subject is, never
+ *     WHAT they own or which role they hold.
  *   - Transport auth stays storefront's OWN operator credential (`TOT_API_KEY` /
  *     `TOT_SECRET_KEY`; the route is `requireSecretKey`), the same credential every
  *     sibling client here presents. It authenticates the BROKER; it does not choose
@@ -84,9 +89,102 @@ export interface UserPrincipal {
   email: string;
 }
 
-/** `ship-on-behalf` today; kept as a string so a future tot20 vocabulary addition
- * (see `grantCapabilities.CAPABILITIES` in tot20) doesn't need a type change here. */
-export type PrincipalGrantCapability = "ship-on-behalf" | (string & {});
+/** Kept as a string so a future tot20 vocabulary addition (see
+ * `grantCapabilities.CAPABILITIES` in tot20) doesn't need a type change here. */
+export type PrincipalGrantCapability = "ship-on-behalf" | "customer-contact-read" | (string & {});
+
+// --- Route guards shared by the grant routes ---------------------------------
+
+/** The capabilities storefront's grant routes may issue. Anything else is refused before tot20. */
+export const GRANTABLE_CAPABILITIES = ["ship-on-behalf", "customer-contact-read"] as const;
+export type GrantableCapability = (typeof GRANTABLE_CAPABILITIES)[number];
+
+export function isGrantableCapability(value: unknown): value is GrantableCapability {
+  return typeof value === "string" && (GRANTABLE_CAPABILITIES as readonly string[]).includes(value);
+}
+
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+
+/**
+ * Expiry bounds per capability. Customer contact data is order and customer PII, so its grants are
+ * short (at most 7 days); ship-on-behalf keeps its longer delegation window.
+ */
+export const GRANT_TTL_BOUNDS: Record<GrantableCapability, { minMs: number; maxMs: number; label: string }> = {
+  "ship-on-behalf": { minMs: HOUR_MS, maxMs: 90 * DAY_MS, label: "between 1 hour and 90 days" },
+  "customer-contact-read": { minMs: HOUR_MS, maxMs: 7 * DAY_MS, label: "between 1 hour and 7 days" },
+};
+
+/**
+ * The expiry for a grant request: `expiresAt` (epoch-ms) wins, else `ttlMs` from now. Refused when
+ * absent, not finite, or outside the capability's bounds.
+ */
+export function grantExpiry(
+  capability: GrantableCapability,
+  body: { expiresAt?: unknown; ttlMs?: unknown },
+  now: number,
+): { ok: true; expiresAt: number } | { ok: false; error: string } {
+  let expiresAt: number;
+  if (typeof body.expiresAt === "number" && Number.isFinite(body.expiresAt)) expiresAt = body.expiresAt;
+  else if (typeof body.ttlMs === "number" && Number.isFinite(body.ttlMs)) expiresAt = now + body.ttlMs;
+  else return { ok: false, error: "expiresAt (epoch-ms) or ttlMs is required — a human grant is never standing authority" };
+  const { minMs, maxMs, label } = GRANT_TTL_BOUNDS[capability];
+  const ttl = expiresAt - now;
+  if (ttl < minMs || ttl > maxMs) return { ok: false, error: `expiry must be ${label} from now` };
+  return { ok: true, expiresAt };
+}
+
+/**
+ * Cross-site request refusal for the cookie-authenticated grant mutations. The session cookie is
+ * SameSite=Lax and the admin entry checks do not look at Origin, so a sibling host under the shared
+ * store domain could otherwise post here. Requires `Origin` equal to the request URL's origin and,
+ * for a body-carrying method, a JSON content type. Returns a 403 response to send, or null to proceed.
+ */
+export function crossOriginRefusal(request: Request): Response | null {
+  const origin = request.headers.get("origin");
+  let expected: string;
+  try {
+    expected = new URL(request.url).origin;
+  } catch {
+    expected = "";
+  }
+  const sameOrigin = !!origin && !!expected && origin === expected;
+  const contentType = (request.headers.get("content-type") ?? "").toLowerCase();
+  const jsonBody = request.method === "GET" || request.method === "HEAD" || contentType.startsWith("application/json");
+  if (sameOrigin && jsonBody) return null;
+  return new Response(JSON.stringify({ error: "cross-origin" }), {
+    status: 403,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+/** How a staff member heard the owner consent. A fixed list, so no free text reaches a grant. */
+export const CONSENT_CHANNELS = ["phone", "email", "chat", "meeting"] as const;
+export type ConsentChannel = (typeof CONSENT_CHANNELS)[number];
+
+/** The support-ticket reference shape the contact support-read already accepts. */
+export const CONSENT_TICKET_REF = /^[A-Za-z0-9._-]{1,64}$/;
+
+/**
+ * The grant purpose recorded for a staff consent capture, from validated fields only, so a purpose
+ * can never carry customer detail.
+ */
+export function consentCapturePurpose(
+  body: { channel?: unknown; ticket?: unknown },
+): { ok: true; purpose: string; channel: ConsentChannel; ticket: string } | { ok: false; error: string } {
+  const channel = body.channel;
+  if (typeof channel !== "string" || !(CONSENT_CHANNELS as readonly string[]).includes(channel)) {
+    return { ok: false, error: `channel must be one of ${CONSENT_CHANNELS.join(", ")}` };
+  }
+  const ticket = typeof body.ticket === "string" ? body.ticket.trim() : "";
+  if (!CONSENT_TICKET_REF.test(ticket)) return { ok: false, error: "ticket must be a support ticket reference" };
+  return {
+    ok: true,
+    purpose: `staff-consent-capture channel=${channel} ticket=${ticket}`,
+    channel: channel as ConsentChannel,
+    ticket,
+  };
+}
 
 export interface CreatePrincipalGrantInput {
   /** Target tenant this grant is issued on (session-derived; never trust a body field). */
@@ -121,6 +219,7 @@ export type PrincipalGrantFailureReason =
   | "assertionTenantMismatch" // 422 — assertion names a different tenant than the request
   | "tenantNotRegistered" // 422 — the named appDomain is not a ToT client
   | "subjectNotTenantOwner" // 403 — the signed-in subject does not OWN this tenant
+  | "staffScopeInsufficient" // 403 — a staff subject whose role may not capture consent here
   | "brokerNotConfigured" // LOCAL 503 — this deploy holds no broker signing key
   | "error"; // transport / unexpected upstream fault
 
@@ -431,11 +530,11 @@ function reasonFor(code: string | undefined, status: number): PrincipalGrantFail
     case "operatorGrants:tenantNotRegistered":
       return "tenantNotRegistered";
     case "operatorGrants:subjectNotTenantOwner":
-    // Storefront never drives the staff-consent-capture branch, so a staff-scope
-    // refusal here can only mean the subject reached tot20 as staff rather than as
-    // the owner — the same operator-facing story as "you don't own this store".
-    case "operatorGrants:staffScopeInsufficient":
       return "subjectNotTenantOwner";
+    // The staff-consent-capture branch (POST /api/grants/contact-capture): tot20 decided this
+    // staff role may not capture consent on the tenant.
+    case "operatorGrants:staffScopeInsufficient":
+      return "staffScopeInsufficient";
     default:
       if (status === 403 || status === 401) return "notAuthenticated";
       return "error";
@@ -474,7 +573,9 @@ export function principalGrantFailureMessage(reason: PrincipalGrantFailureReason
     case "principalTypeNotSupported":
       return "this endpoint grants a human (email) principal only";
     case "subjectNotTenantOwner":
-      return "only an owner of this store can delegate ship-on-behalf";
+      return "only an owner of this store can grant access";
+    case "staffScopeInsufficient":
+      return "your Token of Trust staff role can't capture owner consent on this store";
     case "tenantNotRegistered":
       return "this store isn't registered with Token of Trust";
     case "brokerAssertionInvalid":
@@ -551,6 +652,7 @@ export function principalGrantHttpStatus(reason: PrincipalGrantFailureReason, up
     case "brokerAssertionInvalid":
       return 401;
     case "subjectNotTenantOwner":
+    case "staffScopeInsufficient":
       return 403;
     case "brokerNotConfigured":
       return 503;

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

@@ -50,14 +50,19 @@ export class FetchShipGrantTransport implements ViewerShipGrantGetTransport {
     // every admin tab), so an unbounded hang stalls the whole document stream. A
     // timeout aborts to the documented deny-default (the resolver maps any transport/
     // timeout fault to `preview-access`) — never a render-blocking wait on a slow MCP.
-    // `redirect: "error"`: a redirect would carry the service-secret header to another origin,
-    // so it rejects (a transport fault, so a deny) and nothing is sent to the redirect target.
+    // `redirect: "manual"`, then a 3xx throws: a followed redirect would carry the service-secret
+    // header to another origin, so a redirect is a transport fault (a deny) and nothing is sent to
+    // its target. Not `redirect: "error"`: the Workers runtime rejects that value before the request
+    // leaves, so every lookup would deny without ever reaching tot-mcp.
     const res = await fetch(url, {
       method: "GET",
       headers,
-      redirect: "error",
+      redirect: "manual",
       signal: AbortSignal.timeout(2500),
     });
+    if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
+      throw new Error("grant authority answered a redirect; refused");
+    }
     return { status: res.status, json: () => res.json() };
   }
 }

package/apps/storefront/src/lib/orders/admin/orderActions.ts

@@ -95,7 +95,9 @@ export function addressLines(address: unknown): string[] {
 export const CONTACT_NONE =
   "No customer contact details are on file for this order. They are kept for a limited time and are gone once expired or erased.";
 export const CONTACT_DENIED = "You cannot view customer contact details for this order.";
-export const CONTACT_GRANT_REQUIRED = "The store owner has not granted ToT support access to customer contact details.";
+export const CONTACT_GRANT_REQUIRED =
+  "The store owner has not granted ToT support access to customer contact details. Ask the owner to grant it on the " +
+  "store's Team page, or, if the owner already agreed, record their consent there under Customer contact access.";
 export const CONTACT_QUOTA = "The hourly limit for reading customer contact details has been reached. Try again later.";
 export const CONTACT_UNAVAILABLE = "Customer contact details are temporarily unavailable. Try again shortly.";
 export const CONTACT_FAILED = "The contact details could not be loaded. Try again.";

package/package.json

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