@keelcodes/settlement 0.1.0

package/dist/wire.d.ts

@@ -0,0 +1,31 @@
+/** Encodes UTF-8 text as base64 (standard, padded) or base64url (unpadded). */
+export declare function base64Encode(input: string, options?: {
+    urlSafe?: boolean;
+}): string;
+/** Decodes base64 or base64url (padding optional) back to UTF-8 text. */
+export declare function base64Decode(input: string): string;
+/** Encodes a value as base64(url) JSON — how both protocols carry a payload. */
+export declare function encodeJsonPayload(value: unknown, options?: {
+    urlSafe?: boolean;
+}): string;
+/** Decodes base64(url) JSON, reporting a `malformed-payload` error on bad input. */
+export declare function decodeJsonPayload<T>(input: string): T;
+export interface AuthHeader {
+    scheme: string;
+    params: Record<string, string>;
+}
+/**
+ * Reads just the auth scheme. Useful for rejecting a foreign scheme before
+ * parsing params — `Bearer abc` is not an auth-param header at all, and the
+ * error worth reporting is "wrong scheme", not "malformed parameters".
+ */
+export declare function authScheme(headerValue: string): string;
+/**
+ * Parses an HTTP auth header (`Scheme a="1", b=2`) as defined by RFC 9110
+ * §11.2. Handles quoted-string values containing commas and escapes — which is
+ * exactly what a base64 payload in a challenge param looks like.
+ */
+export declare function parseAuthHeader(headerValue: string): AuthHeader;
+/** Serialises an auth header, quoting and escaping every value. */
+export declare function formatAuthHeader(header: AuthHeader): string;
+//# sourceMappingURL=wire.d.ts.map

package/dist/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../src/wire.ts"],"names":[],"mappings":"AAuFA,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAgBvF;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAkBlD;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAE7F;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAOrD;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAKD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,CAkE/D;AAED,mEAAmE;AACnE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAO3D"}

package/dist/wire.js

@@ -0,0 +1,224 @@
+import { SettlementError } from './types.js';
+/**
+ * Base64 / base64url and UTF-8 codecs, plus the HTTP auth-param grammar both
+ * payment protocols lean on.
+ *
+ * Written against plain ES2022 rather than `Buffer`/`atob` on purpose: the
+ * settlement core carries no runtime dependency and must run in Node, browsers
+ * and edge workers alike.
+ */
+const STD_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const DECODE_TABLE = (() => {
+    const table = new Map();
+    for (let index = 0; index < 64; index += 1) {
+        table.set(STD_ALPHABET.charAt(index), index);
+        table.set(URL_ALPHABET.charAt(index), index);
+    }
+    return table;
+})();
+function utf8Encode(input) {
+    const bytes = [];
+    for (const char of input) {
+        const codePoint = char.codePointAt(0) ?? 0;
+        if (codePoint < 0x80) {
+            bytes.push(codePoint);
+        }
+        else if (codePoint < 0x800) {
+            bytes.push(0xc0 | (codePoint >> 6), 0x80 | (codePoint & 0x3f));
+        }
+        else if (codePoint < 0x10000) {
+            bytes.push(0xe0 | (codePoint >> 12), 0x80 | ((codePoint >> 6) & 0x3f), 0x80 | (codePoint & 0x3f));
+        }
+        else {
+            bytes.push(0xf0 | (codePoint >> 18), 0x80 | ((codePoint >> 12) & 0x3f), 0x80 | ((codePoint >> 6) & 0x3f), 0x80 | (codePoint & 0x3f));
+        }
+    }
+    return bytes;
+}
+function utf8Decode(bytes) {
+    let out = '';
+    let index = 0;
+    while (index < bytes.length) {
+        const lead = bytes[index];
+        let codePoint;
+        let width;
+        if (lead < 0x80) {
+            codePoint = lead;
+            width = 1;
+        }
+        else if ((lead & 0xe0) === 0xc0) {
+            codePoint = lead & 0x1f;
+            width = 2;
+        }
+        else if ((lead & 0xf0) === 0xe0) {
+            codePoint = lead & 0x0f;
+            width = 3;
+        }
+        else if ((lead & 0xf8) === 0xf0) {
+            codePoint = lead & 0x07;
+            width = 4;
+        }
+        else {
+            throw new SettlementError('malformed-payload', `invalid UTF-8 lead byte 0x${lead.toString(16)}`);
+        }
+        if (index + width > bytes.length) {
+            throw new SettlementError('malformed-payload', 'truncated UTF-8 sequence');
+        }
+        for (let offset = 1; offset < width; offset += 1) {
+            const continuation = bytes[index + offset];
+            if ((continuation & 0xc0) !== 0x80) {
+                throw new SettlementError('malformed-payload', 'invalid UTF-8 continuation byte');
+            }
+            codePoint = (codePoint << 6) | (continuation & 0x3f);
+        }
+        out += String.fromCodePoint(codePoint);
+        index += width;
+    }
+    return out;
+}
+/** Encodes UTF-8 text as base64 (standard, padded) or base64url (unpadded). */
+export function base64Encode(input, options = {}) {
+    const urlSafe = options.urlSafe ?? false;
+    const alphabet = urlSafe ? URL_ALPHABET : STD_ALPHABET;
+    const bytes = utf8Encode(input);
+    let out = '';
+    for (let index = 0; index < bytes.length; index += 3) {
+        const b0 = bytes[index];
+        const b1 = bytes[index + 1];
+        const b2 = bytes[index + 2];
+        out += alphabet.charAt(b0 >> 2);
+        out += alphabet.charAt(((b0 & 0x03) << 4) | ((b1 ?? 0) >> 4));
+        out += b1 === undefined ? (urlSafe ? '' : '=') : alphabet.charAt(((b1 & 0x0f) << 2) | ((b2 ?? 0) >> 6));
+        out += b2 === undefined ? (urlSafe ? '' : '=') : alphabet.charAt(b2 & 0x3f);
+    }
+    return out;
+}
+/** Decodes base64 or base64url (padding optional) back to UTF-8 text. */
+export function base64Decode(input) {
+    const cleaned = input.replace(/\s+/g, '').replace(/=+$/, '');
+    const bytes = [];
+    let buffer = 0;
+    let bits = 0;
+    for (const char of cleaned) {
+        const value = DECODE_TABLE.get(char);
+        if (value === undefined) {
+            throw new SettlementError('malformed-payload', `invalid base64 character ${JSON.stringify(char)}`);
+        }
+        buffer = (buffer << 6) | value;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes.push((buffer >> bits) & 0xff);
+        }
+    }
+    return utf8Decode(bytes);
+}
+/** Encodes a value as base64(url) JSON — how both protocols carry a payload. */
+export function encodeJsonPayload(value, options = {}) {
+    return base64Encode(JSON.stringify(value), options);
+}
+/** Decodes base64(url) JSON, reporting a `malformed-payload` error on bad input. */
+export function decodeJsonPayload(input) {
+    const text = base64Decode(input);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new SettlementError('malformed-payload', `payload is not valid JSON: ${text.slice(0, 120)}`);
+    }
+}
+const WHITESPACE = /\s/;
+const SEPARATOR = /[\s,]/;
+/**
+ * Reads just the auth scheme. Useful for rejecting a foreign scheme before
+ * parsing params — `Bearer abc` is not an auth-param header at all, and the
+ * error worth reporting is "wrong scheme", not "malformed parameters".
+ */
+export function authScheme(headerValue) {
+    return /^([^\s]+)/.exec(headerValue.trim())?.[1] ?? '';
+}
+/**
+ * Parses an HTTP auth header (`Scheme a="1", b=2`) as defined by RFC 9110
+ * §11.2. Handles quoted-string values containing commas and escapes — which is
+ * exactly what a base64 payload in a challenge param looks like.
+ */
+export function parseAuthHeader(headerValue) {
+    const trimmed = headerValue.trim();
+    if (trimmed === '') {
+        throw new SettlementError('malformed-payload', 'empty auth header');
+    }
+    let index = 0;
+    while (index < trimmed.length && !WHITESPACE.test(trimmed.charAt(index)))
+        index += 1;
+    const scheme = trimmed.slice(0, index);
+    const params = {};
+    while (index < trimmed.length) {
+        while (index < trimmed.length && (SEPARATOR.test(trimmed.charAt(index))))
+            index += 1;
+        if (index >= trimmed.length)
+            break;
+        const nameStart = index;
+        while (index < trimmed.length && trimmed.charAt(index) !== '=' && !SEPARATOR.test(trimmed.charAt(index))) {
+            index += 1;
+        }
+        const name = trimmed.slice(nameStart, index);
+        if (name === '') {
+            throw new SettlementError('malformed-payload', `empty auth-param name in ${JSON.stringify(headerValue)}`);
+        }
+        while (index < trimmed.length && WHITESPACE.test(trimmed.charAt(index)))
+            index += 1;
+        if (trimmed.charAt(index) !== '=') {
+            throw new SettlementError('malformed-payload', `auth-param ${name} has no value`);
+        }
+        index += 1;
+        while (index < trimmed.length && WHITESPACE.test(trimmed.charAt(index)))
+            index += 1;
+        if (trimmed.charAt(index) === '"') {
+            index += 1;
+            let value = '';
+            let closed = false;
+            while (index < trimmed.length) {
+                const char = trimmed.charAt(index);
+                if (char === '\\') {
+                    const escaped = trimmed.charAt(index + 1);
+                    if (escaped === '') {
+                        throw new SettlementError('malformed-payload', 'dangling escape in quoted auth-param');
+                    }
+                    value += escaped;
+                    index += 2;
+                    continue;
+                }
+                if (char === '"') {
+                    closed = true;
+                    index += 1;
+                    break;
+                }
+                value += char;
+                index += 1;
+            }
+            if (!closed) {
+                throw new SettlementError('malformed-payload', `unterminated quoted value for auth-param ${name}`);
+            }
+            params[name] = value;
+        }
+        else {
+            const valueStart = index;
+            while (index < trimmed.length && !SEPARATOR.test(trimmed.charAt(index)))
+                index += 1;
+            params[name] = trimmed.slice(valueStart, index);
+        }
+    }
+    return { scheme, params };
+}
+/** Serialises an auth header, quoting and escaping every value. */
+export function formatAuthHeader(header) {
+    const entries = Object.entries(header.params);
+    if (entries.length === 0)
+        return header.scheme;
+    const rendered = entries
+        .map(([name, value]) => `${name}="${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`)
+        .join(', ');
+    return `${header.scheme} ${rendered}`;
+}
+//# sourceMappingURL=wire.js.map

package/dist/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../src/wire.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;GAOG;AAEH,MAAM,YAAY,GAAG,kEAAkE,CAAC;AACxF,MAAM,YAAY,GAAG,kEAAkE,CAAC;AAExF,MAAM,YAAY,GAAgC,CAAC,GAAG,EAAE;IACtD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,EAAE,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC3C,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;QAC7C,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC,CAAC,EAAE,CAAC;AAEL,SAAS,UAAU,CAAC,KAAa;IAC/B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,SAAS,GAAG,IAAI,EAAE,CAAC;YACrB,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACxB,CAAC;aAAM,IAAI,SAAS,GAAG,KAAK,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,SAAS,IAAI,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC;QACjE,CAAC;aAAM,IAAI,SAAS,GAAG,OAAO,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CACR,IAAI,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,EACxB,IAAI,GAAG,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,EAChC,IAAI,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,CAC1B,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CACR,IAAI,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,EACxB,IAAI,GAAG,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EACjC,IAAI,GAAG,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,EAChC,IAAI,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,CAC1B,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,UAAU,CAAC,KAAwB;IAC1C,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAW,CAAC;QACpC,IAAI,SAAiB,CAAC;QACtB,IAAI,KAAa,CAAC;QAClB,IAAI,IAAI,GAAG,IAAI,EAAE,CAAC;YAChB,SAAS,GAAG,IAAI,CAAC;YACjB,KAAK,GAAG,CAAC,CAAC;QACZ,CAAC;aAAM,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAClC,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC;YACxB,KAAK,GAAG,CAAC,CAAC;QACZ,CAAC;aAAM,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAClC,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC;YACxB,KAAK,GAAG,CAAC,CAAC;QACZ,CAAC;aAAM,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAClC,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC;YACxB,KAAK,GAAG,CAAC,CAAC;QACZ,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,eAAe,CAAC,mBAAmB,EAAE,6BAA6B,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACnG,CAAC;QACD,IAAI,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YACjC,MAAM,IAAI,eAAe,CAAC,mBAAmB,EAAE,0BAA0B,CAAC,CAAC;QAC7E,CAAC;QACD,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,KAAK,EAAE,MAAM,IAAI,CAAC,EAAE,CAAC;YACjD,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,GAAG,MAAM,CAAW,CAAC;YACrD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;gBACnC,MAAM,IAAI,eAAe,CAAC,mBAAmB,EAAE,iCAAiC,CAAC,CAAC;YACpF,CAAC;YACD,SAAS,GAAG,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;QACvD,CAAC;QACD,GAAG,IAAI,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QACvC,KAAK,IAAI,KAAK,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,UAAiC,EAAE;IAC7E,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC;IACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC;IACvD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAEhC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAW,CAAC;QAClC,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAC5B,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAC5B,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;QAChC,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC9D,GAAG,IAAI,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACxG,GAAG,IAAI,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,eAAe,CAAC,mBAAmB,EAAE,4BAA4B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrG,CAAC;QACD,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC;QAC/B,IAAI,IAAI,CAAC,CAAC;QACV,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;YACd,IAAI,IAAI,CAAC,CAAC;YACV,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAAC,KAAc,EAAE,UAAiC,EAAE;IACnF,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,iBAAiB,CAAI,KAAa;IAChD,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,eAAe,CAAC,mBAAmB,EAAE,8BAA8B,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IACrG,CAAC;AACH,CAAC;AAOD,MAAM,UAAU,GAAG,IAAI,CAAC;AACxB,MAAM,SAAS,GAAG,OAAO,CAAC;AAE1B;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,WAAmB;IAC5C,OAAO,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,WAAmB;IACjD,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,MAAM,IAAI,eAAe,CAAC,mBAAmB,EAAE,mBAAmB,CAAC,CAAC;IACtE,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAAE,KAAK,IAAI,CAAC,CAAC;IACrF,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACvC,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,OAAO,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QAC9B,OAAO,KAAK,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAAE,KAAK,IAAI,CAAC,CAAC;QACrF,IAAI,KAAK,IAAI,OAAO,CAAC,MAAM;YAAE,MAAM;QAEnC,MAAM,SAAS,GAAG,KAAK,CAAC;QACxB,OAAO,KAAK,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YACzG,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;QACD,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QAC7C,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YAChB,MAAM,IAAI,eAAe,CAAC,mBAAmB,EAAE,4BAA4B,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAC5G,CAAC;QAED,OAAO,KAAK,GAAG,OAAO,CAAC,MAAM,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAAE,KAAK,IAAI,CAAC,CAAC;QACpF,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC;YAClC,MAAM,IAAI,eAAe,CAAC,mBAAmB,EAAE,cAAc,IAAI,eAAe,CAAC,CAAC;QACpF,CAAC;QACD,KAAK,IAAI,CAAC,CAAC;QACX,OAAO,KAAK,GAAG,OAAO,CAAC,MAAM,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAAE,KAAK,IAAI,CAAC,CAAC;QAEpF,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC;YAClC,KAAK,IAAI,CAAC,CAAC;YACX,IAAI,KAAK,GAAG,EAAE,CAAC;YACf,IAAI,MAAM,GAAG,KAAK,CAAC;YACnB,OAAO,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;gBAC9B,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACnC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;oBAClB,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;oBAC1C,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;wBACnB,MAAM,IAAI,eAAe,CAAC,mBAAmB,EAAE,sCAAsC,CAAC,CAAC;oBACzF,CAAC;oBACD,KAAK,IAAI,OAAO,CAAC;oBACjB,KAAK,IAAI,CAAC,CAAC;oBACX,SAAS;gBACX,CAAC;gBACD,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;oBACjB,MAAM,GAAG,IAAI,CAAC;oBACd,KAAK,IAAI,CAAC,CAAC;oBACX,MAAM;gBACR,CAAC;gBACD,KAAK,IAAI,IAAI,CAAC;gBACd,KAAK,IAAI,CAAC,CAAC;YACb,CAAC;YACD,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,eAAe,CAAC,mBAAmB,EAAE,4CAA4C,IAAI,EAAE,CAAC,CAAC;YACrG,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,MAAM,UAAU,GAAG,KAAK,CAAC;YACzB,OAAO,KAAK,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAAE,KAAK,IAAI,CAAC,CAAC;YACpF,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,MAAkB;IACjD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC;IAC/C,MAAM,QAAQ,GAAG,OAAO;SACrB,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC;SACxF,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,GAAG,MAAM,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;AACxC,CAAC"}

package/dist/x402.d.ts

@@ -0,0 +1,93 @@
+import { type Caip2, type PaymentIntent } from './types.js';
+/**
+ * x402 v2 (https://docs.x402.org) — the HTTP 402 payment flow.
+ *
+ * Keel models the part of x402 the *core* spec fixes: the three headers, the
+ * `PaymentRequired` requirements object, requirement selection, and the
+ * anti-tamper check against a {@link PaymentIntent}. The scheme-specific
+ * `PaymentPayload` a client puts in `PAYMENT-SIGNATURE` (EIP-3009 authorization,
+ * permit, …) is opaque here and produced by the caller's scheme module — this
+ * package does not invent it.
+ */
+export declare const X402_VERSION = 2;
+/** HTTP header names used by x402 v2 (HTTP header lookup is case-insensitive). */
+export declare const X402_HEADERS: {
+    /** Server → client: base64 `PaymentRequired`. */
+    readonly required: "PAYMENT-REQUIRED";
+    /** Client → server: base64 `PaymentPayload` (scheme-specific). */
+    readonly signature: "PAYMENT-SIGNATURE";
+    /** Server → client: base64 `SettlementResponse`. */
+    readonly response: "PAYMENT-RESPONSE";
+};
+export interface X402Resource {
+    url: string;
+    description?: string;
+    mimeType?: string;
+}
+export interface X402Requirements {
+    /** e.g. `exact`. */
+    scheme: string;
+    network: Caip2;
+    /** Atomic units, as a decimal string. */
+    amount: string;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: Record<string, unknown>;
+}
+export interface X402PaymentRequired {
+    x402Version: number;
+    error?: string;
+    resource: X402Resource;
+    accepts: X402Requirements[];
+    extensions?: Record<string, unknown>;
+}
+export interface X402SettlementResponse {
+    success: boolean;
+    transaction?: string;
+    network?: string;
+    payer?: string;
+    errorReason?: string;
+    extensions?: Record<string, unknown>;
+}
+/** Parses a `PAYMENT-REQUIRED` header value. */
+export declare function parsePaymentRequired(headerValue: string): X402PaymentRequired;
+/** Serialises a `PaymentRequired` object for the `PAYMENT-REQUIRED` header. */
+export declare function formatPaymentRequired(value: X402PaymentRequired): string;
+/** Parses a `PAYMENT-RESPONSE` header value. */
+export declare function parseSettlementResponse(headerValue: string): X402SettlementResponse;
+/** Serialises a settlement response for the `PAYMENT-RESPONSE` header. */
+export declare function formatSettlementResponse(value: X402SettlementResponse): string;
+/** Wraps a scheme-specific payment payload for the `PAYMENT-SIGNATURE` header. */
+export declare function encodePaymentSignature(payload: unknown): string;
+/** Unwraps a `PAYMENT-SIGNATURE` header value into the scheme payload. */
+export declare function parsePaymentSignature(headerValue: string): unknown;
+export interface RequirementFilter {
+    scheme?: string;
+    network?: string;
+    asset?: string;
+    payTo?: string;
+    /** Reject anything more expensive than this (atomic units). */
+    maxAmount?: bigint;
+}
+/**
+ * Picks the cheapest requirement the client can satisfy. Throws rather than
+ * returning a "best effort" pick: silently paying a requirement you did not
+ * choose is how an agent overpays.
+ */
+export declare function selectRequirement(accepts: readonly X402Requirements[], filter?: RequirementFilter): X402Requirements;
+/**
+ * The anti-tamper gate: a server may return whatever `payTo`/`amount` it likes,
+ * so what it asks for is only safe to act on once it matches the intent.
+ */
+export declare function verifyRequirement(requirement: X402Requirements, intent: PaymentIntent): void;
+export interface IntentFromRequirementArgs {
+    id: string;
+    payer: string;
+    reference?: string;
+    /** Anchors `expiresAt` from `maxTimeoutSeconds`. */
+    now?: Date;
+}
+/** Builds the client-side intent from the requirement the client agreed to. */
+export declare function intentFromRequirement(requirement: X402Requirements, args: IntentFromRequirementArgs): PaymentIntent;
+//# sourceMappingURL=x402.d.ts.map

package/dist/x402.d.ts.map

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

package/dist/x402.js

@@ -0,0 +1,196 @@
+import { SettlementError, assertCaip2 } from './types.js';
+import { decodeJsonPayload, encodeJsonPayload } from './wire.js';
+/**
+ * x402 v2 (https://docs.x402.org) — the HTTP 402 payment flow.
+ *
+ * Keel models the part of x402 the *core* spec fixes: the three headers, the
+ * `PaymentRequired` requirements object, requirement selection, and the
+ * anti-tamper check against a {@link PaymentIntent}. The scheme-specific
+ * `PaymentPayload` a client puts in `PAYMENT-SIGNATURE` (EIP-3009 authorization,
+ * permit, …) is opaque here and produced by the caller's scheme module — this
+ * package does not invent it.
+ */
+export const X402_VERSION = 2;
+/** HTTP header names used by x402 v2 (HTTP header lookup is case-insensitive). */
+export const X402_HEADERS = {
+    /** Server → client: base64 `PaymentRequired`. */
+    required: 'PAYMENT-REQUIRED',
+    /** Client → server: base64 `PaymentPayload` (scheme-specific). */
+    signature: 'PAYMENT-SIGNATURE',
+    /** Server → client: base64 `SettlementResponse`. */
+    response: 'PAYMENT-RESPONSE',
+};
+function requireString(value, field) {
+    if (typeof value !== 'string' || value === '') {
+        throw new SettlementError('missing-field', `${field} must be a non-empty string`);
+    }
+    return value;
+}
+function assertRequirement(value, index) {
+    if (typeof value !== 'object' || value === null) {
+        throw new SettlementError('malformed-payload', `accepts[${index}] is not an object`);
+    }
+    const raw = value;
+    const maxTimeoutSeconds = raw['maxTimeoutSeconds'];
+    if (typeof maxTimeoutSeconds !== 'number' || !Number.isFinite(maxTimeoutSeconds)) {
+        throw new SettlementError('missing-field', `accepts[${index}].maxTimeoutSeconds must be a number`);
+    }
+    const amount = requireString(raw['amount'], `accepts[${index}].amount`);
+    if (!/^\d+$/.test(amount)) {
+        throw new SettlementError('malformed-payload', `accepts[${index}].amount must be atomic units, got ${amount}`);
+    }
+    const requirement = {
+        scheme: requireString(raw['scheme'], `accepts[${index}].scheme`),
+        network: assertCaip2(raw['network'], `accepts[${index}].network`),
+        amount,
+        asset: requireString(raw['asset'], `accepts[${index}].asset`),
+        payTo: requireString(raw['payTo'], `accepts[${index}].payTo`),
+        maxTimeoutSeconds,
+    };
+    const extra = raw['extra'];
+    if (extra !== undefined) {
+        if (typeof extra !== 'object' || extra === null) {
+            throw new SettlementError('malformed-payload', `accepts[${index}].extra must be an object`);
+        }
+        requirement.extra = extra;
+    }
+    return requirement;
+}
+/** Parses a `PAYMENT-REQUIRED` header value. */
+export function parsePaymentRequired(headerValue) {
+    const raw = decodeJsonPayload(headerValue);
+    if (raw['x402Version'] !== X402_VERSION) {
+        throw new SettlementError('unsupported-version', `expected x402Version ${X402_VERSION}, got ${JSON.stringify(raw['x402Version'])}`);
+    }
+    const resource = raw['resource'];
+    if (typeof resource !== 'object' || resource === null) {
+        throw new SettlementError('missing-field', 'resource is required');
+    }
+    const resourceUrl = requireString(resource['url'], 'resource.url');
+    const accepts = raw['accepts'];
+    if (!Array.isArray(accepts) || accepts.length === 0) {
+        throw new SettlementError('missing-field', 'accepts must be a non-empty array');
+    }
+    const parsed = {
+        x402Version: X402_VERSION,
+        resource: { url: resourceUrl },
+        accepts: accepts.map((entry, index) => assertRequirement(entry, index)),
+    };
+    const rawResource = resource;
+    if (typeof rawResource['description'] === 'string')
+        parsed.resource.description = rawResource['description'];
+    if (typeof rawResource['mimeType'] === 'string')
+        parsed.resource.mimeType = rawResource['mimeType'];
+    if (typeof raw['error'] === 'string')
+        parsed.error = raw['error'];
+    if (typeof raw['extensions'] === 'object' && raw['extensions'] !== null) {
+        parsed.extensions = raw['extensions'];
+    }
+    return parsed;
+}
+/** Serialises a `PaymentRequired` object for the `PAYMENT-REQUIRED` header. */
+export function formatPaymentRequired(value) {
+    return encodeJsonPayload(value);
+}
+/** Parses a `PAYMENT-RESPONSE` header value. */
+export function parseSettlementResponse(headerValue) {
+    const raw = decodeJsonPayload(headerValue);
+    if (typeof raw['success'] !== 'boolean') {
+        throw new SettlementError('missing-field', 'SettlementResponse.success must be a boolean');
+    }
+    const response = { success: raw['success'] };
+    for (const field of ['transaction', 'network', 'payer', 'errorReason']) {
+        const fieldValue = raw[field];
+        if (fieldValue !== undefined) {
+            if (typeof fieldValue !== 'string') {
+                throw new SettlementError('malformed-payload', `SettlementResponse.${field} must be a string`);
+            }
+            response[field] = fieldValue;
+        }
+    }
+    if (typeof raw['extensions'] === 'object' && raw['extensions'] !== null) {
+        response.extensions = raw['extensions'];
+    }
+    return response;
+}
+/** Serialises a settlement response for the `PAYMENT-RESPONSE` header. */
+export function formatSettlementResponse(value) {
+    return encodeJsonPayload(value);
+}
+/** Wraps a scheme-specific payment payload for the `PAYMENT-SIGNATURE` header. */
+export function encodePaymentSignature(payload) {
+    return encodeJsonPayload(payload);
+}
+/** Unwraps a `PAYMENT-SIGNATURE` header value into the scheme payload. */
+export function parsePaymentSignature(headerValue) {
+    return decodeJsonPayload(headerValue);
+}
+function matches(requirement, filter) {
+    if (filter.scheme !== undefined && requirement.scheme !== filter.scheme)
+        return false;
+    if (filter.network !== undefined && requirement.network !== filter.network)
+        return false;
+    if (filter.asset !== undefined &&
+        requirement.asset.toLowerCase() !== filter.asset.toLowerCase()) {
+        return false;
+    }
+    if (filter.payTo !== undefined && requirement.payTo.toLowerCase() !== filter.payTo.toLowerCase()) {
+        return false;
+    }
+    if (filter.maxAmount !== undefined && BigInt(requirement.amount) > filter.maxAmount)
+        return false;
+    return true;
+}
+/**
+ * Picks the cheapest requirement the client can satisfy. Throws rather than
+ * returning a "best effort" pick: silently paying a requirement you did not
+ * choose is how an agent overpays.
+ */
+export function selectRequirement(accepts, filter = {}) {
+    const eligible = accepts.filter((requirement) => matches(requirement, filter));
+    if (eligible.length === 0) {
+        throw new SettlementError('no-acceptable-requirement', `no offered requirement satisfies ${JSON.stringify(filter, (_key, value) => typeof value === 'bigint' ? value.toString() : value)}`);
+    }
+    return eligible.reduce((cheapest, candidate) => BigInt(candidate.amount) < BigInt(cheapest.amount) ? candidate : cheapest);
+}
+/**
+ * The anti-tamper gate: a server may return whatever `payTo`/`amount` it likes,
+ * so what it asks for is only safe to act on once it matches the intent.
+ */
+export function verifyRequirement(requirement, intent) {
+    const mismatches = [];
+    if (requirement.network !== intent.network) {
+        mismatches.push(`network ${requirement.network} != ${intent.network}`);
+    }
+    if (requirement.asset.toLowerCase() !== intent.asset.toLowerCase()) {
+        mismatches.push(`asset ${requirement.asset} != ${intent.asset}`);
+    }
+    if (requirement.payTo.toLowerCase() !== intent.payee.toLowerCase()) {
+        mismatches.push(`payTo ${requirement.payTo} != ${intent.payee}`);
+    }
+    if (BigInt(requirement.amount) !== intent.amount) {
+        mismatches.push(`amount ${requirement.amount} != ${intent.amount.toString()}`);
+    }
+    if (mismatches.length > 0) {
+        throw new SettlementError('requirement-mismatch', `offered requirement does not match intent ${intent.id}: ${mismatches.join('; ')}`);
+    }
+}
+/** Builds the client-side intent from the requirement the client agreed to. */
+export function intentFromRequirement(requirement, args) {
+    const intent = {
+        id: args.id,
+        protocol: 'x402',
+        network: requirement.network,
+        asset: requirement.asset,
+        amount: BigInt(requirement.amount),
+        payer: args.payer,
+        payee: requirement.payTo,
+    };
+    if (args.reference !== undefined)
+        intent.reference = args.reference;
+    if (args.now !== undefined) {
+        intent.expiresAt = new Date(args.now.getTime() + requirement.maxTimeoutSeconds * 1000).toISOString();
+    }
+    return intent;
+}
+//# sourceMappingURL=x402.js.map

package/dist/x402.js.map

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

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@keelcodes/settlement",
+  "version": "0.1.0",
+  "description": "Settlement core for agent payments: x402 v2 and MPP (HTTP Payment auth scheme) codecs, receipts and a reconciliation ledger. No billing.",
+  "license": "Apache-2.0",
+  "homepage": "https://keel.codes",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keelcodes/keel.git",
+    "directory": "packages/settlement"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "viem": "^2.21.0",
+    "vitest": "^2.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "x402",
+    "mpp",
+    "machine-payments",
+    "http-402",
+    "settlement",
+    "agent",
+    "payments",
+    "receipts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  }
+}