@envarai/envarpay 0.2.0-alpha.4 → 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) || (options.mpp.mode === 'test' && options.mpp.paymentMethod === 'pm_card_visa')) || !['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

@@ -137,6 +137,7 @@ async function run() {
             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 });

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/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/stripe-issuer.d.ts

@@ -12,6 +12,8 @@ export interface StripeMppBuyerConfig {
     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>>;

package/dist/commerce/stripe-issuer.js

@@ -5,6 +5,7 @@ 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}$/;
@@ -80,15 +81,18 @@ export function createStripeMppBuyer(input, runtime) {
     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' && config.paymentMethod === 'pm_card_visa'))) {
+        !(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' || config.paymentMethod !== 'pm_card_visa' || Object.values(config.sellers).some(s => s.accountId !== config.issuerAccountId))) {
-        throw new CommerceError('stripe_test_helper_configuration', 'Test helper requires pm_card_visa and the same explicitly configured test seller account');
+    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;
@@ -250,7 +254,7 @@ export function createStripeMppBuyer(input, runtime) {
         }
     }
     const adapter = {
-        payer: config.payer, mode: config.mode, paymentMethod: config.paymentMethod,
+        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))
@@ -308,6 +312,23 @@ export function createStripeMppBuyer(input, runtime) {
                 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)

package/package.json

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