@tokenoftrust/storefront-runner 0.1.0

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

@@ -0,0 +1,449 @@
+/**
+ * StaffVendorAccessClient — the storefront's seam to tot20's two ToT-STAFF
+ * cross-vendor endpoints (#8425 staff access). A ToT-staff user isn't a member of
+ * a bounded set of vendors; they reach ANY vendor by explicit SEARCH-and-ENTER.
+ * Both endpoints are operator-authed (storefront's OWN per-tier credentials) and
+ * PROVE the staff actor with a storefront-signed BROKER ASSERTION in the
+ * `X-ToT-Broker-Assertion` header (#8453 `staff-invite-proof-via-broker`) — NOT a
+ * plaintext email field (spoofable, removed). tot20 verifies the assertion, derives
+ * the staff actor from its `sub`, scopes the capability to that user's staffRoles,
+ * and writes the server-side AUDIT row.
+ *
+ *   GET  /api/clients/vendorSearch?q=<prefix>&limit=<n>   (operator secretKey; staff via header)
+ *        → { content: { code, vendors: [{ appDomain, displayName }] } }
+ *   POST /api/clients/staffVendorAccess { vendorAppDomain }  (operator secretKey; staff via header)
+ *        → { content: { code, capability } }   (WRITES the audit row; capability is
+ *          staffRoles-scoped)
+ *
+ * AUTH WIRE (mirrors `@/lib/grants/developerInvites` + `@/lib/auth/totAccessClient`,
+ * verified against live qa): tot20's swagger `normalizeSecureUserRequest` extracts
+ * machine creds from the request BODY/QUERY fields `totApiKey`/`totSecretKey`, NOT
+ * custom `x-tot-*` headers. That is the ONLY integration-sensitive spot
+ * ({@link credentialFields}). tot20 wraps every response in a `{ content, metadata }`
+ * envelope.
+ *
+ * TIER: host + operator credential are per-DEPLOY env (`TOT_CORE_URL` +
+ * `TOT_API_KEY`/`TOT_SECRET_KEY`) — the SAME env the sibling access + invite
+ * clients read; no hardcoded hosts, no secrets in code.
+ *
+ * Built like `@/lib/grants/developerInvites` (interface + Http impl + Mock + env
+ * factory) so the routes develop/test against `MockStaffVendorAccessClient` and
+ * swap in the Http client with no call-site change.
+ */
+import { readEnv } from "@/lib/env";
+import { decodeJwt } from "jose";
+
+/**
+ * The header carrying the storefront-signed staff BROKER ASSERTION to tot20 (#8453
+ * `staff-invite-proof-via-broker`). The staff actor is PROVEN by this signed JWT,
+ * not by a plaintext `email` field (which was spoofable and has been removed from
+ * the wire). Minted server-side (`@/lib/auth/brokerAssertion`) from the verified
+ * `session.email`; tot20 verifies signature + replay and derives the staff actor
+ * from the VERIFIED `sub`, scopes the capability to their staffRoles, and writes
+ * the audit row. The literal is inlined (not imported) to keep this module's
+ * transport seam self-contained, mirroring the sibling grants client.
+ */
+const BROKER_ASSERTION_HEADER = "X-ToT-Broker-Assertion";
+
+/** One vendor hit from a search — the minimum needed to render + select. */
+export interface VendorHit {
+  appDomain: string;
+  displayName: string;
+}
+
+/** Result of a vendor search (typed failure, fail-closed). */
+export type VendorSearchResult =
+  | { ok: true; vendors: VendorHit[] }
+  | { ok: false; status: number; reason: StaffAccessFailureReason; message: string; code?: string };
+
+/** Result of a staff-vendor-access grant — the staffRoles-scoped capability. */
+export type StaffVendorAccessResult =
+  | { ok: true; capability: string }
+  | { ok: false; status: number; reason: StaffAccessFailureReason; message: string; code?: string };
+
+/** Typed failure reasons mapped from tot20's error codes / HTTP status. */
+export type StaffAccessFailureReason =
+  | "notStaff" // 403 — the email holds no ToT-staff scope (server-authoritative)
+  | "notFound" // 404/422 — the vendor appDomain isn't a resolvable app
+  | "invalid" // 400/422 — bad/empty query or vendor
+  | "notAuthenticated" // 401/403 — storefront's operator credential was rejected
+  | "error"; // transport / unexpected upstream fault
+
+export interface StaffVendorAccessClient {
+  /**
+   * Search vendors by appDomain prefix. `brokerAssertion` is the storefront-signed
+   * staff proof (presented in the `X-ToT-Broker-Assertion` header); tot20 derives
+   * the staff actor from its verified `sub` and scopes results to their staffRoles.
+   */
+  searchVendors(brokerAssertion: string, query: string, limit?: number): Promise<VendorSearchResult>;
+  /**
+   * Admit the staff actor (proven by `brokerAssertion`) to `vendorAppDomain`: tot20
+   * verifies the assertion, writes the audit row, and returns the staffRoles-scoped
+   * capability. Called on explicit enter, never a silent per-host grant.
+   */
+  grantStaffAccess(brokerAssertion: string, vendorAppDomain: string): Promise<StaffVendorAccessResult>;
+}
+
+// --- HTTP transport seam (injected by tests) --------------------------------
+
+export interface HttpResponseLike {
+  status: number;
+  json(): Promise<unknown>;
+}
+export interface HttpTransport {
+  get(url: string, headers: Record<string, string>): Promise<HttpResponseLike>;
+  post(url: string, headers: Record<string, string>, body: unknown): Promise<HttpResponseLike>;
+}
+
+/** Default transport: JSON `fetch` GET/POST. */
+export class FetchHttpTransport implements HttpTransport {
+  async get(url: string, headers: Record<string, string>) {
+    return fetch(url, { method: "GET", headers: { accept: "application/json", ...headers } });
+  }
+  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),
+    });
+  }
+}
+
+export interface HttpStaffVendorAccessClientConfig {
+  /** tot20 core API base (no trailing slash), e.g. https://qa.tokenoftrust.com */
+  baseUrl: string;
+  /** Storefront's OWN per-tier ToT credentials (machine auth to the operator API). */
+  apiKey: string;
+  secretKey?: string;
+  transport?: HttpTransport;
+  /** Default result cap when a caller passes no limit. */
+  defaultLimit?: number;
+}
+
+export class StaffVendorAccessClientError extends Error {}
+
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 50;
+
+/** Clamp a caller-supplied limit into (0, MAX_LIMIT], defaulting when absent/bad. */
+function clampLimit(limit: number | undefined, fallback: number): number {
+  const n = typeof limit === "number" ? Math.floor(limit) : NaN;
+  if (!Number.isFinite(n) || n <= 0) return fallback;
+  return Math.min(n, MAX_LIMIT);
+}
+
+// --- HTTP impl --------------------------------------------------------------
+
+export class HttpStaffVendorAccessClient implements StaffVendorAccessClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly secretKey?: string;
+  private readonly transport: HttpTransport;
+  private readonly defaultLimit: number;
+
+  constructor(config: HttpStaffVendorAccessClientConfig) {
+    if (!config.baseUrl) {
+      throw new StaffVendorAccessClientError("staffVendorAccess: TOT_CORE_URL is not configured");
+    }
+    if (!config.apiKey) {
+      throw new StaffVendorAccessClientError(
+        "staffVendorAccess: storefront ToT credentials are not configured",
+      );
+    }
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.secretKey = config.secretKey;
+    this.transport = config.transport ?? new FetchHttpTransport();
+    this.defaultLimit = clampLimit(config.defaultLimit, DEFAULT_LIMIT);
+  }
+
+  /**
+   * The one integration-sensitive spot: tot20 reads `totApiKey`/`totSecretKey`
+   * from the request body/query (`normalizeSecureUserRequest`). Swap for a
+   * machine-JWT `Authorization: Bearer` here if tot20 ever requires it.
+   */
+  private credentialFields(): Record<string, string> {
+    const f: Record<string, string> = { totApiKey: this.apiKey };
+    if (this.secretKey) f.totSecretKey = this.secretKey;
+    return f;
+  }
+
+  async searchVendors(brokerAssertion: string, query: string, limit?: number): Promise<VendorSearchResult> {
+    const q = (query ?? "").trim();
+    if (!q) return { ok: true, vendors: [] }; // empty prefix → nothing to search
+    // #8453 `staff-invite-proof-via-broker`: the staff actor is proven by the signed
+    // assertion header — NEVER a plaintext `email` query param.
+    const params = new URLSearchParams({
+      q,
+      limit: String(clampLimit(limit, this.defaultLimit)),
+      ...this.credentialFields(),
+    });
+    const headers: Record<string, string> = {};
+    if (brokerAssertion) headers[BROKER_ASSERTION_HEADER] = brokerAssertion;
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.get(`${this.baseUrl}/api/clients/vendorSearch?${params.toString()}`, headers);
+    } catch (cause) {
+      return {
+        ok: false,
+        status: 0,
+        reason: "error",
+        message:
+          "staffVendorAccess: transport failure searching vendors " +
+          (cause instanceof Error ? cause.message : String(cause)),
+      };
+    }
+    let parsed: unknown;
+    try {
+      parsed = await res.json();
+    } catch {
+      return {
+        ok: false,
+        status: res.status,
+        reason: "error",
+        message: `staffVendorAccess: tot20 returned a non-JSON body (status ${res.status})`,
+      };
+    }
+    return normalizeVendorSearch(res.status, parsed);
+  }
+
+  async grantStaffAccess(brokerAssertion: string, vendorAppDomain: string): Promise<StaffVendorAccessResult> {
+    const vendor = (vendorAppDomain ?? "").trim();
+    if (!vendor) {
+      return { ok: false, status: 400, reason: "invalid", message: "a vendor appDomain is required" };
+    }
+    // #8453 `staff-invite-proof-via-broker`: the staff actor is proven by the signed
+    // assertion header — NEVER a plaintext `email` body field.
+    const headers: Record<string, string> = {};
+    if (brokerAssertion) headers[BROKER_ASSERTION_HEADER] = brokerAssertion;
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.post(
+        `${this.baseUrl}/api/clients/staffVendorAccess`,
+        headers,
+        { vendorAppDomain: vendor, ...this.credentialFields() },
+      );
+    } catch (cause) {
+      return {
+        ok: false,
+        status: 0,
+        reason: "error",
+        message:
+          "staffVendorAccess: transport failure granting access " +
+          (cause instanceof Error ? cause.message : String(cause)),
+      };
+    }
+    let parsed: unknown;
+    try {
+      parsed = await res.json();
+    } catch {
+      return {
+        ok: false,
+        status: res.status,
+        reason: "error",
+        message: `staffVendorAccess: tot20 returned a non-JSON body (status ${res.status})`,
+      };
+    }
+    return normalizeStaffAccess(res.status, parsed);
+  }
+}
+
+/** Unwrap tot20's `{ content, metadata }` envelope (fall back to the raw body). */
+function unwrap(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>;
+}
+
+/** Parse tot20's vendorSearch response into a typed result (fail closed). */
+export function normalizeVendorSearch(status: number, body: unknown): VendorSearchResult {
+  const c = unwrap(body);
+  const code = typeof c.code === "string" ? c.code : undefined;
+  const isOk =
+    code === "vendorSearch:ok" || (status >= 200 && status < 300 && Array.isArray(c.vendors));
+  if (isOk) {
+    const vendors: VendorHit[] = (Array.isArray(c.vendors) ? c.vendors : [])
+      .map((raw2) => {
+        const r = (raw2 ?? {}) as Record<string, unknown>;
+        const appDomain = typeof r.appDomain === "string" ? r.appDomain : "";
+        return {
+          appDomain,
+          displayName: typeof r.displayName === "string" && r.displayName ? r.displayName : appDomain,
+        };
+      })
+      .filter((v) => v.appDomain);
+    return { ok: true, vendors };
+  }
+  return failure(status, c);
+}
+
+/** Parse tot20's staffVendorAccess response into a typed result (fail closed). */
+export function normalizeStaffAccess(status: number, body: unknown): StaffVendorAccessResult {
+  const c = unwrap(body);
+  const code = typeof c.code === "string" ? c.code : undefined;
+  const isOk =
+    code === "staffVendorAccess:granted" ||
+    (status >= 200 && status < 300 && typeof c.capability === "string");
+  if (isOk) {
+    return { ok: true, capability: typeof c.capability === "string" ? c.capability : "staff" };
+  }
+  return failure(status, c);
+}
+
+/** Map an error envelope onto a typed failure by tot20 `code` then HTTP status. */
+function failure(
+  status: number,
+  c: Record<string, unknown>,
+): { ok: false; status: number; reason: StaffAccessFailureReason; message: string; code?: string } {
+  const code = typeof c.code === "string" ? c.code : undefined;
+  const message = typeof c.message === "string" ? c.message : undefined;
+  const reason = reasonFor(code, status);
+  return { ok: false, status, reason, message: message ?? defaultMessage(reason, status), ...(code ? { code } : {}) };
+}
+
+function reasonFor(code: string | undefined, status: number): StaffAccessFailureReason {
+  switch (code) {
+    case "staffVendorAccess:notStaff":
+      return "notStaff";
+    case "staffVendorAccess:vendorNotFound":
+    case "vendorSearch:vendorNotFound":
+      return "notFound";
+    case "staffVendorAccess:invalid":
+    case "vendorSearch:invalid":
+      return "invalid";
+    case "operatorGrants:notAuthenticated":
+      return "notAuthenticated";
+    default:
+      if (status === 401) return "notAuthenticated";
+      if (status === 403) return "notStaff";
+      if (status === 404) return "notFound";
+      if (status === 400 || status === 422) return "invalid";
+      return "error";
+  }
+}
+
+/**
+ * Map a typed failure onto the HTTP status a storefront endpoint should return:
+ * notStaff/notAuthenticated → 403; notFound → 404; invalid → 400; a transport /
+ * unexpected fault → the upstream status if it's an error, else 502.
+ */
+export function staffAccessHttpStatus(reason: StaffAccessFailureReason, upstreamStatus: number): number {
+  switch (reason) {
+    case "notStaff":
+    case "notAuthenticated":
+      return 403;
+    case "notFound":
+      return 404;
+    case "invalid":
+      return 400;
+    default:
+      return upstreamStatus >= 400 ? upstreamStatus : 502;
+  }
+}
+
+function defaultMessage(reason: StaffAccessFailureReason, status: number): string {
+  switch (reason) {
+    case "notStaff":
+      return "this account doesn't hold ToT-staff access to that vendor";
+    case "notAuthenticated":
+      return "storefront's operator credential was rejected";
+    case "notFound":
+      return "that vendor is not a resolvable Token of Trust app";
+    case "invalid":
+      return "a valid vendor is required";
+    default:
+      return `staffVendorAccess: tot20 returned status ${status}`;
+  }
+}
+
+// --- Mock (tests + local dev) -----------------------------------------------
+
+/**
+ * In-memory StaffVendorAccessClient. Seeded with a directory of vendors and the
+ * set of staff emails, it drives route + client tests deterministically and lets
+ * local dev exercise the search+enter flow before/without the live tot20 endpoint.
+ */
+export class MockStaffVendorAccessClient implements StaffVendorAccessClient {
+  private readonly vendors: VendorHit[];
+  private readonly staff: Set<string>;
+  private readonly capability: string;
+  /** Recorded admissions, for assertions (the audit row tot20 would write). */
+  granted: Array<{ email: string; vendorAppDomain: string }> = [];
+
+  constructor(opts: { vendors?: VendorHit[]; staffEmails?: string[]; capability?: string } = {}) {
+    this.vendors = opts.vendors ?? [];
+    this.staff = new Set((opts.staffEmails ?? []).map((e) => e.toLowerCase()));
+    this.capability = opts.capability ?? "staff";
+  }
+
+  /**
+   * Derive the staff actor's email from the broker assertion's `sub` — simulating
+   * tot20 deriving it from the VERIFIED assertion. The Mock only DECODES (never
+   * verifies the signature); the real tot20 verifies. Returns "" for an
+   * absent/malformed assertion so a proofless call fails the staff check.
+   */
+  private actorEmail(brokerAssertion: string): string {
+    if (!brokerAssertion || !brokerAssertion.trim()) return "";
+    try {
+      const sub = decodeJwt(brokerAssertion).sub;
+      return typeof sub === "string" ? sub.toLowerCase() : "";
+    } catch {
+      return "";
+    }
+  }
+
+  async searchVendors(_brokerAssertion: string, query: string, limit?: number): Promise<VendorSearchResult> {
+    const q = (query ?? "").trim().toLowerCase();
+    if (!q) return { ok: true, vendors: [] };
+    const cap = clampLimit(limit, DEFAULT_LIMIT);
+    const vendors = this.vendors
+      .filter(
+        (v) =>
+          v.appDomain.toLowerCase().startsWith(q) || v.displayName.toLowerCase().includes(q),
+      )
+      .slice(0, cap);
+    return { ok: true, vendors };
+  }
+
+  async grantStaffAccess(brokerAssertion: string, vendorAppDomain: string): Promise<StaffVendorAccessResult> {
+    const vendor = (vendorAppDomain ?? "").trim();
+    if (!vendor) return { ok: false, status: 400, reason: "invalid", message: "a vendor appDomain is required" };
+    const email = this.actorEmail(brokerAssertion);
+    if (!email || !this.staff.has(email)) {
+      return {
+        ok: false,
+        status: 403,
+        reason: "notStaff",
+        message: "this account doesn't hold ToT-staff access to that vendor",
+        code: "staffVendorAccess:notStaff",
+      };
+    }
+    if (!this.vendors.some((v) => v.appDomain === vendor)) {
+      return {
+        ok: false,
+        status: 404,
+        reason: "notFound",
+        message: "that vendor is not a resolvable Token of Trust app",
+        code: "staffVendorAccess:vendorNotFound",
+      };
+    }
+    this.granted.push({ email, vendorAppDomain: vendor });
+    return { ok: true, capability: this.capability };
+  }
+}
+
+// --- Factory ----------------------------------------------------------------
+
+/**
+ * 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.
+ * Throws {@link StaffVendorAccessClientError} when unconfigured (routes map that to 503).
+ */
+export async function createStaffVendorAccessClient(
+  overrides: Partial<HttpStaffVendorAccessClientConfig> = {},
+): Promise<HttpStaffVendorAccessClient> {
+  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 HttpStaffVendorAccessClient({ ...overrides, baseUrl, apiKey, secretKey });
+}

package/apps/storefront/src/lib/dashboard/tenantSelection.ts

@@ -0,0 +1,136 @@
+/**
+ * Vendor (tenant/appDomain) selection — the L3 consumer pattern from
+ * docs/architecture/identity-and-authorization.md: an app renders tenant
+ * selection FROM the verified id_token's tenant claims. Single membership → go
+ * straight into that vendor; multiple → show a picker; none → nothing to manage.
+ *
+ * PURE (no I/O, no Astro) so the single-vs-picker routing and the "does this
+ * viewer have access to vendor X" authorization are unit-testable in isolation.
+ * The session's `tenants: {resource, role}[]` (minted from the offline-verified
+ * assertion — see `@/lib/auth/identityToken` `sessionFromClaims`) is the sole
+ * input; the storefront holds no membership state of its own (L3 constraint #4).
+ *
+ * STAGE-0 NOTE (tot20 dependency): today tot20's access-code id_token carries only
+ * the ONE resource the code was verified against (identityAssertion.buildClaims),
+ * so `tenants[]` has a single entry and this resolves to `single` in practice. The
+ * `picker` branch is built to the locked contract and activates unchanged once
+ * tot20 populates all of the email's memberships. Flagged to the workstream lead.
+ */
+
+import type { StaffSelection } from "@/lib/auth/session";
+
+/** One tenant membership carried in the verified session. */
+export interface TenantMembership {
+  resource: string;
+  role: string;
+}
+
+/**
+ * The ToT-staff admission path — DISTINCT from `tenants[]`. A staff viewer reaches
+ * a vendor by explicit search-and-enter (never by membership), so access is
+ * decided from their active {@link StaffSelection} + the current time, NOT from a
+ * synthesized membership. `viewerCanAccess`/`membershipFor` take this as an
+ * optional extra source; when omitted they behave exactly as before (membership
+ * only), so non-staff callers are unchanged.
+ */
+export interface StaffAdmission {
+  /** The staff viewer's active selection (from the session), if any. */
+  selection: StaffSelection | undefined;
+  /** Current time (epoch seconds) for the selection's expiry check. */
+  nowSeconds: number;
+}
+
+/**
+ * True when a staff admission is LIVE for `resource`: a selection exists, targets
+ * this exact vendor, and has not expired. Deny-closed on every other case. This
+ * is the sole staff-side authorization primitive — a distinct branch from the
+ * membership check, and it never consults `tenants[]`.
+ */
+export function staffAdmits(
+  admission: StaffAdmission | undefined,
+  resource: string,
+): boolean {
+  if (!admission?.selection) return false;
+  const target = (resource ?? "").trim();
+  if (!target) return false;
+  return (
+    admission.selection.resource === target &&
+    admission.selection.exp > admission.nowSeconds
+  );
+}
+
+/** Where a signed-in viewer should land based on their memberships. */
+export type TenantSelection =
+  | { mode: "none" }
+  | { mode: "single"; tenant: TenantMembership }
+  | { mode: "picker"; tenants: TenantMembership[] };
+
+/** De-dupe memberships by resource (keep first), dropping malformed entries. */
+function normalizeMemberships(
+  tenants: readonly TenantMembership[] | undefined,
+): TenantMembership[] {
+  const seen = new Set<string>();
+  const out: TenantMembership[] = [];
+  for (const t of tenants ?? []) {
+    const resource = typeof t?.resource === "string" ? t.resource.trim() : "";
+    if (!resource || seen.has(resource)) continue;
+    seen.add(resource);
+    out.push({ resource, role: typeof t.role === "string" ? t.role : "member" });
+  }
+  return out;
+}
+
+/**
+ * Decide the vendor-selection outcome for a viewer's memberships:
+ *   0 → `none`, 1 → `single` (navigate straight in), ≥2 → `picker`.
+ */
+export function selectTenant(
+  tenants: readonly TenantMembership[] | undefined,
+): TenantSelection {
+  const members = normalizeMemberships(tenants);
+  const [first, ...rest] = members;
+  if (!first) return { mode: "none" };
+  if (rest.length === 0) return { mode: "single", tenant: first };
+  return { mode: "picker", tenants: members };
+}
+
+/**
+ * Whether the viewer may act on `resource` — i.e. holds a membership for that
+ * vendor. The near-side authorization for every dashboard action; the far side
+ * (tot20 `hasOperatorGrant(storefront, tenant)`) is enforced independently.
+ * Deny-by-default: no membership, no access.
+ */
+export function viewerCanAccess(
+  tenants: readonly TenantMembership[] | undefined,
+  resource: string,
+  staff?: StaffAdmission,
+): boolean {
+  const target = (resource ?? "").trim();
+  if (!target) return false;
+  if (normalizeMemberships(tenants).some((t) => t.resource === target)) return true;
+  // DISTINCT staff path: a live staff selection for THIS vendor admits, without
+  // any `tenants[]` membership. Omitted `staff` → membership-only (unchanged).
+  return staffAdmits(staff, target);
+}
+
+/**
+ * The viewer's membership for `resource`, or null. When a `staff` admission is
+ * supplied and no real membership exists, a LIVE staff selection for this vendor
+ * yields a staff-derived stand-in `{ resource, role: capability }` so the guard
+ * has a role/capability to render — this is NOT a `tenants[]` entry and is never
+ * persisted as one (the distinct-path invariant).
+ */
+export function membershipFor(
+  tenants: readonly TenantMembership[] | undefined,
+  resource: string,
+  staff?: StaffAdmission,
+): TenantMembership | null {
+  const target = (resource ?? "").trim();
+  if (!target) return null;
+  const member = normalizeMemberships(tenants).find((t) => t.resource === target);
+  if (member) return member;
+  if (staffAdmits(staff, target)) {
+    return { resource: target, role: staff!.selection!.capability };
+  }
+  return null;
+}

package/apps/storefront/src/lib/dashboard/vendorQuery.ts

@@ -0,0 +1,61 @@
+/**
+ * Anchor syntax for the ToT-STAFF vendor search (#8425). tot20's vendorSearch does a
+ * plain SUBSTRING match over appDomain OR displayName, so a common term like
+ * `tokenoftrust.com` surfaces every subdomain/displayName that contains it and buries
+ * (or caps out) the one exact hit. These anchors let a staffer narrow it, mirroring
+ * regex/grep intuition — but they are LITERAL anchors, not a regex engine:
+ *
+ *   ^acme.com    → appDomain STARTS WITH "acme.com"
+ *   acme.com$    → appDomain ENDS WITH "acme.com"
+ *   ^acme.com$   → appDomain EXACTLY "acme.com"
+ *   acme         → unchanged substring search (appDomain OR displayName, tot20-side)
+ *
+ * Anchors match the **appDomain** only (the domain the operator is targeting), case-
+ * insensitively. Only a leading `^` and a trailing `$` are treated as anchors; the
+ * characters elsewhere are literal. The core term (anchors stripped) is what we send
+ * upstream, so tot20 still returns a superset we filter locally.
+ */
+
+/** Upstream fetch cap for an anchored query — widened so the exact hit is in the set we filter. */
+export const ANCHORED_FETCH_LIMIT = 50;
+
+/** Max rows returned to the client after an anchored post-filter (the visible autocomplete list). */
+export const ANCHORED_DISPLAY_LIMIT = 10;
+
+export interface ParsedVendorQuery {
+  /** The search term with any anchors stripped — what we send upstream to tot20. */
+  core: string;
+  /** True when `^`/`$` anchors are present AND there is a non-empty core to match. */
+  anchored: boolean;
+  /** Predicate applied to a vendor `appDomain` when `anchored` (always true otherwise). */
+  matches: (appDomain: string) => boolean;
+}
+
+/**
+ * Parse a raw search string into its core term + an anchor predicate. Pure + total:
+ * a bare `^`, `$`, or `^$` (no core) yields `anchored:false` and an empty core, so the
+ * caller sends an empty query upstream (→ no results) rather than matching everything.
+ */
+export function parseVendorQuery(raw: string): ParsedVendorQuery {
+  const q = (raw ?? "").trim();
+  const start = q.startsWith("^");
+  const end = q.endsWith("$");
+  let core = q;
+  if (start) core = core.slice(1);
+  if (end) core = core.slice(0, core.length - 1);
+  core = core.trim();
+  const needle = core.toLowerCase();
+  const anchored = (start || end) && core.length > 0;
+
+  let matches: (appDomain: string) => boolean;
+  if (start && end) {
+    matches = (d) => (d ?? "").toLowerCase() === needle;
+  } else if (start) {
+    matches = (d) => (d ?? "").toLowerCase().startsWith(needle);
+  } else if (end) {
+    matches = (d) => (d ?? "").toLowerCase().endsWith(needle);
+  } else {
+    matches = () => true;
+  }
+  return { core, anchored, matches };
+}