@envarai/envarpay 0.2.0-alpha.1 → 0.2.0-alpha.11

package/README.md

@@ -11,6 +11,8 @@ not evidence that its npm/OCI artifact is published.
 
 ## Runtime and entry points
 
+For Hermes onboarding, see [guided Skill setup](../../docs/hermes-skill-setup.md). The `setup --file ...` command reads the owner's local model configuration and creates a private seller with an empty catalog, ready for the first service to be configured in Envar.
+
 Node.js 22.14+ (Node 24 recommended). SQLite is single-instance. Contracts can be
 read without loading the seller or buyer runtime; Bun validation covers the
 contracts entry, not the SQLite server.

package/dist/commerce/alerts.d.ts

@@ -0,0 +1,37 @@
+type SignalName = 'ledger_read' | 'payment_unknown' | 'execution_unknown' | 'recorded_provider_failure' | 'budget_near_limit' | 'budget_exhausted' | 'report_backlog' | 'report_failure';
+type Signal = {
+    name: SignalName;
+    status: 'clear' | 'alert' | 'unavailable' | 'not_applicable';
+    severity: 'info' | 'warning' | 'critical';
+    count: number | null;
+};
+type Budget = {
+    unit: string;
+    maxTotal: string;
+    reserved: string;
+    spent: string;
+    remaining: string;
+    state: 'available' | 'near_limit' | 'exhausted';
+};
+export interface LocalAlertOptions {
+    policyPath?: string;
+    integrationPath?: string;
+    integrationDisabled?: boolean;
+}
+/** Owner-local aggregate evidence only. Never opens a runtime store, signer, vault or network. */
+export declare function inspectLocalAlerts(path: string, options?: LocalAlertOptions): {
+    role: "unavailable" | "buyer" | "seller";
+    view: "alerts";
+    observation: "local_persisted_state_only";
+    status: string;
+    signals: Signal[];
+    budgets: Budget[];
+    alertCount: number;
+    unavailableCount: number;
+    providerHealth: "unavailable_not_probed";
+    recommendedExitCode: number;
+    paymentPerformed: boolean;
+    refundPerformed: boolean;
+    networkRequests: number;
+};
+export {};

package/dist/commerce/alerts.js

@@ -0,0 +1,127 @@
+import { DatabaseSync } from 'node:sqlite';
+import { lstatSync, readFileSync } from 'node:fs';
+import { loadBuyerPolicy } from './config.js';
+const CURRENCIES = {
+    usd: 'usd_cents',
+    'eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913': 'base_usdc_atomic',
+    'eip155:84532/erc20:0x036cbd53842c5426634e7929541ec2318f3dcf7e': 'base_sepolia_usdc_atomic',
+};
+function privateFile(path, limit) {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || (process.getuid && stat.uid !== process.getuid()) || (limit !== undefined && stat.size > limit))
+        throw new Error('private_source_unavailable');
+}
+function database(path) {
+    privateFile(path);
+    const db = new DatabaseSync(path, { readOnly: true });
+    try {
+        db.exec('PRAGMA query_only=ON; PRAGMA busy_timeout=1000; BEGIN');
+        return db;
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+}
+const count = (db, sql) => Number(db.prepare(sql).get().n);
+const signal = (name, value, severity = 'warning') => ({ name, status: value ? 'alert' : 'clear', severity: value ? severity : 'info', count: value });
+const missing = (name) => ({ name, status: 'unavailable', severity: 'warning', count: null });
+const irrelevant = (name) => ({ name, status: 'not_applicable', severity: 'info', count: null });
+/** Owner-local aggregate evidence only. Never opens a runtime store, signer, vault or network. */
+export function inspectLocalAlerts(path, options = {}) {
+    const signals = [], budgets = [];
+    let role = 'unavailable', db;
+    try {
+        db = database(path);
+        const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map(row => row.name));
+        if (tables.has('buyer_purchases') === tables.has('commerce_orders'))
+            throw new Error('unknown_ledger');
+        role = tables.has('buyer_purchases') ? 'buyer' : 'seller';
+        if (db.prepare(`SELECT version FROM ${role === 'buyer' ? 'buyer_meta' : 'commerce_meta'}`).get()?.version !== (role === 'buyer' ? 1 : 2))
+            throw new Error('unknown_version');
+        const unknownPayments = count(db, role === 'buyer' ? "SELECT COUNT(*) n FROM buyer_purchases WHERE json_extract(record_json,'$.paymentState')='unknown'" : "SELECT COUNT(*) n FROM commerce_orders WHERE payment_state='unknown'");
+        const unknownExecution = count(db, role === 'buyer' ? "SELECT COUNT(*) n FROM buyer_purchases WHERE json_extract(record_json,'$.executionState')='unknown'" : "SELECT COUNT(*) n FROM commerce_orders WHERE execution_state='unknown'");
+        // Only concrete persisted provider errors count. Generic unknown is not proof of provider failure.
+        const providerFailures = count(db, role === 'buyer'
+            ? "SELECT COUNT(*) n FROM buyer_purchases WHERE json_extract(record_json,'$.paymentState')!='confirmed' AND json_extract(record_json,'$.errorCode') IN ('stripe_transport_unknown','stripe_request_failed','stripe_rate_limit','stripe_response','stripe_response_size')"
+            : "SELECT COUNT(*) n FROM commerce_payment_attempts WHERE state!='confirmed' AND json_extract(receipt_json,'$.success')=0 AND length(json_extract(receipt_json,'$.errorReason'))>0");
+        signals.push(signal('ledger_read', 0), signal('payment_unknown', unknownPayments), signal('execution_unknown', unknownExecution), signal('recorded_provider_failure', providerFailures));
+        if (role === 'seller')
+            signals.push(irrelevant('budget_near_limit'), irrelevant('budget_exhausted'));
+        else {
+            try {
+                if (!options.policyPath)
+                    throw new Error('policy_required');
+                privateFile(options.policyPath, 1024 * 1024);
+                const policy = loadBuyerPolicy(JSON.parse(readFileSync(options.policyPath, 'utf8')));
+                const usage = new Map();
+                for (const b of policy.budgets)
+                    usage.set(b.currency, { reserved: 0n, spent: 0n });
+                for (const row of db.prepare("SELECT currency,amount,budget_state FROM buyer_purchases WHERE budget_state!='none'").iterate()) {
+                    const currency = String(row.currency), amount = String(row.amount), state = row.budget_state;
+                    const target = usage.get(currency);
+                    if (!target || !/^[1-9][0-9]{0,77}$/.test(amount) || !['spent', 'reserved'].includes(String(state)))
+                        throw new Error('budget_binding');
+                    target[state === 'spent' ? 'spent' : 'reserved'] += BigInt(amount);
+                }
+                const checked = policy.budgets.map(b => {
+                    const u = usage.get(b.currency), cap = BigInt(b.maxTotal), used = u.reserved + u.spent;
+                    const state = used >= cap ? 'exhausted' : used * 10n >= cap * 9n ? 'near_limit' : 'available';
+                    return { unit: CURRENCIES[b.currency], maxTotal: cap.toString(), reserved: u.reserved.toString(), spent: u.spent.toString(), remaining: (used < cap ? cap - used : 0n).toString(), state };
+                });
+                budgets.push(...checked);
+                signals.push(signal('budget_near_limit', checked.filter(b => b.state === 'near_limit').length), signal('budget_exhausted', checked.filter(b => b.state === 'exhausted').length, 'critical'));
+            }
+            catch {
+                signals.push(missing('budget_near_limit'), missing('budget_exhausted'));
+            }
+        }
+    }
+    catch {
+        role = 'unavailable';
+        signals.length = 0;
+        budgets.length = 0;
+        signals.push(...['ledger_read', 'payment_unknown', 'execution_unknown', 'recorded_provider_failure', 'budget_near_limit', 'budget_exhausted'].map(missing));
+    }
+    finally {
+        db?.close();
+    }
+    let integration;
+    try {
+        if (options.integrationDisabled && !options.integrationPath) {
+            signals.push(irrelevant('report_backlog'), irrelevant('report_failure'));
+        }
+        else {
+            if (options.integrationDisabled)
+                throw new Error('ambiguous_integration');
+            if (!options.integrationPath)
+                throw new Error('integration_not_supplied');
+            integration = database(options.integrationPath);
+            const binding = integration.prepare("SELECT value FROM meta WHERE key='binding'").get();
+            const source = integration.prepare("SELECT value FROM meta WHERE key='source_instance'").get();
+            if (!binding || !source || typeof binding.value !== 'string' || typeof source.value !== 'string')
+                throw new Error('integration_schema');
+            const parsed = JSON.parse(binding.value);
+            if (!parsed || typeof parsed.platformOrigin !== 'string' || typeof parsed.agentId !== 'string' || typeof parsed.runtimeAgentId !== 'string')
+                throw new Error('integration_schema');
+            const pending = count(integration, "SELECT COUNT(*) n FROM outbox WHERE state='pending'");
+            const failed = count(integration, "SELECT COUNT(*) n FROM outbox WHERE state='pending' AND attempts>0 AND last_error<>''");
+            signals.push(signal('report_backlog', pending), signal('report_failure', failed));
+        }
+    }
+    catch {
+        signals.push(missing('report_backlog'), missing('report_failure'));
+    }
+    finally {
+        integration?.close();
+    }
+    const alertCount = signals.filter(s => s.status === 'alert').length, unavailableCount = signals.filter(s => s.status === 'unavailable').length;
+    return {
+        role, view: 'alerts', observation: 'local_persisted_state_only',
+        status: role === 'unavailable' ? 'unavailable' : unavailableCount ? 'partial' : 'available',
+        signals, budgets, alertCount, unavailableCount,
+        providerHealth: 'unavailable_not_probed',
+        recommendedExitCode: unavailableCount ? 3 : alertCount ? 2 : 0,
+        paymentPerformed: false, refundPerformed: false, networkRequests: 0,
+    };
+}

package/dist/commerce/buyer-store.d.ts

@@ -15,6 +15,8 @@ export interface BuyerQuote {
     inputDigest: string;
     termsDigest: string;
     quoteId: string;
+    /** Absent for the original seller-advertised EnvarPay contract. */
+    termsSource?: 'local-policy';
 }
 export interface BuyerRecord {
     id: string;
@@ -29,6 +31,12 @@ export interface BuyerRecord {
     quote: BuyerQuote;
     input: Input;
     inputSchema: Record<string, unknown>;
+    peerMode?: 'standard-a2a';
+    standardBinding?: {
+        policyDigest: string;
+        bodyDigest: string;
+        challengeDigest: string;
+    };
     continuations?: {
         messageId: string;
         input: Input;

package/dist/commerce/buyer.d.ts

@@ -1,9 +1,9 @@
 import type { ClientEvmSigner } from '@x402/evm';
 import type { PaymentPayload, PaymentRequirements, SettleResponse } from '@x402/core/types';
-import { type BuyerPolicy, type Input } from './types.js';
+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;
@@ -78,9 +82,10 @@ export declare class CommerceBuyer {
         policyVersion: 1;
         paymentsEnabled: boolean;
         approval: "per_purchase" | "within_preapproved_limits";
-        peers: ({
+        peers: (StandardA2APeer | {
             id: string;
             cardUrl: string;
+            mode?: "envarpay";
             protocol: "x402" | "mpp";
             currency: string;
             recipient: string;
@@ -88,6 +93,7 @@ export declare class CommerceBuyer {
         } | {
             id: string;
             cardUrl: string;
+            mode?: "envarpay";
             protocol: "free";
             currency: null;
             recipient: null;
@@ -102,6 +108,7 @@ export declare class CommerceBuyer {
     get(caller: string, id: string): BuyerSnapshot;
     preview(caller: string, input: BuyerPreviewInput): Promise<BuyerSnapshot>;
     private prepare;
+    private prepareStandard;
     private prepareFree;
     private replayFree;
     private prepareMpp;
@@ -111,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

@@ -1,6 +1,6 @@
 import { findDefaultAsset } from '@x402/evm';
 import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
-import { AgentCard, SendMessageRequest, GetTaskRequest, Task, TaskState } from '@a2a-js/sdk';
+import { AgentCard, SendMessageRequest, GetTaskRequest, Task, TaskState, Message, Role } from '@a2a-js/sdk';
 import { ClientFactory, JsonRpcTransportFactory } from '@a2a-js/sdk/client';
 import { x402Client } from '@x402/core/client';
 import { decodePaymentRequiredHeader, decodePaymentResponseHeader, encodePaymentSignatureHeader } from '@x402/core/http';
@@ -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) {
@@ -67,6 +67,31 @@ function noExternalRefs(value) {
         noExternalRefs(child);
     }
 }
+function standardPolicyDigest(peer) {
+    return digest({ mode: peer.mode, cardUrl: peer.cardUrl, endpoint: peer.endpoint, authentication: peer.authentication,
+        protocol: peer.protocol, currency: peer.currency, recipient: peer.recipient, localContract: peer.localContract });
+}
+function standardRequirements(peer, required) {
+    let resource;
+    try {
+        resource = new URL(required.resource?.url ?? '');
+    }
+    catch {
+        throw new CommerceError('quote_mismatch', 'Standard payment resource must name the approved A2A endpoint');
+    }
+    const candidates = Array.isArray(required.accepts) ? required.accepts.filter(r => {
+        if (!r || r.scheme !== 'exact' || typeof r.asset !== 'string' || typeof r.payTo !== 'string' || `${r.network}/erc20:${r.asset.toLowerCase()}` !== peer.currency || r.payTo.toLowerCase() !== peer.recipient || r.amount !== peer.localContract.amount || !Number.isInteger(r.maxTimeoutSeconds) || r.maxTimeoutSeconds < 1 || r.maxTimeoutSeconds > 300)
+            return false;
+        const asset = findDefaultAsset(r.asset, r.network), extra = r.extra;
+        return !!asset && !!extra && typeof extra === 'object' && !Array.isArray(extra)
+            && (extra.assetTransferMethod === undefined || extra.assetTransferMethod === 'eip3009')
+            && (extra.paymentFlow === undefined || extra.paymentFlow === 'upfront')
+            && extra.name === asset.name && extra.version === asset.version;
+    }) : [];
+    if (required.x402Version !== 2 || resource.href !== peer.endpoint || resource.username || resource.password || resource.hash || candidates.length !== 1)
+        throw new CommerceError('quote_mismatch', 'Native challenge differs from the exact locally approved resource, price, asset, payee or timeout');
+    return candidates[0];
+}
 /** Independent x402 wallet; payment and execution state are deliberately separate. */
 export class CommerceBuyer {
     options;
@@ -83,11 +108,11 @@ 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 (!options.peerTokens[peer.id] || options.peerTokens[peer.id].length < 16)
-                throw new CommerceError('peer_credentials', 'Each allowed peer needs its own authentication token');
+            if (!(peer.mode === 'standard-a2a' && peer.authentication === 'none') && (!options.peerTokens[peer.id] || options.peerTokens[peer.id].length < 16))
+                throw new CommerceError('peer_credentials', 'Each authenticated peer needs its own authentication token');
     }
     /** Background observation only; never signs, replays credentials or changes reservations. */
     start(intervalMs = 2000) {
@@ -117,6 +142,11 @@ export class CommerceBuyer {
     }
     endpoint(peer) {
         const explicit = this.options.peerEndpoints?.[peer.id];
+        if (peer.mode === 'standard-a2a') {
+            if (explicit && explicit !== peer.endpoint)
+                throw new CommerceError('endpoint_policy', 'A standard peer endpoint must match its locally reviewed policy');
+            return peer.endpoint;
+        }
         const card = new URL(peer.cardUrl);
         if (!explicit && (!card.pathname.endsWith('/agent-card.json') || card.search))
             throw new CommerceError('endpoint_policy', 'Configure an explicit peer endpoint for this Agent Card URL');
@@ -133,7 +163,10 @@ export class CommerceBuyer {
             if ((request.url === peer.cardUrl && request.method !== 'GET') || (request.url === endpoint && request.method !== 'POST'))
                 throw new CommerceError('peer_scope', 'Unsupported peer operation');
             const headers = new Headers(request.headers);
-            headers.set('Authorization', `Bearer ${this.options.peerTokens[peer.id]}`);
+            if (peer.mode === 'standard-a2a' && peer.authentication === 'none')
+                headers.delete('Authorization');
+            else
+                headers.set('Authorization', `Bearer ${this.options.peerTokens[peer.id]}`);
             headers.set('A2A-Version', '1.0');
             const response = await this.fetchImpl(new Request(request, { headers, redirect: 'error', signal: AbortSignal.any([request.signal, AbortSignal.timeout(30000)]) }));
             if (response.status >= 300 && response.status < 400)
@@ -183,7 +216,11 @@ export class CommerceBuyer {
         if (!response.ok)
             throw new CommerceError('peer_card', 'Unable to read allowed Agent Card');
         const card = AgentCard.fromJSON(await response.json());
-        if (!card.supportedInterfaces.some(i => i.protocolVersion === '1.0' && i.protocolBinding === 'JSONRPC' && i.url === endpoint) || card.supportedInterfaces.some(i => i.url !== endpoint))
+        if (!card.supportedInterfaces.some(i => i.protocolVersion === '1.0' && i.protocolBinding === 'JSONRPC' && i.url === endpoint))
+            throw new CommerceError('peer_interface', 'Agent Card must expose the approved A2A 1.0 JSONRPC endpoint');
+        if (peer.mode === 'standard-a2a')
+            return this.prepareStandard(caller, input, fingerprint, peer, card);
+        if (card.supportedInterfaces.some(i => i.url !== endpoint))
             throw new CommerceError('peer_interface', 'Agent Card must expose only the approved A2A 1.0 JSONRPC endpoint');
         const advertised = card.capabilities?.extensions.find(e => e.uri === COMMERCE)?.params;
         if (!advertised || advertised.offerId !== input.offerId || !advertised.serviceId || !Number.isSafeInteger(advertised.serviceRevision) || advertised.serviceRevision < 1 || !/^[0-9a-f]{64}$/.test(advertised.termsDigest ?? '') || !advertised.contract?.inputSchema || (peer.protocol !== 'free' && (advertised.collection?.kind !== 'upfront' || advertised.payment?.adapter !== peer.protocol)))
@@ -247,6 +284,63 @@ export class CommerceBuyer {
         };
         return this.snapshot(this.options.store.insert({ protocol: 'x402', caller, peerId: peer.id, cardUrl: peer.cardUrl, endpoint, messageId: input.messageId, fingerprint, input: structuredClone(input.input), inputSchema: structuredClone(advertised.contract.inputSchema), body: originalBody, quoteToken: randomBytes(32).toString('base64url'), quote: frozenQuote, required, requirements: candidates[0] }));
     }
+    async prepareStandard(caller, input, fingerprint, peer, card) {
+        const contract = peer.localContract;
+        if (card.securityRequirements.length && !card.securityRequirements.some(requirement => {
+            const names = Object.keys(requirement.schemes);
+            if (!names.length)
+                return true;
+            if (peer.authentication !== 'bearer' || names.length !== 1)
+                return false;
+            const name = names[0], scheme = card.securitySchemes[name]?.scheme;
+            return scheme?.$case === 'httpAuthSecurityScheme' && scheme.value.scheme.toLowerCase() === 'bearer' && !requirement.schemes[name].list.length;
+        }))
+            throw new CommerceError('peer_authentication', 'Agent Card authentication is not satisfied by the locally approved none/bearer mode');
+        if (input.offerId !== contract.offerId)
+            throw new CommerceError('offer_not_allowed', 'Select the locally reviewed standard-peer offer');
+        const ajv = new Ajv2020({ strict: true });
+        addFormats(ajv);
+        if (!ajv.compile(contract.inputSchema)(input.input))
+            throw new CommerceError('invalid_input', 'Input does not satisfy the locally reviewed schema');
+        const amount = atomic(contract.amount).toString();
+        if (atomic(amount) > atomic(peer.maxPerPurchase))
+            throw new CommerceError('purchase_limit', 'Local price exceeds the per-purchase limit');
+        let body = '', required;
+        const capture = async (value, init) => {
+            const request = new Request(value, init);
+            body = await request.clone().text();
+            if (Buffer.byteLength(body) > 1024 * 1024)
+                throw new CommerceError('request_too_large', 'Purchase input exceeds 1 MiB');
+            const response = await this.scopedFetch(peer, peer.endpoint)(request);
+            if (response.status !== 402)
+                throw new CommerceError('paid_quote_required', 'The operator-approved paid-only endpoint must return 402 before any authorization');
+            const header = response.headers.get('PAYMENT-REQUIRED');
+            if (!header || header.length > 65536)
+                throw new CommerceError('invalid_challenge', 'Missing or oversized native x402 challenge');
+            required = decodePaymentRequiredHeader(header);
+            throw new CommerceError('preview_captured', 'Native standard payment challenge captured');
+        };
+        // Ignore every advertised alternative; only the operator-selected interface may receive requests.
+        const selected = AgentCard.fromJSON({ ...AgentCard.toJSON(card), supportedInterfaces: [{ url: peer.endpoint, protocolBinding: 'JSONRPC', protocolVersion: '1.0' }] });
+        const client = await new ClientFactory({ transports: [new JsonRpcTransportFactory({ fetchImpl: capture })] }).createFromAgentCard(selected);
+        try {
+            await client.sendMessage(SendMessageRequest.fromJSON({ message: { messageId: input.messageId, role: 'ROLE_USER', parts: [{ data: input.input }] }, configuration: { returnImmediately: true } }));
+        }
+        catch (error) {
+            if (!required)
+                throw error;
+        }
+        if (!required || !body)
+            throw new CommerceError('invalid_challenge', 'The approved endpoint did not return a native payment challenge');
+        const requirements = standardRequirements(peer, required), policyDigest = standardPolicyDigest(peer);
+        const quote = { quoteId: randomUUID(), messageId: input.messageId, payer: this.options.signer.address.toLowerCase(), amount,
+            currency: peer.currency, recipient: peer.recipient, expiresAt: new Date(Date.now() + requirements.maxTimeoutSeconds * 1000).toISOString(),
+            serviceId: peer.id, serviceRevision: contract.revision, offerId: contract.offerId, inputDigest: digest(input.input), termsDigest: policyDigest, termsSource: 'local-policy' };
+        return this.snapshot(this.options.store.insert({ protocol: 'x402', peerMode: 'standard-a2a', caller, peerId: peer.id, cardUrl: peer.cardUrl, endpoint: peer.endpoint,
+            messageId: input.messageId, fingerprint, input: structuredClone(input.input), inputSchema: structuredClone(contract.inputSchema), body,
+            quoteToken: randomBytes(32).toString('base64url'), quote, required, requirements,
+            standardBinding: { policyDigest, bodyDigest: digest(body), challengeDigest: digest(required) } }));
+    }
     prepareFree(caller, input, fingerprint, peer, endpoint, advertised) {
         if (advertised.pricing?.kind !== 'free' || advertised.collection?.kind !== 'none' || advertised.payment !== null)
             throw new CommerceError('free_offer_required', 'This peer permits explicit free offers only');
@@ -391,10 +485,41 @@ 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))
             throw new CommerceError('policy_changed', 'Original purchase no longer matches local wallet policy');
+        if ((record.peerMode === 'standard-a2a') !== (peer.mode === 'standard-a2a'))
+            throw new CommerceError('policy_changed', 'Original peer protocol profile changed');
+        if (record.peerMode === 'standard-a2a') {
+            if (peer.mode !== 'standard-a2a' || !record.standardBinding || record.standardBinding.policyDigest !== standardPolicyDigest(peer))
+                throw new CommerceError('policy_changed', 'Original local standard-peer contract or authentication changed');
+            const quote = record.quote, contract = peer.localContract;
+            if (quote.termsSource !== 'local-policy' || quote.termsDigest !== record.standardBinding.policyDigest || quote.inputDigest !== digest(record.input) || quote.messageId !== record.messageId || quote.amount !== contract.amount || quote.serviceId !== peer.id || quote.serviceRevision !== contract.revision || quote.offerId !== contract.offerId || digest(record.inputSchema) !== digest(contract.inputSchema))
+                throw new CommerceError('recovery_conflict', 'Local review quote no longer matches its frozen standard-peer contract and input');
+            if (record.standardBinding.bodyDigest !== digest(record.body) || record.standardBinding.challengeDigest !== digest(record.required) || digest(standardRequirements(peer, record.required)) !== digest(record.requirements))
+                throw new CommerceError('recovery_conflict', 'Original standard request or native challenge changed');
+        }
         if (signing && peer.protocol !== 'free' && !this.policy.paymentsEnabled)
             throw new CommerceError('payments_disabled', 'Enable payments in local wallet policy before confirming');
         return peer;
@@ -470,6 +595,8 @@ export class CommerceBuyer {
     async verify(record, saved, receipt) {
         if (record.paymentState === 'confirmed')
             return record;
+        if (record.peerMode === 'standard-a2a' && receipt && (receipt.network !== saved.requirements.network || (receipt.payer && receipt.payer.toLowerCase() !== record.quote.payer)))
+            throw new CommerceError('receipt_binding', 'Receipt differs from the original standard-peer chain or payer');
         if (receipt)
             record = this.options.store.update(record.id, { receipt });
         if (!receipt?.transaction && record.fromBlock && this.options.findOriginalReceipt)
@@ -505,8 +632,16 @@ export class CommerceBuyer {
         }
         catch { /* retain the original receipt and reservation for reconciliation */ }
         const raw = await response.json();
+        if (record.peerMode === 'standard-a2a' && (raw.jsonrpc !== '2.0' || raw.id !== JSON.parse(record.body).id))
+            throw new CommerceError('rpc_response_binding', 'Peer response does not match the original standard JSON-RPC request');
         if (response.ok && raw.result?.task)
             record = this.task(record, raw.result.task);
+        else if (record.peerMode === 'standard-a2a' && response.ok && raw.result?.message) {
+            const message = Message.fromJSON(raw.result.message);
+            if (!message.messageId || message.role !== Role.ROLE_AGENT || !message.parts.length)
+                throw new CommerceError('message_binding', 'Peer returned an invalid A2A response message');
+            record = this.options.store.update(record.id, { result: { message: Message.toJSON(message) }, executionState: 'completed', state: record.paymentState === 'confirmed' ? 'completed' : 'unknown' });
+        }
         else
             record = this.options.store.update(record.id, { state: 'unknown', errorCode: 'original_purchase_pending' });
         return this.snapshot(record);
@@ -529,6 +664,8 @@ export class CommerceBuyer {
     }
     async continue(caller, id, input) {
         const record = this.record(caller, id);
+        if (record.peerMode === 'standard-a2a')
+            throw new CommerceError('standard_continuation_unavailable', 'A standard peer has not promised included clarification; inspect its original Task without a new submission');
         if (typeof input.messageId !== 'string' || !input.messageId || input.messageId.length > 128 || input.messageId === record.messageId || !input.input || typeof input.input !== 'object' || Array.isArray(input.input))
             throw new CommerceError('invalid_continuation', 'A distinct stable message ID and full object input are required');
         const running = this.active.get(id);
@@ -621,6 +758,13 @@ export class CommerceBuyer {
                 if (original.task?.id) {
                     return this.observe(original);
                 }
+                if (original.peerMode === 'standard-a2a') {
+                    // A2A message IDs do not guarantee idempotent execution at an unrelated seller.
+                    // Keep the exact original authorization, but never POST it again after an ambiguous outcome.
+                    if (original.paymentState === 'confirmed' && original.executionState === 'completed' && original.result && typeof original.result === 'object' && 'message' in original.result)
+                        return this.snapshot(this.options.store.update(id, { state: 'completed', errorCode: undefined }));
+                    return this.snapshot(this.options.store.update(id, { state: 'unknown', executionState: 'unknown', errorCode: 'standard_task_recovery_required' }));
+                }
                 return await this.replay(original);
             }
             catch (error) {

package/dist/commerce/card.js

@@ -1,6 +1,6 @@
 import { AgentCard } from '@a2a-js/sdk';
 import { CommerceError } from './types.js';
-import { validateUrl, digest } from './config.js';
+import { validateUrl, serviceTermsDigest } from './config.js';
 /** One deterministic offer route, serialized by the official A2A 1.0 codec. */
 export function offerPath(serviceId, revision, offerId) {
     return `/services/${encodeURIComponent(serviceId)}/v${revision}/offers/${encodeURIComponent(offerId)}`;
@@ -20,7 +20,7 @@ export function createOfferCard(config, serviceId, offerId, origin) {
         description: `Deliverables: ${service.contract.deliverables.join(', ')}`,
         version: String(service.revision),
         supportedInterfaces: [{ url: new URL(`${offerPath(service.id, service.revision, offer.id)}/a2a`, base).href, protocolBinding: 'JSONRPC', protocolVersion: '1.0' }],
-        capabilities: { streaming: false, pushNotifications: false, extensions: [{ uri: 'urn:envarpay:commerce:1', required: false, description: 'Optional service offer metadata; standard A2A and payment transports remain independently usable', params: { serviceId: service.id, serviceRevision: service.revision, offerId: offer.id, pricing: offer.pricing, collection: offer.collection, contract: service.contract, payment, termsDigest: digest({ contract: service.contract, offer, profile }) } }] },
+        capabilities: { streaming: false, pushNotifications: false, extensions: [{ uri: 'urn:envarpay:commerce:1', required: false, description: 'Optional service offer metadata; standard A2A and payment transports remain independently usable', params: { serviceId: service.id, serviceRevision: service.revision, offerId: offer.id, pricing: offer.pricing, collection: offer.collection, contract: service.contract, payment, termsDigest: serviceTermsDigest(config.configVersion, service, offer, profile), ...(config.configVersion === 2 && service.execution.type === 'skill' ? { skillDigest: service.execution.skillDigest } : {}) } }] },
         defaultInputModes: ['application/json'], defaultOutputModes: ['application/json', 'text/plain'],
         skills: [{ id: service.id, name: service.name, description: `Purchase ${service.name}`, tags: [service.id] }],
         securitySchemes: { bearer: { httpAuthSecurityScheme: { scheme: 'bearer' } } },