agent-passport-system 1.5.1 → 1.7.0

package/README.md

@@ -2,12 +2,12 @@
 
 [![npm version](https://img.shields.io/npm/v/agent-passport-system)](https://www.npmjs.com/package/agent-passport-system)
 [![license](https://img.shields.io/npm/l/agent-passport-system)](https://github.com/aeoess/agent-passport-system/blob/main/LICENSE)
-[![tests](https://img.shields.io/badge/tests-165%20passing-brightgreen)](https://github.com/aeoess/agent-passport-system)
+[![tests](https://img.shields.io/badge/tests-182%20passing-brightgreen)](https://github.com/aeoess/agent-passport-system)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18749779.svg)](https://doi.org/10.5281/zenodo.18749779)
 
-Cryptographic identity, ethical governance, economic attribution, protocol-native communication, intent architecture, cascade revocation, and coordination primitives for autonomous AI agents.
+Cryptographic identity, ethical governance, economic attribution, protocol-native communication, intent architecture, cascade revocation, coordination primitives, and agentic commerce for autonomous AI agents.
 
-**7 layers. 165 tests. Zero heavy dependencies. Running code. MCP server included.**
+**8 layers. 182 tests. Zero heavy dependencies. Running code. MCP server included.**
 
 > *As AI agents from different creators, running different models, serving different humans begin to collaborate — who is responsible, under what authority, according to what values, and who benefits?*
 
@@ -231,10 +231,76 @@ const completion = completeTask(brief.id, {
 }, operatorKeys)
 ```
 
+### Layer 8 — Agentic Commerce (ACP by OpenAI + Stripe)
+
+```typescript
+import {
+  commercePreflight, createCheckout, completeCheckout,
+  createCommerceDelegation, getSpendSummary,
+  requestHumanApproval, verifyCommerceReceipt
+} from 'agent-passport-system'
+
+// Create a commerce-scoped delegation with spend limit
+const delegation = createCommerceDelegation({
+  delegatorKeys: humanKeys,
+  agentPublicKey: agent.publicKey,
+  spendLimit: 500,
+  allowedMerchants: ['merchant.example.com'],
+  currency: 'usd',
+  expiresAt: '2026-04-01T00:00:00Z'
+})
+
+// 4-gate preflight check before any merchant interaction
+const preflight = commercePreflight(agent.passport, delegation, {
+  amount: { amount: 4999, currency: 'usd' },  // $49.99
+  merchant: 'merchant.example.com'
+})
+// → { approved: true, gates: { passport: ✓, scope: ✓, spend: ✓, merchant: ✓ } }
+
+// Create ACP checkout session with merchant
+const session = await createCheckout('https://merchant.example.com', {
+  lineItems: [{ name: 'Cloud API Credits', quantity: 1, price: { amount: 4999, currency: 'usd' } }],
+  agentPassport: agent.passport,
+  delegation
+})
+
+// Check if human approval needed (configurable threshold)
+if (session.total.amount > config.humanApprovalThreshold) {
+  const approval = requestHumanApproval(session, agent, delegation)
+  // → { requestId, amount, merchant, beneficiary, expiresAt }
+  // Wait for human confirmation before proceeding
+}
+
+// Complete purchase → signed receipt with beneficiary attribution
+const receipt = await completeCheckout(session.id, {
+  paymentToken: sharedPaymentToken,
+  agentKeys: agent.keys,
+  delegation
+})
+
+// Verify any commerce receipt (tamper-proof)
+const valid = verifyCommerceReceipt(receipt)
+// → true (Ed25519 signature over canonical JSON)
+
+// Track spending against delegation limits
+const summary = getSpendSummary(delegation, allReceipts)
+// → { limit: 500, spent: 49.99, remaining: 450.01, utilization: '10.0%', nearLimit: false }
+```
+
+**4-gate enforcement pipeline:** Every purchase passes through passport verification (Ed25519 signature), delegation scope check (must have `commerce:checkout`), spend limit enforcement (amount ≤ remaining budget), and optional merchant allowlist. Agents cannot bypass gates — the cryptography prevents it.
+
+**Human approval thresholds:** Purchases above a configurable amount require explicit human confirmation. The agent generates an approval request; the human signs it. No unsigned approvals accepted.
+
+**Beneficiary attribution:** Every purchase receipt traces back to a human principal through the delegation chain. Who authorized the spend, under what limits, and who benefits — cryptographically provable.
+
 ## Architecture
 
 ```
 ┌─────────────────────────────────────────────────┐
+│  Layer 8: Agentic Commerce (ACP)                │
+│  4-gate preflight · Spend tracking · Human       │
+│  approval · Signed receipts · Beneficiary trace  │
+├─────────────────────────────────────────────────┤
 │  Layer 7: Coordination Primitives               │
 │  Task briefs · Role assignment · Evidence ·      │
 │  Review gates · Handoffs · Deliverables · Metrics│
@@ -279,6 +345,8 @@ const completion = completeTask(brief.id, {
 
 **Layer 7 — Coordination Primitives.** Protocol-native multi-agent task orchestration. Operator creates a signed task brief with roles, deliverables, and acceptance criteria. Agents are assigned to roles and sign acceptance. Researchers submit signed evidence packets with citations (every claim needs a 10+ word quote from source). Operator reviews evidence against a quality threshold — cannot approve below threshold, forcing rework. Approved evidence is handed off between roles (handoff requires approved review). Analysts submit deliverables citing evidence packets. Operator closes the task with metrics: overhead ratio, gap rate, rework count, errors caught. Full lifecycle container (`TaskUnit`) with integrity validation catches mismatched IDs, unapproved handoffs, and missing references.
 
+**Layer 8 — Agentic Commerce (ACP by OpenAI + Stripe).** Implements the [Agentic Commerce Protocol](https://openai.com/index/agentic-commerce-protocol/) identity and governance layer. 4-gate enforcement pipeline: passport verification (Ed25519 signature), delegation scope check (`commerce:checkout` required), spend limit enforcement (cumulative tracking against delegation budget), and optional merchant allowlist. Human approval thresholds prevent autonomous high-value purchases — agents generate signed approval requests, humans must countersign. Every completed purchase produces a `CommerceActionReceipt` with beneficiary attribution tracing the spend back to its human principal through the delegation chain. Spend analytics with utilization warnings at 80%. 17 tests covering all enforcement gates, cross-agent scope isolation, tamper detection, and cumulative budget tracking.
+
 ## Human Values Floor — v0.1
 
 | ID | Principle | Enforcement |
@@ -327,7 +395,7 @@ npm: [agent-passport-system-mcp](https://www.npmjs.com/package/agent-passport-sy
 
 ```bash
 npm test
-# 165 tests across 12 files, 40 suites, 0 failures
+# 182 tests across 13 files, 40+ suites, 0 failures
 ```
 
 Includes 23 adversarial tests: Merkle tree tampering, attribution gaming resistance, compliance violations, floor negotiation attacks, wrong-key attestations.
@@ -336,6 +404,8 @@ Includes 23 adversarial tests: Merkle tree tampering, attribution gaming resista
 
 17 coordination tests: task brief creation/verification, role assignment, evidence submission, review gates (score vs threshold), handoff enforcement (requires approved review), deliverable submission, full lifecycle, task unit validation.
 
+17 commerce tests: delegation creation with commerce scopes, 4-gate preflight (passport, scope, spend, merchant), spend analytics, human approval request generation, receipt signing/verification, tamper detection, cross-agent scope enforcement, cumulative spend tracking.
+
 ## Paper
 
 **"The Agent Social Contract: Cryptographic Identity, Ethical Governance, and Beneficiary Economics for Autonomous AI Agents"**
@@ -356,13 +426,14 @@ By Tymofii Pidlisnyi — Published on Zenodo
 | Attribution | Merkle proofs | — | — | — | — |
 | Communication | Signed Agora | — | — | — | — |
 | Coordination | Task units + MCP server | — | — | — | — |
-| Tests | 165 (23 adversarial) | None | Limited | None | None |
+| Commerce | ACP + 4-gate enforcement | — | — | — | — |
+| Tests | 182 (23 adversarial) | None | Limited | None | None |
 | Dependencies | Node.js crypto + uuid | — | Multi-LLM | — | Consensus network |
 
 ## Structure
 
 ```
-src/                    21 source files
+src/                    22 source files
   contract.ts          — High-level API (6 functions)
   core/
     passport.ts        — Ed25519 identity
@@ -373,6 +444,7 @@ src/                    21 source files
     intent.ts          — Intent architecture, deliberation, roles
     policy.ts          — 3-signature chain, policy validation
     coordination.ts    — Task briefs, evidence, review, handoff, deliverables
+    commerce.ts        — ACP checkout, 4-gate enforcement, spend tracking
   cli/
     index.ts           — CLI (14 commands)
   crypto/
@@ -383,7 +455,8 @@ src/                    21 source files
     intent.ts          — Layer 5 types
     policy.ts          — Layer 6 types
     coordination.ts    — Layer 7 types
-tests/                  12 test files, 165 tests (40 suites)
+    commerce.ts        — Layer 8 types
+tests/                  13 test files, 182 tests (40+ suites)
   adversarial.ts       — 23 adversarial cases
   agora.test.ts        — 15 Agora tests
   contract.test.ts     — High-level API tests
@@ -396,6 +469,7 @@ tests/                  12 test files, 165 tests (40 suites)
   policy.test.ts       — Intent, policy decision, 3-sig chain
   cascade.test.ts      — Chain registry, cascade revocation, batch
   coordination.test.ts — Task briefs, evidence, review, handoff, lifecycle
+  commerce.test.ts     — ACP checkout, 4-gate preflight, spend tracking
 values/
   floor.yaml           — Human Values Floor manifest
 papers/

package/dist/src/core/commerce.d.ts

@@ -0,0 +1,100 @@
+import type { SignedPassport } from '../types/passport.js';
+import type { ACPCheckoutSession, ACPLineItem, ACPMoney, ACPAddress, CommerceConfig, CommerceDelegation, CommercePreflightResult, CommerceActionReceipt, HumanApprovalRequest } from '../types/commerce.js';
+export declare function commercePreflight(opts: {
+    signedPassport: SignedPassport;
+    delegation: CommerceDelegation;
+    merchantName: string;
+    estimatedTotal: ACPMoney;
+    config?: CommerceConfig;
+}): CommercePreflightResult;
+export declare function createCheckout(opts: {
+    signedPassport: SignedPassport;
+    delegation: CommerceDelegation;
+    config: CommerceConfig;
+    items: {
+        skuId: string;
+        quantity: number;
+    }[];
+    customer?: {
+        name?: string;
+        email?: string;
+    };
+    fulfillmentAddress?: ACPAddress;
+    privateKey: string;
+}): Promise<{
+    session: ACPCheckoutSession;
+    receipt: CommerceActionReceipt;
+}>;
+export declare function updateCheckout(opts: {
+    signedPassport: SignedPassport;
+    delegation: CommerceDelegation;
+    config: CommerceConfig;
+    sessionId: string;
+    updates: {
+        items?: {
+            id: string;
+            quantity: number;
+        }[];
+        fulfillmentAddress?: ACPAddress;
+        fulfillmentOptionId?: string;
+    };
+    privateKey: string;
+}): Promise<{
+    session: ACPCheckoutSession;
+    receipt: CommerceActionReceipt;
+}>;
+export declare function completeCheckout(opts: {
+    signedPassport: SignedPassport;
+    delegation: CommerceDelegation;
+    config: CommerceConfig;
+    sessionId: string;
+    paymentToken: string;
+    paymentMethod?: string;
+    privateKey: string;
+}): Promise<{
+    session: ACPCheckoutSession;
+    receipt: CommerceActionReceipt;
+    spendUpdated: CommerceDelegation;
+}>;
+export declare function cancelCheckout(opts: {
+    signedPassport: SignedPassport;
+    delegation: CommerceDelegation;
+    config: CommerceConfig;
+    sessionId: string;
+    privateKey: string;
+}): Promise<{
+    session: ACPCheckoutSession;
+    receipt: CommerceActionReceipt;
+}>;
+export declare function requestHumanApproval(opts: {
+    agentId: string;
+    delegationId: string;
+    merchantName: string;
+    items: ACPLineItem[];
+    totalAmount: ACPMoney;
+    reason: string;
+    expiresInMinutes?: number;
+}): HumanApprovalRequest;
+export declare function createCommerceDelegation(opts: {
+    agentId: string;
+    delegationId: string;
+    spendLimit: number;
+    currency?: string;
+    approvedMerchants?: string[];
+    requireHumanApproval?: boolean;
+    humanApprovalThreshold?: number;
+    additionalScopes?: string[];
+}): CommerceDelegation;
+export declare function getSpendSummary(delegation: CommerceDelegation): {
+    limit: number;
+    spent: number;
+    remaining: number;
+    currency: string;
+    utilizationPercent: number;
+    nearLimit: boolean;
+};
+export declare function verifyCommerceReceipt(receipt: CommerceActionReceipt, publicKey: string): {
+    valid: boolean;
+    errors: string[];
+};
+//# sourceMappingURL=commerce.d.ts.map

package/dist/src/core/commerce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commerce.d.ts","sourceRoot":"","sources":["../../../src/core/commerce.ts"],"names":[],"mappings":"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"}

package/dist/src/core/commerce.js

@@ -0,0 +1,389 @@
+// ══════════════════════════════════════════════════════════════════
+// Layer 7 — Agentic Commerce: Implementation
+// ══════════════════════════════════════════════════════════════════
+// Integration with the Agentic Commerce Protocol (ACP) by OpenAI + Stripe.
+//
+// Every commerce action flows through a 4-gate pipeline:
+//   1. Passport verification — is this agent who it claims to be?
+//   2. Delegation scope check — does this agent have commerce:checkout?
+//   3. Spend limit check — would this purchase exceed the cap?
+//   4. Values Floor check (F-003 Scoped Authority) — is this within policy?
+//
+// Only after all 4 gates pass does the agent interact with the merchant.
+// Every completed action produces a signed CommerceActionReceipt.
+// ══════════════════════════════════════════════════════════════════
+import { randomBytes } from 'node:crypto';
+import { sign, verify as ed25519Verify } from '../crypto/keys.js';
+import { canonicalize } from './canonical.js';
+import { verifyPassport } from '../verification/verify.js';
+// ── Commerce Scopes ──
+const COMMERCE_SCOPES = [
+    'commerce:checkout',
+    'commerce:browse',
+    'commerce:purchase',
+    'commerce:cancel',
+];
+function hasScope(delegation, required) {
+    return delegation.scope.includes(required) || delegation.scope.includes('commerce:*');
+}
+// ── Preflight Check: 4-Gate Pipeline ──
+export function commercePreflight(opts) {
+    const checks = [];
+    const warnings = [];
+    // Gate 1: Passport verification
+    const passportResult = verifyPassport(opts.signedPassport);
+    checks.push({
+        check: 'passport_valid',
+        passed: passportResult.valid,
+        detail: passportResult.valid
+            ? `Passport verified for ${opts.signedPassport.passport.agentId}`
+            : `Passport failed: ${passportResult.errors.join(', ')}`,
+    });
+    // Gate 2: Delegation scope
+    const hasCheckoutScope = hasScope(opts.delegation, 'commerce:checkout');
+    checks.push({
+        check: 'delegation_scope',
+        passed: hasCheckoutScope,
+        detail: hasCheckoutScope
+            ? `Agent has commerce:checkout scope via delegation ${opts.delegation.delegationId}`
+            : `Agent lacks commerce:checkout scope. Has: [${opts.delegation.scope.join(', ')}]`,
+    });
+    // Gate 3: Spend limit
+    const amountInBase = opts.estimatedTotal.amount;
+    const remainingBudget = opts.delegation.spendLimit - opts.delegation.spentAmount;
+    const withinBudget = amountInBase <= remainingBudget;
+    checks.push({
+        check: 'spend_limit',
+        passed: withinBudget,
+        detail: withinBudget
+            ? `Purchase ${amountInBase} within budget (${remainingBudget} remaining of ${opts.delegation.spendLimit})`
+            : `Purchase ${amountInBase} exceeds remaining budget of ${remainingBudget} (limit: ${opts.delegation.spendLimit}, spent: ${opts.delegation.spentAmount})`,
+    });
+    // Gate 3b: Human approval threshold
+    if (opts.delegation.requireHumanApproval && opts.delegation.humanApprovalThreshold) {
+        if (amountInBase > opts.delegation.humanApprovalThreshold) {
+            warnings.push(`Purchase of ${amountInBase} exceeds human approval threshold of ${opts.delegation.humanApprovalThreshold}. Human confirmation required.`);
+        }
+    }
+    // Gate 4: Merchant allowlist (if configured)
+    if (opts.delegation.approvedMerchants && opts.delegation.approvedMerchants.length > 0) {
+        const merchantApproved = opts.delegation.approvedMerchants.includes(opts.merchantName);
+        checks.push({
+            check: 'merchant_approved',
+            passed: merchantApproved,
+            detail: merchantApproved
+                ? `Merchant "${opts.merchantName}" is on approved list`
+                : `Merchant "${opts.merchantName}" is NOT on approved list: [${opts.delegation.approvedMerchants.join(', ')}]`,
+        });
+    }
+    const permitted = checks.every(c => c.passed);
+    return {
+        permitted,
+        checks,
+        delegation: opts.delegation,
+        warnings,
+        blockedReason: permitted ? undefined : checks.find(c => !c.passed)?.detail,
+    };
+}
+// ── ACP Client: Create Checkout Session ──
+export async function createCheckout(opts) {
+    // Run preflight — estimate total as 0 for creation (real total comes from merchant)
+    const preflight = commercePreflight({
+        signedPassport: opts.signedPassport,
+        delegation: opts.delegation,
+        merchantName: opts.config.merchantName,
+        estimatedTotal: { amount: 0, currency: opts.delegation.currency },
+    });
+    if (!preflight.permitted) {
+        throw new Error(`Commerce preflight DENIED: ${preflight.blockedReason}`);
+    }
+    // Build ACP CreateCheckoutRequest
+    const requestBody = {
+        items: opts.items.map(i => ({ sku_id: i.skuId, quantity: i.quantity })),
+        ...(opts.customer && { customer: opts.customer }),
+        ...(opts.fulfillmentAddress && { fulfillment_address: opts.fulfillmentAddress }),
+    };
+    // Call merchant endpoint
+    const url = `${opts.config.merchantBaseUrl}/checkout_sessions`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(opts.config.bearerToken && { 'Authorization': `Bearer ${opts.config.bearerToken}` }),
+        },
+        body: JSON.stringify(requestBody),
+    });
+    if (!response.ok) {
+        throw new Error(`ACP CreateCheckout failed: ${response.status} ${response.statusText}`);
+    }
+    const session = await response.json();
+    // Generate signed receipt
+    const receipt = signCommerceReceipt({
+        agentId: opts.signedPassport.passport.agentId,
+        delegationId: opts.delegation.delegationId,
+        actionType: 'commerce:create_checkout',
+        target: url,
+        method: 'POST',
+        session,
+        merchantName: opts.config.merchantName,
+        delegationChain: extractDelegationChain(opts.signedPassport),
+        beneficiary: opts.signedPassport.passport.metadata?.beneficiaryPrincipalId || 'unknown',
+        privateKey: opts.privateKey,
+    });
+    return { session, receipt };
+}
+// ── ACP Client: Update Checkout Session ──
+export async function updateCheckout(opts) {
+    const url = `${opts.config.merchantBaseUrl}/checkout_sessions/${opts.sessionId}`;
+    const response = await fetch(url, {
+        method: 'PUT',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(opts.config.bearerToken && { 'Authorization': `Bearer ${opts.config.bearerToken}` }),
+        },
+        body: JSON.stringify({
+            ...(opts.updates.items && { items: opts.updates.items }),
+            ...(opts.updates.fulfillmentAddress && { fulfillment_address: opts.updates.fulfillmentAddress }),
+            ...(opts.updates.fulfillmentOptionId && { fulfillment_option_id: opts.updates.fulfillmentOptionId }),
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`ACP UpdateCheckout failed: ${response.status} ${response.statusText}`);
+    }
+    const session = await response.json();
+    const receipt = signCommerceReceipt({
+        agentId: opts.signedPassport.passport.agentId,
+        delegationId: opts.delegation.delegationId,
+        actionType: 'commerce:update_checkout',
+        target: url,
+        method: 'PUT',
+        session,
+        merchantName: opts.config.merchantName,
+        delegationChain: extractDelegationChain(opts.signedPassport),
+        beneficiary: opts.signedPassport.passport.metadata?.beneficiaryPrincipalId || 'unknown',
+        privateKey: opts.privateKey,
+    });
+    return { session, receipt };
+}
+// ── ACP Client: Complete Checkout (Payment) ──
+export async function completeCheckout(opts) {
+    // Re-run preflight with actual total — fetch current session first
+    const getUrl = `${opts.config.merchantBaseUrl}/checkout_sessions/${opts.sessionId}`;
+    const getResponse = await fetch(getUrl, {
+        headers: opts.config.bearerToken ? { 'Authorization': `Bearer ${opts.config.bearerToken}` } : {},
+    });
+    if (!getResponse.ok) {
+        throw new Error(`ACP GetCheckout failed: ${getResponse.status}`);
+    }
+    const currentSession = await getResponse.json();
+    const total = currentSession.totals.total;
+    // Final preflight with real amount
+    const preflight = commercePreflight({
+        signedPassport: opts.signedPassport,
+        delegation: opts.delegation,
+        merchantName: opts.config.merchantName,
+        estimatedTotal: total,
+    });
+    if (!preflight.permitted) {
+        throw new Error(`Commerce preflight DENIED at payment: ${preflight.blockedReason}`);
+    }
+    // Check human approval threshold
+    if (opts.delegation.requireHumanApproval && opts.delegation.humanApprovalThreshold) {
+        if (total.amount > opts.delegation.humanApprovalThreshold) {
+            throw new Error(`HUMAN_APPROVAL_REQUIRED: Purchase of ${total.amount} ${total.currency} exceeds threshold of ${opts.delegation.humanApprovalThreshold}. ` +
+                `Use requestHumanApproval() to get confirmation before completing.`);
+        }
+    }
+    // Complete checkout via ACP
+    const url = `${opts.config.merchantBaseUrl}/checkout_sessions/${opts.sessionId}/complete`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(opts.config.bearerToken && { 'Authorization': `Bearer ${opts.config.bearerToken}` }),
+        },
+        body: JSON.stringify({
+            payment_token: opts.paymentToken,
+            ...(opts.paymentMethod && { payment_method: opts.paymentMethod }),
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`ACP CompleteCheckout failed: ${response.status} ${response.statusText}`);
+    }
+    const session = await response.json();
+    // Update spend tracking on the delegation
+    const spendUpdated = {
+        ...opts.delegation,
+        spentAmount: opts.delegation.spentAmount + total.amount,
+    };
+    // Generate signed receipt with full purchase details
+    const receipt = signCommerceReceipt({
+        agentId: opts.signedPassport.passport.agentId,
+        delegationId: opts.delegation.delegationId,
+        actionType: 'commerce:complete_checkout',
+        target: url,
+        method: 'POST',
+        session,
+        merchantName: opts.config.merchantName,
+        delegationChain: extractDelegationChain(opts.signedPassport),
+        beneficiary: opts.signedPassport.passport.metadata?.beneficiaryPrincipalId || 'unknown',
+        privateKey: opts.privateKey,
+    });
+    return { session, receipt, spendUpdated };
+}
+// ── ACP Client: Cancel Checkout ──
+export async function cancelCheckout(opts) {
+    const url = `${opts.config.merchantBaseUrl}/checkout_sessions/${opts.sessionId}/cancel`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(opts.config.bearerToken && { 'Authorization': `Bearer ${opts.config.bearerToken}` }),
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`ACP CancelCheckout failed: ${response.status} ${response.statusText}`);
+    }
+    const session = await response.json();
+    const receipt = signCommerceReceipt({
+        agentId: opts.signedPassport.passport.agentId,
+        delegationId: opts.delegation.delegationId,
+        actionType: 'commerce:cancel_checkout',
+        target: url,
+        method: 'POST',
+        session,
+        merchantName: opts.config.merchantName,
+        delegationChain: extractDelegationChain(opts.signedPassport),
+        beneficiary: opts.signedPassport.passport.metadata?.beneficiaryPrincipalId || 'unknown',
+        privateKey: opts.privateKey,
+    });
+    return { session, receipt };
+}
+// ── Human Approval Request ──
+export function requestHumanApproval(opts) {
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + (opts.expiresInMinutes || 30) * 60 * 1000);
+    return {
+        requestId: `approval-${randomBytes(8).toString('hex')}`,
+        agentId: opts.agentId,
+        merchantName: opts.merchantName,
+        items: opts.items,
+        totalAmount: opts.totalAmount,
+        delegationId: opts.delegationId,
+        reason: opts.reason,
+        createdAt: now.toISOString(),
+        expiresAt: expiresAt.toISOString(),
+        status: 'pending',
+    };
+}
+// ── Commerce Receipt Signing ──
+function signCommerceReceipt(opts) {
+    const receipt = {
+        receiptId: `rcpt-commerce-${randomBytes(8).toString('hex')}`,
+        version: '1.0',
+        timestamp: new Date().toISOString(),
+        agentId: opts.agentId,
+        delegationId: opts.delegationId,
+        action: {
+            type: opts.actionType,
+            target: opts.target,
+            method: opts.method,
+            scopeUsed: 'commerce:checkout',
+            spend: {
+                amount: opts.session.totals.total.amount,
+                currency: opts.session.totals.total.currency,
+            },
+        },
+        checkout: {
+            sessionId: opts.session.id,
+            merchantName: opts.merchantName,
+            items: opts.session.items.map(i => ({
+                skuId: i.skuId,
+                name: i.name,
+                quantity: i.quantity,
+                unitPrice: i.unitPrice.amount,
+            })),
+            totalAmount: opts.session.totals.total.amount,
+            totalCurrency: opts.session.totals.total.currency,
+            status: opts.session.status,
+        },
+        delegationChain: opts.delegationChain,
+        beneficiary: opts.beneficiary,
+    };
+    const payload = canonicalize(receipt);
+    const signature = sign(payload, opts.privateKey);
+    return { ...receipt, signature };
+}
+// ── Helpers ──
+function extractDelegationChain(sp) {
+    const chain = [sp.passport.publicKey];
+    if (sp.passport.delegations) {
+        for (const d of sp.passport.delegations) {
+            if (!chain.includes(d.delegatedBy))
+                chain.push(d.delegatedBy);
+        }
+    }
+    return chain;
+}
+// ── Commerce Delegation Factory ──
+export function createCommerceDelegation(opts) {
+    return {
+        agentId: opts.agentId,
+        delegationId: opts.delegationId,
+        scope: ['commerce:checkout', 'commerce:browse', ...(opts.additionalScopes || [])],
+        spendLimit: opts.spendLimit,
+        spentAmount: 0,
+        currency: opts.currency || 'usd',
+        approvedMerchants: opts.approvedMerchants,
+        requireHumanApproval: opts.requireHumanApproval ?? true,
+        humanApprovalThreshold: opts.humanApprovalThreshold,
+    };
+}
+// ── Spend Analytics ──
+export function getSpendSummary(delegation) {
+    const remaining = delegation.spendLimit - delegation.spentAmount;
+    const utilization = delegation.spendLimit > 0
+        ? (delegation.spentAmount / delegation.spendLimit) * 100
+        : 0;
+    return {
+        limit: delegation.spendLimit,
+        spent: delegation.spentAmount,
+        remaining,
+        currency: delegation.currency,
+        utilizationPercent: Math.round(utilization * 100) / 100,
+        nearLimit: utilization >= 80,
+    };
+}
+// ── Verify Commerce Receipt ──
+export function verifyCommerceReceipt(receipt, publicKey) {
+    const errors = [];
+    // Verify signature
+    const { signature, ...payload } = receipt;
+    const canonical = canonicalize(payload);
+    try {
+        const signatureValid = ed25519Verify(canonical, signature, publicKey);
+        if (!signatureValid) {
+            errors.push('Commerce receipt signature is invalid');
+        }
+    }
+    catch {
+        errors.push('Failed to verify commerce receipt signature');
+    }
+    // Verify required fields
+    if (!receipt.receiptId)
+        errors.push('Missing receiptId');
+    if (!receipt.agentId)
+        errors.push('Missing agentId');
+    if (!receipt.delegationId)
+        errors.push('Missing delegationId');
+    if (!receipt.action?.type)
+        errors.push('Missing action type');
+    if (!receipt.action?.scopeUsed)
+        errors.push('Missing scopeUsed');
+    if (!receipt.beneficiary)
+        errors.push('Missing beneficiary');
+    if (!receipt.checkout?.sessionId)
+        errors.push('Missing checkout sessionId');
+    return { valid: errors.length === 0, errors };
+}
+//# sourceMappingURL=commerce.js.map