x402-trust-layer 5.1.0

package/dist/lib/verify-examples.js

@@ -0,0 +1,438 @@
+/** Canonical probe bodies used when Dexter AI verifier sends an empty POST body */
+export const VERIFY_EXAMPLES = {
+    "/api/x402/proxy": {
+        agentId: "dexter-verifier-probe",
+        walletAddress: "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt",
+        targetUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        estimatedCostUsdc: 0.05,
+        policy: { dailyCapUsdc: 10, perCallCapUsdc: 0.5 },
+        issueAttestation: true,
+    },
+    "/api/mpp/session": {
+        action: "open",
+        expectedCalls: 25,
+        avgPricePerCallUsdc: 0.03,
+        chain: "solana",
+        agentId: "dexter-verifier-probe",
+    },
+    "/api/attestation/issue": {
+        agentId: "dexter-verifier-probe",
+        walletAddress: "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt",
+        targetUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        estimatedCostUsdc: 0.03,
+        policy: { dailyCapUsdc: 10, perCallCapUsdc: 0.5 },
+    },
+    "/api/attestation/verify": {
+        attestationId: "att_verifier_probe_example",
+    },
+    "/api/guard/pre-x402": {
+        agentId: "dexter-verifier-probe",
+        walletAddress: "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt",
+        targetUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        estimatedCostUsdc: 0.05,
+        network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+        policy: { dailyCapUsdc: 10, perCallCapUsdc: 0.5, allowedHosts: ["myceliasignal.com"] },
+    },
+    "/api/agent/verify": {
+        walletAddress: "0x0000000000000000000000000000000000000001",
+        agentId: "1",
+    },
+    "/api/guard/pre-x402-alchemy": {
+        agentId: "alchemy-live-demo-1",
+        walletAddress: "0x0000000000000000000000000000000000000001",
+        targetUrl: "https://x402.alchemy.com/base-mainnet/v2",
+        estimatedCostUsdc: 1,
+        network: "eip155:8453",
+        policy: { dailyCapUsdc: 20, perCallCapUsdc: 2, allowedHosts: ["x402.alchemy.com"] },
+    },
+    "/api/pipeline/execute": {
+        agentId: "dexter-verifier-probe",
+        walletAddress: "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt",
+        targetUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        estimatedCostUsdc: 0.05,
+        network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+        policy: { dailyCapUsdc: 10, perCallCapUsdc: 0.5, allowedHosts: ["myceliasignal.com"] },
+        task: "ETH oracle with guard and marketplace routing under one dollar",
+        maxBudgetUsdc: 1,
+        marketplaceQuery: "ETH USD spot price oracle",
+        preferNetwork: "solana",
+    },
+    "/api/payment-intent/compile": {
+        task: "Verify spend policy for ETH oracle call under one dollar budget",
+        maxBudgetUsdc: 1,
+        agentId: "dexter-verifier-probe",
+        externalCallEstimateUsdc: 0.05,
+    },
+    "/api/facilitator/failover": {
+        targetUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        preferNetwork: "solana",
+        fastProbe: true,
+    },
+    "/api/mpp/session-plan": {
+        action: "estimate",
+        expectedCalls: 25,
+        avgPricePerCallUsdc: 0.03,
+    },
+    "/api/spend-governor/check": {
+        agentId: "dexter-verifier-probe",
+        estimatedCostUsdc: 0.03,
+        targetUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+        policy: { dailyCapUsdc: 10, perCallCapUsdc: 0.5, allowedHosts: ["myceliasignal.com"] },
+    },
+    "/api/identity-gate/check": {
+        walletAddress: "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt",
+        maxTierSpendUsdc: 10,
+    },
+    "/api/risk-gate/scan": {
+        targetUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        estimatedCostUsdc: 0.05,
+        policy: { dailyCapUsdc: 10, perCallCapUsdc: 0.5 },
+    },
+    "/api/router/route": {
+        query: "Dexter USDC route from Arbitrum to Ethereum",
+        preferNetwork: "arbitrum",
+        maxPriceUsdc: 0.9985,
+        skipProbes: true,
+    },
+    "/api/research/brief": {
+        topic: "Ethereum network fees today",
+        includePrice: true,
+        fastProbe: true,
+    },
+    "/api/receipt-auditor/verify": {
+        network: "eip155:8453",
+        expectedAmountUsdc: 0.05,
+        transactionHash: "0x0000000000000000000000000000000000000000000000000000000000000001",
+        settlement: {
+            transaction: "0x0000000000000000000000000000000000000000000000000000000000000001",
+            amountUsdc: 0.05,
+            network: "eip155:8453",
+            payer: "0x0000000000000000000000000000000000000001",
+        },
+    },
+    "/api/refund-arbiter/evaluate": {
+        verificationScore: 85,
+        responseEmpty: false,
+        responseGeneric: false,
+        endpointReachable: true,
+    },
+    "/api/budget-allocator/run": {
+        fleetId: "verifier-fleet",
+        poolRemainingUsdc: 1,
+        agents: [
+            { agentId: "a1", priority: 10, requestedUsdc: 0.2, dailyRemainingUsdc: 5 },
+        ],
+    },
+    "/api/settlement-graph/next": {
+        lastEndpointPath: "/api/spend-governor/check",
+        lastTopic: "agent spend policy",
+    },
+    "/api/quality-monitor/probe": {
+        urls: ["https://x402trustlayer.xyz/health"],
+    },
+    "/api/evidence-locker/export": {
+        organizationId: "verifier-org",
+        records: [
+            {
+                endpoint: "/api/spend-governor/check",
+                amountUsdc: 0.03,
+                network: "solana",
+                timestamp: new Date().toISOString(),
+            },
+        ],
+    },
+    "/api/agent-escrow": {
+        action: "create",
+        payerAgentId: "verifier-payer",
+        payeeAgentId: "verifier-payee",
+        amountUsdc: 0.05,
+        releaseCondition: "receipt-auditor valid:true",
+    },
+    "/api/market/buy-advisor": {
+        intent: "ETH USD spot price oracle for trading bot",
+        agentId: "dexter-verifier-probe",
+        walletAddress: "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt",
+        preferNetwork: "eip155:8453",
+        maxPriceUsdc: 0.15,
+        expectedCalls: 12,
+        policy: { dailyCapUsdc: 10, perCallCapUsdc: 0.5, allowedHosts: ["myceliasignal.com", "dexter.cash"] },
+        dryRunTarget: true,
+    },
+    "/api/seller/audition-coach": {
+        origin: "https://x402trustlayer.xyz",
+        maxRoutes: 3,
+    },
+    "/api/merchant-trust/score": {
+        host: "api.myceliasignal.com",
+        targetUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        observedTxns: 54,
+        observedVolumeUsdc: 1.76,
+        washTradePct: 17,
+        verifiedResources: 44,
+        totalResources: 91,
+        p50LatencyMs: 1200,
+        probe: false,
+    },
+    "/api/mandate/compile": {
+        principal: "cardholder:dexter-verifier",
+        agentId: "dexter-verifier-probe",
+        intent: "Buy ETH/USD oracle data for a trading bot, under $1 per call, daily $10 cap",
+        maxPerTxUsdc: 0.5,
+        dailyCapUsdc: 10,
+        allowedMerchants: ["myceliasignal.com", "dexter.cash"],
+        allowedCategories: ["market-data", "oracle"],
+        allowedRails: ["base-x402", "solana-x402", "visa-cli"],
+        ttlMinutes: 1440,
+    },
+    "/api/mandate/verify": {
+        mandateId: "mdt_verifier_probe_example",
+        proposed: {
+            amountUsdc: 0.05,
+            merchant: "api.myceliasignal.com",
+            category: "oracle",
+            rail: "base-x402",
+        },
+    },
+    "/api/rail-optimizer/route": {
+        amountUsdc: 1.5,
+        disputable: true,
+        latencySensitive: false,
+        expectedCalls: 1,
+    },
+    "/api/compliance/ledger": {
+        organizationId: "verifier-org",
+        period: "2026-05",
+        records: [
+            {
+                merchant: "api.myceliasignal.com",
+                amountUsdc: 0.05,
+                rail: "base-x402",
+                network: "eip155:8453",
+                category: "oracle",
+                agentId: "dexter-verifier-probe",
+                transactionHash: "0x0000000000000000000000000000000000000000000000000000000000000001",
+                timestamp: new Date().toISOString(),
+            },
+        ],
+        policy: { monthlyCapUsdc: 1000, perMerchantCapUsdc: 500, requireTxHash: true },
+    },
+    "/api/dispute/resolve": {
+        rail: "visa-cli",
+        merchant: "api.myceliasignal.com",
+        amountUsdc: 1.0,
+        reason: "non_delivery",
+        evidence: { actualResponseEmpty: true, receiptValid: false },
+    },
+    "/api/quality-escrow/settle": {
+        action: "settle",
+        payerAgentId: "dexter-verifier-probe",
+        payeeMerchant: "api.myceliasignal.com",
+        amountUsdc: 0.05,
+        releaseThreshold: 70,
+        expectedProfile: { requiredKeys: ["price", "symbol"], minLengthBytes: 16, forbidEmpty: true },
+        actualResponse: { bodyKeys: ["price", "symbol", "ts"], byteLength: 64, empty: false },
+    },
+    "/api/quality-escrow/semantic-settle": {
+        action: "settle",
+        deliveryIntent: "ETH/USD spot oracle price with symbol",
+        payerAgentId: "dexter-verifier-probe",
+        payeeMerchant: "api.myceliasignal.com",
+        amountUsdc: 0.05,
+        releaseThreshold: 72,
+        expectedProfile: { requiredKeys: ["price", "symbol"], forbidEmpty: true },
+        actualResponse: {
+            bodyKeys: ["price", "symbol"],
+            byteLength: 48,
+            empty: false,
+            fields: { price: 3450.12, symbol: "ETH" },
+            sample: '{"price":3450.12,"symbol":"ETH"}',
+        },
+    },
+    "/api/mandate/diff": {
+        mandateId: "mdt_verifier_probe_example",
+        task: "Buy ETH/USD oracle data for trading bot",
+        toolCalls: [
+            {
+                name: "x402_fetch",
+                url: "https://api.myceliasignal.com/oracle/price/eth/usd",
+                amountUsdc: 0.05,
+                merchant: "api.myceliasignal.com",
+                category: "oracle",
+                rail: "base-x402",
+            },
+        ],
+        proposed: {
+            amountUsdc: 0.05,
+            merchant: "api.myceliasignal.com",
+            category: "oracle",
+            rail: "base-x402",
+        },
+    },
+    "/api/merchant-trust/certify": {
+        host: "api.myceliasignal.com",
+        targetUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        washTradePct: 12,
+        verifiedResources: 44,
+        totalResources: 91,
+        probe: false,
+        ttlDays: 30,
+        policy: { requireAttestation: true, minAgentTier: "SILVER", minTrustScore: 50, minSecurityGrade: "C" },
+        goodResponseProfile: { requiredKeys: ["price", "symbol"], forbidEmpty: true },
+    },
+    "/api/trust-network/buyer-gate": {
+        sellerHost: "api.myceliasignal.com",
+        walletAddress: "0x0000000000000000000000000000000000000001",
+        attestationId: "att_verifier_probe_example",
+        agentTier: "GOLD",
+        trustScore: 75,
+    },
+    "/api/pipeline/trust-v2": {
+        agentId: "dexter-verifier-probe",
+        walletAddress: "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt",
+        targetUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        estimatedCostUsdc: 0.05,
+        policy: { dailyCapUsdc: 10, perCallCapUsdc: 0.5, allowedHosts: ["myceliasignal.com"] },
+        mandateId: "mdt_verifier_probe_example",
+        toolCalls: [
+            {
+                name: "x402_fetch",
+                url: "https://api.myceliasignal.com/oracle/price/eth/usd",
+                amountUsdc: 0.05,
+                merchant: "api.myceliasignal.com",
+                rail: "base-x402",
+            },
+        ],
+        sellerHost: "api.myceliasignal.com",
+        kymBeforePay: true,
+    },
+    "/api/trust-network/bond/slash": {
+        sellerHost: "api.myceliasignal.com",
+        amountUsdc: 0.02,
+        reason: "semantic_delivery_fail",
+        qualityScore: 42,
+    },
+    "/api/protocol/pipeline/full-trust": {
+        agentId: "dexter-verifier-probe",
+        walletAddress: "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt",
+        targetUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        estimatedCostUsdc: 0.05,
+        organizationId: "verifier-org",
+        policy: { dailyCapUsdc: 10, perCallCapUsdc: 0.5, allowedHosts: ["myceliasignal.com"] },
+    },
+    "/api/protocol/passport/issue": {
+        agentId: "dexter-verifier-probe",
+        walletAddress: "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt",
+        capabilities: ["x402.pay", "tool.invoke"],
+    },
+    "/api/protocol/trust-score/v2": {
+        agentId: "dexter-verifier-probe",
+        walletAddress: "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt",
+        uptimePct: 99,
+        deliveryQualityScore: 85,
+    },
+    "/api/protocol/fraud/scan": {
+        agentId: "dexter-verifier-probe",
+        walletAddress: "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt",
+        merchantHost: "api.myceliasignal.com",
+        amountUsdc: 0.05,
+    },
+    "/api/protocol/execution/issue": {
+        agentId: "dexter-verifier-probe",
+        targetUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        toolTrace: [{ name: "x402_fetch", url: "https://api.myceliasignal.com/oracle/price/eth/usd", amountUsdc: 0.05 }],
+        decisionTrace: ["guard_pass", "payment_settled"],
+        responseSummary: '{"price":3450,"symbol":"ETH"}',
+    },
+    "/api/protocol/replay/bind": {
+        agentId: "dexter-verifier-probe",
+        resourceUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        requestBody: { estimatedCostUsdc: 0.05 },
+    },
+    "/api/protocol/credit/score": {
+        agentId: "dexter-verifier-probe",
+        walletAddress: "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt",
+        settlementCount: 12,
+        disputeCount: 0,
+    },
+    "/api/a2a/execute": {
+        buyerAgentId: "dexter-verifier-probe",
+        sellerAgentId: "seller-oracle-1",
+        sellerEndpoint: "https://x402trustlayer.xyz/api/guard/pre-x402",
+        taskDescription: "Preflight guard check for ETH oracle call under $0.10",
+        maxBudgetUsdc: 0.1,
+    },
+    "/api/bedrock/preflight": {
+        actionGroup: "TrustLayerGuard",
+        apiPath: "/guard/pre-x402",
+        requestBody: {
+            content: {
+                "application/json": {
+                    properties: {
+                        agentId: "bedrock-agent",
+                        walletAddress: "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt",
+                        targetUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+                        estimatedCostUsdc: 0.05,
+                    },
+                },
+            },
+        },
+    },
+    "/api/protocol/passport/verify": {
+        did: "did:agent:dexter_verifier_probe:0000000000000001",
+    },
+    "/api/protocol/oracle/consensus": {
+        subjectType: "agent",
+        subjectId: "dexter-verifier-probe",
+        claims: { trustScore: 82, deliveryQuality: 85 },
+        minQuorum: 3,
+    },
+    "/api/protocol/execution/verify": {
+        receiptId: "poe_verifier_probe_example",
+    },
+    "/api/protocol/reasoning/commit": {
+        agentId: "dexter-verifier-probe",
+        sessionId: "sess_verifier_probe",
+        toolCalls: [{ name: "x402_fetch", argsHash: "abc123" }],
+        policyChecks: ["spend_cap_ok", "host_allowed"],
+        promptHashes: ["prompt_hash_verifier_probe"],
+        riskAnalysis: "low",
+    },
+    "/api/protocol/reasoning/disclose": {
+        auditId: "aud_verifier_probe_example",
+        leafIndices: [0, 1],
+    },
+    "/api/protocol/escrow/create": {
+        payerAgentId: "dexter-verifier-probe",
+        payeeMerchant: "api.myceliasignal.com",
+        amountUsdc: 0.05,
+        resourceHash: "res_verifier_probe",
+    },
+    "/api/protocol/escrow/transition": {
+        escrowId: "00000000-0000-4000-8000-000000000001",
+        nextState: "FUNDED",
+        note: "verifier probe transition",
+    },
+    "/api/protocol/escrow/status": {
+        escrowId: "00000000-0000-4000-8000-000000000001",
+    },
+    "/api/protocol/replay/verify": {
+        bindingId: "rb_verifier_probe_example",
+        resourceUrl: "https://api.myceliasignal.com/oracle/price/eth/usd",
+        requestBody: { estimatedCostUsdc: 0.05 },
+    },
+    "/api/protocol/zk/prove": {
+        proofType: "authorization",
+        agentId: "dexter-verifier-probe",
+        witness: { dailyCapUsdc: 10, spentTodayUsdc: 0 },
+        publicInputs: { agentId: "dexter-verifier-probe" },
+    },
+    "/api/protocol/compliance/assess": {
+        organizationId: "verifier-org",
+        agentId: "dexter-verifier-probe",
+        jurisdiction: "US",
+        monthlyVolumeUsdc: 500,
+        rails: ["base-x402", "solana-x402"],
+        requiresKyc: false,
+    },
+};

package/dist/lib/version.d.ts

@@ -0,0 +1,2 @@
+/** Single source of truth for API / OpenAPI / discovery version strings */
+export declare const SUITE_VERSION: "5.1.0";

package/dist/lib/version.js

@@ -0,0 +1,2 @@
+/** Single source of truth for API / OpenAPI / discovery version strings */
+export const SUITE_VERSION = "5.1.0";

package/dist/lib/webhook-auth.d.ts

@@ -0,0 +1,3 @@
+import type { Request, Response } from "express";
+/** Require WEBHOOK_ADMIN_SECRET in production for webhook management routes. */
+export declare function requireWebhookAdmin(req: Request, res: Response): boolean;

package/dist/lib/webhook-auth.js

@@ -0,0 +1,34 @@
+import { timingSafeEqual } from "node:crypto";
+import { config } from "../config.js";
+function isProduction() {
+    return process.env.NODE_ENV === "production" || !!process.env.RAILWAY_ENVIRONMENT;
+}
+function secretsMatch(expected, provided) {
+    if (expected.length !== provided.length)
+        return false;
+    try {
+        return timingSafeEqual(Buffer.from(expected, "utf8"), Buffer.from(provided, "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
+/** Require WEBHOOK_ADMIN_SECRET in production for webhook management routes. */
+export function requireWebhookAdmin(req, res) {
+    if (!isProduction())
+        return true;
+    const secret = config.webhookAdminSecret;
+    if (!secret) {
+        res.status(503).json({
+            error: "Webhook management disabled — set WEBHOOK_ADMIN_SECRET in production",
+        });
+        return false;
+    }
+    const raw = req.headers["x-webhook-admin-secret"];
+    const provided = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof provided !== "string" || !secretsMatch(secret, provided)) {
+        res.status(403).json({ error: "Forbidden — invalid X-Webhook-Admin-Secret" });
+        return false;
+    }
+    return true;
+}

package/dist/lib/webhook-routes.d.ts

@@ -0,0 +1,2 @@
+import type { Express } from "express";
+export declare function registerWebhookRoutes(app: Express): void;

package/dist/lib/webhook-routes.js

@@ -0,0 +1,112 @@
+import { timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+import { UnsafeUrlError } from "./ssrf.js";
+import { deactivateWebhook, dispatchWebhooks, listWebhooks, registerWebhook, } from "./webhooks.js";
+import { requireWebhookAdmin } from "./webhook-auth.js";
+function isProduction() {
+    return process.env.NODE_ENV === "production" || !!process.env.RAILWAY_ENVIRONMENT;
+}
+const eventSchema = z.enum([
+    "guard.denied",
+    "guard.allowed",
+    "receipt.invalid",
+    "spend.cap_exceeded",
+    "merchant.trust_low",
+]);
+export function registerWebhookRoutes(app) {
+    app.post("/api/webhooks/register", async (req, res) => {
+        if (!requireWebhookAdmin(req, res))
+            return;
+        const parsed = z
+            .object({
+            fleetId: z.string().min(1),
+            url: z.string().url(),
+            events: z.array(eventSchema).min(1),
+        })
+            .safeParse(req.body);
+        if (!parsed.success) {
+            res.status(400).json({ error: parsed.error.flatten() });
+            return;
+        }
+        try {
+            const sub = await registerWebhook(parsed.data);
+            res.status(201).json({
+                ok: true,
+                subscription: {
+                    id: sub.id,
+                    fleetId: sub.fleetId,
+                    url: sub.url,
+                    events: sub.events,
+                    secret: sub.secret,
+                    createdAt: sub.createdAt,
+                },
+                note: "Deliveries signed with x-hub-signature-256 (HMAC-SHA256).",
+            });
+        }
+        catch (err) {
+            const msg = err instanceof UnsafeUrlError ? err.message : "Invalid webhook URL";
+            res.status(400).json({ error: msg });
+        }
+    });
+    app.get("/api/webhooks/list", async (req, res) => {
+        if (!requireWebhookAdmin(req, res))
+            return;
+        const fleetId = typeof req.query.fleetId === "string" ? req.query.fleetId : undefined;
+        const subs = await listWebhooks(fleetId);
+        res.json({
+            ok: true,
+            count: subs.length,
+            subscriptions: subs.map((s) => ({
+                id: s.id,
+                fleetId: s.fleetId,
+                url: s.url,
+                events: s.events,
+                createdAt: s.createdAt,
+                active: s.active,
+            })),
+        });
+    });
+    app.delete("/api/webhooks/:id", async (req, res) => {
+        if (!requireWebhookAdmin(req, res))
+            return;
+        const fleetId = typeof req.query.fleetId === "string" ? req.query.fleetId : "";
+        if (!fleetId) {
+            res.status(400).json({ error: "fleetId query param required" });
+            return;
+        }
+        const ok = await deactivateWebhook(req.params.id, fleetId);
+        if (!ok) {
+            res.status(404).json({ error: "Webhook not found" });
+            return;
+        }
+        res.json({ ok: true, deactivated: req.params.id });
+    });
+    app.post("/api/webhooks/test-dispatch", async (req, res) => {
+        if (isProduction()) {
+            const secret = process.env.WEBHOOK_TEST_SECRET?.trim();
+            const raw = req.headers["x-webhook-test-secret"];
+            const provided = Array.isArray(raw) ? raw[0] : raw;
+            const ok = secret &&
+                typeof provided === "string" &&
+                secret.length === provided.length &&
+                timingSafeEqual(Buffer.from(secret, "utf8"), Buffer.from(provided, "utf8"));
+            if (!ok) {
+                res.status(403).json({ error: "Forbidden — set WEBHOOK_TEST_SECRET and X-Webhook-Test-Secret header" });
+                return;
+            }
+        }
+        const parsed = z
+            .object({
+            fleetId: z.string().optional(),
+            event: eventSchema,
+            payload: z.record(z.unknown()).optional(),
+        })
+            .safeParse(req.body);
+        if (!parsed.success) {
+            res.status(400).json({ error: parsed.error.flatten() });
+            return;
+        }
+        const result = await dispatchWebhooks(parsed.data.event, parsed.data.payload ?? { test: true }, parsed.data.fleetId);
+        res.json({ ok: true, ...result });
+    });
+}

package/dist/lib/webhooks.d.ts

@@ -0,0 +1,23 @@
+export type WebhookEvent = "guard.denied" | "guard.allowed" | "receipt.invalid" | "spend.cap_exceeded" | "merchant.trust_low";
+export type WebhookSubscription = {
+    id: string;
+    fleetId: string;
+    url: string;
+    events: WebhookEvent[];
+    secret: string;
+    createdAt: string;
+    active: boolean;
+};
+/** Reject SSRF targets (localhost, metadata, private IPs) for outbound webhook delivery. */
+export declare function assertValidWebhookUrl(url: string): void;
+export declare function registerWebhook(input: {
+    fleetId: string;
+    url: string;
+    events: WebhookEvent[];
+}): Promise<WebhookSubscription>;
+export declare function listWebhooks(fleetId?: string): Promise<WebhookSubscription[]>;
+export declare function deactivateWebhook(id: string, fleetId: string): Promise<boolean>;
+export declare function dispatchWebhooks(event: WebhookEvent, payload: Record<string, unknown>, fleetId?: string): Promise<{
+    delivered: number;
+    failed: number;
+}>;