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

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

@@ -0,0 +1,684 @@
+/**
+ * Public control-plane contract for managed analytics integrations.
+ *
+ * Tenant authority comes from the authenticated server context. Consequently no
+ * request in this module accepts a tenant id. The contract is declarative: it can
+ * select an approved adapter and provide primitive configuration values, but it
+ * cannot carry executable markup/code, selectors, storage instructions, secrets,
+ * wildcard origins, legacy Universal Analytics ids, or GTM container ids.
+ */
+import type { ContractResult } from "./result.js";
+import { Violations, isPlainObject } from "./result.js";
+import { isForbiddenKey } from "./secrets.js";
+import {
+  MANAGED_ANALYTICS_PII_VALUE_PATTERN,
+  MANAGED_ANALYTICS_SECRET_VALUE_PATTERN,
+} from "./managed-analytics-api-v1-safety.mjs";
+
+export const MANAGED_ANALYTICS_API_VERSION = "v1" as const;
+export const MANAGED_ANALYTICS_SCHEMA_VERSION = 1 as const;
+
+export const INTEGRATION_INSTALL_STATUSES = ["disabled", "enabled"] as const;
+export type IntegrationInstallStatus = (typeof INTEGRATION_INSTALL_STATUSES)[number];
+
+export const INTEGRATION_REVISION_STATUSES = ["draft", "active", "superseded"] as const;
+export type IntegrationRevisionStatus = (typeof INTEGRATION_REVISION_STATUSES)[number];
+
+export const ADAPTER_AVAILABILITY = ["available", "deprecated"] as const;
+export type AdapterAvailability = (typeof ADAPTER_AVAILABILITY)[number];
+
+export const ADAPTER_CONFIG_VALUE_KINDS = ["string", "boolean", "integer"] as const;
+export type AdapterConfigValueKind = (typeof ADAPTER_CONFIG_VALUE_KINDS)[number];
+export type AdapterConfigValue = string | boolean | number;
+/** Public identifiers are opaque handles: never emails, names, or user-provided labels. */
+export type OpaquePublicId = string;
+/** Stable, redacted machine code; migration findings never contain source text or PII. */
+export type MigrationFindingCode = string;
+/** Operator-safe text that must not interpolate request values, secrets, or PII. */
+export type RedactedPublicMessage = string;
+
+export interface AdapterConfigField {
+  key: string;
+  label: string;
+  description: string;
+  kind: AdapterConfigValueKind;
+  required: boolean;
+}
+
+export interface AdapterDeprecation {
+  deprecatedAt: string;
+  sunsetAt: string;
+  replacementAdapterId?: OpaquePublicId;
+}
+
+/** A reviewed catalog entry. It describes configuration; it is not executable. */
+export interface AdapterDefinition {
+  schemaVersion: typeof MANAGED_ANALYTICS_SCHEMA_VERSION;
+  adapterId: OpaquePublicId;
+  adapterVersion: string;
+  displayName: string;
+  description: string;
+  availability: AdapterAvailability;
+  configuration: AdapterConfigField[];
+  eventTypes: string[];
+  consentPurposes: string[];
+  /** Exact HTTPS collection origins. Paths, queries, credentials, and wildcards fail validation. */
+  collectionOrigins: string[];
+  deprecation?: AdapterDeprecation;
+}
+
+export interface IntegrationInstall {
+  schemaVersion: typeof MANAGED_ANALYTICS_SCHEMA_VERSION;
+  installId: OpaquePublicId;
+  adapterId: OpaquePublicId;
+  status: IntegrationInstallStatus;
+  activeRevisionId: OpaquePublicId | null;
+  /** Monotonic compare-and-swap token for mutations against this install. */
+  revision: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface IntegrationRevisionV1 {
+  schemaVersion: typeof MANAGED_ANALYTICS_SCHEMA_VERSION;
+  revisionId: OpaquePublicId;
+  installId: OpaquePublicId;
+  adapterId: OpaquePublicId;
+  adapterVersion: string;
+  sequence: number;
+  status: IntegrationRevisionStatus;
+  configuration: Record<string, AdapterConfigValue>;
+  createdAt: string;
+}
+
+/**
+ * An approved migration suggestion. A migration draft is inert by contract: it
+ * cannot enable an install or publish a revision. A separate install mutation is
+ * always required after review.
+ */
+export interface MigrationDraftV1 {
+  schemaVersion: typeof MANAGED_ANALYTICS_SCHEMA_VERSION;
+  draftId: OpaquePublicId;
+  /** Monotonic compare-and-swap token for update and delete mutations. */
+  revision: number;
+  source: "approved-migration";
+  status: "draft";
+  enabled: false;
+  publishes: false;
+  proposedAdapterId: OpaquePublicId;
+  proposedConfiguration: Record<string, AdapterConfigValue>;
+  findings: MigrationFindingCode[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface PageRequest {
+  cursor?: OpaquePublicId;
+  limit?: number;
+}
+
+export interface Page<T> {
+  items: T[];
+  nextCursor?: string;
+}
+
+/** Common envelope for reads. `tenantId` is deliberately absent. */
+export interface ReadRequest<TQuery extends object = Record<string, never>> {
+  apiVersion: typeof MANAGED_ANALYTICS_API_VERSION;
+  query: TQuery;
+}
+
+/**
+ * Common envelope for writes. Every write is idempotency-keyed and CAS-guarded.
+ * Reusing a key with the same canonical request replays the original response;
+ * reusing it with different content fails with `idempotency_conflict`. A stale
+ * `expectedRevision` fails with `stale_revision` and never partially applies.
+ */
+export interface MutationRequest<TBody extends object> {
+  apiVersion: typeof MANAGED_ANALYTICS_API_VERSION;
+  idempotencyKey: OpaquePublicId;
+  expectedRevision: number;
+  body: TBody;
+}
+
+export interface ApiSuccess<T> {
+  apiVersion: typeof MANAGED_ANALYTICS_API_VERSION;
+  requestId: OpaquePublicId;
+  data: T;
+}
+
+export interface MutationSuccess<T> extends ApiSuccess<T> {
+  idempotencyReplayed: boolean;
+}
+
+export const MANAGED_ANALYTICS_ERROR_CODES = [
+  "invalid_request",
+  "unauthorized",
+  "forbidden",
+  "not_found",
+  "validation_failed",
+  "unsupported_version",
+  "stale_revision",
+  "idempotency_conflict",
+  "adapter_deprecated",
+  "conflict",
+  "internal_error",
+] as const;
+export type ManagedAnalyticsErrorCode = (typeof MANAGED_ANALYTICS_ERROR_CODES)[number];
+
+export interface ApiErrorDetail {
+  /** Redacted schema path only; never a raw input value. */
+  path: string;
+  code: string;
+  message: RedactedPublicMessage;
+}
+
+export interface ApiError {
+  code: ManagedAnalyticsErrorCode;
+  message: RedactedPublicMessage;
+  details?: ApiErrorDetail[];
+}
+
+export interface ApiErrorEnvelope {
+  apiVersion: typeof MANAGED_ANALYTICS_API_VERSION;
+  requestId: OpaquePublicId;
+  error: ApiError;
+}
+
+export type ApiResult<T> = ApiSuccess<T> | ApiErrorEnvelope;
+export type MutationResult<T> = MutationSuccess<T> | ApiErrorEnvelope;
+
+export type ListAdapterDefinitionsRequest = ReadRequest<PageRequest>;
+export type ListAdapterDefinitionsResponse = ApiResult<Page<AdapterDefinition>>;
+export type GetAdapterDefinitionRequest = ReadRequest<{ adapterId: OpaquePublicId }>;
+export type GetAdapterDefinitionResponse = ApiResult<AdapterDefinition>;
+export type ListIntegrationInstallsRequest = ReadRequest<PageRequest>;
+export type ListIntegrationInstallsResponse = ApiResult<Page<IntegrationInstall>>;
+export type GetIntegrationInstallRequest = ReadRequest<{ installId: OpaquePublicId }>;
+export type GetIntegrationInstallResponse = ApiResult<IntegrationInstall>;
+export type ListIntegrationRevisionsRequest = ReadRequest<{ installId: OpaquePublicId } & PageRequest>;
+export type ListIntegrationRevisionsResponse = ApiResult<Page<IntegrationRevisionV1>>;
+export type GetIntegrationRevisionRequest = ReadRequest<{ installId: OpaquePublicId; revisionId: OpaquePublicId }>;
+export type GetIntegrationRevisionResponse = ApiResult<IntegrationRevisionV1>;
+export type GetMigrationDraftRequest = ReadRequest<{ draftId: OpaquePublicId }>;
+export type GetMigrationDraftResponse = ApiResult<MigrationDraftV1>;
+
+export interface CreateMigrationDraftBody {
+  proposedAdapterId: OpaquePublicId;
+  proposedConfiguration: Record<string, AdapterConfigValue>;
+  /** Stable redacted codes only; raw migration-source text is never public. */
+  findings: MigrationFindingCode[];
+}
+export type CreateMigrationDraftRequest = MutationRequest<CreateMigrationDraftBody>;
+export type CreateMigrationDraftResponse = MutationResult<MigrationDraftV1>;
+
+export interface UpdateMigrationDraftBody {
+  draftId: OpaquePublicId;
+  proposedAdapterId: OpaquePublicId;
+  proposedConfiguration: Record<string, AdapterConfigValue>;
+  /** Stable redacted codes only; raw migration-source text is never public. */
+  findings: MigrationFindingCode[];
+}
+export type UpdateMigrationDraftRequest = MutationRequest<UpdateMigrationDraftBody>;
+export type UpdateMigrationDraftResponse = MutationResult<MigrationDraftV1>;
+
+export interface DeleteMigrationDraftBody { draftId: OpaquePublicId }
+export type DeleteMigrationDraftRequest = MutationRequest<DeleteMigrationDraftBody>;
+export type DeleteMigrationDraftResponse = MutationResult<{ deleted: true }>;
+
+export interface CreateIntegrationInstallBody {
+  adapterId: OpaquePublicId;
+  adapterVersion: string;
+  configuration: Record<string, AdapterConfigValue>;
+  /** Creation is reviewed-first; callers cannot create a live install in one step. */
+  status: "disabled";
+}
+export type CreateIntegrationInstallRequest = MutationRequest<CreateIntegrationInstallBody>;
+export type CreateIntegrationInstallResponse = MutationResult<{
+  install: IntegrationInstall;
+  revision: IntegrationRevisionV1;
+}>;
+
+export interface ReviseIntegrationInstallBody {
+  installId: OpaquePublicId;
+  adapterVersion: string;
+  configuration: Record<string, AdapterConfigValue>;
+}
+export type ReviseIntegrationInstallRequest = MutationRequest<ReviseIntegrationInstallBody>;
+export type ReviseIntegrationInstallResponse = MutationResult<{
+  install: IntegrationInstall;
+  revision: IntegrationRevisionV1;
+}>;
+
+export interface SetIntegrationInstallStatusBody {
+  installId: OpaquePublicId;
+  status: IntegrationInstallStatus;
+}
+export type SetIntegrationInstallStatusRequest = MutationRequest<SetIntegrationInstallStatusBody>;
+export type SetIntegrationInstallStatusResponse = MutationResult<IntegrationInstall>;
+
+export interface DeleteIntegrationInstallBody { installId: OpaquePublicId }
+export type DeleteIntegrationInstallRequest = MutationRequest<DeleteIntegrationInstallBody>;
+export type DeleteIntegrationInstallResponse = MutationResult<{ deleted: true }>;
+
+/** The only backend seam WS2 needs; tests can mock this interface without HTTP. */
+export interface ManagedAnalyticsApiV1Client {
+  listAdapterDefinitions(request: ListAdapterDefinitionsRequest): Promise<ListAdapterDefinitionsResponse>;
+  getAdapterDefinition(request: GetAdapterDefinitionRequest): Promise<GetAdapterDefinitionResponse>;
+  listIntegrationInstalls(request: ListIntegrationInstallsRequest): Promise<ListIntegrationInstallsResponse>;
+  getIntegrationInstall(request: GetIntegrationInstallRequest): Promise<GetIntegrationInstallResponse>;
+  listIntegrationRevisions(request: ListIntegrationRevisionsRequest): Promise<ListIntegrationRevisionsResponse>;
+  getIntegrationRevision(request: GetIntegrationRevisionRequest): Promise<GetIntegrationRevisionResponse>;
+  getMigrationDraft(request: GetMigrationDraftRequest): Promise<GetMigrationDraftResponse>;
+  createMigrationDraft(request: CreateMigrationDraftRequest): Promise<CreateMigrationDraftResponse>;
+  updateMigrationDraft(request: UpdateMigrationDraftRequest): Promise<UpdateMigrationDraftResponse>;
+  deleteMigrationDraft(request: DeleteMigrationDraftRequest): Promise<DeleteMigrationDraftResponse>;
+  createIntegrationInstall(request: CreateIntegrationInstallRequest): Promise<CreateIntegrationInstallResponse>;
+  reviseIntegrationInstall(request: ReviseIntegrationInstallRequest): Promise<ReviseIntegrationInstallResponse>;
+  setIntegrationInstallStatus(request: SetIntegrationInstallStatusRequest): Promise<SetIntegrationInstallStatusResponse>;
+  deleteIntegrationInstall(request: DeleteIntegrationInstallRequest): Promise<DeleteIntegrationInstallResponse>;
+}
+
+export const MANAGED_ANALYTICS_API_V1_VERSION_POLICY = Object.freeze({
+  path: "/api/integrations/v1",
+  breakingChanges: "new-major-path",
+  additiveChanges: "new-operations-only; resource-shape-changes-bump-schemaVersion",
+  unknownRequestFields: "reject",
+  deprecatedAdapter: Object.freeze({
+    newInstalls: "reject-after-deprecatedAt",
+    existingInstalls: "readable-until-sunsetAt",
+    sunsetMinimumDays: 90,
+  }),
+} as const);
+
+const FORBIDDEN_KEY_WORDS = [
+  "tenant", "html", "javascript", "js", "script", "template", "eval", "selector",
+  "storage", "cookie", "secret", "token", "credential", "password", "gtm",
+] as const;
+const FORBIDDEN_KEY_FORMS = [
+  "tenantid", "privatekey", "apikey", "liveauthority", "publishauthority", "uaid",
+  "localstorage", "sessionstorage",
+] as const;
+const PUBLIC_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const FINDING_CODE = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+const REDACTED_PATH = /^(?:\$|[A-Za-z][A-Za-z0-9]*)(?:\.[A-Za-z][A-Za-z0-9]*|\[[0-9]+\])*$/;
+const GTM_OR_UA_ID = /(?:GTM-[A-Z0-9]+|UA-\d+-\d+)/i;
+const PII_VALUE = new RegExp(MANAGED_ANALYTICS_PII_VALUE_PATTERN);
+const SECRET_VALUE = new RegExp(MANAGED_ANALYTICS_SECRET_VALUE_PATTERN);
+const PROTOTYPE_PATH_KEYS = new Set(["constructor", "prototype", "__proto__"]);
+const SECRET_PATH_KEY_HINT = /^(?:AKIA|AIza|SG|eyJ|(?:sk|rk)(?:Live|Test|Prod)|gh[pousr]|githubPat|npm|glpat|xox|secret|password|credential|apiKey|clientSecret|privateKey)/i;
+const EXECUTABLE_OR_INSTRUCTION_VALUE =
+  /(?:<\/?[a-z][^>]*>|javascript\s*:|\beval\s*\(|\b(?:alert|fetch)\s*\(|\{\{|\}\}|\$\{|#[a-z_][\w-]*|(?:^|[\s,>+~])\.[a-z_-][\w-]*(?:$|[\s,>+~.#[:])|\[[a-z_:][-a-z0-9_:.]*(?:[~|^$*]?=[^\]]+)?\]|\b(?:local|session)Storage\b|\bindexedDB\b|\bquerySelector\b|\b(?:window|document|globalThis|console)\s*(?:\.|\[)|\b[a-z_$][\w$]*\s*\.\s*[a-z_$][\w$]*\s*\(|\b[a-z_$][\w$]*\s*\([^)]*\)\s*;|\breturn\b[^;{}]*;|\bfunction\b|=>|\b(?:var|let|const)\s+[a-z_$])/i;
+
+function redactedPathKey(key: string): string | undefined {
+  if (!/^[A-Za-z][A-Za-z0-9]*$/.test(key) || PROTOTYPE_PATH_KEYS.has(key) ||
+      Object.prototype.hasOwnProperty.call(Object.prototype, key)) return undefined;
+  return SECRET_PATH_KEY_HINT.test(key) ? undefined : key;
+}
+function pathAt(path: string, key: string): string {
+  const safe = redactedPathKey(key);
+  if (!safe) return path || "$";
+  return path && path !== "$" ? `${path}.${safe}` : path === "$" ? `$.${safe}` : safe;
+}
+function indexAt(path: string, index: string | number): string { return `${path || "$"}[${index}]`; }
+function keyWords(key: string): string[] {
+  return key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[^a-zA-Z0-9]+/g, " ").toLowerCase().split(/\s+/).filter(Boolean);
+}
+function isForbiddenKeyName(key: string): boolean {
+  const tokens = keyWords(key);
+  const collapsed = tokens.join("");
+  return isForbiddenKey(key) || tokens.some((token) => FORBIDDEN_KEY_WORDS.includes(token as (typeof FORBIDDEN_KEY_WORDS)[number])) || FORBIDDEN_KEY_FORMS.includes(collapsed as (typeof FORBIDDEN_KEY_FORMS)[number]);
+}
+
+class HostileManagedAnalyticsInput extends Error {
+  constructor(readonly redactedPath: string) { super("managed_analytics_input_unreadable"); }
+}
+const MANAGED_ANALYTICS_SNAPSHOTS = new WeakSet<object>();
+
+/**
+ * Detach public input without invoking getters or ordinary property reads. A
+ * proxy can still trap the reflection operations themselves, so each object is
+ * asked for its key set once and each descriptor once; any trap failure is
+ * collapsed to one stable, redacted boundary violation.
+ */
+export function snapshotManagedAnalyticsDeclarativeInput<T>(input: unknown): ContractResult<T> {
+  const copies = new WeakMap<object, object>();
+  const active = new WeakSet<object>();
+  const fail = (path: string): never => { throw new HostileManagedAnalyticsInput(path && REDACTED_PATH.test(path) ? path : "$"); };
+  const copy = (value: unknown, path: string): unknown => {
+    if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+    if (typeof value === "number") return Number.isFinite(value) ? value : fail(path);
+    if (typeof value !== "object") return fail(path);
+    if (MANAGED_ANALYTICS_SNAPSHOTS.has(value)) return value;
+    if (active.has(value)) return fail(path);
+    const prior = copies.get(value);
+    if (prior) return prior;
+
+    let array: boolean;
+    let keys: readonly PropertyKey[];
+    let prototype: object | null;
+    try {
+      array = Array.isArray(value);
+      keys = Reflect.ownKeys(value);
+      prototype = Reflect.getPrototypeOf(value);
+    } catch {
+      return fail(path);
+    }
+    if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) return fail(path);
+    const output: Record<string, unknown> | unknown[] = array ? [] : Object.create(null) as Record<string, unknown>;
+    let arrayLength: number | undefined;
+    let arrayIndexes = 0;
+    let maximumArrayIndex = -1;
+    copies.set(value, output);
+    active.add(value);
+    try {
+      for (const key of keys) {
+        let descriptor: PropertyDescriptor | undefined;
+        try { descriptor = Reflect.getOwnPropertyDescriptor(value, key); }
+        catch { return fail(path); }
+        if (!descriptor) return fail(path);
+        if (array && key === "length") {
+          if (!("value" in descriptor) || typeof descriptor.value !== "number" ||
+              !Number.isInteger(descriptor.value) || descriptor.value < 0 || descriptor.value > 0xffff_ffff) return fail(path);
+          arrayLength = descriptor.value;
+          continue;
+        }
+        if (!descriptor.enumerable) continue;
+        if (typeof key !== "string" || !("value" in descriptor)) return fail(typeof key === "string" ? pathAt(path, key) : path);
+        if (array) {
+          const index = Number(key);
+          if (!/^(?:0|[1-9]\d*)$/.test(key) || !Number.isSafeInteger(index) || index >= 0xffff_ffff) return fail(pathAt(path, key));
+          arrayIndexes += 1;
+          maximumArrayIndex = Math.max(maximumArrayIndex, index);
+        }
+        const child = copy(descriptor.value, array ? indexAt(path, key) : pathAt(path, key));
+        if (array) (output as unknown[])[Number(key)] = child;
+        else Object.defineProperty(output, key, { value: child, enumerable: true, writable: false, configurable: false });
+      }
+      if (array && (arrayLength === undefined || arrayIndexes !== arrayLength || maximumArrayIndex >= arrayLength)) return fail(path);
+      const frozen = Object.freeze(output);
+      MANAGED_ANALYTICS_SNAPSHOTS.add(frozen);
+      return frozen;
+    } finally {
+      active.delete(value);
+    }
+  };
+
+  try { return { ok: true, value: copy(input, "") as T }; }
+  catch (cause) {
+    const path = cause instanceof HostileManagedAnalyticsInput ? cause.redactedPath : "$";
+    return { ok: false, violations: [{ path, code: "hostile_object", message: "Input could not be safely read as declarative data." }] };
+  }
+}
+
+function rejectKeys(obj: Record<string, unknown>, allowed: readonly string[], v: Violations, path: string): void {
+  for (const key of Object.keys(obj)) {
+    if (!allowed.includes(key)) v.add(pathAt(path, key), "unknown_field", "Unknown field; this contract is closed.");
+  }
+}
+function object(value: unknown, v: Violations, path: string): Record<string, unknown> | undefined {
+  if (!isPlainObject(value)) { v.add(path || "$", "type", "Expected an object."); return undefined; }
+  return value;
+}
+function string(obj: Record<string, unknown>, key: string, v: Violations, path: string): string | undefined {
+  const value = obj[key];
+  if (typeof value !== "string" || value.length === 0) { v.add(pathAt(path, key), "type", "Expected a non-empty string."); return undefined; }
+  return value;
+}
+function integer(obj: Record<string, unknown>, key: string, v: Violations, path: string, minimum = 0): number | undefined {
+  const value = obj[key];
+  if (typeof value !== "number" || !Number.isInteger(value) || value < minimum) { v.add(pathAt(path, key), "type", `Expected an integer >= ${minimum}.`); return undefined; }
+  return value;
+}
+function timestamp(obj: Record<string, unknown>, key: string, v: Violations, path: string): string | undefined {
+  const value = string(obj, key, v, path);
+  if (value !== undefined && (!/^\d{4}-\d{2}-\d{2}T/.test(value) || Number.isNaN(Date.parse(value)))) v.add(pathAt(path, key), "format", "Expected an ISO-8601 timestamp.");
+  return value;
+}
+function literal(obj: Record<string, unknown>, key: string, expected: unknown, v: Violations, path: string): void {
+  if (obj[key] !== expected) v.add(pathAt(path, key), "unsupported_value", `Expected ${JSON.stringify(expected)}.`);
+}
+function stringArray(obj: Record<string, unknown>, key: string, v: Violations, path: string): string[] | undefined {
+  const value = obj[key];
+  if (!Array.isArray(value)) { v.add(pathAt(path, key), "type", "Expected an array."); return undefined; }
+  const out: string[] = [];
+  value.forEach((item, i) => typeof item === "string" && item.length > 0 ? out.push(item) : v.add(`${pathAt(path, key)}[${i}]`, "type", "Expected a non-empty string."));
+  return out;
+}
+function enumeration(obj: Record<string, unknown>, key: string, values: readonly string[], v: Violations, path: string): string | undefined {
+  const value = string(obj, key, v, path);
+  if (value !== undefined && !values.includes(value)) { v.add(pathAt(path, key), "unknown_enum", `Expected one of: ${values.join(", ")}.`); return undefined; }
+  return value;
+}
+function opaqueId(obj: Record<string, unknown>, key: string, v: Violations, path: string): string | undefined {
+  const value = string(obj, key, v, path);
+  if (value !== undefined && !PUBLIC_ID.test(value)) { v.add(pathAt(path, key), "opaque_id", "Expected an opaque public identifier."); return undefined; }
+  return value;
+}
+function findingCodes(obj: Record<string, unknown>, key: string, v: Violations, path: string): string[] | undefined {
+  const values = stringArray(obj, key, v, path);
+  values?.forEach((value, i) => { if (!FINDING_CODE.test(value)) v.add(`${pathAt(path, key)}[${i}]`, "redacted_code", "Expected a stable redacted finding code."); });
+  return values;
+}
+
+/** Defense-in-depth for every declarative request/resource payload. */
+export function validateManagedAnalyticsSafePayload(input: unknown): ContractResult<unknown> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<unknown>(input);
+  if (!prepared.ok) return prepared;
+  const v = new Violations();
+  const seen = new Set<unknown>();
+  const walk = (value: unknown, path: string): void => {
+    if (typeof value === "string" && GTM_OR_UA_ID.test(value.trim())) v.add(path || "$", "legacy_execution_id", "GTM container ids and Universal Analytics ids are not accepted by managed analytics.");
+    if (typeof value === "string" && SECRET_VALUE.test(value)) v.add(path || "$", "secret_value", "Secret-shaped values are not accepted by managed analytics.");
+    if (typeof value === "string" && PII_VALUE.test(value)) v.add(path || "$", "pii_value", "PII-shaped values are not accepted by managed analytics.");
+    if (typeof value === "string" && EXECUTABLE_OR_INSTRUCTION_VALUE.test(value)) v.add(path || "$", "executable_value", "Executable markup, code, templates, selectors, and browser storage instructions are not accepted by managed analytics.");
+    if (Array.isArray(value)) { value.forEach((item, i) => walk(item, indexAt(path, i))); return; }
+    if (!isPlainObject(value) || seen.has(value)) return;
+    seen.add(value);
+    for (const [key, child] of Object.entries(value)) {
+      if (isForbiddenKeyName(key)) v.add(pathAt(path, key), "forbidden_field", "A field names data outside the declarative managed-analytics contract.");
+      walk(child, pathAt(path, key));
+    }
+  };
+  walk(prepared.value, "");
+  return v.ok ? prepared : { ok: false, violations: v.items };
+}
+
+function validateConfig(input: unknown, v: Violations, path: string): void {
+  const obj = object(input, v, path);
+  if (!obj) return;
+  for (const [key, value] of Object.entries(obj)) {
+    if (!/^[a-z][a-zA-Z0-9]{0,63}$/.test(key)) v.add(pathAt(path, key), "format", "Configuration keys must be lower camel-case identifiers.");
+    if (!(typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isInteger(value)))) v.add(pathAt(path, key), "type", "Configuration values must be strings, booleans, or integers.");
+    if (typeof value === "string" && EXECUTABLE_OR_INSTRUCTION_VALUE.test(value)) v.add(pathAt(path, key), "executable_value", "Configuration cannot contain markup, JavaScript, templates, selectors, or storage instructions.");
+  }
+  const safe = validateManagedAnalyticsSafePayload(obj);
+  if (!safe.ok) for (const item of safe.violations) v.items.push({ ...item, path: pathAt(path, item.path) });
+}
+
+function validateExactOrigin(value: string, v: Violations, path: string): void {
+  if (value.includes("*")) { v.add(path, "wildcard_origin", "Wildcard origins are forbidden."); return; }
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "https:" || url.username || url.password || url.pathname !== "/" || url.search || url.hash || url.origin !== value.replace(/\/$/, "")) v.add(path, "origin", "Expected an exact HTTPS origin with no path, query, fragment, or credentials.");
+  } catch { v.add(path, "origin", "Expected an exact HTTPS origin."); }
+}
+
+export function validateAdapterDefinition(input: unknown): ContractResult<AdapterDefinition> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<AdapterDefinition>(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", "adapterId", "adapterVersion", "displayName", "description", "availability", "configuration", "eventTypes", "consentPurposes", "collectionOrigins", "deprecation"], v, "");
+  literal(obj, "schemaVersion", 1, v, ""); opaqueId(obj, "adapterId", v, ""); opaqueId(obj, "adapterVersion", v, ""); string(obj, "displayName", v, ""); string(obj, "description", v, "");
+  const availability = enumeration(obj, "availability", ADAPTER_AVAILABILITY, v, "");
+  const fields = obj.configuration;
+  if (!Array.isArray(fields)) v.add("configuration", "type", "Expected an array.");
+  else fields.forEach((field, i) => {
+    const path = `configuration[${i}]`; const f = object(field, v, path); if (!f) return;
+    rejectKeys(f, ["key", "label", "description", "kind", "required"], v, path);
+    const key = string(f, "key", v, path); if (key && (!/^[a-z][a-zA-Z0-9]{0,63}$/.test(key) || isForbiddenKeyName(key))) v.add(`${path}.key`, "forbidden_field", "Configuration field names must be safe lower camel-case identifiers.");
+    string(f, "label", v, path); string(f, "description", v, path); enumeration(f, "kind", ADAPTER_CONFIG_VALUE_KINDS, v, path);
+    if (typeof f.required !== "boolean") v.add(`${path}.required`, "type", "Expected a boolean.");
+  });
+  if (Array.isArray(fields)) {
+    const keys = fields.flatMap((field) => isPlainObject(field) && typeof field.key === "string" ? [field.key] : []);
+    if (new Set(keys).size !== keys.length) v.add("configuration", "duplicate", "Configuration field keys must be unique.");
+  }
+  const events = stringArray(obj, "eventTypes", v, ""); if (events && new Set(events).size !== events.length) v.add("eventTypes", "duplicate", "Event types must be unique.");
+  const purposes = stringArray(obj, "consentPurposes", v, ""); if (purposes && new Set(purposes).size !== purposes.length) v.add("consentPurposes", "duplicate", "Consent purposes must be unique.");
+  const origins = stringArray(obj, "collectionOrigins", v, ""); origins?.forEach((origin, i) => validateExactOrigin(origin, v, `collectionOrigins[${i}]`));
+  if (origins && new Set(origins).size !== origins.length) v.add("collectionOrigins", "duplicate", "Collection origins must be unique.");
+  if (availability === "available" && obj.deprecation !== undefined) v.add("deprecation", "state", "Available adapters cannot carry deprecation metadata.");
+  if (availability === "deprecated" || obj.deprecation !== undefined) {
+    const d = object(obj.deprecation, v, "deprecation");
+    if (d) { rejectKeys(d, ["deprecatedAt", "sunsetAt", "replacementAdapterId"], v, "deprecation"); const deprecatedAt = timestamp(d, "deprecatedAt", v, "deprecation"); const sunsetAt = timestamp(d, "sunsetAt", v, "deprecation"); if (d.replacementAdapterId !== undefined) string(d, "replacementAdapterId", v, "deprecation"); if (deprecatedAt && sunsetAt && Date.parse(sunsetAt) - Date.parse(deprecatedAt) < 90 * 86_400_000) v.add("deprecation.sunsetAt", "deprecation_window", "Adapter sunset must be at least 90 days after deprecation."); }
+  }
+  const safe = validateManagedAnalyticsSafePayload(obj); if (!safe.ok) v.items.push(...safe.violations);
+  return v.ok ? prepared : { ok: false, violations: v.items };
+}
+
+export function validateIntegrationInstall(input: unknown): ContractResult<IntegrationInstall> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<IntegrationInstall>(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", "installId", "adapterId", "status", "activeRevisionId", "revision", "createdAt", "updatedAt"], v, "");
+  literal(obj, "schemaVersion", 1, v, ""); opaqueId(obj, "installId", v, ""); opaqueId(obj, "adapterId", v, ""); enumeration(obj, "status", INTEGRATION_INSTALL_STATUSES, v, "");
+  if (!(obj.activeRevisionId === null || (typeof obj.activeRevisionId === "string" && PUBLIC_ID.test(obj.activeRevisionId)))) v.add("activeRevisionId", "opaque_id", "Expected an opaque public identifier or null.");
+  integer(obj, "revision", v, "", 0); timestamp(obj, "createdAt", v, ""); timestamp(obj, "updatedAt", v, "");
+  const safe = validateManagedAnalyticsSafePayload(obj); if (!safe.ok) v.items.push(...safe.violations);
+  return v.ok ? prepared : { ok: false, violations: v.items };
+}
+
+export function validateIntegrationRevisionV1(input: unknown): ContractResult<IntegrationRevisionV1> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<IntegrationRevisionV1>(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", "revisionId", "installId", "adapterId", "adapterVersion", "sequence", "status", "configuration", "createdAt"], v, "");
+  literal(obj, "schemaVersion", 1, v, ""); opaqueId(obj, "revisionId", v, ""); opaqueId(obj, "installId", v, ""); opaqueId(obj, "adapterId", v, ""); opaqueId(obj, "adapterVersion", v, ""); integer(obj, "sequence", v, "", 1); enumeration(obj, "status", INTEGRATION_REVISION_STATUSES, v, ""); validateConfig(obj.configuration, v, "configuration"); 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 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 };
+  rejectKeys(obj, ["schemaVersion", "draftId", "revision", "source", "status", "enabled", "publishes", "proposedAdapterId", "proposedConfiguration", "findings", "createdAt", "updatedAt"], v, "");
+  literal(obj, "schemaVersion", 1, v, ""); opaqueId(obj, "draftId", v, ""); integer(obj, "revision", v, "", 0); literal(obj, "source", "approved-migration", v, ""); literal(obj, "status", "draft", v, ""); literal(obj, "enabled", false, v, ""); literal(obj, "publishes", false, v, ""); opaqueId(obj, "proposedAdapterId", v, ""); validateConfig(obj.proposedConfiguration, v, "proposedConfiguration"); findingCodes(obj, "findings", v, ""); timestamp(obj, "createdAt", v, ""); timestamp(obj, "updatedAt", v, "");
+  const safe = validateManagedAnalyticsSafePayload(obj); if (!safe.ok) v.items.push(...safe.violations);
+  return v.ok ? prepared : { ok: false, violations: v.items };
+}
+
+export function validateReadRequest(input: unknown): ContractResult<ReadRequest<Record<string, unknown>>> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<ReadRequest<Record<string, unknown>>>(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, ["apiVersion", "query"], v, ""); literal(obj, "apiVersion", "v1", v, ""); object(obj.query, v, "query");
+  const safe = validateManagedAnalyticsSafePayload(obj); if (!safe.ok) v.items.push(...safe.violations);
+  return v.ok ? prepared : { ok: false, violations: v.items };
+}
+
+export function validateMutationRequest(input: unknown): ContractResult<MutationRequest<Record<string, unknown>>> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<MutationRequest<Record<string, unknown>>>(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, ["apiVersion", "idempotencyKey", "expectedRevision", "body"], v, ""); literal(obj, "apiVersion", "v1", v, "");
+  const key = string(obj, "idempotencyKey", v, ""); if (key && (key.length < 8 || key.length > 128 || !PUBLIC_ID.test(key))) v.add("idempotencyKey", "opaque_id", "Idempotency keys must be opaque and contain 8–128 characters.");
+  integer(obj, "expectedRevision", v, "", 0); object(obj.body, v, "body");
+  const safe = validateManagedAnalyticsSafePayload(obj); if (!safe.ok) v.items.push(...safe.violations);
+  return v.ok ? prepared : { ok: false, violations: v.items };
+}
+
+type ObjectShapeValidator = (obj: Record<string, unknown>, v: Violations, path: string) => void;
+
+function validateReadOperation<T>(input: unknown, validateQuery: ObjectShapeValidator): ContractResult<T> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<T>(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, ["apiVersion", "query"], v, ""); literal(obj, "apiVersion", "v1", v, "");
+  const query = object(obj.query, v, "query"); if (query) validateQuery(query, v, "query");
+  const safe = validateManagedAnalyticsSafePayload(obj); if (!safe.ok) v.items.push(...safe.violations);
+  return v.ok ? prepared : { ok: false, violations: v.items };
+}
+
+function validateMutationOperation<T>(input: unknown, validateBody: ObjectShapeValidator): ContractResult<T> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<T>(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, ["apiVersion", "idempotencyKey", "expectedRevision", "body"], v, ""); literal(obj, "apiVersion", "v1", v, "");
+  const key = string(obj, "idempotencyKey", v, ""); if (key && (key.length < 8 || key.length > 128 || !PUBLIC_ID.test(key))) v.add("idempotencyKey", "opaque_id", "Idempotency keys must be opaque and contain 8–128 characters.");
+  integer(obj, "expectedRevision", v, "", 0);
+  const body = object(obj.body, v, "body"); if (body) validateBody(body, v, "body");
+  const safe = validateManagedAnalyticsSafePayload(obj); if (!safe.ok) v.items.push(...safe.violations);
+  return v.ok ? prepared : { ok: false, violations: v.items };
+}
+
+function validatePageShape(obj: Record<string, unknown>, v: Violations, path: string, required: readonly string[] = []): void {
+  rejectKeys(obj, [...required, "cursor", "limit"], v, path);
+  for (const key of required) opaqueId(obj, key, v, path);
+  if ("cursor" in obj) opaqueId(obj, "cursor", v, path);
+  if ("limit" in obj) integer(obj, "limit", v, path, 1);
+}
+
+const validateAdapterIdQuery: ObjectShapeValidator = (obj, v, path) => { rejectKeys(obj, ["adapterId"], v, path); opaqueId(obj, "adapterId", v, path); };
+const validateInstallIdQuery: ObjectShapeValidator = (obj, v, path) => { rejectKeys(obj, ["installId"], v, path); opaqueId(obj, "installId", v, path); };
+const validateRevisionQuery: ObjectShapeValidator = (obj, v, path) => { rejectKeys(obj, ["installId", "revisionId"], v, path); opaqueId(obj, "installId", v, path); opaqueId(obj, "revisionId", v, path); };
+const validateDraftIdQuery: ObjectShapeValidator = (obj, v, path) => { rejectKeys(obj, ["draftId"], v, path); opaqueId(obj, "draftId", v, path); };
+
+export function validateListAdapterDefinitionsRequest(input: unknown): ContractResult<ListAdapterDefinitionsRequest> { return validateReadOperation(input, validatePageShape); }
+export function validateGetAdapterDefinitionRequest(input: unknown): ContractResult<GetAdapterDefinitionRequest> { return validateReadOperation(input, validateAdapterIdQuery); }
+export function validateListIntegrationInstallsRequest(input: unknown): ContractResult<ListIntegrationInstallsRequest> { return validateReadOperation(input, validatePageShape); }
+export function validateGetIntegrationInstallRequest(input: unknown): ContractResult<GetIntegrationInstallRequest> { return validateReadOperation(input, validateInstallIdQuery); }
+export function validateListIntegrationRevisionsRequest(input: unknown): ContractResult<ListIntegrationRevisionsRequest> { return validateReadOperation(input, (obj, v, path) => validatePageShape(obj, v, path, ["installId"])); }
+export function validateGetIntegrationRevisionRequest(input: unknown): ContractResult<GetIntegrationRevisionRequest> { return validateReadOperation(input, validateRevisionQuery); }
+export function validateGetMigrationDraftRequest(input: unknown): ContractResult<GetMigrationDraftRequest> { return validateReadOperation(input, validateDraftIdQuery); }
+
+const validateCreateMigrationDraftBody: ObjectShapeValidator = (obj, v, path) => {
+  rejectKeys(obj, ["proposedAdapterId", "proposedConfiguration", "findings"], v, path);
+  opaqueId(obj, "proposedAdapterId", v, path); validateConfig(obj.proposedConfiguration, v, `${path}.proposedConfiguration`); findingCodes(obj, "findings", v, path);
+};
+const validateUpdateMigrationDraftBody: ObjectShapeValidator = (obj, v, path) => {
+  rejectKeys(obj, ["draftId", "proposedAdapterId", "proposedConfiguration", "findings"], v, path);
+  opaqueId(obj, "draftId", v, path); opaqueId(obj, "proposedAdapterId", v, path); validateConfig(obj.proposedConfiguration, v, `${path}.proposedConfiguration`); findingCodes(obj, "findings", v, path);
+};
+const validateDeleteMigrationDraftBody: ObjectShapeValidator = (obj, v, path) => { rejectKeys(obj, ["draftId"], v, path); opaqueId(obj, "draftId", v, path); };
+const validateCreateIntegrationInstallBody: ObjectShapeValidator = (obj, v, path) => {
+  rejectKeys(obj, ["adapterId", "adapterVersion", "configuration", "status"], v, path);
+  opaqueId(obj, "adapterId", v, path); opaqueId(obj, "adapterVersion", v, path); validateConfig(obj.configuration, v, `${path}.configuration`); literal(obj, "status", "disabled", v, path);
+};
+const validateReviseIntegrationInstallBody: ObjectShapeValidator = (obj, v, path) => {
+  rejectKeys(obj, ["installId", "adapterVersion", "configuration"], v, path);
+  opaqueId(obj, "installId", v, path); opaqueId(obj, "adapterVersion", v, path); validateConfig(obj.configuration, v, `${path}.configuration`);
+};
+const validateSetIntegrationInstallStatusBody: ObjectShapeValidator = (obj, v, path) => {
+  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); };
+
+export function validateCreateMigrationDraftRequest(input: unknown): ContractResult<CreateMigrationDraftRequest> { return validateMutationOperation(input, validateCreateMigrationDraftBody); }
+export function validateUpdateMigrationDraftRequest(input: unknown): ContractResult<UpdateMigrationDraftRequest> { return validateMutationOperation(input, validateUpdateMigrationDraftBody); }
+export function validateDeleteMigrationDraftRequest(input: unknown): ContractResult<DeleteMigrationDraftRequest> { return validateMutationOperation(input, validateDeleteMigrationDraftBody); }
+export function validateCreateIntegrationInstallRequest(input: unknown): ContractResult<CreateIntegrationInstallRequest> { return validateMutationOperation(input, validateCreateIntegrationInstallBody); }
+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); }
+
+/** Validate the closed, public-safe error shape before it crosses the API boundary. */
+export function validateApiErrorEnvelope(input: unknown): ContractResult<ApiErrorEnvelope> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<ApiErrorEnvelope>(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, ["apiVersion", "requestId", "error"], v, ""); literal(obj, "apiVersion", "v1", v, ""); opaqueId(obj, "requestId", v, "");
+  const error = object(obj.error, v, "error");
+  if (error) {
+    rejectKeys(error, ["code", "message", "details"], v, "error");
+    enumeration(error, "code", MANAGED_ANALYTICS_ERROR_CODES, v, "error"); string(error, "message", v, "error");
+    if (error.details !== undefined) {
+      if (!Array.isArray(error.details)) v.add("error.details", "type", "Expected an array.");
+      else error.details.forEach((detail, i) => {
+        const path = `error.details[${i}]`; const item = object(detail, v, path); if (!item) return;
+        rejectKeys(item, ["path", "code", "message"], v, path);
+        const detailPath = string(item, "path", v, path); if (detailPath && !REDACTED_PATH.test(detailPath)) v.add(`${path}.path`, "redacted_path", "Expected a redacted schema path.");
+        const code = string(item, "code", v, path); if (code && !FINDING_CODE.test(code)) v.add(`${path}.code`, "redacted_code", "Expected a stable redacted error code.");
+        string(item, "message", v, path);
+      });
+    }
+  }
+  const safe = validateManagedAnalyticsSafePayload(obj); if (!safe.ok) v.items.push(...safe.violations);
+  return v.ok ? prepared : { ok: false, violations: v.items };
+}