@trusty-squire/mcp 1.1.13-rc.8 → 1.1.13

package/dist/bot/pay-operator.js

@@ -3,7 +3,7 @@ import { classifyPaymentCandidateBinding, } from "@trusty-squire/skill-schema";
 import canonicalize from "canonicalize";
 import { createLocalJWKSet, decodeJwt, jwtVerify } from "jose";
 import { z } from "zod";
-import { ApiCallError } from "../api-client.js";
+import { ApiCallError, isPaymentApprovalTransportTimeout, } from "../api-client.js";
 import { PaymentCardFillCleanupError, PaymentSubmitOutcomeUnknownError, UnrecognizedPaymentFrameError, } from "./browser.js";
 import { generateOperatorKeypair, openSealed } from "./payment-hpke.js";
 const cardSchema = z.object({
@@ -162,6 +162,40 @@ function normalizeCard(value) {
 function confidenceAtLeastLow(value) {
     return value === "low" || value === "medium" || value === "high";
 }
+const MAX_PREVERIFIED_MANDATE_RELAY_MS = 18 * 60 * 1_000;
+function isJwtExpired(error) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ERR_JWT_EXPIRED");
+}
+async function verifyRelayedAssertion(jws, jwks, expectedAudience) {
+    const options = {
+        issuer: "https://vouchflow.dev",
+        audience: expectedAudience,
+    };
+    try {
+        return (await jwtVerify(jws, jwks, options)).payload;
+    }
+    catch (error) {
+        if (!isJwtExpired(error))
+            throw error;
+        const decoded = decodeJwt(jws);
+        const issuedAt = decoded.iat;
+        const expiresAt = decoded.exp;
+        const now = Date.now();
+        if (!Number.isSafeInteger(issuedAt) ||
+            !Number.isSafeInteger(expiresAt) ||
+            expiresAt <= issuedAt ||
+            now - expiresAt * 1_000 > MAX_PREVERIFIED_MANDATE_RELAY_MS) {
+            throw new Error("mandate_assertion_expired");
+        }
+        return (await jwtVerify(jws, jwks, {
+            ...options,
+            currentDate: new Date((expiresAt - 1) * 1_000),
+        })).payload;
+    }
+}
 async function verifyMandate(jws, expectedHash, vouchflowApiBase, expectedAudience, fetchImpl) {
     const jwksUrl = `${vouchflowApiBase.replace(/\/+$/, "")}/.well-known/jwks.json`;
     const signal = AbortSignal.timeout(5_000);
@@ -185,10 +219,11 @@ async function verifyMandate(jws, expectedHash, vouchflowApiBase, expectedAudien
         !Array.isArray(body.keys)) {
         throw new Error("invalid_jwks");
     }
-    const { payload } = await jwtVerify(jws, createLocalJWKSet(body), {
-        issuer: "https://vouchflow.dev",
-        audience: expectedAudience,
-    });
+    // Every candidate returned by this authenticated relay was already checked
+    // at phone submission. Re-check all cryptographic and binding properties,
+    // while allowing only that exact candidate's short-lived assertion to age
+    // within the still-live approval window.
+    const payload = await verifyRelayedAssertion(jws, createLocalJWKSet(body), expectedAudience);
     const signedHash = decodePayloadHash(payload.payload_sha256);
     if (!timingSafeEqual(Buffer.from(expectedHash), Buffer.from(signedHash))) {
         throw new Error("payload_hash_mismatch");
@@ -212,6 +247,7 @@ function safeFailureReason(error) {
         "payload_hash_mismatch",
         "invalid_mandate_context",
         "insufficient_mandate_confidence",
+        "mandate_assertion_expired",
         "invalid_card_pan",
         "invalid_card_expiry",
     ];
@@ -241,6 +277,29 @@ function cardRequiredResult(approvalUrl, checkout, reason) {
         },
     };
 }
+function approvalDeniedResult(approvalId, approvalUrl, checkout) {
+    return {
+        status: "payment_approval_denied",
+        approval_id: approvalId,
+        approval_url: approvalUrl,
+        merchant: checkout.merchant,
+        amount_cents: checkout.amount_cents,
+        currency: checkout.currency,
+    };
+}
+function approvalExpiredResult(approvalUrl, checkout, jit, boundCardRef) {
+    const base = {
+        status: "payment_approval_timeout",
+        approval_url: approvalUrl,
+        merchant: checkout.merchant,
+        amount_cents: checkout.amount_cents,
+        currency: checkout.currency,
+    };
+    return jit && hasBoundCard(boundCardRef) ? { ...base, card_persisted: true } : base;
+}
+function isPaymentApprovalDeniedError(error) {
+    return error instanceof ApiCallError && error.code === "payment_approval_denied";
+}
 // Total additional time (beyond this call's own bounded wait) that a
 // resumed, still-pending decoupled/out-of-band 3DS challenge stays
 // checkable via operate_payment_status before handing back an accurate
@@ -248,6 +307,7 @@ function cardRequiredResult(approvalUrl, checkout, reason) {
 // their phone, open the banking app, and approve — but bounded, matching
 // the rest of this file's "wait, but never forever" posture.
 const THREE_DS_RESUME_WINDOW_MS = 20 * 60 * 1000;
+const PAYMENT_APPROVAL_RESPONSE_RESERVE_MS = 500;
 // The cardholder approves 3-D Secure via an app-push in their bank app while
 // the browser's checkout JavaScript owns the native challenge handshake. Fires
 // the Telegram nudge WITHOUT awaiting it (a slow/unresolved Telegram call must
@@ -306,6 +366,8 @@ function statusAfterThreeDsResolution(currentStatus, resolution) {
             return "payment_submitted";
         case "failed":
             return "payment_declined";
+        case "challenge_pending":
+            return "payment_3ds_required";
         case "timeout":
             return currentStatus;
     }
@@ -370,7 +432,11 @@ function defaultDependencies() {
         onCardFillCleanupFailed: () => undefined,
         onSubmitStarted: () => undefined,
         onApprovalPending: () => undefined,
+        onApprovalTerminal: () => undefined,
+        onThreeDsHandoffArmed: () => undefined,
+        coordinateThreeDsAudit: async (_state, audit) => await audit(),
         onThreeDsPending: () => undefined,
+        onThreeDsCleared: () => undefined,
     };
 }
 function logPaymentReviewLifecycle(event) {
@@ -418,15 +484,28 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
         }
         if (resume !== undefined) {
             let reusable = false;
-            if (deps.now() < resume.deadline) {
-                try {
-                    const live = await api.getPaymentApproval(resume.approval_id);
-                    reusable = isLiveResumableApproval(live, resume, deps.now());
+            try {
+                const live = await api.getPaymentApproval(resume.approval_id);
+                const liveDeadline = Date.parse(live.expires_at);
+                const terminalStatus = live.status === "denied"
+                    ? "denied"
+                    : live.status === "expired" ||
+                        (Number.isFinite(liveDeadline) ? liveDeadline : resume.deadline) <= deps.now()
+                        ? "expired"
+                        : null;
+                if (terminalStatus !== null) {
+                    deps.onApprovalTerminal(resume, terminalStatus);
+                    resumableState = undefined;
+                    keypairHandedOff = false;
+                    return terminalStatus === "denied"
+                        ? approvalDeniedResult(resume.approval_id, resume.approval_url, resume.checkout)
+                        : approvalExpiredResult(resume.approval_url, resume.checkout, resume.jit, resume.boundCardRef);
                 }
-                catch (error) {
-                    if (!(error instanceof ApiCallError && error.code === "payment_approval_not_found")) {
-                        throw error;
-                    }
+                reusable = isLiveResumableApproval(live, resume, deps.now());
+            }
+            catch (error) {
+                if (!(error instanceof ApiCallError && error.code === "payment_approval_not_found")) {
+                    throw error;
                 }
             }
             if (!reusable) {
@@ -538,14 +617,10 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
             ...(threeDsWaitSeconds !== undefined ? { three_ds_wait_seconds: threeDsWaitSeconds } : {}),
         });
         await deps.surfaceApprovalUrl(approvalUrl);
-        // [P0] This call's own wait budget, bounded by the server approval expiry.
-        // Undefined pollBudgetMs (direct executeOperatePay callers) = no additional
-        // bound, i.e. the legacy full-deadline blocking behavior.
+        // This call's wait is bounded by both its client budget and server expiry.
         const callDeadline = deps.pollBudgetMs === undefined
             ? deadline
             : Math.min(deadline, deps.now() + deps.pollBudgetMs);
-        // True once this call's (not the overall) budget is exhausted with no
-        // resolution — distinguishes "still pending, ask again" from "expired".
         let budgetExhausted = false;
         const shouldKeepPolling = () => {
             const now = deps.now();
@@ -557,37 +632,30 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
             }
             return true;
         };
-        // In the JIT branch, the approval starts card-less; the card is bound
-        // server-side mid-ceremony. Track the latest binding so a timeout/expiry
-        // can distinguish "no card was ever added" (card_required) from "card was
-        // stored but never approved" (payment_approval_timeout, card persists).
+        // A JIT approval that expires before binding still needs a card; a bound
+        // card remains stored even though the approval itself is terminal.
         const timeoutResult = () => {
             if (jit && !hasBoundCard(boundCardRef)) {
                 return cardRequiredResult(approvalUrl, checkout, "the add-card link expired before a card was added");
             }
-            const base = {
-                status: "payment_approval_timeout",
-                approval_url: approvalUrl,
-                merchant: checkout.merchant,
-                amount_cents: checkout.amount_cents,
-                currency: checkout.currency,
-            };
-            // JIT + a bound card = the user added a card but never approved. The card
-            // stays in the vault, so the retry is a fast has-card approval.
-            return jit ? { ...base, card_persisted: true } : base;
+            return approvalExpiredResult(approvalUrl, checkout, jit, boundCardRef);
+        };
+        const approvalExpired = () => deps.now() >= deadline;
+        let terminalApprovalState;
+        const terminalApprovalResult = (terminalStatus) => {
+            const state = resumableState?.() ?? terminalApprovalState;
+            if (state !== undefined)
+                deps.onApprovalTerminal(state, terminalStatus);
+            resumableState = undefined;
+            keypairHandedOff = false;
+            return terminalStatus === "denied"
+                ? approvalDeniedResult(approvalId, approvalUrl, checkout)
+                : timeoutResult();
         };
+        const expiredApprovalResult = () => terminalApprovalResult("expired");
         let approved;
         let claims;
-        // Always runs at least once — a fresh call must make one live check
-        // before ever reporting pending, and a resumed call with a zero poll
-        // budget must too. Two things gate every re-entry to the top: (1) right
-        // before each sleep, shouldKeepPolling() skips the sleep entirely when
-        // the budget is already exhausted, so a not-yet-resolved call never
-        // blocks on a real wait before returning; (2) the iteration>0 check
-        // here re-validates AFTER that sleep (real time — or a mocked clock —
-        // may have advanced past the deadline during it) so the loop never
-        // spends one more live poll call past the budget it just decided to
-        // respect.
+        // Always make one live read; later iterations recheck the budget after sleep.
         let iteration = 0;
         let immediateReviewFollowup = false;
         while (true) {
@@ -595,12 +663,30 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
                 break;
             immediateReviewFollowup = false;
             iteration++;
-            const approval = await api.getPaymentApproval(approvalId, deps.now() < callDeadline ? true : "immediate");
+            const remainingPollMs = Math.max(Math.min(callDeadline, deadline) - deps.now(), 0);
+            const candidateRead = remainingPollMs > 0 ? true : "immediate";
+            let approval;
+            try {
+                approval =
+                    candidateRead === true
+                        ? await api.getPaymentApproval(approvalId, true, Math.min(Math.max(remainingPollMs - PAYMENT_APPROVAL_RESPONSE_RESERVE_MS, 0), 15_000), remainingPollMs)
+                        : await api.getPaymentApproval(approvalId, "immediate");
+            }
+            catch (error) {
+                if (!isPaymentApprovalTransportTimeout(error))
+                    throw error;
+                budgetExhausted = true;
+                break;
+            }
+            const liveDeadline = Date.parse(approval.expires_at);
+            if (Number.isFinite(liveDeadline))
+                deadline = Math.min(deadline, liveDeadline);
             boundCardRef = approval.card_ref;
-            if (approval.status === "expired") {
-                resumableState = undefined;
-                keypairHandedOff = false;
-                return timeoutResult();
+            if (approval.status === "denied") {
+                return terminalApprovalResult("denied");
+            }
+            if (approval.status === "expired" || approvalExpired()) {
+                return expiredApprovalResult();
             }
             const hasCandidate = typeof approval.jws === "string" && typeof approval.sealed_card === "string";
             if (approval.status === "approved" && !hasCandidate) {
@@ -692,6 +778,8 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
                                 approval_url: approvalUrl,
                             };
                         }
+                        if (approvalExpired())
+                            return expiredApprovalResult();
                         let candidateCardBytes;
                         let candidateCard;
                         try {
@@ -731,6 +819,9 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
                             }
                             catch (error) {
                                 candidateCardBytes.fill(0);
+                                if (isPaymentApprovalDeniedError(error)) {
+                                    return terminalApprovalResult("denied");
+                                }
                                 const failureReason = error instanceof Error && /404|409/.test(error.message)
                                     ? "confirm_status"
                                     : "confirm_failed";
@@ -767,33 +858,30 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
                                     throw new Error("confirm_status");
                             }
                             catch (error) {
-                                try {
-                                    const reconciliation = await api.confirmPaymentApproval(approvalId, candidate);
-                                    if (reconciliation.status !== "approved")
-                                        throw error;
-                                }
-                                catch {
-                                    candidateCardBytes.fill(0);
-                                    // The initial confirm may have actually gone through server-side (its
-                                    // response was merely lost) even though reconciliation couldn't prove
-                                    // it. Throwing here would leave resumableState live, and the outer
-                                    // catch would resurrect this candidate as still-awaiting — letting a
-                                    // later call re-confirm and re-charge a purchase that may already be
-                                    // spent. Fail closed with a terminal result instead, mirroring the
-                                    // review-candidate branch above.
-                                    const failureReason = error instanceof Error && /404|409/.test(error.message)
-                                        ? "confirm_status"
-                                        : "confirm_failed";
-                                    logPaymentCandidateLifecycle(approvalId, "approval", "confirmation_failed", failureReason);
-                                    return {
-                                        status: "payment_confirmation_failed",
-                                        reason: failureReason,
-                                        candidate_kind: "approval",
-                                        approval_url: approvalUrl,
-                                    };
+                                candidateCardBytes.fill(0);
+                                if (isPaymentApprovalDeniedError(error)) {
+                                    return terminalApprovalResult("denied");
                                 }
+                                const failureReason = error instanceof Error && /404|409/.test(error.message)
+                                    ? "confirm_status"
+                                    : "confirm_failed";
+                                const state = resumableState();
+                                deps.onApprovalTerminal(state, "payment_confirmation_failed");
+                                resumableState = undefined;
+                                keypairHandedOff = false;
+                                logPaymentCandidateLifecycle(approvalId, "approval", "confirmation_failed", failureReason);
+                                return {
+                                    status: "payment_confirmation_failed",
+                                    reason: failureReason,
+                                    candidate_kind: "approval",
+                                    approval_url: approvalUrl,
+                                };
                             }
                         }
+                        if (approvalExpired()) {
+                            candidateCardBytes.fill(0);
+                            return expiredApprovalResult();
+                        }
                         logPaymentCandidateLifecycle(approvalId, "approval", "ready_to_charge");
                         cardBytes = candidateCardBytes;
                         card = candidateCard;
@@ -824,10 +912,10 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
                     candidate_kind: "review",
                     ready_to_charge: false,
                     next: {
-                        tool: "operate_payment_status",
-                        wait_seconds: 15,
+                        tool: "operate_pay",
                         message: "The review signature was verified, but final payment approval is still required. " +
-                            "Refresh the approval page if it does not advance to the final approval prompt.",
+                            "Refresh the approval page if it does not advance to the final approval prompt, " +
+                            "then call operate_pay again with the same arguments; it resumes this approval and waits.",
                     },
                 };
             }
@@ -846,7 +934,12 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
                     merchant: checkout.merchant,
                     candidate_kind: "none",
                     ready_to_charge: false,
-                    next: { tool: "operate_payment_status", wait_seconds: 15 },
+                    next: {
+                        tool: "operate_pay",
+                        message: "The bounded server wait ended before the human responded. Call operate_pay again " +
+                            "with the same arguments; it resumes this approval and continues waiting without " +
+                            "creating another approval.",
+                    },
                 };
             }
             if (jit) {
@@ -856,15 +949,14 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
                 }
                 catch { }
             }
-            resumableState = undefined;
-            keypairHandedOff = false;
-            return timeoutResult();
+            return expiredApprovalResult();
         }
         if (claims === undefined || card === undefined) {
             resumableState = undefined;
             keypairHandedOff = false;
             return timeoutResult();
         }
+        terminalApprovalState = resumableState?.();
         resumableState = undefined;
         keypairHandedOff = false;
         const cardRef = cardRefArg ?? approved.card_ref;
@@ -875,7 +967,6 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
                 approval_url: approvalUrl,
             };
         }
-        deps.onCardResolved(cardRef);
         const last4 = card.pan.slice(-4);
         const mandateId = typeof claims.mandate_id === "string"
             ? claims.mandate_id
@@ -943,10 +1034,16 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
                     ...(liveOrigin !== null ? { live_checkout_origin: liveOrigin } : {}),
                 };
             }
+            if (approvalExpired())
+                return expiredApprovalResult();
+            deps.onCardResolved(cardRef);
             try {
-                await browser.fillCheckoutCardFields(card);
+                await browser.fillCheckoutCardFields(card, { deadline });
             }
             catch (error) {
+                if (error instanceof Error && error.message === "payment_approval_expired") {
+                    return expiredApprovalResult();
+                }
                 const frameOrigin = error instanceof UnrecognizedPaymentFrameError
                     ? error.frameOrigin
                     : error instanceof PaymentCardFillCleanupError
@@ -1007,26 +1104,49 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
                     "does not need to happen before you place the order.",
             };
         }
+        if (approvalExpired())
+            return expiredApprovalResult();
+        deps.onCardResolved(cardRef);
+        const pendingThreeDsHandoff = {
+            approval_id: approvalId,
+            approval_url: approvalUrl,
+            checkout,
+            last4,
+            ...(mandateId !== undefined ? { mandate_id: mandateId } : {}),
+            deadline: deps.now() + THREE_DS_RESUME_WINDOW_MS,
+            outcome: "unknown",
+        };
+        deps.onThreeDsHandoffArmed(pendingThreeDsHandoff);
+        let retainedPendingThreeDs = null;
         const retainPendingThreeDs = () => {
-            deps.onThreeDsPending({
-                approval_id: approvalId,
-                approval_url: approvalUrl,
-                checkout,
-                last4,
-                ...(submitResult.payment_instrument_mismatch !== undefined
-                    ? { payment_instrument_mismatch: submitResult.payment_instrument_mismatch }
-                    : {}),
-                ...(mandateId !== undefined ? { mandate_id: mandateId } : {}),
-                deadline: deps.now() + THREE_DS_RESUME_WINDOW_MS,
-            });
+            const firstRetention = retainedPendingThreeDs === null;
+            if (retainedPendingThreeDs === null) {
+                retainedPendingThreeDs = pendingThreeDsHandoff;
+            }
+            if (submitResult.payment_instrument_mismatch !== undefined) {
+                retainedPendingThreeDs.payment_instrument_mismatch =
+                    submitResult.payment_instrument_mismatch;
+            }
+            if (firstRetention)
+                deps.onThreeDsPending(retainedPendingThreeDs);
         };
-        const pendingThreeDsNext = {
+        const clearPendingThreeDs = () => {
+            if (retainedPendingThreeDs === null)
+                return;
+            deps.onThreeDsCleared(retainedPendingThreeDs);
+            retainedPendingThreeDs = null;
+        };
+        const pendingOutcomeNext = () => ({
             tool: "operate_payment_status",
             wait_seconds: 15,
-            hint: "The 3-D Secure challenge has not resolved. Call operate_payment_status to keep " +
-                "checking the same submitted charge — this does not re-release the card or create a " +
-                "new approval.",
-        };
+            hint: pendingThreeDsHandoff.outcome === "three_ds"
+                ? "The 3-D Secure challenge has not resolved. Call operate_payment_status to keep " +
+                    "checking the same submitted charge — this does not re-release the card or create a " +
+                    "new approval."
+                : "The submitted payment has no confirmed merchant outcome or 3-D Secure evidence. " +
+                    "Call operate_payment_status to keep checking the same attempt; its outcome remains " +
+                    "unknown until terminal merchant or authentication evidence appears.",
+        });
         let paymentStatus = "payment_submitted";
         let submitResult = { three_ds_required: false, order_confirmed: false };
         try {
@@ -1037,48 +1157,104 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
                 ...(args.card_issuer !== undefined
                     ? { issuer: args.card_issuer, issuer_source: "bin_metadata" }
                     : {}),
+            }, {
+                onSubmitDispatched: retainPendingThreeDs,
+                beforeSubmitDispatch: () => {
+                    if (approvalExpired())
+                        throw new Error("payment_approval_expired");
+                    return deadline - deps.now();
+                },
             });
             if (submitResult.three_ds_required)
                 paymentStatus = "payment_3ds_required";
             else if (!submitResult.order_confirmed)
                 paymentStatus = "payment_outcome_unknown";
+            if (submitResult.three_ds_required)
+                pendingThreeDsHandoff.outcome = "three_ds";
         }
         catch (error) {
+            if (error instanceof Error && error.message === "payment_approval_expired") {
+                clearPendingThreeDs();
+                return expiredApprovalResult();
+            }
             const outcomeUnknown = error instanceof PaymentSubmitOutcomeUnknownError;
             paymentStatus = outcomeUnknown ? "payment_outcome_unknown" : "payment_checkout_failed";
+            let terminalSubmitOutcome = false;
             if (outcomeUnknown) {
-                await browser.waitForThreeDsResolution(0).catch(() => undefined);
+                const resolution = await browser.waitForThreeDsResolution(0).catch(() => undefined);
+                if (resolution !== undefined) {
+                    paymentStatus = statusAfterThreeDsResolution(paymentStatus, resolution);
+                    terminalSubmitOutcome = resolution === "succeeded" || resolution === "failed";
+                    if (resolution === "challenge_pending") {
+                        pendingThreeDsHandoff.outcome = "three_ds";
+                        submitResult.three_ds_required = true;
+                    }
+                }
                 const mismatch = browser.paymentInstrumentMismatch?.();
                 if (mismatch !== undefined)
                     submitResult.payment_instrument_mismatch = mismatch;
             }
             let audit_recorded = true;
             try {
-                await api.auditPayment({
-                    ...checkout,
-                    last4,
-                    status: paymentStatus,
-                    ...(mandateId !== undefined ? { mandate_id: mandateId } : {}),
-                });
+                const recordAudit = async () => {
+                    await api.auditPayment({
+                        ...checkout,
+                        last4,
+                        status: paymentStatus,
+                        ...(mandateId !== undefined ? { mandate_id: mandateId } : {}),
+                    });
+                };
+                if (retainedPendingThreeDs === null)
+                    await recordAudit();
+                else
+                    await deps.coordinateThreeDsAudit(retainedPendingThreeDs, recordAudit);
             }
             catch {
                 audit_recorded = false;
             }
-            if (outcomeUnknown)
+            if (outcomeUnknown && !terminalSubmitOutcome && retainedPendingThreeDs !== null) {
                 retainPendingThreeDs();
+            }
+            else {
+                clearPendingThreeDs();
+            }
             return {
                 status: paymentStatus,
                 audit_recorded,
-                reason: outcomeUnknown
-                    ? "payment_submit_outcome_unknown"
-                    : error instanceof Error && /^payment_[a-z_]+(?::[a-z_]+)?$/.test(error.message)
-                        ? error.message
-                        : "payment_checkout_failed",
+                ...(!terminalSubmitOutcome
+                    ? {
+                        reason: outcomeUnknown
+                            ? paymentStatus === "payment_3ds_required"
+                                ? "payment_3ds_required"
+                                : "payment_submit_outcome_unknown"
+                            : error instanceof Error && /^payment_[a-z_]+(?::[a-z_]+)?$/.test(error.message)
+                                ? error.message
+                                : "payment_checkout_failed",
+                    }
+                    : {}),
                 approval_url: approvalUrl,
                 ...(submitResult.payment_instrument_mismatch !== undefined
                     ? { warning: submitResult.payment_instrument_mismatch }
                     : {}),
-                ...(outcomeUnknown ? { next: pendingThreeDsNext } : {}),
+                ...(outcomeUnknown && !terminalSubmitOutcome && retainedPendingThreeDs !== null
+                    ? { next: pendingOutcomeNext() }
+                    : {}),
+                ...(paymentStatus === "payment_3ds_required"
+                    ? {
+                        needs_user: {
+                            wall: "3ds",
+                            message: threeDsHandoffMessage(submitResult, undefined),
+                            resume: "checkout",
+                        },
+                    }
+                    : {}),
+                ...(paymentStatus === "payment_submitted"
+                    ? {
+                        merchant: checkout.merchant,
+                        amount_cents: checkout.amount_cents,
+                        currency: checkout.currency,
+                    }
+                    : {}),
             };
         }
         finally {
@@ -1090,20 +1266,32 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
         if (submitResult.payment_instrument_mismatch === undefined &&
             !submitResult.order_confirmed &&
             threeDsWaitMs > 0) {
-            getThreeDsTelegramSent = trackThreeDsNotification(api.notifyThreeDs(approvalId, threeDsNotificationMode(submitResult)));
+            const challengeKnownBeforeWait = pendingThreeDsHandoff.outcome === "three_ds";
+            if (challengeKnownBeforeWait) {
+                getThreeDsTelegramSent = trackThreeDsNotification(api.notifyThreeDs(approvalId, threeDsNotificationMode(submitResult)));
+            }
             const resolution = await browser.waitForThreeDsResolution(threeDsWaitMs);
             const mismatch = browser.paymentInstrumentMismatch?.();
             if (mismatch !== undefined)
                 submitResult.payment_instrument_mismatch ??= mismatch;
             paymentStatus = statusAfterThreeDsResolution(paymentStatus, resolution);
+            if (resolution === "challenge_pending") {
+                pendingThreeDsHandoff.outcome = "three_ds";
+                submitResult.three_ds_required = true;
+                if (!challengeKnownBeforeWait) {
+                    getThreeDsTelegramSent = trackThreeDsNotification(api.notifyThreeDs(approvalId, "detected_challenge"));
+                }
+            }
         }
         let auditRecorded = true;
         try {
-            await api.auditPayment({
-                ...checkout,
-                last4,
-                status: paymentStatus,
-                ...(mandateId !== undefined ? { mandate_id: mandateId } : {}),
+            await deps.coordinateThreeDsAudit(pendingThreeDsHandoff, async () => {
+                await api.auditPayment({
+                    ...checkout,
+                    last4,
+                    status: paymentStatus,
+                    ...(mandateId !== undefined ? { mandate_id: mandateId } : {}),
+                });
             });
         }
         catch {
@@ -1121,16 +1309,23 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
                 ...(submitResult.payment_instrument_mismatch !== undefined
                     ? { warning: submitResult.payment_instrument_mismatch }
                     : {}),
-                needs_user: {
-                    wall: "3ds",
-                    message: threeDsHandoffMessage(submitResult, getThreeDsTelegramSent()),
-                    resume: "checkout",
-                    ...(submitResult.challenge_url !== undefined ? { url: submitResult.challenge_url } : {}),
-                },
-                next: pendingThreeDsNext,
+                ...(paymentStatus === "payment_3ds_required"
+                    ? {
+                        needs_user: {
+                            wall: "3ds",
+                            message: threeDsHandoffMessage(submitResult, getThreeDsTelegramSent()),
+                            resume: "checkout",
+                            ...(submitResult.challenge_url !== undefined
+                                ? { url: submitResult.challenge_url }
+                                : {}),
+                        },
+                    }
+                    : {}),
+                next: pendingOutcomeNext(),
             };
         }
         if (paymentStatus === "payment_declined") {
+            clearPendingThreeDs();
             return {
                 status: paymentStatus,
                 audit_recorded: auditRecorded,
@@ -1140,6 +1335,7 @@ export async function executeOperatePay(args, api, browser, overrides = {}) {
                     : {}),
             };
         }
+        clearPendingThreeDs();
         return {
             status: paymentStatus,
             audit_recorded: auditRecorded,