x402-trust-layer 5.1.0

package/dist/agents/audition-coach.js

@@ -0,0 +1,257 @@
+import { config } from "../config.js";
+import { buildBazaarExtension } from "../lib/bazaar-extension.js";
+import { agentTrustMeta, withAgentTrust } from "../lib/agent-response.js";
+import { hostOf, probeEndpoint } from "../lib/probe.js";
+import { assertSafeOutboundUrl } from "../lib/ssrf.js";
+import { VERIFY_EXAMPLES } from "../lib/verify-examples.js";
+async function fetchJson(url, timeoutMs = 15_000) {
+    assertSafeOutboundUrl(url);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            headers: { accept: "application/json" },
+            signal: controller.signal,
+            redirect: "manual",
+        });
+        clearTimeout(timer);
+        const text = await res.text();
+        let data = null;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            data = { raw: text.slice(0, 300) };
+        }
+        return { ok: res.ok, status: res.status, data };
+    }
+    catch (err) {
+        clearTimeout(timer);
+        return { ok: false, status: 0, data: { error: err instanceof Error ? err.message : String(err) } };
+    }
+}
+function extractWellKnownUrls(data, origin) {
+    if (!data || typeof data !== "object")
+        return [];
+    const record = data;
+    const resources = record.resources;
+    if (!Array.isArray(resources))
+        return [];
+    return resources
+        .map((r) => (typeof r === "string" ? r : typeof r === "object" && r && "url" in r ? String(r.url) : null))
+        .filter((u) => typeof u === "string" && u.startsWith("http"));
+}
+function extractOpenApiPaidPaths(data, origin) {
+    if (!data || typeof data !== "object")
+        return [];
+    const paths = data.paths;
+    if (!paths || typeof paths !== "object")
+        return [];
+    const base = origin.replace(/\/$/, "");
+    const out = [];
+    for (const [path, methods] of Object.entries(paths)) {
+        if (path === "/health")
+            continue;
+        if (!methods || typeof methods !== "object")
+            continue;
+        for (const method of Object.keys(methods)) {
+            if (["get", "post", "put", "delete"].includes(method)) {
+                out.push({ method: method.toUpperCase(), path, url: `${base}${path}` });
+            }
+        }
+    }
+    return out;
+}
+function bazaarShapeOk(path, method, example) {
+    const ext = buildBazaarExtension(path, method, example);
+    const schema = ext.schema;
+    const props = schema.properties;
+    if (!props?.input)
+        return false;
+    const inputProps = props.input;
+    const inputInner = inputProps.properties;
+    const hasInput = Boolean(inputInner?.body) ||
+        Boolean(inputInner?.queryParams) ||
+        method === "GET";
+    const outputProps = props.output;
+    const hasOutput = Boolean(ext.info.output) || Boolean(outputProps);
+    return hasInput && hasOutput && Boolean(schema.$schema);
+}
+function auditRoute(url, method, fastProbe) {
+    return (async () => {
+        const issues = [];
+        const fixInstructions = [];
+        const probeMethod = method === "GET" ? "GET" : "POST";
+        const probe = await probeEndpoint(url, {
+            method: probeMethod,
+            body: probeMethod === "POST" ? "{}" : undefined,
+            fastSynthetic: fastProbe,
+            timeoutMs: fastProbe ? 1_500 : 6_000,
+        });
+        let score = 50;
+        if (probe.status === 402) {
+            score += 25;
+        }
+        else if (probe.status === 200 && method === "POST") {
+            issues.push("POST route returns 200 without payment — verifiers expect 402 or paid 200 with body");
+            fixInstructions.push("Wrap route with x402 middleware; return 402 for unpaid POST.");
+            score -= 15;
+        }
+        else if (probe.status === 0) {
+            issues.push("Endpoint unreachable from coach probe");
+            fixInstructions.push("Check Railway/deploy URL, TLS, and firewall.");
+            score -= 40;
+        }
+        else {
+            issues.push(`Unexpected probe status ${probe.status}`);
+            fixInstructions.push("Ensure unpaid probe returns HTTP 402 with paymentOptions.");
+            score -= 10;
+        }
+        if (probe.priceUsdc == null && probe.requiresPayment) {
+            issues.push("402 missing parseable USDC price");
+            fixInstructions.push("Include paymentOptions[].price per chain in 402 body.");
+            score -= 10;
+        }
+        else if (probe.priceUsdc != null && probe.priceUsdc > 0) {
+            score += 8;
+        }
+        if (!url.startsWith("https://")) {
+            issues.push("Resource URL is not HTTPS");
+            fixInstructions.push("Set PUBLIC_BASE_URL to https:// in production.");
+            score -= 20;
+        }
+        const path = new URL(url).pathname;
+        if (method === "POST" && fastProbe) {
+            const example = VERIFY_EXAMPLES[path];
+            if (!example) {
+                issues.push("Missing VERIFY_EXAMPLES entry for verifier empty-body merge");
+                fixInstructions.push(`Add canonical body to src/lib/verify-examples.ts for ${path}`);
+                score -= 12;
+            }
+            else if (!bazaarShapeOk(path, method, example)) {
+                issues.push("Bazaar schema shape may fail AgentCash discovery");
+                fixInstructions.push("Use schema.properties.input.properties.body and output.properties.example (see bazaar-extension.ts).");
+                score -= 15;
+            }
+            else {
+                score += 10;
+            }
+        }
+        if (probe.paymentOptions.length >= 2)
+            score += 5;
+        score = Math.max(0, Math.min(100, score));
+        const status = score >= 75 ? "pass" : score >= 55 ? "warn" : "fail";
+        return {
+            url,
+            method,
+            probeStatus: probe.status,
+            requiresPayment: probe.requiresPayment,
+            priceUsdc: probe.priceUsdc,
+            scoreEstimate: score,
+            status,
+            issues,
+            fixInstructions,
+        };
+    })();
+}
+export async function runAuditionCoach(input) {
+    const origin = input.origin.replace(/\/$/, "");
+    assertSafeOutboundUrl(origin);
+    const isOwnSuite = hostOf(origin) === hostOf(config.canonicalOrigin) ||
+        hostOf(origin) === hostOf(config.publicBaseUrl);
+    const fastProbe = isOwnSuite;
+    const maxRoutes = fastProbe
+        ? Math.min(Math.max(input.maxRoutes ?? 3, 1), 3)
+        : Math.min(Math.max(input.maxRoutes ?? 24, 1), 30);
+    const globalFixes = [];
+    const routes = [];
+    const [openapiRes, wellKnownRes, rootHead] = await Promise.all([
+        fetchJson(`${origin}/openapi.json`, fastProbe ? 4_000 : 15_000),
+        fetchJson(`${origin}/.well-known/x402`, fastProbe ? 4_000 : 15_000),
+        fetch(`${origin}/`, { method: "HEAD" }).catch(() => null),
+    ]);
+    if (!openapiRes.ok) {
+        globalFixes.push("Publish GET /openapi.json with x-payment-info and requestBody examples.");
+    }
+    if (!wellKnownRes.ok) {
+        globalFixes.push("Publish GET /.well-known/x402 listing all paid resource URLs.");
+    }
+    const openapiPaths = openapiRes.ok ? extractOpenApiPaidPaths(openapiRes.data, origin) : [];
+    const wellKnownUrls = wellKnownRes.ok ? extractWellKnownUrls(wellKnownRes.data, origin) : [];
+    if (openapiRes.ok && typeof openapiRes.data === "object") {
+        const paths = openapiRes.data.paths;
+        if (paths && "/health" in paths) {
+            globalFixes.push("Remove /health from OpenAPI paid paths (x402scan registers it incorrectly).");
+        }
+        const info = openapiRes.data.info;
+        if (!info?.["x-guidance"]) {
+            globalFixes.push("Add info.x-guidance in OpenAPI for agent instructions.");
+        }
+    }
+    const x402gleHeader = rootHead?.headers.get("x-x402gle-verify");
+    if (!x402gleHeader) {
+        globalFixes.push("Set X402GLE_CHALLENGE_TOKEN on host and emit X-X402GLE-VERIFY header for x402gle domain claim.");
+    }
+    if (wellKnownUrls.length && openapiPaths.length && wellKnownUrls.length !== openapiPaths.length) {
+        globalFixes.push(`Align /.well-known/x402 (${wellKnownUrls.length} URLs) with OpenAPI paid paths (${openapiPaths.length}).`);
+    }
+    const urlsToAudit = new Map();
+    for (const u of wellKnownUrls.slice(0, maxRoutes)) {
+        urlsToAudit.set(u, u.includes("registry") ? "GET" : "POST");
+    }
+    for (const p of openapiPaths.slice(0, maxRoutes)) {
+        const full = `${origin}${p.path}`;
+        urlsToAudit.set(full, p.method);
+    }
+    const routeAudits = await Promise.all([...urlsToAudit.entries()].map(([url, method]) => auditRoute(url, method, fastProbe)));
+    routes.push(...routeAudits);
+    const avg = routes.length > 0 ? routes.reduce((s, r) => s + r.scoreEstimate, 0) / routes.length : 0;
+    const failCount = routes.filter((r) => r.status === "fail").length;
+    const hostScoreEstimate = Math.round(avg);
+    const summary = routes.length === 0
+        ? "No routes discovered — fix OpenAPI and .well-known/x402 first."
+        : `${routes.length} routes audited; ~${hostScoreEstimate} avg score; ${failCount} need fixes before Dexter/x402gle pass (75+).`;
+    const coaching = {
+        hostScoreEstimate,
+        failCount,
+        passCount: routes.filter((r) => r.status === "pass").length,
+        warnCount: routes.filter((r) => r.status === "warn").length,
+        topFixes: routes.flatMap((r) => r.fixInstructions).slice(0, 8),
+    };
+    return withAgentTrust({
+        status: "ok",
+        ok: true,
+        coached: true,
+        allowed: hostScoreEstimate >= 75 && failCount === 0,
+        origin,
+        auditedAt: new Date().toISOString(),
+        hostScoreEstimate,
+        summary,
+        discovery: {
+            openapiOk: openapiRes.ok,
+            wellKnownOk: wellKnownRes.ok,
+            resourceCount: wellKnownUrls.length || null,
+            openapiPathCount: openapiPaths.length || null,
+        },
+        globalFixes,
+        routes: routes.sort((a, b) => a.scoreEstimate - b.scoreEstimate),
+        routeAudits: routes.sort((a, b) => a.scoreEstimate - b.scoreEstimate),
+        coaching,
+        nextCommands: [
+            `npx -y @dexterai/opendexter@latest audition "${origin}" --json`,
+            `npm run discovery:check -- ${origin}/api/x402/proxy`,
+            "Fix fixInstructions per route → redeploy → re-run coach",
+        ],
+        dexterAuditionNote: "Coach is static + unpaid probes. Dexter audition runs real paid tests and updates catalog quality scores.",
+    }, agentTrustMeta([
+        "openapi_checked",
+        "well_known_checked",
+        openapiRes.ok ? "openapi_ok" : "openapi_missing",
+        wellKnownRes.ok ? "well_known_ok" : "well_known_missing",
+        routes.length > 0 ? "routes_audited" : "no_routes_found",
+    ], {
+        confidence: routes.length > 0 ? 0.88 : 0.55,
+        sources: ["audition-coach", "x402gle-aligned"],
+        accuracy_note: "Coach uses unpaid 402 probes only; Dexter/x402gle paid auditions grade live settlement responses.",
+    }));
+}

package/dist/agents/bedrock-bridge.d.ts

@@ -0,0 +1,3 @@
+import type { Request, Response } from "express";
+/** AWS Bedrock AgentCore action-group → Trust Layer guard preflight. */
+export declare function handleBedrockPreflight(req: Request, res: Response): Promise<void>;

package/dist/agents/bedrock-bridge.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { config } from "../config.js";
+import { parseWithVerifierFallback } from "../lib/parse-with-verifier-fallback.js";
+const bedrockSchema = z.object({
+    actionGroup: z.string().optional(),
+    apiPath: z.string().optional(),
+    requestBody: z
+        .object({
+        content: z
+            .record(z.object({
+            properties: z.record(z.unknown()).optional(),
+        }))
+            .optional(),
+    })
+        .optional(),
+});
+function extractBedrockProperties(body) {
+    const content = body.requestBody?.content;
+    if (!content)
+        return {};
+    const json = content["application/json"];
+    return json?.properties ?? {};
+}
+/** AWS Bedrock AgentCore action-group → Trust Layer guard preflight. */
+export async function handleBedrockPreflight(req, res) {
+    const parsed = parseWithVerifierFallback("/api/bedrock/preflight", bedrockSchema, req.body);
+    if (!parsed.success) {
+        res.status(400).json({ error: parsed.error.flatten() });
+        return;
+    }
+    const params = extractBedrockProperties(parsed.data);
+    const upstream = await fetch(`${config.publicBaseUrl}/api/guard/pre-x402`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            agentId: String(params.agentId ?? "bedrock-agent"),
+            walletAddress: String(params.walletAddress ?? config.payToEvm ?? config.payTo),
+            targetUrl: String(params.targetUrl ?? config.publicBaseUrl),
+            estimatedCostUsdc: Number(params.estimatedCostUsdc ?? 0.05),
+            policy: params.policy ?? {
+                dailyCapUsdc: 50,
+                perCallCapUsdc: 1,
+                allowedHosts: ["*"],
+            },
+        }),
+    });
+    const result = await upstream.json();
+    res.json({
+        messageVersion: "1.0",
+        response: {
+            actionGroup: parsed.data.actionGroup ?? "TrustLayerGuard",
+            apiPath: parsed.data.apiPath ?? "/guard/pre-x402",
+            httpMethod: "POST",
+            httpStatusCode: upstream.status,
+            responseBody: {
+                "application/json": { body: JSON.stringify(result) },
+            },
+        },
+    });
+}

package/dist/agents/budget-allocator.d.ts

@@ -0,0 +1,24 @@
+export type FleetAgent = {
+    agentId: string;
+    priority: number;
+    requestedUsdc: number;
+    dailyRemainingUsdc: number;
+};
+export type BudgetAllocatorInput = {
+    fleetId: string;
+    poolRemainingUsdc: number;
+    agents: FleetAgent[];
+};
+export type Allocation = {
+    agentId: string;
+    allocatedUsdc: number;
+    approved: boolean;
+    reason: string;
+};
+export type BudgetAllocatorResult = {
+    fleetId: string;
+    poolRemainingUsdc: number;
+    poolAfterUsdc: number;
+    allocations: Allocation[];
+};
+export declare function runBudgetAllocator(input: BudgetAllocatorInput): BudgetAllocatorResult;

package/dist/agents/budget-allocator.js

@@ -0,0 +1,31 @@
+export function runBudgetAllocator(input) {
+    const sorted = [...input.agents].sort((a, b) => b.priority - a.priority);
+    let pool = input.poolRemainingUsdc;
+    const allocations = [];
+    for (const agent of sorted) {
+        const cap = Math.min(agent.requestedUsdc, agent.dailyRemainingUsdc);
+        if (pool >= cap && cap > 0) {
+            allocations.push({
+                agentId: agent.agentId,
+                allocatedUsdc: cap,
+                approved: true,
+                reason: "Approved within fleet pool and agent daily cap",
+            });
+            pool -= cap;
+        }
+        else {
+            allocations.push({
+                agentId: agent.agentId,
+                allocatedUsdc: 0,
+                approved: false,
+                reason: pool <= 0 ? "Fleet pool exhausted" : "Exceeds daily remaining or pool",
+            });
+        }
+    }
+    return {
+        fleetId: input.fleetId,
+        poolRemainingUsdc: input.poolRemainingUsdc,
+        poolAfterUsdc: Number(pool.toFixed(4)),
+        allocations,
+    };
+}

package/dist/agents/compliance-ledger.d.ts

@@ -0,0 +1,66 @@
+export type ComplianceRecord = {
+    merchant: string;
+    endpoint?: string;
+    amountUsdc: number;
+    rail?: string;
+    network?: string;
+    category?: string;
+    agentId?: string;
+    transactionHash?: string;
+    timestamp?: string;
+};
+export type CompliancePolicy = {
+    monthlyCapUsdc?: number;
+    perMerchantCapUsdc?: number;
+    disallowedCategories?: string[];
+    requireTxHash?: boolean;
+};
+export type ComplianceLedgerInput = {
+    organizationId: string;
+    period?: string;
+    records: ComplianceRecord[];
+    policy?: CompliancePolicy;
+};
+/**
+ * CFO-grade Spend Compliance & Audit agent.
+ * Reconciles a fleet's agentic spend into a tamper-evident, SOC2/tax-ready
+ * ledger: spend by merchant/category/rail/agent, policy-violation flags, and
+ * a deterministic ledger hash. Complements evidence-locker (raw bundle export)
+ * with the analytics + reconciliation layer enterprises actually file.
+ */
+export declare function runComplianceLedger(input: ComplianceLedgerInput): {
+    organizationId: string;
+    period: string;
+    summary: {
+        recordCount: number;
+        totalUsdc: number;
+        averageUsdc: number;
+        unreconciledRecords: number;
+        policyCompliant: boolean;
+    };
+    breakdown: {
+        byMerchant: Record<string, {
+            count: number;
+            totalUsdc: number;
+        }>;
+        byCategory: Record<string, {
+            count: number;
+            totalUsdc: number;
+        }>;
+        byRail: Record<string, {
+            count: number;
+            totalUsdc: number;
+        }>;
+        byAgent: Record<string, {
+            count: number;
+            totalUsdc: number;
+        }>;
+    };
+    violations: {
+        type: string;
+        detail: string;
+    }[];
+    ledgerHash: string;
+    exportFormats: string[];
+    auditNote: string;
+} & import("../lib/agent-response.js").AgentTrustMeta;

package/dist/agents/compliance-ledger.js

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { agentTrustMeta, withAgentTrust } from "../lib/agent-response.js";
+function group(rows, key) {
+    const out = {};
+    for (const r of rows) {
+        const k = key(r) || "unknown";
+        out[k] ??= { count: 0, totalUsdc: 0 };
+        out[k].count += 1;
+        out[k].totalUsdc = Number((out[k].totalUsdc + r.amountUsdc).toFixed(6));
+    }
+    return out;
+}
+/**
+ * CFO-grade Spend Compliance & Audit agent.
+ * Reconciles a fleet's agentic spend into a tamper-evident, SOC2/tax-ready
+ * ledger: spend by merchant/category/rail/agent, policy-violation flags, and
+ * a deterministic ledger hash. Complements evidence-locker (raw bundle export)
+ * with the analytics + reconciliation layer enterprises actually file.
+ */
+export function runComplianceLedger(input) {
+    const rows = input.records;
+    const totalUsdc = Number(rows.reduce((a, r) => a + r.amountUsdc, 0).toFixed(6));
+    const policy = input.policy ?? {};
+    const byMerchant = group(rows, (r) => r.merchant ?? r.endpoint ?? "unknown");
+    const byCategory = group(rows, (r) => r.category ?? "uncategorized");
+    const byRail = group(rows, (r) => r.rail ?? r.network ?? "unknown");
+    const byAgent = group(rows, (r) => r.agentId ?? "unknown");
+    const violations = [];
+    if (policy.monthlyCapUsdc != null && totalUsdc > policy.monthlyCapUsdc) {
+        violations.push({ type: "monthly_cap", detail: `Total $${totalUsdc} exceeds monthly cap $${policy.monthlyCapUsdc}` });
+    }
+    if (policy.perMerchantCapUsdc != null) {
+        for (const [m, agg] of Object.entries(byMerchant)) {
+            if (agg.totalUsdc > policy.perMerchantCapUsdc) {
+                violations.push({ type: "per_merchant_cap", detail: `${m}: $${agg.totalUsdc} > $${policy.perMerchantCapUsdc}` });
+            }
+        }
+    }
+    if (policy.disallowedCategories?.length) {
+        for (const cat of policy.disallowedCategories) {
+            if (byCategory[cat])
+                violations.push({ type: "disallowed_category", detail: `Category ${cat} present ($${byCategory[cat].totalUsdc})` });
+        }
+    }
+    const unreconciled = policy.requireTxHash
+        ? rows.filter((r) => !r.transactionHash).length
+        : rows.filter((r) => !r.transactionHash).length;
+    const canonical = JSON.stringify({
+        organizationId: input.organizationId,
+        period: input.period ?? null,
+        records: rows.map((r) => ({
+            merchant: r.merchant ?? r.endpoint,
+            amountUsdc: r.amountUsdc,
+            rail: r.rail ?? r.network,
+            txHash: r.transactionHash ?? null,
+            ts: r.timestamp ?? null,
+        })),
+    });
+    const ledgerHash = createHash("sha256").update(canonical).digest("hex");
+    return withAgentTrust({
+        organizationId: input.organizationId,
+        period: input.period ?? "unspecified",
+        summary: {
+            recordCount: rows.length,
+            totalUsdc,
+            averageUsdc: rows.length ? Number((totalUsdc / rows.length).toFixed(6)) : 0,
+            unreconciledRecords: unreconciled,
+            policyCompliant: violations.length === 0,
+        },
+        breakdown: { byMerchant, byCategory, byRail, byAgent },
+        violations,
+        ledgerHash,
+        exportFormats: ["json", "csv-ready", "soc2-bundle"],
+        auditNote: "Persist ledgerHash off-system; recompute to detect tampering. Pair with /api/evidence-locker/export for signed bundles.",
+    }, agentTrustMeta(["aggregation", "policy_eval", "tamper_hash"], {
+        confidence: 0.9,
+        sources: ["compliance-ledger"],
+        accuracy_note: "Reconciliation is based on supplied records; on-chain verification of each txHash should be done via /api/receipt-auditor/verify.",
+    }));
+}

package/dist/agents/dispute-resolver.d.ts

@@ -0,0 +1,62 @@
+export type DisputeReason = "non_delivery" | "quality_mismatch" | "overcharge" | "duplicate" | "unauthorized";
+export type DisputeRail = "visa-cli" | "card" | "base-x402" | "solana-x402" | "circle-nano" | "stripe-mpp";
+export type DisputeEvidence = {
+    expectedSchema?: string[];
+    actualResponseEmpty?: boolean;
+    verificationScore?: number;
+    receiptValid?: boolean;
+    duplicateOfTx?: string;
+    chargedUsdc?: number;
+    quotedUsdc?: number;
+};
+export type DisputeResolveInput = {
+    rail: DisputeRail;
+    merchant: string;
+    amountUsdc: number;
+    reason: DisputeReason;
+    transactionHash?: string;
+    evidence?: DisputeEvidence;
+};
+/**
+ * Dispute & Chargeback Auto-Resolver.
+ * Visa CLI brings chargeback rights to agentic payments — but nobody automates
+ * the filing. For card rails this builds a Visa chargeback dossier (reason code,
+ * required evidence, filing steps). For final/stablecoin rails (no chargeback)
+ * it routes to an escrow/refund claim instead. Bridges card dispute rules with
+ * on-chain receipts.
+ */
+export declare function runDisputeResolve(input: DisputeResolveInput): ({
+    path: string;
+    rail: DisputeRail;
+    merchant: string;
+    amountUsdc: number;
+    reason: DisputeReason;
+    reasonCode: string;
+    reasonFamily: string;
+    disputeStrength: number;
+    likelihood: string;
+    autoFileable: boolean;
+    requiredEvidence: string[];
+    evidenceCaptured: string[];
+    filingSteps: string[];
+    nextStep: {
+        method: string;
+        path: string;
+        note: string;
+    };
+} & import("../lib/agent-response.js").AgentTrustMeta) | ({
+    path: string;
+    rail: DisputeRail;
+    merchant: string;
+    amountUsdc: number;
+    reason: DisputeReason;
+    finality: string;
+    disputeStrength: number;
+    likelihood: string;
+    autoFileable: boolean;
+    requiredEvidence: string[];
+    evidenceCaptured: string[];
+    recommendedRoute: string[];
+    escrowUrl: string;
+    refundArbiterUrl: string;
+} & import("../lib/agent-response.js").AgentTrustMeta);