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

package/dist/commerce/card.d.ts

@@ -0,0 +1,5 @@
+import { AgentCard } from '@a2a-js/sdk';
+import type { CommerceConfig } from './types.js';
+/** One deterministic offer route, serialized by the official A2A 1.0 codec. */
+export declare function offerPath(serviceId: string, revision: number, offerId: string): string;
+export declare function createOfferCard(config: CommerceConfig, serviceId: string, offerId: string, origin: string): AgentCard;

package/dist/commerce/card.js

@@ -0,0 +1,29 @@
+import { AgentCard } from '@a2a-js/sdk';
+import { CommerceError } from './types.js';
+import { validateUrl, digest } 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)}`;
+}
+export function createOfferCard(config, serviceId, offerId, origin) {
+    const base = validateUrl(origin, true);
+    if (base.search || base.pathname !== '/')
+        throw new CommerceError('invalid_origin', 'Origin must not contain a path or query');
+    const service = config.services.find(x => x.id === serviceId);
+    const offer = service?.offers.find(x => x.id === offerId);
+    if (!service || !offer)
+        throw new CommerceError('offer_not_found', 'Service offer not found');
+    const profile = offer.paymentProfile ? config.paymentProfiles[offer.paymentProfile] : null;
+    const payment = profile?.adapter === 'x402' ? { adapter: 'x402', network: profile.network, asset: profile.asset, payTo: profile.payTo } : profile ? { adapter: 'mpp', method: 'stripe', intent: 'charge', currency: profile.currency } : null;
+    return AgentCard.fromJSON({
+        name: service.name,
+        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 }) } }] },
+        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' } } },
+        securityRequirements: [{ schemes: { bearer: { list: [] } } }],
+    });
+}

package/dist/commerce/chain.d.ts

@@ -0,0 +1,24 @@
+import type { PaymentPayload, PaymentRequirements, SettleResponse } from '@x402/core/types';
+export interface ExpiredUnusedProof {
+    expiredUnused: true;
+    network: string;
+    asset: string;
+    payer: string;
+    nonce: string;
+    validAfter: string;
+    validBefore: string;
+    blockNumber: string;
+    blockHash: string;
+    blockTimestamp: string;
+    finality: 'finalized';
+    authorizationUsed: false;
+}
+/** Checks the canonical chain receipt and exact official-token Transfer. */
+export declare function evmReceiptVerifier(rpcUrls: Readonly<Record<string, string>>, confirmations?: number): (receipt: SettleResponse, payload: PaymentPayload, requirements: PaymentRequirements) => Promise<boolean>;
+/** Locate an original EIP-3009 settlement even when facilitator lost its tx response. */
+export declare function evmSettlementRecovery(rpcUrls: Readonly<Record<string, string>>): {
+    expiredUnusedProof: (payload: PaymentPayload, requirements: PaymentRequirements) => Promise<ExpiredUnusedProof | undefined>;
+    proveExpiredUnused: (payload: PaymentPayload, requirements: PaymentRequirements) => Promise<boolean>;
+    checkpoint: (requirements: PaymentRequirements) => Promise<string>;
+    findOriginalReceipt: (payload: PaymentPayload, requirements: PaymentRequirements, fromBlock: string) => Promise<SettleResponse | undefined>;
+};

package/dist/commerce/chain.js

@@ -0,0 +1,146 @@
+import { createPublicClient, http, decodeEventLog, parseAbi } from 'viem';
+import { CommerceError } from './types.js';
+import { validateUrl } from './config.js';
+const abi = parseAbi(['event Transfer(address indexed from, address indexed to, uint256 value)']);
+const authorizationAbi = parseAbi(['event AuthorizationUsed(address indexed authorizer, bytes32 indexed nonce)']);
+const authorizationStateAbi = parseAbi(['function authorizationState(address authorizer,bytes32 nonce) view returns (bool)']);
+const officialUsdc = {
+    'eip155:84532': '0x036cbd53842c5426634e7929541ec2318f3dcf7e',
+    'eip155:8453': '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+};
+/** Checks the canonical chain receipt and exact official-token Transfer. */
+export function evmReceiptVerifier(rpcUrls, confirmations = 2) {
+    if (!Number.isInteger(confirmations) || confirmations < 1)
+        throw new CommerceError('confirmation_policy', 'Positive confirmation depth required');
+    return async (receipt, payload, requirements) => {
+        const rpc = rpcUrls[requirements.network];
+        if (!rpc)
+            throw new CommerceError('rpc_missing', 'Configure the settlement network RPC');
+        validateUrl(rpc, true);
+        const chainId = Number(requirements.network.split(':')[1]);
+        if (!Number.isSafeInteger(chainId) || !/^0x[0-9a-fA-F]{64}$/.test(receipt.transaction) || receipt.network !== requirements.network)
+            return false;
+        const client = createPublicClient({ transport: http(rpc, { timeout: 15000, retryCount: 0 }) });
+        if (await client.getChainId() !== chainId)
+            return false;
+        const mined = await client.getTransactionReceipt({ hash: receipt.transaction });
+        if (mined.status !== 'success')
+            return false;
+        const block = await client.getBlock({ blockNumber: mined.blockNumber });
+        if (block.hash !== mined.blockHash)
+            return false;
+        const latest = await client.getBlockNumber();
+        if (latest - mined.blockNumber + 1n < BigInt(confirmations))
+            return false;
+        const auth = payload.payload.authorization;
+        if (!auth?.from || !auth.nonce || auth.to?.toLowerCase() !== requirements.payTo.toLowerCase() || auth.value !== requirements.amount)
+            return false;
+        if (receipt.payer && receipt.payer.toLowerCase() !== auth.from.toLowerCase())
+            return false;
+        const matches = mined.logs.filter(log => {
+            if (log.address.toLowerCase() !== requirements.asset.toLowerCase())
+                return false;
+            try {
+                const event = decodeEventLog({ abi, data: log.data, topics: log.topics });
+                return event.args.from.toLowerCase() === auth.from.toLowerCase() && event.args.to.toLowerCase() === requirements.payTo.toLowerCase() && event.args.value === BigInt(requirements.amount);
+            }
+            catch {
+                return false;
+            }
+        });
+        const authorizations = mined.logs.filter(log => {
+            if (log.address.toLowerCase() !== requirements.asset.toLowerCase())
+                return false;
+            try {
+                const event = decodeEventLog({ abi: authorizationAbi, data: log.data, topics: log.topics });
+                return event.args.authorizer.toLowerCase() === auth.from.toLowerCase() && event.args.nonce.toLowerCase() === auth.nonce.toLowerCase();
+            }
+            catch {
+                return false;
+            }
+        });
+        return matches.length === 1 && authorizations.length === 1;
+    };
+}
+/** Locate an original EIP-3009 settlement even when facilitator lost its tx response. */
+export function evmSettlementRecovery(rpcUrls) {
+    const clientFor = async (requirements) => {
+        const rpc = rpcUrls[requirements.network];
+        if (!rpc)
+            throw new CommerceError('rpc_missing', 'Configure the settlement network RPC');
+        validateUrl(rpc, true);
+        const client = createPublicClient({ transport: http(rpc, { timeout: 15000, retryCount: 0 }) });
+        if (await client.getChainId() !== Number(requirements.network.split(':')[1]))
+            throw new CommerceError('rpc_network', 'RPC network does not match frozen requirements');
+        return client;
+    };
+    const expiredUnusedProof = async (payload, requirements) => {
+        try {
+            const asset = officialUsdc[requirements.network];
+            if (!asset || typeof requirements.asset !== 'string' || requirements.asset.toLowerCase() !== asset)
+                return undefined;
+            const auth = payload.payload?.authorization;
+            if (!auth || !/^0x[0-9a-fA-F]{40}$/.test(auth.from ?? '') || !/^0x[0-9a-fA-F]{64}$/.test(auth.nonce ?? '') ||
+                auth.to?.toLowerCase() !== requirements.payTo.toLowerCase() || auth.value !== requirements.amount ||
+                !/^(0|[1-9][0-9]{0,77})$/.test(auth.validAfter ?? '') || !/^(0|[1-9][0-9]{0,77})$/.test(auth.validBefore ?? ''))
+                return undefined;
+            const validAfter = BigInt(auth.validAfter), validBefore = BigInt(auth.validBefore);
+            if (validAfter >= validBefore || validBefore >= 2n ** 256n)
+                return undefined;
+            const client = await clientFor(requirements);
+            const finalized = await client.getBlock({ blockTag: 'finalized' });
+            if (finalized.number === null || !/^0x[0-9a-fA-F]{64}$/.test(finalized.hash ?? '') ||
+                finalized.timestamp < validBefore || finalized.timestamp < validAfter)
+                return undefined;
+            // A missing nonce log is not proof. Read the official token's state at
+            // the exact finalized block, after this authorization can no longer execute.
+            const used = await client.readContract({ address: asset, abi: authorizationStateAbi, functionName: 'authorizationState',
+                args: [auth.from, auth.nonce], blockNumber: finalized.number });
+            if (used !== false)
+                return undefined;
+            const canonical = await client.getBlock({ blockNumber: finalized.number });
+            if (canonical.hash !== finalized.hash || canonical.number !== finalized.number || canonical.timestamp !== finalized.timestamp)
+                return undefined;
+            return { expiredUnused: true, network: requirements.network, asset, payer: auth.from.toLowerCase(), nonce: auth.nonce.toLowerCase(),
+                validAfter: auth.validAfter, validBefore: auth.validBefore, blockNumber: finalized.number.toString(),
+                blockHash: finalized.hash, blockTimestamp: finalized.timestamp.toString(), finality: 'finalized', authorizationUsed: false };
+        }
+        catch {
+            // Unsupported finalized tags, archive state gaps, malformed return values
+            // and network errors retain the original unknown operation and its budget.
+            return undefined;
+        }
+    };
+    return {
+        expiredUnusedProof,
+        proveExpiredUnused: async (payload, requirements) => !!await expiredUnusedProof(payload, requirements),
+        checkpoint: async (requirements) => {
+            const client = await clientFor(requirements);
+            const block = await client.getBlockNumber();
+            return (block > 12n ? block - 12n : 0n).toString();
+        },
+        findOriginalReceipt: async (payload, requirements, fromBlock) => {
+            if (!/^(0|[1-9][0-9]*)$/.test(fromBlock))
+                throw new CommerceError('recovery_checkpoint', 'Invalid original chain checkpoint');
+            const auth = payload.payload.authorization;
+            if (!/^0x[0-9a-fA-F]{40}$/.test(auth?.from ?? '') || !/^0x[0-9a-fA-F]{64}$/.test(auth?.nonce ?? ''))
+                throw new CommerceError('invalid_payment', 'Missing original EIP-3009 identity');
+            const client = await clientFor(requirements);
+            const latest = await client.getBlockNumber();
+            // Bounded per reconciliation. Very old operations need an operator/archive
+            // RPC lookup; never reinterpret incomplete search as proof of non-payment.
+            if (latest - BigInt(fromBlock) > 100000n)
+                throw new CommerceError('archive_reconciliation_required', 'Original authorization requires an archive log lookup');
+            for (let start = BigInt(fromBlock); start <= latest; start += 2000n) {
+                const end = start + 1999n < latest ? start + 1999n : latest;
+                const logs = await client.getLogs({ address: requirements.asset, event: authorizationAbi[0], args: { authorizer: auth.from, nonce: auth.nonce }, fromBlock: start, toBlock: end, strict: true });
+                const settled = logs.filter(log => !log.removed && log.transactionHash);
+                if (settled.length > 1)
+                    throw new CommerceError('ambiguous_receipt', 'Multiple authorization events require manual reconciliation');
+                if (settled.length === 1)
+                    return { success: true, transaction: settled[0].transactionHash, network: requirements.network, payer: auth.from };
+            }
+            return undefined;
+        },
+    };
+}

package/dist/commerce/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/commerce/cli.js

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+import { readFileSync, lstatSync, mkdirSync, writeFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { createRequire } from 'node:module';
+import { randomBytes } from 'node:crypto';
+import { once } from 'node:events';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { privateKeyToAccount } from 'viem/accounts';
+import { AgentCard } from '@a2a-js/sdk';
+import { loadCommerceConfig, loadBuyerPolicy, digest } from './config.js';
+import { createOfferCard } from './card.js';
+import { CommerceStore } from './store.js';
+import { CommerceServer, bearerAuthenticator } from './server.js';
+import { EnvarIntegration } from './envar.js';
+import { EnvarSellerRuntime, PinnedUpstreams, restoreEnvarConfig } from './envar-runtime.js';
+import { listenCommerce } from './http.js';
+import { CredentialVault } from './vault.js';
+import { X402Gate } from './x402.js';
+import { evmReceiptVerifier, evmSettlementRecovery } from './chain.js';
+import { CommerceError } from './types.js';
+const { values, positionals } = parseArgs({ allowPositionals: true, options: {
+        config: { type: 'string' }, service: { type: 'string' }, offer: { type: 'string' }, origin: { type: 'string' },
+        version: { type: 'boolean' }, help: { type: 'boolean', short: 'h' }, state: { type: 'string' }, credentials: { type: 'string' }, host: { type: 'string' },
+        port: { type: 'string' }, directory: { type: 'string' }, 'envar-config': { type: 'string' }, 'envar-credentials': { type: 'string' },
+    } });
+const usage = 'envarpay init --directory DIR | validate --config seller.json | card --config seller.json --service ID --offer ID --origin URL | serve/buyer-serve --config FILE --credentials FILE --state DB --origin URL';
+const closers = [];
+function privateFile(path) {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || stat.size > 1024 * 1024)
+        throw new CommerceError('private_file', 'Credentials must be bounded owner-only files (chmod 600)');
+    return readFileSync(path);
+}
+function port(defaultPort) {
+    const result = Number(values.port ?? defaultPort);
+    if (!Number.isInteger(result) || result < 1 || result > 65535)
+        throw new CommerceError('listen_port', 'Invalid listen port');
+    return result;
+}
+function signals() {
+    let stopping = false;
+    const stop = async () => {
+        if (stopping)
+            return;
+        stopping = true;
+        const deadline = setTimeout(() => process.exit(1), 60000);
+        deadline.unref();
+        let failed = false;
+        for (const close of closers.reverse()) {
+            try {
+                await close();
+            }
+            catch {
+                failed = true;
+            }
+        }
+        clearTimeout(deadline);
+        process.exit(failed ? 1 : 0);
+    };
+    process.once('SIGTERM', () => void stop());
+    process.once('SIGINT', () => void stop());
+}
+async function closeHttp(http) {
+    await new Promise((resolve, reject) => http.close(error => error ? reject(error) : resolve()));
+}
+async function loadMppAdapter(path) {
+    privateFile(path);
+    const module = await import(pathToFileURL(resolve(path)).href);
+    if (typeof module.createMppBuyerOptions !== 'function')
+        throw new CommerceError('mpp_adapter_module', 'Owner-supplied module must export createMppBuyerOptions');
+    const options = await module.createMppBuyerOptions();
+    if (!options || typeof options.createToken !== 'function' || typeof options.recoverToken !== 'function' || typeof options.verifyReceipt !== 'function')
+        throw new CommerceError('mpp_adapter_module', 'MPP requires real token creation, original-operation recovery and receipt verification');
+    return options;
+}
+async function run() {
+    if (values.help || positionals.length === 0 && !values.version) {
+        console.log(usage);
+        return;
+    }
+    if (values.version) {
+        console.log(createRequire(import.meta.url)('../../package.json').version);
+        return;
+    }
+    const command = positionals[0];
+    if ((values['envar-config'] || values['envar-credentials']) && command !== 'serve')
+        throw new CommerceError('envar_role', 'Configuration synchronization is available on seller serve only');
+    if (Boolean(values['envar-config']) !== Boolean(values['envar-credentials']))
+        throw new CommerceError('envar_configuration', 'Supply both --envar-config and --envar-credentials');
+    if (command === 'init' && values.directory) {
+        mkdirSync(values.directory, { recursive: true, mode: 0o700 });
+        for (const [name, source] of [['seller.json', 'seller.json'], ['buyer-policy.json', 'buyer-policy.json']]) {
+            writeFileSync(join(values.directory, name), readFileSync(new URL(`../../examples/${source}`, import.meta.url)), { flag: 'wx', mode: 0o600 });
+        }
+        writeFileSync(join(values.directory, 'vault.key'), randomBytes(32), { flag: 'wx', mode: 0o600, flush: true });
+        console.log(JSON.stringify({ directory: values.directory, configured: false, paymentPerformed: false, next: 'Review placeholder addresses, prices, runtime and private credential files before serve' }));
+        return;
+    }
+    if (!values.config)
+        throw new CommerceError('usage', usage);
+    const raw = JSON.parse(readFileSync(values.config, 'utf8'));
+    if (command === 'buyer-serve') {
+        if (!values.origin || !values.state || !values.credentials)
+            throw new CommerceError('usage', usage);
+        const policy = loadBuyerPolicy(raw);
+        const secrets = JSON.parse(privateFile(values.credentials).toString('utf8'));
+        const needsEvm = policy.peers.some(peer => peer.protocol === 'x402'), needsMpp = policy.peers.some(peer => peer.protocol === 'mpp');
+        if (!secrets.peerTokens || (needsEvm || needsMpp) && !secrets.vaultKeyFile)
+            throw new CommerceError('buyer_credentials', 'Paid buyer needs private vault key and peer credentials');
+        let signer;
+        if (needsEvm) {
+            if (!secrets.privateKeyFile || !secrets.rpcUrls)
+                throw new CommerceError('buyer_credentials', 'x402 peers require local signer and RPC configuration');
+            const key = privateFile(secrets.privateKeyFile).toString('utf8').trim();
+            if (!/^0x[0-9a-fA-F]{64}$/.test(key))
+                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;
+        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,
+            signer, mpp, peerTokens: secrets.peerTokens, peerEndpoints: secrets.peerEndpoints,
+            ...(needsEvm ? { verifyReceipt: evmReceiptVerifier(secrets.rpcUrls), ...evmSettlementRecovery(secrets.rpcUrls) } : {}) });
+        closers.push(() => buyer.stop());
+        if (secrets.peerProxies?.length) {
+            if (secrets.peerProxies.length > 8)
+                throw new CommerceError('proxy_limit', 'Configure at most8 explicit peer proxies per buyer');
+            const { A2APeerProxy, listenPeerProxy } = await import('./peer-proxy.js');
+            for (const settings of secrets.peerProxies) {
+                if (Object.keys(settings.tokens).some(token => Object.hasOwn(secrets.callers, token)))
+                    throw new CommerceError('proxy_token_scope', 'Agent proxy tokens must differ from owner management credentials');
+                if (!Number.isInteger(settings.port) || settings.port < 1 || settings.port > 65535)
+                    throw new CommerceError('proxy_port', 'Invalid proxy listen port');
+                const proxy = new A2APeerProxy({ ...settings, buyer });
+                closers.push(async () => { await proxy.stop(); proxy.close(); });
+                const listener = listenPeerProxy(proxy, settings.host ?? '127.0.0.1', settings.port);
+                closers.push(() => closeHttp(listener));
+                await once(listener, 'listening');
+            }
+        }
+        const management = new BuyerManagement({ buyer, origin: values.origin, authenticate: bearerAuthenticator(secrets.callers) });
+        const http = listenBuyerManagement(management, values.origin, values.host ?? '127.0.0.1', port(4021));
+        closers.push(() => closeHttp(http));
+        await once(http, 'listening');
+        buyer.start();
+        signals();
+        console.log(JSON.stringify({ listening: port(4021), role: 'buyer', paymentsEnabled: policy.paymentsEnabled }));
+        return;
+    }
+    let config = loadCommerceConfig(raw);
+    if (command === 'validate') {
+        console.log(JSON.stringify({ valid: true, digest: digest(config), services: config.services.length, paymentPerformed: false }));
+        return;
+    }
+    if (command === 'card' && values.service && values.offer && values.origin) {
+        console.log(JSON.stringify(AgentCard.toJSON(createOfferCard(config, values.service, values.offer, values.origin)), null, 2));
+        return;
+    }
+    if (command !== 'serve' || !values.origin || !values.state || !values.credentials)
+        throw new CommerceError('usage', usage);
+    const secrets = JSON.parse(privateFile(values.credentials).toString('utf8'));
+    let integration, syncSettings;
+    if (values['envar-config']) {
+        syncSettings = JSON.parse(privateFile(values['envar-config']).toString('utf8'));
+        if (!syncSettings?.policy)
+            throw new CommerceError('envar_configuration', 'Envar settings must include an explicit local policy');
+        const tokenFile = resolve(values['envar-credentials']);
+        privateFile(tokenFile);
+        integration = new EnvarIntegration({ policy: syncSettings.policy, stateDirectory: syncSettings.stateDirectory ?? join(dirname(values.state), 'envar-state'), configDirectory: syncSettings.configDirectory ?? join(dirname(values.state), 'envar-configs'), token: () => privateFile(tokenFile).toString('utf8').trim() });
+        closers.push(() => integration.close());
+    }
+    const controller = new AbortController();
+    const store = new CommerceStore(values.state);
+    closers.push(() => store.close());
+    if (integration)
+        config = restoreEnvarConfig(config, integration, store.catalogHistory());
+    const protocols = new Set(Object.values(config.paymentProfiles).map(p => p.adapter));
+    for (const historical of store.catalogHistory())
+        for (const profile of Object.values(historical.profiles))
+            protocols.add(profile.adapter);
+    if (syncSettings?.policy.allowedX402.length)
+        protocols.add('x402');
+    if (syncSettings?.policy.allowedMppAccounts.length)
+        protocols.add('mpp');
+    let vault;
+    if (protocols.size) {
+        if (!secrets.vaultKeyFile)
+            throw new CommerceError('vault_key', 'Paid services require a private vault key file');
+        vault = new CredentialVault(join(dirname(values.state), 'authorizations'), privateFile(secrets.vaultKeyFile));
+    }
+    const gates = {};
+    let stripeRecipientFor;
+    if (protocols.has('x402')) {
+        if (!secrets.payers || !secrets.rpcUrls)
+            throw new CommerceError('x402_configuration', 'x402 requires explicit caller-payer bindings and network RPCs');
+        const gate = new X402Gate({ store, vault: vault, payerFor: caller => secrets.payers?.[caller], verifyReceipt: evmReceiptVerifier(secrets.rpcUrls), ...evmSettlementRecovery(secrets.rpcUrls) });
+        await gate.check(Object.values(config.paymentProfiles).filter((p) => p.adapter === 'x402'));
+        gates.x402 = gate;
+    }
+    if (protocols.has('mpp')) {
+        if (!secrets.stripe || !secrets.mppHmacKeyFile)
+            throw new CommerceError('mpp_configuration', 'MPP requires private Stripe credentials and a separate challenge key');
+        const { MppGate } = await import('./mpp.js'), { stripeProvider } = await import('./stripe-provider.js');
+        const providers = Object.fromEntries(Object.entries(secrets.stripe).map(([ref, p]) => [ref, stripeProvider({ ...p, secretKey: privateFile(p.secretKeyFile).toString('utf8').trim() })]));
+        const hmacKey = privateFile(secrets.mppHmacKeyFile);
+        if (hmacKey.length < 32)
+            throw new CommerceError('mpp_hmac_key', 'MPP requires a private challenge key of at least32 random bytes');
+        const gate = new MppGate({ store, vault: vault, origin: values.origin, hmacSecret: hmacKey.toString('base64'), providers });
+        await gate.check();
+        gates.mpp = gate;
+        stripeRecipientFor = ref => gate.merchantRecipient(ref);
+    }
+    const upstreams = new PinnedUpstreams(join(dirname(values.state), 'upstream-bindings.json'), secrets.upstreams, secrets.upstreamInputEncoding, fetch, controller.signal);
+    upstreams.prepare(config, store.catalogHistory().map(entry => entry.service));
+    const validateAdapters = (candidate) => {
+        for (const profile of Object.values(candidate.paymentProfiles)) {
+            if (!gates[profile.adapter])
+                throw new CommerceError('payment_method_unavailable', 'Configure the payment adapter locally before enabling this service');
+            if (profile.adapter === 'x402' && !secrets.rpcUrls?.[profile.network])
+                throw new CommerceError('x402_configuration', 'Configure the required network RPC locally');
+            if (profile.adapter === 'mpp' && !stripeRecipientFor?.(profile.accountRef))
+                throw new CommerceError('mpp_configuration', 'Configure and verify the merchant account locally');
+        }
+    };
+    validateAdapters(config);
+    const server = new CommerceServer({ config, origin: values.origin, store, stripeRecipientFor, ownershipChallenges: secrets.ownershipChallenges,
+        authenticate: bearerAuthenticator(secrets.callers), execute: upstreams.execute,
+        paymentGate: { handle: async (request, order) => {
+                const adapter = order.quote.paymentProfile?.adapter, gate = adapter ? gates[adapter] : undefined;
+                if (!gate)
+                    throw new CommerceError('payment_method_unavailable', 'Configured payment adapter is unavailable');
+                return gate.handle(request, order);
+            } }, onError: (code, orderId) => console.error(JSON.stringify({ code, orderId })) });
+    closers.push(async () => { server.stop(); controller.abort(); while (server.isRunning)
+        await new Promise(r => setTimeout(r, 50)); });
+    let connection;
+    if (integration) {
+        connection = new EnvarSellerRuntime({ integration, server, upstreams, pollIntervalMs: syncSettings?.pollIntervalMs, validateConfig: validateAdapters, onError: code => console.error(JSON.stringify({ code, integration: 'envar' })) });
+        closers.push(() => connection.stop());
+    }
+    const http = listenCommerce(server, values.origin, values.host ?? '127.0.0.1', port(4020));
+    closers.push(async () => { server.stop(); controller.abort(); await closeHttp(http); });
+    await once(http, 'listening');
+    connection?.start();
+    signals();
+    console.log(JSON.stringify({ listening: port(4020), role: 'seller', paidTransports: [...protocols] }));
+}
+try {
+    await run();
+}
+catch (error) {
+    for (const close of closers.reverse()) {
+        try {
+            await close();
+        }
+        catch { }
+    }
+    // Only typed errors are safe to print; arbitrary provider failures may echo credentials.
+    console.error(error instanceof CommerceError ? `${error.code}: ${error.message}` : 'Startup failed; inspect configuration and private credential file permissions');
+    process.exitCode = 1;
+}

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

@@ -0,0 +1,8 @@
+/** Node.js buyer runtime. Does not initialize seller storage or any signer. */
+export * from './buyer-store.js';
+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 * from './peer-proxy.js';

package/dist/commerce/client-runtime.js

@@ -0,0 +1,7 @@
+/** Node.js buyer runtime. Does not initialize seller storage or any signer. */
+export * from './buyer-store.js';
+export * from './buyer.js';
+export * from './management.js';
+export * from './vault.js';
+export * from './chain.js';
+export * from './peer-proxy.js';

package/dist/commerce/config.d.ts

@@ -0,0 +1,7 @@
+import { type BuyerPolicy, type CommerceConfig, type PaymentProfile } from './types.js';
+export declare function atomic(value: string): bigint;
+export declare function validateUrl(value: string, allowPrivate?: boolean): URL;
+export declare function currencyOf(profile: PaymentProfile): string;
+export declare function digest(value: unknown): string;
+export declare function loadCommerceConfig(value: unknown): CommerceConfig;
+export declare function loadBuyerPolicy(value: unknown): BuyerPolicy;