@envarai/envarpay 0.2.0-alpha.3 → 0.2.0-alpha.5

package/dist/commerce/buyer.d.ts

@@ -3,7 +3,7 @@ import type { PaymentPayload, PaymentRequirements, SettleResponse } from '@x402/
 import { type BuyerPolicy, type Input, type StandardA2APeer } from './types.js';
 import { CredentialVault } from './vault.js';
 import { BuyerStore, type BuyerQuote } from './buyer-store.js';
-import { type MppBuyerOptions, type MppReceipt } from './mpp-client.js';
+import { type MppAuthenticationAction, type MppBuyerOptions, type MppReceipt } from './mpp-client.js';
 export interface BuyerPreviewInput {
     cardUrl: string;
     messageId: string;
@@ -15,6 +15,10 @@ export interface BuyerConfirmInput {
     quoteToken: string;
     messageId: string;
 }
+export interface BuyerAuthentication {
+    purchaseId: string;
+    action: MppAuthenticationAction | null;
+}
 export interface CommerceBuyerOptions {
     policy: BuyerPolicy;
     store: BuyerStore;
@@ -114,6 +118,8 @@ export declare class CommerceBuyer {
     private verifyMpp;
     private replayMpp;
     private recoverMpp;
+    /** Owner-only provider read. No replay, token creation, reservation or payment transition. */
+    authentication(caller: string, id: string): Promise<BuyerAuthentication>;
     private assertCurrentPolicy;
     confirm(caller: string, input: BuyerConfirmInput): Promise<BuyerSnapshot>;
     private exclusive;

package/dist/commerce/buyer.js

@@ -10,7 +10,7 @@ import addFormatsImport from 'ajv-formats';
 import { atomic, digest, loadBuyerPolicy, validateUrl } from './config.js';
 import { CommerceError } from './types.js';
 import { Challenge, Receipt, PaymentRequest } from 'mppx';
-import { assertMppDigest, prepareMppCredential, publicMppReceipt, validateMppCredential } from './mpp-client.js';
+import { assertMppDigest, isStripeTestPaymentMethod, prepareMppCredential, publicMppReceipt, validateMppCredential } from './mpp-client.js';
 const COMMERCE = 'urn:envarpay:commerce:1', QUOTE = 'urn:envarpay:quote:1';
 const addFormats = addFormatsImport;
 async function bounded(response, limit = 4 * 1024 * 1024) {
@@ -108,7 +108,7 @@ export class CommerceBuyer {
         this.fetchImpl = options.fetchImpl ?? fetch;
         if (this.policy.peers.some(p => p.protocol === 'x402') && (!options.signer || !/^0x[0-9a-fA-F]{40}$/.test(options.signer.address) || BigInt(options.signer.address) === 0n || !options.verifyReceipt))
             throw new CommerceError('invalid_signer', 'x402 peers require an EVM wallet and independent receipt verifier');
-        if (this.policy.peers.some(p => p.protocol === 'mpp') && (!options.mpp || !options.mpp.payer || !/^pm_[A-Za-z0-9]+$/.test(options.mpp.paymentMethod) || !['test', 'live'].includes(options.mpp.mode) || typeof options.mpp.createToken !== 'function' || typeof options.mpp.verifyReceipt !== 'function'))
+        if (this.policy.peers.some(p => p.protocol === 'mpp') && (!options.mpp || !options.mpp.payer || !(/^pm_[A-Za-z0-9]+$/.test(options.mpp.paymentMethod) || (options.mpp.mode === 'test' && options.mpp.issuance === 'test-helper' && isStripeTestPaymentMethod(options.mpp.paymentMethod))) || !['test', 'live'].includes(options.mpp.mode) || typeof options.mpp.createToken !== 'function' || typeof options.mpp.verifyReceipt !== 'function'))
             throw new CommerceError('mpp_provider_missing', 'MPP peers require explicit token creation and independent provider verification');
         for (const peer of this.policy.peers)
             if (!(peer.mode === 'standard-a2a' && peer.authentication === 'none') && (!options.peerTokens[peer.id] || options.peerTokens[peer.id].length < 16))
@@ -485,6 +485,26 @@ export class CommerceBuyer {
             return this.snapshot(this.options.store.update(record.id, { state: 'unknown', errorCode: error instanceof CommerceError ? error.code : 'mpp_reconciliation_pending' }));
         }
     }
+    /** Owner-only provider read. No replay, token creation, reservation or payment transition. */
+    async authentication(caller, id) {
+        const record = this.record(caller, id);
+        if (record.protocol !== 'mpp')
+            throw new CommerceError('mpp_authentication_unavailable', 'Original purchase does not use MPP');
+        this.assertCurrentPolicy(record, false);
+        if (!record.tokenOperationId || record.paymentState === 'confirmed')
+            return { purchaseId: id, action: null };
+        const provider = this.options.mpp;
+        if (!provider?.getAuthentication)
+            throw new CommerceError('mpp_authentication_unavailable', 'Configured provider does not support customer authentication');
+        const action = await provider.getAuthentication({ purchaseId: record.id, quote: structuredClone(record.quote), mode: record.mppMode, operationId: record.tokenOperationId });
+        if (!action)
+            return { purchaseId: id, action: null };
+        if (action.type !== 'use_stripe_sdk' || typeof action.hashedValue !== 'string' || !action.hashedValue || action.hashedValue.length > 16384 ||
+            typeof action.publishableKey !== 'string' || !new RegExp(`^pk_${record.mppMode}_[A-Za-z0-9]{1,256}$`).test(action.publishableKey)) {
+            throw new CommerceError('stripe_spt_action_unsupported', 'Provider returned an unsupported or mismatched customer action');
+        }
+        return { purchaseId: id, action: { type: 'use_stripe_sdk', hashedValue: action.hashedValue, publishableKey: action.publishableKey } };
+    }
     assertCurrentPolicy(record, signing) {
         const peer = this.peer(record.cardUrl);
         if (peer.id !== record.peerId || this.endpoint(peer) !== record.endpoint || peer.currency !== record.quote.currency || peer.recipient !== record.quote.recipient || (peer.protocol !== 'free' && atomic(record.quote.amount) > atomic(peer.maxPerPurchase)) || record.quote.payer !== (peer.protocol === 'free' ? record.caller : peer.protocol === 'mpp' ? this.options.mpp?.payer : this.options.signer?.address.toLowerCase()) || (record.protocol === 'mpp' && record.mppMode !== this.options.mpp?.mode))

package/dist/commerce/cli.js

@@ -123,15 +123,36 @@ async function run() {
                 throw new CommerceError('buyer_key', 'Signer file must contain one 32-byte 0x-prefixed private key');
             signer = privateKeyToAccount(key);
         }
-        if (needsMpp && !secrets.mppAdapterModule)
-            throw new CommerceError('mpp_adapter_module', 'MPP peers require an explicit local adapter module for authorized funding and receipt verification');
-        const mpp = needsMpp ? await loadMppAdapter(secrets.mppAdapterModule) : undefined;
+        if (secrets.mppAdapterModule && secrets.mppStripe)
+            throw new CommerceError('mpp_configuration', 'Choose the built-in Stripe issuer or one explicit adapter module');
+        if (needsMpp && !secrets.mppAdapterModule && !secrets.mppStripe)
+            throw new CommerceError('mpp_configuration', 'MPP peers require a configured Stripe issuer or explicit authorized funding adapter');
+        const buyerVault = secrets.vaultKeyFile ? new CredentialVault(join(dirname(values.state), 'buyer-authorizations'), privateFile(secrets.vaultKeyFile)) : undefined;
+        let mpp;
+        if (needsMpp && secrets.mppStripe) {
+            const configured = secrets.mppStripe;
+            if (!configured.secretKeyFile || !configured.sellers || typeof configured.sellers !== 'object' || Array.isArray(configured.sellers))
+                throw new CommerceError('mpp_configuration', 'Stripe issuer and seller read credentials must use private key files');
+            const { createStripeMppBuyer } = await import('./stripe-issuer.js');
+            const adapter = createStripeMppBuyer({
+                payer: configured.payer, mode: configured.mode, issuerAccountId: configured.issuerAccountId,
+                secretKey: privateFile(configured.secretKeyFile).toString('utf8').trim(), paymentMethod: configured.paymentMethod,
+                ...(configured.publishableKey !== undefined ? { publishableKey: configured.publishableKey } : {}),
+                sellers: Object.fromEntries(Object.entries(configured.sellers).map(([id, seller]) => [id, { accountId: seller.accountId, secretKey: privateFile(seller.secretKeyFile).toString('utf8').trim() }])),
+                ...(configured.issuance ? { issuance: configured.issuance } : {}), ...(configured.returnUrl ? { returnUrl: configured.returnUrl } : {}),
+            }, { statePath: values.state + '.stripe-issuer.sqlite3', vault: buyerVault });
+            closers.push(() => adapter.close());
+            await adapter.assertReady();
+            mpp = adapter;
+        }
+        else if (needsMpp)
+            mpp = await loadMppAdapter(secrets.mppAdapterModule);
         const { BuyerStore } = await import('./buyer-store.js');
         const { CommerceBuyer } = await import('./buyer.js');
         const { BuyerManagement, listenBuyerManagement } = await import('./management.js');
         const store = new BuyerStore(values.state);
         closers.push(() => store.close());
-        const buyer = new CommerceBuyer({ policy, store, vault: secrets.vaultKeyFile ? new CredentialVault(join(dirname(values.state), 'buyer-authorizations'), privateFile(secrets.vaultKeyFile)) : undefined,
+        const buyer = new CommerceBuyer({ policy, store, vault: buyerVault,
             signer, mpp, peerTokens: secrets.peerTokens, peerEndpoints: secrets.peerEndpoints,
             ...(needsEvm ? { verifyReceipt: evmReceiptVerifier(secrets.rpcUrls), ...evmSettlementRecovery(secrets.rpcUrls) } : {}) });
         closers.push(() => buyer.stop());

package/dist/commerce/client-runtime.d.ts

@@ -4,5 +4,5 @@ export * from './buyer.js';
 export * from './management.js';
 export * from './vault.js';
 export * from './chain.js';
-export type { MppBuyerOptions, MppTokenOperation, MppVerificationContext, MppReceipt } from './mpp-client.js';
+export type { MppAuthenticationAction, MppBuyerOptions, MppTokenOperation, MppVerificationContext, MppReceipt } from './mpp-client.js';
 export * from './peer-proxy.js';

package/dist/commerce/config.d.ts

@@ -2,6 +2,8 @@ import { type BuyerPolicy, type CommerceConfig, type PaymentProfile } from './ty
 export declare function atomic(value: string): bigint;
 export declare function validateUrl(value: string, allowPrivate?: boolean): URL;
 export declare function currencyOf(profile: PaymentProfile): string;
+/** Stripe documents sandbox Business Profile IDs as profile_test_<opaque id>. */
+export declare function isStripeProfileId(value: unknown): value is string;
 export declare function digest(value: unknown): string;
 export declare function loadCommerceConfig(value: unknown): CommerceConfig;
 export declare function loadBuyerPolicy(value: unknown): BuyerPolicy;

package/dist/commerce/config.js

@@ -45,6 +45,10 @@ export function validateUrl(value, allowPrivate = false) {
 export function currencyOf(profile) {
     return profile.adapter === 'x402' ? `${profile.network}/erc20:${profile.asset.toLowerCase()}` : profile.currency;
 }
+/** Stripe documents sandbox Business Profile IDs as profile_test_<opaque id>. */
+export function isStripeProfileId(value) {
+    return typeof value === 'string' && /^profile_(?:test_)?[A-Za-z0-9]{1,120}$/.test(value);
+}
 function assertJson(value) {
     if (typeof value === 'number' && (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))))
         throw new CommerceError('unsafe_json_number', 'Use strings for integers outside the safe JSON number range');
@@ -172,7 +176,7 @@ export function loadBuyerPolicy(value) {
                 throw new CommerceError('invalid_recipient', 'x402 peers require a nonzero EVM recipient and USDC asset');
             peer.recipient = peer.recipient.toLowerCase();
         }
-        else if (peer.currency !== 'usd' || !/^profile_[A-Za-z0-9]+$/.test(peer.recipient))
+        else if (peer.currency !== 'usd' || !isStripeProfileId(peer.recipient))
             throw new CommerceError('invalid_recipient', 'MPP peers require USD and a verified Stripe merchant profile');
         const limit = limits.get(peer.currency);
         if (limit === undefined || atomic(peer.maxPerPurchase) > limit)

package/dist/commerce/management.js

@@ -77,9 +77,11 @@ export class BuyerManagement {
                     throw new CommerceError('invalid_request', 'Confirmation identifiers must be strings');
                 return Response.json(await this.options.buyer.confirm(caller, body), { headers });
             }
-            const match = /^\/management\/v1\/purchases\/([0-9a-f-]{36})(\/(?:recover|continue))?$/.exec(url.pathname);
+            const match = /^\/management\/v1\/purchases\/([0-9a-f-]{36})(\/(?:recover|continue|authentication))?$/.exec(url.pathname);
             if (match && request.method === 'GET' && !match[2])
                 return Response.json(this.options.buyer.get(caller, match[1]), { headers });
+            if (match && request.method === 'GET' && match[2] === '/authentication')
+                return Response.json(await this.options.buyer.authentication(caller, match[1]), { headers });
             if (match && request.method === 'POST' && match[2] === '/continue') {
                 const body = await jsonBody(request);
                 exactKeys(body, ['messageId', 'input']);

package/dist/commerce/mpp-client.d.ts

@@ -28,16 +28,27 @@ export interface MppVerificationContext {
     mode: 'test' | 'live';
     operationId: string;
 }
+export interface MppAuthenticationAction {
+    type: 'use_stripe_sdk';
+    hashedValue: string;
+    publishableKey: string;
+}
+/** Explicit official sandbox aliases, never accepted for live funding. */
+export declare const STRIPE_TEST_PAYMENT_METHODS: readonly ["pm_card_visa", "pm_card_visa_chargeDeclined", "pm_card_authenticationRequired"];
+export declare function isStripeTestPaymentMethod(value: string): boolean;
 export interface MppBuyerOptions {
     /** Stable private buyer/PSP identity; never inferred from seller metadata. */
     payer: string;
     mode: 'test' | 'live';
     paymentMethod: string;
+    issuance?: 'issued-token' | 'test-helper';
     createToken: (operation: MppTokenOperation) => Promise<string>;
     /** Read the original operation only; never create another SPT on absence. */
     recoverToken?: (operation: MppTokenOperation) => Promise<string | undefined>;
     /** Independently read provider state and match account/mode/merchant/amount/order. */
     verifyReceipt: (receipt: MppReceipt, context: MppVerificationContext) => Promise<boolean>;
+    /** Read only, for the owner of this exact original purchase. Never completes payment. */
+    getAuthentication?: (context: MppVerificationContext) => Promise<MppAuthenticationAction | undefined>;
 }
 export interface SavedMppAuthorization {
     protocol: 'mpp';

package/dist/commerce/mpp-client.js

@@ -3,6 +3,11 @@ import { Mppx } from 'mppx/client';
 import { charge } from 'mppx/stripe/client';
 import { createHash } from 'node:crypto';
 import { CommerceError } from './types.js';
+/** Explicit official sandbox aliases, never accepted for live funding. */
+export const STRIPE_TEST_PAYMENT_METHODS = ['pm_card_visa', 'pm_card_visa_chargeDeclined', 'pm_card_authenticationRequired'];
+export function isStripeTestPaymentMethod(value) {
+    return STRIPE_TEST_PAYMENT_METHODS.includes(value);
+}
 /** Native SDK preparation only; no fetch polyfill or automatic payment retry. */
 export async function prepareMppCredential(challenge, paymentMethod, createToken) {
     const client = Mppx.create({ polyfill: false, maxPaymentRetries: 0, methods: [charge({ paymentMethod, createToken })] });

package/dist/commerce/mpp-runtime.d.ts

@@ -1,3 +1,4 @@
 /** Opt-in MPP server adapter. Account eligibility is checked at startup. */
 export * from './mpp.js';
 export * from './stripe-provider.js';
+export * from './stripe-issuer.js';

package/dist/commerce/mpp-runtime.js

@@ -1,3 +1,4 @@
 /** Opt-in MPP server adapter. Account eligibility is checked at startup. */
 export * from './mpp.js';
 export * from './stripe-provider.js';
+export * from './stripe-issuer.js';

package/dist/commerce/stripe-issuer.d.ts

@@ -0,0 +1,41 @@
+import { CredentialVault } from './vault.js';
+import type { MppBuyerOptions } from './mpp-client.js';
+/** Buyer and seller use the same public preview, independently of mppx internals. */
+export declare const STRIPE_ISSUER_API_VERSION = "2026-09-30.preview";
+export interface StripeSellerReadBinding {
+    accountId: string;
+    /** Account-scoped read credential for account, profile and PaymentIntent reads. */
+    secretKey: string;
+}
+export interface StripeMppBuyerConfig {
+    payer: string;
+    mode: 'test' | 'live';
+    issuerAccountId: string;
+    secretKey: string;
+    /** Issuer's Stripe.js key; optional until customer authentication is needed. */
+    publishableKey?: string;
+    /** Previously owner-authorized PaymentMethod; this adapter never collects card data. */
+    paymentMethod: string;
+    sellers: Readonly<Record<string, StripeSellerReadBinding>>;
+    returnUrl?: string;
+    /** Real Stripe test infrastructure, selected explicitly; never a live fallback. */
+    issuance?: 'issued-token' | 'test-helper';
+}
+export interface StripeMppBuyerRuntime {
+    statePath: string;
+    vault: CredentialVault;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+export interface StripeAuthenticationAction {
+    type: 'use_stripe_sdk';
+    hashedValue: string;
+}
+export interface StripeMppBuyerAdapter extends MppBuyerOptions {
+    assertReady(): Promise<void>;
+    close(): void;
+    /** Private owner-only API. Pass this value directly to Stripe.js, never logs. */
+    authenticationAction(operationId: string): Promise<StripeAuthenticationAction | undefined>;
+}
+/** Official SPT issuer with exact scope and original-ID-only recovery. No automatic funding. */
+export declare function createStripeMppBuyer(input: StripeMppBuyerConfig, runtime: StripeMppBuyerRuntime): StripeMppBuyerAdapter;

package/dist/commerce/stripe-issuer.js

@@ -0,0 +1,351 @@
+import { DatabaseSync } from 'node:sqlite';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { Challenge } from 'mppx';
+import { digest, isStripeProfileId } from './config.js';
+import { CommerceError } from './types.js';
+import { STRIPE_MPP_API_VERSION } from './stripe-provider.js';
+import { isStripeTestPaymentMethod } from './mpp-client.js';
+/** Buyer and seller use the same public preview, independently of mppx internals. */
+export const STRIPE_ISSUER_API_VERSION = STRIPE_MPP_API_VERSION;
+const ACCOUNT = /^acct_[A-Za-z0-9]{1,128}$/;
+const TOKEN = /^spt_[A-Za-z0-9_]{1,200}$/;
+const PAYMENT_METHOD = /^pm_[A-Za-z0-9]{1,128}$/;
+const OPERATION = /^[A-Za-z0-9_-]{1,200}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+/** Durable private references only; exact requests and tokens live in CredentialVault. */
+class IssuerLedger {
+    db;
+    owner;
+    closed = false;
+    constructor(path) {
+        if (typeof path !== 'string' || !path.trim() || path === ':memory:')
+            throw new CommerceError('stripe_issuer_state', 'SPT issuance requires a durable private ledger');
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        this.owner = new DatabaseSync(path + '.owner.sqlite3');
+        chmodSync(path + '.owner.sqlite3', 0o600);
+        try {
+            this.owner.exec('PRAGMA busy_timeout=0; BEGIN EXCLUSIVE');
+        }
+        catch {
+            this.owner.close();
+            throw new CommerceError('store_locked', 'Stripe issuer ledger already has an active process');
+        }
+        try {
+            this.db = new DatabaseSync(path);
+            chmodSync(path, 0o600);
+            this.db.exec(`PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;
+        CREATE TABLE IF NOT EXISTS stripe_issuer_meta(version INTEGER NOT NULL);
+        INSERT INTO stripe_issuer_meta SELECT 1 WHERE NOT EXISTS(SELECT 1 FROM stripe_issuer_meta);
+        CREATE TABLE IF NOT EXISTS stripe_issuer_operations(
+          operation_id TEXT PRIMARY KEY, idempotency_key TEXT NOT NULL UNIQUE, purchase_id TEXT NOT NULL UNIQUE,
+          fingerprint TEXT NOT NULL, request_ref TEXT NOT NULL, token_ref TEXT,
+          created_at INTEGER NOT NULL
+        );`);
+            if (this.db.prepare('SELECT version FROM stripe_issuer_meta').get()?.version !== 1)
+                throw new CommerceError('store_version', 'Unsupported Stripe issuer ledger version');
+        }
+        catch (error) {
+            this.db?.close();
+            this.owner.close();
+            throw error;
+        }
+    }
+    get(id) {
+        const row = this.db.prepare('SELECT * FROM stripe_issuer_operations WHERE operation_id=?').get(id);
+        return row ? { operationId: String(row.operation_id), fingerprint: String(row.fingerprint), requestRef: String(row.request_ref), ...(row.token_ref ? { tokenRef: String(row.token_ref) } : {}) } : undefined;
+    }
+    insert(operation, fingerprint, requestRef, now) {
+        try {
+            this.db.prepare('INSERT INTO stripe_issuer_operations VALUES(?,?,?,?,?,NULL,?)').run(operation.operationId, operation.idempotencyKey, operation.purchaseId, fingerprint, requestRef, now);
+        }
+        catch {
+            throw new CommerceError('stripe_spt_operation_conflict', 'Purchase or idempotency identity already has an original issuer operation');
+        }
+        return this.get(operation.operationId);
+    }
+    token(id, ref) { this.db.prepare('UPDATE stripe_issuer_operations SET token_ref=? WHERE operation_id=? AND token_ref IS NULL').run(ref, id); }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.db.close();
+        this.owner?.exec('ROLLBACK');
+        this.owner?.close();
+    }
+}
+/** Official SPT issuer with exact scope and original-ID-only recovery. No automatic funding. */
+export function createStripeMppBuyer(input, runtime) {
+    const config = structuredClone(input), issuance = config.issuance ?? 'issued-token';
+    const keyValid = (key) => typeof key === 'string' && new RegExp(`^(?:sk|rk)_${config.mode}_[A-Za-z0-9]{1,256}$`).test(key);
+    if (!['test', 'live'].includes(config.mode) || !['issued-token', 'test-helper'].includes(issuance) || !ACCOUNT.test(config.issuerAccountId) || !keyValid(config.secretKey) ||
+        typeof config.payer !== 'string' || !config.payer || config.payer.length > 200 || !config.sellers || !Object.keys(config.sellers).length ||
+        !(PAYMENT_METHOD.test(config.paymentMethod) || (issuance === 'test-helper' && isStripeTestPaymentMethod(config.paymentMethod)))) {
+        throw new CommerceError('stripe_issuer_configuration', 'Explicit Stripe issuer, funding method, seller read bindings and mode are required');
+    }
+    for (const [profile, seller] of Object.entries(config.sellers)) {
+        if (!isStripeProfileId(profile) || (config.mode === 'live' && profile.startsWith('profile_test_')) || !ACCOUNT.test(seller.accountId) || !keyValid(seller.secretKey))
+            throw new CommerceError('stripe_issuer_configuration', 'Seller profile, account and read credential must match the explicit mode');
+    }
+    if (issuance === 'test-helper' && (config.mode !== 'test' || !isStripeTestPaymentMethod(config.paymentMethod) || Object.values(config.sellers).some(s => s.accountId !== config.issuerAccountId))) {
+        throw new CommerceError('stripe_test_helper_configuration', 'Test helper requires an explicitly supported test card and the same configured test seller account');
+    }
+    if (config.publishableKey !== undefined && (typeof config.publishableKey !== 'string' || !new RegExp(`^pk_${config.mode}_[A-Za-z0-9]{1,256}$`).test(config.publishableKey))) {
+        throw new CommerceError('stripe_publishable_key', 'Stripe.js requires an issuer publishable key matching the configured mode');
+    }
+    if (config.returnUrl !== undefined) {
+        let url;
+        try {
+            url = new URL(config.returnUrl);
+        }
+        catch {
+            throw new CommerceError('stripe_return_url', 'Stripe return URL must be an owner-configured HTTPS URL');
+        }
+        if (url.protocol !== 'https:' || url.username || url.password || config.returnUrl.length > 2048)
+            throw new CommerceError('stripe_return_url', 'Stripe return URL must be an owner-configured HTTPS URL');
+    }
+    const ledger = new IssuerLedger(runtime.statePath), vault = runtime.vault;
+    const fetchImpl = runtime.fetchImpl ?? fetch, now = runtime.now ?? Date.now;
+    const inFlight = new Set();
+    async function call(secret, path, body, idempotencyKey) {
+        const headers = new Headers({ Authorization: `Bearer ${secret}`, 'Stripe-Version': STRIPE_ISSUER_API_VERSION });
+        if (body !== undefined)
+            headers.set('Content-Type', 'application/x-www-form-urlencoded');
+        if (idempotencyKey)
+            headers.set('Idempotency-Key', idempotencyKey);
+        let response;
+        try {
+            response = await fetchImpl(`https://api.stripe.com${path}`, { method: body === undefined ? 'GET' : 'POST', headers, ...(body === undefined ? {} : { body }), redirect: 'error', signal: AbortSignal.timeout(20000) });
+        }
+        catch {
+            throw new CommerceError('stripe_transport_unknown', 'Stripe request outcome is unknown; retain the original operation');
+        }
+        const reader = response.body?.getReader();
+        let size = 0;
+        const chunks = [];
+        try {
+            if (reader)
+                for (;;) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    size += value.byteLength;
+                    if (size > 1024 * 1024) {
+                        await reader.cancel();
+                        throw new CommerceError('stripe_response_size', 'Stripe response exceeds limit');
+                    }
+                    chunks.push(value);
+                }
+        }
+        catch (error) {
+            if (error instanceof CommerceError && error.code === 'stripe_response_size')
+                throw error;
+            throw new CommerceError('stripe_transport_unknown', 'Stripe response was interrupted; retain the original operation');
+        }
+        if (!response.ok)
+            throw new CommerceError(response.status === 429 ? 'stripe_rate_limit' : 'stripe_request_failed', `Stripe request failed (HTTP ${response.status})`);
+        let value;
+        try {
+            value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            throw new CommerceError('stripe_response', 'Stripe returned invalid JSON');
+        }
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new CommerceError('stripe_response', 'Stripe returned an invalid object');
+        return value;
+    }
+    async function account(secret, id) {
+        const result = await call(secret, '/v1/account');
+        if (result.id !== id || result.object !== 'account')
+            throw new CommerceError('stripe_account_mismatch', 'Stripe credential does not prove the expected account');
+        return result;
+    }
+    async function sellerReady(profile) {
+        const seller = config.sellers[profile];
+        if (!Object.hasOwn(config.sellers, profile) || !seller)
+            throw new CommerceError('stripe_seller_binding', 'Seller is not in the local read-verification allowlist');
+        const result = await account(seller.secretKey, seller.accountId);
+        if (config.mode === 'live' && (result.charges_enabled !== true || object(result.capabilities).card_payments !== 'active'))
+            throw new CommerceError('stripe_charges_disabled', 'Live seller card payments are not enabled');
+        const ownProfile = await call(seller.secretKey, '/v2/network/business_profiles/me');
+        // Require the documented mode as well as the credential-scoped /me identity.
+        if (ownProfile.id !== profile || ownProfile.object !== 'v2.network.business_profile' || ownProfile.livemode !== (config.mode === 'live'))
+            throw new CommerceError('stripe_profile_mismatch', 'Seller credential does not prove the expected profile and mode');
+        return seller;
+    }
+    function requestFor(operation) {
+        const quote = operation.quote, challenge = operation.challenge;
+        const details = object(challenge?.request?.methodDetails), metadata = object(operation.metadata);
+        const expiry = Math.floor(Date.parse(quote?.expiresAt) / 1000);
+        if (!OPERATION.test(operation.operationId) || operation.idempotencyKey !== operation.operationId || !UUID.test(operation.purchaseId) ||
+            operation.mode !== config.mode || operation.paymentMethod !== config.paymentMethod || operation.currency !== 'usd' || !/^[1-9][0-9]{1,7}$/.test(operation.amount) ||
+            BigInt(operation.amount) < 50n || BigInt(operation.amount) > 99999999n || operation.amount !== quote.amount || quote.currency !== 'usd' || quote.payer !== config.payer ||
+            operation.networkId !== quote.recipient || !isStripeProfileId(operation.networkId) || !Object.hasOwn(config.sellers, operation.networkId) || !Number.isSafeInteger(expiry) || operation.expiresAt !== expiry ||
+            challenge?.method !== 'stripe' || challenge.intent !== 'charge' || challenge.header !== 'Payment-Authorization' || challenge.expires !== quote.expiresAt ||
+            challenge.request.amount !== quote.amount || challenge.request.currency !== 'usd' || challenge.request.recipient !== quote.recipient || challenge.request.externalId !== quote.quoteId ||
+            details.networkId !== quote.recipient || digest(details.metadata ?? {}) !== digest(metadata) ||
+            metadata.envarpay_quote !== quote.quoteId || metadata.envarpay_terms !== quote.termsDigest || typeof metadata.envarpay_order !== 'string' || !UUID.test(metadata.envarpay_order) ||
+            typeof quote.quoteId !== 'string' || quote.quoteId.length > 500 || typeof quote.termsDigest !== 'string' || quote.termsDigest.length > 500 ||
+            Challenge.serialize(challenge).length > 32768)
+            throw new CommerceError('stripe_spt_binding', 'SPT request differs from the frozen purchase or approved funding scope');
+        const body = new URLSearchParams({ payment_method: operation.paymentMethod,
+            'usage_limits[currency]': 'usd', 'usage_limits[max_amount]': operation.amount, 'usage_limits[expires_at]': String(expiry),
+            'shared_metadata[envarpay_operation]': operation.operationId, 'shared_metadata[envarpay_purchase]': operation.purchaseId,
+            'shared_metadata[envarpay_order]': metadata.envarpay_order, 'shared_metadata[envarpay_quote]': quote.quoteId, 'shared_metadata[envarpay_terms]': quote.termsDigest,
+        });
+        if (issuance === 'issued-token') {
+            body.set('seller_details[network_business_profile]', operation.networkId);
+            if (config.returnUrl)
+                body.set('return_url', config.returnUrl);
+        }
+        return { operation: structuredClone(operation), body: body.toString(), binding: { issuerAccountId: config.issuerAccountId, sellerAccountId: config.sellers[operation.networkId].accountId, issuance, ...(config.returnUrl ? { returnUrl: config.returnUrl } : {}) } };
+    }
+    function saved(row) {
+        const original = vault.get(row.requestRef);
+        if (row.operationId !== original.operation?.operationId || digest(original) !== row.fingerprint || digest(requestFor(original.operation)) !== row.fingerprint)
+            throw new CommerceError('stripe_spt_recovery_binding', 'Original issuer scope changed or failed integrity validation');
+        return original;
+    }
+    function tokenId(row) {
+        if (!row.tokenRef)
+            throw new CommerceError('stripe_spt_recovery_required', 'Original SPT ID is unknown; do not issue a replacement token');
+        const value = vault.get(row.tokenRef);
+        if (value.operationId !== row.operationId || value.fingerprint !== row.fingerprint || !TOKEN.test(value.id))
+            throw new CommerceError('stripe_spt_recovery_binding', 'Original encrypted SPT binding is invalid');
+        return value.id;
+    }
+    function validateToken(value, original, expectedId) {
+        const operation = original.operation, limits = object(value.usage_limits), meta = object(value.shared_metadata);
+        if (value.id !== expectedId || value.object !== (issuance === 'issued-token' ? 'shared_payment.issued_token' : 'shared_payment.granted_token') ||
+            value.livemode !== (config.mode === 'live') || limits.currency !== 'usd' || !Number.isSafeInteger(limits.max_amount) || String(limits.max_amount) !== operation.amount || limits.expires_at !== operation.expiresAt ||
+            meta.envarpay_operation !== operation.operationId || meta.envarpay_purchase !== operation.purchaseId || meta.envarpay_order !== operation.metadata.envarpay_order || meta.envarpay_quote !== operation.quote.quoteId || meta.envarpay_terms !== operation.quote.termsDigest ||
+            (issuance === 'issued-token' && (value.payment_method !== operation.paymentMethod || object(value.seller_details).network_business_profile !== operation.networkId)) ||
+            (issuance === 'test-helper' && object(value.payment_method_details).type !== 'card'))
+            throw new CommerceError('stripe_spt_response_binding', 'Stripe token does not match the original scope and mode');
+    }
+    function usable(value, original) {
+        if (value.status === 'requires_action')
+            throw new CommerceError('stripe_spt_requires_action', 'Original SPT requires customer authentication through Stripe.js');
+        const captured = object(object(value.usage_details).amount_captured);
+        if ((issuance === 'issued-token' && value.status !== 'active') || value.deactivated_at != null || value.deactivated_reason != null ||
+            captured.value !== 0 || captured.currency !== 'usd' || original.operation.expiresAt <= Math.floor(now() / 1000))
+            throw new CommerceError('stripe_spt_unusable', 'Original SPT is expired, consumed, inactive or not proven unused');
+        return String(value.id);
+    }
+    async function retrieve(row) {
+        const original = saved(row), id = tokenId(row);
+        await account(config.secretKey, config.issuerAccountId);
+        // Test helpers use the seller account itself; issued tokens use the issuer account.
+        const value = await call(config.secretKey, `/v1/shared_payment/${issuance === 'issued-token' ? 'issued' : 'granted'}_tokens/${id}`);
+        validateToken(value, original, id);
+        return { original, value };
+    }
+    async function exclusive(id, fn) {
+        if (inFlight.has(id))
+            throw new CommerceError('stripe_spt_operation_busy', 'Original SPT operation is already in progress');
+        inFlight.add(id);
+        try {
+            return await fn();
+        }
+        finally {
+            inFlight.delete(id);
+        }
+    }
+    const adapter = {
+        payer: config.payer, mode: config.mode, paymentMethod: config.paymentMethod, issuance,
+        async assertReady() {
+            await account(config.secretKey, config.issuerAccountId);
+            for (const profile of Object.keys(config.sellers))
+                await sellerReady(profile);
+        },
+        close() { ledger.close(); },
+        async createToken(operation) {
+            return exclusive(operation.operationId, async () => {
+                const original = requestFor(operation), fingerprint = digest(original), prior = ledger.get(operation.operationId);
+                if (prior) {
+                    if (prior.fingerprint !== fingerprint)
+                        throw new CommerceError('stripe_spt_recovery_binding', 'Operation ID is already bound to another SPT request');
+                    const result = await retrieve(prior);
+                    return usable(result.value, result.original);
+                }
+                if (operation.expiresAt <= Math.floor(now() / 1000) || operation.expiresAt > Math.floor(now() / 1000) + 3600)
+                    throw new CommerceError('stripe_spt_expiry', 'SPT expiry must be within the original one-hour quote window');
+                await account(config.secretKey, config.issuerAccountId);
+                await sellerReady(operation.networkId);
+                if (operation.expiresAt <= Math.floor(now() / 1000))
+                    throw new CommerceError('stripe_spt_expiry', 'Original quote expired during issuer readiness checks');
+                // No await between durable insertion and starting the one permitted POST.
+                const row = ledger.insert(operation, fingerprint, vault.put(original), now());
+                const value = await call(config.secretKey, issuance === 'issued-token' ? '/v1/shared_payment/issued_tokens' : '/v1/test_helpers/shared_payment/granted_tokens', original.body, operation.idempotencyKey);
+                if (typeof value.id !== 'string' || !TOKEN.test(value.id))
+                    throw new CommerceError('stripe_spt_response_binding', 'Stripe did not return a valid original SPT ID');
+                // Save the ID even if the remaining response needs independent reconciliation.
+                ledger.token(row.operationId, vault.put({ operationId: row.operationId, fingerprint, id: value.id }));
+                validateToken(value, original, value.id);
+                return usable(value, original);
+            });
+        },
+        async recoverToken(operation) {
+            return exclusive(operation.operationId, async () => {
+                const row = ledger.get(operation.operationId);
+                if (!row)
+                    throw new CommerceError('stripe_spt_recovery_required', 'Original issuer operation is absent; do not issue a replacement token');
+                if (digest(requestFor(operation)) !== row.fingerprint)
+                    throw new CommerceError('stripe_spt_recovery_binding', 'Recovery differs from the original SPT request');
+                const result = await retrieve(row);
+                return usable(result.value, result.original);
+            });
+        },
+        async authenticationAction(operationId) {
+            if (!OPERATION.test(operationId))
+                throw new CommerceError('stripe_spt_recovery_required', 'Original issuer operation is required');
+            const row = ledger.get(operationId);
+            if (!row)
+                throw new CommerceError('stripe_spt_recovery_required', 'Original issuer operation is absent');
+            const { value } = await retrieve(row);
+            if (value.status !== 'requires_action')
+                return undefined;
+            const action = object(value.next_action), sdk = object(action.use_stripe_sdk);
+            if (action.type !== 'use_stripe_sdk' || typeof sdk.value !== 'string' || !sdk.value || sdk.value.length > 16384)
+                throw new CommerceError('stripe_spt_action_unsupported', 'Original SPT requires customer action not supported by this Stripe.js bridge');
+            return { type: 'use_stripe_sdk', hashedValue: sdk.value };
+        },
+        async getAuthentication(context) {
+            if (!OPERATION.test(context.operationId))
+                throw new CommerceError('stripe_spt_recovery_required', 'Original issuer operation is required');
+            const row = ledger.get(context.operationId);
+            if (!row)
+                throw new CommerceError('stripe_spt_recovery_required', 'Original issuer operation is absent');
+            const original = saved(row), op = original.operation;
+            if (context.purchaseId !== op.purchaseId || context.mode !== config.mode || digest(context.quote) !== digest(op.quote)) {
+                throw new CommerceError('stripe_spt_recovery_binding', 'Authentication differs from the original purchase');
+            }
+            const action = await adapter.authenticationAction(context.operationId);
+            if (!action)
+                return undefined;
+            if (!config.publishableKey)
+                throw new CommerceError('stripe_publishable_key_required', 'Configure the issuer publishable key to authenticate this original payment');
+            return { ...action, publishableKey: config.publishableKey };
+        },
+        async verifyReceipt(receipt, context) {
+            const row = ledger.get(context.operationId);
+            if (!row?.tokenRef)
+                return false;
+            const original = saved(row), op = original.operation, seller = config.sellers[op.networkId];
+            if (context.purchaseId !== op.purchaseId || context.mode !== config.mode || digest(context.quote) !== digest(op.quote) ||
+                receipt.method !== 'stripe' || receipt.status !== 'success' || !/^pi_[A-Za-z0-9]{1,128}$/.test(receipt.reference) ||
+                receipt.externalId !== op.quote.quoteId || receipt.amount !== op.amount || receipt.currency !== 'usd' || receipt.merchant !== op.networkId ||
+                receipt.accountId !== seller.accountId || receipt.livemode !== (config.mode === 'live'))
+                return false;
+            await sellerReady(op.networkId);
+            const intent = await call(seller.secretKey, `/v1/payment_intents/${receipt.reference}`);
+            const metadata = object(intent.metadata);
+            return intent.id === receipt.reference && intent.object === 'payment_intent' && intent.status === 'succeeded' && intent.livemode === (config.mode === 'live') &&
+                Number.isSafeInteger(intent.amount) && String(intent.amount) === op.amount && Number.isSafeInteger(intent.amount_received) && String(intent.amount_received) === op.amount &&
+                intent.currency === 'usd' && metadata.envarpay_order === op.metadata.envarpay_order && metadata.envarpay_quote === op.quote.quoteId && metadata.envarpay_terms === op.quote.termsDigest;
+        },
+    };
+    return adapter;
+}

package/dist/commerce/stripe-provider.d.ts

@@ -5,5 +5,7 @@ export interface StripeProviderConfig {
     merchantProfile: string;
     mode: 'test' | 'live';
 }
+/** Public Stripe Business Profiles and Shared Payment Tokens contract. */
+export declare const STRIPE_MPP_API_VERSION = "2026-09-30.preview";
 /** Stripe REST transport used by the official mppx Stripe method. No SPT creation. */
 export declare function stripeProvider(config: StripeProviderConfig, fetchImpl?: typeof fetch): StripeProvider;

package/dist/commerce/stripe-provider.js

@@ -1,8 +1,12 @@
 import { CommerceError } from './types.js';
+import { isStripeProfileId } from './config.js';
+/** Public Stripe Business Profiles and Shared Payment Tokens contract. */
+export const STRIPE_MPP_API_VERSION = '2026-09-30.preview';
 /** Stripe REST transport used by the official mppx Stripe method. No SPT creation. */
 export function stripeProvider(config, fetchImpl = fetch) {
-    if (!/^acct_[A-Za-z0-9]+$/.test(config.accountId) || !/^profile_[A-Za-z0-9]+$/.test(config.merchantProfile) ||
-        !config.secretKey.startsWith(config.mode === 'live' ? 'sk_live_' : 'sk_test_')) {
+    if (!['test', 'live'].includes(config.mode) || !/^acct_[A-Za-z0-9]+$/.test(config.accountId) || !isStripeProfileId(config.merchantProfile) ||
+        !new RegExp(`^(?:sk|rk)_${config.mode}_[A-Za-z0-9]{1,256}$`).test(config.secretKey) ||
+        (config.mode === 'live' && config.merchantProfile.startsWith('profile_test_'))) {
         throw new CommerceError('stripe_configuration', 'Explicit matching Stripe account, profile and test/live credentials are required');
     }
     const call = async (path, method = 'GET', params, options) => {
@@ -26,30 +30,45 @@ export function stripeProvider(config, fetchImpl = fetch) {
         for (const [key, value] of Object.entries(params ?? {}))
             add(key, value);
         const headers = new Headers({ Authorization: `Bearer ${config.secretKey}` });
-        if (options?.apiVersion)
-            headers.set('Stripe-Version', options.apiVersion);
+        headers.set('Stripe-Version', STRIPE_MPP_API_VERSION);
         if (options?.idempotencyKey)
             headers.set('Idempotency-Key', options.idempotencyKey);
         if (method !== 'GET')
             headers.set('Content-Type', 'application/x-www-form-urlencoded');
-        const response = await fetchImpl(`https://api.stripe.com${path}${method === 'GET' && body.size ? '?' + body.toString() : ''}`, {
-            method, headers, ...(method === 'GET' ? {} : { body }), redirect: 'error', signal: AbortSignal.timeout(20000),
-        });
+        const url = `https://api.stripe.com${path}${method === 'GET' && body.size ? '?' + body.toString() : ''}`;
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method, headers, ...(method === 'GET' ? {} : { body }), redirect: 'error', signal: AbortSignal.timeout(20000),
+            });
+        }
+        catch {
+            throw new CommerceError('stripe_transport_unknown', 'Stripe request outcome is unknown; preserve the original payment');
+        }
+        if (response.url && response.url !== url)
+            throw new CommerceError('stripe_redirect', 'Stripe response escaped the fixed provider request');
         const reader = response.body?.getReader();
         let size = 0;
         const chunks = [];
-        if (reader)
-            for (;;) {
-                const { value, done } = await reader.read();
-                if (done)
-                    break;
-                size += value.byteLength;
-                if (size > 1024 * 1024) {
-                    await reader.cancel();
-                    throw new CommerceError('stripe_response_size', 'Stripe response exceeds limit');
+        try {
+            if (reader)
+                for (;;) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    size += value.byteLength;
+                    if (size > 1024 * 1024) {
+                        await reader.cancel();
+                        throw new CommerceError('stripe_response_size', 'Stripe response exceeds limit');
+                    }
+                    chunks.push(value);
                 }
-                chunks.push(value);
-            }
+        }
+        catch (error) {
+            if (error instanceof CommerceError)
+                throw error;
+            throw new CommerceError('stripe_transport_unknown', 'Stripe response was interrupted; preserve the original payment');
+        }
         let result;
         try {
             result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
@@ -73,12 +92,28 @@ export function stripeProvider(config, fetchImpl = fetch) {
         accountId: config.accountId, merchantProfile: config.merchantProfile, mode: config.mode,
         async assertReady() {
             const account = await call('/v1/account');
-            if (account.id !== config.accountId)
+            if (account.object !== 'account' || account.id !== config.accountId)
                 throw new CommerceError('stripe_account_mismatch', 'Stripe key belongs to another account');
-            if (config.mode === 'live' && account.charges_enabled !== true)
-                throw new CommerceError('stripe_charges_disabled', 'Live merchant is not enabled for charges');
+            if (config.mode === 'live' && (account.charges_enabled !== true || account.capabilities?.card_payments !== 'active'))
+                throw new CommerceError('stripe_charges_disabled', 'Live merchant is not enabled for card charges');
+            const profile = await call('/v2/network/business_profiles/me');
+            // /me binds the profile to this authenticated merchant; the documented
+            // livemode field must also prove the requested test/live boundary.
+            if (profile.object !== 'v2.network.business_profile' || profile.id !== config.merchantProfile ||
+                profile.livemode !== (config.mode === 'live'))
+                throw new CommerceError('stripe_profile_mismatch', 'Stripe profile does not match this merchant and mode');
+        },
+        async create(params, options) {
+            if (!Number.isSafeInteger(params.amount) || Number(params.amount) < 50 || Number(params.amount) > 99999999 || params.currency !== 'usd' || params.confirm !== true ||
+                typeof params.shared_payment_granted_token !== 'string' || !/^spt_[A-Za-z0-9_]+$/.test(params.shared_payment_granted_token) ||
+                params.payment_method_data !== undefined || params.payment_method !== undefined || typeof options.idempotencyKey !== 'string' || !options.idempotencyKey || options.idempotencyKey.length > 255) {
+                throw new CommerceError('stripe_request', 'MPP Stripe charge requires a bound USD amount, original SPT and idempotency key');
+            }
+            // mppx 0.13.1 supplies the older SDK argument. The pinned public Stripe API
+            // consumes SPTs under payment_method_data; preserve the same original token.
+            const { shared_payment_granted_token: token, ...rest } = params;
+            return validateIntent(await call('/v1/payment_intents', 'POST', { ...rest, payment_method_data: { shared_payment_granted_token: token } }, options));
         },
-        async create(params, options) { return validateIntent(await call('/v1/payment_intents', 'POST', params, options)); },
         async retrieve(id) {
             if (!/^pi_[A-Za-z0-9]+$/.test(id))
                 throw new CommerceError('stripe_reference', 'Invalid original PaymentIntent');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envarai/envarpay",
-  "version": "0.2.0-alpha.3",
+  "version": "0.2.0-alpha.5",
   "description": "Independent A2A service commerce, budgeted buyers and x402/MPP payments",
   "type": "module",
   "license": "MIT",