@splitin/verification-adapter-plaid-idv 0.1.0-beta.0

package/dist/index.js

@@ -0,0 +1,727 @@
+import { defineProviderManifest, VERIFICATION_ADAPTER_CONTRACT_VERSION, plainStringProperty, secretStringProperty, ProviderError, metadataContainsForbiddenIdentifier, isOpaqueSubjectReference, ProviderUnavailableError } from '@splitin/verification-adapter-sdk';
+import { decodeProtectedHeader, importJWK, jwtVerify } from 'jose';
+
+// src/adapter.ts
+function createPlaidIdvConfiguration(values, environment) {
+  const secret = environment === "production" ? values.secret ?? values.PLAID_PRODUCTION_SECRET ?? values.PLAID_SECRET : values.secret ?? values.PLAID_SANDBOX_SECRET ?? values.PLAID_SECRET;
+  const templateId = environment === "production" ? values.templateId ?? values.PLAID_IDV_TEMPLATE_ID ?? values.PLAID_TEMPLATE_ID : values.templateId ?? values.PLAID_SANDBOX_TEMPLATE_ID ?? values.PLAID_IDV_TEMPLATE_ID ?? values.PLAID_TEMPLATE_ID;
+  return Object.freeze({
+    clientId: values.clientId ?? values.PLAID_CLIENT_ID ?? "",
+    secret: secret ?? "",
+    templateId: templateId ?? "",
+    clientName: values.clientName ?? values.PLAID_CLIENT_NAME ?? "",
+    webhookUrl: values.webhookUrl ?? values.PLAID_IDV_WEBHOOK_URL
+  });
+}
+function validatePlaidIdvConfiguration(config) {
+  if (!config.clientId.trim() || !config.secret.trim() || !config.templateId.trim() || !config.clientName.trim()) {
+    throw new ProviderError("INVALID_CONFIGURATION", "Plaid Identity Verification is not configured.", {
+      safeCode: "plaid_idv_not_configured"
+    });
+  }
+  if (config.webhookUrl) {
+    let url;
+    try {
+      url = new URL(config.webhookUrl);
+    } catch {
+      throw new ProviderError("INVALID_CONFIGURATION", "Plaid webhook URL is invalid.", {
+        safeCode: "plaid_webhook_url_invalid"
+      });
+    }
+    if (url.protocol !== "https:" || url.username || url.password) {
+      throw new ProviderError("INVALID_CONFIGURATION", "Plaid webhook URL is invalid.", {
+        safeCode: "plaid_webhook_url_invalid"
+      });
+    }
+  }
+}
+
+// src/constants.ts
+var PLAID_SANDBOX_HOST = "sandbox.plaid.com";
+var PLAID_PRODUCTION_HOST = "production.plaid.com";
+var PLAID_HOSTED_HOST = "verify.plaid.com";
+var PLAID_API_VERSION = "2020-09-14";
+var PLAID_DISCLOSURE = "Powered by Plaid";
+var PLAID_NORMALIZATION_VERSION = "plaid-idv-v1";
+var PLAID_IDV_WEBHOOK_TYPE = "IDENTITY_VERIFICATION";
+var PLAID_IDV_WEBHOOK_CODES = /* @__PURE__ */ new Set(["STATUS_UPDATED", "STEP_UPDATED", "RETRIED"]);
+var plaidIdvProviderManifest = defineProviderManifest({
+  contractVersion: VERIFICATION_ADAPTER_CONTRACT_VERSION,
+  adapterVersion: "1.0.0",
+  engineCompatibility: "1.0.0",
+  provider: "plaid",
+  displayName: "Plaid Identity Verification",
+  description: "Plaid Identity Verification only. Auth, Identity (non-IDV), Monitor, and payments are out of scope. Redaction is not applicable; Plaid does not expose an IDV redaction API.",
+  supportedPackages: ["human_idv"],
+  supportedCountries: ["US"],
+  environments: ["sandbox", "production"],
+  capabilities: {
+    presentations: ["embedded", "hosted"],
+    canResume: true,
+    canRetry: true,
+    canCancel: false,
+    canRedact: false
+  },
+  launcherKeys: ["plaid_link", "hosted"],
+  launchPresentations: ["embedded", "hosted"],
+  configurationSchemaVersion: "urn:splitin:verification:config:plaid-idv:v1",
+  configurationSchema: {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    additionalProperties: false,
+    required: ["clientId", "secret", "templateId", "clientName"],
+    properties: {
+      clientId: secretStringProperty(),
+      secret: secretStringProperty(),
+      templateId: plainStringProperty(),
+      clientName: plainStringProperty(),
+      webhookUrl: { type: "string", format: "uri", "x-secret": false }
+    }
+  },
+  webhook: {
+    protocol: "plaid_es256_jwk",
+    eventFamilies: ["IDENTITY_VERIFICATION"],
+    toleranceSeconds: 300
+  },
+  dataPolicy: {
+    classifications: ["provider_resource_id", "normalized_status", "reason_codes"],
+    prohibitedPersistence: ["raw_webhook", "launch_secret", "document", "selfie", "link_token"],
+    rawPayloadPersistence: false,
+    browserSecretPersistence: false,
+    governmentIdentifierPersistence: false
+  },
+  retry: { sameResourceWhenResumable: true, newAttemptAfterTerminal: true },
+  cancellation: { supported: false, terminal: true },
+  redaction: { supported: false, asynchronous: false, notApplicable: true },
+  apiHosts: [PLAID_SANDBOX_HOST, PLAID_PRODUCTION_HOST],
+  testedApiVersions: [PLAID_API_VERSION]
+});
+
+// src/status.ts
+function normalizePlaidIdentityStatus(value) {
+  switch (String(value ?? "").trim().toLowerCase()) {
+    case "active":
+    case "pending":
+      return { status: "pending_user_input", reasonCodes: [] };
+    case "processing":
+      return { status: "processing", reasonCodes: [] };
+    case "success":
+    case "passed":
+      return { status: "verified", reasonCodes: [] };
+    case "pending_review":
+    case "review_needed":
+      return { status: "manual_review_required", reasonCodes: ["plaid_pending_review"] };
+    case "failed":
+      return { status: "failed", reasonCodes: ["plaid_verification_failed"] };
+    case "expired":
+      return { status: "expired", reasonCodes: ["plaid_attempt_expired"] };
+    case "canceled":
+    case "cancelled":
+      return { status: "canceled", reasonCodes: ["plaid_attempt_canceled"] };
+    default:
+      return { status: "manual_review_required", reasonCodes: ["plaid_status_ambiguous"] };
+  }
+}
+
+// src/webhook-crypto.ts
+function constantTimeEqual(left, right) {
+  const maxLength = Math.max(left.length, right.length);
+  let difference = left.length ^ right.length;
+  for (let index = 0; index < maxLength; index += 1) {
+    difference |= (left.charCodeAt(index) || 0) ^ (right.charCodeAt(index) || 0);
+  }
+  return difference === 0;
+}
+async function sha256Hex(crypto, value) {
+  const bytes = typeof value === "string" ? new TextEncoder().encode(value) : value;
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", Uint8Array.from(bytes)));
+  return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+// src/webhook-key-cache.ts
+var PlaidWebhookVerificationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "PlaidWebhookVerificationError";
+  }
+  code;
+};
+var PlaidVerificationKeyCache = class {
+  entries = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Map();
+  ttlMs;
+  now;
+  constructor(options = {}) {
+    this.ttlMs = Math.min(Math.max(options.ttlMs ?? 15 * 6e4, 1e4), 60 * 6e4);
+    this.now = options.now ?? Date.now;
+  }
+  async get(keyId, loader) {
+    assertKeyId(keyId);
+    const nowMs = this.now();
+    const cached = this.entries.get(keyId);
+    if (cached && nowMs - cached.fetchedAtMs < this.ttlMs && !isExpired(cached.key, nowMs)) {
+      validatePlaidJwk(cached.key, keyId, nowMs);
+      return cached.key;
+    }
+    this.entries.delete(keyId);
+    const existing = this.inFlight.get(keyId);
+    if (existing) return existing;
+    const pending = (async () => {
+      const key = await loader(keyId);
+      validatePlaidJwk(key, keyId, this.now());
+      this.entries.set(keyId, { key, fetchedAtMs: this.now() });
+      return key;
+    })();
+    this.inFlight.set(keyId, pending);
+    try {
+      return await pending;
+    } finally {
+      this.inFlight.delete(keyId);
+    }
+  }
+  clear(keyId) {
+    if (keyId) this.entries.delete(keyId);
+    else this.entries.clear();
+  }
+};
+function assertKeyId(keyId) {
+  if (!/^[A-Za-z0-9_-]{1,256}$/.test(keyId)) {
+    throw new PlaidWebhookVerificationError("INVALID_KEY_ID", "Webhook key ID is invalid");
+  }
+}
+function validatePlaidJwk(key, keyId, nowMs) {
+  if (!key || key.kid !== keyId || key.kty !== "EC" || key.crv !== "P-256" || key.alg !== "ES256" || key.use !== "sig" || typeof key.x !== "string" || typeof key.y !== "string" || !/^[A-Za-z0-9_-]{40,64}$/.test(key.x) || !/^[A-Za-z0-9_-]{40,64}$/.test(key.y)) {
+    throw new PlaidWebhookVerificationError("INVALID_KEY", "Webhook verification key is invalid");
+  }
+  const nowSeconds = Math.floor(nowMs / 1e3);
+  const createdAt = timestampSeconds(key.created_at);
+  if (createdAt === null || createdAt > nowSeconds + 60) {
+    throw new PlaidWebhookVerificationError("INVALID_KEY", "Webhook verification key creation time is invalid");
+  }
+  if (isExpired(key, nowMs)) {
+    throw new PlaidWebhookVerificationError("EXPIRED_KEY", "Webhook verification key is expired");
+  }
+}
+function isExpired(key, nowMs) {
+  if (key.expired_at == null) return false;
+  const expiry = timestampSeconds(key.expired_at);
+  return expiry === null || expiry <= Math.floor(nowMs / 1e3);
+}
+function timestampSeconds(value) {
+  if (typeof value === "number") return Number.isInteger(value) && value > 0 ? value : null;
+  if (typeof value !== "string" || !value) return null;
+  const numeric = Number(value);
+  if (Number.isInteger(numeric) && numeric > 0) return numeric;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? Math.floor(parsed / 1e3) : null;
+}
+async function verifyPlaidWebhook(options) {
+  try {
+    return await verifyPlaidWebhookInner(options);
+  } catch (error) {
+    if (error instanceof ProviderError) throw error;
+    const code = error instanceof PlaidWebhookVerificationError ? error.code : "INVALID_SIGNATURE";
+    const retryable = code === "KEY_FETCH_FAILED";
+    throw new ProviderError(
+      retryable ? "RETRYABLE_PROVIDER_FAILURE" : "SIGNATURE_INVALID",
+      "Plaid webhook signature is invalid.",
+      {
+        retryable,
+        safeCode: `plaid_webhook_${code.toLowerCase()}`,
+        cause: error
+      }
+    );
+  }
+}
+async function verifyPlaidWebhookInner(options) {
+  const token = options.verificationHeader?.trim();
+  if (!token) {
+    throw new PlaidWebhookVerificationError("MISSING_HEADER", "Missing Plaid-Verification header");
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3 || parts.some((part) => part.length === 0)) {
+    throw new PlaidWebhookVerificationError("MALFORMED_JWT", "Malformed webhook verification token");
+  }
+  let header;
+  try {
+    header = decodeProtectedHeader(token);
+  } catch {
+    throw new PlaidWebhookVerificationError("MALFORMED_JWT", "Malformed webhook verification token");
+  }
+  if (header.alg !== "ES256") {
+    throw new PlaidWebhookVerificationError("WRONG_ALGORITHM", "Webhook token must use ES256");
+  }
+  if (typeof header.kid !== "string" || !header.kid) {
+    throw new PlaidWebhookVerificationError("MISSING_KEY_ID", "Webhook token is missing its key ID");
+  }
+  assertKeyId(header.kid);
+  let jwk;
+  try {
+    jwk = await options.getKey(header.kid);
+  } catch (error) {
+    if (error instanceof PlaidWebhookVerificationError) throw error;
+    throw new PlaidWebhookVerificationError("KEY_FETCH_FAILED", "Unable to retrieve webhook verification key");
+  }
+  const nowMs = options.nowMs ?? Date.now();
+  validatePlaidJwk(jwk, header.kid, nowMs);
+  let payload;
+  try {
+    const key = await importJWK(jwk, "ES256");
+    const result = await jwtVerify(token, key, {
+      algorithms: ["ES256"],
+      currentDate: new Date(nowMs)
+    });
+    payload = result.payload;
+  } catch {
+    throw new PlaidWebhookVerificationError("INVALID_SIGNATURE", "Webhook signature is invalid");
+  }
+  if (!Number.isInteger(payload.iat)) {
+    throw new PlaidWebhookVerificationError("MISSING_ISSUED_AT", "Webhook token is missing a valid issued-at time");
+  }
+  const nowSeconds = Math.floor(nowMs / 1e3);
+  const maxAge = options.maxTokenAgeSeconds ?? 300;
+  const futureSkew = options.maxFutureSkewSeconds ?? 60;
+  if (nowSeconds - payload.iat > maxAge) {
+    throw new PlaidWebhookVerificationError("STALE_TOKEN", "Webhook token is older than five minutes");
+  }
+  if (payload.iat - nowSeconds > futureSkew) {
+    throw new PlaidWebhookVerificationError("FUTURE_TOKEN", "Webhook token issued-at time is in the future");
+  }
+  const claimedBodyHash = payload.request_body_sha256;
+  if (typeof claimedBodyHash !== "string" || !/^[a-f0-9]{64}$/i.test(claimedBodyHash)) {
+    throw new PlaidWebhookVerificationError("MISSING_BODY_HASH", "Webhook token is missing a valid body hash");
+  }
+  const bodySha256 = await sha256Hex(options.crypto, options.rawBody);
+  if (!constantTimeEqual(bodySha256.toLowerCase(), claimedBodyHash.toLowerCase())) {
+    throw new PlaidWebhookVerificationError("BODY_MISMATCH", "Webhook body does not match its signed digest");
+  }
+  return { bodySha256, issuedAt: payload.iat, keyId: header.kid };
+}
+
+// src/adapter.ts
+var PlaidIdvVerificationAdapter = class {
+  contractVersion = VERIFICATION_ADAPTER_CONTRACT_VERSION;
+  manifest = plaidIdvProviderManifest;
+  provider = "plaid";
+  environment;
+  runtime;
+  verificationKeyCache;
+  constructor(runtime) {
+    this.runtime = runtime;
+    this.environment = runtime.environment;
+    this.verificationKeyCache = new PlaidVerificationKeyCache({
+      now: () => this.runtime.now().getTime()
+    });
+    this.validateConfiguration();
+  }
+  validateConfiguration() {
+    validatePlaidIdvConfiguration(this.runtime.configuration);
+  }
+  async createAttempt(command) {
+    this.assertCommand(command);
+    this.requireIdempotencyKey("create", command.attemptId, command.idempotencyKey);
+    const identity = await this.call("create", "/identity_verification/create", {
+      client_user_id: command.subjectReference,
+      template_id: this.runtime.configuration.templateId,
+      is_shareable: true,
+      gave_consent: false,
+      is_idempotent: true
+    });
+    return this.toAttemptResult(command.attemptId, identity, "create");
+  }
+  async resumeAttempt(command) {
+    const identity = await this.getIdentity(command.providerResourceId, "resume");
+    this.assertSubject(identity.client_user_id);
+    return this.createLaunch(command.attemptId, identity, "resume");
+  }
+  async retrieveAttempt(command) {
+    return this.normalizeSnapshot(await this.getIdentity(command.providerResourceId, "retrieve"));
+  }
+  async retryAttempt(command) {
+    this.assertCommand(command);
+    this.requireIdempotencyKey("retry", command.attemptId, command.idempotencyKey);
+    if (!command.previousProviderResourceId) {
+      return this.createAttempt(command);
+    }
+    const previous = await this.getIdentity(command.previousProviderResourceId, "retry");
+    this.assertSubject(previous.client_user_id);
+    if (previous.client_user_id !== command.subjectReference) {
+      throw new ProviderError("TERMINAL_INPUT_FAILURE", "The prior Plaid attempt does not match this subject.", {
+        safeCode: "plaid_subject_mismatch"
+      });
+    }
+    const normalized = normalizePlaidIdentityStatus(previous.status);
+    if (normalized.status === "pending_user_input" || normalized.status === "created") {
+      return this.toAttemptResult(command.attemptId, previous, "retry");
+    }
+    if (normalized.status === "processing") {
+      throw new ProviderError("RETRYABLE_PROVIDER_FAILURE", "Plaid is still processing this attempt.", {
+        retryable: true,
+        retryAfterSeconds: 15,
+        safeCode: "plaid_attempt_processing"
+      });
+    }
+    if (normalized.status === "manual_review_required" || normalized.status === "verified") {
+      throw new ProviderError("TERMINAL_INPUT_FAILURE", "Plaid review state cannot be retried.", {
+        safeCode: normalized.status === "verified" ? "plaid_attempt_already_verified" : "plaid_manual_review_pending"
+      });
+    }
+    const identity = await this.call("retry", "/identity_verification/retry", {
+      client_user_id: command.subjectReference,
+      template_id: this.runtime.configuration.templateId,
+      strategy: "reset"
+    });
+    const result = await this.toAttemptResult(command.attemptId, identity, "retry");
+    result.linkedResources = [{
+      resourceType: "identity_verification",
+      resourceId: requiredProviderId(previous.id),
+      relationshipCode: "retried_from",
+      providerStatus: requiredStatus(previous.status),
+      occurredAt: safeDate(previous.created_at, this.runtime.now())
+    }];
+    return result;
+  }
+  async cancelAttempt(_command) {
+    throw new ProviderError("UNSUPPORTED_CAPABILITY", "Plaid Identity Verification does not expose a cancel API.", {
+      safeCode: "plaid_cancel_unsupported"
+    });
+  }
+  async redactSubject(_command) {
+    return { completed: true, retryable: false, disposition: "not_applicable" };
+  }
+  async verifyWebhook(request) {
+    const rawBody = new Uint8Array(await request.arrayBuffer());
+    if (rawBody.byteLength === 0 || rawBody.byteLength > 1048576) {
+      throw new ProviderError("SIGNATURE_INVALID", "Plaid webhook body size is invalid.", {
+        safeCode: "plaid_webhook_body_invalid"
+      });
+    }
+    const verified = await verifyPlaidWebhook({
+      rawBody,
+      verificationHeader: request.headers.get("Plaid-Verification"),
+      crypto: this.runtime.crypto,
+      nowMs: this.runtime.now().getTime(),
+      getKey: async (keyId) => this.verificationKeyCache.get(
+        keyId,
+        async (uncachedKeyId) => this.getVerificationKey(uncachedKeyId)
+      )
+    });
+    return {
+      providerEventKey: `plaid_${verified.bodySha256}`,
+      receivedAt: this.runtime.now().toISOString(),
+      bodySha256: verified.bodySha256,
+      signatureIssuedAt: new Date(verified.issuedAt * 1e3).toISOString(),
+      opaquePayload: rawBody
+    };
+  }
+  async normalizeWebhook(input) {
+    let webhook;
+    try {
+      webhook = JSON.parse(new TextDecoder().decode(input.opaquePayload));
+    } catch {
+      throw new ProviderError("TERMINAL_INPUT_FAILURE", "Plaid webhook JSON is invalid.", {
+        safeCode: "plaid_webhook_payload_invalid"
+      });
+    }
+    const webhookType = requiredText(webhook.webhook_type, "webhook_type");
+    const webhookCode = requiredText(webhook.webhook_code, "webhook_code");
+    if (webhookType !== PLAID_IDV_WEBHOOK_TYPE || !PLAID_IDV_WEBHOOK_CODES.has(webhookCode)) {
+      throw new ProviderError("TERMINAL_INPUT_FAILURE", "Plaid webhook is outside Identity Verification scope.", {
+        safeCode: "plaid_webhook_scope_denied"
+      });
+    }
+    const providerResourceId = requiredProviderId(webhook.identity_verification_id);
+    const webhookEnvironment = requiredText(webhook.environment, "environment");
+    if (webhookEnvironment !== this.environment) {
+      throw new ProviderError("TERMINAL_INPUT_FAILURE", "Plaid webhook environment does not match the configured adapter.", {
+        safeCode: "plaid_environment_mismatch"
+      });
+    }
+    const status = typeof webhook.status === "string" ? normalizePlaidIdentityStatus(webhook.status) : null;
+    const providerEventKey = `plaid_${await sha256Hex(this.runtime.crypto, [
+      this.environment,
+      webhookType,
+      webhookCode,
+      providerResourceId,
+      input.bodySha256
+    ].join(":"))}`;
+    return {
+      providerEventKey,
+      providerResourceId,
+      eventType: status ? `verification.provider_event.${status.status}` : "verification.provider_event.processing",
+      providerEventType: `${webhookType}.${webhookCode}`,
+      canonicalStatus: status?.status,
+      occurredAt: input.receivedAt,
+      normalizedReasonCodes: status?.reasonCodes ?? ["plaid_webhook_requires_reconciliation"],
+      safeMetadata: {
+        adapter_version: this.manifest.adapterVersion,
+        normalization_version: PLAID_NORMALIZATION_VERSION,
+        provider_event_category: webhookCode.toLowerCase(),
+        provider_environment: this.environment
+      }
+    };
+  }
+  assertCommand(command) {
+    if (command.packageCode !== "human_idv") {
+      throw new ProviderError("UNSUPPORTED_CAPABILITY", "Plaid Identity Verification does not support this package.", {
+        safeCode: "unsupported_package"
+      });
+    }
+    this.assertSubject(command.subjectReference);
+    if (metadataContainsForbiddenIdentifier(command.metadata)) {
+      throw new ProviderError("TERMINAL_INPUT_FAILURE", "Attempt metadata contains a forbidden identifier.", {
+        safeCode: "forbidden_identifier"
+      });
+    }
+  }
+  assertSubject(value) {
+    if (!isOpaqueSubjectReference(value)) {
+      throw new ProviderError("TERMINAL_INPUT_FAILURE", "The subject reference is not an opaque identifier.", {
+        safeCode: "subject_reference_invalid"
+      });
+    }
+  }
+  async getIdentity(providerResourceId, operation) {
+    return this.call(operation, "/identity_verification/get", {
+      identity_verification_id: requiredProviderId(providerResourceId)
+    });
+  }
+  async toAttemptResult(attemptId, identity, operation) {
+    const normalized = normalizePlaidIdentityStatus(identity.status);
+    return {
+      attemptId,
+      providerResourceId: requiredProviderId(identity.id),
+      providerStatus: requiredStatus(identity.status),
+      canonicalStatus: normalized.status,
+      launch: await this.createLaunch(attemptId, identity, operation)
+    };
+  }
+  normalizeSnapshot(identity) {
+    const normalized = normalizePlaidIdentityStatus(identity.status);
+    const unknownStatus = normalized.reasonCodes.includes("plaid_status_ambiguous");
+    if (unknownStatus) {
+      this.runtime.logger.error("verification_provider_status_unknown", {
+        provider: this.provider,
+        environment: this.environment,
+        safe_code: "PLAID_STATUS_UNRECOGNIZED"
+      });
+    }
+    return {
+      providerResourceId: requiredProviderId(identity.id),
+      providerStatus: requiredStatus(identity.status),
+      canonicalStatus: normalized.status,
+      occurredAt: safeDate(identity.completed_at ?? identity.created_at, this.runtime.now()),
+      normalizedReasonCodes: normalized.reasonCodes,
+      safeMetadata: {
+        source: "retrieve",
+        adapter_version: this.manifest.adapterVersion,
+        normalization_version: PLAID_NORMALIZATION_VERSION,
+        ...unknownStatus ? { unknown_reason: "provider_status_not_allowlisted" } : {}
+      }
+    };
+  }
+  async createLaunch(attemptId, identity, operation) {
+    this.assertSubject(identity.client_user_id);
+    const payload = {
+      user: { client_user_id: identity.client_user_id },
+      client_name: this.runtime.configuration.clientName,
+      products: ["identity_verification"],
+      country_codes: ["US"],
+      language: "en",
+      identity_verification: { template_id: this.runtime.configuration.templateId, gave_consent: false }
+    };
+    if (this.runtime.configuration.webhookUrl) payload.webhook = this.runtime.configuration.webhookUrl;
+    const result = await this.call(operation, "/link/token/create", payload);
+    if (typeof result.link_token !== "string" || result.link_token.length < 8) {
+      throw new ProviderUnavailableError("Plaid did not return launch material.", {
+        safeCode: "plaid_launch_material_missing"
+      });
+    }
+    const canonical = normalizePlaidIdentityStatus(identity.status).status;
+    const hostedUrl = safeHttpsUrl(identity.shareable_url, PLAID_HOSTED_HOST);
+    return {
+      attemptId,
+      canonicalStatus: canonical,
+      presentation: "embedded",
+      launcherKey: "plaid_link",
+      providerDisclosure: PLAID_DISCLOSURE,
+      transientSecret: result.link_token,
+      transientSecretExpiresAt: safeDate(result.expiration, new Date(this.runtime.now().getTime() + 30 * 6e4)),
+      hostedUrl,
+      hostedFallbackExpiresAt: hostedUrl ? safeDate(result.expiration, new Date(this.runtime.now().getTime() + 30 * 6e4)) : void 0,
+      continuationReference: requiredProviderId(identity.id)
+    };
+  }
+  async getVerificationKey(keyId) {
+    const response = await this.call(
+      "webhook_verify",
+      "/webhook_verification_key/get",
+      { key_id: keyId }
+    );
+    if (!response.key || response.key.kid !== keyId) {
+      throw new ProviderError("SIGNATURE_INVALID", "Plaid returned an unknown webhook key.", {
+        safeCode: "plaid_webhook_invalid_key"
+      });
+    }
+    return response.key;
+  }
+  async call(operation, endpoint, body) {
+    if (this.runtime.rateBudget) {
+      const budget = await this.runtime.rateBudget.acquire(operation);
+      if (!budget.allowed) {
+        throw new ProviderError("RATE_LIMITED", "Plaid rate budget is exhausted.", {
+          retryable: true,
+          retryAfterSeconds: budget.retryAfterSeconds,
+          safeCode: "plaid_rate_limited"
+        });
+      }
+    }
+    const startedAt = this.runtime.now().getTime();
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 1e4);
+    const host = this.environment === "production" ? PLAID_PRODUCTION_HOST : PLAID_SANDBOX_HOST;
+    try {
+      const response = await this.runtime.http.fetch(`https://${host}${endpoint}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "PLAID-CLIENT-ID": this.runtime.configuration.clientId,
+          "PLAID-SECRET": this.runtime.configuration.secret,
+          "Plaid-Version": PLAID_API_VERSION
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+        const code = response.status === 401 || response.status === 403 ? "AUTHENTICATION_FAILED" : response.status === 429 ? "RATE_LIMITED" : response.status === 408 || response.status === 504 ? "TIMEOUT" : response.status >= 500 ? "RETRYABLE_PROVIDER_FAILURE" : "TERMINAL_INPUT_FAILURE";
+        throw new ProviderError(code, "Plaid request failed.", {
+          retryable: response.status === 408 || response.status === 429 || response.status >= 500,
+          retryAfterSeconds: retryAfter,
+          safeCode: code === "AUTHENTICATION_FAILED" ? "plaid_authentication_failed" : code === "RATE_LIMITED" ? "plaid_rate_limited" : code === "TIMEOUT" ? "plaid_timeout" : code === "RETRYABLE_PROVIDER_FAILURE" ? "plaid_provider_failure" : "plaid_terminal_input_failure"
+        });
+      }
+      const result = await response.json().catch(() => {
+        throw new ProviderError("UNKNOWN_PROVIDER_STATE", "Plaid returned a malformed response.", {
+          safeCode: "malformed_provider_response"
+        });
+      });
+      const unknown = isRecordWithStringStatus(result) && normalizePlaidIdentityStatus(result.status).reasonCodes.includes("plaid_status_ambiguous");
+      await this.recordObservation(
+        operation,
+        unknown ? "unknown_status" : "success",
+        unknown ? "plaid_unknown_status" : `plaid_${operation}_ok`,
+        startedAt
+      );
+      return result;
+    } catch (error) {
+      const failure = error instanceof ProviderError ? error : error instanceof DOMException && error.name === "AbortError" ? new ProviderError("TIMEOUT", "Plaid request timed out.", {
+        retryable: true,
+        safeCode: "plaid_timeout"
+      }) : new ProviderError("RETRYABLE_PROVIDER_FAILURE", "Plaid Identity Verification is temporarily unavailable.", {
+        retryable: true,
+        safeCode: "plaid_provider_failure",
+        cause: error
+      });
+      await this.recordObservation(
+        operation,
+        failure.retryable ? "retryable_failure" : "terminal_failure",
+        failure.safeCode,
+        startedAt
+      );
+      throw failure;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  requireIdempotencyKey(operation, attemptId, suppliedKey) {
+    const key = this.runtime.idempotency.keyFor(operation, attemptId, suppliedKey);
+    if (!key || key.length > 255) {
+      throw new ProviderError("INVALID_CONFIGURATION", "Plaid idempotency configuration is invalid.", {
+        safeCode: "plaid_idempotency_invalid"
+      });
+    }
+    return key;
+  }
+  async recordObservation(operation, outcome, safeCode, startedAt) {
+    const observedAt = this.runtime.now();
+    const latencyMs = Math.max(0, observedAt.getTime() - startedAt);
+    const metadata = {
+      provider: this.provider,
+      environment: this.environment,
+      operation,
+      outcome,
+      safe_code: safeCode,
+      latency_ms: latencyMs
+    };
+    try {
+      await this.runtime.recordHealth({
+        operation,
+        outcome,
+        safeCode,
+        observedAt: observedAt.toISOString(),
+        latencyMs
+      });
+      if (outcome === "success") this.runtime.logger.info("verification_provider_operation", metadata);
+      else this.runtime.logger.warn("verification_provider_operation", metadata);
+    } catch {
+      this.runtime.logger.warn("verification_provider_health_record_failed", {
+        provider: this.provider,
+        environment: this.environment,
+        operation
+      });
+    }
+  }
+};
+function requiredProviderId(value) {
+  if (typeof value !== "string" || !/^[A-Za-z0-9_.:-]{3,256}$/.test(value)) {
+    throw new ProviderError("UNKNOWN_PROVIDER_STATE", "Plaid resource identifier is invalid.", {
+      safeCode: "malformed_provider_response"
+    });
+  }
+  return value;
+}
+function requiredStatus(value) {
+  if (typeof value !== "string" || value.length < 1 || value.length > 128) {
+    throw new ProviderError("UNKNOWN_PROVIDER_STATE", "Plaid status is invalid.", {
+      safeCode: "malformed_provider_response"
+    });
+  }
+  return value;
+}
+function requiredText(value, field) {
+  if (typeof value !== "string" || value.length < 1 || value.length > 128) {
+    throw new ProviderError("TERMINAL_INPUT_FAILURE", `Plaid ${field} is invalid.`, {
+      safeCode: "plaid_webhook_payload_invalid"
+    });
+  }
+  return value;
+}
+function safeDate(value, fallback) {
+  if (typeof value === "string") {
+    const parsed = Date.parse(value);
+    if (Number.isFinite(parsed)) return new Date(parsed).toISOString();
+  }
+  return fallback.toISOString();
+}
+function safeHttpsUrl(value, hostedHost) {
+  if (typeof value !== "string") return void 0;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && url.hostname === hostedHost && !url.username && !url.password ? url.toString() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function parseRetryAfter(value) {
+  if (!value || !/^\d{1,6}$/.test(value)) return void 0;
+  return Math.min(Number(value), 3600);
+}
+function isRecordWithStringStatus(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value) && typeof value.status === "string";
+}
+
+export { PlaidIdvVerificationAdapter, PlaidVerificationKeyCache, createPlaidIdvConfiguration, normalizePlaidIdentityStatus, plaidIdvProviderManifest, verifyPlaidWebhook };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map