@openlup/platform 0.19.0 → 0.21.0

package/dist/payments/stripe/index.js

@@ -0,0 +1,239 @@
+import { createHash } from "node:crypto";
+import { classifyPaymentFailure, isPaymentRetryAdviceCode } from "@openlup/core/payment";
+import { createStripeSandboxPaymentExecutionAdapter } from "./stripeSandboxPaymentExecutionAdapter.js";
+import { createStripePaymentReconciliationProvider } from "./stripePaymentReconciliationProvider.js";
+import { normalizeStripeWebhookEvent } from "./stripeWebhookNormalizer.js";
+import { verifyStripeSignature } from "./webhookSignature.js";
+import { declineCodeHints } from "./declineFailureHints.js";
+/** Observed protocol capabilities; account activation remains host-owned. */
+export const stripePaymentCapabilities = Object.freeze({
+    providerKind: "stripe",
+    captureFlows: Object.freeze([Object.freeze({ kind: "card_payment", handoff: "client-confirmed", methodFamilies: Object.freeze(["card", "wallet"]) })]),
+    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",
+});
+const refusal = (reason) => ({ kind: "refusal", reason });
+/** Explicit construction is the only activation point; importing performs no I/O. */
+export function createStripePaymentAdapter(config) {
+    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) {
+        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 = 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 = 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 } } : {}),
+                    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 = JSON.parse(rawBody);
+                    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+                        return refusal("malformed");
+                    const event = raw;
+                    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) => {
+                    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) {
+    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, status) {
+    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) {
+    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) {
+    let normalized;
+    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.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 : {};
+    const intentRef = typeof metadata.paymentIntentId === "string" ? metadata.paymentIntentId : null;
+    const identity = { provider: "stripe", providerEventId: normalized.providerEventId,
+        providerOccurredAt: occurred };
+    let result;
+    if (normalized.methodLifecycle || normalized.eventType.startsWith("setup.")) {
+        const lifecycle = 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.id : null);
+        if (typeof method !== "string" || !method)
+            return refusal("unsupported-event");
+        const outcomes = {
+            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;
+        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", 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.decline_code),
+                        adviceCode: typeof object.last_payment_error.advice_code === "string"
+                            ? object.last_payment_error.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/dist/payments/stripe/intentMapper.d.ts

@@ -0,0 +1,26 @@
+import { 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 declare function mapStripeIntent(intent: StripeIntentShape, knownCardOnlyRequest?: boolean, source?: "execution" | "readback"): StripeIntentLike;
+export declare function mapSetupIntent(intent: StripeIntentShape): StripeIntentLike;
+export {};

package/dist/payments/stripe/intentMapper.js

@@ -0,0 +1,51 @@
+import { stripeFailureEvidence } from "./stripeFailureEvidence.js";
+export function mapStripeIntent(intent, knownCardOnlyRequest = false, source = "readback") {
+    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 = {
+        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) {
+    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/dist/payments/stripe/methodFacts.d.ts

@@ -0,0 +1,10 @@
+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 declare const METHOD_SCHEME_SNAPSHOT_KEY = "methodScheme";
+export declare const METHOD_LAST_DIGITS_SNAPSHOT_KEY = "methodLastDigits";
+export declare const METHOD_EXPIRES_AT_SNAPSHOT_KEY = "methodExpiresAt";
+export declare function methodFactSnapshotKeys(facts: PaymentMethodReplacementFacts | null | undefined): Record<string, unknown>;

package/dist/payments/stripe/methodFacts.js

@@ -0,0 +1,12 @@
+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) {
+    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/dist/payments/stripe/paymentFailureEvidence.d.ts

@@ -0,0 +1,26 @@
+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 declare function evidenceToken(value: unknown): string | null;
+export declare function evidenceRecord(value: unknown): Record<string, unknown>;
+/** Explicit construction prevents accidental payload expansion by object spreading. */
+export declare function serializeFailureEvidence(input: PaymentFailureEvidence): PaymentFailureEvidence;
+/** Persist beside legacy fields; never merge the diagnostic codes into them. */
+export declare function failureEvidencePayload(evidence: PaymentFailureEvidence | null | undefined): Record<string, unknown>;

package/dist/payments/stripe/paymentFailureEvidence.js

@@ -0,0 +1,33 @@
+/** Bounded machine tokens only. Free-form response fields never cross this seam. */
+export function evidenceToken(value) {
+    return typeof value === "string" && /^[a-zA-Z0-9_:.-]{1,96}$/.test(value) ? value : null;
+}
+export function evidenceRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value : {};
+}
+/** Explicit construction prevents accidental payload expansion by object spreading. */
+export function serializeFailureEvidence(input) {
+    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) {
+    return evidence ? { failureEvidence: serializeFailureEvidence(evidence) } : {};
+}

package/dist/payments/stripe/stripeFailureEvidence.d.ts

@@ -0,0 +1,41 @@
+import { type PaymentRecoveryEvidence } from "@openlup/core/payment";
+import { 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 declare function stripeFailureEvidence(input: unknown, options: {
+    source: FailureObservationSource;
+    confirmedFailureEvent?: boolean;
+    knownCardOnlyRequest?: boolean;
+}): PaymentFailureEvidence | null;
+/** UI evidence only: does not call or alter the shared failure taxonomy. */
+export declare function normalizeStripeFailureEvidence(input: PaymentFailureEvidence): PaymentRecoveryEvidence;
+/** Preserve the existing webhook projection and append only failure diagnostics. */
+export declare function stripeWebhookPayload(input: {
+    eventId: string;
+    eventType: string;
+    providerPaymentId: string;
+    amountMinor: number | null;
+    currency: string | null;
+}, object: unknown): Record<string, unknown>;

package/dist/payments/stripe/stripeFailureEvidence.js

@@ -0,0 +1,82 @@
+import { isPaymentRetryAdviceCode } from "@openlup/core/payment";
+import { evidenceRecord, evidenceToken, failureEvidencePayload, serializeFailureEvidence } from "./paymentFailureEvidence.js";
+/** Reads only one current PaymentIntent/error, never an arbitrary historical Charge. */
+export function stripeFailureEvidence(input, options) {
+    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 = 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 = 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 = {
+    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) {
+    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, object) {
+    return { provider: "stripe", ...input,
+        ...(input.eventType === "payment_intent.payment_failed"
+            ? failureEvidencePayload(stripeFailureEvidence(object, { source: "webhook", confirmedFailureEvent: true })) : {}),
+    };
+}

package/dist/payments/stripe/stripeIntentConfirmationEvidence.d.ts

@@ -0,0 +1,28 @@
+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 declare function noIssuerWasAsked(intent: StripeIntentLike): boolean;

package/dist/payments/stripe/stripeIntentConfirmationEvidence.js

@@ -0,0 +1,32 @@
+/**
+ * `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) {
+    return intent.status === "requires_payment_method"
+        && !intent.payment_method
+        && !intent.latest_charge
+        && !intent.last_payment_error;
+}

package/dist/payments/stripe/stripePaymentReconciliationProvider.d.ts

@@ -0,0 +1,35 @@
+import type { ProviderReconciliationStatus } from "./donorContracts.js";
+import type { PaymentProviderRecoveryProvider } from "./donorContracts.js";
+import type { StripeIntentLike } from "./stripeSandboxPaymentExecutionAdapter.js";
+export interface StripePaymentIntentReader {
+    retrievePaymentIntent(paymentIntentId: string): Promise<StripeIntentLike>;
+    cancelPaymentIntent?(paymentIntentId: string): Promise<StripeIntentLike>;
+}
+export interface StripePaymentIntentSearcher {
+    /**
+     * Search Stripe PaymentIntents by a metadata key/value pair (GET
+     * /v1/payment_intents/search). Every intent the payment-control adapter
+     * creates carries metadata.paymentIntentId = <local intent uuid>
+     * (stripeSandboxPaymentExecutionAdapter metadataFor), so this is the
+     * intent-correlated absence probe for prepared attempts that never recorded
+     * a provider payment id.
+     */
+    searchPaymentIntentsByMetadata(input: {
+        key: string;
+        value: string;
+        limit?: number;
+    }): Promise<{
+        ids: string[];
+    }>;
+}
+export declare function createStripePaymentReconciliationProvider(client: StripePaymentIntentReader & Partial<StripePaymentIntentSearcher>): PaymentProviderRecoveryProvider;
+export declare function normalizeStripeIntent(intent: StripeIntentLike): ProviderReconciliationStatus;
+/**
+ * The disposition of a failed intent nobody actually refused.
+ *
+ * Deliberately NOT a taxonomy class. The kernel classifies REFUSALS — it answers
+ * "may this instrument be charged again, and by whom" — and an absence of
+ * attempt is not a refusal, so an "abandonment" class would be a category error
+ * inside a vocabulary whose every other member describes an issuer's verdict.
+ */
+export declare const ABANDONED_BEFORE_CONFIRMATION = "abandoned_before_confirmation";