@tokenoftrust/storefront-runner 2.0.8 → 2.0.10

package/apps/storefront/integrations/materialize-guard.mjs

@@ -34,7 +34,13 @@ export function materializeGuard() {
         const onlyTenants = scoped.length > 0 ? scoped : null;
         const frameworkOnly = onlyTenants === null || process.env.TOT_FRAMEWORK_ONLY_BUILD === "1";
         if (frameworkOnly) {
-          const { problems } = checkPinned(undefined, { expectRef, allowUnpinned, onlyTenants });
+          // Framework mode never treats tenant content as a build input (it's
+          // resolved from KV/R2 per request), so the guard checks ZERO
+          // tenants here — onlyTenants=[] scopes checkPinned to an empty
+          // set (not "all tenants", which `null` would mean), so a sibling
+          // tenant that is present-but-stale can never block this build.
+          const frameworkOnlyTenants = [];
+          const { problems } = checkPinned(undefined, { expectRef, allowUnpinned, onlyTenants: frameworkOnlyTenants });
           const absent = problems.filter((p) => p.reason === "absent");
           const real = problems.filter((p) => p.reason !== "absent");
           if (absent.length) {
@@ -43,7 +49,7 @@ export function materializeGuard() {
             else console.log(msg);
           }
           if (real.length) {
-            assertPinnedMaterialized({ expectRef, allowUnpinned, onlyTenants });
+            assertPinnedMaterialized({ expectRef, allowUnpinned, onlyTenants: frameworkOnlyTenants });
           }
           return;
         }

package/apps/storefront/src/lib/auth/brokerAssertion.ts

@@ -28,6 +28,13 @@ import { readEnv } from "@/lib/env";
 /** The audience tot20's broker verifier pins. */
 export const BROKER_AUDIENCE = "tot20-broker";
 
+/**
+ * The ONLY place an assertion may travel — a header, never a query string, so the
+ * subject never lands in access logs, proxy logs or browser history. tot20 reads
+ * it case-insensitively (`readAssertion`, `operatorGrants-api.routes.node.js`).
+ */
+export const BROKER_ASSERTION_HEADER = "X-ToT-Broker-Assertion";
+
 /** The only algorithm the storefront broker signs with (tot20 rejects anything else). */
 export const BROKER_ALG = "RS256";
 
@@ -52,8 +59,20 @@ export const BROKER_ISSUER_ENV = "STOREFRONT_BROKER_ISSUER";
  */
 export class BrokerAssertionError extends Error {}
 
-/** Optional test/DI overrides (avoids touching process env in unit tests). */
+/** Mint options: the optional `tenant` claim, plus test/DI overrides. */
 export interface MintBrokerAssertionOverrides {
+  /**
+   * Binds this one assertion to a single target tenant (appDomain), signed. tot20
+   * reads it as `assertionTenant` and requires it to match the tenant named on the
+   * request EXACTLY — an unnormalized string compare, so pass the same value the
+   * request carries. It names the tenant the broker was asked to act on; it is
+   * NOT evidence the subject owns it (tot20 resolves ownership from its own state).
+   *
+   * Omit for the surfaces that act on the caller's own store or on ToT-staff
+   * authority alone (the invite/vendor-search flows) — tot20 leaves
+   * `assertionTenant` undefined there and those routes never consult it.
+   */
+  tenant?: string;
   /** base64 of the PKCS8 PEM private key (defaults to the env value). */
   privateKeyB64?: string;
   kid?: string;
@@ -95,12 +114,17 @@ async function loadSigningKey(privateKeyB64: string): Promise<CryptoKey> {
 }
 
 /**
- * Mint a fresh, storefront-signed broker assertion PROVING `subjectEmail` is the
- * staff actor. Returns the compact RS256 JWT to place in `X-ToT-Broker-Assertion`.
+ * Mint a fresh, storefront-signed broker assertion PROVING the storefront asserts
+ * `subjectEmail` as the actor. Returns the compact RS256 JWT to place in
+ * {@link BROKER_ASSERTION_HEADER}.
  *
- * Claims: `{ iss, sub:<subjectEmail>, aud:'tot20-broker', jti:<uuid>, iat, exp:iat+300 }`.
+ * Claims: `{ iss, sub:<subjectEmail>, aud:'tot20-broker', jti:<uuid>, iat, exp:iat+300 }`,
+ * plus `tenant` when `overrides.tenant` is given.
  * Header: `{ alg:'RS256', kid, typ:'JWT' }`.
  *
+ * MINT ONE PER CALL. tot20's verifier BURNS the `jti` on first verify (single-use
+ * replay protection), so an assertion must never be reused across two requests.
+ *
  * FAILS CLOSED: throws {@link BrokerAssertionError} when the private key env is
  * absent/malformed or no subject is supplied — the caller must NOT fall back to an
  * unproven call.
@@ -122,9 +146,11 @@ export async function mintBrokerAssertion(
   const kid = overrides.kid ?? (await readEnv(BROKER_KID_ENV)) ?? DEFAULT_BROKER_KID;
   const issuer = overrides.issuer ?? (await readEnv(BROKER_ISSUER_ENV)) ?? DEFAULT_BROKER_ISSUER;
 
+  const tenant = (overrides.tenant ?? "").trim();
+
   const key = await loadSigningKey(privateKeyB64);
   const nowSeconds = Math.floor(Date.now() / 1000);
-  return new SignJWT({})
+  return new SignJWT(tenant ? { tenant } : {})
     .setProtectedHeader({ alg: BROKER_ALG, kid, typ: "JWT" })
     .setIssuer(issuer)
     .setSubject(sub)

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

@@ -9,57 +9,64 @@
  * 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 }
+ *   POST   /api/clients/principalGrants                   { tenant, 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 }
+ *   GET    /api/clients/principalGrants?tenant=<t>        → 200 { code:'operatorGrants:principalGrantsOk', grants:[...] }
+ *   DELETE /api/clients/principalGrants/{ref}?tenant=<t>  → 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}.
+ * 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:
+ *
+ *   - 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
+ *     brokered path.
+ *   - 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.
+ *   - 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
+ *     the grantor. tot20 audits the result as `authorityPath:'owner-brokered-session'`
+ *     with actor `owner:<hash>` — distinct from the owner-key `self-service-direct`.
+ *
+ * The assertion is minted PER CALL by the route (the only layer holding the verified
+ * session) and injected as {@link OwnerAssertionMinter}; this module never sees a
+ * session and so cannot mint on a client-supplied email. tot20's verifier BURNS the
+ * `jti` on first verify, so a minter that memoized would fail the second call as a
+ * replay.
  *
  * 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}).
+ * which takes PRECEDENCE over the body/query values). The broker assertion rides the
+ * separate `X-ToT-Broker-Assertion` header ({@link BROKER_ASSERTION_HEADER}) — the
+ * only place tot20's `readAssertion` looks. These are the integration-sensitive spots
+ * ({@link credentialAuthHeader}, {@link HttpPrincipalGrantClient.brokeredHeaders}).
  *
- * ⚠ 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.
+ * ⚠ CREDENTIALS AND ASSERTIONS NEVER GO IN A URL. `POST` carries the credential 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 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. `?tenant=` on GET/DELETE is the ONE permitted query param
+ * — an appDomain is public routing data, not a credential, and tot20 reads the tenant
+ * from `req.query` on exactly those two verbs. `principalGrants.test.ts` asserts that
+ * `tenant` is the only param present and that no credential or assertion value ever
+ * reaches a 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).
@@ -70,6 +77,7 @@
  */
 import { readEnv } from "@/lib/env";
 import { diagEmail } from "@/lib/diag/redact";
+import { BROKER_ASSERTION_HEADER, BROKER_PRIVATE_KEY_ENV } from "@/lib/auth/brokerAssertion";
 
 /** A human grantee — the only principal type this HTTP surface accepts. */
 export interface UserPrincipal {
@@ -103,12 +111,18 @@ export interface PrincipalGrantCreated {
 }
 
 export type PrincipalGrantFailureReason =
-  | "notAuthenticated" // 403/422 — owner credential missing/rejected
+  | "notAuthenticated" // 403/422 — storefront's own operator 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)
+  // --- owner-brokered grantor path (tot20 `resolveGrantorContext`) ---
+  | "brokerAssertionRequired" // 422 — named a tenant with no assertion (client bug)
+  | "brokerAssertionInvalid" // 401 — bad signature / expired / replayed jti
+  | "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
+  | "brokerNotConfigured" // LOCAL 503 — this deploy holds no broker signing key
   | "error"; // transport / unexpected upstream fault
 
 export interface PrincipalGrantFailed {
@@ -173,14 +187,18 @@ export class FetchHttpTransport implements HttpTransport {
 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).
+ * Mints a FRESH broker assertion naming `tenant`, whose subject is the signed-in
+ * OWNER. Supplied by the route, which is the only layer holding a verified session
+ * — keeping this an injected function is what makes it structurally impossible for
+ * this module to assert an email that came off a request.
+ *
+ * Returns `null` when this deploy cannot sign at all (no broker key) — the caller
+ * fails closed with `brokerNotConfigured` rather than sending an unbrokered request
+ * that tot20 would silently resolve to storefront's OWN store as grantor.
+ *
+ * Called once per request: tot20 burns the `jti`, so a cached assertion replays.
  */
-export type OwnerCredentialResolver = (
-  tenant: string,
-) => Promise<{ totApiKey: string; totSecretKey?: string } | null>;
+export type OwnerAssertionMinter = (tenant: string) => Promise<string | null>;
 
 /**
  * Build the `Authorization` header tot20 accepts for a body-less request (GET /
@@ -204,34 +222,63 @@ export function credentialAuthHeader(cred: {
 export interface HttpPrincipalGrantClientConfig {
   /** tot20 core API base (no trailing slash), e.g. https://qa.tokenoftrust.com */
   baseUrl: string;
-  resolveOwnerCredential: OwnerCredentialResolver;
+  /** Storefront's OWN operator credential — authenticates the broker, not the grantor. */
+  apiKey: string;
+  secretKey?: string;
+  mintOwnerAssertion: OwnerAssertionMinter;
   transport?: HttpTransport;
 }
 
 export class HttpPrincipalGrantClient implements PrincipalGrantClient {
   private readonly baseUrl: string;
-  private readonly resolveOwnerCredential: OwnerCredentialResolver;
+  private readonly apiKey: string;
+  private readonly secretKey: string | undefined;
+  private readonly mintOwnerAssertion: OwnerAssertionMinter;
   private readonly transport: HttpTransport;
 
   constructor(config: HttpPrincipalGrantClientConfig) {
     if (!config.baseUrl) {
       throw new PrincipalGrantClientError("principalGrants: TOT_CORE_URL is not configured");
     }
+    if (!config.apiKey) {
+      throw new PrincipalGrantClientError("principalGrants: TOT_API_KEY is not configured");
+    }
     this.baseUrl = config.baseUrl.replace(/\/+$/, "");
-    this.resolveOwnerCredential = config.resolveOwnerCredential;
+    this.apiKey = config.apiKey;
+    this.secretKey = config.secretKey;
+    this.mintOwnerAssertion = config.mintOwnerAssertion;
     this.transport = config.transport ?? new FetchHttpTransport();
   }
 
+  /** Storefront's own operator credential, as tot20's documented body fields. */
+  private credential(): { totApiKey: string; totSecretKey?: string } {
+    return { totApiKey: this.apiKey, ...(this.secretKey ? { totSecretKey: this.secretKey } : {}) };
+  }
+
+  /**
+   * Headers for a brokered call. `assertion` is header-only; the license-key
+   * `Authorization` is added for the body-less verbs, which have nowhere else to
+   * carry the credential that isn't the URL.
+   */
+  private brokeredHeaders(assertion: string, withCredential: boolean): Record<string, string> {
+    return {
+      [BROKER_ASSERTION_HEADER]: assertion,
+      ...(withCredential ? credentialAuthHeader(this.credential()) : {}),
+    };
+  }
+
   async createGrant(input: CreatePrincipalGrantInput): Promise<PrincipalGrantResult> {
-    const cred = await this.resolveOwnerCredential(input.tenant);
-    if (!cred) return notConfigured();
+    const assertion = await this.mintOwnerAssertion(input.tenant);
+    if (!assertion) return brokerNotConfigured();
 
+    // `tenant` in the BODY is what puts tot20 on the owner-brokered branch for POST
+    // (createPrincipalGrant reads `body.tenant`); GET/DELETE read `req.query.tenant`.
     const body: Record<string, unknown> = {
+      tenant: input.tenant,
       principal: { type: "user", email: input.principal.email.toLowerCase() },
       capability: input.capability,
       expiresAt: input.expiresAt,
-      totApiKey: cred.totApiKey,
-      ...(cred.totSecretKey ? { totSecretKey: cred.totSecretKey } : {}),
+      ...this.credential(),
     };
     if (input.scope) body.scope = input.scope;
     if (input.purpose) body.purpose = input.purpose;
@@ -246,7 +293,11 @@ export class HttpPrincipalGrantClient implements PrincipalGrantClient {
 
     let res: HttpResponseLike;
     try {
-      res = await this.transport.post(`${this.baseUrl}/api/clients/principalGrants`, {}, body);
+      res = await this.transport.post(
+        `${this.baseUrl}/api/clients/principalGrants`,
+        this.brokeredHeaders(assertion, false),
+        body,
+      );
     } catch (cause) {
       return transportFailure("creating principal grant", cause);
     }
@@ -263,14 +314,15 @@ export class HttpPrincipalGrantClient implements PrincipalGrantClient {
   }
 
   async listGrants(tenant: string): Promise<PrincipalGrantListResult> {
-    const cred = await this.resolveOwnerCredential(tenant);
-    if (!cred) return notConfigured();
+    const assertion = await this.mintOwnerAssertion(tenant);
+    if (!assertion) return brokerNotConfigured();
     let res: HttpResponseLike;
     try {
-      // Credential travels in the Authorization header, never the query string.
+      // `tenant` is the ONLY query param — public routing data, and the only place
+      // tot20's listPrincipalGrants reads it. The credential stays in a header.
       res = await this.transport.get(
-        `${this.baseUrl}/api/clients/principalGrants`,
-        credentialAuthHeader(cred),
+        `${this.baseUrl}/api/clients/principalGrants?tenant=${encodeURIComponent(tenant)}`,
+        this.brokeredHeaders(assertion, true),
       );
     } catch (cause) {
       return transportFailure("listing principal grants", cause);
@@ -281,16 +333,17 @@ export class HttpPrincipalGrantClient implements PrincipalGrantClient {
   }
 
   async revokeGrant(tenant: string, ref: string): Promise<PrincipalGrantRevokeResult> {
-    const cred = await this.resolveOwnerCredential(tenant);
-    if (!cred) return notConfigured();
+    const assertion = await this.mintOwnerAssertion(tenant);
+    if (!assertion) return brokerNotConfigured();
     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.
+      // `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. `tenant` is
+      // the only query param; the credential stays in the Authorization header.
       res = await this.transport.delete(
-        `${this.baseUrl}/api/clients/principalGrants/${encodeURIComponent(ref)}`,
-        credentialAuthHeader(cred),
+        `${this.baseUrl}/api/clients/principalGrants/${encodeURIComponent(ref)}` +
+          `?tenant=${encodeURIComponent(tenant)}`,
+        this.brokeredHeaders(assertion, true),
       );
     } catch (cause) {
       return transportFailure("revoking principal grant", cause);
@@ -301,14 +354,14 @@ export class HttpPrincipalGrantClient implements PrincipalGrantClient {
   }
 }
 
-function notConfigured(): PrincipalGrantFailed {
+function brokerNotConfigured(): PrincipalGrantFailed {
   return {
     ok: false,
     status: 503,
-    reason: "ownerCredentialNotConfigured",
+    reason: "brokerNotConfigured",
     message:
-      "storefront has no owner credential to present to tot20 for this tenant yet " +
-      "(see the KNOWN GAP note in lib/shared/principalGrants.ts)",
+      "this storefront deploy cannot sign an owner assertion " +
+      `(${BROKER_PRIVATE_KEY_ENV} is not configured), so the request was not sent`,
   };
 }
 
@@ -366,12 +419,49 @@ function reasonFor(code: string | undefined, status: number): PrincipalGrantFail
       return "invalidPrincipal";
     case "operatorGrants:principalTypeNotSupported":
       return "principalTypeNotSupported";
+    // --- owner-brokered grantor path ---
+    case "operatorGrants:brokerAssertionRequired":
+      return "brokerAssertionRequired";
+    case "operatorGrants:brokerAssertionInvalid":
+      return "brokerAssertionInvalid";
+    // All three are the same class of storefront bug: the signed `tenant` claim and
+    // the tenant on the request did not line up. Collapsed so the UI has one story.
+    case "operatorGrants:assertionTenantRequired":
+    case "operatorGrants:tenantAssertionMismatch":
+    case "operatorGrants:tenantRequired":
+      return "assertionTenantMismatch";
+    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";
     default:
       if (status === 403 || status === 401) return "notAuthenticated";
       return "error";
   }
 }
 
+/**
+ * Turn a tot20 refusal into a typed failure. When we RECOGNISE the code we prefer
+ * our own operator-facing wording over tot20's — tot20's messages are written for
+ * an API integrator ("The broker assertion names a different tenant than the
+ * request."), which is noise to a merchant clicking Delegate. An unrecognised code
+ * keeps tot20's message, since that is the only signal we have.
+ */
+function failureFrom(
+  status: number,
+  c: Record<string, unknown>,
+): { status: number; reason: PrincipalGrantFailureReason; message: string; code?: string } {
+  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);
+  return { status, reason, message, ...(code ? { code } : {}) };
+}
+
 function defaultMessage(reason: PrincipalGrantFailureReason, status: number): string {
   switch (reason) {
     case "notAuthenticated":
@@ -384,8 +474,17 @@ function defaultMessage(reason: PrincipalGrantFailureReason, status: number): st
       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";
+    case "subjectNotTenantOwner":
+      return "only an owner of this store can delegate ship-on-behalf";
+    case "tenantNotRegistered":
+      return "this store isn't registered with Token of Trust";
+    case "brokerAssertionInvalid":
+      return "your session proof was rejected — sign in again and retry";
+    case "brokerAssertionRequired":
+    case "assertionTenantMismatch":
+      return "storefront sent a malformed delegation request — please report this";
+    case "brokerNotConfigured":
+      return "delegation isn't available on this deployment";
     default:
       return `principalGrants: tot20 returned status ${status}`;
   }
@@ -405,9 +504,7 @@ export function normalizeCreateResponse(status: number, body: unknown): Principa
       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 } : {}) };
+  return { ok: false, ...failureFrom(status, c) };
 }
 
 export function normalizeListResponse(status: number, tenant: string, body: unknown): PrincipalGrantListResult {
@@ -426,9 +523,7 @@ export function normalizeListResponse(status: number, tenant: string, body: unkn
     });
     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 } : {}) };
+  return { ok: false, ...failureFrom(status, c) };
 }
 
 export function normalizeRevokeResponse(status: number, tenant: string, body: unknown): PrincipalGrantRevokeResult {
@@ -438,9 +533,7 @@ export function normalizeRevokeResponse(status: number, tenant: string, body: un
   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 } : {}) };
+  return { ok: false, ...failureFrom(status, c) };
 }
 
 /** Map a typed failure onto the HTTP status a storefront route should return. */
@@ -452,8 +545,15 @@ export function principalGrantHttpStatus(reason: PrincipalGrantFailureReason, up
     case "unknownCapability":
     case "invalidPrincipal":
     case "principalTypeNotSupported":
+    case "brokerAssertionRequired":
+    case "assertionTenantMismatch":
+    case "tenantNotRegistered":
       return 422;
-    case "ownerCredentialNotConfigured":
+    case "brokerAssertionInvalid":
+      return 401;
+    case "subjectNotTenantOwner":
+      return 403;
+    case "brokerNotConfigured":
       return 503;
     default:
       return upstreamStatus >= 400 ? upstreamStatus : 502;
@@ -466,16 +566,26 @@ export function principalGrantHttpStatus(reason: PrincipalGrantFailureReason, up
 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>;
+  /** Tenants the signed-in subject does NOT own (tot20's `subjectNotTenantOwner`). */
+  private readonly notOwned: Set<string>;
 
-  constructor(unconfiguredTenants: string[] = []) {
-    this.unconfigured = new Set(unconfiguredTenants.map((t) => t.toLowerCase()));
+  constructor(notOwnedTenants: string[] = []) {
+    this.notOwned = new Set(notOwnedTenants.map((t) => t.toLowerCase()));
+  }
+
+  private refuseNotOwner(): PrincipalGrantFailed {
+    return {
+      ok: false,
+      status: 403,
+      reason: "subjectNotTenantOwner",
+      message: defaultMessage("subjectNotTenantOwner", 403),
+      code: "operatorGrants:subjectNotTenantOwner",
+    };
   }
 
   async createGrant(input: CreatePrincipalGrantInput): Promise<PrincipalGrantResult> {
     const tenant = input.tenant.toLowerCase();
-    if (this.unconfigured.has(tenant)) return notConfigured();
+    if (this.notOwned.has(tenant)) return this.refuseNotOwner();
     if (!input.expiresAt || input.expiresAt <= Date.now()) {
       return { ok: false, status: 422, reason: "expiresAtRequired", message: "a future expiresAt is required", code: "operatorGrants:expiresAtRequired" };
     }
@@ -490,7 +600,7 @@ export class MockPrincipalGrantClient implements PrincipalGrantClient {
 
   async listGrants(tenant: string): Promise<PrincipalGrantListResult> {
     const t = tenant.toLowerCase();
-    if (this.unconfigured.has(t)) return notConfigured();
+    if (this.notOwned.has(t)) return this.refuseNotOwner();
     const grants = [...this.grants.entries()]
       .filter(([ref]) => ref.startsWith(`mock-ref-${t}-`))
       .map(([ref, g]) => ({ ...g, ref }));
@@ -499,7 +609,7 @@ export class MockPrincipalGrantClient implements PrincipalGrantClient {
 
   async revokeGrant(tenant: string, ref: string): Promise<PrincipalGrantRevokeResult> {
     const t = tenant.toLowerCase();
-    if (this.unconfigured.has(t)) return notConfigured();
+    if (this.notOwned.has(t)) return this.refuseNotOwner();
     if (!ref.startsWith(`mock-ref-${t}-`) || !this.grants.has(ref)) {
       return { ok: false, status: 404, reason: "error", message: "no such grant" };
     }
@@ -511,17 +621,28 @@ export class MockPrincipalGrantClient implements PrincipalGrantClient {
 // --- 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.
+ * Build the env-configured client:
+ *   - `TOT_CORE_URL` — tot20 core API base (tier-matching per deploy).
+ *   - `TOT_API_KEY` (+ optional `TOT_SECRET_KEY`) — storefront's own operator creds.
+ *
+ * `mintOwnerAssertion` is a REQUIRED positional argument, not an override with a
+ * default: there is no safe default. A client built without it would send an
+ * unbrokered request that tot20 resolves to storefront's OWN store as grantor —
+ * silently granting on the wrong tenant. Making it structural means the caller must
+ * hold a verified owner session to build a client at all.
  */
 export async function createPrincipalGrantClient(
-  overrides: Partial<HttpPrincipalGrantClientConfig> = {},
+  mintOwnerAssertion: OwnerAssertionMinter,
+  overrides: Partial<Omit<HttpPrincipalGrantClientConfig, "mintOwnerAssertion">> = {},
 ): Promise<HttpPrincipalGrantClient> {
   const baseUrl = overrides.baseUrl ?? (await readEnv("TOT_CORE_URL")) ?? "";
+  const apiKey = overrides.apiKey ?? (await readEnv("TOT_API_KEY")) ?? "";
+  const secretKey = overrides.secretKey ?? (await readEnv("TOT_SECRET_KEY"));
   return new HttpPrincipalGrantClient({
     baseUrl,
-    resolveOwnerCredential: overrides.resolveOwnerCredential ?? (async () => null),
+    apiKey,
+    mintOwnerAssertion,
+    ...(secretKey ? { secretKey } : {}),
     ...(overrides.transport ? { transport: overrides.transport } : {}),
   });
 }