@tokenoftrust/storefront-runner 2.0.21 → 2.0.23

package/apps/storefront/src/lib/activity/uiActor.ts

@@ -51,11 +51,9 @@ import type { ActionKey } from "@tot/public-runtime";
 import { readViewerSession } from "@/lib/auth/route";
 import { isStaffSession } from "@/lib/dashboard/staffAdmission";
 import { readEnv } from "@/lib/env";
+import { isOwnerCapability } from "@/lib/shared/capability";
 import { hashActorId, recordActivity } from "./recordActivity";
 
-/** The host-bound capabilities that mark a viewer as the store OWNER (merchant). */
-const OWNER_CAPABILITIES = new Set(["owner", "admin"]);
-
 /** The minimal viewer chrome the middleware stamps on `locals.viewer`. */
 interface ViewerLike {
   email?: string;
@@ -81,7 +79,7 @@ export function classifyActorKind(
 ): ActorKind {
   if (!viewer?.email) return "agent";
   if (isStaffSession(session)) return "admin";
-  if (viewer.capability && OWNER_CAPABILITIES.has(viewer.capability)) return "merchant";
+  if (isOwnerCapability(viewer.capability)) return "merchant";
   return "dev";
 }
 

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

@@ -32,8 +32,8 @@ import type { SessionRecord } from "./session.js";
 import { sessionHostCapability } from "./loginGate.js";
 import {
   decideIsOwner,
+  isOwnerCapability,
   resolveShipCapabilities,
-  OWNER_CAPABILITIES,
   type Capability,
   type ShipCapabilities,
 } from "@/lib/shared/capability";
@@ -108,7 +108,7 @@ export function resolveAdminEntry(input: {
   const principal: AdminEntryPrincipal = !record
     ? "anonymous"
     : hostCapability
-      ? OWNER_CAPABILITIES.has(hostCapability)
+      ? isOwnerCapability(hostCapability)
         ? (hostCapability as "owner" | "admin")
         : "member"
       : staffScope

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

@@ -77,7 +77,7 @@ export async function devSessionFields(
   const resource = (await readEnv("STOREFRONT_APP_DOMAIN")) || "storefront";
   const tenants = devTenantResources().map((resource) => ({
     resource,
-    role: "developer",
+    role: "member" as const,
   }));
   return {
     email: email.toLowerCase(),

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

@@ -27,6 +27,11 @@ import {
   type JSONWebKeySet,
 } from "jose";
 import { readEnv } from "@/lib/env";
+import {
+  TENANT_ROLES,
+  isTenantRole,
+  type TenantRole,
+} from "@/lib/shared/capability";
 
 /** tot's issuer — consumers pin/allowlist this (`auth.jwt.issuer`). */
 export const TOT_ISSUER = "tokenoftrust-internal-ops";
@@ -45,7 +50,13 @@ export const JWKS_PATH = "/api/.well-known/jwks.json";
  * (`developer`/`inviter`/none → `member`). Org standing only; finer granularity
  * is the storefront's own job to derive locally (Phase-4 PDP work).
  */
-export type CoarseRole = "owner" | "admin" | "member";
+export const COARSE_ROLES = TENANT_ROLES;
+export type CoarseRole = TenantRole;
+
+/** Runtime counterpart to the closed coarse-role type. */
+export function isCoarseRole(value: unknown): value is CoarseRole {
+  return isTenantRole(value);
+}
 
 /** A single tenant membership carried in the assertion. */
 export interface TenantMembership {
@@ -90,7 +101,7 @@ export interface IdentityClaims {
 
 /** Coarse-role collapse guard: anything tot didn't send as owner/admin → member. */
 function coerceRole(role: unknown): CoarseRole {
-  return role === "owner" || role === "admin" ? role : "member";
+  return isCoarseRole(role) ? role : "member";
 }
 
 /**

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

@@ -16,8 +16,22 @@
 /** Access level the acting operator holds. */
 export type Capability = "preview-access" | "ship-on-behalf";
 
+/** Complete tenant-role vocabulary emitted by verified identity assertions. */
+export const TENANT_ROLES = ["owner", "admin", "member"] as const;
+export type TenantRole = (typeof TENANT_ROLES)[number];
+
+export function isTenantRole(value: unknown): value is TenantRole {
+  return typeof value === "string" && (TENANT_ROLES as readonly string[]).includes(value);
+}
+
 /** Capabilities that carry tenant-owner standing (vs. a granted developer). */
-export const OWNER_CAPABILITIES: ReadonlySet<string> = new Set(["owner", "admin"]);
+export const OWNER_CAPABILITY_VALUES = ["owner", "admin"] as const satisfies readonly TenantRole[];
+export type OwnerCapability = (typeof OWNER_CAPABILITY_VALUES)[number];
+export const OWNER_CAPABILITIES: ReadonlySet<string> = new Set(OWNER_CAPABILITY_VALUES);
+
+export function isOwnerCapability(value: unknown): value is OwnerCapability {
+  return typeof value === "string" && OWNER_CAPABILITIES.has(value);
+}
 
 /** Pure inputs to the owner-principal decision (session only, no I/O). */
 export interface OwnerPrincipalInput {
@@ -34,7 +48,7 @@ export interface OwnerPrincipalInput {
  */
 export function decideIsOwner(input: OwnerPrincipalInput): boolean {
   if (!input.authorized) return false;
-  return !!input.viewerCapability && OWNER_CAPABILITIES.has(input.viewerCapability);
+  return isOwnerCapability(input.viewerCapability);
 }
 
 /**

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

@@ -0,0 +1,166 @@
+/**
+ * Viewer ship-grant resolver (security-critical) — resolve a signed-in developer
+ * VIEWER's REAL, owner-revocable ship capability over a tenant, LIVE from the MCP
+ * subject-capability store. This is the near-side read of the Step-1 tot-mcp seam:
+ *
+ *   GET `${origin}/api/internal/dev-access/subject-capability?subject=<email>&tenant=<appDomain>&app=storefront`
+ *   Auth: header `x-mcp-service-secret: <MCP_SERVICE_SHARED_SECRET>` (NOT a bearer)
+ *   → 200 { capability: "ship-on-behalf" | "preview-access" }
+ *        · an ABSENT / REVOKED grant answers `preview-access`
+ *        · a store fault answers 502
+ *
+ * WHY it exists (the security constraint): a normally-invited developer's COARSE
+ * role is `preview-access`, NOT ship — the coarse "developer" role collapses to
+ * member. ship-on-behalf is a SEPARATE, explicit, OWNER-REVOCABLE grant. So the
+ * viewer/browser ship path must NEVER map the coarse role → ship and must NEVER
+ * trust a client-supplied `x-tot-capability` header; it resolves the REAL grant
+ * here, LIVE (no cache that could outlive a revoke).
+ *
+ * FAIL-CLOSED, TOTAL, NEVER THROWS: an unconfigured seam (no URL/secret), a missing
+ * subject/tenant, any non-2xx (INCLUDING 502), an unparseable body, an unexpected
+ * capability value, or a transport/timeout fault ALL resolve to `preview-access` —
+ * the deny default. Only an explicit `200 { capability: "ship-on-behalf" }` grants
+ * ship. This mirrors `dev/previewStatus.ts` + `grants/developerInvites.ts`'s
+ * `recordDeveloperAppBinding` transport (same MCP-origin + service-secret seam);
+ * it keeps its OWN small transport rather than importing another cluster's copy so
+ * the two stay decoupled (the same reason previewStatus duplicates its transport).
+ *
+ * The MCP HOST is the ORIGIN of `MCP_APP_BINDING_URL` — the same tier the invite
+ * app-binding WRITE (`recordDeveloperAppBinding`) targets, so this READ and that
+ * WRITE always agree on which subject-capability store they speak to.
+ */
+import { readEnv } from "@/lib/env";
+import type { Capability } from "./capability.js";
+
+/** Minimal GET transport (mirrors `dev/previewStatus.ts` — decoupled by design). */
+export interface ViewerShipGrantGetTransport {
+  get(
+    url: string,
+    headers: Record<string, string>,
+  ): Promise<{ status: number; json(): Promise<unknown> }>;
+}
+
+/** Default transport: JSON `fetch` GET. */
+export class FetchShipGrantTransport implements ViewerShipGrantGetTransport {
+  async get(url: string, headers: Record<string, string>) {
+    // Bounded: this GET runs during admin-page SSR (AdminPublishTab frontmatter, on
+    // every admin tab), so an unbounded hang stalls the whole document stream. A
+    // timeout aborts to the documented deny-default (the resolver maps any transport/
+    // timeout fault to `preview-access`) — never a render-blocking wait on a slow MCP.
+    const res = await fetch(url, { method: "GET", headers, signal: AbortSignal.timeout(2500) });
+    return { status: res.status, json: () => res.json() };
+  }
+}
+
+/** Injectable deps so the resolver is unit-testable without a live MCP. */
+export interface ViewerShipGrantDeps {
+  transport?: ViewerShipGrantGetTransport;
+}
+
+/** The Step-1 subject-capability reader path (mounted OUTSIDE the session guard). */
+const SUBJECT_CAPABILITY_PATH = "/api/internal/dev-access/subject-capability";
+
+/** The viewer's blog-contribute capability — a NEW, blog-scoped projection kept OUT
+ * of the forge `Capability` union (which stays exactly two rungs). `ship-on-behalf`
+ * supersets contribute, so a ship grant also yields `"blog-contribute"` here. */
+export type ViewerContributeCapability = "preview-access" | "blog-contribute";
+
+/** The raw recognized capability read off the subject-capability seam. The private
+ * transport whitelists BOTH grant literals; the public wrappers narrow it. */
+type RawViewerCapability = "preview-access" | "blog-contribute" | "ship-on-behalf";
+
+/**
+ * ONE live subject-capability lookup, returning the raw whitelisted capability.
+ * FAIL-CLOSED, TOTAL, NEVER THROWS: an unconfigured seam (no URL/secret), a missing
+ * subject/tenant, any non-2xx (INCLUDING 502), an unparseable body, an unexpected
+ * capability value, or a transport/timeout fault ALL resolve to `"preview-access"` —
+ * the deny default. Only an explicit `200 { capability: "ship-on-behalf" }` or
+ * `200 { capability: "blog-contribute" }` returns a grant literal.
+ */
+async function resolveRawViewerCapability(
+  email: string | null | undefined,
+  appDomain: string | null | undefined,
+  deps: ViewerShipGrantDeps = {},
+): Promise<RawViewerCapability> {
+  const subject = (email ?? "").trim().toLowerCase();
+  const tenant = (appDomain ?? "").trim();
+  if (!subject || !tenant) return "preview-access";
+
+  const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
+  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
+  // Unconfigured seam → deny (the MCP route is only mounted once the secret exists).
+  if (!bindingUrl || !secret) return "preview-access";
+
+  let endpoint: string;
+  try {
+    endpoint = `${new URL(bindingUrl).origin}${SUBJECT_CAPABILITY_PATH}`;
+  } catch {
+    return "preview-access";
+  }
+  const full =
+    `${endpoint}?subject=${encodeURIComponent(subject)}` +
+    `&tenant=${encodeURIComponent(tenant)}&app=storefront`;
+
+  const transport = deps.transport ?? new FetchShipGrantTransport();
+  let res: { status: number; json(): Promise<unknown> };
+  try {
+    res = await transport.get(full, { "x-mcp-service-secret": secret });
+  } catch {
+    // Transport / timeout fault — fail closed.
+    return "preview-access";
+  }
+  // Any non-2xx (incl. 502 store fault, 401 unmounted, 404) → deny.
+  if (res.status < 200 || res.status >= 300) return "preview-access";
+
+  let payload: unknown;
+  try {
+    payload = await res.json();
+  } catch {
+    return "preview-access";
+  }
+  const capability = (payload as Record<string, unknown> | null)?.capability;
+  // Whitelist: ONLY the explicit grant literals admit; anything else is deny-default.
+  if (capability === "ship-on-behalf") return "ship-on-behalf";
+  if (capability === "blog-contribute") return "blog-contribute";
+  return "preview-access";
+}
+
+/**
+ * Resolve the viewer's LIVE ship capability over `appDomain`. Returns the granted
+ * `Capability` — `"ship-on-behalf"` ONLY on an explicit `200 { capability:
+ * "ship-on-behalf" }`; EVERYTHING else (unconfigured, absent, 502, timeout,
+ * malformed, unexpected value) fail-closes to `"preview-access"`. Never throws.
+ *
+ * @param email     the signed-in viewer's email (the subject-capability store key)
+ * @param appDomain the resolved tenant the capability is scoped to (server-derived)
+ */
+export async function resolveViewerShipCapability(
+  email: string | null | undefined,
+  appDomain: string | null | undefined,
+  deps: ViewerShipGrantDeps = {},
+): Promise<Capability> {
+  const raw = await resolveRawViewerCapability(email, appDomain, deps);
+  return raw === "ship-on-behalf" ? "ship-on-behalf" : "preview-access";
+}
+
+/**
+ * Resolve the viewer's LIVE blog-contribute capability over `appDomain`, from the
+ * SAME subject-capability seam the ship resolver reads. Returns `"blog-contribute"`
+ * ONLY on an explicit `200 { capability: "blog-contribute" }` OR `200 { capability:
+ * "ship-on-behalf" }` (ship supersets contribute); EVERYTHING else (unconfigured,
+ * absent, 502, timeout, malformed, unexpected value) fail-closes to
+ * `"preview-access"`. Never throws. Mirrors `resolveViewerShipCapability` exactly.
+ *
+ * @param email     the signed-in viewer's email (the subject-capability store key)
+ * @param appDomain the resolved tenant the capability is scoped to (server-derived)
+ */
+export async function resolveViewerContributeCapability(
+  email: string | null | undefined,
+  appDomain: string | null | undefined,
+  deps: ViewerShipGrantDeps = {},
+): Promise<ViewerContributeCapability> {
+  const raw = await resolveRawViewerCapability(email, appDomain, deps);
+  return raw === "blog-contribute" || raw === "ship-on-behalf"
+    ? "blog-contribute"
+    : "preview-access";
+}

package/package.json

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