@tokenoftrust/storefront-runner 4.7.8 → 4.7.9

package/apps/storefront/src/lib/access/dashboard/staffStoreEntry.ts

@@ -0,0 +1,134 @@
+/**
+ * A ToT-staff principal ENTERING a store: the one audited act behind every staff
+ * cross-store admission (#8425 staff access).
+ *
+ * Shared by the staff console (`POST /api/dashboard/enter-vendor`) and the preview
+ * token mint (`POST /api/preview/token`, what `tot preview token` calls), so a staff
+ * CLI principal records exactly the selection the console does:
+ *
+ *   1. prove the staff actor to tot20 with a fresh storefront-signed broker assertion
+ *      minted from the VERIFIED session email (no plaintext email on the wire);
+ *   2. tot20 re-checks staff scope, scopes the capability, and writes the AUDIT row —
+ *      it is the authority, and nothing is admitted without its ok;
+ *   3. stamp the short-lived {@link StaffSelection} on the session (never a `tenants[]`
+ *      entry), so re-entering after it lapses re-audits;
+ *   4. hand every exit's outcome to the caller's `emit`, which records it as
+ *      `dashboard.vendor_entered` against its opaque admin actor id (the email is
+ *      never stored).
+ */
+import type { SessionRecord, SessionStore, StaffSelection } from "@/lib/access/auth/session";
+import { updateSession } from "@/lib/access/auth/session";
+import { isStaffSession, buildStaffSelection } from "./staffAdmission";
+import {
+  createStaffVendorAccessClient,
+  staffAccessHttpStatus,
+  StaffVendorAccessClientError,
+} from "./staffVendorAccess";
+import { mintBrokerAssertion, BrokerAssertionError } from "@/lib/access/auth/brokerAssertion";
+/** One `dashboard.vendor_entered` outcome, for the caller to record against its actor. */
+export interface StaffEntryEvent {
+  outcome: { status: "succeeded" | "failed" | "refused"; errorClass?: string };
+  scope: { tenantId: string };
+  payload: { args: { resource: string; capability?: string } };
+}
+
+export interface StaffStoreEntryInput {
+  /** The verified viewer session. Must carry ToT-staff scope. */
+  session: SessionRecord;
+  /** The store to enter, by appDomain. */
+  vendorAppDomain: string;
+  /** Records each entry outcome; the route binds it to its opaque admin actor. */
+  emit: (event: StaffEntryEvent) => void;
+  /** The persisted session to stamp the selection on; null when there is no store. */
+  sessionHandle: () => Promise<{ store: SessionStore; id: string } | null>;
+}
+
+export type StaffStoreEntryResult =
+  | { ok: true; selection: StaffSelection; capability: string }
+  | {
+      ok: false;
+      status: number;
+      body: { error: string; reason?: string; code?: string };
+    };
+
+/** Enter `vendorAppDomain` as ToT staff: audit with tot20, then persist the selection. */
+export async function enterStoreAsStaff(input: StaffStoreEntryInput): Promise<StaffStoreEntryResult> {
+  const { session, emit } = input;
+  const vendorAppDomain = input.vendorAppDomain.trim();
+  if (!isStaffSession(session)) {
+    return { ok: false, status: 403, body: { error: "staff access required", reason: "notStaff" } };
+  }
+
+  let client;
+  try {
+    client = await createStaffVendorAccessClient();
+  } catch (err) {
+    if (err instanceof StaffVendorAccessClientError) {
+      return { ok: false, status: 503, body: { error: "staff-access integration not configured" } };
+    }
+    throw err;
+  }
+
+  let brokerAssertion: string;
+  try {
+    brokerAssertion = await mintBrokerAssertion(session.email);
+  } catch (err) {
+    if (err instanceof BrokerAssertionError) {
+      return { ok: false, status: 503, body: { error: "staff-proof signing not configured" } };
+    }
+    throw err;
+  }
+
+  const result = await client.grantStaffAccess(brokerAssertion, vendorAppDomain);
+  if (!result.ok) {
+    emit({
+      outcome: { status: "refused", errorClass: result.reason ?? `http_${result.status}` },
+      scope: { tenantId: vendorAppDomain },
+      payload: { args: { resource: vendorAppDomain } },
+    });
+    return {
+      ok: false,
+      status: staffAccessHttpStatus(result.reason, result.status),
+      body: { error: result.message, reason: result.reason, code: result.code },
+    };
+  }
+
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const selection = buildStaffSelection({
+    resource: vendorAppDomain,
+    capability: result.capability,
+    nowSeconds,
+  });
+  const handle = await input.sessionHandle();
+  if (!handle) {
+    // The audit row is written but the marker cannot persist (no SESSION KV / no
+    // cookie): fail closed so the caller is never told it is admitted.
+    emit({
+      outcome: { status: "failed", errorClass: "session_store_unavailable" },
+      scope: { tenantId: vendorAppDomain },
+      payload: { args: { resource: vendorAppDomain, capability: result.capability } },
+    });
+    return { ok: false, status: 503, body: { error: "session store unavailable; cannot persist admission" } };
+  }
+  const updated = await updateSession(
+    handle.store,
+    handle.id,
+    (rec) => ({ ...rec, staffSelection: selection }),
+    nowSeconds,
+  );
+  if (!updated) {
+    emit({
+      outcome: { status: "failed", errorClass: "session_expired" },
+      scope: { tenantId: vendorAppDomain },
+      payload: { args: { resource: vendorAppDomain, capability: result.capability } },
+    });
+    return { ok: false, status: 401, body: { error: "session expired; sign in again" } };
+  }
+
+  emit({
+    outcome: { status: "succeeded" },
+    scope: { tenantId: vendorAppDomain },
+    payload: { args: { resource: vendorAppDomain, capability: result.capability } },
+  });
+  return { ok: true, selection, capability: result.capability };
+}

package/package.json

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