@agirails/sdk 3.2.0 → 3.4.1

package/dist/server/buildX402Server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildX402Server.d.ts","sourceRoot":"","sources":["../../src/server/buildX402Server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;;AAEH,OAAO,EAAE,kBAAkB,EAAyB,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,KAAK,YAAY,EAAsB,MAAM,iBAAiB,CAAC;AAOhG;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IAEd,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IAEd,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,mEAAmE;IACnE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB,8BAA8B;IAC9B,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAE9B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,UAAU,EAAE,sBAAsB,CAAC;IAEnC;;;OAGG;IACH,MAAM,EAAE,YAAY,CAAC;IAErB,0EAA0E;IAC1E,cAAc,EAAE,kBAAkB,CAAC;CACpC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAyH3B"}

package/dist/server/buildX402Server.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * buildX402Server — factory that maps AGIRAILS agent config into
+ * a ready-to-use x402 v2 resource server + route definitions.
+ *
+ * Design: we never wrap or re-export framework middleware. The output
+ * plugs directly into @x402/express, @x402/hono, @x402/next, or raw
+ * @x402/core processHTTPRequest for any framework.
+ *
+ * @module server/buildX402Server
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildX402Server = void 0;
+const server_1 = require("@x402/core/server");
+const http_1 = require("@x402/core/http");
+const server_2 = require("@x402/evm/exact/server");
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Build a configured x402 v2 resource server from simple route definitions.
+ *
+ * Async because it calls `httpServer.initialize()` which fetches facilitator
+ * capabilities and validates that all route schemes are supported.
+ *
+ * @param config - Server configuration
+ * @returns Ready-to-use server + routes
+ * @throws {Error} If facilitator is unreachable or route schemes unsupported
+ *
+ * @example
+ * ```typescript
+ * // Express
+ * import { buildX402Server } from '@agirails/sdk/server';
+ * import { paymentMiddleware } from '@x402/express';
+ * import express from 'express';
+ *
+ * const { httpServer, routes } = await buildX402Server({
+ *   payTo: client.getAddress(),
+ *   network: 'eip155:84532',
+ *   routes: [{ route: 'GET /api/data', price: '$0.01' }],
+ * });
+ *
+ * const app = express();
+ * app.use(paymentMiddleware(routes, httpServer));
+ * app.get('/api/data', (req, res) => res.json({ data: 42 }));
+ * app.listen(3000);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Hono
+ * import { buildX402Server } from '@agirails/sdk/server';
+ * import { paymentMiddleware } from '@x402/hono';
+ * import { Hono } from 'hono';
+ *
+ * const { httpServer, routes } = await buildX402Server({
+ *   payTo: '0xYourAddress',
+ *   network: 'eip155:8453',
+ *   routes: [{ route: 'GET /api/premium', price: '$0.10' }],
+ * });
+ *
+ * const app = new Hono();
+ * app.use('*', paymentMiddleware(routes, httpServer));
+ * ```
+ */
+async function buildX402Server(config) {
+    if (!config.payTo || !/^0x[0-9a-f]{40}$/i.test(config.payTo)) {
+        throw new Error(`buildX402Server: payTo must be a valid Ethereum address, got "${config.payTo}"`);
+    }
+    if (!config.network || !config.network.includes(':')) {
+        throw new Error(`buildX402Server: network must be a CAIP-2 identifier (e.g. "eip155:8453"), got "${config.network}"`);
+    }
+    if (!config.routes || config.routes.length === 0) {
+        throw new Error('buildX402Server: at least one route is required');
+    }
+    // 1. Facilitator client
+    const facilitator = new server_1.HTTPFacilitatorClient({
+        url: config.facilitatorUrl ?? 'https://x402.org/facilitator',
+    });
+    // 2. Resource server with EVM exact scheme
+    const resourceServer = new server_1.x402ResourceServer(facilitator);
+    (0, server_2.registerExactEvmScheme)(resourceServer);
+    // 3. Build route config
+    const routesConfig = {};
+    const seen = new Set();
+    for (const def of config.routes) {
+        if (!def.route || !/^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+\/\S*$/.test(def.route)) {
+            throw new Error(`buildX402Server: route must be "METHOD /path" format (e.g. "GET /api/data"), got "${def.route}"`);
+        }
+        if (seen.has(def.route)) {
+            throw new Error(`buildX402Server: duplicate route "${def.route}". Each route must be unique.`);
+        }
+        seen.add(def.route);
+        const routePayTo = def.payTo ?? config.payTo;
+        if (!/^0x[0-9a-f]{40}$/i.test(routePayTo)) {
+            throw new Error(`buildX402Server: route "${def.route}" has invalid payTo "${routePayTo}"`);
+        }
+        const routeNetwork = def.network ?? config.network;
+        if (!routeNetwork.includes(':')) {
+            throw new Error(`buildX402Server: route "${def.route}" has invalid network "${routeNetwork}" (must be CAIP-2)`);
+        }
+        if (!def.price || (typeof def.price === 'string' && def.price.trim() === '')) {
+            throw new Error(`buildX402Server: route "${def.route}" has empty or missing price`);
+        }
+        if (typeof def.price === 'string') {
+            const trimmed = def.price.trim();
+            if (!/^\$?\d+(\.\d+)?$/.test(trimmed)) {
+                throw new Error(`buildX402Server: route "${def.route}" has invalid price "${def.price}" (expected format: "$0.10" or "0.50")`);
+            }
+            if (parseFloat(trimmed.replace('$', '')) <= 0) {
+                throw new Error(`buildX402Server: route "${def.route}" price must be > 0, got "${def.price}"`);
+            }
+        }
+        const timeout = def.maxTimeoutSeconds ?? 300;
+        if (!Number.isFinite(timeout) || timeout <= 0) {
+            throw new Error(`buildX402Server: route "${def.route}" has invalid maxTimeoutSeconds ${def.maxTimeoutSeconds} (must be > 0)`);
+        }
+        const paymentOption = {
+            scheme: 'exact',
+            network: routeNetwork,
+            payTo: routePayTo,
+            price: def.price,
+            maxTimeoutSeconds: timeout,
+        };
+        // Advertise Permit2 so Smart Wallet buyers work out of the box
+        if (config.preferPermit2 !== false) {
+            paymentOption.extra = { assetTransferMethod: 'permit2' };
+        }
+        routesConfig[def.route] = {
+            accepts: [paymentOption],
+            description: def.description,
+        };
+    }
+    // 4. HTTP resource server
+    const httpServer = new http_1.x402HTTPResourceServer(resourceServer, routesConfig);
+    // 5. Initialize (fetches facilitator capabilities, validates routes)
+    try {
+        await httpServer.initialize();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`buildX402Server: failed to initialize — ${msg}`);
+    }
+    return {
+        httpServer,
+        routes: routesConfig,
+        resourceServer,
+    };
+}
+exports.buildX402Server = buildX402Server;
+//# sourceMappingURL=buildX402Server.js.map

package/dist/server/buildX402Server.js.map

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

package/dist/server/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Server Module — x402 v2 seller-side helpers.
+ *
+ * Framework-agnostic: builds a configured `x402HTTPResourceServer` + routes
+ * object that plugs directly into upstream middleware (`@x402/express`,
+ * `@x402/hono`, `@x402/next`) or any framework via the raw processHTTPRequest
+ * API from `@x402/core`.
+ *
+ * @module server
+ *
+ * @example
+ * ```typescript
+ * import { buildX402Server } from '@agirails/sdk/server';
+ * import { paymentMiddleware } from '@x402/express';
+ * import express from 'express';
+ *
+ * const { httpServer, routes } = await buildX402Server({
+ *   payTo: '0xYourAddress',
+ *   network: 'eip155:84532',
+ *   routes: [
+ *     { route: 'GET /api/premium', price: '$0.10', description: 'Premium content' },
+ *   ],
+ * });
+ *
+ * const app = express();
+ * app.use(paymentMiddleware(routes, httpServer));
+ * app.get('/api/premium', (req, res) => res.json({ secret: '...' }));
+ * app.listen(3000);
+ * ```
+ */
+export { buildX402Server } from './buildX402Server';
+export type { X402ServerConfig, X402RouteDefinition, X402ServerResult, } from './buildX402Server';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EACV,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC"}

package/dist/server/index.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Server Module — x402 v2 seller-side helpers.
+ *
+ * Framework-agnostic: builds a configured `x402HTTPResourceServer` + routes
+ * object that plugs directly into upstream middleware (`@x402/express`,
+ * `@x402/hono`, `@x402/next`) or any framework via the raw processHTTPRequest
+ * API from `@x402/core`.
+ *
+ * @module server
+ *
+ * @example
+ * ```typescript
+ * import { buildX402Server } from '@agirails/sdk/server';
+ * import { paymentMiddleware } from '@x402/express';
+ * import express from 'express';
+ *
+ * const { httpServer, routes } = await buildX402Server({
+ *   payTo: '0xYourAddress',
+ *   network: 'eip155:84532',
+ *   routes: [
+ *     { route: 'GET /api/premium', price: '$0.10', description: 'Premium content' },
+ *   ],
+ * });
+ *
+ * const app = express();
+ * app.use(paymentMiddleware(routes, httpServer));
+ * app.get('/api/premium', (req, res) => res.json({ secret: '...' }));
+ * app.listen(3000);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildX402Server = void 0;
+var buildX402Server_1 = require("./buildX402Server");
+Object.defineProperty(exports, "buildX402Server", { enumerable: true, get: function () { return buildX402Server_1.buildX402Server; } });
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAEH,qDAAoD;AAA3C,kHAAA,eAAe,OAAA"}

package/dist/transport/QuoteChannel.d.ts

@@ -0,0 +1,201 @@
+/**
+ * QuoteChannel — HTTPS transport for AIP-2.1 quote + counter-offer messages.
+ *
+ * Split into three responsibilities so the SDK is framework-agnostic:
+ *
+ *  1. `QuoteChannelClient`  — sends a signed message to a peer's endpoint.
+ *     Used by buyers (posting counter-offers to the provider) and by
+ *     providers (posting quotes to the buyer). Plain fetch + timeout.
+ *
+ *  2. `QuoteChannelHandler` — framework-agnostic receive-side handler.
+ *     Callers wire it into whatever HTTP framework they use (Express,
+ *     Next.js route handler, Fastify, etc). Enforces the security model
+ *     from AIP-2.1-DRAFT §8:
+ *        - URL path binding: `/quote-channel/{chainId}/{txId}` must
+ *          match message.chainId / message.txId (closes T2 + T5).
+ *        - EIP-712 signature verification (closes "anyone can POST").
+ *        - TTL + grace window (closes T3).
+ *        - Nonce LRU dedup (closes T1, idempotent replay).
+ *     Rate limiting is intentionally out of scope — framework-level
+ *     concern (Next.js middleware, Express rate-limit, nginx, etc).
+ *
+ *  3. `DedupStore` — swappable backing for the nonce LRU. In-memory
+ *     default for single-process use; callers can plug Redis etc. for
+ *     multi-worker production.
+ *
+ * @module transport/QuoteChannel
+ * @see Protocol/aips/AIP-2.1-DRAFT.md §8 (threat model + mitigations)
+ */
+import { QuoteMessage } from '../builders/QuoteBuilder';
+import { CounterOfferMessage } from '../builders/CounterOfferBuilder';
+/** Path pattern builders use / handlers expect. */
+export declare function buildChannelPath(chainId: number, txId: string): string;
+export declare const TTL_GRACE_SECONDS = 30;
+export declare const DEDUP_TTL_SECONDS = 90000;
+/**
+ * Wire payload posted by the client and parsed by the handler.
+ * Discriminated by `type` so the same endpoint serves both directions.
+ */
+export type ChannelPayload = {
+    type: 'agirails.quote.v1';
+    message: QuoteMessage;
+} | {
+    type: 'agirails.counteroffer.v1';
+    message: CounterOfferMessage;
+};
+export interface DedupStore {
+    /**
+     * Atomic "record if absent". Returns:
+     *   'recorded' — the key was not present (or had expired) and has now
+     *                been recorded with the given TTL. Caller treats this
+     *                POST as fresh and performs side effects.
+     *   'duplicate' — the key was already present and unexpired. Caller
+     *                 must return an idempotent cached response without
+     *                 performing side effects.
+     *
+     * MUST be atomic at the backend level. Single-process JS gets this
+     * trivially (no real concurrency); Redis implementations use
+     * `SET key 1 NX PX ttlMs` which is natively atomic and correctly
+     * handles multiple concurrent workers competing on the same key.
+     *
+     * Separate check+record would open a TOCTOU window where two
+     * workers both observe 'fresh' and both commit — that's the P2
+     * audit finding this interface closes.
+     */
+    recordOnce(key: string, ttlMs: number): Promise<'recorded' | 'duplicate'>;
+}
+/**
+ * Single-process in-memory LRU. Callers replace this in production
+ * with a distributed store (Redis SET NX EX, DynamoDB conditional put,
+ * Postgres INSERT ... ON CONFLICT DO NOTHING, etc).
+ *
+ * Atomicity here is free because JavaScript event-loop execution is
+ * single-threaded — a `recordOnce` call cannot be interrupted mid-way.
+ * Multi-worker deployments MUST use a real distributed store or will
+ * see duplicate 'recorded' returns across workers.
+ */
+export declare class InMemoryDedupStore implements DedupStore {
+    private readonly entries;
+    private readonly maxSize;
+    constructor(maxSize?: number);
+    recordOnce(key: string, ttlMs: number): Promise<'recorded' | 'duplicate'>;
+    /** Drop entries whose TTL has elapsed. O(n) — fine for our sizes. */
+    private dropExpired;
+    /** Bound the map at `maxSize` by evicting oldest-inserted keys. */
+    private trimToSize;
+}
+export interface QuoteChannelClientConfig {
+    /** Per-request timeout in ms. Default 10s. */
+    timeoutMs?: number;
+    /** Override fetch for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Allow insecure targets (http://, localhost, RFC1918, link-local).
+     * Default false (production hardening). Set to true ONLY for local
+     * dev or integration tests running against a mock server.
+     *
+     * Note: this is a URL-string check only. DNS rebinding can still bypass
+     * it — production deployments that are extra paranoid should put the
+     * client behind an HTTP proxy that enforces the same rules against the
+     * resolved IP at request time.
+     */
+    allowInsecureTargets?: boolean;
+}
+export declare class QuoteChannelClient {
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly allowInsecureTargets;
+    constructor(cfg?: QuoteChannelClientConfig);
+    /** POST a provider quote to the buyer's endpoint. */
+    sendQuote(peerEndpoint: string, quote: QuoteMessage): Promise<void>;
+    /** POST a buyer counter-offer to the provider's endpoint. */
+    sendCounter(peerEndpoint: string, counter: CounterOfferMessage): Promise<void>;
+    private post;
+}
+export interface QuoteChannelHandlerConfig {
+    /** Kernel address per chainId — used for EIP-712 domain when verifying. */
+    kernelAddressByChainId: Record<number, string>;
+    /** Dedup store. Defaults to in-memory (single process). */
+    dedupStore?: DedupStore;
+    /** TTL grace window in seconds for `expiresAt` check. Defaults to 30s. */
+    ttlGraceSeconds?: number;
+}
+export interface HandlerContext {
+    /** Chain ID parsed from the URL path. */
+    pathChainId: number;
+    /** txId parsed from the URL path (0x-prefixed 64-hex). */
+    pathTxId: string;
+}
+export type HandlerResult = {
+    status: 201;
+    body: {
+        accepted: true;
+        duplicate: false;
+    };
+} | {
+    status: 200;
+    body: {
+        accepted: true;
+        duplicate: true;
+    };
+} | {
+    status: 400;
+    body: {
+        accepted: false;
+        reason: string;
+    };
+} | {
+    status: 401;
+    body: {
+        accepted: false;
+        reason: string;
+    };
+} | {
+    status: 410;
+    body: {
+        accepted: false;
+        reason: string;
+    };
+} | {
+    status: 422;
+    body: {
+        accepted: false;
+        reason: string;
+    };
+};
+export declare class QuoteChannelHandler {
+    private readonly kernelAddressByChainId;
+    private readonly dedupStore;
+    private readonly ttlGraceSeconds;
+    private readonly quoteVerifier;
+    private readonly counterVerifier;
+    constructor(cfg: QuoteChannelHandlerConfig);
+    /**
+     * Validate + dedup an incoming POST.
+     * Caller is responsible for: parsing URL path into `pathChainId` /
+     * `pathTxId`, parsing request body into `ChannelPayload`, and rate
+     * limiting the endpoint at the framework level.
+     */
+    handle(payload: unknown, ctx: HandlerContext): Promise<HandlerResult>;
+}
+/**
+ * Reject peer URLs that could SSRF into local / internal infrastructure.
+ *
+ * Rules (default, `allowInsecureTargets=false`):
+ *   - scheme MUST be https
+ *   - hostname MUST NOT be `localhost`
+ *   - hostname MUST NOT be a literal loopback IP (127.x.x.x, ::1)
+ *   - hostname MUST NOT be a literal link-local IP (169.254.x.x, fe80::/10)
+ *     — this also covers AWS metadata at 169.254.169.254
+ *   - hostname MUST NOT be a literal RFC1918 private IP (10.x, 172.16-31.x,
+ *     192.168.x) or IPv6 ULA (fc00::/7)
+ *
+ * Dev mode (`allowInsecureTargets=true`): no restrictions, callers
+ * opting in are responsible for their own network security.
+ *
+ * @throws Error if the URL fails the checks. Error message is deliberately
+ *   specific so test fixtures and diagnostics can assert on it.
+ * @internal Exported for unit tests.
+ */
+export declare function assertSafePeerUrl(url: string, allowInsecureTargets: boolean): void;
+//# sourceMappingURL=QuoteChannel.d.ts.map

package/dist/transport/QuoteChannel.d.ts.map

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