@tokenoftrust/storefront-runner 2.0.17 → 2.0.19

package/packages/public-runtime/src/integration/consent-broker.ts

@@ -140,6 +140,33 @@ export function defaultConsentSnapshot(): ConsentSnapshot {
   return makeSnapshot([ESSENTIAL]);
 }
 
+/**
+ * The MATERIALIZE-ONLY request header carrying a tenant's resolved consent snapshot
+ * (ADR 0013). The go-live dispatch resolves the tenant's REAL snapshot from D1 (the
+ * Worker holds that binding) and the bake pipeline sets this header on each render, so
+ * the static render inlines the real snapshot WITHOUT a consent D1 read on the
+ * public/materialize path. Never present on a real public request.
+ */
+export const CONSENT_SNAPSHOT_INPUT_HEADER = "x-tot-consent-snapshot";
+
+/**
+ * The HMAC-SHA256 signature (hex) over the {@link CONSENT_SNAPSHOT_INPUT_HEADER}
+ * value, carried alongside it. The go-live Worker (which holds both the tenant's real
+ * consent D1 and the signing secret) signs the snapshot; the materialize render
+ * VERIFIES it before honoring the input header. Absent/invalid ⇒ the snapshot input is
+ * rejected and consent falls back to the fail-closed default. Together with the
+ * materialize-mode binding gate this makes the input header un-forgeable: the deployed
+ * Worker never reads it at all, and even in materialize mode a snapshot without a valid
+ * signature from the go-live secret is refused.
+ */
+export const CONSENT_SNAPSHOT_SIG_HEADER = "x-tot-consent-snapshot-sig";
+
+/** The Worker secret binding whose value signs/verifies the baked consent snapshot. */
+export const CONSENT_SNAPSHOT_HMAC_SECRET_BINDING = "CONSENT_SNAPSHOT_HMAC_SECRET";
+
+/** The Worker binding that marks a MATERIALIZE-mode render — absent on the deployed Worker. */
+export const MATERIALIZE_MODE_BINDING = "TOT_MATERIALIZE_MODE";
+
 /**
  * Whether a purpose is currently eligible. `essential` is always eligible; an
  * unknown or unapproved-and-ungranted purpose is not — so this both permits
@@ -208,6 +235,94 @@ export function parseConsentSnapshot(raw: unknown): ConsentSnapshot | null {
   return canonical;
 }
 
+// ── Baked-snapshot signature (materialize bake wire) ────────────────────────────
+// The go-live Worker holds the tenant's real consent D1 AND the signing secret; it
+// signs the resolved snapshot, and the materialize render verifies before honoring the
+// input header. Web Crypto only (crypto.subtle) so it runs unchanged on workerd, and
+// verification is constant-time. The signature is TENANT-BOUND — it covers a
+// length-prefixed framing of `tenantId` and `serializedSnapshot`, so neither field's
+// content can shift a byte across the field boundary: a signed snapshot for one tenant
+// can never be replayed as another tenant's baked input, or as a different snapshot for
+// the same tenant.
+
+const consentSigTextEncoder = new TextEncoder();
+
+/**
+ * The exact string the consent snapshot signature covers: each field prefixed by its
+ * own UTF-8 byte length, so no value in either field can be interpreted as a field
+ * separator.
+ */
+function consentSignaturePayload(tenantId: string, serializedSnapshot: string): string {
+  const tenantBytes = consentSigTextEncoder.encode(tenantId).length;
+  const snapshotBytes = consentSigTextEncoder.encode(serializedSnapshot).length;
+  return `${tenantBytes}:${tenantId}${snapshotBytes}:${serializedSnapshot}`;
+}
+
+async function consentHmacKey(secret: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    "raw",
+    consentSigTextEncoder.encode(secret) as unknown as BufferSource,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"],
+  );
+}
+
+function consentSigHexToBytes(hex: string): Uint8Array | null {
+  if (hex.length === 0 || hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex)) return null;
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+/**
+ * Sign a tenant's serialized consent snapshot: hex HMAC-SHA256 over the length-prefixed
+ * {@link consentSignaturePayload}. The go-live Worker calls this; the materialize render
+ * verifies with the same secret via {@link verifyConsentSnapshotSig}.
+ */
+export async function signConsentSnapshot(
+  secret: string,
+  tenantId: string,
+  serializedSnapshot: string,
+): Promise<string> {
+  const key = await consentHmacKey(secret);
+  const sig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    consentSigTextEncoder.encode(
+      consentSignaturePayload(tenantId, serializedSnapshot),
+    ) as unknown as BufferSource,
+  );
+  let hex = "";
+  for (const b of new Uint8Array(sig)) hex += b.toString(16).padStart(2, "0");
+  return hex;
+}
+
+/**
+ * Verify a consent snapshot signature (constant-time via `crypto.subtle.verify`). A
+ * malformed / short / absent signature returns false rather than throwing — fail-closed,
+ * so a caller can never smuggle in an unsigned or forged snapshot.
+ */
+export async function verifyConsentSnapshotSig(
+  secret: string,
+  tenantId: string,
+  serializedSnapshot: string,
+  signatureHex: string | null | undefined,
+): Promise<boolean> {
+  if (!signatureHex) return false;
+  const sig = consentSigHexToBytes(signatureHex.trim());
+  if (!sig) return false;
+  const key = await consentHmacKey(secret);
+  return crypto.subtle.verify(
+    "HMAC",
+    key,
+    sig as unknown as BufferSource,
+    consentSigTextEncoder.encode(
+      consentSignaturePayload(tenantId, serializedSnapshot),
+    ) as unknown as BufferSource,
+  );
+}
+
 /** Listener invoked with the new snapshot whenever eligibility changes. */
 export type ConsentListener = (snapshot: ConsentSnapshot) => void;
 

package/packages/public-runtime/src/integration/interim-bridge.ts

@@ -12,13 +12,15 @@
  * with it (the plan carries no vendor runtime, and `planRevision` moves), so a
  * rollback leaves no stale effect.
  *
- * It is deliberately narrow (ADR 0016/0023 Q6): the bridge is enabled ONLY on
- * eligible unregulated-marketing tenants. A regulated tenant is REFUSED with an
- * actionable explanation until a capability-specific certification exists — the
- * regulated shared-runtime floor is non-waivable, and this bridge never opens an
- * escape hatch around it. Promote-time enforcement still runs through the full
- * fail-closed gate (`verifyIntegrationPromotable`); this module is the render-time
- * tenant-eligibility decision that precedes it.
+ * It is deliberately narrow (ADR 0016/0023 Q6): on a regulated tenant the bridge
+ * enables only the declarations the surface × tier matrix permits on the regulated
+ * surface without a certification — reviewed platform-adapter/sandbox/server tiers —
+ * and REFUSES full parent authority (`elevated-parent`) until a capability-specific
+ * certification clears every clause. The regulated shared-runtime floor is
+ * non-waivable, and this bridge never opens an escape hatch around it. Promote-time
+ * enforcement still runs through the full fail-closed gate
+ * (`verifyIntegrationPromotable`); this module is the render-time tenant-eligibility
+ * decision that precedes it.
  */
 import type { BrowserEnvironment } from "./environment.js";
 import type { EffectivePlan } from "./plan.js";
@@ -34,6 +36,13 @@ import {
   isRegulatedParentCertified,
   type RegulatedParentCertification,
 } from "./regulated-parent-cert.js";
+import {
+  allowedTiersForCell,
+  resolveCellAuthority,
+  type CellAuthority,
+  type TenantTier,
+} from "../integration-capabilities.js";
+import type { ExecutionTier } from "./phases.js";
 
 /**
  * Whether an integration's declared consent dependency permits loading its entry
@@ -57,6 +66,11 @@ export interface InterimBridgeRefusal {
   surface: AssuranceSurface;
   /** An operator-facing explanation of the refusal and what unblocks it. */
   message: string;
+  /**
+   * The registered feedback item tracking this gap, so a consumer can route the reader
+   * to live work without parsing the message. See {@link REGULATED_REFUSAL_FEEDBACK_REF}.
+   */
+  feedbackRef: string;
 }
 
 /**
@@ -80,10 +94,11 @@ export interface InterimBridgeInput {
    * G2: the regulated elevated-parent certification artifact for a regulated tenant.
    * The bridge NEVER accepts a raw "certified" boolean — it runs
    * {@link decideRegulatedParentCert} itself (via {@link isRegulatedParentCertified}),
-   * so `certifiedImmutable` has a SINGLE ORIGIN: a regulated tenant is enabled ONLY
-   * when the cert clears every clause (pinned, undrifted from `servedDigest`, every
-   * server-derived obligation proven). Absent/failed ⇒ the decision fails closed and
-   * the tenant stays refused. This is the WS2 forward seam, not a per-tenant bypass.
+   * so `certifiedImmutable` has a SINGLE ORIGIN: a regulated tenant's full-parent
+   * authority (`elevated-parent`) declaration is enabled ONLY when the cert clears
+   * every clause (pinned, undrifted from `servedDigest`, every server-derived
+   * obligation proven). Absent/failed ⇒ the decision fails closed and that declaration
+   * stays refused. This is the WS2 forward seam, not a per-tenant bypass.
    */
   regulatedCertification?: RegulatedParentCertification | null;
   /**
@@ -101,31 +116,71 @@ export interface InterimBridgeInput {
  * set), so an eligible tenant's plan is exactly the kernel plan every mount serves —
  * the bridge adds only the tenant-eligibility gate, not a second plan shape.
  */
+/**
+ * Feedback tripwire for the regulated refusal below.
+ *
+ * A tripwire is three coupled parts: a registered feedback item describing an accepted
+ * gap, a reference to it from the message emitted where execution trips over that gap,
+ * and a workstream that owns closing it. Carrying the reference in the refusal itself is
+ * what routes a reader to live work instead of a fresh diagnosis.
+ *
+ * This gate refuses a regulated tenant whose declaration requests full parent
+ * authority (`elevated-parent`) without a {@link RegulatedParentCertification} that
+ * clears every clause — an absent or failed one fails closed. Owned by the
+ * `tot-regulated-integration-certification` workstream.
+ *
+ * See docs/playbooks/feedback-tripwire.md for the generalized recipe — this is the
+ * reference implementation, not a one-off.
+ */
+export const REGULATED_REFUSAL_FEEDBACK_REF = "fb-1788612281954-3q8f1n" as const;
+
 export function resolveInterimBridgePlan(input: InterimBridgeInput): InterimBridgeResult {
   const surface = resolveObligationSurface(input.tenant);
 
   // The certification is the SINGLE ORIGIN of `certifiedImmutable`: derive it from the
-  // decision (never a raw external flag), so a regulated tenant is enabled only when the
-  // cert actually clears every clause. Absent/failed ⇒ false ⇒ refused.
+  // decision (never a raw external flag), so a regulated tenant's full-parent authority
+  // declaration is enabled only when the cert actually clears every clause. Absent/failed
+  // ⇒ false ⇒ that declaration is refused.
   const regulatedCertified = isRegulatedParentCertified(input.regulatedCertification, {
     tenant: input.tenant,
     servedDigest: input.servedDigest,
   });
 
-  if (isRegulated(input.tenant) && !regulatedCertified) {
-    return {
-      ok: false,
-      reason: "regulated-refused",
-      refusal: {
-        code: "regulated-tenant-not-certified",
-        surface,
-        message:
-          `The interim marketing bridge is not enabled for regulated tenants (resolved surface ` +
-          `"${surface}"). A regulated parent tier requires an immutable, version-pinned, ` +
-          `capability-specific certification — a mere acknowledgement cannot waive the ` +
-          `non-waivable regulated shared-runtime floor. Complete WS2 certification to enable it.`,
-      },
-    };
+  // Drive the render-time refusal off the same surface × tier matrix the policy layer
+  // enforces (SURFACE_TENANT_TIER_MATRIX): a regulated tenant is refused only for a
+  // declaration the matrix does not permit on the regulated surface — full parent
+  // authority (`elevated-parent`) without a certification that clears every clause, never
+  // a reviewed platform-adapter/sandbox/server tier the cell already allows. A cert whose
+  // codeForm is `mutable-container`, or that has drifted/is incomplete, never clears the
+  // decision, so mutable parent code on a regulated surface stays refused.
+  // `verifyIntegrationPromotable` remains the authoritative fail-closed backstop at
+  // promote time; this only stops the bridge PRE-refusing a class the policy permits.
+  if (isRegulated(input.tenant)) {
+    const cell = resolveCellAuthority(regulatedTenantTier(input.tenant), "regulated");
+    const refused =
+      !cell ||
+      input.declarations.some((decl) =>
+        isRegulatedDeclarationRefused(decl.manifest.browser.executionTier, cell, regulatedCertified),
+      );
+    if (refused) {
+      return {
+        ok: false,
+        reason: "regulated-refused",
+        refusal: {
+          code: "regulated-tenant-not-certified",
+          surface,
+          message:
+            `This integration needs full-page access to run on your storefront. Because your ` +
+            `store is regulated, that level of access is only available once a compliance ` +
+            `certification confirms it can't reach age-verification or customer data — a ` +
+            `safeguard, not a limitation of your store. Standard analytics and platform ` +
+            `integrations, including Google Analytics 4 (GA4), work normally on a regulated ` +
+            `storefront and can be added today. To proceed, choose a standard, already-supported ` +
+            `integration, or contact support to pursue certification for this one.`,
+          feedbackRef: REGULATED_REFUSAL_FEEDBACK_REF,
+        },
+      };
+    }
   }
 
   const result = resolveEffectivePlan({
@@ -136,3 +191,32 @@ export function resolveInterimBridgePlan(input: InterimBridgeInput): InterimBrid
   if (!result.ok) return { ok: false, reason: "invalid-plan", violations: result.violations };
   return { ok: true, plan: result.value };
 }
+
+/**
+ * The regulated tenant tier for the matrix lookup. Both regulated tiers carry the
+ * identical `regulated` cell (`maxTier: "server"`, `elevatedParent: "cert-required"`),
+ * so the split only tracks the tenant's site type; an unset site type resolves to
+ * `regulated-commerce`, mirroring {@link resolveObligationSurface}'s commerce floor.
+ */
+function regulatedTenantTier(tenant: ObligationTenant): TenantTier {
+  return tenant.siteType === "marketing" ? "regulated-marketing" : "regulated-commerce";
+}
+
+/**
+ * Whether one declaration is refused on the regulated surface, per the cell's authority.
+ * Full parent authority (`elevated-parent`) is gated by the cell's elevated-parent
+ * disposition — `cert-required` enables it only behind a certification that clears every
+ * clause, and any other disposition (`prohibited`/`acknowledge`) never enables it here
+ * (fail closed). Every other tier is permitted when it is within the cell's allowed
+ * non-elevated tiers (`platform-adapter` ≤ `sandbox` ≤ `server`).
+ */
+function isRegulatedDeclarationRefused(
+  tier: ExecutionTier,
+  cell: CellAuthority,
+  regulatedCertified: boolean,
+): boolean {
+  if (tier === "elevated-parent") {
+    return cell.elevatedParent === "cert-required" ? !regulatedCertified : true;
+  }
+  return !allowedTiersForCell(cell).includes(tier);
+}

package/packages/public-runtime/src/integration/managed-analytics-api-v1.schemas.ts

@@ -286,6 +286,32 @@ const SET_INTEGRATION_INSTALL_STATUS_BODY_SCHEMA = {
 const DELETE_INTEGRATION_INSTALL_BODY_SCHEMA = {
   type: "object", additionalProperties: false, required: ["installId"], properties: { installId: PUBLIC_IDENTIFIER },
 } as const;
+const TEST_DESTINATION_ENVIRONMENT = { type: "string", enum: ["local", "candidate", "staged"] } as const;
+const APPROVED_MARKETING_ACTION_NAME = {
+  type: "string",
+  enum: [
+    "user_clicked_contact_sales_mktg",
+    "user_clicked_create_account_mktg",
+    "user_clicked_login_mktg",
+    "user_clicked_contact_support_consumer_mktg",
+    "user_clicked_contact_support_partner_mktg",
+  ],
+} as const;
+const REGISTER_TEST_DESTINATION_BODY_SCHEMA = {
+  type: "object", additionalProperties: false,
+  required: ["destinationId", "environment"],
+  properties: { destinationId: PUBLIC_IDENTIFIER, environment: TEST_DESTINATION_ENVIRONMENT },
+} as const;
+const DELIVER_TEST_EVENT_BODY_SCHEMA = {
+  type: "object", additionalProperties: false,
+  required: ["destinationId", "eventId", "actionName"],
+  properties: { destinationId: PUBLIC_IDENTIFIER, eventId: PUBLIC_IDENTIFIER, actionName: APPROVED_MARKETING_ACTION_NAME },
+} as const;
+const TEST_DESTINATION_DELIVERY_QUERY_SCHEMA = {
+  type: "object", additionalProperties: false,
+  required: ["destinationId", "eventId"],
+  properties: { destinationId: PUBLIC_IDENTIFIER, eventId: PUBLIC_IDENTIFIER },
+} as const;
 
 export const CREATE_MIGRATION_DRAFT_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("CreateMigrationDraftRequest", "create-migration-draft-request.schema.json", CREATE_MIGRATION_DRAFT_BODY_SCHEMA);
 export const UPDATE_MIGRATION_DRAFT_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("UpdateMigrationDraftRequest", "update-migration-draft-request.schema.json", UPDATE_MIGRATION_DRAFT_BODY_SCHEMA);
@@ -294,6 +320,40 @@ export const CREATE_INTEGRATION_INSTALL_REQUEST_V1_JSON_SCHEMA = mutationOperati
 export const REVISE_INTEGRATION_INSTALL_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("ReviseIntegrationInstallRequest", "revise-integration-install-request.schema.json", REVISE_INTEGRATION_INSTALL_BODY_SCHEMA);
 export const SET_INTEGRATION_INSTALL_STATUS_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("SetIntegrationInstallStatusRequest", "set-integration-install-status-request.schema.json", SET_INTEGRATION_INSTALL_STATUS_BODY_SCHEMA);
 export const DELETE_INTEGRATION_INSTALL_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("DeleteIntegrationInstallRequest", "delete-integration-install-request.schema.json", DELETE_INTEGRATION_INSTALL_BODY_SCHEMA);
+export const REGISTER_TEST_DESTINATION_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("RegisterTestDestinationRequest", "register-test-destination-request.schema.json", REGISTER_TEST_DESTINATION_BODY_SCHEMA);
+export const DELIVER_TEST_EVENT_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("DeliverTestEventRequest", "deliver-test-event-request.schema.json", DELIVER_TEST_EVENT_BODY_SCHEMA);
+export const GET_TEST_DESTINATION_DELIVERY_REQUEST_V1_JSON_SCHEMA = readOperationSchema("GetTestDestinationDeliveryRequest", "get-test-destination-delivery-request.schema.json", TEST_DESTINATION_DELIVERY_QUERY_SCHEMA);
+
+export const TEST_DESTINATION_V1_JSON_SCHEMA = {
+  $schema: DRAFT,
+  $id: `${BASE}/test-destination.schema.json`,
+  title: "TestDestinationV1",
+  type: "object",
+  additionalProperties: false,
+  required: ["schemaVersion", "destinationId", "environment", "createdAt"],
+  properties: {
+    schemaVersion: { type: "integer", const: 1 },
+    destinationId: PUBLIC_IDENTIFIER,
+    environment: TEST_DESTINATION_ENVIRONMENT,
+    createdAt: { ...SAFE_CONFIG_STRING, format: "date-time" },
+  },
+} as const;
+
+export const TEST_DESTINATION_DELIVERY_V1_JSON_SCHEMA = {
+  $schema: DRAFT,
+  $id: `${BASE}/test-destination-delivery.schema.json`,
+  title: "TestDestinationDeliveryV1",
+  type: "object",
+  additionalProperties: false,
+  required: ["schemaVersion", "destinationId", "eventId", "actionName", "deliveredAt"],
+  properties: {
+    schemaVersion: { type: "integer", const: 1 },
+    destinationId: PUBLIC_IDENTIFIER,
+    eventId: PUBLIC_IDENTIFIER,
+    actionName: APPROVED_MARKETING_ACTION_NAME,
+    deliveredAt: { ...SAFE_CONFIG_STRING, format: "date-time" },
+  },
+} as const;
 
 export const READ_SUCCESS_ENVELOPE_V1_JSON_SCHEMA = {
   $schema: DRAFT,
@@ -376,6 +436,11 @@ export const MANAGED_ANALYTICS_API_V1_JSON_SCHEMAS = Object.freeze({
   reviseIntegrationInstallRequest: REVISE_INTEGRATION_INSTALL_REQUEST_V1_JSON_SCHEMA,
   setIntegrationInstallStatusRequest: SET_INTEGRATION_INSTALL_STATUS_REQUEST_V1_JSON_SCHEMA,
   deleteIntegrationInstallRequest: DELETE_INTEGRATION_INSTALL_REQUEST_V1_JSON_SCHEMA,
+  registerTestDestinationRequest: REGISTER_TEST_DESTINATION_REQUEST_V1_JSON_SCHEMA,
+  deliverTestEventRequest: DELIVER_TEST_EVENT_REQUEST_V1_JSON_SCHEMA,
+  getTestDestinationDeliveryRequest: GET_TEST_DESTINATION_DELIVERY_REQUEST_V1_JSON_SCHEMA,
+  testDestination: TEST_DESTINATION_V1_JSON_SCHEMA,
+  testDestinationDelivery: TEST_DESTINATION_DELIVERY_V1_JSON_SCHEMA,
   readSuccessEnvelope: READ_SUCCESS_ENVELOPE_V1_JSON_SCHEMA,
   mutationSuccessEnvelope: MUTATION_SUCCESS_ENVELOPE_V1_JSON_SCHEMA,
   errorEnvelope: API_ERROR_ENVELOPE_V1_JSON_SCHEMA,

package/packages/public-runtime/src/integration/managed-analytics-api-v1.ts

@@ -10,6 +10,7 @@
 import type { ContractResult } from "./result.js";
 import { Violations, isPlainObject } from "./result.js";
 import { isForbiddenKey } from "./secrets.js";
+import { APPROVED_MARKETING_ACTION_NAMES } from "./events.js";
 import {
   MANAGED_ANALYTICS_PII_VALUE_PATTERN,
   MANAGED_ANALYTICS_SECRET_VALUE_PATTERN,
@@ -112,6 +113,37 @@ export interface MigrationDraftV1 {
   updatedAt: string;
 }
 
+/**
+ * A test destination is intentionally never `live`: it exists so a developer can
+ * prove exactly-once delivery for a new marketing action without touching a real
+ * vendor property. Real first-class adapters (GA4/Meta/Amplitude) fire directly to
+ * their vendor with no server-side readback; this destination is Storefront-owned,
+ * so a delivered event can be read back.
+ */
+export const TEST_DESTINATION_ENVIRONMENTS = ["local", "candidate", "staged"] as const;
+export type TestDestinationEnvironment = (typeof TEST_DESTINATION_ENVIRONMENTS)[number];
+
+export interface TestDestinationV1 {
+  schemaVersion: typeof MANAGED_ANALYTICS_SCHEMA_VERSION;
+  destinationId: OpaquePublicId;
+  environment: TestDestinationEnvironment;
+  createdAt: string;
+}
+
+/**
+ * One delivered event, read back by (destinationId, eventId). `actionName` is
+ * restricted to the program-approved v1 marketing action allowlist — the same
+ * set a tenant's action registry may enable — so this proves delivery for a real
+ * action, never an arbitrary caller-invented event shape.
+ */
+export interface TestDestinationDeliveryV1 {
+  schemaVersion: typeof MANAGED_ANALYTICS_SCHEMA_VERSION;
+  destinationId: OpaquePublicId;
+  eventId: OpaquePublicId;
+  actionName: OpaquePublicId;
+  deliveredAt: string;
+}
+
 export interface PageRequest {
   cursor?: OpaquePublicId;
   limit?: number;
@@ -261,6 +293,25 @@ export interface DeleteIntegrationInstallBody { installId: OpaquePublicId }
 export type DeleteIntegrationInstallRequest = MutationRequest<DeleteIntegrationInstallBody>;
 export type DeleteIntegrationInstallResponse = MutationResult<{ deleted: true }>;
 
+export interface RegisterTestDestinationBody {
+  destinationId: OpaquePublicId;
+  environment: TestDestinationEnvironment;
+}
+export type RegisterTestDestinationRequest = MutationRequest<RegisterTestDestinationBody>;
+export type RegisterTestDestinationResponse = MutationResult<{ destination: TestDestinationV1 }>;
+
+export interface DeliverTestEventBody {
+  destinationId: OpaquePublicId;
+  eventId: OpaquePublicId;
+  actionName: OpaquePublicId;
+}
+export type DeliverTestEventRequest = MutationRequest<DeliverTestEventBody>;
+/** `duplicate: true` when this eventId had already been delivered — the exactly-once proof. */
+export type DeliverTestEventResponse = MutationResult<{ delivery: TestDestinationDeliveryV1; duplicate: boolean }>;
+
+export type GetTestDestinationDeliveryRequest = ReadRequest<{ destinationId: OpaquePublicId; eventId: OpaquePublicId }>;
+export type GetTestDestinationDeliveryResponse = ApiResult<TestDestinationDeliveryV1>;
+
 /** The only backend seam WS2 needs; tests can mock this interface without HTTP. */
 export interface ManagedAnalyticsApiV1Client {
   listAdapterDefinitions(request: ListAdapterDefinitionsRequest): Promise<ListAdapterDefinitionsResponse>;
@@ -557,6 +608,26 @@ export function validateIntegrationRevisionV1(input: unknown): ContractResult<In
   return v.ok ? prepared : { ok: false, violations: v.items };
 }
 
+export function validateTestDestinationV1(input: unknown): ContractResult<TestDestinationV1> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<TestDestinationV1>(input); if (!prepared.ok) return prepared;
+  const v = new Violations(); const obj = object(prepared.value, v, ""); if (!obj) return { ok: false, violations: v.items };
+  rejectKeys(obj, ["schemaVersion", "destinationId", "environment", "createdAt"], v, "");
+  literal(obj, "schemaVersion", 1, v, ""); opaqueId(obj, "destinationId", v, ""); enumeration(obj, "environment", TEST_DESTINATION_ENVIRONMENTS, v, ""); timestamp(obj, "createdAt", v, "");
+  const safe = validateManagedAnalyticsSafePayload(obj); if (!safe.ok) v.items.push(...safe.violations);
+  return v.ok ? prepared : { ok: false, violations: v.items };
+}
+
+export function validateTestDestinationDeliveryV1(input: unknown): ContractResult<TestDestinationDeliveryV1> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<TestDestinationDeliveryV1>(input); if (!prepared.ok) return prepared;
+  const v = new Violations(); const obj = object(prepared.value, v, ""); if (!obj) return { ok: false, violations: v.items };
+  rejectKeys(obj, ["schemaVersion", "destinationId", "eventId", "actionName", "deliveredAt"], v, "");
+  literal(obj, "schemaVersion", 1, v, ""); opaqueId(obj, "destinationId", v, ""); opaqueId(obj, "eventId", v, "");
+  enumeration(obj, "actionName", APPROVED_MARKETING_ACTION_NAMES, v, "");
+  timestamp(obj, "deliveredAt", v, "");
+  const safe = validateManagedAnalyticsSafePayload(obj); if (!safe.ok) v.items.push(...safe.violations);
+  return v.ok ? prepared : { ok: false, violations: v.items };
+}
+
 export function validateMigrationDraftV1(input: unknown): ContractResult<MigrationDraftV1> {
   const prepared = snapshotManagedAnalyticsDeclarativeInput<MigrationDraftV1>(input); if (!prepared.ok) return prepared;
   const v = new Violations(); const obj = object(prepared.value, v, ""); if (!obj) return { ok: false, violations: v.items };
@@ -649,6 +720,13 @@ const validateSetIntegrationInstallStatusBody: ObjectShapeValidator = (obj, v, p
   rejectKeys(obj, ["installId", "status"], v, path); opaqueId(obj, "installId", v, path); enumeration(obj, "status", INTEGRATION_INSTALL_STATUSES, v, path);
 };
 const validateDeleteIntegrationInstallBody: ObjectShapeValidator = (obj, v, path) => { rejectKeys(obj, ["installId"], v, path); opaqueId(obj, "installId", v, path); };
+const validateRegisterTestDestinationBody: ObjectShapeValidator = (obj, v, path) => {
+  rejectKeys(obj, ["destinationId", "environment"], v, path); opaqueId(obj, "destinationId", v, path); enumeration(obj, "environment", TEST_DESTINATION_ENVIRONMENTS, v, path);
+};
+const validateDeliverTestEventBody: ObjectShapeValidator = (obj, v, path) => {
+  rejectKeys(obj, ["destinationId", "eventId", "actionName"], v, path); opaqueId(obj, "destinationId", v, path); opaqueId(obj, "eventId", v, path); enumeration(obj, "actionName", APPROVED_MARKETING_ACTION_NAMES, v, path);
+};
+const validateTestDestinationDeliveryQuery: ObjectShapeValidator = (obj, v, path) => { rejectKeys(obj, ["destinationId", "eventId"], v, path); opaqueId(obj, "destinationId", v, path); opaqueId(obj, "eventId", v, path); };
 
 export function validateCreateMigrationDraftRequest(input: unknown): ContractResult<CreateMigrationDraftRequest> { return validateMutationOperation(input, validateCreateMigrationDraftBody); }
 export function validateUpdateMigrationDraftRequest(input: unknown): ContractResult<UpdateMigrationDraftRequest> { return validateMutationOperation(input, validateUpdateMigrationDraftBody); }
@@ -657,6 +735,9 @@ export function validateCreateIntegrationInstallRequest(input: unknown): Contrac
 export function validateReviseIntegrationInstallRequest(input: unknown): ContractResult<ReviseIntegrationInstallRequest> { return validateMutationOperation(input, validateReviseIntegrationInstallBody); }
 export function validateSetIntegrationInstallStatusRequest(input: unknown): ContractResult<SetIntegrationInstallStatusRequest> { return validateMutationOperation(input, validateSetIntegrationInstallStatusBody); }
 export function validateDeleteIntegrationInstallRequest(input: unknown): ContractResult<DeleteIntegrationInstallRequest> { return validateMutationOperation(input, validateDeleteIntegrationInstallBody); }
+export function validateRegisterTestDestinationRequest(input: unknown): ContractResult<RegisterTestDestinationRequest> { return validateMutationOperation(input, validateRegisterTestDestinationBody); }
+export function validateDeliverTestEventRequest(input: unknown): ContractResult<DeliverTestEventRequest> { return validateMutationOperation(input, validateDeliverTestEventBody); }
+export function validateGetTestDestinationDeliveryRequest(input: unknown): ContractResult<GetTestDestinationDeliveryRequest> { return validateReadOperation(input, validateTestDestinationDeliveryQuery); }
 
 /** Validate the closed, public-safe error shape before it crosses the API boundary. */
 export function validateApiErrorEnvelope(input: unknown): ContractResult<ApiErrorEnvelope> {

package/packages/public-runtime/src/integration/render-phases.ts

@@ -36,7 +36,7 @@ import {
   renderBrowserEnvironmentScript,
   serializeForInlineScript,
 } from "./environment.js";
-import { defaultConsentSnapshot } from "./consent-broker.js";
+import { defaultConsentSnapshot, type ConsentSnapshot } from "./consent-broker.js";
 
 /**
  * The sentinel a renderer stamps in place of a live CSP nonce. It is a valid
@@ -138,11 +138,16 @@ export function phaseBoundary(phase: ReservedPhase): string {
  * splice regions both document mounts consume. `nonce` is the value stamped onto
  * the emitted inline scripts — pass {@link INTEGRATION_NONCE_PLACEHOLDER} so the
  * renderer can stamp a fresh nonce per response; an empty string omits the
- * attribute (for tests / mounts that stamp uniformly downstream).
+ * attribute (for tests / mounts that stamp uniformly downstream). `consentSnapshot`
+ * is the tenant's actual initial consent state — the snapshot the ext-policy-03
+ * broker computes from its {@link TenantConsentConfig}, seeded before any CMP/banner
+ * interaction; it defaults to {@link defaultConsentSnapshot} (essential-only, fail
+ * closed) for callers with no tenant consent config to resolve.
  */
 export function renderIntegrationPhases(
   plan: EffectivePlan,
   nonce: string = INTEGRATION_NONCE_PLACEHOLDER,
+  consentSnapshot: ConsentSnapshot = defaultConsentSnapshot(),
 ): IntegrationPhaseMarkup {
   assertRenderablePlan(plan);
 
@@ -150,7 +155,7 @@ export function renderIntegrationPhases(
     phaseBoundary("platform.environment") +
     renderBrowserEnvironmentScript(plan.environment, nonce) +
     phaseBoundary("consent.defaults") +
-    inlineFrozenGlobal(INTEGRATION_CONSENT_GLOBAL, defaultConsentSnapshot(), nonce) +
+    inlineFrozenGlobal(INTEGRATION_CONSENT_GLOBAL, consentSnapshot, nonce) +
     phaseBoundary("head.early") +
     inlineFrozenGlobal(INTEGRATION_PLAN_GLOBAL, bootDescriptor(plan), nonce);