@odatano/x402 0.1.0

package/srv/core/asset.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Cardano-x402-v2 asset identifier handling.
+ *
+ * v2 expresses an asset as a single string:
+ *   - For native assets:  `<policyIdHex>.<assetNameHex>`  (DOT separator)
+ *     where policyId is 28 bytes (56 hex chars) and assetNameHex is 0..64 hex chars.
+ *     An empty name (NFT-style) is `<policyIdHex>.`
+ *   - For ADA:            the literal string `'lovelace'`
+ *
+ * v1 split policy and name across `asset` + `extra.assetNameHex`; we
+ * refuse that shape outright so consumers can't mix specs.
+ */
+export interface ParsedAsset {
+    /** raw v2 string as emitted by buildPaymentRequirements */
+    raw: string;
+    /** true when the asset is ADA (lovelace) */
+    isLovelace: boolean;
+    /** lowercase 56-char hex; empty string when isLovelace */
+    policyId: string;
+    /** lowercase hex, 0..64 chars; empty string when isLovelace OR when name is empty */
+    assetNameHex: string;
+    /**
+     * Concatenation used as the canonical UTxO `unit` key by Blockfrost /
+     * Koios / ODATANO (`policyId + assetNameHex`). Empty for lovelace —
+     * comparisons against UTxO assets short-circuit via `isLovelace`.
+     */
+    unit: string;
+}
+/** Parse a v2 asset string. Throws X402Error on malformed input. */
+export declare function parseAsset(s: string): ParsedAsset;
+/** Build a v2 asset string from policy + assetName parts. */
+export declare function buildAssetString(policyId: string, assetNameHex?: string): string;
+//# sourceMappingURL=asset.d.ts.map

package/srv/core/asset.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Cardano-x402-v2 asset identifier handling.
+ *
+ * v2 expresses an asset as a single string:
+ *   - For native assets:  `<policyIdHex>.<assetNameHex>`  (DOT separator)
+ *     where policyId is 28 bytes (56 hex chars) and assetNameHex is 0..64 hex chars.
+ *     An empty name (NFT-style) is `<policyIdHex>.`
+ *   - For ADA:            the literal string `'lovelace'`
+ *
+ * v1 split policy and name across `asset` + `extra.assetNameHex`; we
+ * refuse that shape outright so consumers can't mix specs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAsset = parseAsset;
+exports.buildAssetString = buildAssetString;
+const errors_1 = require("./errors");
+const POLICY_RE = /^[0-9a-f]{56}$/i;
+const NAME_RE = /^[0-9a-f]{0,64}$/i;
+/** Parse a v2 asset string. Throws X402Error on malformed input. */
+function parseAsset(s) {
+    if (typeof s !== 'string' || s.length === 0) {
+        throw new errors_1.X402Error(errors_1.Codes.INVALID_ASSET_FORMAT, 'asset must be a non-empty string');
+    }
+    if (s === 'lovelace') {
+        return { raw: s, isLovelace: true, policyId: '', assetNameHex: '', unit: '' };
+    }
+    const dot = s.indexOf('.');
+    if (dot < 0) {
+        throw new errors_1.X402Error(errors_1.Codes.INVALID_ASSET_FORMAT, `asset '${s}' must be 'lovelace' or '<policyIdHex>.<assetNameHex>' (dot-separated)`);
+    }
+    const policyId = s.slice(0, dot).toLowerCase();
+    const assetNameHex = s.slice(dot + 1).toLowerCase();
+    if (!POLICY_RE.test(policyId)) {
+        throw new errors_1.X402Error(errors_1.Codes.INVALID_ASSET_FORMAT, `asset policyId '${policyId}' must be 28-byte (56-char) hex`);
+    }
+    if (!NAME_RE.test(assetNameHex)) {
+        throw new errors_1.X402Error(errors_1.Codes.INVALID_ASSET_FORMAT, `asset name '${assetNameHex}' must be 0..32 byte (0..64 char) hex`);
+    }
+    return {
+        raw: s,
+        isLovelace: false,
+        policyId,
+        assetNameHex,
+        unit: (policyId + assetNameHex).toLowerCase(),
+    };
+}
+/** Build a v2 asset string from policy + assetName parts. */
+function buildAssetString(policyId, assetNameHex = '') {
+    if (!POLICY_RE.test(policyId)) {
+        throw new errors_1.X402Error(errors_1.Codes.INVALID_ASSET_FORMAT, `buildAssetString: policyId '${policyId}' must be 56-char hex`);
+    }
+    if (assetNameHex && !NAME_RE.test(assetNameHex)) {
+        throw new errors_1.X402Error(errors_1.Codes.INVALID_ASSET_FORMAT, `buildAssetString: assetNameHex '${assetNameHex}' must be 0..64-char hex`);
+    }
+    return `${policyId.toLowerCase()}.${assetNameHex.toLowerCase()}`;
+}

package/srv/core/decode.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Decode the `PAYMENT-SIGNATURE` header (Cardano-x402-v2 wire format).
+ *
+ * Wire format:
+ *   PAYMENT-SIGNATURE: base64(JSON.stringify({
+ *     x402Version: 2,
+ *     scheme: 'exact',
+ *     network: 'cardano:preprod' | 'cardano:mainnet' | 'cardano:preview',
+ *     payload: {
+ *       transaction: '<base64 CBOR of signed tx>',
+ *       nonce:       '<txHash>#<outputIndex>'
+ *     }
+ *   }))
+ *
+ * The decoder is **pure** — no chain calls, no DB. It produces a
+ * `DecodedPayment` that downstream `validate.ts` checks against
+ * `PaymentRequirementEntry` (the 6 mandatory checks).
+ */
+import type { DecodedPayment } from './types';
+/**
+ * Decode a `PAYMENT-SIGNATURE` header value end-to-end. Throws X402Error
+ * with a precise `code` on any malformed input — the caller catches and
+ * surfaces the code in the 402 response body.
+ */
+export declare function decode(paymentHeader: string | undefined | null): DecodedPayment;
+//# sourceMappingURL=decode.d.ts.map

package/srv/core/decode.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * Decode the `PAYMENT-SIGNATURE` header (Cardano-x402-v2 wire format).
+ *
+ * Wire format:
+ *   PAYMENT-SIGNATURE: base64(JSON.stringify({
+ *     x402Version: 2,
+ *     scheme: 'exact',
+ *     network: 'cardano:preprod' | 'cardano:mainnet' | 'cardano:preview',
+ *     payload: {
+ *       transaction: '<base64 CBOR of signed tx>',
+ *       nonce:       '<txHash>#<outputIndex>'
+ *     }
+ *   }))
+ *
+ * The decoder is **pure** — no chain calls, no DB. It produces a
+ * `DecodedPayment` that downstream `validate.ts` checks against
+ * `PaymentRequirementEntry` (the 6 mandatory checks).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decode = decode;
+const CSL = __importStar(require("@emurgo/cardano-serialization-lib-nodejs"));
+const errors_1 = require("./errors");
+const SUPPORTED_VERSION = 2;
+const SUPPORTED_SCHEME = 'exact';
+const NONCE_RE = /^([0-9a-f]{64})#(\d+)$/i;
+function decodeBase64ToBuffer(s, errCode) {
+    // Node's Buffer.from is lenient (silently drops bad chars). Re-encode
+    // and compare modulo padding to catch malformed input early — otherwise
+    // garbage in `transaction` would only fail at CBOR parse time with a
+    // confusing error.
+    const buf = Buffer.from(s, 'base64');
+    if (buf.toString('base64').replace(/=+$/, '') !== String(s).replace(/=+$/, '')) {
+        throw new errors_1.X402Error(errCode, 'malformed base64 payload');
+    }
+    return buf;
+}
+function extractOutputs(txBody) {
+    const out = txBody.outputs();
+    const result = [];
+    for (let i = 0; i < out.len(); i++) {
+        const o = out.get(i);
+        const addr = o.address().to_bech32();
+        const value = o.amount();
+        const lovelace = value.coin().to_str();
+        const assets = [];
+        const ma = value.multiasset();
+        if (ma) {
+            const policies = ma.keys();
+            for (let p = 0; p < policies.len(); p++) {
+                const policy = policies.get(p);
+                const policyHex = Buffer.from(policy.to_bytes()).toString('hex').toLowerCase();
+                const assetMap = ma.get(policy);
+                if (!assetMap)
+                    continue;
+                const names = assetMap.keys();
+                for (let n = 0; n < names.len(); n++) {
+                    const name = names.get(n);
+                    const nameHex = Buffer.from(name.name()).toString('hex').toLowerCase();
+                    const qty = assetMap.get(name);
+                    if (!qty)
+                        continue;
+                    assets.push({
+                        unit: (policyHex + nameHex),
+                        policyId: policyHex,
+                        assetNameHex: nameHex,
+                        quantity: qty.to_str(),
+                    });
+                }
+            }
+        }
+        result.push({ outputIndex: i, address: addr, lovelace, assets });
+    }
+    return result;
+}
+function extractInputs(txBody) {
+    const ins = txBody.inputs();
+    const result = [];
+    for (let i = 0; i < ins.len(); i++) {
+        const inp = ins.get(i);
+        result.push({
+            txHash: Buffer.from(inp.transaction_id().to_bytes()).toString('hex').toLowerCase(),
+            outputIndex: inp.index(),
+        });
+    }
+    return result;
+}
+/**
+ * Pull validity range bounds. CSL exposes `ttl()` (upper) since Shelley
+ * and `validity_start_interval_bignum()` (lower) since Allegra. Both can
+ * be absent — in which case we return null and the TTL check is skipped
+ * (per v2 spec: only validate TTL if buyer set one).
+ */
+function extractValidityRange(txBody) {
+    let ttlSlot = null;
+    let validityStartSlot = null;
+    try {
+        const ttl = txBody.ttl_bignum();
+        if (ttl) {
+            // BigNum → string → number; slots fit comfortably in JS number
+            // (current preprod ~85M, max safe int 9e15).
+            ttlSlot = Number(ttl.to_str());
+            if (!Number.isFinite(ttlSlot))
+                ttlSlot = null;
+        }
+    }
+    catch {
+        ttlSlot = null;
+    }
+    try {
+        const start = txBody.validity_start_interval_bignum();
+        if (start) {
+            validityStartSlot = Number(start.to_str());
+            if (!Number.isFinite(validityStartSlot))
+                validityStartSlot = null;
+        }
+    }
+    catch {
+        validityStartSlot = null;
+    }
+    return { ttlSlot, validityStartSlot };
+}
+function parseNonceRef(nonce) {
+    const m = NONCE_RE.exec(nonce);
+    if (!m) {
+        throw new errors_1.X402Error(errors_1.Codes.INVALID_NONCE_FORMAT, `nonce '${nonce}' must be '<txHash>#<outputIndex>' (64-hex#int)`);
+    }
+    const idx = Number(m[2]);
+    if (!Number.isFinite(idx) || idx < 0 || idx > 65535) {
+        throw new errors_1.X402Error(errors_1.Codes.INVALID_NONCE_FORMAT, `nonce output index ${m[2]} out of range`);
+    }
+    return { txHash: m[1].toLowerCase(), index: idx };
+}
+/**
+ * Decode a `PAYMENT-SIGNATURE` header value end-to-end. Throws X402Error
+ * with a precise `code` on any malformed input — the caller catches and
+ * surfaces the code in the 402 response body.
+ */
+function decode(paymentHeader) {
+    if (!paymentHeader || typeof paymentHeader !== 'string') {
+        throw new errors_1.X402Error(errors_1.Codes.MISSING_HEADER);
+    }
+    // 1. base64 → JSON
+    const outerBuf = decodeBase64ToBuffer(paymentHeader, errors_1.Codes.INVALID_BASE64);
+    let raw;
+    try {
+        raw = JSON.parse(outerBuf.toString('utf8'));
+    }
+    catch {
+        throw new errors_1.X402Error(errors_1.Codes.INVALID_JSON, 'PAYMENT-SIGNATURE body is not valid JSON');
+    }
+    // 2. Field shape
+    for (const f of ['x402Version', 'scheme', 'network', 'payload']) {
+        if (!(f in raw))
+            throw new errors_1.X402Error(errors_1.Codes.MISSING_FIELD, `missing field: ${f}`);
+    }
+    if (raw.x402Version !== SUPPORTED_VERSION) {
+        throw new errors_1.X402Error(errors_1.Codes.UNSUPPORTED_VERSION, `x402Version ${raw.x402Version} not supported (only ${SUPPORTED_VERSION})`);
+    }
+    if (raw.scheme !== SUPPORTED_SCHEME) {
+        throw new errors_1.X402Error(errors_1.Codes.UNSUPPORTED_SCHEME, `scheme '${raw.scheme}' not supported (only '${SUPPORTED_SCHEME}')`);
+    }
+    const payload = raw.payload;
+    if (!payload || typeof payload.transaction !== 'string') {
+        throw new errors_1.X402Error(errors_1.Codes.MISSING_FIELD, 'payload.transaction is required');
+    }
+    if (typeof payload.nonce !== 'string' || payload.nonce.length === 0) {
+        throw new errors_1.X402Error(errors_1.Codes.MISSING_FIELD, 'payload.nonce is required (v2 UTxO-ref)');
+    }
+    // 3. Tx CBOR → CSL Transaction (parses both `transaction` and `fixed`
+    //    representation; we need both — Transaction for body access,
+    //    FixedTransaction for byte-stable hash).
+    const txBuf = decodeBase64ToBuffer(payload.transaction, errors_1.Codes.INVALID_CBOR);
+    let tx;
+    try {
+        tx = CSL.Transaction.from_bytes(txBuf);
+    }
+    catch {
+        throw new errors_1.X402Error(errors_1.Codes.INVALID_CBOR, 'transaction CBOR did not decode');
+    }
+    // 4. Diagnostics
+    const txBody = tx.body();
+    const wits = tx.witness_set();
+    const vkeys = wits.vkeys();
+    const vkeyWitnessCount = vkeys ? vkeys.len() : 0;
+    const txHashBytes = CSL.FixedTransaction
+        .from_bytes(txBuf)
+        .transaction_hash()
+        .to_bytes();
+    const txHash = Buffer.from(txHashBytes).toString('hex').toLowerCase();
+    const validity = extractValidityRange(txBody);
+    const nonce = parseNonceRef(payload.nonce);
+    const envelope = {
+        x402Version: SUPPORTED_VERSION,
+        scheme: SUPPORTED_SCHEME,
+        network: raw.network,
+        payload: { transaction: payload.transaction, nonce: payload.nonce },
+    };
+    return {
+        envelope,
+        txCborHex: Buffer.from(txBuf).toString('hex'),
+        txHash,
+        outputs: extractOutputs(txBody),
+        inputs: extractInputs(txBody),
+        vkeyWitnessCount,
+        ttlSlot: validity.ttlSlot,
+        validityStartSlot: validity.validityStartSlot,
+        nonce,
+    };
+}

package/srv/core/errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Typed errors for x402 (Cardano-v2) verification.
+ *
+ * Codes stay in lower_snake to match the masumi-spec convention so they
+ * are interoperable with v1 callers grepping for known strings. Codes
+ * specific to v2 (UTxO-ref nonce, TTL window) are marked below.
+ *
+ * The `code` field is surfaced in the 402 response body's `error` field
+ * (parenthesised after the human message), so it doubles as the
+ * machine-readable diagnostic for clients.
+ */
+export declare class X402Error extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+export declare const Codes: Readonly<{
+    readonly MISSING_HEADER: "missing_payment_header";
+    readonly INVALID_BASE64: "invalid_base64";
+    readonly INVALID_JSON: "invalid_json";
+    readonly MISSING_FIELD: "missing_field";
+    readonly UNSUPPORTED_VERSION: "unsupported_version";
+    readonly UNSUPPORTED_SCHEME: "unsupported_scheme";
+    readonly UNSUPPORTED_METHOD: "unsupported_transfer_method";
+    readonly INVALID_CBOR: "invalid_cbor";
+    readonly INVALID_NETWORK_FORMAT: "invalid_network_format";
+    readonly INVALID_ASSET_FORMAT: "invalid_asset_format";
+    readonly INVALID_NONCE_FORMAT: "invalid_nonce_format";
+    readonly NETWORK_MISMATCH: "network_mismatch";
+    readonly WRONG_RECIPIENT: "wrong_recipient";
+    readonly INSUFFICIENT_AMOUNT: "insufficient_amount";
+    readonly WRONG_ASSET: "wrong_asset";
+    readonly REPLAY: "replay_detected";
+    readonly NONCE_NOT_REFERENCED: "nonce_not_referenced";
+    readonly EXPIRED_TTL: "expired_ttl";
+    readonly UNSIGNED_TRANSACTION: "unsigned_transaction";
+    readonly SUBMIT_FAILED: "submit_failed";
+    readonly PENDING: "invalid_transaction_state";
+    readonly BRIDGE_UNAVAILABLE: "bridge_unavailable";
+}>;
+export type X402Code = typeof Codes[keyof typeof Codes];
+//# sourceMappingURL=errors.d.ts.map

package/srv/core/errors.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Typed errors for x402 (Cardano-v2) verification.
+ *
+ * Codes stay in lower_snake to match the masumi-spec convention so they
+ * are interoperable with v1 callers grepping for known strings. Codes
+ * specific to v2 (UTxO-ref nonce, TTL window) are marked below.
+ *
+ * The `code` field is surfaced in the 402 response body's `error` field
+ * (parenthesised after the human message), so it doubles as the
+ * machine-readable diagnostic for clients.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Codes = exports.X402Error = void 0;
+class X402Error extends Error {
+    code;
+    constructor(code, message) {
+        super(message ?? code);
+        this.name = 'X402Error';
+        this.code = code;
+    }
+}
+exports.X402Error = X402Error;
+exports.Codes = Object.freeze({
+    // ---- decode ----
+    MISSING_HEADER: 'missing_payment_header',
+    INVALID_BASE64: 'invalid_base64',
+    INVALID_JSON: 'invalid_json',
+    MISSING_FIELD: 'missing_field',
+    UNSUPPORTED_VERSION: 'unsupported_version',
+    UNSUPPORTED_SCHEME: 'unsupported_scheme',
+    UNSUPPORTED_METHOD: 'unsupported_transfer_method',
+    INVALID_CBOR: 'invalid_cbor',
+    INVALID_NETWORK_FORMAT: 'invalid_network_format', // v2 requires 'cardano:<net>'
+    INVALID_ASSET_FORMAT: 'invalid_asset_format', // v2 requires '<policy>.<nameHex>'
+    INVALID_NONCE_FORMAT: 'invalid_nonce_format', // v2 requires '<txHash>#<index>'
+    // ---- validate (6 mandatory facilitator checks) ----
+    NETWORK_MISMATCH: 'network_mismatch', // check 1
+    WRONG_RECIPIENT: 'wrong_recipient', // check 2
+    INSUFFICIENT_AMOUNT: 'insufficient_amount', // check 3
+    WRONG_ASSET: 'wrong_asset', // check 4
+    REPLAY: 'replay_detected', // check 5 — UTxO already spent
+    NONCE_NOT_REFERENCED: 'nonce_not_referenced', // check 5 — UTxO not in tx inputs
+    EXPIRED_TTL: 'expired_ttl', // check 6 — validity range upper bound passed
+    // ---- supporting ----
+    UNSIGNED_TRANSACTION: 'unsigned_transaction', // sanity: no vkey witnesses
+    // ---- settle ----
+    SUBMIT_FAILED: 'submit_failed',
+    PENDING: 'invalid_transaction_state', // matches masumi spec
+    // ---- bridge / infrastructure ----
+    BRIDGE_UNAVAILABLE: 'bridge_unavailable',
+});

package/srv/core/network.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cardano-x402-v2 network identifiers.
+ *
+ * v2 uses **colon** as separator: `cardano:mainnet | cardano:preprod | cardano:preview`.
+ * v1 used hyphen (`cardano-mainnet`). We accept only the v2 form on input
+ * and refuse v1 strings so callers can't silently misroute funds across
+ * networks.
+ */
+export type Network = 'cardano:mainnet' | 'cardano:preprod' | 'cardano:preview';
+export declare function isNetwork(s: unknown): s is Network;
+/**
+ * Validate a network string and return it typed. Throws X402Error on
+ * malformed input — including v1-style hyphen variants — so the caller's
+ * 402 body carries a precise diagnostic.
+ */
+export declare function parseNetwork(s: string): Network;
+/** True iff `payload.network` (the buyer's claim) matches the server's requirement. */
+export declare function networksMatch(claimed: string, required: Network): boolean;
+//# sourceMappingURL=network.d.ts.map

package/srv/core/network.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Cardano-x402-v2 network identifiers.
+ *
+ * v2 uses **colon** as separator: `cardano:mainnet | cardano:preprod | cardano:preview`.
+ * v1 used hyphen (`cardano-mainnet`). We accept only the v2 form on input
+ * and refuse v1 strings so callers can't silently misroute funds across
+ * networks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNetwork = isNetwork;
+exports.parseNetwork = parseNetwork;
+exports.networksMatch = networksMatch;
+const errors_1 = require("./errors");
+const VALID = new Set(['cardano:mainnet', 'cardano:preprod', 'cardano:preview']);
+function isNetwork(s) {
+    return typeof s === 'string' && VALID.has(s);
+}
+/**
+ * Validate a network string and return it typed. Throws X402Error on
+ * malformed input — including v1-style hyphen variants — so the caller's
+ * 402 body carries a precise diagnostic.
+ */
+function parseNetwork(s) {
+    if (typeof s !== 'string' || s.length === 0) {
+        throw new errors_1.X402Error(errors_1.Codes.INVALID_NETWORK_FORMAT, 'network must be a non-empty string');
+    }
+    if (s.includes('-') && !s.includes(':')) {
+        throw new errors_1.X402Error(errors_1.Codes.INVALID_NETWORK_FORMAT, `network '${s}' uses v1 hyphen format; v2 requires colon: 'cardano:mainnet|preprod|preview'`);
+    }
+    if (!isNetwork(s)) {
+        throw new errors_1.X402Error(errors_1.Codes.INVALID_NETWORK_FORMAT, `network '${s}' is not one of cardano:mainnet | cardano:preprod | cardano:preview`);
+    }
+    return s;
+}
+/** True iff `payload.network` (the buyer's claim) matches the server's requirement. */
+function networksMatch(claimed, required) {
+    return claimed === required;
+}

package/srv/core/requirements.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Build the canonical Cardano-x402-v2 PaymentRequirements body.
+ *
+ * Asset-agnostic by design — the consumer passes a v2 asset string
+ * (`<policy>.<nameHex>` or `'lovelace'`), a payTo bech32, a network, and
+ * a resource descriptor. There is NO USDM default and no decimals
+ * assumption — both belong to the consumer's product config.
+ *
+ * The v2 shape diverges from v1 in five places (see `docs/spec-v2-summary.md`
+ * once written):
+ *   1. `x402Version: 2`               (was 1)
+ *   2. `accepts[].amount`             (was `maxAmountRequired`)
+ *   3. `accepts[].asset` is a single  (was split: `asset` + `extra.assetNameHex`)
+ *      string `<policy>.<nameHex>` or `'lovelace'`
+ *   4. `accepts[].resource` is an     (was a string)
+ *      object `{ url, description, mimeType }`
+ *   5. `accepts[].assetTransferMethod`(new field)
+ */
+import { type Network } from './network';
+import type { PaymentRequirementEntry, PaymentRequirementsBody, ResourceDescriptor, AssetTransferMethod } from './types';
+export interface BuildPaymentRequirementsArgs {
+    /** Asset amount in raw units (BigInt-safe). */
+    amount: string | number | bigint;
+    asset: string;
+    payTo: string;
+    network: Network | string;
+    resource: ResourceDescriptor | string;
+    description?: string;
+    mimeType?: string;
+    outputSchema?: unknown;
+    assetTransferMethod?: AssetTransferMethod;
+    maxTimeoutSeconds?: number;
+    /** Free-form extras (decimals, fingerprint, UI hints). */
+    extra?: Record<string, unknown>;
+    /**
+     * If true, prepend the standard 'PAYMENT-SIGNATURE header is required'
+     * error string. Used for the missing-header path; omit for downstream
+     * rejection bodies where the caller sets a more specific `error`.
+     */
+    withMissingHeaderError?: boolean;
+}
+/**
+ * Construct a single `accepts[]` entry. Most callers want
+ * `buildPaymentRequirements()` which wraps this in the 402 envelope —
+ * use `buildEntry()` directly when composing multi-asset accept lists.
+ */
+export declare function buildEntry(args: BuildPaymentRequirementsArgs): PaymentRequirementEntry;
+export declare function buildPaymentRequirements(args: BuildPaymentRequirementsArgs): PaymentRequirementsBody;
+/** Pick the first `accepts[]` entry — what the validator inspects. */
+export declare function flatRequirements(body: PaymentRequirementsBody): PaymentRequirementEntry;
+//# sourceMappingURL=requirements.d.ts.map

package/srv/core/requirements.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Build the canonical Cardano-x402-v2 PaymentRequirements body.
+ *
+ * Asset-agnostic by design — the consumer passes a v2 asset string
+ * (`<policy>.<nameHex>` or `'lovelace'`), a payTo bech32, a network, and
+ * a resource descriptor. There is NO USDM default and no decimals
+ * assumption — both belong to the consumer's product config.
+ *
+ * The v2 shape diverges from v1 in five places (see `docs/spec-v2-summary.md`
+ * once written):
+ *   1. `x402Version: 2`               (was 1)
+ *   2. `accepts[].amount`             (was `maxAmountRequired`)
+ *   3. `accepts[].asset` is a single  (was split: `asset` + `extra.assetNameHex`)
+ *      string `<policy>.<nameHex>` or `'lovelace'`
+ *   4. `accepts[].resource` is an     (was a string)
+ *      object `{ url, description, mimeType }`
+ *   5. `accepts[].assetTransferMethod`(new field)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEntry = buildEntry;
+exports.buildPaymentRequirements = buildPaymentRequirements;
+exports.flatRequirements = flatRequirements;
+const network_1 = require("./network");
+const asset_1 = require("./asset");
+function normalizeResource(resource, description, mimeType, outputSchema) {
+    if (typeof resource === 'string') {
+        return {
+            url: resource,
+            description: description ?? '',
+            mimeType: mimeType ?? 'application/json',
+            ...(outputSchema !== undefined ? { outputSchema } : {}),
+        };
+    }
+    // Object form: caller's fields win, but allow per-call overrides.
+    return {
+        url: resource.url,
+        description: description ?? resource.description ?? '',
+        mimeType: mimeType ?? resource.mimeType ?? 'application/json',
+        ...(outputSchema !== undefined
+            ? { outputSchema }
+            : (resource.outputSchema !== undefined ? { outputSchema: resource.outputSchema } : {})),
+    };
+}
+/**
+ * Construct a single `accepts[]` entry. Most callers want
+ * `buildPaymentRequirements()` which wraps this in the 402 envelope —
+ * use `buildEntry()` directly when composing multi-asset accept lists.
+ */
+function buildEntry(args) {
+    if (!args.payTo)
+        throw new Error('buildEntry: payTo is required');
+    const network = (0, network_1.parseNetwork)(args.network);
+    const parsedAsset = (0, asset_1.parseAsset)(args.asset);
+    const amount = String(args.amount);
+    if (!/^\d+$/.test(amount) || amount === '0') {
+        throw new Error(`buildEntry: amount must be a positive integer (got '${amount}')`);
+    }
+    const resource = normalizeResource(args.resource, args.description, args.mimeType, args.outputSchema);
+    return {
+        scheme: 'exact',
+        network,
+        asset: parsedAsset.raw,
+        amount,
+        payTo: args.payTo,
+        resource,
+        assetTransferMethod: args.assetTransferMethod ?? 'default',
+        maxTimeoutSeconds: args.maxTimeoutSeconds ?? 600,
+        ...(args.extra ? { extra: args.extra } : {}),
+    };
+}
+function buildPaymentRequirements(args) {
+    const accepts = [buildEntry(args)];
+    return {
+        x402Version: 2,
+        ...(args.withMissingHeaderError ? { error: 'PAYMENT-SIGNATURE header is required' } : {}),
+        accepts,
+    };
+}
+/** Pick the first `accepts[]` entry — what the validator inspects. */
+function flatRequirements(body) {
+    if (!body.accepts || body.accepts.length === 0) {
+        throw new Error('flatRequirements: PaymentRequirementsBody.accepts is empty');
+    }
+    return body.accepts[0];
+}