@tokenoftrust/storefront-runner 2.0.22 → 2.0.23

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.22",
+  "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",