@tokenoftrust/storefront-runner 2.0.6 → 2.0.8

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

@@ -0,0 +1,132 @@
+/**
+ * Client behavior for the "Delegate ship-on-behalf" section of
+ * /dashboard/<appDomain>/team (handoff 2026-09-03-storefront-owner-grants-a-developer).
+ *
+ * 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).
+ */
+(function () {
+  const $ = (id) => document.getElementById(id);
+  const body = $("delegations");
+  if (!body) return; // section not rendered (staff view) — nothing to wire up
+  const tenant = body.dataset.tenant;
+
+  function showMsg(kind, text) {
+    const el = $("delegateMsg");
+    el.className = "msg " + kind;
+    el.textContent = text;
+  }
+
+  function renderRows(grants) {
+    body.replaceChildren();
+    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.";
+      tr.appendChild(td); body.appendChild(tr);
+      return;
+    }
+    for (const g of grants) {
+      const tr = document.createElement("tr");
+      const dev = document.createElement("td");
+      dev.textContent = (g.principal && g.principal.email) || "";
+      const exp = document.createElement("td");
+      exp.textContent = g.expiresAt ? new Date(g.expiresAt).toLocaleString() : "";
+      const act = document.createElement("td");
+      act.className = "act";
+      const revokeBtn = document.createElement("button");
+      revokeBtn.type = "button";
+      revokeBtn.className = "rowbtn";
+      revokeBtn.textContent = "Revoke";
+      revokeBtn.addEventListener("click", () => revoke(g.ref, dev.textContent, revokeBtn));
+      act.appendChild(revokeBtn);
+      tr.appendChild(dev); tr.appendChild(exp); tr.appendChild(act);
+      body.appendChild(tr);
+    }
+  }
+
+  function renderError(msg) {
+    body.replaceChildren();
+    const tr = document.createElement("tr");
+    const td = document.createElement("td");
+    td.colSpan = 3; td.className = "muted";
+    td.textContent = msg;
+    tr.appendChild(td); body.appendChild(tr);
+  }
+
+  async function loadDelegations() {
+    try {
+      const res = await fetch("/api/grants/principal?tenant=" + encodeURIComponent(tenant), {
+        headers: { accept: "application/json" },
+      });
+      const data = await res.json().catch(() => ({}));
+      if (res.ok) renderRows(data.grants);
+      else renderError(data.error || ("Couldn't load delegations (HTTP " + res.status + ")."));
+    } catch (e) {
+      renderError("Couldn't load delegations: " + (e && e.message ? e.message : e));
+    }
+  }
+
+  async function revoke(ref, email, btn) {
+    if (!ref) return;
+    if (!confirm("Revoke " + (email || "this developer") + "'s ship-on-behalf access?")) return;
+    if (btn) btn.disabled = true;
+    try {
+      const res = await fetch("/api/grants/principal", {
+        method: "DELETE",
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify({ tenant, ref }),
+      });
+      const data = await res.json().catch(() => ({}));
+      if (res.ok) {
+        showMsg("ok", "Revoked " + (email || "") + "'s access.");
+        loadDelegations();
+      } else {
+        showMsg("err", data.error || ("Couldn't revoke (HTTP " + res.status + ")."));
+        if (btn) btn.disabled = false;
+      }
+    } catch (e) {
+      showMsg("err", "Couldn't revoke: " + (e && e.message ? e.message : e));
+      if (btn) btn.disabled = false;
+    }
+  }
+
+  async function grant() {
+    const email = $("delegateEmail").value.trim();
+    if (!email) { showMsg("err", "Enter a developer email."); return; }
+    const ttlEl = $("delegateTtl");
+    const ttlMs = ttlEl ? Number(ttlEl.value) : 2592000000;
+    const btn = $("delegateBtn");
+    btn.disabled = true;
+    showMsg("", "Granting…");
+    try {
+      const res = await fetch("/api/grants/principal", {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify({ tenant, email, ttlMs }),
+      });
+      const data = await res.json().catch(() => ({}));
+      if (res.ok) {
+        showMsg("ok", "Granted ship-on-behalf to " + email + ".");
+        $("delegateEmail").value = "";
+        loadDelegations();
+      } else {
+        showMsg("err", data.error || ("Grant failed (HTTP " + res.status + ")."));
+      }
+    } catch (e) {
+      showMsg("err", "Grant failed: " + (e && e.message ? e.message : e));
+    } finally {
+      btn.disabled = false;
+    }
+  }
+
+  const delegateBtn = $("delegateBtn");
+  const emailInput = $("delegateEmail");
+  if (delegateBtn && emailInput) {
+    delegateBtn.addEventListener("click", grant);
+    emailInput.addEventListener("keydown", (e) => { if (e.key === "Enter") grant(); });
+  }
+  loadDelegations();
+})();

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

@@ -21,11 +21,25 @@
  *     → 422 developerInvites:{tenantRequired|invalidEmail|tenantNotFound}
  *
  * AUTH WIRE (mirrors `@/lib/auth/totAccessClient`): tot20's swagger
- * `normalizeSecureUserRequest` extracts machine creds
- * from the request BODY fields `totApiKey`/`totSecretKey`, NOT custom `x-tot-*`
- * headers. That is the ONLY integration-sensitive spot ({@link credentialFields}).
+ * `normalizeSecureUserRequest` accepts machine creds three ways — request BODY
+ * fields `totApiKey`/`totSecretKey`, the same fields as QUERY params, or an
+ * `Authorization` header carrying a base64 "license key"
+ * (`base64("<apiKey>;<secretKey>")`, expanded by tot20's `expandLicenseKey`, which
+ * takes PRECEDENCE over the body/query values). Custom `x-tot-*` headers are NOT
+ * read. Those are the only integration-sensitive spots
+ * ({@link credentialFields}, {@link credentialAuthHeader}).
  * tot20 wraps every response in a `{ content, metadata }` envelope.
  *
+ * ⚠ CREDENTIALS NEVER GO IN A URL. `POST` carries them in the body; `GET`/`DELETE`
+ * have no body, so they use the `Authorization` license-key header — NOT the query
+ * string, even though tot20 would accept it there. A query string lands in access
+ * logs, proxy logs, browser history and error-tracking payloads, so a credential
+ * there is a disclosure with a long tail. tot20 holds this same line deliberately
+ * (its staff broker assertions are header-only "so the staff subject never lands in
+ * URLs/access logs"); this client must not be the thing that breaks it.
+ * `developerInvites.test.ts` asserts no credential value ever appears in a request
+ * URL, for any method — keep that guard.
+ *
  * TIER: the host + operator credential are per-DEPLOY env (`TOT_CORE_URL` +
  * `TOT_API_KEY`/`TOT_SECRET_KEY`) — each tier's deploy is configured with its
  * tier-matching values (test/qa → https://qa.tokenoftrust.com, prod →
@@ -372,6 +386,29 @@ export class HttpDeveloperInviteClient implements DeveloperInviteClient {
     return f;
   }
 
+  /**
+   * The body-less counterpart to {@link credentialFields}: the `Authorization`
+   * header tot20 accepts for GET/DELETE, so the credential never reaches the URL.
+   * tot20's `expandLicenseKey` base64-decodes this value and splits it on `;` into
+   * `apiKey;secretKey[;appDomain]`, and `normalizeSecureUserRequest` prefers it over
+   * any body/query credential.
+   *
+   * The encoding is not optional: `expandLicenseKey` returns `undefined` for a PLAIN
+   * `a;b` string (it only decodes values that don't already split into 2-3 fields),
+   * so the base64 wrapper is what makes tot20 read it at all. Base64's alphabet
+   * contains no `;`, so the wrapper can never be mistaken for the plain form.
+   *
+   * Deliberately duplicated from the sibling `@/lib/shared/principalGrants`
+   * (`credentialAuthHeader`) rather than imported, for the same reason the HTTP
+   * transport seam is: this client stays self-contained, and enrollment (L1) does not
+   * take a dependency on the authorization (L2) client. Each copy is guarded by its
+   * own no-credential-in-URL test.
+   */
+  private credentialAuthHeader(): Record<string, string> {
+    const licenseKey = `${this.apiKey};${this.secretKey ?? ""}`;
+    return { authorization: Buffer.from(licenseKey, "utf8").toString("base64") };
+  }
+
   async createInvite(
     input: DeveloperInviteInput,
   ): Promise<DeveloperInviteResult> {
@@ -474,12 +511,13 @@ export class HttpDeveloperInviteClient implements DeveloperInviteClient {
         message: "developerInvites: transport does not support GET",
       };
     }
-    // GET → creds go in the query string (tot20 reads totApiKey/totSecretKey from
-    // body OR query; a GET has no body). tenant is a normal query param.
-    const q = new URLSearchParams({ tenant, ...this.credentialFields() });
+    // GET has no body, so the credential rides the Authorization license-key header
+    // — NEVER the query string (see the ⚠ note in this file's header). `tenant` is a
+    // normal, non-secret query param and stays where it is.
+    const q = new URLSearchParams({ tenant });
     // #8453: the staff actor is proven by the signed
     // assertion header — NEVER a plaintext email query param.
-    const headers: Record<string, string> = {};
+    const headers: Record<string, string> = { ...this.credentialAuthHeader() };
     if (brokerAssertion) headers[BROKER_ASSERTION_HEADER] = brokerAssertion;
     let res: HttpResponseLike;
     try {
@@ -523,14 +561,15 @@ export class HttpDeveloperInviteClient implements DeveloperInviteClient {
         message: "developerInvites: transport does not support DELETE",
       };
     }
-    // DELETE has no body — creds ride the query string, matching listInvites.
-    const q = new URLSearchParams(this.credentialFields());
-    const headers: Record<string, string> = {};
+    // DELETE has no body — the credential rides the Authorization license-key header,
+    // matching listInvites. Nothing secret goes in the URL, so there is no query
+    // string here at all (inviteId is an opaque id, already path-encoded).
+    const headers: Record<string, string> = { ...this.credentialAuthHeader() };
     if (brokerAssertion) headers[BROKER_ASSERTION_HEADER] = brokerAssertion;
     let res: HttpResponseLike;
     try {
       res = await this.transport.delete(
-        `${this.baseUrl}/api/clients/developerInvites/${encodeURIComponent(inviteId)}?${q.toString()}`,
+        `${this.baseUrl}/api/clients/developerInvites/${encodeURIComponent(inviteId)}`,
         headers,
       );
     } catch (cause) {

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

@@ -0,0 +1,527 @@
+/**
+ * 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.
+ *
+ * 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
+ * a human grantee). It is NOT the enrollment path (`@/lib/shared/developerInvites`,
+ * which only ever emits `preview-access`/`blog-contribute` sign-in eligibility) —
+ * the two revoke independently and must never be merged.
+ *
+ *   POST   /api/clients/principalGrants                { principal:{type:'user',email}, capability, expiresAt }
+ *     → 200 { code:'operatorGrants:principalGrantCreated', tenant, principal, ref, capability, expiresAt }
+ *     → 422 operatorGrants:{expiresAtRequired|unknownCapability|invalidPrincipal|principalTypeNotSupported}
+ *     → 403 operatorGrants:notAuthenticated (bad/absent owner credential)
+ *   GET    /api/clients/principalGrants                 → 200 { code:'operatorGrants:principalGrantsOk', grants:[...] }
+ *   DELETE /api/clients/principalGrants/{ref}            → 200 { code:'operatorGrants:principalGrantRevoked', tenant }
+ *
+ * `expiresAt` (epoch-ms) is REQUIRED for a human grantee — tot20 fails closed
+ * with `expiresAtRequired` if omitted (ADR-0003 D4: no standing authority for a
+ * human/service principal). `ref` is opaque (never the raw email) and is what
+ * `revoke`/list rows key on.
+ *
+ * ⚠ KNOWN GAP (2026-09-03, see handoff 2026-09-03-storefront-owner-grants-a-developer,
+ * Part 1): unlike every other tot20 seam in this repo, this route is
+ * OWNER-authenticated — `req.getApiClient()` must resolve to the TARGET TENANT's
+ * own credential, not storefront's own operator identity. Storefront holds NO
+ * per-tenant owner secret key anywhere (confirmed: no such credential exists in
+ * this codebase — every other tot20 call here, `developerInvites`/`teamGrants`,
+ * authenticates as storefront ITSELF via `TOT_API_KEY`/`TOT_SECRET_KEY`, which
+ * resolves to storefront's OWN app domain, not a hosted tenant's). Presenting
+ * storefront's operator credential here would not grant on behalf of the target
+ * tenant — it would either self-grant on storefront's own domain or be rejected.
+ * `createPrincipalGrantClient` therefore FAILS CLOSED (throws
+ * {@link PrincipalGrantClientError}) until one of the following lands:
+ *   (a) tot20 accepts the signed-in owner's verified id_token as bearer auth on
+ *       this route, or
+ *   (b) tot20 adds a storefront-proxy grantor mode (operator credential + a
+ *       verified owner id_token/session claim, scoped to storefront's own hosted
+ *       tenants) — the same shape as the ToT-staff-broker-assertion widening
+ *       requested separately for this same route.
+ * The client/route/UI below are otherwise complete and ready to light up the
+ * moment a real credential resolver exists — see {@link OwnerCredentialResolver}.
+ *
+ * AUTH WIRE: tot20's swagger `normalizeSecureUserRequest` accepts machine creds
+ * three ways — request BODY fields `totApiKey`/`totSecretKey`, the same fields as
+ * QUERY params, or an `Authorization` header carrying a base64 "license key"
+ * (`base64("<apiKey>;<secretKey>")`, expanded by tot20's `expandLicenseKey`,
+ * which takes PRECEDENCE over the body/query values). Custom `x-tot-*` headers
+ * are NOT read. This is the only integration-sensitive spot
+ * ({@link OwnerCredentialResolver}, {@link credentialAuthHeader}).
+ *
+ * ⚠ CREDENTIALS NEVER GO IN A URL. `POST` carries them in the body; `GET`/`DELETE`
+ * have no body, so they use the `Authorization` license-key header — NOT the query
+ * string, even though tot20 would accept it there. A query string lands in access
+ * logs, proxy logs, browser history and error-tracking payloads, so a credential
+ * there is a disclosure with a long tail. tot20 holds this same line deliberately
+ * (its staff broker assertions are header-only "so the staff subject never lands
+ * in URLs/access logs", and its revoke addresses a grant by an opaque `ref`
+ * precisely so an email never becomes a path segment); this client must not be the
+ * thing that breaks it. `principalGrants.test.ts` asserts no credential value ever
+ * appears in a request URL, for any method — keep that guard.
+ *
+ * TIER: host + credentials are per-DEPLOY env, same `TOT_CORE_URL` the sibling
+ * developerInvites/forge clients read (qa tier is what's live today for this route).
+ *
+ * Built like `@/lib/shared/developerInvites` (interface + Http impl + Mock + env
+ * factory) so the route develops/tests against `MockPrincipalGrantClient` and
+ * swaps in the Http client with no call-site change.
+ */
+import { readEnv } from "@/lib/env";
+import { diagEmail } from "@/lib/diag/redact";
+
+/** A human grantee — the only principal type this HTTP surface accepts. */
+export interface UserPrincipal {
+  type: "user";
+  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 & {});
+
+export interface CreatePrincipalGrantInput {
+  /** Target tenant this grant is issued on (session-derived; never trust a body field). */
+  tenant: string;
+  principal: UserPrincipal;
+  capability: PrincipalGrantCapability;
+  /** Epoch-ms; REQUIRED (ADR-0003 D4 — a human grant is never standing authority). */
+  expiresAt: number;
+  scope?: string;
+  purpose?: string;
+}
+
+export interface PrincipalGrantCreated {
+  ok: true;
+  tenant: string;
+  principal: UserPrincipal;
+  /** Opaque revoke handle — never the raw email. */
+  ref: string;
+  capability: string;
+  expiresAt: number;
+}
+
+export type PrincipalGrantFailureReason =
+  | "notAuthenticated" // 403/422 — owner credential missing/rejected
+  | "expiresAtRequired" // 422 — ADR-0003 D4
+  | "unknownCapability" // 422
+  | "invalidPrincipal" // 422
+  | "principalTypeNotSupported" // 422 — non-'user' principal at this HTTP layer
+  | "ownerCredentialNotConfigured" // LOCAL: no owner-credential resolver wired yet (see file header)
+  | "error"; // transport / unexpected upstream fault
+
+export interface PrincipalGrantFailed {
+  ok: false;
+  status: number;
+  reason: PrincipalGrantFailureReason;
+  message: string;
+  code?: string;
+}
+
+export type PrincipalGrantResult = PrincipalGrantCreated | PrincipalGrantFailed;
+
+export interface PrincipalGrantSummary {
+  principal: UserPrincipal;
+  capability: string;
+  expiresAt: number;
+  ref: string;
+}
+
+export type PrincipalGrantListResult =
+  | { ok: true; tenant: string; grants: PrincipalGrantSummary[] }
+  | { ok: false; status: number; reason: PrincipalGrantFailureReason; message: string; code?: string };
+
+export type PrincipalGrantRevokeResult =
+  | { ok: true; tenant: string; ref: string }
+  | { ok: false; status: number; reason: PrincipalGrantFailureReason; message: string; code?: string };
+
+export interface PrincipalGrantClient {
+  createGrant(input: CreatePrincipalGrantInput): Promise<PrincipalGrantResult>;
+  listGrants(tenant: string): Promise<PrincipalGrantListResult>;
+  revokeGrant(tenant: string, ref: string): Promise<PrincipalGrantRevokeResult>;
+}
+
+// --- HTTP transport seam (injected by tests) --------------------------------
+
+export interface HttpResponseLike {
+  status: number;
+  json(): Promise<unknown>;
+}
+export interface HttpTransport {
+  post(url: string, headers: Record<string, string>, body: unknown): Promise<HttpResponseLike>;
+  get(url: string, headers: Record<string, string>): Promise<HttpResponseLike>;
+  delete(url: string, headers: Record<string, string>): Promise<HttpResponseLike>;
+}
+
+export class FetchHttpTransport implements HttpTransport {
+  async post(url: string, headers: Record<string, string>, body: unknown) {
+    return fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json", ...headers },
+      body: JSON.stringify(body),
+    });
+  }
+  async get(url: string, headers: Record<string, string>) {
+    return fetch(url, { method: "GET", headers: { accept: "application/json", ...headers } });
+  }
+  async delete(url: string, headers: Record<string, string>) {
+    return fetch(url, { method: "DELETE", headers: { accept: "application/json", ...headers } });
+  }
+}
+
+export class PrincipalGrantClientError extends Error {}
+
+/**
+ * Resolves the tot20 credential fields to merge into a request body FOR A GIVEN
+ * TENANT — the seam the known gap above is about. Returns `null` when no owner
+ * credential can be resolved for that tenant (fails closed; never falls back to
+ * storefront's own operator credential, which would silently misdirect the grant).
+ */
+export type OwnerCredentialResolver = (
+  tenant: string,
+) => Promise<{ totApiKey: string; totSecretKey?: string } | null>;
+
+/**
+ * Build the `Authorization` header tot20 accepts for a body-less request (GET /
+ * DELETE), so the credential never reaches the URL. tot20's `expandLicenseKey`
+ * base64-decodes this value and splits it on `;` into `apiKey;secretKey[;appDomain]`,
+ * and `normalizeSecureUserRequest` prefers it over any body/query credential.
+ *
+ * Note the encoding is not optional: `expandLicenseKey` returns `undefined` for a
+ * PLAIN `a;b` string (it only decodes values that don't already split into 2-3
+ * fields), so the base64 wrapper is what makes tot20 read it at all. Base64's
+ * alphabet contains no `;`, so the wrapper can never be mistaken for the plain form.
+ */
+export function credentialAuthHeader(cred: {
+  totApiKey: string;
+  totSecretKey?: string;
+}): { authorization: string } {
+  const licenseKey = `${cred.totApiKey};${cred.totSecretKey ?? ""}`;
+  return { authorization: Buffer.from(licenseKey, "utf8").toString("base64") };
+}
+
+export interface HttpPrincipalGrantClientConfig {
+  /** tot20 core API base (no trailing slash), e.g. https://qa.tokenoftrust.com */
+  baseUrl: string;
+  resolveOwnerCredential: OwnerCredentialResolver;
+  transport?: HttpTransport;
+}
+
+export class HttpPrincipalGrantClient implements PrincipalGrantClient {
+  private readonly baseUrl: string;
+  private readonly resolveOwnerCredential: OwnerCredentialResolver;
+  private readonly transport: HttpTransport;
+
+  constructor(config: HttpPrincipalGrantClientConfig) {
+    if (!config.baseUrl) {
+      throw new PrincipalGrantClientError("principalGrants: TOT_CORE_URL is not configured");
+    }
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.resolveOwnerCredential = config.resolveOwnerCredential;
+    this.transport = config.transport ?? new FetchHttpTransport();
+  }
+
+  async createGrant(input: CreatePrincipalGrantInput): Promise<PrincipalGrantResult> {
+    const cred = await this.resolveOwnerCredential(input.tenant);
+    if (!cred) return notConfigured();
+
+    const body: Record<string, unknown> = {
+      principal: { type: "user", email: input.principal.email.toLowerCase() },
+      capability: input.capability,
+      expiresAt: input.expiresAt,
+      totApiKey: cred.totApiKey,
+      ...(cred.totSecretKey ? { totSecretKey: cred.totSecretKey } : {}),
+    };
+    if (input.scope) body.scope = input.scope;
+    if (input.purpose) body.purpose = input.purpose;
+
+    logGrantDiag("request", {
+      endpoint: `${this.baseUrl}/api/clients/principalGrants`,
+      tenant: input.tenant,
+      email: diagEmail(input.principal.email.toLowerCase()),
+      capability: input.capability,
+      expiresAt: input.expiresAt,
+    });
+
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.post(`${this.baseUrl}/api/clients/principalGrants`, {}, body);
+    } catch (cause) {
+      return transportFailure("creating principal grant", cause);
+    }
+    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 }),
+    });
+    return result;
+  }
+
+  async listGrants(tenant: string): Promise<PrincipalGrantListResult> {
+    const cred = await this.resolveOwnerCredential(tenant);
+    if (!cred) return notConfigured();
+    let res: HttpResponseLike;
+    try {
+      // Credential travels in the Authorization header, never the query string.
+      res = await this.transport.get(
+        `${this.baseUrl}/api/clients/principalGrants`,
+        credentialAuthHeader(cred),
+      );
+    } catch (cause) {
+      return transportFailure("listing principal grants", cause);
+    }
+    const parsed = await safeJson(res, "listing principal grants");
+    if ("failed" in parsed) return parsed.failed;
+    return normalizeListResponse(res.status, tenant, parsed.body);
+  }
+
+  async revokeGrant(tenant: string, ref: string): Promise<PrincipalGrantRevokeResult> {
+    const cred = await this.resolveOwnerCredential(tenant);
+    if (!cred) return notConfigured();
+    let res: HttpResponseLike;
+    try {
+      // Credential travels in the Authorization header, never the query string.
+      // `ref` is tot20's opaque grant handle (never a raw email), so it is safe
+      // as a path segment — that is exactly why tot20 addresses revoke by ref.
+      res = await this.transport.delete(
+        `${this.baseUrl}/api/clients/principalGrants/${encodeURIComponent(ref)}`,
+        credentialAuthHeader(cred),
+      );
+    } catch (cause) {
+      return transportFailure("revoking principal grant", cause);
+    }
+    const parsed = await safeJson(res, "revoking principal grant");
+    if ("failed" in parsed) return parsed.failed;
+    return normalizeRevokeResponse(res.status, tenant, parsed.body);
+  }
+}
+
+function notConfigured(): PrincipalGrantFailed {
+  return {
+    ok: false,
+    status: 503,
+    reason: "ownerCredentialNotConfigured",
+    message:
+      "storefront has no owner credential to present to tot20 for this tenant yet " +
+      "(see the KNOWN GAP note in lib/shared/principalGrants.ts)",
+  };
+}
+
+async function transportFailure(action: string, cause: unknown): Promise<PrincipalGrantFailed> {
+  return {
+    ok: false,
+    status: 0,
+    reason: "error",
+    message: `principalGrants: transport failure ${action} ` + (cause instanceof Error ? cause.message : String(cause)),
+  };
+}
+
+async function safeJson(
+  res: HttpResponseLike,
+  action: string,
+): Promise<{ body: unknown } | { failed: PrincipalGrantFailed }> {
+  try {
+    return { body: await res.json() };
+  } catch {
+    return {
+      failed: {
+        ok: false,
+        status: res.status,
+        reason: "error",
+        message: `principalGrants: tot20 returned a non-JSON body ${action} (status ${res.status})`,
+      },
+    };
+  }
+}
+
+function logGrantDiag(phase: "request" | "response", fields: Record<string, unknown>): void {
+  try {
+    console.info(`[diag:principalGrants:${phase}]`, JSON.stringify(fields));
+  } catch {
+    /* diagnostics must never break the call */
+  }
+}
+
+function unwrapEnvelope(body: unknown): Record<string, unknown> {
+  const raw = (body ?? {}) as Record<string, unknown>;
+  return (raw.content && typeof raw.content === "object" ? raw.content : raw) as Record<string, unknown>;
+}
+
+function reasonFor(code: string | undefined, status: number): PrincipalGrantFailureReason {
+  switch (code) {
+    case "operatorGrants:notAuthenticated":
+      return "notAuthenticated";
+    case "operatorGrants:expiresAtRequired":
+    case "operatorGrants:invalidExpiresAt":
+      return "expiresAtRequired";
+    case "operatorGrants:unknownCapability":
+      return "unknownCapability";
+    case "operatorGrants:invalidPrincipal":
+    case "operatorGrants:principalNotFound":
+      return "invalidPrincipal";
+    case "operatorGrants:principalTypeNotSupported":
+      return "principalTypeNotSupported";
+    default:
+      if (status === 403 || status === 401) return "notAuthenticated";
+      return "error";
+  }
+}
+
+function defaultMessage(reason: PrincipalGrantFailureReason, status: number): string {
+  switch (reason) {
+    case "notAuthenticated":
+      return "storefront isn't authorized to grant on this tenant";
+    case "expiresAtRequired":
+      return "a future expiresAt is required for a human grant";
+    case "unknownCapability":
+      return "unknown capability";
+    case "invalidPrincipal":
+      return "a valid grantee email is required";
+    case "principalTypeNotSupported":
+      return "this endpoint grants a human (email) principal only";
+    case "ownerCredentialNotConfigured":
+      return "storefront has no owner credential configured for this tenant";
+    default:
+      return `principalGrants: tot20 returned status ${status}`;
+  }
+}
+
+export function normalizeCreateResponse(status: number, body: unknown): PrincipalGrantResult {
+  const c = unwrapEnvelope(body);
+  const code = typeof c.code === "string" ? c.code : undefined;
+  const isCreated = code === "operatorGrants:principalGrantCreated" || (status >= 200 && status < 300 && typeof c.ref === "string");
+  if (isCreated) {
+    return {
+      ok: true,
+      tenant: String(c.tenant ?? ""),
+      principal: (c.principal as UserPrincipal) ?? { type: "user", email: "" },
+      ref: String(c.ref ?? ""),
+      capability: String(c.capability ?? ""),
+      expiresAt: Number(c.expiresAt ?? 0),
+    };
+  }
+  const reason = reasonFor(code, status);
+  const message = typeof c.message === "string" ? c.message : defaultMessage(reason, status);
+  return { ok: false, status, reason, message, ...(code ? { code } : {}) };
+}
+
+export function normalizeListResponse(status: number, tenant: string, body: unknown): PrincipalGrantListResult {
+  const c = unwrapEnvelope(body);
+  const code = typeof c.code === "string" ? c.code : undefined;
+  const isOk = code === "operatorGrants:principalGrantsOk" || (status >= 200 && status < 300 && Array.isArray(c.grants));
+  if (isOk) {
+    const grants: PrincipalGrantSummary[] = (Array.isArray(c.grants) ? c.grants : []).map((raw) => {
+      const g = (raw ?? {}) as Record<string, unknown>;
+      return {
+        principal: (g.principal as UserPrincipal) ?? { type: "user", email: "" },
+        capability: String(g.capability ?? ""),
+        expiresAt: Number(g.expiresAt ?? 0),
+        ref: String(g.ref ?? ""),
+      };
+    });
+    return { ok: true, tenant, grants };
+  }
+  const reason = reasonFor(code, status);
+  const message = typeof c.message === "string" ? c.message : defaultMessage(reason, status);
+  return { ok: false, status, reason, message, ...(code ? { code } : {}) };
+}
+
+export function normalizeRevokeResponse(status: number, tenant: string, body: unknown): PrincipalGrantRevokeResult {
+  const c = unwrapEnvelope(body);
+  const code = typeof c.code === "string" ? c.code : undefined;
+  const isOk = code === "operatorGrants:principalGrantRevoked" || (status >= 200 && status < 300);
+  if (isOk) {
+    return { ok: true, tenant: String(c.tenant ?? tenant), ref: "" };
+  }
+  const reason = reasonFor(code, status);
+  const message = typeof c.message === "string" ? c.message : defaultMessage(reason, status);
+  return { ok: false, status, reason, message, ...(code ? { code } : {}) };
+}
+
+/** Map a typed failure onto the HTTP status a storefront route should return. */
+export function principalGrantHttpStatus(reason: PrincipalGrantFailureReason, upstreamStatus: number): number {
+  switch (reason) {
+    case "notAuthenticated":
+      return 403;
+    case "expiresAtRequired":
+    case "unknownCapability":
+    case "invalidPrincipal":
+    case "principalTypeNotSupported":
+      return 422;
+    case "ownerCredentialNotConfigured":
+      return 503;
+    default:
+      return upstreamStatus >= 400 ? upstreamStatus : 502;
+  }
+}
+
+// --- Mock (tests + local dev) -----------------------------------------------
+
+/** In-memory PrincipalGrantClient — deterministic for route/UI tests. */
+export class MockPrincipalGrantClient implements PrincipalGrantClient {
+  private grants = new Map<string, { principal: UserPrincipal; capability: string; expiresAt: number }>();
+  private seq = 0;
+  /** Tenants with NO owner credential configured (simulates the known gap). */
+  private readonly unconfigured: Set<string>;
+
+  constructor(unconfiguredTenants: string[] = []) {
+    this.unconfigured = new Set(unconfiguredTenants.map((t) => t.toLowerCase()));
+  }
+
+  async createGrant(input: CreatePrincipalGrantInput): Promise<PrincipalGrantResult> {
+    const tenant = input.tenant.toLowerCase();
+    if (this.unconfigured.has(tenant)) return notConfigured();
+    if (!input.expiresAt || input.expiresAt <= Date.now()) {
+      return { ok: false, status: 422, reason: "expiresAtRequired", message: "a future expiresAt is required", code: "operatorGrants:expiresAtRequired" };
+    }
+    const email = input.principal.email.trim().toLowerCase();
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      return { ok: false, status: 422, reason: "invalidPrincipal", message: "a valid grantee email is required", code: "operatorGrants:invalidPrincipal" };
+    }
+    const ref = `mock-ref-${tenant}-${++this.seq}`;
+    this.grants.set(ref, { principal: { type: "user", email }, capability: input.capability, expiresAt: input.expiresAt });
+    return { ok: true, tenant, principal: { type: "user", email }, ref, capability: input.capability, expiresAt: input.expiresAt };
+  }
+
+  async listGrants(tenant: string): Promise<PrincipalGrantListResult> {
+    const t = tenant.toLowerCase();
+    if (this.unconfigured.has(t)) return notConfigured();
+    const grants = [...this.grants.entries()]
+      .filter(([ref]) => ref.startsWith(`mock-ref-${t}-`))
+      .map(([ref, g]) => ({ ...g, ref }));
+    return { ok: true, tenant: t, grants };
+  }
+
+  async revokeGrant(tenant: string, ref: string): Promise<PrincipalGrantRevokeResult> {
+    const t = tenant.toLowerCase();
+    if (this.unconfigured.has(t)) return notConfigured();
+    if (!ref.startsWith(`mock-ref-${t}-`) || !this.grants.has(ref)) {
+      return { ok: false, status: 404, reason: "error", message: "no such grant" };
+    }
+    this.grants.delete(ref);
+    return { ok: true, tenant: t, ref };
+  }
+}
+
+// --- Factory ----------------------------------------------------------------
+
+/**
+ * Build the env-configured client. `resolveOwnerCredential` defaults to a
+ * fail-closed stub (see the KNOWN GAP note at the top of this file) — pass an
+ * override once a real owner-credential resolver exists.
+ */
+export async function createPrincipalGrantClient(
+  overrides: Partial<HttpPrincipalGrantClientConfig> = {},
+): Promise<HttpPrincipalGrantClient> {
+  const baseUrl = overrides.baseUrl ?? (await readEnv("TOT_CORE_URL")) ?? "";
+  return new HttpPrincipalGrantClient({
+    baseUrl,
+    resolveOwnerCredential: overrides.resolveOwnerCredential ?? (async () => null),
+    ...(overrides.transport ? { transport: overrides.transport } : {}),
+  });
+}

package/package.json

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