@tokenoftrust/storefront-runner 2.0.11 → 2.0.12

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

@@ -0,0 +1,96 @@
+/**
+ * The "Delegate ship-on-behalf" gate on /dashboard/<appDomain>/team, as a PURE
+ * decision — who sees the control, and what everyone else is told instead.
+ *
+ * The gate itself is unchanged and stays OWNER-ONLY: `/api/grants/principal`
+ * refuses anything but a real owner (mirroring tot20's `ownsTenant`), so showing
+ * the control to an admin would only ever produce a 403. What changes here is
+ * that every OTHER viewer now gets an explicit sentence naming their actual role,
+ * instead of the section vanishing with no explanation — a hidden control is
+ * indistinguishable from a broken one, and that ambiguity has already cost a
+ * live debugging session.
+ *
+ * Why staff get a REFUSAL and not a bypass: `ship-on-behalf` is a grant-required
+ * operation under `guidance://access-authority` — it is not required to keep the
+ * store's service running, so it runs on owner consent even when an admin or ToT
+ * staff performs it. Staff capture that consent and issue the grant with their
+ * own attestation on the record; they never self-serve it from a staff boolean.
+ * Do NOT "fix" the staff state by widening {@link resolveDelegateGate} to admit
+ * `mode: "staff"` — that is the confused-deputy hole the model exists to close.
+ *
+ * PURE (no I/O, no Astro) so all four states are unit-testable without rendering
+ * the page, matching `@/lib/dashboard/tenantSelection` and `@/lib/auth/loginGate`.
+ */
+import { membershipFor, staffAdmits } from "@/lib/dashboard/tenantSelection";
+import type { StaffAdmission, TenantMembership } from "@/lib/dashboard/tenantSelection";
+
+/**
+ * What the delegate section renders for this viewer.
+ *
+ * - `owner` — a real `tenants[]` membership with coarse role `owner`. The only
+ *   state that renders the control.
+ * - `member` — a real membership that is not owner (`admin`, `member`, …).
+ * - `staff` — no real membership; admitted by a LIVE ToT-staff vendor selection.
+ *   `role` is the selection's capability, not a membership role.
+ * - `none` — neither. Unreachable from team.astro (its `membershipFor` guard
+ *   redirects to /dashboard first), but represented so the function is total and
+ *   no input can ever produce a silently blank section.
+ */
+export type DelegateGate =
+  | { mode: "owner" }
+  | { mode: "member"; role: string; explanation: string }
+  | { mode: "staff"; role: string; explanation: string }
+  | { mode: "none"; role: null; explanation: string };
+
+/**
+ * Resolve the delegate gate for a viewer.
+ *
+ * Order matters and mirrors {@link membershipFor}: a REAL membership always wins
+ * over a staff selection, so a ToT staffer who is also a genuine owner of this
+ * store is treated as the owner they are. Only a viewer with no membership at all
+ * falls through to the staff branch.
+ *
+ * The role string is surfaced verbatim in the explanation on purpose. The coarse
+ * role reaching `tenants[]` is the end of a five-hop chain (tot20 `appSpec.users`
+ * → `collapseCapability` → `coarseRole` → the signed id_token → the storefront's
+ * `coerceRole`, which defaults anything unrecognised to `member`). Naming the
+ * value the page actually received turns "why is this hidden?" into a one-glance
+ * answer instead of a trace through both repos.
+ */
+export function resolveDelegateGate(
+  tenants: readonly TenantMembership[] | undefined,
+  resource: string,
+  staff?: StaffAdmission,
+): DelegateGate {
+  const target = (resource ?? "").trim();
+  const membership = membershipFor(tenants, target);
+  if (membership) {
+    if (membership.role === "owner") return { mode: "owner" };
+    return {
+      mode: "member",
+      role: membership.role,
+      explanation:
+        `Only the store owner can delegate ship-on-behalf. Your role on ${target} is ` +
+        `“${membership.role}”. Ask an owner to set up the delegation, or to make you one.`,
+    };
+  }
+
+  if (staffAdmits(staff, target)) {
+    const role = staff!.selection!.capability;
+    return {
+      mode: "staff",
+      role,
+      explanation:
+        `You’re here through Token of Trust staff access (“${role}”), not as a member of ` +
+        `${target}. Delegating ship-on-behalf is the owner’s own control, so it isn’t ` +
+        `offered here — capture the owner’s consent and issue the grant on their behalf instead.`,
+    };
+  }
+
+  return {
+    mode: "none",
+    role: null,
+    explanation:
+      `You don’t hold a role on ${target}, so ship-on-behalf delegation isn’t available here.`,
+  };
+}

package/package.json

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