@visa/cli 4.1.0-rc.262 → 4.1.0-rc.264

package/dist/checkout-engine/executor.js

@@ -18,7 +18,7 @@ import { randomUUID } from 'node:crypto';
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { detectFields } from './detect.js';
-import { checkMandate, checkMandatePreFill } from './mandate.js';
+import { checkMandate, checkMandatePreFill, } from './mandate.js';
 import { EvidenceLog, maskOtp } from './evidence.js';
 import { observeOutcome } from './outcome.js';
 import { selectAdapter } from './adapters/index.js';
@@ -27,7 +27,7 @@ import { traceHandleFields } from './trace-handles.js';
 import { readGenericPageAmount } from './amount.js';
 import { webBotAuthHeadersOrNone } from './web-bot-auth.js';
 import { assertShopifyGuestCheckout, ensureShopifyGuestCheckout, isShopifyCheckoutPage, readShopifyAmount, readStableShopifyAmount, shopifyEnglishCheckoutUrl, } from './adapters/shopify.js';
-import { navigationRedirectEvidence, shopifyPrimaryDomainAlias } from './shopify-primary-domain.js';
+import { navigationRedirectEvidence, shopifyPrimaryDomainAlias, } from './shopify-primary-domain.js';
 export { minorFromDecimal, pageCurrency } from './amount.js';
 const SUBMIT_TEXT = /pay|place order|complete|buy|submit|checkout/i;
 const REVEAL_TEXT = /continue|next|proceed|review|go to payment/i;
@@ -389,7 +389,7 @@ function unknownPreparedCheckoutResult(reviewId) {
     evidence.step('approval', { approved: false, reviewId, reason: detail });
     return makeResult('failed', {}, evidence, [], detail);
 }
-function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirmationRef, failureCode) {
+function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirmationRef, failureCode, refusalCode) {
     const steps = evidence.getSteps();
     const approved = steps.find((step) => step.type === 'approval' && step.data.approved === true);
     const minted = steps.find((step) => step.type === 'credential-minted');
@@ -428,15 +428,25 @@ function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirma
             ...(completed ? { fillCompletedAt: completed.ts } : {}),
         },
         ...(terminalFailureCode ? { failureCode: terminalFailureCode } : {}),
+        ...(refusalCode ? { refusalCode } : {}),
         ...(detail ? { detail } : {}),
         ...(confirmationRef ? { confirmationRef } : {}),
     };
 }
+// Shopify computes shipping and tax asynchronously after the delivery address
+// lands; a settled, reconciled summary can take well over the default 6s on a
+// cold checkout. Review is free and safe to wait on; approval and pre-submit
+// keep the strict short window because they only confirm an already-settled page.
+const SHOPIFY_REVIEW_SETTLE_MS = 20_000;
 async function readTransactionFacts(page, opts, phase) {
     const shopify = await isShopifyCheckoutPage(page);
     const amountRead = shopify
         ? phase === 'review'
-            ? await readStableShopifyAmount(page)
+            ? await readStableShopifyAmount(page, SHOPIFY_REVIEW_SETTLE_MS, {
+                // A trusted UCP handoff carries the merchant-settled total; a page
+                // that omits a tax row must match it before the review trusts it.
+                expectedMinor: opts.trustedMerchantIdentity ? (opts.amountMinor ?? null) : null,
+            })
             : await readShopifyAmount(page, true)
         : await readGenericPageAmount(page);
     const pageAmount = shopify && amountRead.kind === 'none'
@@ -472,6 +482,7 @@ async function readTransactionFacts(page, opts, phase) {
             amountMinor,
             currency,
             source,
+            code: 'amount_unreadable',
             reason: pageAmount.kind === 'unreadable'
                 ? (pageAmount.reason ?? 'page total is displayed but cannot be parsed unambiguously')
                 : 'transaction amount could not be determined',
@@ -486,6 +497,7 @@ async function readTransactionFacts(page, opts, phase) {
             amountMinor,
             currency,
             source,
+            code: 'currency_unreadable',
             reason: 'transaction currency could not be determined',
             detail: 'transaction currency could not be determined (page total does not state one unambiguously, no currency asserted by the caller); refusing fail-closed',
         };
@@ -526,23 +538,96 @@ function exactOrigin(value) {
         return null;
     }
 }
-export function trustedMerchantOriginRefusal(options, pageUrl, expectedOrigin) {
+export function trustedMerchantOriginVerdict(options, pageUrl, expectedOrigin) {
     const identity = options.trustedMerchantIdentity;
     if (!identity)
         return null;
-    if (Date.parse(identity.expiresAt) <= Date.now())
-        return 'trusted UCP checkout handoff expired';
+    if (Date.parse(identity.expiresAt) <= Date.now()) {
+        return { code: 'trusted_handoff_expired', reason: 'trusted UCP checkout handoff expired' };
+    }
     const origin = exactOrigin(pageUrl);
-    if (!origin)
-        return 'trusted UCP checkout reached a non-HTTPS or credentialed origin';
+    if (!origin) {
+        return {
+            code: 'trusted_origin_insecure',
+            reason: 'trusted UCP checkout reached a non-HTTPS or credentialed origin',
+        };
+    }
     if (expectedOrigin) {
         return origin === expectedOrigin
             ? null
-            : `merchant origin changed after review: ${expectedOrigin} -> ${origin}`;
+            : {
+                code: 'trusted_origin_changed',
+                reason: `merchant origin changed after review: ${expectedOrigin} -> ${origin}`,
+            };
     }
     return identity.allowedOrigins.includes(origin)
         ? null
-        : `trusted UCP checkout reached undeclared origin ${origin}`;
+        : {
+            code: 'trusted_origin_undeclared',
+            reason: `trusted UCP checkout reached undeclared origin ${origin}`,
+        };
+}
+export function trustedMerchantOriginRefusal(options, pageUrl, expectedOrigin) {
+    return trustedMerchantOriginVerdict(options, pageUrl, expectedOrigin)?.reason ?? null;
+}
+function wwwNormalizedHost(host) {
+    return host.toLowerCase().replace(/^www\./, '');
+}
+const MYSHOPIFY_SERVICE_HOST = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.myshopify\.com$/;
+/**
+ * Bind the storefront a trusted UCP continuation actually lands on (#8669).
+ *
+ * The merchant published its UCP business profile at its own business origin
+ * and declared the permanent `*.myshopify.com` service that issued the
+ * continuation; the CLI verified both before minting the handoff. That is
+ * independently verified merchant provenance, so the review may bind the final
+ * page origin when, and only when: the navigation started on that declared
+ * myshopify origin, the final origin is plain HTTPS, and its host is the
+ * declared business host modulo a leading `www.` label. The redirect chain in
+ * between (Shopify's primary-domain hop, its shop.app bounce, #8496) carries no
+ * authority either way: a redirect cannot land on the merchant's own business
+ * domain unless the merchant controls it, and any other final host stays an
+ * undeclared origin. Shopify's `primary_domain_redirection` proof is recorded
+ * as evidence when present but is not required.
+ */
+export function trustedShopifyAliasOrigin(args) {
+    let initial;
+    let final;
+    try {
+        initial = new URL(args.initialUrl);
+        final = new URL(args.finalUrl);
+    }
+    catch {
+        return null;
+    }
+    if (initial.protocol !== 'https:' || final.protocol !== 'https:')
+        return null;
+    if (final.username || final.password || final.port)
+        return null;
+    const initialHost = initial.hostname.toLowerCase();
+    const finalHost = final.hostname.toLowerCase();
+    if (!MYSHOPIFY_SERVICE_HOST.test(initialHost) || initialHost === finalHost)
+        return null;
+    // A declared origin is held to the same standard as the final one: plain
+    // HTTPS, default port, no credentials. Anything else never contributes a
+    // host, so the identity stays an origin set rather than widening to a host.
+    const declared = args.allowedOrigins.flatMap((candidate) => {
+        try {
+            const url = new URL(candidate);
+            return url.protocol === 'https:' && !url.username && !url.password && !url.port
+                ? [url.hostname.toLowerCase()]
+                : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    if (!declared.includes(initialHost))
+        return null;
+    const declaredBusiness = declared.some((host) => host !== initialHost &&
+        !MYSHOPIFY_SERVICE_HOST.test(host) &&
+        wwwNormalizedHost(host) === wwwNormalizedHost(finalHost));
+    return declaredBusiness ? final.origin.toLowerCase() : null;
 }
 function mandateForPage(options, pageUrl) {
     if (!options.trustedMerchantIdentity)
@@ -812,17 +897,52 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
             url: options.trustedMerchantIdentity ? exactOrigin(page.url()) : page.url(),
         });
         let merchantHost = new URL(page.url()).hostname;
-        const initialOriginRefusal = trustedMerchantOriginRefusal(options, page.url());
-        if (initialOriginRefusal) {
+        let initialOriginVerdict = trustedMerchantOriginVerdict(options, page.url());
+        if (initialOriginVerdict?.code === 'trusted_origin_undeclared' &&
+            options.trustedMerchantIdentity) {
+            // #8669: the trusted path never got the Shopify primary-domain proof the
+            // generic path has carried since #8469, so every declared-business
+            // storefront that Shopify serves from its primary domain refused here.
+            const aliasOrigin = trustedShopifyAliasOrigin({
+                allowedOrigins: options.trustedMerchantIdentity.allowedOrigins,
+                initialUrl: options.url,
+                finalUrl: page.url(),
+                redirects: await navigationRedirectEvidence(navigationResponse),
+            });
+            if (aliasOrigin) {
+                evidence.step('note', {
+                    kind: 'shopify-primary-domain-alias',
+                    trusted: true,
+                    continuationHost: new URL(options.url).hostname,
+                    checkoutHost: new URL(aliasOrigin).hostname,
+                    shopifyProof: shopifyPrimaryDomainAlias({
+                        mandateHost: new URL(options.url).hostname,
+                        initialUrl: options.url,
+                        finalUrl: page.url(),
+                        redirects: await navigationRedirectEvidence(navigationResponse),
+                    }) !== null,
+                });
+                options.trustedMerchantIdentity = Object.freeze({
+                    ...options.trustedMerchantIdentity,
+                    allowedOrigins: Object.freeze([
+                        ...options.trustedMerchantIdentity.allowedOrigins,
+                        aliasOrigin,
+                    ]),
+                });
+                initialOriginVerdict = trustedMerchantOriginVerdict(options, page.url());
+            }
+        }
+        if (initialOriginVerdict) {
             evidence.step('mandate-verdict', {
                 phase: 'trusted-origin',
                 ok: false,
-                reason: initialOriginRefusal,
+                reason: initialOriginVerdict.reason,
+                code: initialOriginVerdict.code,
             });
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return {
                 status: 'finished',
-                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, initialOriginRefusal),
+                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, initialOriginVerdict.reason, undefined, undefined, initialOriginVerdict.code),
             };
         }
         if (!options.trustedMerchantIdentity) {
@@ -854,7 +974,7 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return {
                 status: 'finished',
-                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, preFill.reason),
+                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, preFill.reason, undefined, undefined, preFill.code),
             };
         }
         // Payer-chosen amount (Stripe payment links): an empty customUnitAmount
@@ -973,19 +1093,21 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
             }
             await settle(page);
             const prefillHost = new URL(page.url()).hostname;
-            const trustedPrefillRefusal = trustedMerchantOriginRefusal(options, page.url());
-            if (trustedPrefillRefusal || prefillHost !== merchantHost) {
-                const reason = trustedPrefillRefusal ??
+            const trustedPrefillVerdict = trustedMerchantOriginVerdict(options, page.url());
+            if (trustedPrefillVerdict || prefillHost !== merchantHost) {
+                const reason = trustedPrefillVerdict?.reason ??
                     `merchant changed during contact prefill: ${merchantHost} -> ${prefillHost}`;
+                const code = trustedPrefillVerdict?.code ?? 'merchant_host_mismatch';
                 evidence.step('mandate-verdict', {
                     phase: 'contact-prefill',
                     ok: false,
                     reason,
+                    code,
                 });
                 evidence.setSnapshotSummary(await snapshotSummary(page));
                 return {
                     status: 'finished',
-                    result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, reason),
+                    result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, reason, undefined, undefined, code),
                 };
             }
             detected = await detectFields(page);
@@ -1030,17 +1152,18 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
         // whichever declared origin is actually on-screen only after those
         // credential-free steps, then require that exact origin for approval,
         // credential fill, and submit.
-        const reviewOriginRefusal = trustedMerchantOriginRefusal(options, page.url());
-        if (reviewOriginRefusal) {
+        const reviewOriginVerdict = trustedMerchantOriginVerdict(options, page.url());
+        if (reviewOriginVerdict) {
             evidence.step('mandate-verdict', {
                 phase: 'review-origin',
                 ok: false,
-                reason: reviewOriginRefusal,
+                reason: reviewOriginVerdict.reason,
+                code: reviewOriginVerdict.code,
             });
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return {
                 status: 'finished',
-                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, reviewOriginRefusal),
+                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, reviewOriginVerdict.reason, undefined, undefined, reviewOriginVerdict.code),
             };
         }
         merchantHost = new URL(page.url()).hostname;
@@ -1052,7 +1175,7 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return {
                 status: 'finished',
-                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, facts.detail),
+                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, facts.detail, undefined, undefined, facts.code),
             };
         }
         const verdict = checkMandate(mandateForPage(options, page.url()), {
@@ -1065,7 +1188,7 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return {
                 status: 'finished',
-                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, verdict.reason),
+                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, verdict.reason, undefined, undefined, verdict.code),
             };
         }
         // Multi-step pages may expose the final submit control in a hidden section
@@ -1156,15 +1279,16 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
         // the credential boundary. A changed checkout requires a fresh review.
         await waitForStableDom(page);
         const merchantHost = new URL(page.url()).hostname;
-        const approvalOriginRefusal = trustedMerchantOriginRefusal(options, page.url(), checkout.review.merchantOrigin);
-        if (approvalOriginRefusal) {
+        const approvalOriginVerdict = trustedMerchantOriginVerdict(options, page.url(), checkout.review.merchantOrigin);
+        if (approvalOriginVerdict) {
             evidence.step('mandate-verdict', {
                 phase: 'approval-origin',
                 ok: false,
-                reason: approvalOriginRefusal,
+                reason: approvalOriginVerdict.reason,
+                code: approvalOriginVerdict.code,
             });
             evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, approvalOriginRefusal);
+            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, approvalOriginVerdict.reason, undefined, undefined, approvalOriginVerdict.code);
         }
         const preFill = checkMandatePreFill(mandateForPage(options, page.url()), {
             merchantHost,
@@ -1174,7 +1298,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
         if (!preFill.ok) {
             evidence.step('approval', { approved: false, reviewId: checkout.review.id });
             evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, preFill.reason);
+            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, preFill.reason, undefined, undefined, preFill.code);
         }
         const approvedFacts = await readTransactionFacts(page, options, 'approval');
         recordTransactionFacts(evidence, 'approval', approvedFacts);
@@ -1186,7 +1310,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             });
             evidence.step('approval', { approved: false, reviewId: checkout.review.id });
             evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, approvedFacts.detail);
+            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, approvedFacts.detail, undefined, undefined, approvedFacts.code);
         }
         const approvalVerdict = checkMandate(mandateForPage(options, page.url()), {
             merchantHost,
@@ -1197,7 +1321,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
         if (!approvalVerdict.ok) {
             evidence.step('approval', { approved: false, reviewId: checkout.review.id });
             evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, approvalVerdict.reason);
+            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, approvalVerdict.reason, undefined, undefined, approvalVerdict.code);
         }
         const changedAtApproval = reviewChangeReason(checkout.review, merchantHost, approvedFacts, exactOrigin(page.url()) ?? undefined);
         if (changedAtApproval) {
@@ -1207,7 +1331,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
                 reason: changedAtApproval,
             });
             evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, changedAtApproval);
+            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, changedAtApproval, undefined, undefined, 'review_facts_changed');
         }
         // Revalidate the same future target before credential minting. This may be
         // hidden on a multi-step checkout; the final lookup after reveal requires
@@ -1221,7 +1345,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
                 reason: submitChangedAtApproval,
             });
             evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitChangedAtApproval);
+            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitChangedAtApproval, undefined, undefined, 'review_facts_changed');
         }
         if (opts.mode === 'submit' && !approvalSubmit) {
             const reason = 'no submit target was available for human review';
@@ -1392,18 +1516,19 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
                 reason: submitFacts.reason,
             });
             evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitFacts.detail);
+            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitFacts.detail, undefined, undefined, submitFacts.code);
         }
         const submitMerchantHost = new URL(page.url()).hostname;
-        const submitOriginRefusal = trustedMerchantOriginRefusal(options, page.url(), checkout.review.merchantOrigin);
-        if (submitOriginRefusal) {
+        const submitOriginVerdict = trustedMerchantOriginVerdict(options, page.url(), checkout.review.merchantOrigin);
+        if (submitOriginVerdict) {
             evidence.step('mandate-verdict', {
                 phase: 'pre-submit-origin',
                 ok: false,
-                reason: submitOriginRefusal,
+                reason: submitOriginVerdict.reason,
+                code: submitOriginVerdict.code,
             });
             evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitOriginRefusal);
+            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitOriginVerdict.reason, undefined, undefined, submitOriginVerdict.code);
         }
         const verdict = checkMandate(mandateForPage(options, page.url()), {
             merchantHost: submitMerchantHost,
@@ -1413,7 +1538,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
         evidence.step('mandate-verdict', { phase: 'pre-submit', ...verdict });
         if (!verdict.ok) {
             evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, verdict.reason);
+            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, verdict.reason, undefined, undefined, verdict.code);
         }
         const changedBeforeSubmit = reviewChangeReason(checkout.review, submitMerchantHost, submitFacts, exactOrigin(page.url()) ?? undefined);
         if (changedBeforeSubmit) {
@@ -1423,7 +1548,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
                 reason: changedBeforeSubmit,
             });
             evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, changedBeforeSubmit);
+            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, changedBeforeSubmit, undefined, undefined, 'review_facts_changed');
         }
         const submit = await findSubmit(page);
         const submitChangedBeforeClick = submitTargetChangeReason(checkout.review, submit);
@@ -1434,7 +1559,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
                 reason: submitChangedBeforeClick,
             });
             evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitChangedBeforeClick);
+            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitChangedBeforeClick, undefined, undefined, 'review_facts_changed');
         }
         if (!adapterFillOk) {
             evidence.setSnapshotSummary(await snapshotSummary(page));

package/dist/checkout-engine/index.d.ts

@@ -1,5 +1,7 @@
 export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, type CliStartMandateInput, type CliMandateFacts, type CliEngineDeps, type ReceiptWriteObservation, CheckoutReviewRefusedError, CardMandateActivationError, classifyServerIntentFailure, type CardMandateActivationFacts, type CliResumeMandateInput, } from './cli-engine.js';
-export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
+export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, trustedShopifyAliasOrigin, } from './executor.js';
+export { MANDATE_REFUSAL_CODES } from './mandate.js';
+export type { MandateRefusalCode, MandateVerdict } from './mandate.js';
 export type { CheckoutResult, CheckoutReview, CheckoutOutcome, CheckoutFailureCode, CheckoutRoute, } from './executor.js';
 export { readConfirmedMerchants, type ConfirmedMerchant, type ConfirmedCharge, } from './confirmed-merchants.js';
 export { KNOWN_MERCHANT_IDENTITIES, type MerchantIdentity } from './known-merchants.js';

package/dist/checkout-engine/index.js

@@ -2,7 +2,8 @@
 // consumes createCliCheckoutEngine() through a structural seam; the core engine
 // primitives are re-exported for direct/embedded use.
 export { createCliCheckoutEngine, CheckoutReviewRefusedError, CardMandateActivationError, classifyServerIntentFailure, } from './cli-engine.js';
-export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
+export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, trustedShopifyAliasOrigin, } from './executor.js';
+export { MANDATE_REFUSAL_CODES } from './mandate.js';
 export { readConfirmedMerchants, } from './confirmed-merchants.js';
 export { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';
 export { RECEIPT_DIR } from './receipt-dir.js';

package/dist/checkout-engine/mandate.d.ts

@@ -15,11 +15,19 @@ export type MandatePreFillContext = {
     currency?: string | null;
     now?: Date;
 };
+/**
+ * Bounded, machine-readable reason a review or pay was refused by the mandate
+ * or trusted-identity gate. Callers branch on this instead of parsing the
+ * human-readable reason sentence.
+ */
+export type MandateRefusalCode = 'mandate_missing' | 'mandate_malformed' | 'mandate_expired' | 'currency_mismatch' | 'merchant_host_mismatch' | 'currency_unreadable' | 'amount_invalid' | 'amount_over_cap' | 'amount_unreadable' | 'trusted_handoff_expired' | 'trusted_origin_insecure' | 'trusted_origin_changed' | 'trusted_origin_undeclared' | 'review_facts_changed';
+export declare const MANDATE_REFUSAL_CODES: ReadonlySet<MandateRefusalCode>;
 export type MandateVerdict = {
     ok: true;
 } | {
     ok: false;
     reason: string;
+    code: MandateRefusalCode;
 };
 export declare function checkMandatePreFill(mandate: Mandate | null | undefined, ctx: MandatePreFillContext): MandateVerdict;
 export declare function checkMandate(mandate: Mandate | null | undefined, ctx: MandateContext): MandateVerdict;

package/dist/checkout-engine/mandate.js

@@ -17,36 +17,61 @@
 // All amounts are integer minor units (e.g. cents for USD). There is no
 // floating-point money here on purpose; the executor reads a minor-unit total
 // and compares integers.
+export const MANDATE_REFUSAL_CODES = new Set([
+    'mandate_missing',
+    'mandate_malformed',
+    'mandate_expired',
+    'currency_mismatch',
+    'merchant_host_mismatch',
+    'currency_unreadable',
+    'amount_invalid',
+    'amount_over_cap',
+    'amount_unreadable',
+    'trusted_handoff_expired',
+    'trusted_origin_insecure',
+    'trusted_origin_changed',
+    'trusted_origin_undeclared',
+    'review_facts_changed',
+]);
 function isInteger(n) {
     return typeof n === 'number' && Number.isInteger(n);
 }
 // Pre-fill gate: everything knowable before a credential is minted.
 export function checkMandatePreFill(mandate, ctx) {
     if (!mandate) {
-        return { ok: false, reason: 'no mandate provided' };
+        return { ok: false, reason: 'no mandate provided', code: 'mandate_missing' };
     }
     // Structural validation: a malformed mandate must never authorize a spend.
     if (!isInteger(mandate.maxAmountMinor) || mandate.maxAmountMinor <= 0) {
-        return { ok: false, reason: 'mandate maxAmountMinor must be a positive integer (minor units)' };
+        return {
+            ok: false,
+            reason: 'mandate maxAmountMinor must be a positive integer (minor units)',
+            code: 'mandate_malformed',
+        };
     }
     if (!mandate.currency) {
-        return { ok: false, reason: 'mandate is missing a currency' };
+        return { ok: false, reason: 'mandate is missing a currency', code: 'mandate_malformed' };
     }
     if (!mandate.expiresAt) {
-        return { ok: false, reason: 'mandate is missing an expiry' };
+        return { ok: false, reason: 'mandate is missing an expiry', code: 'mandate_malformed' };
     }
     const expiry = new Date(mandate.expiresAt);
     if (Number.isNaN(expiry.getTime())) {
-        return { ok: false, reason: `mandate expiry is not a valid date: ${mandate.expiresAt}` };
+        return {
+            ok: false,
+            reason: `mandate expiry is not a valid date: ${mandate.expiresAt}`,
+            code: 'mandate_malformed',
+        };
     }
     const now = ctx.now ?? new Date();
     if (expiry.getTime() <= now.getTime()) {
-        return { ok: false, reason: `mandate expired at ${mandate.expiresAt}` };
+        return { ok: false, reason: `mandate expired at ${mandate.expiresAt}`, code: 'mandate_expired' };
     }
     if (ctx.currency && mandate.currency.toUpperCase() !== ctx.currency.toUpperCase()) {
         return {
             ok: false,
             reason: `currency mismatch: mandate ${mandate.currency} vs transaction ${ctx.currency}`,
+            code: 'currency_mismatch',
         };
     }
     if (mandate.merchantHost &&
@@ -54,6 +79,7 @@ export function checkMandatePreFill(mandate, ctx) {
         return {
             ok: false,
             reason: `merchant host mismatch: mandate ${mandate.merchantHost} vs checkout ${ctx.merchantHost}`,
+            code: 'merchant_host_mismatch',
         };
     }
     return { ok: true };
@@ -65,20 +91,29 @@ export function checkMandate(mandate, ctx) {
     if (!pre.ok)
         return pre;
     if (!mandate)
-        return { ok: false, reason: 'no mandate provided' };
+        return { ok: false, reason: 'no mandate provided', code: 'mandate_missing' };
     // The pre-fill phase skips the currency check when none is asserted yet;
     // here the resolved currency is mandatory.
     if (!ctx.currency) {
-        return { ok: false, reason: 'transaction currency could not be determined' };
+        return {
+            ok: false,
+            reason: 'transaction currency could not be determined',
+            code: 'currency_unreadable',
+        };
     }
     // Transaction amount must be a clean integer minor-unit value.
     if (!isInteger(ctx.amountMinor) || ctx.amountMinor < 0) {
-        return { ok: false, reason: 'transaction amount is not a non-negative integer (minor units)' };
+        return {
+            ok: false,
+            reason: 'transaction amount is not a non-negative integer (minor units)',
+            code: 'amount_invalid',
+        };
     }
     if (ctx.amountMinor > mandate.maxAmountMinor) {
         return {
             ok: false,
             reason: `amount ${ctx.amountMinor} exceeds mandate cap ${mandate.maxAmountMinor} (minor units)`,
+            code: 'amount_over_cap',
         };
     }
     return { ok: true };