@tokenoftrust/storefront-runner 1.3.4-rc.4 → 1.4.0

package/apps/storefront/src/lib/apps/registryService.ts

@@ -0,0 +1,579 @@
+/**
+ * App registry service — PrivateApps epic, D2 (Chunk A). Owns the
+ * `app_installs` / `app_audit_log` rows described in `schema.ts` and
+ * orchestrates credential lifecycle through the {@link CredentialPort} seam
+ * (Chunk B implements it; Chunk A only depends on the interface, mirroring
+ * how `D1VersionStore` implements `@tot/private-controlplane`'s `VersionStore`
+ * contract without either side importing the other's internals).
+ *
+ * Pure over the `Queryable` seam (see `../d1/catalog.ts`) — the same shape
+ * `D1VersionStore` and the catalog read model use, so this runs unchanged
+ * against real D1 in the Worker and an in-memory `node:sqlite` in tests.
+ *
+ * Rules enforced HERE (not just at a future route/edge layer):
+ *   - `install` validates scopes via `scopes.ts` BEFORE writing; a denied
+ *     request writes no row.
+ *   - `install`/`update` validate a non-null `webhookEndpoint` via
+ *     `../webhooks/endpointGuard.ts` BEFORE writing, for the same reason:
+ *     the manifest contract promises https-only, and an app-supplied SSRF
+ *     target must never reach the database, let alone `deliveryEngine.ts`'s
+ *     `fetch()`.
+ *   - `install`/`update` validate a non-empty `widgetPlacements` the same
+ *     way (deny-by-default): every placement must name one of the 3
+ *     platform-owned slots, the granted scopes must include
+ *     `widgets:launch`, and each `endpoint` runs through the SAME SSRF
+ *     guard the webhook endpoint uses — a widget is a sandboxed iframe
+ *     `src`, not merchant-pasted script, but its origin is still
+ *     app-supplied and gets the same fail-closed treatment.
+ *   - `tenantId` is only ever taken from the caller's auth context, never
+ *     from install input — there is no path to override it from manifest
+ *     content.
+ *   - Every mutating method appends exactly one `app_audit_log` row in the
+ *     same operation; audit rows are never deleted, including on uninstall.
+ *   - Fail-closed: an unknown `installId` is reported as generic "not found"
+ *     (no detail that would let a caller distinguish "wrong tenant" from
+ *     "never existed"); a suspended/uninstalled install rejects further
+ *     mutation with `invalid_state`.
+ */
+import { validateScopes, type ScopeDenial } from "./scopes.js";
+import { validateWebhookEndpoint } from "../webhooks/endpointGuard.js";
+import type { Queryable } from "../d1/catalog.js";
+
+export type AppInstallStatus = "active" | "suspended" | "uninstalled";
+
+export interface AppInstall {
+  installId: string;
+  appId: string;
+  appVersion: string;
+  tenantId: string;
+  env: string;
+  status: AppInstallStatus;
+  scopes: string[];
+  /** The full tot-app.json snapshot captured at install/update time. */
+  manifest: unknown;
+  webhookEndpoint: string | null;
+  widgetPlacements: WidgetPlacementInput[];
+  installActor: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Audit event vocabulary — one row appended per mutating call. */
+export type AppAuditEvent =
+  | "installed"
+  | "updated"
+  | "suspended"
+  | "resumed"
+  | "uninstalled"
+  | "credentials_rotated";
+
+/** The auth-derived context every install is scoped to — never caller input. */
+export interface InstallActorContext {
+  tenantId: string;
+  actor: string;
+}
+
+export interface InstallInput {
+  appId: string;
+  appVersion: string;
+  env: string;
+  scopes: string[];
+  manifest: unknown;
+  webhookEndpoint?: string | null;
+  widgetPlacements?: unknown[];
+}
+
+export interface AppInstallPatch {
+  appVersion?: string;
+  scopes?: string[];
+  manifest?: unknown;
+  webhookEndpoint?: string | null;
+  widgetPlacements?: unknown[];
+}
+
+export type RegistryErrorCode =
+  | "scope_denied"
+  | "not_found"
+  | "already_installed"
+  | "invalid_state"
+  | "invalid_webhook_endpoint"
+  | "invalid_widget_placement";
+
+/**
+ * `install()`'s return: the install row PLUS the one-time client credential
+ * `credentials.issue()` just minted. Surfaced here — rather than discarded,
+ * as an earlier shape of this method did — because the plaintext `secret` is
+ * gone for good after this call returns; there is no later "show it again".
+ */
+export interface InstallResult {
+  install: AppInstall;
+  credential: { clientId: string; secret: string };
+}
+
+/** Thrown by every rule violation above — callers branch on `.code`. */
+export class RegistryError extends Error {
+  constructor(
+    message: string,
+    readonly code: RegistryErrorCode,
+    readonly denials?: ScopeDenial[],
+  ) {
+    super(message);
+    this.name = "RegistryError";
+  }
+}
+
+/** What `install()` returns from a fresh credential issue. */
+export interface IssuedCredential {
+  installId: string;
+  clientId: string;
+  jwksKid: string;
+}
+
+/**
+ * `IssuedCredential` plus the one-time plaintext secret. `issue`/`rotate` mint
+ * the secret, hash it for storage (Chunk B: `sha256Hex`), and hand the
+ * plaintext back exactly once here — there is no "show secret again" path by
+ * design, so a caller that discards this return has lost it for good (see
+ * `AppRegistryService.install`'s `InstallResult`, which is why this seam
+ * exists at all).
+ */
+export type IssuedCredentialSecret = IssuedCredential & { secret: string };
+
+/**
+ * Minimal seam for the credential lifecycle a later chunk (D2 Chunk B)
+ * implements against `app_credentials`. `AppRegistryService` orchestrates
+ * through this interface only — it never touches credential storage directly,
+ * so Chunk A can ship and be tested (with a fake) without Chunk B existing.
+ */
+export interface CredentialPort {
+  /** Issue a fresh client-credential set for a newly installed app. */
+  issue(installId: string): Promise<IssuedCredentialSecret>;
+  /** Rotate the secret for an existing install, keeping the same clientId. */
+  rotate(installId: string): Promise<IssuedCredentialSecret>;
+  /** Revoke/clear credential material for an install (uninstall). Idempotent. */
+  clear(installId: string): Promise<void>;
+}
+
+/**
+ * The 3 platform-owned widget slots (D5 Chunk A). Mirrors the `widgets[].placement`
+ * enum in `docs/private-apps/contract/tot-app.schema.json` — widgets render in a
+ * platform-managed sandboxed iframe at one of these fixed slots, never as
+ * merchant-pasted script at an app-chosen location.
+ */
+export const WIDGET_PLACEMENTS = ["product.aside", "home.section", "global.footer"] as const;
+export type WidgetPlacement = (typeof WIDGET_PLACEMENTS)[number];
+const WIDGET_PLACEMENT_SET: ReadonlySet<string> = new Set(WIDGET_PLACEMENTS);
+
+/** One validated widget placement request — `endpoint` has already passed `validateWebhookEndpoint`. */
+export interface WidgetPlacementInput {
+  placement: WidgetPlacement;
+  endpoint: string;
+  title?: string;
+}
+
+export type WidgetPlacementValidationResult =
+  | { ok: true; placements: WidgetPlacementInput[] }
+  | { ok: false; reason: string };
+
+/**
+ * Validate a requested `widgetPlacements` array. Deny-by-default and
+ * all-or-nothing, same discipline as `validateScopes`: an empty/absent array
+ * needs no scope, but ANY non-empty request is refused whole if the granted
+ * `scopes` lack `widgets:launch`, any item's `placement` isn't one of the 3
+ * platform-owned slots, or any item's `endpoint` fails the SAME SSRF guard
+ * `validateWebhookEndpoint` applies to webhook endpoints (https-only, no
+ * private/loopback/link-local target).
+ */
+export function validateWidgetPlacements(
+  placements: unknown,
+  scopes: readonly string[],
+): WidgetPlacementValidationResult {
+  if (!Array.isArray(placements) || placements.length === 0) return { ok: true, placements: [] };
+
+  if (!scopes.includes("widgets:launch")) {
+    return { ok: false, reason: "widgetPlacements requires the widgets:launch scope" };
+  }
+
+  const validated: WidgetPlacementInput[] = [];
+  for (const item of placements) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      return { ok: false, reason: "each widget placement must be an object" };
+    }
+    const { placement, endpoint, title } = item as Record<string, unknown>;
+    if (typeof placement !== "string" || !WIDGET_PLACEMENT_SET.has(placement)) {
+      return { ok: false, reason: `placement must be one of: ${WIDGET_PLACEMENTS.join(", ")}` };
+    }
+    if (typeof endpoint !== "string") {
+      return { ok: false, reason: "endpoint is required" };
+    }
+    const endpointValidation = validateWebhookEndpoint(endpoint);
+    if (!endpointValidation.ok) {
+      return { ok: false, reason: `invalid widget endpoint: ${endpointValidation.reason}` };
+    }
+    if (title !== undefined && typeof title !== "string") {
+      return { ok: false, reason: "title, when given, must be a string" };
+    }
+    validated.push({
+      placement: placement as WidgetPlacement,
+      endpoint,
+      ...(title !== undefined ? { title: title as string } : {}),
+    });
+  }
+  return { ok: true, placements: validated };
+}
+
+/** Raw `app_installs` row shape (snake_case columns, JSON-as-text). */
+interface AppInstallRow {
+  install_id: string;
+  app_id: string;
+  app_version: string;
+  tenant_id: string;
+  env: string;
+  status: string;
+  scopes: string;
+  manifest: string;
+  webhook_endpoint: string | null;
+  widget_placements: string;
+  install_actor: string;
+  created_at: string;
+  updated_at: string;
+}
+
+function toDomain(row: AppInstallRow): AppInstall {
+  return {
+    installId: row.install_id,
+    appId: row.app_id,
+    appVersion: row.app_version,
+    tenantId: row.tenant_id,
+    env: row.env,
+    status: row.status as AppInstallStatus,
+    scopes: JSON.parse(row.scopes) as string[],
+    manifest: JSON.parse(row.manifest) as unknown,
+    webhookEndpoint: row.webhook_endpoint,
+    widgetPlacements: JSON.parse(row.widget_placements) as WidgetPlacementInput[],
+    installActor: row.install_actor,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+export class AppRegistryService {
+  constructor(
+    private readonly db: Queryable,
+    private readonly credentials: CredentialPort,
+    private readonly now: () => string = () => new Date().toISOString(),
+  ) {}
+
+  /**
+   * Install an app for one (tenant, env). Validates scopes BEFORE writing
+   * anything; a `scope_denied` request leaves no trace in `app_installs`.
+   * Issues credentials through {@link CredentialPort} and appends the
+   * `installed` audit row in the same call.
+   */
+  async install(input: InstallInput, ctx: InstallActorContext): Promise<InstallResult> {
+    const validation = validateScopes(input.scopes);
+    if (!validation.ok) {
+      throw new RegistryError(
+        `Install refused: scopes include forbidden or unknown ids.`,
+        "scope_denied",
+        validation.denials,
+      );
+    }
+
+    if (input.webhookEndpoint != null) this.assertValidWebhookEndpoint(input.webhookEndpoint);
+    const widgetPlacements = this.assertValidWidgetPlacements(input.widgetPlacements, validation.scopes);
+
+    const existing = await this.findRowByAppTenantEnv(input.appId, ctx.tenantId, input.env);
+    if (existing) {
+      throw new RegistryError(
+        `App "${input.appId}" is already installed for this tenant/env.`,
+        "already_installed",
+      );
+    }
+
+    const installId = crypto.randomUUID();
+    const now = this.now();
+    await this.db.run(
+      `INSERT INTO app_installs
+         (install_id, app_id, app_version, tenant_id, env, status, scopes, manifest,
+          webhook_endpoint, widget_placements, install_actor, created_at, updated_at)
+       VALUES (?,?,?,?,?,'active',?,?,?,?,?,?,?)`,
+      installId,
+      input.appId,
+      input.appVersion,
+      ctx.tenantId,
+      input.env,
+      JSON.stringify(validation.scopes),
+      JSON.stringify(input.manifest),
+      input.webhookEndpoint ?? null,
+      JSON.stringify(widgetPlacements),
+      ctx.actor,
+      now,
+      now,
+    );
+
+    let issued: IssuedCredentialSecret;
+    try {
+      issued = await this.credentials.issue(installId);
+    } catch (cause) {
+      // Compensate: the install row above is already written, but credential
+      // issuance failed AFTER that — delete it (and skip the audit row) so no
+      // orphaned "active" install with no credential ever survives. Matches
+      // the scope-denied path's guarantee: a failed install leaves no trace.
+      await this.db.run(`DELETE FROM app_installs WHERE install_id = ?`, installId);
+      throw cause;
+    }
+    await this.appendAudit({
+      installId,
+      tenantId: ctx.tenantId,
+      event: "installed",
+      actor: ctx.actor,
+      detail: { appId: input.appId, appVersion: input.appVersion, env: input.env },
+    });
+
+    return {
+      install: await this.getOrThrow(installId),
+      credential: { clientId: issued.clientId, secret: issued.secret },
+    };
+  }
+
+  /** Read one install by id, or `null` if it doesn't exist. */
+  async get(installId: string): Promise<AppInstall | null> {
+    const row = await this.db.first<AppInstallRow>(
+      `SELECT * FROM app_installs WHERE install_id = ?`,
+      installId,
+    );
+    return row ? toDomain(row) : null;
+  }
+
+  /** All installs for a tenant, newest first. */
+  async listByTenant(tenantId: string): Promise<AppInstall[]> {
+    const rows = await this.db.all<AppInstallRow>(
+      `SELECT * FROM app_installs WHERE tenant_id = ? ORDER BY created_at DESC`,
+      tenantId,
+    );
+    return rows.map(toDomain);
+  }
+
+  /**
+   * Patch install metadata. Rejects on an uninstalled app (dead installs
+   * can't be mutated); re-validates scopes when the patch touches them, and
+   * re-validates widgetPlacements (against the PATCHED scopes, when both
+   * change in the same call) when the patch touches them.
+   */
+  async update(installId: string, patch: AppInstallPatch, actor: string): Promise<AppInstall> {
+    const row = await this.mustFindRow(installId);
+    if (row.status === "uninstalled") {
+      throw new RegistryError(`Cannot update an uninstalled app.`, "invalid_state");
+    }
+
+    let scopesJson = row.scopes;
+    let effectiveScopes = JSON.parse(row.scopes) as string[];
+    if (patch.scopes) {
+      const validation = validateScopes(patch.scopes);
+      if (!validation.ok) {
+        throw new RegistryError(
+          `Update refused: scopes include forbidden or unknown ids.`,
+          "scope_denied",
+          validation.denials,
+        );
+      }
+      scopesJson = JSON.stringify(validation.scopes);
+      effectiveScopes = validation.scopes;
+    }
+
+    if (patch.webhookEndpoint != null) this.assertValidWebhookEndpoint(patch.webhookEndpoint);
+    const widgetPlacements =
+      patch.widgetPlacements !== undefined
+        ? this.assertValidWidgetPlacements(patch.widgetPlacements, effectiveScopes)
+        : undefined;
+
+    const now = this.now();
+    const appVersion = patch.appVersion ?? row.app_version;
+    const manifestJson = patch.manifest !== undefined ? JSON.stringify(patch.manifest) : row.manifest;
+    const webhookEndpoint =
+      patch.webhookEndpoint !== undefined ? patch.webhookEndpoint : row.webhook_endpoint;
+    const widgetPlacementsJson =
+      widgetPlacements !== undefined ? JSON.stringify(widgetPlacements) : row.widget_placements;
+
+    await this.db.run(
+      `UPDATE app_installs
+          SET app_version = ?, scopes = ?, manifest = ?, webhook_endpoint = ?,
+              widget_placements = ?, updated_at = ?
+        WHERE install_id = ?`,
+      appVersion,
+      scopesJson,
+      manifestJson,
+      webhookEndpoint,
+      widgetPlacementsJson,
+      now,
+      installId,
+    );
+
+    await this.appendAudit({
+      installId,
+      tenantId: row.tenant_id,
+      event: "updated",
+      actor,
+      detail: { fields: Object.keys(patch) },
+    });
+
+    return this.getOrThrow(installId);
+  }
+
+  /** Suspend an active install: disables API/webhook/widget access. */
+  async suspend(installId: string, actor: string): Promise<AppInstall> {
+    const row = await this.mustFindRow(installId);
+    if (row.status !== "active") {
+      throw new RegistryError(
+        `Install is not active (status=${row.status}); cannot suspend.`,
+        "invalid_state",
+      );
+    }
+    await this.setStatus(installId, "suspended");
+    await this.appendAudit({ installId, tenantId: row.tenant_id, event: "suspended", actor });
+    return this.getOrThrow(installId);
+  }
+
+  /** Resume a suspended install back to active. */
+  async resume(installId: string, actor: string): Promise<AppInstall> {
+    const row = await this.mustFindRow(installId);
+    if (row.status !== "suspended") {
+      throw new RegistryError(
+        `Install is not suspended (status=${row.status}); cannot resume.`,
+        "invalid_state",
+      );
+    }
+    await this.setStatus(installId, "active");
+    await this.appendAudit({ installId, tenantId: row.tenant_id, event: "resumed", actor });
+    return this.getOrThrow(installId);
+  }
+
+  /**
+   * Rotate an install's client secret via {@link CredentialPort.rotate},
+   * keeping the same `clientId`, and append the `credentials_rotated` audit
+   * row — the same one-audit-row-per-mutation guarantee every other method
+   * here upholds. Rejects an uninstalled install: its credential row is
+   * already gone (`uninstall()` cleared it), so there is nothing to rotate.
+   */
+  async rotateCredentials(installId: string, actor: string): Promise<IssuedCredentialSecret> {
+    const row = await this.mustFindRow(installId);
+    if (row.status === "uninstalled") {
+      throw new RegistryError(`Cannot rotate credentials for an uninstalled app.`, "invalid_state");
+    }
+    const issued = await this.credentials.rotate(installId);
+    await this.appendAudit({ installId, tenantId: row.tenant_id, event: "credentials_rotated", actor });
+    return issued;
+  }
+
+  /**
+   * Uninstall: marks the row `uninstalled`, clears its `widgetPlacements`
+   * (in the SAME write as the status flip — an uninstalled app's widgets
+   * must stop rendering immediately, not just its API/webhook access, unlike
+   * `suspend`/`resume` which only ever touch `status`), and clears
+   * credential material via {@link CredentialPort.clear}. Never deletes the
+   * install row or any `app_audit_log` entry.
+   */
+  async uninstall(installId: string, actor: string): Promise<AppInstall> {
+    const row = await this.mustFindRow(installId);
+    if (row.status === "uninstalled") {
+      throw new RegistryError(`Install is already uninstalled.`, "invalid_state");
+    }
+    await this.db.run(
+      `UPDATE app_installs SET status = 'uninstalled', widget_placements = '[]', updated_at = ? WHERE install_id = ?`,
+      this.now(),
+      installId,
+    );
+    await this.credentials.clear(installId);
+    await this.appendAudit({ installId, tenantId: row.tenant_id, event: "uninstalled", actor });
+    return this.getOrThrow(installId);
+  }
+
+  /**
+   * Shared gate for `install`/`update`: refuse a non-https or private/
+   * loopback/link-local `webhookEndpoint` BEFORE any write, same fail-closed
+   * guarantee as `validateScopes` above. Never called for a `null`/absent
+   * endpoint — that's still allowed (a webhook target is optional).
+   */
+  private assertValidWebhookEndpoint(webhookEndpoint: string): void {
+    const validation = validateWebhookEndpoint(webhookEndpoint);
+    if (!validation.ok) {
+      throw new RegistryError(`Invalid webhookEndpoint: ${validation.reason}.`, "invalid_webhook_endpoint");
+    }
+  }
+
+  /**
+   * Shared gate for `install`/`update`: refuse an unrequested-scope, an
+   * unknown placement slot, or an SSRF-unsafe `endpoint`, BEFORE any write —
+   * same fail-closed guarantee as {@link assertValidWebhookEndpoint}. An
+   * empty/absent `placements` is always allowed (widgets are optional).
+   */
+  private assertValidWidgetPlacements(
+    placements: unknown,
+    scopes: readonly string[],
+  ): WidgetPlacementInput[] {
+    const validation = validateWidgetPlacements(placements, scopes);
+    if (!validation.ok) {
+      throw new RegistryError(`Invalid widgetPlacements: ${validation.reason}.`, "invalid_widget_placement");
+    }
+    return validation.placements;
+  }
+
+  private async setStatus(installId: string, status: AppInstallStatus): Promise<void> {
+    await this.db.run(
+      `UPDATE app_installs SET status = ?, updated_at = ? WHERE install_id = ?`,
+      status,
+      this.now(),
+      installId,
+    );
+  }
+
+  private async findRowByAppTenantEnv(
+    appId: string,
+    tenantId: string,
+    env: string,
+  ): Promise<AppInstallRow | null> {
+    return this.db.first<AppInstallRow>(
+      `SELECT * FROM app_installs WHERE app_id = ? AND tenant_id = ? AND env = ?`,
+      appId,
+      tenantId,
+      env,
+    );
+  }
+
+  /** Fetch a row or throw the generic fail-closed `not_found` — no enumeration detail. */
+  private async mustFindRow(installId: string): Promise<AppInstallRow> {
+    const row = await this.db.first<AppInstallRow>(
+      `SELECT * FROM app_installs WHERE install_id = ?`,
+      installId,
+    );
+    if (!row) throw new RegistryError(`App install not found.`, "not_found");
+    return row;
+  }
+
+  private async getOrThrow(installId: string): Promise<AppInstall> {
+    return toDomain(await this.mustFindRow(installId));
+  }
+
+  private async appendAudit(params: {
+    installId: string;
+    tenantId: string;
+    event: AppAuditEvent;
+    actor: string;
+    detail?: Record<string, unknown>;
+    traceId?: string;
+  }): Promise<void> {
+    await this.db.run(
+      `INSERT INTO app_audit_log (id, install_id, tenant_id, event, actor, trace_id, detail, at)
+       VALUES (?,?,?,?,?,?,?,?)`,
+      crypto.randomUUID(),
+      params.installId,
+      params.tenantId,
+      params.event,
+      params.actor,
+      params.traceId ?? null,
+      JSON.stringify(params.detail ?? {}),
+      this.now(),
+    );
+  }
+}

package/apps/storefront/src/lib/apps/scopes.ts

@@ -0,0 +1,79 @@
+/**
+ * Scope validation — the compliance-floor gate for Storefront Private Apps
+ * (PrivateApps epic, D2). See `docs/private-apps/feature-brief.md` §"The
+ * compliance floor" and the machine-readable contract:
+ *   - `docs/private-apps/contract/scopes.json` — the 8-scope V1 catalog.
+ *   - `docs/private-apps/contract/forbidden-scopes.json` — the 8 ids that map
+ *     to floor clauses (`checkout:mutate`, `tax:mutate`, …) and must NEVER be
+ *     grantable.
+ *
+ * The catalog is hand-kept here (Workers can't read `docs/` off disk at
+ * runtime) rather than imported at build time; `scopes.test.ts` asserts
+ * structural equivalence against the actual contract JSON files, the same
+ * discipline `schema.test.ts` uses for the D1 migrations vs. their read-model
+ * consts — so this list and the contract can't silently drift.
+ *
+ * `validateScopes` is the ONE gate `AppRegistryService.install`/`update` call
+ * before writing a row: any requested scope outside the V1 catalog, or any
+ * scope in the forbidden list, denies the whole request (no partial grant).
+ */
+
+/** The V1 scope catalog (`contract/scopes.json`). Least-privilege, mostly READ. */
+export const V1_SCOPES = [
+  "catalog:read",
+  "orders:read:minimal",
+  "orders:webhook",
+  "customers:read:minimal",
+  "inventory:read",
+  "reports:read",
+  "attribution:write",
+  "widgets:launch",
+] as const;
+export type V1Scope = (typeof V1_SCOPES)[number];
+
+/**
+ * Denylist proving the compliance floor is unreachable (`contract/forbidden-scopes.json`).
+ * Never part of the V1 catalog; requesting any of these is always `scope_denied`.
+ */
+export const FORBIDDEN_SCOPES = [
+  "checkout:mutate",
+  "tax:mutate",
+  "identity:mutate",
+  "warnings:mutate",
+  "jurisdiction:approve",
+  "signed-cart:mutate",
+  "promotion:publish",
+  "pii:unrestricted",
+] as const;
+export type ForbiddenScope = (typeof FORBIDDEN_SCOPES)[number];
+
+const V1_SCOPE_SET: ReadonlySet<string> = new Set(V1_SCOPES);
+const FORBIDDEN_SCOPE_SET: ReadonlySet<string> = new Set(FORBIDDEN_SCOPES);
+
+/** One requested scope that failed validation, and why. */
+export interface ScopeDenial {
+  scope: string;
+  reason: "forbidden" | "unknown";
+}
+
+export type ScopeValidationResult =
+  | { ok: true; scopes: V1Scope[] }
+  | { ok: false; code: "scope_denied"; denials: ScopeDenial[] };
+
+/**
+ * Validate a requested scope array against the V1 catalog + forbidden list.
+ * Deny-by-default and all-or-nothing: ANY scope that is forbidden or simply
+ * not in the V1 catalog denies the entire request (never a partial grant).
+ */
+export function validateScopes(requested: readonly string[]): ScopeValidationResult {
+  const denials: ScopeDenial[] = [];
+  for (const scope of requested) {
+    if (FORBIDDEN_SCOPE_SET.has(scope)) {
+      denials.push({ scope, reason: "forbidden" });
+    } else if (!V1_SCOPE_SET.has(scope)) {
+      denials.push({ scope, reason: "unknown" });
+    }
+  }
+  if (denials.length) return { ok: false, code: "scope_denied", denials };
+  return { ok: true, scopes: requested as V1Scope[] };
+}