@splitin/verification-adapter-sdk 0.1.0-beta.0

package/dist/conformance.cjs

@@ -0,0 +1,727 @@
+'use strict';
+
+var _2020_js = require('ajv/dist/2020.js');
+
+// src/errors.ts
+var ProviderError = class extends Error {
+  constructor(code, message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.code = code;
+    this.name = "ProviderError";
+    this.retryable = options.retryable ?? false;
+    this.safeCode = options.safeCode ?? code.toLowerCase();
+    this.retryAfterSeconds = options.retryAfterSeconds;
+  }
+  code;
+  retryable;
+  safeCode;
+  retryAfterSeconds;
+};
+
+// src/identifiers.ts
+var VERIFICATION_ADAPTER_CONTRACT_VERSION = "1.0.0";
+var ENGINE_CONTRACT_VERSION = "1.0.0";
+var PROVIDER_MANIFEST_SCHEMA_URN = "urn:splitin:verification:provider-manifest:v1";
+var STANDARD_PACKAGE_CODES = [
+  "human_idv",
+  "business_kyb",
+  "associated_person_idv",
+  "ownership_review"
+];
+var CANONICAL_STATUSES = [
+  "created",
+  "pending_user_input",
+  "paused",
+  "processing",
+  "manual_review_required",
+  "verified",
+  "declined",
+  "failed",
+  "expired",
+  "canceled",
+  "provider_unavailable",
+  "redacted"
+];
+var TERMINAL_STATUSES = [
+  "verified",
+  "declined",
+  "failed",
+  "expired",
+  "canceled",
+  "redacted"
+];
+var STANDARD_PACKAGE_SET = new Set(STANDARD_PACKAGE_CODES);
+var STANDARD_STATUS_SET = new Set(CANONICAL_STATUSES);
+var TERMINAL_STATUS_SET = new Set(TERMINAL_STATUSES);
+var PROVIDER_CODE = /^[a-z][a-z0-9_]{1,63}$/;
+var LAUNCHER_KEY = /^[a-z][a-z0-9_]{1,63}$/;
+var CUSTOM_PACKAGE = /^[a-z0-9][a-z0-9-]{0,32}(?:\.[a-z0-9][a-z0-9_-]{0,63}){1,6}$/;
+var WEBHOOK_PROTOCOL = /^(?:[a-z][a-z0-9_]{1,63}|[a-z0-9][a-z0-9-]{0,32}(?:\.[a-z0-9][a-z0-9_-]{0,63}){1,6})$/;
+var COUNTRY = /^[A-Z]{2}$/;
+var SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+var GOVERNMENT_ID = /\b(?:ssn|itin|nino|sin|aadhaar|passport|national[_-]?id|tax[_-]?id|ein|ssn_last4)\b/i;
+function isProviderCode(value) {
+  return PROVIDER_CODE.test(value);
+}
+function isLauncherKey(value) {
+  return LAUNCHER_KEY.test(value);
+}
+function isStandardPackageCode(value) {
+  return STANDARD_PACKAGE_SET.has(value);
+}
+function isCustomPackageCode(value) {
+  return CUSTOM_PACKAGE.test(value) && !STANDARD_PACKAGE_SET.has(value);
+}
+function isPackageCode(value) {
+  return isStandardPackageCode(value) || isCustomPackageCode(value);
+}
+function isWebhookProtocol(value) {
+  return WEBHOOK_PROTOCOL.test(value);
+}
+function isCountryCode(value) {
+  return COUNTRY.test(value);
+}
+function isSemver(value) {
+  return SEMVER.test(value);
+}
+function isCanonicalStatus(value) {
+  return STANDARD_STATUS_SET.has(value);
+}
+function isTerminalStatus(value) {
+  return TERMINAL_STATUS_SET.has(value);
+}
+function metadataContainsForbiddenIdentifier(value) {
+  if (value == null) return false;
+  if (typeof value === "string") return GOVERNMENT_ID.test(value);
+  if (Array.isArray(value)) return value.some(metadataContainsForbiddenIdentifier);
+  if (typeof value === "object") {
+    return Object.entries(value).some(([key, nested]) => GOVERNMENT_ID.test(key) || metadataContainsForbiddenIdentifier(nested));
+  }
+  return false;
+}
+function majorsCompatible(left, right) {
+  return left.split(".")[0] === right.split(".")[0];
+}
+
+// src/schema.ts
+var providerManifestV1JsonSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: PROVIDER_MANIFEST_SCHEMA_URN,
+  title: "Verification Provider Manifest V1",
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "contractVersion",
+    "adapterVersion",
+    "engineCompatibility",
+    "provider",
+    "displayName",
+    "supportedPackages",
+    "supportedCountries",
+    "environments",
+    "capabilities",
+    "launcherKeys",
+    "launchPresentations",
+    "configurationSchemaVersion",
+    "configurationSchema",
+    "webhook",
+    "dataPolicy",
+    "retry",
+    "cancellation",
+    "redaction",
+    "apiHosts",
+    "testedApiVersions"
+  ],
+  properties: {
+    contractVersion: { const: "1.0.0" },
+    adapterVersion: { type: "string", pattern: "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$" },
+    engineCompatibility: { type: "string", pattern: "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$" },
+    provider: { type: "string", pattern: "^[a-z][a-z0-9_]{1,63}$" },
+    displayName: { type: "string", minLength: 1 },
+    description: { type: "string" },
+    supportedPackages: {
+      type: "array",
+      minItems: 1,
+      uniqueItems: true,
+      items: {
+        type: "string",
+        anyOf: [
+          { enum: ["human_idv", "business_kyb", "associated_person_idv", "ownership_review"] },
+          { pattern: "^[a-z0-9][a-z0-9-]{0,32}(?:\\.[a-z0-9][a-z0-9_-]{0,63}){1,6}$" }
+        ]
+      }
+    },
+    supportedCountries: { type: "array", minItems: 1, uniqueItems: true, items: { type: "string", pattern: "^[A-Z]{2}$" } },
+    environments: { type: "array", minItems: 1, uniqueItems: true, items: { enum: ["sandbox", "production"] } },
+    capabilities: {
+      type: "object",
+      additionalProperties: false,
+      required: ["presentations", "canResume", "canRetry", "canCancel", "canRedact"],
+      properties: {
+        presentations: { type: "array", minItems: 1, uniqueItems: true, items: { enum: ["embedded", "hosted", "qr", "none"] } },
+        canResume: { type: "boolean" },
+        canRetry: { type: "boolean" },
+        canCancel: { type: "boolean" },
+        canRedact: { type: "boolean" }
+      }
+    },
+    launcherKeys: { type: "array", minItems: 1, uniqueItems: true, items: { type: "string", pattern: "^[a-z][a-z0-9_]{1,63}$" } },
+    launchPresentations: { type: "array", minItems: 1, uniqueItems: true, items: { enum: ["embedded", "hosted", "qr", "none"] } },
+    configurationSchemaVersion: { type: "string", minLength: 1 },
+    configurationSchema: { $ref: "#/$defs/jsonSchema2020" },
+    webhook: {
+      type: "object",
+      additionalProperties: false,
+      required: ["protocol", "eventFamilies"],
+      properties: {
+        protocol: { type: "string", minLength: 1, maxLength: 128 },
+        eventFamilies: { type: "array", uniqueItems: true, items: { type: "string", minLength: 1 } },
+        toleranceSeconds: { type: "integer", minimum: 1 }
+      }
+    },
+    dataPolicy: {
+      type: "object",
+      additionalProperties: false,
+      required: [
+        "classifications",
+        "prohibitedPersistence",
+        "rawPayloadPersistence",
+        "browserSecretPersistence",
+        "governmentIdentifierPersistence"
+      ],
+      properties: {
+        classifications: { type: "array", uniqueItems: true, items: { type: "string", minLength: 1 } },
+        prohibitedPersistence: { type: "array", uniqueItems: true, items: { type: "string", minLength: 1 } },
+        rawPayloadPersistence: { const: false },
+        browserSecretPersistence: { const: false },
+        governmentIdentifierPersistence: { const: false }
+      }
+    },
+    retry: {
+      type: "object",
+      additionalProperties: false,
+      required: ["sameResourceWhenResumable", "newAttemptAfterTerminal"],
+      properties: {
+        sameResourceWhenResumable: { type: "boolean" },
+        newAttemptAfterTerminal: { type: "boolean" }
+      }
+    },
+    cancellation: {
+      type: "object",
+      additionalProperties: false,
+      required: ["supported", "terminal"],
+      properties: { supported: { type: "boolean" }, terminal: { type: "boolean" } }
+    },
+    redaction: {
+      type: "object",
+      additionalProperties: false,
+      required: ["supported", "asynchronous"],
+      properties: {
+        supported: { type: "boolean" },
+        asynchronous: { type: "boolean" },
+        notApplicable: { type: "boolean" }
+      }
+    },
+    apiHosts: {
+      type: "array",
+      minItems: 1,
+      uniqueItems: true,
+      items: { type: "string", pattern: "^[a-z0-9.-]+$" }
+    },
+    testedApiVersions: { type: "array", minItems: 1, uniqueItems: true, items: { type: "string", minLength: 1 } }
+  },
+  $defs: {
+    jsonSchema2020: {
+      type: "object",
+      required: ["$schema", "type", "additionalProperties", "required", "properties"],
+      properties: {
+        $schema: { const: "https://json-schema.org/draft/2020-12/schema" },
+        type: { const: "object" },
+        additionalProperties: { const: false },
+        required: { type: "array", uniqueItems: true, items: { type: "string", minLength: 1 } },
+        properties: { type: "object" }
+      }
+    }
+  }
+};
+
+// src/manifest.ts
+var manifestValidator = new _2020_js.Ajv2020({ allErrors: true, strict: false }).compile(providerManifestV1JsonSchema);
+var REQUIRED_ADAPTER_METHODS = [
+  "validateConfiguration",
+  "createAttempt",
+  "resumeAttempt",
+  "retrieveAttempt",
+  "retryAttempt",
+  "cancelAttempt",
+  "redactSubject",
+  "verifyWebhook",
+  "normalizeWebhook"
+];
+function assertProviderManifest(manifest) {
+  if (!manifestValidator(manifest)) {
+    const first = manifestValidator.errors?.[0];
+    invalid(
+      `json_schema_${toSafeCode(first?.keyword ?? "invalid")}`,
+      `The provider adapter manifest does not satisfy ProviderManifestV1 JSON Schema at ${first?.instancePath || "/"}.`
+    );
+  }
+  if (manifest.contractVersion !== VERIFICATION_ADAPTER_CONTRACT_VERSION) invalid("contract_version");
+  if (!isProviderCode(manifest.provider)) invalid("provider_code");
+  if (!manifest.displayName.trim() || !isSemver(manifest.adapterVersion) || !isSemver(manifest.engineCompatibility)) {
+    invalid("identity");
+  }
+  if (!majorsCompatible(manifest.adapterVersion, VERIFICATION_ADAPTER_CONTRACT_VERSION)) {
+    invalid("adapter_version_incompatible", "Provider adapter major version must be compatible with contract V1.");
+  }
+  if (!majorsCompatible(manifest.engineCompatibility, ENGINE_CONTRACT_VERSION)) {
+    invalid("engine_incompatible", "Provider adapter is not compatible with this engine major version.");
+  }
+  if (!manifest.supportedPackages.length || manifest.supportedPackages.some((value) => !isPackageCode(value))) {
+    invalid("supported_packages");
+  }
+  if (manifest.supportedPackages.some((value) => !isStandardPackageCode(value) && !isCustomPackageCode(value))) {
+    invalid("supported_packages");
+  }
+  if (!manifest.supportedCountries.length || manifest.supportedCountries.some((value) => !isCountryCode(value))) {
+    invalid("supported_countries");
+  }
+  if (!manifest.launcherKeys.length || manifest.launcherKeys.some((value) => !isLauncherKey(value))) {
+    invalid("launcher_keys");
+  }
+  if (!isWebhookProtocol(manifest.webhook.protocol)) invalid("webhook_protocol");
+  if (!manifest.apiHosts.length || manifest.apiHosts.some((host) => host.includes("/") || host.includes(":"))) {
+    invalid("api_hosts", "Provider API hosts must be code-owned hostnames, not URLs or caller-supplied origins.");
+  }
+  if (manifest.dataPolicy.rawPayloadPersistence !== false || manifest.dataPolicy.browserSecretPersistence !== false || manifest.dataPolicy.governmentIdentifierPersistence !== false) {
+    invalid("data_policy");
+  }
+  if (manifest.capabilities.canCancel !== manifest.cancellation.supported) invalid("cancellation_capability");
+  if (manifest.capabilities.canRedact !== manifest.redaction.supported) invalid("redaction_capability");
+  assertConfigurationSecrets(manifest);
+}
+function assertConfigurationSecrets(manifest) {
+  const properties = manifest.configurationSchema.properties ?? {};
+  for (const [name, schema] of Object.entries(properties)) {
+    if (schema["x-secret"] === true && schema.type !== "string") {
+      invalid("secret_schema", `Configuration field "${name}" marked x-secret must be a string.`);
+    }
+  }
+}
+function assertAdapterConformsToManifest(adapter) {
+  const candidate = adapter;
+  const provider = typeof candidate.provider === "string" && candidate.provider ? candidate.provider : "unknown";
+  for (const method of REQUIRED_ADAPTER_METHODS) {
+    if (typeof candidate[method] !== "function") {
+      invalid(
+        `missing_method_${toSafeCode(method)}`,
+        `Provider adapter "${provider}" is missing required method "${method}".`
+      );
+    }
+  }
+  if (!candidate.manifest || typeof candidate.manifest !== "object") {
+    invalid("missing_manifest", `Provider adapter "${provider}" is missing its manifest.`);
+  }
+  assertProviderManifest(adapter.manifest);
+  if (adapter.contractVersion !== VERIFICATION_ADAPTER_CONTRACT_VERSION || adapter.provider !== adapter.manifest.provider || !adapter.manifest.environments.includes(adapter.environment)) {
+    invalid("adapter_identity", `Provider adapter "${provider}" does not match its manifest identity or environment.`);
+  }
+  if (adapter.manifest.capabilities.canResume === false && typeof candidate.resumeAttempt !== "function") {
+    invalid("resume_capability");
+  }
+  adapter.validateConfiguration();
+}
+function invalid(safeCode, message = "The provider adapter manifest is invalid.") {
+  throw new ProviderError("INVALID_CONFIGURATION", message, { safeCode });
+}
+function toSafeCode(value) {
+  return value.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
+
+// src/conformance.ts
+var CANONICAL_STATUS_RANK = {
+  created: 10,
+  pending_user_input: 20,
+  paused: 20,
+  provider_unavailable: 25,
+  processing: 30,
+  manual_review_required: 40,
+  verified: 100,
+  declined: 100,
+  failed: 100,
+  expired: 100,
+  canceled: 100,
+  redacted: 200
+};
+function canonicalStatusRank(status) {
+  return CANONICAL_STATUS_RANK[status];
+}
+var providerConformanceScenarios = Object.freeze([
+  "success",
+  "input_required",
+  "processing",
+  "verified",
+  "decline",
+  "failure",
+  "manual_review",
+  "timeout",
+  "rate_limit",
+  "malformed_response",
+  "unknown_state",
+  "cancellation",
+  "resume",
+  "asynchronous_redaction",
+  "retryable_provider_failure"
+]);
+async function runAdapterConformance(adapter, command, options = {}) {
+  const results = [];
+  const manifest = capture("manifest", () => assertAdapterConformsToManifest(adapter));
+  results.push(manifest);
+  if (!manifest.passed) return results;
+  results.push(capture("package", () => {
+    if (!adapter.manifest.supportedPackages.includes(command.packageCode)) {
+      throw new Error("The fixture package is not declared by the adapter.");
+    }
+    if (metadataContainsForbiddenIdentifier(command.metadata) || !command.subjectReference) {
+      throw new Error("Attempt command contains forbidden identifiers or a missing opaque subject.");
+    }
+  }));
+  let created = null;
+  try {
+    created = await adapter.createAttempt(command);
+    assertAttemptResult(adapter, created);
+    results.push({ name: "create", passed: true });
+  } catch (error) {
+    results.push(failure("create", error));
+  }
+  if (created) {
+    try {
+      const duplicate = await adapter.createAttempt(command);
+      if (duplicate.providerResourceId !== created.providerResourceId) {
+        throw new Error("Duplicate create produced a second provider resource.");
+      }
+      results.push({ name: "create_idempotency", passed: true });
+    } catch (error) {
+      results.push(failure("create_idempotency", error));
+    }
+    if (adapter.manifest.capabilities.canResume) {
+      try {
+        const resumed = await adapter.resumeAttempt(resourceCommand(command, created.providerResourceId));
+        assertLaunchResult(adapter, resumed);
+        results.push({ name: "resume", passed: true });
+      } catch (error) {
+        results.push(failure("resume", error));
+      }
+    } else {
+      results.push(skipped("resume", "canResume"));
+    }
+    try {
+      const snapshot = await adapter.retrieveAttempt(resourceCommand(command, created.providerResourceId));
+      assertNormalizedSnapshot(snapshot);
+      results.push({ name: "retrieve", passed: true });
+      try {
+        if (isTerminalStatus(snapshot.canonicalStatus)) {
+          const second = await adapter.retrieveAttempt(resourceCommand(command, created.providerResourceId));
+          assertNormalizedSnapshot(second);
+          const firstRank = canonicalStatusRank(snapshot.canonicalStatus);
+          const secondRank = canonicalStatusRank(second.canonicalStatus);
+          if (!isTerminalStatus(second.canonicalStatus) && secondRank < firstRank) {
+            throw new Error("A terminal snapshot must not regress to a non-terminal status with lower rank.");
+          }
+        }
+        results.push({ name: "terminal_monotonicity", passed: true });
+      } catch (error) {
+        results.push(failure("terminal_monotonicity", error));
+      }
+    } catch (error) {
+      results.push(failure("retrieve", error));
+    }
+    if (adapter.manifest.capabilities.canRetry) {
+      try {
+        const retried = await adapter.retryAttempt({ ...command, previousProviderResourceId: created.providerResourceId });
+        assertAttemptResult(adapter, retried);
+        results.push({ name: "retry", passed: true });
+      } catch (error) {
+        results.push(failure("retry", error));
+      }
+    } else {
+      results.push(skipped("retry", "canRetry"));
+    }
+    if (adapter.manifest.capabilities.canCancel) {
+      try {
+        const canceled = await adapter.cancelAttempt(resourceCommand(command, created.providerResourceId));
+        if (!canceled.accepted) throw new Error("Adapter did not acknowledge cancellation.");
+        results.push({ name: "cancel", passed: true });
+      } catch (error) {
+        results.push(failure("cancel", error));
+      }
+    } else {
+      results.push(skipped("cancel", "canCancel"));
+    }
+    if (adapter.manifest.capabilities.canRedact) {
+      try {
+        const redaction = await adapter.redactSubject(redactionCommand(command, created.providerResourceId));
+        assertRedactionResult(redaction);
+        results.push({ name: "redact", passed: true });
+      } catch (error) {
+        results.push(failure("redact", error));
+      }
+    } else {
+      results.push(skipped("redact", "canRedact"));
+    }
+  }
+  if (options.webhookRequest) {
+    try {
+      const verified = await adapter.verifyWebhook(options.webhookRequest);
+      const normalized = await adapter.normalizeWebhook(verified);
+      if (!verified.providerEventKey || !verified.receivedAt || !verified.bodySha256 || !(verified.opaquePayload instanceof Uint8Array)) {
+        throw new Error("The verified webhook envelope is incomplete.");
+      }
+      if (!normalized.providerEventKey || !normalized.providerResourceId || !normalized.eventType || !normalized.providerEventType || !normalized.occurredAt) {
+        throw new Error("The normalized webhook event is incomplete.");
+      }
+      if (normalized.canonicalStatus) assertCanonicalStatus(normalized.canonicalStatus);
+      assertProviderTypesDoNotEscape(normalized);
+      results.push({ name: "webhook", passed: true });
+    } catch (error) {
+      results.push(failure("webhook", error));
+    }
+  }
+  return results;
+}
+async function runAdapterConformanceScenarios(adapterForScenario, command) {
+  const results = [];
+  for (const scenario of providerConformanceScenarios) {
+    try {
+      const adapter = await adapterForScenario(scenario);
+      assertAdapterConformsToManifest(adapter);
+      if (!adapter.manifest.supportedPackages.includes(command.packageCode)) {
+        throw new Error(`Scenario "${scenario}" uses a package that the adapter does not declare.`);
+      }
+      await executeScenario(adapter, command, scenario);
+      results.push({ name: scenario, passed: true });
+    } catch (error) {
+      results.push(failure(scenario, error));
+    }
+  }
+  return results;
+}
+function validateManifestOnly(manifest) {
+  return capture("manifest", () => assertProviderManifest(manifest));
+}
+function capture(name, operation) {
+  try {
+    operation();
+    return { name, passed: true };
+  } catch (error) {
+    return failure(name, error);
+  }
+}
+function failure(name, error) {
+  return { name, passed: false, detail: error instanceof Error ? error.message : "Unknown conformance failure." };
+}
+function skipped(name, capability) {
+  return { name, passed: true, detail: `Skipped because the manifest declares ${capability}=false.` };
+}
+async function executeScenario(adapter, command, scenario) {
+  const providerResourceId = `conformance_${command.attemptId.replace(/[^a-zA-Z0-9]/g, "")}`;
+  const resource = resourceCommand(command, providerResourceId);
+  switch (scenario) {
+    case "success":
+    case "verified": {
+      const created = await adapter.createAttempt(command);
+      assertAttemptResult(adapter, created);
+      const snapshot = await adapter.retrieveAttempt(resourceCommand(command, created.providerResourceId));
+      assertNormalizedSnapshot(snapshot);
+      if (snapshot.canonicalStatus !== "verified") {
+        throw new Error('The success scenario must normalize to canonical status "verified".');
+      }
+      return;
+    }
+    case "input_required":
+      await expectCanonicalSnapshot(adapter, resource, "pending_user_input");
+      return;
+    case "processing":
+      await expectCanonicalSnapshot(adapter, resource, "processing");
+      return;
+    case "decline":
+      await expectCanonicalSnapshot(adapter, resource, "declined");
+      return;
+    case "failure":
+      await expectCanonicalSnapshot(adapter, resource, "failed");
+      return;
+    case "manual_review":
+      await expectCanonicalSnapshot(adapter, resource, "manual_review_required");
+      return;
+    case "timeout":
+      await expectProviderError(() => adapter.retrieveAttempt(resource), "TIMEOUT", { retryable: true });
+      return;
+    case "rate_limit":
+      await expectProviderError(() => adapter.retrieveAttempt(resource), "RATE_LIMITED", { retryable: true, retryAfterRequired: true });
+      return;
+    case "retryable_provider_failure":
+      await expectProviderError(() => adapter.retrieveAttempt(resource), "RETRYABLE_PROVIDER_FAILURE", { retryable: true });
+      return;
+    case "malformed_response":
+      await expectRejectedSnapshot(adapter, resource, "malformed_provider_response");
+      return;
+    case "unknown_state":
+      await expectRejectedSnapshot(adapter, resource, "unknown_provider_status");
+      return;
+    case "cancellation": {
+      const canceled = await adapter.cancelAttempt(resource);
+      if (!canceled.accepted) throw new Error("Cancellation was not accepted.");
+      return;
+    }
+    case "resume": {
+      const launched = await adapter.resumeAttempt(resource);
+      assertLaunchResult(adapter, launched);
+      return;
+    }
+    case "asynchronous_redaction": {
+      if (!adapter.manifest.capabilities.canRedact) {
+        throw new Error('The redaction scenario requires manifest capability "canRedact".');
+      }
+      const redaction = await adapter.redactSubject(redactionCommand(command, providerResourceId));
+      assertRedactionResult(redaction);
+      if (adapter.manifest.redaction.asynchronous) {
+        if (redaction.completed && redaction.disposition !== "redacted") {
+          throw new Error("Asynchronous redaction must not claim completion until the provider finishes.");
+        }
+        if (!["processing", "scheduled", "retryable"].includes(redaction.disposition ?? "")) {
+          throw new Error("Asynchronous redaction must report processing, scheduled, or retryable.");
+        }
+      } else if (!redaction.completed || redaction.retryable) {
+        throw new Error("Synchronous redaction must complete terminally without retry.");
+      }
+    }
+  }
+}
+async function expectCanonicalSnapshot(adapter, command, expected) {
+  const snapshot = await adapter.retrieveAttempt(command);
+  assertNormalizedSnapshot(snapshot);
+  if (snapshot.canonicalStatus !== expected) {
+    throw new Error(`The scenario must normalize to canonical status "${expected}".`);
+  }
+}
+async function expectRejectedSnapshot(adapter, command, expectedSafeCode) {
+  try {
+    const snapshot = await adapter.retrieveAttempt(command);
+    assertNormalizedSnapshot(snapshot);
+  } catch (error) {
+    if (isProviderErrorLike(error) && error.safeCode === expectedSafeCode) return;
+    throw new Error(`The scenario must be rejected with safe code "${expectedSafeCode}"; received ${describeError(error)}.`);
+  }
+  throw new Error(`The scenario was accepted instead of being rejected as "${expectedSafeCode}".`);
+}
+async function expectProviderError(operation, code, expectations) {
+  try {
+    await operation();
+  } catch (error) {
+    if (!isProviderErrorLike(error)) {
+      throw new Error(`Expected ProviderError ${code}; received ${describeError(error)}.`);
+    }
+    if (error.code !== code) throw new Error(`Expected ProviderError ${code}; received ${error.code}.`);
+    if (error.retryable !== expectations.retryable) {
+      throw new Error(`ProviderError ${code} must set retryable=${String(expectations.retryable)}.`);
+    }
+    if (!error.safeCode.trim()) throw new Error(`ProviderError ${code} must provide a safe code.`);
+    if (expectations.retryAfterRequired && (!Number.isSafeInteger(error.retryAfterSeconds) || Number(error.retryAfterSeconds) <= 0)) {
+      throw new Error(`ProviderError ${code} must provide a positive integer retryAfterSeconds.`);
+    }
+    return;
+  }
+  throw new Error(`Expected ProviderError ${code}, but the adapter operation succeeded.`);
+}
+function assertAttemptResult(adapter, result) {
+  if (!result || typeof result !== "object" || !isNonEmptyString(result.providerResourceId) || !isNonEmptyString(result.providerStatus) || result.attemptId == null) {
+    malformed("The adapter returned an incomplete attempt result.");
+  }
+  assertLaunchResult(adapter, result.launch);
+  assertProviderTypesDoNotEscape(result);
+}
+function assertLaunchResult(adapter, launch) {
+  if (!launch || typeof launch !== "object" || !isNonEmptyString(launch.launcherKey) || !adapter.manifest.launcherKeys.includes(launch.launcherKey) || !adapter.manifest.capabilities.presentations.includes(launch.presentation) || !isCanonicalStatus(launch.canonicalStatus)) {
+    malformed("The adapter returned an invalid launch envelope.");
+  }
+  const forbidden = ["inquiryOrSessionId", "environmentId", "opaqueLaunchSecret", "adapter", "clientSecret"];
+  if (forbidden.some((key) => key in launch)) {
+    throw new Error("Deprecated or secret launch fields escaped the adapter boundary.");
+  }
+}
+function assertNormalizedSnapshot(snapshot) {
+  if (!snapshot || typeof snapshot !== "object" || !isNonEmptyString(snapshot.providerResourceId) || !isNonEmptyString(snapshot.providerStatus) || !isIsoTimestamp(snapshot.occurredAt) || !Array.isArray(snapshot.normalizedReasonCodes) || snapshot.normalizedReasonCodes.some((code) => !isNonEmptyString(code)) || !isSafeMetadata(snapshot.safeMetadata)) {
+    malformed("The adapter returned a malformed normalized snapshot.");
+  }
+  assertCanonicalStatus(snapshot.canonicalStatus);
+  assertProviderTypesDoNotEscape(snapshot);
+}
+function assertRedactionResult(result) {
+  if (!result || typeof result !== "object" || typeof result.completed !== "boolean" || typeof result.retryable !== "boolean") {
+    malformed("Adapter returned an invalid redaction result.");
+  }
+}
+function assertCanonicalStatus(value) {
+  if (!isCanonicalStatus(value)) {
+    throw new ProviderError("UNKNOWN_PROVIDER_STATE", "Adapter returned an unknown canonical status.", {
+      safeCode: "unknown_provider_status"
+    });
+  }
+}
+function assertProviderTypesDoNotEscape(value) {
+  const serialized = JSON.stringify(value, (_key, nested) => nested instanceof Uint8Array ? void 0 : nested);
+  if (/"(?:access_token|api_key|client_secret|document_number|raw_payload|ssn|template_id|verification_session|webhook_secret|inquiry_status|document_front|selfie)"/i.test(serialized)) {
+    throw new Error("Provider SDK or raw provider fields escaped the adapter boundary.");
+  }
+  if (metadataContainsForbiddenIdentifier(value)) {
+    throw new Error("Government identifiers escaped the adapter boundary.");
+  }
+}
+function resourceCommand(command, providerResourceId) {
+  return {
+    attemptId: command.attemptId,
+    providerResourceId,
+    configurationRevision: command.configurationRevision,
+    requestOrigin: command.requestOrigin
+  };
+}
+function redactionCommand(command, providerResourceId) {
+  return {
+    subjectReference: command.subjectReference,
+    providerResourceId,
+    requestReference: command.idempotencyKey
+  };
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function isIsoTimestamp(value) {
+  return isNonEmptyString(value) && !Number.isNaN(Date.parse(value));
+}
+function isSafeMetadata(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((entry) => entry === null || ["string", "boolean", "number"].includes(typeof entry));
+}
+function malformed(message) {
+  throw new ProviderError("RETRYABLE_PROVIDER_FAILURE", message, {
+    retryable: true,
+    safeCode: "malformed_provider_response"
+  });
+}
+function isProviderErrorLike(error) {
+  if (error instanceof ProviderError) return true;
+  if (!error || typeof error !== "object") return false;
+  const candidate = error;
+  return candidate.name === "ProviderError" && typeof candidate.code === "string" && typeof candidate.safeCode === "string" && typeof candidate.retryable === "boolean";
+}
+function describeError(error) {
+  return error instanceof Error ? `${error.name}: ${error.message}` : "a non-Error value";
+}
+
+exports.assertProviderTypesDoNotEscape = assertProviderTypesDoNotEscape;
+exports.canonicalStatusRank = canonicalStatusRank;
+exports.providerConformanceScenarios = providerConformanceScenarios;
+exports.runAdapterConformance = runAdapterConformance;
+exports.runAdapterConformanceScenarios = runAdapterConformanceScenarios;
+exports.validateManifestOnly = validateManifestOnly;
+//# sourceMappingURL=conformance.cjs.map
+//# sourceMappingURL=conformance.cjs.map