@openlup/platform 0.20.0 → 0.21.0

package/src/payments/stripe/index.ts

@@ -0,0 +1,235 @@
+import { createHash } from "node:crypto";
+import { classifyPaymentFailure, isPaymentRetryAdviceCode, type PaymentMethodLifecycleEvent } from "@openlup/core/payment";
+import type {
+  PaymentAdapter, PaymentAdapterCapabilities, PaymentAttemptPort, PaymentReadbackEnvelope,
+  PaymentReadbackPort, PaymentRefusalEnvelope, PaymentVerifyNormalizePort, TransientSecret,
+  VerifiedMethodEvidence, VerifiedPaymentEvidence,
+} from "../contracts/index.js";
+import { createStripeSandboxPaymentExecutionAdapter, type StripeSandboxClient } from "./stripeSandboxPaymentExecutionAdapter.js";
+import { createStripePaymentReconciliationProvider, type StripePaymentIntentReader } from "./stripePaymentReconciliationProvider.js";
+import { normalizeStripeWebhookEvent } from "./stripeWebhookNormalizer.js";
+import { verifyStripeSignature } from "./webhookSignature.js";
+import { declineCodeHints } from "./declineFailureHints.js";
+import type { PaymentExecutionResult } from "./donorContracts.js";
+
+/** Host-owned client, credentials, SDK construction and mode policy. clock returns UTC seconds. */
+export interface StripePaymentAdapterConfig {
+  client: Omit<StripeSandboxClient, "createSetupIntent"> & Partial<Pick<StripeSandboxClient, "createSetupIntent">> & StripePaymentIntentReader;
+  webhookSigningSecrets: readonly string[];
+  mode: "live" | "test";
+  supportedCurrencies: readonly string[];
+  toleranceSeconds?: number;
+  clock?: () => number;
+}
+
+/** Observed protocol capabilities; account activation remains host-owned. */
+export const stripePaymentCapabilities: Readonly<PaymentAdapterCapabilities> = Object.freeze<PaymentAdapterCapabilities>({
+  providerKind: "stripe",
+  captureFlows: Object.freeze([Object.freeze({ kind: "card_payment", handoff: "client-confirmed", methodFamilies: Object.freeze(["card", "wallet"] as const) })]),
+  requiresStoredMandateEvidence: false,
+  assessMandate: () => ({ chargeable: true }),
+  unattendedChargeFlow: "off_session_payment",
+  payerContext: Object.freeze({ requiresPayerBlock: false, customerRefFallsBackToContactEmail: false }),
+  methodHealth: Object.freeze({ requiresCustomerRef: true, requiredMethodKind: null, requiresPayerContact: false }),
+  terminalOutcomeReporting: Object.freeze({ kind: "status_field", silenceBecomesSuspectAfterMinutes: 360 }),
+  mandateUpsertIsSubscriptionScoped: false,
+  /** declared by the host through the adapter config */
+  supportedCurrencies: Object.freeze([]),
+  unattended: "supported", readback: "supported", close: "unsupported", exactAbsence: "unsupported",
+  refundObservation: "supported", refundCreate: "unsupported", authorizationCaptureSplit: "unsupported",
+});
+
+type VerificationResult = Awaited<ReturnType<PaymentVerifyNormalizePort["verifyAndNormalize"]>>;
+const refusal = (reason: Extract<VerificationResult, { kind: "refusal" }>["reason"]): VerificationResult => ({ kind: "refusal", reason });
+
+/** Explicit construction is the only activation point; importing performs no I/O. */
+export function createStripePaymentAdapter(config: StripePaymentAdapterConfig): PaymentAdapter {
+  if (config.mode !== "live" && config.mode !== "test") throw new Error("Invalid payment mode");
+  const declaredCurrencies = config.supportedCurrencies;
+  if (!Array.isArray(declaredCurrencies) || declaredCurrencies.length === 0
+    || ![...declaredCurrencies].every(currency => typeof currency === "string" && currency.length === 3 && /^[A-Z]{3}$/u.test(currency))) {
+    throw new Error("Invalid supported currencies");
+  }
+  const supportedCurrencies = Object.freeze([...declaredCurrencies]);
+  const tolerance = config.toleranceSeconds ?? 300;
+  if (!Number.isFinite(tolerance) || tolerance < 0) throw new Error("Invalid signature tolerance");
+  const secrets = [...config.webhookSigningSecrets];
+  const now = config.clock ?? (() => Math.floor(Date.now() / 1000));
+  const execution = createStripeSandboxPaymentExecutionAdapter({ client: {
+    createPaymentIntent: config.client.createPaymentIntent.bind(config.client),
+    createSetupIntent: inputSetup,
+    ensureCustomer: config.client.ensureCustomer?.bind(config.client),
+  } });
+  function inputSetup(...args: Parameters<StripeSandboxClient["createSetupIntent"]>) {
+    if (!config.client.createSetupIntent) throw new Error("Method setup unsupported by injected client");
+    return config.client.createSetupIntent(...args);
+  }
+  const reader = createStripePaymentReconciliationProvider(config.client);
+  const validateInput: PaymentAttemptPort["validateInput"] = input => {
+    if (input.mode !== config.mode || !["initial", "recovery", "renewal-unattended"].includes(input.purpose)
+      || !input.attemptRef || !input.intentRef || !input.fingerprint || !input.providerIdempotencyKey
+      || !Number.isSafeInteger(input.money.amountMinor) || input.money.amountMinor <= 0
+      || !supportedCurrencies.includes(input.money.currency)
+      || input.customerAuthorization !== undefined
+      || (input.purpose === "renewal-unattended" && !input.storedMethod?.reference)) {
+      throw new Error("Unsupported payment input");
+    }
+  };
+  const read: PaymentReadbackPort["readPayment"] = async input => {
+    const base = { identity: input.identity, expectedMoney: input.expectedMoney, purpose: input.purpose };
+    if (input.identity.provider !== "stripe" || !input.identity.providerPaymentRef) return { ...base, kind: "unsupported" };
+    try {
+      // Bind the response to the requested remote object before translating status.
+      const intent = await config.client.retrievePaymentIntent(input.identity.providerPaymentRef);
+      if (intent.id !== input.identity.providerPaymentRef || intent.amount !== input.expectedMoney.amountMinor
+        || intent.currency?.toUpperCase() !== input.expectedMoney.currency.toUpperCase()) {
+        return { ...base, kind: "unknown", reason: "indeterminate" };
+      }
+      const status = await createStripePaymentReconciliationProvider({ retrievePaymentIntent: async () => intent })
+        .readPayment({ providerPaymentId: input.identity.providerPaymentRef, purpose: input.purpose });
+      return readback(base, status);
+    } catch { return { ...base, kind: "unknown", reason: "indeterminate" }; }
+  };
+  return {
+    capabilities: { ...stripePaymentCapabilities, supportedCurrencies, close: config.client.cancelPaymentIntent ? "supported" : "unsupported" },
+    attemptPort: {
+      validateInput,
+      async execute(input) {
+        validateInput(input);
+        const result = await execution.execute({
+          idempotencyKey: input.attemptRef, providerIdempotencyKey: input.providerIdempotencyKey,
+          providerRequestFingerprint: input.fingerprint, paymentIntentId: input.intentRef,
+          amountMinor: input.money.amountMinor, currency: input.money.currency,
+          mode: input.purpose === "renewal-unattended" ? "subscription_cycle" : "one_time",
+          orderRef: input.intentRef,
+          providerFlow: input.purpose === "renewal-unattended" ? "off_session_payment" : "one_time_payment",
+          paymentMethodRef: input.storedMethod?.reference,
+        });
+        return {
+          outcome: result.providerDecline
+            ? { kind: "decline", refusal: neutralDecline(result.providerDecline) }
+            : { kind: "attempt", status: result.attemptStatus },
+          // A synchronous issuer decline is not proof of a pre-dispatch refusal.
+          dispatch: result.providerAttemptId ? { kind: "dispatched", providerPaymentRef: result.providerAttemptId } : { kind: "unknown" },
+          ...(result.clientSecret ? { handoff: { kind: "client-confirmed", payload: result.clientSecret as TransientSecret } as const } : {}),
+          diagnostics: { webhookExpected: result.webhookExpected === true, recoveryRequired: result.recoveryRequired === true },
+        };
+      },
+    },
+    verifyPort: {
+      async verifyAndNormalize(input) {
+        const header = Object.entries(input.headers).find(([key]) => key.toLowerCase() === "stripe-signature")?.[1];
+        if (typeof header !== "string") return refusal("signature");
+        const parts = Object.fromEntries(header.split(",").map(part => part.split("=")).filter(([key, value]) => key && value));
+        const timestamp = Number(parts.t);
+        const current = now();
+        if (!parts.t || !parts.v1 || !Number.isFinite(timestamp) || !Number.isFinite(current)) return refusal("signature");
+        // The preserved verifier supplies HMAC and comparison; this layer owns configurable freshness.
+        if (Math.abs(current - timestamp) > tolerance) return refusal("stale");
+        const rawBody = Buffer.from(input.rawBody).toString("utf8");
+        if (!Buffer.from(rawBody).equals(Buffer.from(input.rawBody))) return refusal("malformed");
+        if (!verifyStripeSignature({ rawBody, signatureHeader: header, endpointSecret: secrets, now: () => timestamp })) return refusal("signature");
+        try {
+          const raw: unknown = JSON.parse(rawBody);
+          if (!raw || typeof raw !== "object" || Array.isArray(raw)) return refusal("malformed");
+          const event = raw as Record<string, unknown>;
+          if (typeof event.livemode === "boolean" && event.livemode !== (config.mode === "live")) return refusal("unsupported-event");
+          return mapVerifiedStripeEvent(event);
+        } catch { return refusal("malformed"); }
+      },
+    },
+    readbackPort: {
+      readPayment: read,
+      ...(reader.closePayment ? { close: async (input: Parameters<PaymentReadbackPort["readPayment"]>[0]): Promise<PaymentReadbackEnvelope> => {
+        const base = { identity: input.identity, expectedMoney: input.expectedMoney, purpose: input.purpose };
+        if (input.identity.provider !== "stripe" || !input.identity.providerPaymentRef) return { ...base, kind: "unsupported" };
+        try {
+          // Check configured money and object identity before a destructive provider operation.
+          const before = await read(input);
+          if (before.kind === "unknown" || before.kind === "unsupported") return before;
+          await reader.closePayment!({ providerPaymentId: input.identity.providerPaymentRef });
+          return read(input);
+        } catch { return { ...base, kind: "unknown", reason: "indeterminate" }; }
+      } } : {}),
+    },
+  };
+}
+
+function neutralDecline(decline: NonNullable<PaymentExecutionResult["providerDecline"]>): PaymentRefusalEnvelope {
+  const hints = decline.neutralReasonHints ?? [];
+  const classified = classifyPaymentFailure({ adviceCode: decline.adviceCode, neutralReasonHints: hints });
+  return { code: classified.failureClass, hints,
+    ...(decline.adviceCode && isPaymentRetryAdviceCode(decline.adviceCode) ? { adviceCode: decline.adviceCode } : {}) };
+}
+
+function readback(base: Pick<PaymentReadbackEnvelope, "identity" | "expectedMoney" | "purpose">,
+  status: Awaited<ReturnType<ReturnType<typeof createStripePaymentReconciliationProvider>["readPayment"]>>): PaymentReadbackEnvelope {
+  if (status.status === "unknown" || status.amountMinor === null || !Number.isSafeInteger(status.amountMinor) || !status.currency) {
+    return { ...base, kind: "unknown", reason: "indeterminate" };
+  }
+  return { ...base, kind: status.status, observedMoney: { amountMinor: status.amountMinor, currency: status.currency }, providerOccurredAt: status.occurredAt };
+}
+
+/** Preserve donor money classifications in the neutral evidence union. */
+function mapStripeOutcome(eventType: string): VerifiedPaymentEvidence["outcome"] | null {
+  switch (eventType) {
+    case "payment.succeeded": return "succeeded";
+    case "payment.failed": return "failed";
+    case "payment.refunded": return "refunded";
+    case "payment.requires_action": return "pending";
+    case "payment.disputed": return "disputed";
+    default: return null;
+  }
+}
+
+function mapVerifiedStripeEvent(raw: Record<string, unknown>): VerificationResult {
+  let normalized: ReturnType<typeof normalizeStripeWebhookEvent>;
+  try { normalized = normalizeStripeWebhookEvent(raw); }
+  catch (error) {
+    return refusal(error instanceof Error && error.message.startsWith("Unsupported Stripe webhook event:") ? "unsupported-event" : "malformed");
+  }
+  const object = (raw.data as { object: Record<string, unknown> }).object;
+  const occurred = typeof raw.created === "number" && Number.isFinite(raw.created)
+    ? normalized.occurredAt : typeof raw.created === "string" && Number.isFinite(Date.parse(raw.created)) ? normalized.occurredAt : null;
+  const metadata = object.metadata && typeof object.metadata === "object" ? object.metadata as Record<string, unknown> : {};
+  const intentRef = typeof metadata.paymentIntentId === "string" ? metadata.paymentIntentId : null;
+  const identity = { provider: "stripe", providerEventId: normalized.providerEventId,
+    providerOccurredAt: occurred };
+  let result: Omit<VerifiedMethodEvidence, "fingerprint"> | Omit<VerifiedPaymentEvidence, "fingerprint">;
+  if (normalized.methodLifecycle || normalized.eventType.startsWith("setup.")) {
+    const lifecycle: PaymentMethodLifecycleEvent | null | undefined = normalized.methodLifecycle;
+    const method = lifecycle?.providerMethodRef ?? (typeof object.payment_method === "string" ? object.payment_method
+      : object.payment_method && typeof object.payment_method === "object" ? (object.payment_method as { id?: unknown }).id : null);
+    if (typeof method !== "string" || !method) return refusal("unsupported-event");
+    const outcomes: Record<string, VerifiedMethodEvidence["outcome"]> = {
+      method_registered: "registered", method_updated: "updated", method_revoked: "revoked", method_expired: "expired", method_suspended: "suspended",
+      "setup.succeeded": "registered", "setup.failed": "failed", "setup.requires_action": "requires-action",
+    };
+    const outcome = outcomes[lifecycle?.kind ?? normalized.eventType];
+    if (!outcome) return refusal("unsupported-event");
+    result = { ...identity, kind: "method", outcome, methodRef: method,
+      setupRef: typeof raw.type === "string" && raw.type.startsWith("setup_intent.") ? normalized.providerPaymentId : null, intentRef,
+      // Missing provider time must not turn the donor's epoch fallback into a lifecycle fact.
+      ...(lifecycle && occurred !== null ? { methodLifecycle: lifecycle } : {}) };
+  } else {
+    const outcome = mapStripeOutcome(normalized.eventType);
+    if (!outcome) return refusal("unsupported-event");
+    const money = Number.isSafeInteger(normalized.amountMinor) && normalized.amountMinor! > 0 && normalized.currency
+      ? { amountMinor: normalized.amountMinor!, currency: normalized.currency } : null;
+    const snapshot = normalized.rawPayload.stripeRefundSnapshot as { chargeId: string; amountRefundedMinor: number } | undefined;
+    if (outcome === "refunded" && (!snapshot || !money)) return refusal("malformed");
+    result = { ...identity, kind: "money", providerPaymentRef: normalized.providerPaymentId, intentRef, attemptRef: null, outcome, money,
+      ...(snapshot && money ? { refund: { kind: "cumulative-snapshot" as const, operationId: snapshot.chargeId,
+        originalPaymentMoney: money, refundedMoney: { amountMinor: snapshot.amountRefundedMinor, currency: money.currency } } } : {}),
+      ...(outcome === "failed" && object.last_payment_error && typeof object.last_payment_error === "object"
+        ? { refusal: neutralDecline({ code: "provider_declined", mandateUnsupported: false,
+          neutralReasonHints: declineCodeHints((object.last_payment_error as { decline_code?: string }).decline_code),
+          adviceCode: typeof (object.last_payment_error as { advice_code?: unknown }).advice_code === "string"
+            ? (object.last_payment_error as { advice_code: string }).advice_code : undefined }) } : {}),
+    };
+  }
+  // The donor normalizer constructs this filtered carrier, never the raw body.
+  // Keep its reader dialect and provenance outside normalized event identity.
+  return { ...result, fingerprint: createHash("sha256").update(JSON.stringify(result)).digest("hex"),
+    providerAuditPayload: normalized.rawPayload };
+}

package/src/payments/stripe/intentMapper.ts

@@ -0,0 +1,58 @@
+import { stripeFailureEvidence, type StripeIntentLike } from "./stripeFailureEvidence.js";
+type Reference = string | { id: string } | null;
+interface StripeIntentShape {
+ id: string; status: string; customer?: Reference; payment_method?: Reference; latest_charge?: Reference;
+ client_secret?: string | null; next_action?: { type?: string | null } | null;
+ amount?: number; amount_received?: number; currency?: string;
+ last_payment_error?: { code?: string | null; message?: string | null; type?: string | null } | null;
+}
+export function mapStripeIntent(intent: StripeIntentShape, knownCardOnlyRequest = false, source: "execution" | "readback" = "readback"): StripeIntentLike {
+  const customer = typeof intent.customer === "string" ? intent.customer : intent.customer?.id ?? null;
+  const paymentMethod =
+    typeof intent.payment_method === "string"
+      ? intent.payment_method
+      : intent.payment_method?.id ?? null;
+  const latestCharge =
+    typeof intent.latest_charge === "string"
+      ? intent.latest_charge
+      : intent.latest_charge?.id ?? null;
+  const mapped: StripeIntentLike = {
+    id: intent.id,
+    status: intent.status,
+    client_secret: intent.client_secret,
+    customer,
+    payment_method: paymentMethod,
+    latest_charge: latestCharge,
+    next_action: intent.next_action ? { type: intent.next_action.type ?? null } : null,
+  };
+  if (typeof intent.amount === "number") mapped.amount = intent.amount;
+  if (typeof intent.amount_received === "number") mapped.amount_received = intent.amount_received;
+  if (typeof intent.currency === "string") mapped.currency = intent.currency;
+  if (intent.last_payment_error) {
+    mapped.last_payment_error = {
+      code: intent.last_payment_error.code ?? null,
+      message: intent.last_payment_error.message ?? null,
+      type: intent.last_payment_error.type ?? null,
+    };
+  }
+  const evidence = stripeFailureEvidence(intent, { source, knownCardOnlyRequest });
+  if (evidence) mapped.diagnosticFailureEvidence = evidence;
+  return mapped;
+}
+
+export function mapSetupIntent(intent: StripeIntentShape): StripeIntentLike {
+  const customer = typeof intent.customer === "string" ? intent.customer : intent.customer?.id ?? null;
+  const paymentMethod =
+    typeof intent.payment_method === "string"
+      ? intent.payment_method
+      : intent.payment_method?.id ?? null;
+  return {
+    id: intent.id,
+    status: intent.status,
+    client_secret: intent.client_secret,
+    customer,
+    payment_method: paymentMethod,
+    latest_charge: null,
+    next_action: intent.next_action ? { type: intent.next_action.type ?? null } : null,
+  };
+}

package/src/payments/stripe/methodFacts.ts

@@ -0,0 +1,21 @@
+import type { PaymentMethodReplacementFacts } from "@openlup/core/payment";
+import type { NormalizedProviderPaymentWebhook } from "./donorContracts.js";
+import type { PaymentMethodLifecycleEvent } from "@openlup/core/payment";
+export interface ProviderWebhookWithMethodLifecycle extends NormalizedProviderPaymentWebhook {
+  methodLifecycle?: PaymentMethodLifecycleEvent | null;
+}
+export const METHOD_SCHEME_SNAPSHOT_KEY = "methodScheme";
+export const METHOD_LAST_DIGITS_SNAPSHOT_KEY = "methodLastDigits";
+export const METHOD_EXPIRES_AT_SNAPSHOT_KEY = "methodExpiresAt";
+
+export function methodFactSnapshotKeys(
+  facts: PaymentMethodReplacementFacts | null | undefined,
+): Record<string, unknown> {
+  if (!facts) return {};
+  return {
+    ...(facts.schemeLabel ? { [METHOD_SCHEME_SNAPSHOT_KEY]: facts.schemeLabel } : {}),
+    ...(facts.lastDigits ? { [METHOD_LAST_DIGITS_SNAPSHOT_KEY]: facts.lastDigits } : {}),
+    ...(facts.expiresAt ? { [METHOD_EXPIRES_AT_SNAPSHOT_KEY]: facts.expiresAt } : {}),
+  };
+}
+

package/src/payments/stripe/paymentFailureEvidence.ts

@@ -0,0 +1,58 @@
+import type { PaymentRecoveryMethod, PaymentRecoveryOperation } from "@openlup/core/payment";
+
+export type FailureObservationSource = "execution" | "webhook" | "readback";
+export type FailureObservationDisposition = "present" | "absent" | "unreadable" | "read_failed" | "read_timeout";
+
+/** Protected provider facts, not a customer message or a retry-policy input. */
+export interface PaymentFailureEvidence {
+  version: 1;
+  source: FailureObservationSource;
+  disposition: FailureObservationDisposition;
+  refusalVerified: boolean;
+  providerPaymentId: string | null;
+  providerChargeId: string | null;
+  code: string | null;
+  declineCode: string | null;
+  adviceCode: string | null;
+  adviceOrigin: "provider" | "inferred" | "unknown";
+  operation: PaymentRecoveryOperation | null;
+  method: PaymentRecoveryMethod | null;
+  methodSource: "provider" | "execution_contract" | "unknown";
+}
+
+/** Bounded machine tokens only. Free-form response fields never cross this seam. */
+export function evidenceToken(value: unknown): string | null {
+  return typeof value === "string" && /^[a-zA-Z0-9_:.-]{1,96}$/.test(value) ? value : null;
+}
+
+export function evidenceRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown> : {};
+}
+
+/** Explicit construction prevents accidental payload expansion by object spreading. */
+export function serializeFailureEvidence(input: PaymentFailureEvidence): PaymentFailureEvidence {
+  const method = input.method;
+  const kind = evidenceToken(method?.kind);
+  const recoveryMethodKey = evidenceToken(method?.recoveryMethodKey);
+  return {
+    version: 1,
+    source: input.source,
+    disposition: input.disposition,
+    refusalVerified: input.refusalVerified,
+    providerPaymentId: evidenceToken(input.providerPaymentId),
+    providerChargeId: evidenceToken(input.providerChargeId),
+    code: evidenceToken(input.code),
+    declineCode: evidenceToken(input.declineCode),
+    adviceCode: evidenceToken(input.adviceCode),
+    adviceOrigin: input.adviceOrigin,
+    operation: input.operation,
+    method: kind && recoveryMethodKey && method ? { kind, recoveryMethodKey, interaction: method.interaction } : null,
+    methodSource: kind && recoveryMethodKey ? input.methodSource : "unknown",
+  };
+}
+
+/** Persist beside legacy fields; never merge the diagnostic codes into them. */
+export function failureEvidencePayload(evidence: PaymentFailureEvidence | null | undefined): Record<string, unknown> {
+  return evidence ? { failureEvidence: serializeFailureEvidence(evidence) } : {};
+}

package/src/payments/stripe/stripeFailureEvidence.ts

@@ -0,0 +1,115 @@
+import { isPaymentRetryAdviceCode, type PaymentRecoveryEvidence, type PaymentRecoveryMethod,
+  type PaymentRecoveryOperation } from "@openlup/core/payment";
+import { evidenceRecord, evidenceToken, failureEvidencePayload, serializeFailureEvidence,
+  type FailureObservationSource, type PaymentFailureEvidence } from "./paymentFailureEvidence.js";
+
+export interface StripeIntentLike {
+  id: string;
+  status: string;
+  amount?: number | null;
+  amount_received?: number | null;
+  currency?: string | null;
+  client_secret?: string | null;
+  customer?: string | null;
+  payment_method?: string | null;
+  latest_charge?: string | null;
+  next_action?: { type?: string | null } | null;
+  last_payment_error?: {
+    code?: string | null;
+    message?: string | null;
+    type?: string | null;
+    decline_code?: string | null;
+    advice_code?: string | null;
+  } | null;
+  /** Kept separate: populating legacy fine fields would change renewal classification. */
+  diagnosticFailureEvidence?: PaymentFailureEvidence;
+}
+
+/** Reads only one current PaymentIntent/error, never an arbitrary historical Charge. */
+export function stripeFailureEvidence(input: unknown, options: {
+  source: FailureObservationSource;
+  confirmedFailureEvent?: boolean;
+  knownCardOnlyRequest?: boolean;
+}): PaymentFailureEvidence | null {
+  const object = evidenceRecord(input);
+  const thrown = object.type === "StripeCardError";
+  const intent = thrown ? evidenceRecord(object.payment_intent) : object;
+  const error = thrown ? object : evidenceRecord(intent.last_payment_error);
+  if (!thrown && !options.confirmedFailureEvent && Object.keys(error).length === 0) return null;
+  const refusalVerified = thrown || options.confirmedFailureEvent === true
+    || (intent.status === "requires_payment_method" && Object.keys(error).length > 0
+      && (error.type === "card_error" || error.code === "card_declined" || Boolean(intent.latest_charge)));
+  const errorMethod = evidenceRecord(error.payment_method);
+  const currentMethod = evidenceRecord(intent.payment_method);
+  const errorMethodId = typeof error.payment_method === "string" ? error.payment_method : errorMethod.id;
+  const currentMethodId = typeof intent.payment_method === "string" ? intent.payment_method : currentMethod.id;
+  const conflictingMethod = Boolean(errorMethodId && currentMethodId && errorMethodId !== currentMethodId)
+    || Boolean(errorMethod.type && currentMethod.type && errorMethod.type !== currentMethod.type);
+  const actualMethod = errorMethod.type ?? currentMethod.type;
+  const cardContract = options.knownCardOnlyRequest === true
+    || (Array.isArray(intent.payment_method_types) && intent.payment_method_types.length === 1
+      && intent.payment_method_types[0] === "card");
+  const flow = evidenceRecord(intent.metadata).providerFlow;
+  const operation: PaymentRecoveryOperation | null = flow === "off_session_payment" ? "stored_method_payment"
+    : intent.setup_future_usage === "off_session" ? "recurring_setup"
+      : intent.setup_future_usage === null && flow === "one_time_payment" ? "one_time_payment" : null;
+  const methodKind = actualMethod === "card" || actualMethod === "blik" ? actualMethod
+    : actualMethod == null && cardContract ? "card" : null;
+  const method: PaymentRecoveryMethod | null = methodKind
+    ? { kind: methodKind, recoveryMethodKey: methodKind, interaction: operation === "stored_method_payment" ? "stored_instrument" : "new_instrument" } : null;
+  const latestCharge = typeof intent.latest_charge === "string" ? intent.latest_charge : evidenceRecord(intent.latest_charge).id;
+  const errorCharge = typeof error.charge === "string" ? error.charge : evidenceRecord(error.charge).id;
+  // A last error tied to another charge cannot explain the currently observed charge.
+  const conflictingEvidence = conflictingMethod || Boolean(latestCharge && errorCharge && latestCharge !== errorCharge);
+  return serializeFailureEvidence({
+    version: 1, source: options.source,
+    disposition: conflictingEvidence ? "unreadable" : Object.keys(error).length ? "present" : "absent",
+    refusalVerified: refusalVerified && !conflictingEvidence, providerPaymentId: evidenceToken(intent.id),
+    providerChargeId: evidenceToken(errorCharge ?? latestCharge),
+    code: conflictingEvidence ? null : evidenceToken(error.code),
+    declineCode: conflictingEvidence ? null : evidenceToken(error.decline_code),
+    adviceCode: conflictingEvidence ? null : evidenceToken(error.advice_code),
+    adviceOrigin: "provider", operation: conflictingEvidence ? null : operation, method: conflictingEvidence ? null : method,
+    methodSource: actualMethod != null ? "provider" : cardContract ? "execution_contract" : "unknown",
+  });
+}
+
+const SAFE_CAUSES: Readonly<Record<string, PaymentRecoveryEvidence["cause"]>> = {
+  insufficient_funds: "insufficient_funds", expired_card: "expired_card",
+  incorrect_cvc: "invalid_payment_data", invalid_cvc: "invalid_payment_data",
+  incorrect_number: "invalid_payment_data", invalid_number: "invalid_payment_data",
+  invalid_expiry_month: "invalid_payment_data", invalid_expiry_year: "invalid_payment_data",
+  authentication_required: "authentication_required",
+  card_not_supported: "operation_unsupported", currency_not_supported: "operation_unsupported",
+  transaction_not_allowed: "operation_unsupported",
+};
+const RESTRICTED = new Set(["fraudulent", "highest_risk_level", "lost_card", "stolen_card", "merchant_blacklist"]);
+
+/** UI evidence only: does not call or alter the shared failure taxonomy. */
+export function normalizeStripeFailureEvidence(input: PaymentFailureEvidence): PaymentRecoveryEvidence {
+  const evidence = serializeFailureEvidence(input);
+  const code = evidence.declineCode ?? evidence.code;
+  const restricted = code !== null && RESTRICTED.has(code);
+  const readable = evidence.refusalVerified && evidence.disposition === "present";
+  // A refused BLIK registration names its operation, not a setup cause: no code
+  // read here distinguishes a refused agreement from a mistyped or expired code.
+  const cause = readable && !restricted && code && Object.hasOwn(SAFE_CAUSES, code)
+    ? SAFE_CAUSES[code]! : "generic_decline";
+  return {
+    refusalVerified: evidence.refusalVerified, cause,
+    certainty: cause === "generic_decline" ? "unknown" : "verified",
+    disclosure: restricted ? "restricted" : "safe", method: evidence.method, operation: evidence.operation,
+    advice: readable && evidence.adviceOrigin === "provider" && evidence.adviceCode !== null && isPaymentRetryAdviceCode(evidence.adviceCode)
+      ? { code: evidence.adviceCode, scope: evidence.method?.kind === "card" ? "instrument" : "unknown" } : null,
+  };
+}
+
+/** Preserve the existing webhook projection and append only failure diagnostics. */
+export function stripeWebhookPayload(input: {
+  eventId: string; eventType: string; providerPaymentId: string; amountMinor: number | null; currency: string | null;
+}, object: unknown): Record<string, unknown> {
+  return { provider: "stripe", ...input,
+    ...(input.eventType === "payment_intent.payment_failed"
+      ? failureEvidencePayload(stripeFailureEvidence(object, { source: "webhook", confirmedFailureEvent: true })) : {}),
+  };
+}

package/src/payments/stripe/stripeIntentConfirmationEvidence.ts

@@ -0,0 +1,34 @@
+import type { StripeIntentLike } from "./stripeSandboxPaymentExecutionAdapter.js";
+
+/**
+ * `requires_payment_method` on an intent that was never confirmed: no payment
+ * method attached, no charge, no payment error. The provider object exists —
+ * the request reached the provider and was accepted — but the payer never
+ * submitted an instrument, so no issuer was ever asked to approve anything.
+ *
+ * Both absences beside the status are load-bearing. A payment method attached
+ * but not yet confirmed means a charge may be seconds from moving; a charge or a
+ * payment error means an issuer HAS been asked and answered. Either presence
+ * makes this claim false, and the claim is used to decide what a durable row
+ * says about the payer's money, so it must stay narrow rather than convenient.
+ *
+ * Shared deliberately. The execution rail asserts it to record what a fresh
+ * intent is, and the reconciliation rail asserts it to answer a payer who is
+ * still standing in the checkout. Those are two readings of ONE provider state,
+ * and two copies of the predicate would let them drift into disagreeing about
+ * whether the same intent had been attempted — the kind of drift that is only
+ * discovered by a payer being told the wrong thing about their own payment.
+ *
+ * ⛔ Not to be widened into "the payer has gone" (abandonment). That is a
+ * separate verdict, passed on a payer who is no longer present, and it
+ * deliberately asserts fewer absences so a real refusal is never mislabelled as
+ * abandonment. Merging the two would put one predicate under two opposite
+ * pressures: this one must stay narrow so no live charge is called idle, that
+ * one must stay broad so no refusal is silently dropped out of dunning.
+ */
+export function noIssuerWasAsked(intent: StripeIntentLike): boolean {
+  return intent.status === "requires_payment_method"
+    && !intent.payment_method
+    && !intent.latest_charge
+    && !intent.last_payment_error;
+}