@envarai/envarpay 0.1.0-alpha.2 → 0.2.0-alpha.1

package/dist/commerce/stripe-provider.js

@@ -0,0 +1,97 @@
+import { CommerceError } from './types.js';
+/** 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_')) {
+        throw new CommerceError('stripe_configuration', 'Explicit matching Stripe account, profile and test/live credentials are required');
+    }
+    const call = async (path, method = 'GET', params, options) => {
+        const body = new URLSearchParams();
+        const add = (key, value) => {
+            if (value === undefined || value === null)
+                return;
+            if (Array.isArray(value)) {
+                value.forEach((v, i) => add(`${key}[${i}]`, v));
+                return;
+            }
+            if (typeof value === 'object') {
+                for (const [k, v] of Object.entries(value))
+                    add(key ? `${key}[${k}]` : k, v);
+                return;
+            }
+            if (!['boolean', 'number', 'string'].includes(typeof value))
+                throw new CommerceError('stripe_request', 'Unsupported Stripe value');
+            body.set(key, String(value));
+        };
+        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);
+        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 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');
+                }
+                chunks.push(value);
+            }
+        let result;
+        try {
+            result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            throw new CommerceError('stripe_response', 'Stripe returned invalid JSON');
+        }
+        // Do not surface provider error text that might echo SPT or customer details.
+        if (!response.ok)
+            throw new CommerceError(response.status === 429 ? 'stripe_rate_limit' : 'stripe_request_failed', `Stripe request failed (HTTP ${response.status})`);
+        return { ...result, lastResponse: { headers: { 'idempotent-replayed': response.headers.get('idempotent-replayed') ?? 'false' } } };
+    };
+    const validateIntent = (value) => {
+        if (typeof value.id !== 'string' || !/^pi_[A-Za-z0-9]+$/.test(value.id) || typeof value.status !== 'string' ||
+            !Number.isSafeInteger(value.amount) || typeof value.livemode !== 'boolean' || !value.metadata || typeof value.metadata !== 'object') {
+            throw new CommerceError('stripe_response', 'Stripe returned an invalid PaymentIntent');
+        }
+        return value;
+    };
+    return {
+        accountId: config.accountId, merchantProfile: config.merchantProfile, mode: config.mode,
+        async assertReady() {
+            const account = await call('/v1/account');
+            if (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');
+        },
+        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');
+            return validateIntent(await call(`/v1/payment_intents/${id}`));
+        },
+        async findOriginal(orderId) {
+            if (!/^[0-9a-f-]{36}$/.test(orderId))
+                throw new CommerceError('order_reference', 'Invalid original order');
+            const result = await call('/v1/payment_intents/search', 'GET', { query: `metadata['envarpay_order']:'${orderId}'`, limit: 2 });
+            if (!Array.isArray(result.data) || result.has_more || result.data.length > 1)
+                throw new CommerceError('ambiguous_payment', 'Multiple intents require original-operation reconciliation');
+            // Stripe search may be eventually consistent. No match remains unknown.
+            return result.data.length ? validateIntent(result.data[0]) : undefined;
+        },
+    };
+}

package/dist/commerce/types.d.ts

@@ -0,0 +1,113 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type Input = Record<string, JsonValue>;
+export type Pricing = {
+    kind: 'free';
+} | {
+    kind: 'fixed';
+    amount: string;
+} | {
+    kind: 'quantity';
+    unit: string;
+    unitAmount: string;
+    quantity: {
+        pointer: string;
+        measure: 'count';
+        min: number;
+        max: number;
+    };
+};
+export interface Offer {
+    id: string;
+    pricing: Pricing;
+    collection: {
+        kind: 'none' | 'upfront';
+    };
+    paymentProfile?: string;
+}
+export type PaymentProfile = {
+    adapter: 'x402';
+    scheme: 'exact';
+    network: string;
+    asset: string;
+    payTo: string;
+    facilitatorUrl: string;
+} | {
+    adapter: 'mpp';
+    method: 'stripe';
+    intent: 'charge';
+    currency: 'usd';
+    accountRef: string;
+};
+export interface Service {
+    id: string;
+    name: string;
+    revision: number;
+    execution: {
+        type: 'a2a';
+        cardUrl: string;
+    };
+    contract: {
+        inputSchema: Record<string, unknown>;
+        deliverables: string[];
+        targetDurationSeconds: number;
+        includedRevisions: 0;
+    };
+    offers: Offer[];
+}
+export interface CommerceConfig {
+    configVersion: 1;
+    agent: {
+        id: string;
+        name: string;
+    };
+    paymentProfiles: Record<string, PaymentProfile>;
+    services: Service[];
+}
+export interface BuyerPolicy {
+    policyVersion: 1;
+    paymentsEnabled: boolean;
+    approval: 'per_purchase' | 'within_preapproved_limits';
+    peers: ({
+        id: string;
+        cardUrl: string;
+        protocol: 'x402' | 'mpp';
+        currency: string;
+        recipient: string;
+        maxPerPurchase: string;
+    } | {
+        id: string;
+        cardUrl: string;
+        protocol: 'free';
+        currency: null;
+        recipient: null;
+        maxPerPurchase: '0';
+    })[];
+    budgets: {
+        currency: string;
+        maxTotal: string;
+        period: 'cumulative';
+    }[];
+}
+export interface PriceQuote {
+    quoteVersion: 1;
+    quoteId: string;
+    caller: string;
+    serviceId: string;
+    serviceRevision: number;
+    offerId: string;
+    messageId: string;
+    inputDigest: string;
+    termsDigest: string;
+    issuedAt: string;
+    expiresAt: string;
+    amount: string;
+    currency: string | null;
+    recipient: string | null;
+    paymentProfile: PaymentProfile | null;
+}
+export declare class CommerceError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}

package/dist/commerce/types.js

@@ -0,0 +1,8 @@
+export class CommerceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'CommerceError';
+    }
+}

package/dist/commerce/upstream.d.ts

@@ -0,0 +1,6 @@
+import type { ExecuteOrder } from './server.js';
+/** Official A2A calls, pinned to the configured origin and original remote interface. */
+export interface NativeA2AOptions {
+    inputEncoding?: Readonly<Record<string, 'data' | 'json-text'>>;
+}
+export declare function nativeA2AExecutor(tokens: Readonly<Record<string, string>>, fetchImpl?: typeof fetch, signal?: AbortSignal, options?: NativeA2AOptions): ExecuteOrder;

package/dist/commerce/upstream.js

@@ -0,0 +1,103 @@
+import { AgentCard, GetTaskRequest, SendMessageRequest, TaskState } from '@a2a-js/sdk';
+import { ClientFactory, JsonRpcTransportFactory } from '@a2a-js/sdk/client';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { CommerceError } from './types.js';
+import { validateUrl } from './config.js';
+export function nativeA2AExecutor(tokens, fetchImpl = fetch, signal, options = {}) {
+    const inputEncoding = Object.freeze({ ...options.inputEncoding });
+    if (Object.values(inputEncoding).some(value => value !== 'data' && value !== 'json-text'))
+        throw new CommerceError('invalid_upstream_encoding', 'Choose an explicit data or json-text input encoding');
+    const parts = (service, input) => inputEncoding[service.id] === 'json-text' ? [{ text: JSON.stringify(input), mediaType: 'application/json' }] : [{ data: input }];
+    const interfaces = new WeakMap();
+    async function prepare(service, remote) {
+        const cardUrl = validateUrl(service.execution.cardUrl, true), token = tokens[`${service.id}:${service.revision}`] ?? tokens[service.id];
+        if (!token || token.length < 16)
+            throw new CommerceError('upstream_credentials', 'Configured runtime authentication is missing');
+        if (remote && remote.origin !== service.execution.cardUrl)
+            throw new CommerceError('upstream_origin', 'Original runtime origin differs from the frozen service');
+        const scopedFetch = async (input, init) => {
+            const request = new Request(input, init);
+            if (new URL(request.url).origin !== cardUrl.origin)
+                throw new CommerceError('upstream_origin', 'Runtime Card cannot redirect credentials to another origin');
+            const headers = new Headers(request.headers);
+            headers.set('Authorization', 'Bearer ' + token);
+            headers.set('A2A-Version', '1.0');
+            const signals = [request.signal, AbortSignal.timeout(120000), ...(signal ? [signal] : [])];
+            const response = await fetchImpl(new Request(request, { headers, redirect: 'error', signal: AbortSignal.any(signals) }));
+            if (Number(response.headers.get('Content-Length') ?? 0) > 4 * 1024 * 1024)
+                throw new CommerceError('upstream_size', 'Runtime response exceeds limit');
+            if (response.body) {
+                const reader = response.body.getReader(), chunks = [];
+                let length = 0;
+                for (;;) {
+                    const next = await reader.read();
+                    if (next.done)
+                        break;
+                    length += next.value.byteLength;
+                    if (length > 4 * 1024 * 1024) {
+                        await reader.cancel();
+                        throw new CommerceError('upstream_size', 'Runtime response exceeds limit');
+                    }
+                    chunks.push(next.value);
+                }
+                return new Response(Buffer.concat(chunks), { status: response.status, statusText: response.statusText, headers: response.headers });
+            }
+            return response;
+        };
+        const response = await scopedFetch(cardUrl);
+        if (!response.ok)
+            throw new CommerceError('upstream_card', 'Unable to read runtime Agent Card');
+        const card = AgentCard.fromJSON(await response.json());
+        const selected = card.supportedInterfaces.find(x => x.protocolVersion === '1.0' && x.protocolBinding === 'JSONRPC');
+        if (!selected)
+            throw new CommerceError('upstream_version', 'Runtime must expose A2A 1.0 JSONRPC');
+        for (const endpoint of card.supportedInterfaces)
+            if (validateUrl(endpoint.url, true).origin !== cardUrl.origin)
+                throw new CommerceError('upstream_origin', 'Runtime interface must share configured Card origin');
+        if (remote?.interfaceUrl && selected.url !== remote.interfaceUrl)
+            throw new CommerceError('upstream_endpoint_changed', 'Original Task interface changed; restore it before recovery');
+        const factory = new ClientFactory({ transports: [new JsonRpcTransportFactory({ fetchImpl: scopedFetch })] });
+        const client = await factory.createFromAgentCard({ ...card, supportedInterfaces: [selected] });
+        return { client, interfaceUrl: selected.url };
+    }
+    function observed(task, interfaceUrl, expectedId) {
+        if (!task || typeof task !== 'object' || !('status' in task) || !('id' in task) || !task.id)
+            throw new CommerceError('upstream_task_required', 'Runtime returned no durable Task handle');
+        const result = task;
+        if (expectedId && result.id !== expectedId)
+            throw new CommerceError('remote_task_conflict', 'Runtime returned a different Task');
+        interfaces.set(result, interfaceUrl);
+        return result;
+    }
+    async function* observe(task, prepared, service) {
+        const deadline = Date.now() + service.contract.targetDurationSeconds * 1000, id = task.id;
+        for (;;) {
+            yield task;
+            if ([TaskState.TASK_STATE_COMPLETED, TaskState.TASK_STATE_FAILED, TaskState.TASK_STATE_CANCELED, TaskState.TASK_STATE_REJECTED, TaskState.TASK_STATE_INPUT_REQUIRED, TaskState.TASK_STATE_AUTH_REQUIRED].includes(task.status?.state ?? 0))
+                return;
+            if (Date.now() >= deadline)
+                throw new CommerceError('execution_pending', 'Read the original Task to continue observing execution');
+            await sleep(1000, undefined, { signal });
+            task = observed(await prepared.client.getTask(GetTaskRequest.fromJSON({ id })), prepared.interfaceUrl, id);
+        }
+    }
+    const execute = async function* (order, service) {
+        const prepared = await prepare(service);
+        const request = SendMessageRequest.fromJSON({ message: { messageId: order.messageId, role: 'ROLE_USER', parts: parts(service, order.input) }, configuration: { returnImmediately: true } });
+        const task = observed(await prepared.client.sendMessage(request), prepared.interfaceUrl);
+        yield* observe(task, prepared, service);
+    };
+    execute.continue = async function* (_order, service, continuation, remote) {
+        const prepared = await prepare(service, remote);
+        const request = SendMessageRequest.fromJSON({ message: { messageId: continuation.messageId, taskId: remote.taskId, ...(remote.contextId ? { contextId: remote.contextId } : {}), role: 'ROLE_USER', parts: parts(service, continuation.input) }, configuration: { returnImmediately: true } });
+        const task = observed(await prepared.client.sendMessage(request), prepared.interfaceUrl, remote.taskId);
+        yield* observe(task, prepared, service);
+    };
+    execute.recover = async (_order, service, remote) => {
+        const prepared = await prepare(service, remote);
+        // Recovery never calls SendMessage, creates a new Task, or retries a dispatch.
+        return observed(await prepared.client.getTask(GetTaskRequest.fromJSON({ id: remote.taskId })), prepared.interfaceUrl, remote.taskId);
+    };
+    execute.remoteInterface = task => interfaces.get(task);
+    return execute;
+}

package/dist/commerce/vault.d.ts

@@ -0,0 +1,8 @@
+/** Original authorizations are encrypted before any external settlement attempt. */
+export declare class CredentialVault {
+    private directory;
+    private readonly key;
+    constructor(directory: string, key: Buffer);
+    put(value: unknown): string;
+    get(id: string): unknown;
+}

package/dist/commerce/vault.js

@@ -0,0 +1,55 @@
+import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, chmodSync, openSync, closeSync, fsyncSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { CommerceError } from './types.js';
+/** Original authorizations are encrypted before any external settlement attempt. */
+export class CredentialVault {
+    directory;
+    key;
+    constructor(directory, key) {
+        this.directory = directory;
+        if (key.length !== 32)
+            throw new CommerceError('vault_key', 'A 32-byte vault encryption key is required');
+        this.key = Buffer.from(key);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        if (!lstatSync(directory).isDirectory())
+            throw new CommerceError('vault_directory', 'Vault must be a real directory');
+        chmodSync(directory, 0o700);
+    }
+    put(value) {
+        const serialized = JSON.stringify(value);
+        if (!serialized || Buffer.byteLength(serialized) > 65536)
+            throw new CommerceError('vault_size', 'Authorization exceeds vault limit');
+        const id = randomUUID(), nonce = randomBytes(12);
+        const cipher = createCipheriv('aes-256-gcm', this.key, nonce);
+        cipher.setAAD(Buffer.from(id));
+        const encrypted = Buffer.concat([cipher.update(serialized, 'utf8'), cipher.final()]);
+        writeFileSync(join(this.directory, id), Buffer.concat([nonce, cipher.getAuthTag(), encrypted]), { mode: 0o600, flag: 'wx', flush: true });
+        // Persist the directory entry before returning a reference to the ledger.
+        const directoryFd = openSync(this.directory, 'r');
+        try {
+            fsyncSync(directoryFd);
+        }
+        finally {
+            closeSync(directoryFd);
+        }
+        return id;
+    }
+    get(id) {
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(id))
+            throw new CommerceError('vault_reference', 'Invalid credential reference');
+        const path = join(this.directory, id), stat = lstatSync(path);
+        if (!stat.isFile() || stat.size < 29 || stat.size > 65564 || (stat.mode & 0o077) !== 0)
+            throw new CommerceError('vault_file', 'Invalid private authorization file');
+        const bytes = readFileSync(path);
+        const cipher = createDecipheriv('aes-256-gcm', this.key, bytes.subarray(0, 12));
+        cipher.setAAD(Buffer.from(id));
+        cipher.setAuthTag(bytes.subarray(12, 28));
+        try {
+            return JSON.parse(Buffer.concat([cipher.update(bytes.subarray(28)), cipher.final()]).toString('utf8'));
+        }
+        catch {
+            throw new CommerceError('vault_integrity', 'Original authorization failed integrity verification');
+        }
+    }
+}

package/dist/commerce/x402.d.ts

@@ -0,0 +1,37 @@
+import { type FacilitatorClient } from '@x402/core/server';
+import type { PaymentPayload, PaymentRequirements, SettleResponse } from '@x402/core/types';
+import { type PaymentProfile } from './types.js';
+import { CommerceStore, type OrderRecord } from './store.js';
+import { CredentialVault } from './vault.js';
+type X402Profile = Extract<PaymentProfile, {
+    adapter: 'x402';
+}>;
+export interface X402GateOptions {
+    store: CommerceStore;
+    vault: CredentialVault;
+    payerFor: (caller: string) => string | undefined;
+    facilitator?: (profile: X402Profile) => FacilitatorClient;
+    verifyReceipt: (receipt: SettleResponse, payload: PaymentPayload, requirements: PaymentRequirements) => Promise<boolean>;
+    /** Read chain before broadcast, so a lost facilitator response remains recoverable. */
+    checkpoint?: (requirements: PaymentRequirements) => Promise<string>;
+    findOriginalReceipt?: (payload: PaymentPayload, requirements: PaymentRequirements, fromBlock: string) => Promise<SettleResponse | undefined>;
+}
+export type GateResult = {
+    response: Response;
+} | {
+    headers: Record<string, string>;
+};
+/** Official x402 v2 exact settlement, with independent chain evidence before work. */
+export declare class X402Gate {
+    private options;
+    private servers;
+    constructor(options: X402GateOptions);
+    check(profiles: readonly X402Profile[]): Promise<void>;
+    recover(orderId: string, caller: string): Promise<{
+        state: string;
+        taskId: string;
+    }>;
+    private resource;
+    handle(request: Request, order: OrderRecord): Promise<GateResult>;
+}
+export {};

package/dist/commerce/x402.js

@@ -0,0 +1,174 @@
+import { findDefaultAsset } from '@x402/evm';
+import { x402ResourceServer, HTTPFacilitatorClient } from '@x402/core/server';
+import { decodePaymentSignatureHeader, encodePaymentRequiredHeader, encodePaymentResponseHeader } from '@x402/core/http';
+import { ExactEvmScheme } from '@x402/evm/exact/server';
+import { PAYMENT_IDENTIFIER, declarePaymentIdentifierExtension, extractPaymentIdentifier, validatePaymentIdentifier, paymentIdentifierResourceServerExtension, } from '@x402/extensions/payment-identifier';
+import { CommerceError } from './types.js';
+import { digest } from './config.js';
+/** Official x402 v2 exact settlement, with independent chain evidence before work. */
+export class X402Gate {
+    options;
+    servers = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async check(profiles) {
+        for (const profile of profiles) {
+            const { facilitator } = await this.resource(profile);
+            const supported = await facilitator.getSupported();
+            if (!supported.kinds.some(k => k.x402Version === 2 && k.scheme === 'exact' && k.network === profile.network))
+                throw new CommerceError('facilitator_network', 'Configured facilitator does not support exact payments on this network');
+            if (this.options.checkpoint)
+                await this.options.checkpoint({ scheme: 'exact', network: profile.network, asset: profile.asset, payTo: profile.payTo, amount: '1', maxTimeoutSeconds: 300, extra: {} });
+        }
+    }
+    async recover(orderId, caller) {
+        const order = this.options.store.getOrder(orderId, caller);
+        if (!order)
+            throw new CommerceError('order_not_found', 'Order not found for this buyer');
+        const attempt = this.options.store.paymentForOrder(order.id);
+        if (!attempt)
+            throw new CommerceError('attempt_not_found', 'No original payment to recover');
+        if (attempt.state === 'confirmed')
+            return { state: 'confirmed', taskId: order.taskId };
+        if (attempt.state === 'rejected')
+            return { state: 'rejected', taskId: order.taskId };
+        const saved = this.options.vault.get(attempt.credentialRef);
+        const required = this.options.store.paymentChallenge(order.id);
+        if (saved.quoteId !== order.quote.quoteId || !required?.accepts.some(r => digest(r) === digest(saved.requirements))) {
+            throw new CommerceError('recovery_conflict', 'Stored authorization differs from the frozen challenge');
+        }
+        let receipt = attempt.receipt;
+        if (!receipt?.transaction && saved.fromBlock && this.options.findOriginalReceipt) {
+            receipt = await this.options.findOriginalReceipt(saved.payload, saved.requirements, saved.fromBlock) ?? null;
+        }
+        if (!receipt?.transaction)
+            return { state: 'unknown', taskId: order.taskId };
+        let proven = false;
+        try {
+            proven = await this.options.verifyReceipt(receipt, saved.payload, saved.requirements);
+        }
+        catch { }
+        // Persist the discovered transaction even if confirmations are still pending.
+        this.options.store.recordSettlement(attempt.id, proven ? 'confirmed' : 'unknown', receipt);
+        return { state: proven ? 'confirmed' : 'unknown', taskId: order.taskId };
+    }
+    async resource(profile) {
+        const key = digest(profile);
+        let promise = this.servers.get(key);
+        if (!promise) {
+            promise = (async () => {
+                const facilitator = this.options.facilitator?.(profile) ?? new HTTPFacilitatorClient({ url: profile.facilitatorUrl });
+                const server = new x402ResourceServer(facilitator)
+                    .register(profile.network, new ExactEvmScheme())
+                    .registerExtension(paymentIdentifierResourceServerExtension);
+                await server.initialize();
+                return { server, facilitator };
+            })();
+            this.servers.set(key, promise);
+            void promise.catch(() => this.servers.delete(key));
+        }
+        return promise;
+    }
+    async handle(request, order) {
+        const profile = order.quote.paymentProfile;
+        if (profile?.adapter !== 'x402')
+            throw new CommerceError('payment_method_unavailable', 'This offer requires another installed payment adapter');
+        const previous = this.options.store.paymentForOrder(order.id);
+        if (order.paymentState === 'confirmed' && previous?.receipt) {
+            return { headers: { 'PAYMENT-RESPONSE': encodePaymentResponseHeader(previous.receipt) } };
+        }
+        if (['settling', 'unknown'].includes(order.paymentState)) {
+            const recovered = await this.recover(order.id, order.caller);
+            if (recovered.state === 'confirmed') {
+                const receipt = this.options.store.paymentForOrder(order.id).receipt;
+                return { headers: { 'PAYMENT-RESPONSE': encodePaymentResponseHeader(receipt) } };
+            }
+            return { response: Response.json({ error: 'payment_reconciliation_required', taskId: order.taskId }, { status: 503, headers: { 'Cache-Control': 'no-store' } }) };
+        }
+        if (Date.now() >= Date.parse(order.quote.expiresAt))
+            return { response: Response.json({ error: 'quote_expired' }, { status: 409 }) };
+        const { server, facilitator } = await this.resource(profile);
+        let required = this.options.store.paymentChallenge(order.id);
+        if (!required) {
+            const token = findDefaultAsset(profile.asset, profile.network);
+            if (!token)
+                throw new CommerceError('unsupported_asset', 'Official token signing domain is unavailable');
+            const requirements = await server.buildPaymentRequirements({
+                scheme: 'exact', network: profile.network, payTo: profile.payTo,
+                price: { asset: profile.asset, amount: order.quote.amount, extra: { name: token.name, version: token.version } },
+                maxTimeoutSeconds: 300, extra: { paymentFlow: 'upfront', assetTransferMethod: 'eip3009' },
+            });
+            const resource = new URL(request.url);
+            resource.search = '';
+            resource.searchParams.set('quote', order.quote.quoteId);
+            required = this.options.store.freezePaymentChallenge(order.id, await server.createPaymentRequiredResponse(requirements, { url: resource.href, description: order.quote.serviceId, mimeType: 'application/json' }, undefined, { [PAYMENT_IDENTIFIER]: declarePaymentIdentifierExtension(false), 'urn:envarpay:quote:1': { info: { quoteId: order.quote.quoteId, messageId: order.messageId, serviceId: order.quote.serviceId, serviceRevision: order.quote.serviceRevision, offerId: order.offerId, inputDigest: order.inputDigest, termsDigest: order.quote.termsDigest, expiresAt: order.quote.expiresAt, amount: order.quote.amount, currency: order.quote.currency, recipient: order.quote.recipient } } }));
+        }
+        // Identifier is optional for unextended standard clients; nonce dedup is mandatory.
+        const challenge = () => ({ response: new Response('{}', {
+                status: 402, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store', 'PAYMENT-REQUIRED': encodePaymentRequiredHeader(required) },
+            }) });
+        const header = request.headers.get('PAYMENT-SIGNATURE');
+        if (!header)
+            return challenge();
+        if (header.length > 32768)
+            throw new CommerceError('payment_payload_size', 'Payment credential exceeds limit');
+        let payload;
+        try {
+            payload = decodePaymentSignatureHeader(header);
+        }
+        catch {
+            throw new CommerceError('invalid_payment', 'Malformed payment credential');
+        }
+        const matched = server.findMatchingRequirements(required.accepts, payload);
+        if (!matched || payload.x402Version !== 2 || payload.resource?.url !== required.resource.url || digest(payload.accepted) !== digest(matched)) {
+            throw new CommerceError('quote_mismatch', 'Payment does not match the frozen quote');
+        }
+        const extension = payload.extensions?.[PAYMENT_IDENTIFIER];
+        // Validate against our schema; never compile a schema supplied by the buyer.
+        if (extension !== undefined && !validatePaymentIdentifier({ info: extension?.info, schema: declarePaymentIdentifierExtension(false).schema }).valid) {
+            throw new CommerceError('invalid_payment_identifier', 'Invalid standard payment identifier');
+        }
+        const identifier = extractPaymentIdentifier(payload, false);
+        const native = payload.payload;
+        const auth = native.authorization;
+        const payer = this.options.payerFor(order.caller);
+        if (!payer || !auth?.from || auth.from.toLowerCase() !== payer.toLowerCase() || auth.to?.toLowerCase() !== profile.payTo.toLowerCase() || auth.value !== order.quote.amount || !/^0x[0-9a-fA-F]{64}$/.test(auth.nonce ?? '') || !native.signature) {
+            throw new CommerceError('payment_identity', 'Signed payer, recipient, amount and nonce must match authorized buyer and quote');
+        }
+        // Quote UI metadata is locally checked above. It is not a facilitator
+        // settlement extension; do not require third-party facilitators to implement it.
+        const settlementPayload = { ...payload, extensions: Object.fromEntries(Object.entries(payload.extensions ?? {}).filter(([key]) => key !== 'urn:envarpay:quote:1')) };
+        // Upfront SDK verification may skip /verify; explicitly perform it before reserve.
+        const verified = await facilitator.verify(settlementPayload, matched);
+        if (!verified.isValid)
+            return challenge();
+        if (verified.payer && verified.payer.toLowerCase() !== payer.toLowerCase())
+            throw new CommerceError('payment_identity', 'Verified payer differs from authorized buyer');
+        const economicKey = digest({ network: profile.network, asset: profile.asset.toLowerCase(), payer: payer.toLowerCase(), nonce: auth.nonce.toLowerCase() });
+        const fromBlock = await this.options.checkpoint?.(matched);
+        const saved = { payload, requirements: matched, quoteId: order.quote.quoteId, ...(fromBlock !== undefined ? { fromBlock } : {}) };
+        const credentialRef = this.options.vault.put(saved);
+        const attempt = this.options.store.reservePayment(order.id, order.caller, economicKey, credentialRef, identifier ?? undefined);
+        let result;
+        try {
+            result = await server.settlePayment(settlementPayload, matched, undefined, undefined, undefined, 'before-handler');
+        }
+        catch {
+            this.options.store.recordSettlement(attempt, 'unknown', {});
+            return { response: Response.json({ error: 'payment_outcome_unknown' }, { status: 503 }) };
+        }
+        // A failure can follow broadcast. Never create a second economic authorization.
+        let proven = false;
+        if (result.success) {
+            try {
+                proven = await this.options.verifyReceipt(result, payload, matched);
+            }
+            catch { }
+        }
+        this.options.store.recordSettlement(attempt, proven ? 'confirmed' : 'unknown', result);
+        if (!proven)
+            return { response: Response.json({ error: result.success ? 'receipt_verification_pending' : 'payment_outcome_unknown' }, { status: 503 }) };
+        return { headers: { 'PAYMENT-RESPONSE': encodePaymentResponseHeader(result) } };
+    }
+}

package/dist/index.js

@@ -1,5 +1,7 @@
+import { createRequire } from 'node:module';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+const packageIdentity = createRequire(import.meta.url)('../package.json');
 /** A wallet refusal or execution error, preserved from the MCP tool response. */
 export class WalletToolError extends Error {
     tool;
@@ -55,7 +57,7 @@ export class WalletClient {
         const timeoutMs = options.timeoutMs ?? 300_000;
         if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
             throw new TypeError('timeoutMs must be positive');
-        const client = new Client({ name: '@envarai/envarpay', version: '0.1.0-alpha.2' });
+        const client = new Client({ name: packageIdentity.name, version: packageIdentity.version });
         const transport = new StreamableHTTPClientTransport(url, {
             requestInit: { headers: { Authorization: `Bearer ${options.token}` }, redirect: 'error' },
         });

package/examples/buyer-policy.json

@@ -0,0 +1,18 @@
+{
+  "policyVersion":1,
+  "paymentsEnabled":false,
+  "approval":"per_purchase",
+  "peers":[{
+    "id":"research-seller",
+    "cardUrl":"https://seller.example/services/research/v1/offers/usdc-once/agent-card.json",
+    "protocol":"x402",
+    "currency":"eip155:84532/erc20:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    "recipient":"0x2222222222222222222222222222222222222222",
+    "maxPerPurchase":"3000000"
+  }],
+  "budgets":[{
+    "currency":"eip155:84532/erc20:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    "maxTotal":"10000000",
+    "period":"cumulative"
+  }]
+}