@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

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

@@ -0,0 +1,112 @@
+/**
+ * The effective plan and source-reference contracts (ADR 0014 C2
+ * `integration-ownership-three-party`, invariants 4, 5, 11).
+ *
+ * The effective plan is the deterministic, server-computed output the resolver
+ * (ext-kernel-03) produces and evidence (ext-kernel-06) reports. It is defined
+ * here as a shared type so both mounts and the candidate evidence agree on one
+ * shape. `planRevision` participates in candidate/cache identity. Every
+ * contribution and config value traces to a `SourceReference`; nothing in the
+ * plan is secret-bearing.
+ */
+import type { ContractViolation } from "./result.js";
+import { EFFECTIVE_PLAN_SCHEMA_VERSION } from "./version.js";
+import type { BrowserEnvironment } from "./environment.js";
+import type { ReservedPhase, ExecutionTier, ContributionKind, EntryFormat } from "./phases.js";
+import type { CommerceEventType } from "./events.js";
+import type { CspSourceSet } from "./csp.js";
+import type { IntegrationOrigin, IntegrationDependency, ConsentLoadWhen } from "./manifest.js";
+import { findForbiddenFields } from "./secrets.js";
+
+/** Provenance for a resolved contribution or config value. */
+export interface SourceReference {
+  origin: IntegrationOrigin;
+  /** Declaration id, adapter id, or board slug the value traces to. */
+  ref: string;
+  appId?: string;
+  version?: string;
+  digest?: string;
+}
+
+/**
+ * The resolved entry MODULE the lifecycle runtime dynamically imports for one
+ * integration: a same-origin, exact-version public asset URL and its format/phase.
+ * This is the executable-content handle the render-phase boot descriptor carries
+ * and the runtime loads against — pinned by the declaration, so a version change
+ * changes both this URL and `planRevision` (hence the candidate/cache identity).
+ */
+export interface PlanIntegrationEntry {
+  /** Same-origin public asset URL; version-pinned by the declaration. Never secret. */
+  url: string;
+  format: EntryFormat;
+  phase: ReservedPhase;
+}
+
+/**
+ * The per-integration consent dependency the runtime gates the entry loader on: the
+ * declared purposes and when the entry may load. A non-`essential-only` entry does
+ * not load until every declared purpose is eligible (ext-policy-03).
+ */
+export interface PlanIntegrationConsent {
+  purposes: string[];
+  loadWhen: ConsentLoadWhen;
+}
+
+export interface PlanIntegration {
+  origin: IntegrationOrigin;
+  appId: string;
+  version: string;
+  digest: string;
+  executionTier: ExecutionTier;
+  /** The exact-version entry module the lifecycle runtime imports and inits. */
+  entry: PlanIntegrationEntry;
+  /** The consent dependency that must be eligible before the entry loads. */
+  consent: PlanIntegrationConsent;
+  /**
+   * The browser-deliverable commerce events this integration declared and was
+   * validated for (`manifest.browser.permissions.events`). Cross-checked
+   * browser-deliverable at manifest validation, so every entry here is one the
+   * runtime's scoped subscribe handle can actually deliver — it bounds the receive-only
+   * subscription an entry may register (F2 wire).
+   */
+  events: CommerceEventType[];
+}
+
+export interface NormalizedContribution {
+  id: string;
+  origin: IntegrationOrigin;
+  phase: ReservedPhase;
+  kind: ContributionKind;
+  source: SourceReference;
+}
+
+export interface EffectivePlan {
+  schemaVersion: typeof EFFECTIVE_PLAN_SCHEMA_VERSION;
+  environment: BrowserEnvironment;
+  /** Participates in candidate/cache identity; changes when the resolved plan changes. */
+  planRevision: string;
+  tenantPublicId: string;
+  integrations: PlanIntegration[];
+  contributions: NormalizedContribution[];
+  /** Resolved execution order over contribution ids. */
+  order: string[];
+  /** Per-integration public config; carries no secret material. */
+  publicConfig: Record<string, Record<string, unknown>>;
+  dependencies: IntegrationDependency[];
+  consentNeeds: string[];
+  cspNeeds: CspSourceSet;
+  provenance: SourceReference[];
+}
+
+/**
+ * Browser-safety assertion for an effective plan or its evidence: the resolved
+ * environment and per-integration public config must carry no nonce, token,
+ * credential, or signed URL. Returns an empty array for a browser-safe plan.
+ */
+export function assertPlanBrowserSafe(plan: EffectivePlan): ContractViolation[] {
+  return [
+    ...findForbiddenFields(plan.environment, "environment"),
+    ...findForbiddenFields(plan.publicConfig, "publicConfig"),
+    ...findForbiddenFields(plan.cspNeeds, "cspNeeds"),
+  ];
+}

package/packages/public-runtime/src/integration/platform-adapter-runtime.ts

@@ -0,0 +1,146 @@
+/**
+ * Closed runtime registry for reviewed, Storefront-owned platform adapters.
+ *
+ * Platform authority is never inferred from an app id alone. Admission requires the
+ * exact declaration origin, execution tier, app id, version, same-origin entry URL,
+ * and module format registered here. A matching data-only entry marker is imported
+ * before the bundled runtime factory receives the host-owned network capability.
+ * Unknown/mismatched platform tuples fail closed and never reach a generic loader.
+ */
+import type { IntegrationLifecycleModule } from "./lifecycle.js";
+import type { IntegrationModuleLoader } from "./lifecycle-runtime.js";
+import type { BootDescriptorIntegration } from "./render-phases.js";
+import {
+  AMPLITUDE_HTTP_ADAPTER_VERSION,
+  AMPLITUDE_HTTP_ENTRY_URL,
+  AMPLITUDE_HTTP_RUNTIME_ID,
+  createAmplitudeLifecycleModule,
+} from "./native-amplitude.js";
+import {
+  createNativeGa4FetchTransport,
+  createNativeGa4Module,
+  NATIVE_GA4_ADAPTER_VERSION,
+  NATIVE_GA4_ENTRY_URL,
+  NATIVE_GA4_RUNTIME_ID,
+} from "./native-ga4.js";
+import { AMPLITUDE_HTTP_ADAPTER, GOOGLE_MEASUREMENT_ADAPTER } from "./platform-adapters.js";
+
+export const PLATFORM_ADAPTER_ENTRY_SCHEMA_VERSION = 1 as const;
+
+export interface PlatformAdapterEntryMarker {
+  schemaVersion: typeof PLATFORM_ADAPTER_ENTRY_SCHEMA_VERSION;
+  origin: "platform-adapter";
+  executionTier: "platform-adapter";
+  appId: string;
+  version: string;
+  entry: { url: string; format: "module" };
+  runtime: string;
+}
+
+export interface PlatformAdapterRuntimeHost {
+  fetch: typeof fetch;
+}
+
+export interface PlatformAdapterRuntimeRegistration {
+  marker: PlatformAdapterEntryMarker;
+  create(host: PlatformAdapterRuntimeHost): IntegrationLifecycleModule;
+}
+
+const GA4_MARKER: PlatformAdapterEntryMarker = Object.freeze({
+  schemaVersion: PLATFORM_ADAPTER_ENTRY_SCHEMA_VERSION,
+  origin: "platform-adapter",
+  executionTier: "platform-adapter",
+  appId: GOOGLE_MEASUREMENT_ADAPTER.adapterId,
+  version: NATIVE_GA4_ADAPTER_VERSION,
+  entry: Object.freeze({ url: NATIVE_GA4_ENTRY_URL, format: "module" }),
+  runtime: NATIVE_GA4_RUNTIME_ID,
+});
+
+const AMPLITUDE_MARKER: PlatformAdapterEntryMarker = Object.freeze({
+  schemaVersion: PLATFORM_ADAPTER_ENTRY_SCHEMA_VERSION,
+  origin: "platform-adapter",
+  executionTier: "platform-adapter",
+  appId: AMPLITUDE_HTTP_ADAPTER.adapterId,
+  version: AMPLITUDE_HTTP_ADAPTER_VERSION,
+  entry: Object.freeze({ url: AMPLITUDE_HTTP_ENTRY_URL, format: "module" }),
+  runtime: AMPLITUDE_HTTP_RUNTIME_ID,
+});
+
+/** The one shared reviewed platform-runtime registry. */
+export const PLATFORM_ADAPTER_RUNTIME_REGISTRY: readonly PlatformAdapterRuntimeRegistration[] = Object.freeze([
+  Object.freeze({
+    marker: GA4_MARKER,
+    create: ({ fetch: fetchCapability }: PlatformAdapterRuntimeHost) => createNativeGa4Module({
+      transport: createNativeGa4FetchTransport(fetchCapability),
+    }),
+  }),
+  Object.freeze({
+    marker: AMPLITUDE_MARKER,
+    create: ({ fetch: fetchCapability }: PlatformAdapterRuntimeHost) =>
+      createAmplitudeLifecycleModule({ fetch: fetchCapability }),
+  }),
+]);
+
+export interface PlatformAdapterRuntimeLoaderOptions {
+  fetchCapability?: typeof fetch;
+  importModule?: (url: string) => Promise<unknown>;
+  fallback: IntegrationModuleLoader;
+}
+
+function platformClaim(integration: BootDescriptorIntegration): boolean {
+  return integration.origin === "platform-adapter" || integration.executionTier === "platform-adapter";
+}
+
+function registrationFor(
+  integration: BootDescriptorIntegration,
+): PlatformAdapterRuntimeRegistration | undefined {
+  return PLATFORM_ADAPTER_RUNTIME_REGISTRY.find(({ marker }) =>
+    integration.origin === marker.origin &&
+    integration.executionTier === marker.executionTier &&
+    integration.appId === marker.appId &&
+    integration.version === marker.version &&
+    integration.entry.url === marker.entry.url &&
+    integration.entry.format === marker.entry.format
+  );
+}
+
+function markerEquals(expected: PlatformAdapterEntryMarker, value: unknown): boolean {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const actual = value as Record<string, unknown>;
+  if (Object.keys(actual).length !== 7) return false;
+  const entry = actual["entry"];
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return false;
+  const actualEntry = entry as Record<string, unknown>;
+  return (
+    Object.keys(actualEntry).length === 2 &&
+    actual["schemaVersion"] === expected.schemaVersion &&
+    actual["origin"] === expected.origin &&
+    actual["executionTier"] === expected.executionTier &&
+    actual["appId"] === expected.appId &&
+    actual["version"] === expected.version &&
+    actual["runtime"] === expected.runtime &&
+    actualEntry["url"] === expected.entry.url &&
+    actualEntry["format"] === expected.entry.format
+  );
+}
+
+/**
+ * Wrap the ordinary lifecycle loader with platform-first, exact-registry admission.
+ * The platform claim is checked before fallback, so neither an option nor a window
+ * override can intercept or broaden a platform-tier entry.
+ */
+export function makePlatformAdapterRuntimeLoader(
+  options: PlatformAdapterRuntimeLoaderOptions,
+): IntegrationModuleLoader {
+  const importModule = options.importModule ?? ((url: string) => import(/* @vite-ignore */ url));
+  return async (integration) => {
+    if (!platformClaim(integration)) return options.fallback(integration);
+    const registration = registrationFor(integration);
+    if (!registration) throw new Error("platform_adapter_entry_unreviewed");
+    if (!options.fetchCapability) throw new Error("platform_adapter_fetch_unavailable");
+    const namespace = await importModule(registration.marker.entry.url);
+    const marker = (namespace as { platformAdapterEntry?: unknown })?.platformAdapterEntry;
+    if (!markerEquals(registration.marker, marker)) throw new Error("platform_adapter_entry_invalid");
+    return registration.create({ fetch: options.fetchCapability });
+  };
+}