@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.1

package/packages/public-runtime/src/integration/manifest.ts

@@ -0,0 +1,470 @@
+/**
+ * The integration declaration — the ONE shared browser contract for both
+ * tenant-local configuration and managed apps (ADR 0014 C1
+ * `integration-schema-shared`, A1 `integration-apps-manifest-v2`).
+ *
+ * Promotion from a tenant-local declaration to a managed app changes ownership
+ * and packaging, never the browser contract: the same `validateIntegration
+ * Manifest` validates both forms identically. `origin` is provenance metadata
+ * only and does not alter validation.
+ *
+ * Executable content (the entry asset, contribution templates) is kept separate
+ * from tenant values (public config). No field is secret-bearing; the browser
+ * block is scanned for secret material as defense-in-depth.
+ */
+import type { ContractResult } from "./result.js";
+import {
+  Violations,
+  reqObject,
+  childObject,
+  reqEnum,
+  reqLiteral,
+  reqString,
+  optString,
+  reqInt,
+  reqBool,
+  reqArray,
+  reqStringArray,
+  rejectUnknownKeys,
+} from "./result.js";
+import {
+  INTEGRATION_MANIFEST_SCHEMA_VERSION,
+  isCompatibleWithCurrentContract,
+  BROWSER_INTEGRATION_CONTRACT_VERSION,
+} from "./version.js";
+import {
+  RESERVED_PHASES,
+  VENDOR_ADDRESSABLE_PHASES,
+  EXECUTION_TIERS,
+  CONTRIBUTION_KINDS,
+  ENTRY_FORMATS,
+  validateContributionDag,
+  type ReservedPhase,
+  type ExecutionTier,
+  type ContributionKind,
+  type EntryFormat,
+  type DagNode,
+  type DagEdge,
+} from "./phases.js";
+import { validateCspSourceSet, type CspSourceSet } from "./csp.js";
+import { isBrowserDeliverableEventType } from "./events.js";
+import { findForbiddenFields } from "./secrets.js";
+
+/** Where a declaration comes from. Provenance only — does not change validation. */
+export const INTEGRATION_ORIGINS = [
+  "platform-adapter",
+  "tenant-local",
+  "managed-app",
+] as const;
+export type IntegrationOrigin = (typeof INTEGRATION_ORIGINS)[number];
+
+export const CONSENT_LOAD_WHEN = [
+  "all-declared-purposes-eligible",
+  "essential-only",
+] as const;
+export type ConsentLoadWhen = (typeof CONSENT_LOAD_WHEN)[number];
+
+export const DOM_INTENTS = [
+  "none",
+  "full-parent-authority-review-metadata-only",
+] as const;
+export type DomIntent = (typeof DOM_INTENTS)[number];
+
+export const ASSURANCE_CLASSIFICATIONS = ["baseline", "elevated-supported"] as const;
+export type AssuranceClassification = (typeof ASSURANCE_CLASSIFICATIONS)[number];
+
+export const REGULATED_TENANT_DEFAULTS = ["disabled-until-certified", "enabled"] as const;
+export type RegulatedTenantDefault = (typeof REGULATED_TENANT_DEFAULTS)[number];
+
+export interface IntegrationAppIdentity {
+  id: string;
+  name: string;
+  version: string;
+  digest: string;
+  publisher: string;
+  supportUrl?: string;
+}
+
+export interface IntegrationCompatibility {
+  storefrontBrowserContract: string;
+  configurationSchemaVersion: number;
+}
+
+export interface IntegrationEntry {
+  asset: string;
+  format: EntryFormat;
+  phase: ReservedPhase;
+}
+
+export interface IntegrationContribution {
+  id: string;
+  phase: ReservedPhase;
+  kind: ContributionKind;
+  template: string;
+}
+
+export interface IntegrationDependency {
+  contribution: string;
+  after: string;
+}
+
+export interface IntegrationConsent {
+  purposes: string[];
+  loadWhen: ConsentLoadWhen;
+  /** Unknown consent state always blocks — fail closed. */
+  unknownState: "block";
+}
+
+export interface IntegrationCsp {
+  profiles: string[];
+  sources: CspSourceSet;
+}
+
+export interface IntegrationPermissions {
+  events: string[];
+  data: string[];
+  actions: string[];
+  domIntent: DomIntent;
+}
+
+export interface PerformanceBudget {
+  maxTransferredBytes: number;
+  maxAdditionalRequests: number;
+  maxMainThreadMilliseconds: number;
+  mustBeAsyncOrDeferred: boolean;
+}
+
+export interface IntegrationBrowser {
+  executionTier: ExecutionTier;
+  entry: IntegrationEntry;
+  contributions: IntegrationContribution[];
+  dependencies: IntegrationDependency[];
+  publicConfigSchema: Record<string, unknown>;
+  consent: IntegrationConsent;
+  csp: IntegrationCsp;
+  permissions: IntegrationPermissions;
+  performanceBudget: PerformanceBudget;
+}
+
+export interface ServerSecretRequirement {
+  /** The NAME of a secret the server needs — never a value. */
+  name: string;
+  description?: string;
+}
+
+export interface IntegrationServer {
+  topics: string[];
+  secretRequirements: ServerSecretRequirement[];
+}
+
+export interface IntegrationAssurance {
+  requestedClassification: AssuranceClassification;
+  regulatedTenantDefault: RegulatedTenantDefault;
+}
+
+export interface ConfigurationMigration {
+  from: number;
+  to: number;
+  migration: string;
+}
+
+export interface IntegrationManifest {
+  schemaVersion: typeof INTEGRATION_MANIFEST_SCHEMA_VERSION;
+  app: IntegrationAppIdentity;
+  compatibility: IntegrationCompatibility;
+  browser: IntegrationBrowser;
+  server: IntegrationServer;
+  assurance: IntegrationAssurance;
+  configurationMigrations: ConfigurationMigration[];
+}
+
+const IMPLICIT_ENTRY_NODE = "entry";
+
+export function validateIntegrationManifest(
+  input: unknown,
+): ContractResult<IntegrationManifest> {
+  const v = new Violations();
+  const obj = reqObject(input, v, "");
+  if (!obj) return { ok: false, violations: v.items };
+
+  rejectUnknownKeys(
+    obj,
+    [
+      "schemaVersion",
+      "app",
+      "compatibility",
+      "browser",
+      "server",
+      "assurance",
+      "configurationMigrations",
+    ],
+    v,
+    "",
+  );
+
+  reqLiteral(obj, "schemaVersion", INTEGRATION_MANIFEST_SCHEMA_VERSION, v, "");
+  validateApp(obj, v);
+  validateCompatibility(obj, v);
+  validateBrowser(obj, v);
+  validateServer(obj, v);
+  validateAssurance(obj, v);
+  validateConfigurationMigrations(obj, v);
+
+  // Defense-in-depth: the browser block must carry no secret material.
+  const browser = obj["browser"];
+  if (browser !== undefined) {
+    for (const violation of findForbiddenFields(browser, "browser")) v.items.push(violation);
+  }
+
+  if (!v.ok) return { ok: false, violations: v.items };
+  return { ok: true, value: input as IntegrationManifest };
+}
+
+function validateApp(obj: Record<string, unknown>, v: Violations): void {
+  const app = childObject(obj, "app", v, "");
+  if (!app) return;
+  rejectUnknownKeys(
+    app,
+    ["id", "name", "version", "digest", "publisher", "supportUrl"],
+    v,
+    "app",
+  );
+  reqString(app, "id", v, "app");
+  reqString(app, "name", v, "app");
+  reqString(app, "version", v, "app");
+  reqString(app, "digest", v, "app");
+  reqString(app, "publisher", v, "app");
+  optString(app, "supportUrl", v, "app");
+}
+
+function validateCompatibility(obj: Record<string, unknown>, v: Violations): void {
+  const compat = childObject(obj, "compatibility", v, "");
+  if (!compat) return;
+  rejectUnknownKeys(
+    compat,
+    ["storefrontBrowserContract", "configurationSchemaVersion"],
+    v,
+    "compatibility",
+  );
+  const range = reqString(compat, "storefrontBrowserContract", v, "compatibility");
+  reqInt(compat, "configurationSchemaVersion", v, "compatibility");
+  // Fail closed: an unparseable range and an out-of-range current contract are
+  // both rejected (`satisfiesRange` returns false for either).
+  if (range !== undefined && !isCompatibleWithCurrentContract(range)) {
+    v.add(
+      "compatibility.storefrontBrowserContract",
+      "incompatible",
+      `The current browser contract ${BROWSER_INTEGRATION_CONTRACT_VERSION} does not satisfy "${range}" (unparseable ranges also fail closed).`,
+    );
+  }
+}
+
+function validateBrowser(obj: Record<string, unknown>, v: Violations): void {
+  const browser = childObject(obj, "browser", v, "");
+  if (!browser) return;
+  rejectUnknownKeys(
+    browser,
+    [
+      "executionTier",
+      "entry",
+      "contributions",
+      "dependencies",
+      "publicConfigSchema",
+      "consent",
+      "csp",
+      "permissions",
+      "performanceBudget",
+    ],
+    v,
+    "browser",
+  );
+
+  reqEnum(browser, "executionTier", EXECUTION_TIERS, v, "browser");
+
+  const dagNodes: DagNode[] = [];
+  const dagEdges: DagEdge[] = [];
+
+  const entry = childObject(browser, "entry", v, "browser");
+  if (entry) {
+    rejectUnknownKeys(entry, ["asset", "format", "phase"], v, "browser.entry");
+    reqString(entry, "asset", v, "browser.entry");
+    reqEnum(entry, "format", ENTRY_FORMATS, v, "browser.entry");
+    const phase = reqEnum(entry, "phase", VENDOR_ADDRESSABLE_PHASES, v, "browser.entry");
+    if (phase) dagNodes.push({ id: IMPLICIT_ENTRY_NODE, phase });
+  }
+
+  const contributions = reqArray(browser, "contributions", v, "browser");
+  if (contributions) {
+    contributions.forEach((raw, i) => {
+      const path = `browser.contributions[${i}]`;
+      const contribution = reqObject(raw, v, path);
+      if (!contribution) return;
+      rejectUnknownKeys(contribution, ["id", "phase", "kind", "template"], v, path);
+      const id = reqString(contribution, "id", v, path);
+      const phase = reqEnum(contribution, "phase", VENDOR_ADDRESSABLE_PHASES, v, path);
+      reqEnum(contribution, "kind", CONTRIBUTION_KINDS, v, path);
+      reqString(contribution, "template", v, path);
+      if (id && phase) dagNodes.push({ id, phase });
+    });
+  }
+
+  const dependencies = reqArray(browser, "dependencies", v, "browser");
+  if (dependencies) {
+    dependencies.forEach((raw, i) => {
+      const path = `browser.dependencies[${i}]`;
+      const dependency = reqObject(raw, v, path);
+      if (!dependency) return;
+      rejectUnknownKeys(dependency, ["contribution", "after"], v, path);
+      const contribution = reqString(dependency, "contribution", v, path);
+      const after = reqString(dependency, "after", v, path);
+      if (contribution && after) {
+        dagEdges.push({ dependent: contribution, prerequisite: after });
+      }
+    });
+  }
+
+  validateContributionDag(dagNodes, dagEdges, v, "browser");
+  validatePublicConfigSchema(browser["publicConfigSchema"], v, "browser.publicConfigSchema");
+  validateConsent(browser, v);
+  validateCsp(browser, v);
+  validatePermissions(browser, v);
+  validatePerformanceBudget(browser, v);
+}
+
+/**
+ * The public config schema must be a CLOSED object schema (`additionalProperties:
+ * false`) with only primitive-typed properties — so a tenant cannot smuggle
+ * unknown or nested executable values into browser config.
+ */
+function validatePublicConfigSchema(value: unknown, v: Violations, path: string): void {
+  const schema = reqObject(value, v, path);
+  if (!schema) return;
+  if (schema["type"] !== "object") {
+    v.add(`${path}.type`, "type", 'publicConfigSchema.type must be "object".');
+  }
+  if (schema["additionalProperties"] !== false) {
+    v.add(
+      `${path}.additionalProperties`,
+      "open_config",
+      "publicConfigSchema.additionalProperties must be false; tenant config is closed.",
+    );
+  }
+  if ("required" in schema) reqStringArray(schema, "required", v, path);
+  const properties = schema["properties"];
+  if (properties !== undefined) {
+    const props = reqObject(properties, v, `${path}.properties`);
+    if (props) {
+      const allowedTypes = new Set(["string", "number", "integer", "boolean"]);
+      for (const [name, propValue] of Object.entries(props)) {
+        const propPath = `${path}.properties.${name}`;
+        const prop = reqObject(propValue, v, propPath);
+        if (!prop) continue;
+        if (typeof prop["type"] !== "string" || !allowedTypes.has(prop["type"])) {
+          v.add(`${propPath}.type`, "type", "Property type must be string, number, integer, or boolean.");
+        }
+      }
+    }
+  }
+}
+
+function validateConsent(browser: Record<string, unknown>, v: Violations): void {
+  const consent = childObject(browser, "consent", v, "browser");
+  if (!consent) return;
+  rejectUnknownKeys(consent, ["purposes", "loadWhen", "unknownState"], v, "browser.consent");
+  reqStringArray(consent, "purposes", v, "browser.consent");
+  reqEnum(consent, "loadWhen", CONSENT_LOAD_WHEN, v, "browser.consent");
+  // Unknown consent state must be block — fail closed by construction.
+  reqLiteral(consent, "unknownState", "block", v, "browser.consent");
+}
+
+function validateCsp(browser: Record<string, unknown>, v: Violations): void {
+  const csp = childObject(browser, "csp", v, "browser");
+  if (!csp) return;
+  rejectUnknownKeys(csp, ["profiles", "sources"], v, "browser.csp");
+  reqStringArray(csp, "profiles", v, "browser.csp");
+  validateCspSourceSet(csp["sources"], v, "browser.csp.sources");
+}
+
+function validatePermissions(browser: Record<string, unknown>, v: Violations): void {
+  const permissions = childObject(browser, "permissions", v, "browser");
+  if (!permissions) return;
+  rejectUnknownKeys(permissions, ["events", "data", "actions", "domIntent"], v, "browser.permissions");
+  const events = reqStringArray(permissions, "events", v, "browser.permissions");
+  // A declared event subscription is a CAPABILITY, not review-only metadata: every
+  // entry must be a released, browser-DELIVERABLE event (browser source-of-truth).
+  // An unknown name, a reserved/forward-declared type, and a verified-provider
+  // (server-authoritative) type are all rejected here — fail closed — so a typo'd or
+  // impossible subscription can never validate clean and then silently never fire.
+  // The wiring layer (lifecycle-runtime's scoped subscribe handle) can therefore
+  // trust that every declared event is one it can actually deliver.
+  if (events) {
+    events.forEach((type, i) => {
+      if (!isBrowserDeliverableEventType(type)) {
+        v.add(
+          `browser.permissions.events[${i}]`,
+          "unsubscribable_event",
+          `"${type}" is not a browser-deliverable event; declare only released browser source-of-truth events (unknown, reserved, and verified-provider types cannot be delivered to a browser subscriber).`,
+        );
+      }
+    });
+  }
+  reqStringArray(permissions, "data", v, "browser.permissions");
+  reqStringArray(permissions, "actions", v, "browser.permissions");
+  reqEnum(permissions, "domIntent", DOM_INTENTS, v, "browser.permissions");
+}
+
+function validatePerformanceBudget(browser: Record<string, unknown>, v: Violations): void {
+  const budget = childObject(browser, "performanceBudget", v, "browser");
+  if (!budget) return;
+  rejectUnknownKeys(
+    budget,
+    ["maxTransferredBytes", "maxAdditionalRequests", "maxMainThreadMilliseconds", "mustBeAsyncOrDeferred"],
+    v,
+    "browser.performanceBudget",
+  );
+  reqInt(budget, "maxTransferredBytes", v, "browser.performanceBudget");
+  reqInt(budget, "maxAdditionalRequests", v, "browser.performanceBudget");
+  reqInt(budget, "maxMainThreadMilliseconds", v, "browser.performanceBudget");
+  reqBool(budget, "mustBeAsyncOrDeferred", v, "browser.performanceBudget");
+}
+
+function validateServer(obj: Record<string, unknown>, v: Violations): void {
+  const server = childObject(obj, "server", v, "");
+  if (!server) return;
+  rejectUnknownKeys(server, ["topics", "secretRequirements"], v, "server");
+  reqStringArray(server, "topics", v, "server");
+  const requirements = reqArray(server, "secretRequirements", v, "server");
+  if (requirements) {
+    requirements.forEach((raw, i) => {
+      const path = `server.secretRequirements[${i}]`;
+      const requirement = reqObject(raw, v, path);
+      if (!requirement) return;
+      // Names + descriptions only. A value-bearing key is a secret leak.
+      rejectUnknownKeys(requirement, ["name", "description"], v, path);
+      reqString(requirement, "name", v, path);
+      optString(requirement, "description", v, path);
+    });
+  }
+}
+
+function validateAssurance(obj: Record<string, unknown>, v: Violations): void {
+  const assurance = childObject(obj, "assurance", v, "");
+  if (!assurance) return;
+  rejectUnknownKeys(assurance, ["requestedClassification", "regulatedTenantDefault"], v, "assurance");
+  reqEnum(assurance, "requestedClassification", ASSURANCE_CLASSIFICATIONS, v, "assurance");
+  reqEnum(assurance, "regulatedTenantDefault", REGULATED_TENANT_DEFAULTS, v, "assurance");
+}
+
+function validateConfigurationMigrations(obj: Record<string, unknown>, v: Violations): void {
+  const migrations = reqArray(obj, "configurationMigrations", v, "");
+  if (!migrations) return;
+  migrations.forEach((raw, i) => {
+    const path = `configurationMigrations[${i}]`;
+    const migration = reqObject(raw, v, path);
+    if (!migration) return;
+    rejectUnknownKeys(migration, ["from", "to", "migration"], v, path);
+    reqInt(migration, "from", v, path);
+    reqInt(migration, "to", v, path);
+    reqString(migration, "migration", v, path);
+  });
+}