x402-trust-layer 5.1.0

package/dist/lib/facilitators.js

@@ -0,0 +1,89 @@
+const FACILITATORS = [
+    { id: "dexter", url: "https://x402.dexter.cash" },
+    { id: "coinbase", url: "https://api.cdp.coinbase.com/platform/v2/x402" },
+];
+export async function checkFacilitatorHealth(facilitator) {
+    const start = Date.now();
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 8_000);
+        const res = await fetch(`${facilitator.url}/supported`, {
+            signal: controller.signal,
+            headers: { accept: "application/json" },
+        });
+        clearTimeout(timer);
+        if (!res.ok) {
+            return {
+                id: facilitator.id,
+                url: facilitator.url,
+                healthy: false,
+                latencyMs: Date.now() - start,
+                supportedNetworks: [],
+                error: `HTTP ${res.status}`,
+            };
+        }
+        const body = (await res.json());
+        const networks = (body.kinds ?? [])
+            .map((k) => k.network)
+            .filter((n) => Boolean(n));
+        return {
+            id: facilitator.id,
+            url: facilitator.url,
+            healthy: true,
+            latencyMs: Date.now() - start,
+            supportedNetworks: networks,
+            error: null,
+        };
+    }
+    catch (err) {
+        return {
+            id: facilitator.id,
+            url: facilitator.url,
+            healthy: false,
+            latencyMs: null,
+            supportedNetworks: [],
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+export async function rankFacilitators(preferNetwork, fastCheck = false) {
+    if (fastCheck) {
+        const note = "Fast-check synthetic data — not measured";
+        return [
+            {
+                id: "dexter",
+                url: "https://x402.dexter.cash",
+                healthy: true,
+                latencyMs: 8,
+                supportedNetworks: [
+                    "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+                    "eip155:8453",
+                    "eip155:137",
+                ],
+                error: null,
+                synthetic: true,
+                note,
+            },
+            {
+                id: "coinbase",
+                url: "https://api.cdp.coinbase.com/platform/v2/x402",
+                healthy: true,
+                latencyMs: 12,
+                supportedNetworks: ["eip155:8453"],
+                error: null,
+                synthetic: true,
+                note,
+            },
+        ];
+    }
+    const results = await Promise.all(FACILITATORS.map(checkFacilitatorHealth));
+    return results.sort((a, b) => {
+        if (a.healthy !== b.healthy)
+            return a.healthy ? -1 : 1;
+        const aNet = preferNetwork && a.supportedNetworks.some((n) => n.includes(preferNetwork)) ? 1 : 0;
+        const bNet = preferNetwork && b.supportedNetworks.some((n) => n.includes(preferNetwork)) ? 1 : 0;
+        if (aNet !== bNet)
+            return bNet - aNet;
+        return (a.latencyMs ?? 99_999) - (b.latencyMs ?? 99_999);
+    });
+}

package/dist/lib/host-policy.d.ts

@@ -0,0 +1,4 @@
+/** Exact host or proper subdomain match (avoids `evilallowed.com` matching `allowed.com`). */
+export declare function hostMatchesPattern(host: string, pattern: string): boolean;
+export declare function hostBlocked(host: string, blocked?: string[]): boolean;
+export declare function hostAllowed(host: string, allowed?: string[]): boolean;

package/dist/lib/host-policy.js

@@ -0,0 +1,20 @@
+/** Exact host or proper subdomain match (avoids `evilallowed.com` matching `allowed.com`). */
+export function hostMatchesPattern(host, pattern) {
+    const h = host.toLowerCase().trim();
+    const p = pattern.toLowerCase().trim();
+    if (!h || !p)
+        return false;
+    if (h === p)
+        return true;
+    return h.endsWith(`.${p}`);
+}
+export function hostBlocked(host, blocked) {
+    if (!blocked?.length)
+        return false;
+    return blocked.some((p) => hostMatchesPattern(host, p));
+}
+export function hostAllowed(host, allowed) {
+    if (!allowed?.length)
+        return true;
+    return allowed.some((p) => hostMatchesPattern(host, p));
+}

package/dist/lib/idempotency.d.ts

@@ -0,0 +1,4 @@
+import type { Request, Response, NextFunction } from "express";
+/** Return cached paid response when Idempotency-Key matches (CDP-style safe retries). */
+export declare function idempotencyPreCheck(req: Request, res: Response, next: NextFunction): void;
+export declare function idempotencyCapture(req: Request, res: Response, next: NextFunction): void;

package/dist/lib/idempotency.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { hasPaymentSignatureHeader } from "./x402-headers.js";
+import { db } from "./db.js";
+const TTL_SEC = 24 * 60 * 60;
+const getCache = db.prepare("SELECT status, body, body_hash, route, created_at FROM idempotency_cache WHERE cache_key = ?");
+const insertCache = db.prepare(`
+  INSERT OR REPLACE INTO idempotency_cache (cache_key, status, body, body_hash, route, created_at)
+  VALUES (?, ?, ?, ?, ?, unixepoch())
+`);
+const claimInflight = db.prepare("INSERT OR IGNORE INTO idempotency_inflight (cache_key, created_at) VALUES (?, unixepoch())");
+const releaseInflight = db.prepare("DELETE FROM idempotency_inflight WHERE cache_key = ?");
+const pruneCache = db.prepare("DELETE FROM idempotency_cache WHERE created_at < unixepoch() - ?");
+const pruneInflight = db.prepare("DELETE FROM idempotency_inflight WHERE created_at < unixepoch() - 3600");
+function maybePrune() {
+    if (Math.random() < 0.02) {
+        pruneCache.run(TTL_SEC);
+        pruneInflight.run();
+    }
+}
+function cacheKey(route, idempotencyKey) {
+    return `${route}::${idempotencyKey}`;
+}
+function bodyHash(req) {
+    const raw = JSON.stringify(req.body ?? {});
+    return createHash("sha256").update(raw).digest("hex").slice(0, 16);
+}
+function rowToEntry(row) {
+    return {
+        status: row.status,
+        body: JSON.parse(row.body),
+        bodyHash: row.body_hash,
+        route: row.route,
+        createdAt: row.created_at * 1000,
+    };
+}
+function tryClaimInFlight(cacheKeyStr) {
+    const r = claimInflight.run(cacheKeyStr);
+    return r.changes > 0;
+}
+function releaseClaim(cacheKeyStr) {
+    releaseInflight.run(cacheKeyStr);
+}
+function loadHit(keyStr) {
+    maybePrune();
+    const row = getCache.get(keyStr);
+    if (!row)
+        return null;
+    const entry = rowToEntry(row);
+    if (Date.now() - entry.createdAt >= TTL_SEC * 1000)
+        return null;
+    return entry;
+}
+/** Return cached paid response when Idempotency-Key matches (CDP-style safe retries). */
+export function idempotencyPreCheck(req, res, next) {
+    const key = String(req.headers["idempotency-key"] ?? "").trim();
+    if (!key || key.length > 128)
+        return void next();
+    if (!hasPaymentSignatureHeader(req))
+        return void next();
+    const route = req.path;
+    const keyStr = cacheKey(route, key);
+    const hit = loadHit(keyStr);
+    if (hit) {
+        if (hit.bodyHash !== bodyHash(req)) {
+            res.status(409).json({
+                error: "Idempotency-Key reused with different request body",
+                idempotencyKey: key,
+            });
+            return;
+        }
+        res.setHeader("Idempotency-Replayed", "true");
+        res.status(hit.status).json(hit.body);
+        return;
+    }
+    if (!tryClaimInFlight(keyStr)) {
+        const retry = loadHit(keyStr);
+        if (retry) {
+            if (retry.bodyHash !== bodyHash(req)) {
+                res.status(409).json({
+                    error: "Idempotency-Key reused with different request body",
+                    idempotencyKey: key,
+                });
+                return;
+            }
+            res.setHeader("Idempotency-Replayed", "true");
+            res.status(retry.status).json(retry.body);
+            return;
+        }
+        res.status(409).json({
+            error: "Idempotency-Key already in progress",
+            idempotencyKey: key,
+        });
+        return;
+    }
+    req.idempotencyClaimKey = keyStr;
+    next();
+}
+export function idempotencyCapture(req, res, next) {
+    const key = String(req.headers["idempotency-key"] ?? "").trim();
+    if (!key || key.length > 128)
+        return void next();
+    const claimKeyStr = req.idempotencyClaimKey;
+    const routeKey = cacheKey(req.path, key);
+    const origJson = res.json.bind(res);
+    res.json = ((body) => {
+        if (res.statusCode >= 200 && res.statusCode < 300 && hasPaymentSignatureHeader(req)) {
+            insertCache.run(routeKey, res.statusCode, JSON.stringify(body ?? null), bodyHash(req), req.path);
+        }
+        if (claimKeyStr)
+            releaseClaim(claimKeyStr);
+        return origJson(body);
+    });
+    const origEnd = res.end.bind(res);
+    res.end = ((...args) => {
+        if (claimKeyStr)
+            releaseClaim(claimKeyStr);
+        return origEnd(...args);
+    });
+    next();
+}

package/dist/lib/ledger.d.ts

@@ -0,0 +1,2 @@
+export declare function getSpentToday(agentId: string): Promise<number>;
+export declare function recordSpend(agentId: string, amountUsdc: number): Promise<number>;

package/dist/lib/ledger.js

@@ -0,0 +1,17 @@
+import { db } from "./db.js";
+function dayKey(agentId) {
+    const day = new Date().toISOString().slice(0, 10);
+    return `${agentId}:${day}`;
+}
+const sumDay = db.prepare(`SELECT COALESCE(SUM(amount_usdc), 0) AS total FROM spend_ledger WHERE agent_id = ? AND day_key = ?`);
+const insertSpend = db.prepare(`INSERT INTO spend_ledger (agent_id, amount_usdc, day_key) VALUES (?, ?, ?)`);
+export async function getSpentToday(agentId) {
+    const row = sumDay.get(agentId, dayKey(agentId));
+    return row?.total ?? 0;
+}
+export async function recordSpend(agentId, amountUsdc) {
+    const dk = dayKey(agentId);
+    insertSpend.run(agentId, amountUsdc, dk);
+    const row = sumDay.get(agentId, dk);
+    return row.total;
+}

package/dist/lib/logger.d.ts

@@ -0,0 +1,6 @@
+export declare const logger: {
+    info(fields: Record<string, unknown>, msg: string): void;
+    warn(fields: Record<string, unknown>, msg: string): void;
+    error(fields: Record<string, unknown>, msg: string): void;
+    debug(fields: Record<string, unknown>, msg: string): void;
+};

package/dist/lib/logger.js

@@ -0,0 +1,24 @@
+function emit(level, fields, msg) {
+    const line = JSON.stringify({ level, msg, time: new Date().toISOString(), ...fields });
+    if (level === "error")
+        console.error(line);
+    else if (level === "warn")
+        console.warn(line);
+    else
+        console.log(line);
+}
+export const logger = {
+    info(fields, msg) {
+        emit("info", fields, msg);
+    },
+    warn(fields, msg) {
+        emit("warn", fields, msg);
+    },
+    error(fields, msg) {
+        emit("error", fields, msg);
+    },
+    debug(fields, msg) {
+        if (process.env.LOG_LEVEL === "debug")
+            emit("debug", fields, msg);
+    },
+};

package/dist/lib/mandate-vc.d.ts

@@ -0,0 +1,20 @@
+import type { MandateRecord, MandateScope } from "./mandate.js";
+export type MandateVC = {
+    "@context": string[];
+    type: ["VerifiableCredential", "AgentPaymentMandate"];
+    issuer: string;
+    validFrom: string;
+    validUntil: string;
+    credentialSubject: {
+        id: string;
+        agentId: string;
+        scope: MandateScope;
+    };
+    proof: {
+        type: "HmacProof2026";
+        created: string;
+        proofValue: string;
+        verificationMethod: string;
+    };
+};
+export declare function mandateToVC(record: MandateRecord, principalDid?: string): MandateVC;

package/dist/lib/mandate-vc.js

@@ -0,0 +1,25 @@
+import { config } from "../config.js";
+export function mandateToVC(record, principalDid) {
+    const base = config.publicBaseUrl.replace(/\/$/, "");
+    return {
+        "@context": [
+            "https://www.w3.org/2018/credentials/v1",
+            "https://x402trustlayer.xyz/contexts/agent-payment-mandate/v1",
+        ],
+        type: ["VerifiableCredential", "AgentPaymentMandate"],
+        issuer: "did:web:x402trustlayer.xyz",
+        validFrom: record.issuedAt,
+        validUntil: record.scope.expiresAt,
+        credentialSubject: {
+            id: principalDid ?? `did:web:agent.id#${record.agentId}`,
+            agentId: record.agentId,
+            scope: record.scope,
+        },
+        proof: {
+            type: "HmacProof2026",
+            created: record.issuedAt,
+            proofValue: record.signature,
+            verificationMethod: `${base}/keys/hmac-signing-key`,
+        },
+    };
+}

package/dist/lib/mandate.d.ts

@@ -0,0 +1,44 @@
+export type MandateScope = {
+    maxPerTxUsdc: number;
+    dailyCapUsdc: number;
+    allowedMerchants: string[];
+    allowedCategories: string[];
+    allowedRails: string[];
+    expiresAt: string;
+};
+export type MandateRecord = {
+    mandateId: string;
+    issuedAt: string;
+    principal: string;
+    agentId: string;
+    intent: string;
+    intentHash: string;
+    scope: MandateScope;
+    suiteVersion: string;
+    signature: string;
+};
+/** Stable mandate id used by x402gle / Dexter verifier probes (see verify-examples.ts). */
+export declare const VERIFIER_PROBE_MANDATE_ID = "mdt_verifier_probe_example";
+export declare function hashIntent(intent: string): string;
+export declare function issueMandate(input: {
+    principal: string;
+    agentId: string;
+    intent: string;
+    scope: MandateScope;
+}): Promise<MandateRecord>;
+/** Seed a signed probe mandate so /api/mandate/verify passes x402gle audits. */
+export declare function ensureVerifierProbeMandate(): Promise<MandateRecord>;
+export type MandateCheck = {
+    amountUsdc: number;
+    merchant?: string;
+    category?: string;
+    rail?: string;
+};
+export type MandateVerifyResult = {
+    valid: boolean;
+    withinScope: boolean;
+    reason: string;
+    record: MandateRecord | null;
+    violations: string[];
+};
+export declare function verifyMandate(mandateId: string, proposed?: MandateCheck): Promise<MandateVerifyResult>;

package/dist/lib/mandate.js

@@ -0,0 +1,190 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { config } from "../config.js";
+import { db } from "./db.js";
+import { SUITE_VERSION } from "./version.js";
+const root = path.dirname(fileURLToPath(import.meta.url));
+const legacyStorePath = path.join(root, "..", "..", "data", "mandates.json");
+/** Stable mandate id used by x402gle / Dexter verifier probes (see verify-examples.ts). */
+export const VERIFIER_PROBE_MANDATE_ID = "mdt_verifier_probe_example";
+const selectById = db.prepare("SELECT * FROM mandates WHERE mandate_id = ?");
+const selectAll = db.prepare("SELECT * FROM mandates ORDER BY issued_at DESC");
+const upsertMandate = db.prepare(`
+  INSERT OR REPLACE INTO mandates (
+    mandate_id, principal, agent_id, intent, intent_hash, scope, signature,
+    issued_at, expires_at, suite_version
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+`);
+function rowToRecord(row) {
+    return {
+        mandateId: row.mandate_id,
+        issuedAt: row.issued_at,
+        principal: row.principal,
+        agentId: row.agent_id,
+        intent: row.intent,
+        intentHash: row.intent_hash,
+        scope: JSON.parse(row.scope),
+        suiteVersion: row.suite_version,
+        signature: row.signature,
+    };
+}
+function expiresAtUnix(scope) {
+    const t = new Date(scope.expiresAt).getTime();
+    return Number.isFinite(t) ? Math.floor(t / 1000) : null;
+}
+async function migrateLegacyJsonOnce() {
+    const count = db.prepare("SELECT COUNT(*) AS c FROM mandates").get().c;
+    if (count > 0)
+        return;
+    try {
+        const raw = await readFile(legacyStorePath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return;
+        for (const r of parsed) {
+            upsertMandate.run(r.mandateId, r.principal, r.agentId, r.intent, r.intentHash, JSON.stringify(r.scope), r.signature, r.issuedAt, expiresAtUnix(r.scope), r.suiteVersion ?? SUITE_VERSION);
+        }
+    }
+    catch {
+        /* no legacy file */
+    }
+}
+async function loadStore() {
+    await migrateLegacyJsonOnce();
+    return selectAll.all().map(rowToRecord);
+}
+async function saveRecord(record) {
+    upsertMandate.run(record.mandateId, record.principal, record.agentId, record.intent, record.intentHash, JSON.stringify(record.scope), record.signature, record.issuedAt, expiresAtUnix(record.scope), record.suiteVersion);
+}
+export function hashIntent(intent) {
+    return createHash("sha256").update(intent).digest("hex");
+}
+function canonical(record) {
+    return JSON.stringify({
+        mandateId: record.mandateId,
+        principal: record.principal,
+        agentId: record.agentId,
+        intentHash: record.intentHash,
+        scope: record.scope,
+    });
+}
+function sign(payload) {
+    return createHmac("sha256", config.attestationHmacSecret).update(payload).digest("hex");
+}
+function signaturesEqual(a, b) {
+    try {
+        const ba = Buffer.from(a, "hex");
+        const bb = Buffer.from(b, "hex");
+        if (ba.length !== bb.length)
+            return false;
+        return timingSafeEqual(ba, bb);
+    }
+    catch {
+        return false;
+    }
+}
+export async function issueMandate(input) {
+    const mandateId = `mdt_${randomBytes(8).toString("hex")}`;
+    const issuedAt = new Date().toISOString();
+    const intentHash = hashIntent(input.intent);
+    const base = {
+        mandateId,
+        issuedAt,
+        principal: input.principal,
+        agentId: input.agentId,
+        intent: input.intent,
+        intentHash,
+        scope: input.scope,
+    };
+    const signature = sign(canonical(base));
+    const record = { ...base, suiteVersion: SUITE_VERSION, signature };
+    await saveRecord(record);
+    return record;
+}
+/** Seed a signed probe mandate so /api/mandate/verify passes x402gle audits. */
+export async function ensureVerifierProbeMandate() {
+    const existing = selectById.get(VERIFIER_PROBE_MANDATE_ID);
+    if (existing)
+        return rowToRecord(existing);
+    const intent = "Buy ETH/USD oracle data for a trading bot, under $1 per call, daily $10 cap";
+    const scope = {
+        maxPerTxUsdc: 0.5,
+        dailyCapUsdc: 10,
+        allowedMerchants: ["myceliasignal.com", "dexter.cash", "api.myceliasignal.com"],
+        allowedCategories: ["market-data", "oracle"],
+        allowedRails: ["base-x402", "solana-x402", "visa-cli"],
+        expiresAt: new Date(Date.now() + 365 * 24 * 60 * 60_000).toISOString(),
+    };
+    const issuedAt = new Date().toISOString();
+    const intentHash = hashIntent(intent);
+    const base = {
+        mandateId: VERIFIER_PROBE_MANDATE_ID,
+        issuedAt,
+        principal: "cardholder:dexter-verifier",
+        agentId: "dexter-verifier-probe",
+        intent,
+        intentHash,
+        scope,
+    };
+    const signature = sign(canonical(base));
+    const record = { ...base, suiteVersion: SUITE_VERSION, signature };
+    await saveRecord(record);
+    return record;
+}
+export async function verifyMandate(mandateId, proposed) {
+    if (mandateId === VERIFIER_PROBE_MANDATE_ID) {
+        await ensureVerifierProbeMandate();
+    }
+    await migrateLegacyJsonOnce();
+    const row = selectById.get(mandateId);
+    const record = row ? rowToRecord(row) : null;
+    if (!record) {
+        return { valid: false, withinScope: false, reason: "Mandate not found", record: null, violations: ["not_found"] };
+    }
+    const expected = sign(canonical({
+        mandateId: record.mandateId,
+        issuedAt: record.issuedAt,
+        principal: record.principal,
+        agentId: record.agentId,
+        intent: record.intent,
+        intentHash: record.intentHash,
+        scope: record.scope,
+    }));
+    if (!signaturesEqual(expected, record.signature)) {
+        return { valid: false, withinScope: false, reason: "Signature mismatch (tampered)", record, violations: ["signature"] };
+    }
+    if (new Date(record.scope.expiresAt) < new Date()) {
+        return { valid: true, withinScope: false, reason: "Mandate expired", record, violations: ["expired"] };
+    }
+    const violations = [];
+    if (proposed) {
+        if (proposed.amountUsdc > record.scope.maxPerTxUsdc) {
+            violations.push(`amount ${proposed.amountUsdc} exceeds maxPerTxUsdc ${record.scope.maxPerTxUsdc}`);
+        }
+        if (proposed.merchant &&
+            record.scope.allowedMerchants.length > 0 &&
+            !record.scope.allowedMerchants.some((m) => proposed.merchant.toLowerCase().includes(m.toLowerCase()))) {
+            violations.push(`merchant ${proposed.merchant} not in allowedMerchants`);
+        }
+        if (proposed.category &&
+            record.scope.allowedCategories.length > 0 &&
+            !record.scope.allowedCategories.includes(proposed.category)) {
+            violations.push(`category ${proposed.category} not in allowedCategories`);
+        }
+        if (proposed.rail &&
+            record.scope.allowedRails.length > 0 &&
+            !record.scope.allowedRails.includes(proposed.rail)) {
+            violations.push(`rail ${proposed.rail} not in allowedRails`);
+        }
+    }
+    const withinScope = violations.length === 0;
+    return {
+        valid: true,
+        withinScope,
+        reason: withinScope ? "Valid mandate, proposed payment within scope" : "Valid signature but proposed payment violates scope",
+        record,
+        violations,
+    };
+}

package/dist/lib/marketplace.d.ts

@@ -0,0 +1,7 @@
+import type { MarketplaceResource } from "../types.js";
+export declare function searchMarketplace(query: string, options?: {
+    limit?: number;
+    maxPriceUsdc?: number;
+    verified?: boolean;
+}): Promise<MarketplaceResource[]>;
+export declare function pickBestResource(resources: MarketplaceResource[], preferNetwork?: string, query?: string): MarketplaceResource | null;