bolt12-utils 0.1.0

package/dist/offer.js

@@ -0,0 +1,288 @@
+"use strict";
+/**
+ * BOLT12 Offer validation.
+ *
+ * An offer is a TLV stream encoded with the "lno" prefix.
+ * This module validates the semantic rules for offers as specified
+ * in BOLT 12.
+ *
+ * Offer TLV types (from the spec):
+ *   2  - offer_chains          (array of 32-byte chain_hashes)
+ *   4  - offer_metadata        (arbitrary bytes)
+ *   6  - offer_currency        (UTF-8 ISO 4217 code)
+ *   8  - offer_amount          (tu64 msat or currency units)
+ *   10 - offer_description     (UTF-8 string)
+ *   12 - offer_features        (feature bits)
+ *   14 - offer_absolute_expiry (tu64 seconds since epoch)
+ *   16 - offer_paths           (blinded_path array)
+ *   18 - offer_issuer          (UTF-8 string)
+ *   20 - offer_quantity_max    (tu64)
+ *   22 - offer_issuer_id       (point, 33 bytes)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OFFER_ISSUER_ID = exports.OFFER_QUANTITY_MAX = exports.OFFER_ISSUER = exports.OFFER_PATHS = exports.OFFER_ABSOLUTE_EXPIRY = exports.OFFER_FEATURES = exports.OFFER_DESCRIPTION = exports.OFFER_AMOUNT = exports.OFFER_CURRENCY = exports.OFFER_METADATA = exports.OFFER_CHAINS = void 0;
+exports.validateOffer = validateOffer;
+const secp256k1_1 = require("@noble/curves/secp256k1");
+const utils_js_1 = require("./utils.js");
+// Offer TLV type numbers
+exports.OFFER_CHAINS = 2n;
+exports.OFFER_METADATA = 4n;
+exports.OFFER_CURRENCY = 6n;
+exports.OFFER_AMOUNT = 8n;
+exports.OFFER_DESCRIPTION = 10n;
+exports.OFFER_FEATURES = 12n;
+exports.OFFER_ABSOLUTE_EXPIRY = 14n;
+exports.OFFER_PATHS = 16n;
+exports.OFFER_ISSUER = 18n;
+exports.OFFER_QUANTITY_MAX = 20n;
+exports.OFFER_ISSUER_ID = 22n;
+const KNOWN_OFFER_TYPES = new Set([
+    exports.OFFER_CHAINS,
+    exports.OFFER_METADATA,
+    exports.OFFER_CURRENCY,
+    exports.OFFER_AMOUNT,
+    exports.OFFER_DESCRIPTION,
+    exports.OFFER_FEATURES,
+    exports.OFFER_ABSOLUTE_EXPIRY,
+    exports.OFFER_PATHS,
+    exports.OFFER_ISSUER,
+    exports.OFFER_QUANTITY_MAX,
+    exports.OFFER_ISSUER_ID,
+]);
+/**
+ * Check if a type is in the valid offer range.
+ * Offers may contain types 1-79 and 1000000000-1999999999.
+ */
+function isValidOfferType(type) {
+    if (type >= 1n && type <= 79n) {
+        return true;
+    }
+    if (type >= 1000000000n && type <= 1999999999n) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Validate UTF-8 encoding of a byte array.
+ * Returns the decoded string or throws if invalid.
+ */
+function validateUtf8(data, fieldName) {
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+    try {
+        return decoder.decode(data);
+    }
+    catch {
+        throw new Error(`Invalid UTF-8 in ${fieldName}`);
+    }
+}
+/**
+ * Validate a compressed public key (33 bytes, valid point on secp256k1).
+ */
+function validatePoint(data, fieldName) {
+    if (data.length !== 33) {
+        throw new Error(`Invalid ${fieldName}: expected 33 bytes, got ${data.length}`);
+    }
+    if (data[0] !== 0x02 && data[0] !== 0x03) {
+        throw new Error(`Invalid ${fieldName}: must start with 02 or 03`);
+    }
+    // Validate the point is actually on the secp256k1 curve
+    try {
+        secp256k1_1.secp256k1.ProjectivePoint.fromHex(data);
+    }
+    catch {
+        throw new Error(`Invalid ${fieldName}: not a valid point on secp256k1`);
+    }
+}
+/**
+ * Validate offer_chains field: must be a multiple of 32 bytes, and non-empty.
+ */
+function validateChains(data) {
+    if (data.length === 0 || data.length % 32 !== 0) {
+        throw new Error('Invalid offer_chains: length must be a non-zero multiple of 32');
+    }
+}
+/**
+ * Validate blinded paths (offer_paths field, type 16).
+ *
+ * Format:
+ *   For each path:
+ *     first_node_id: either 33-byte point OR 9-byte sciddir (if first byte 0x00 or 0x01)
+ *     path_key: 33-byte point (compressed pubkey)
+ *     num_hops: u8 (must be > 0)
+ *     For each hop:
+ *       blinded_node_id: 33-byte point
+ *       enclen: u16
+ *       encrypted_recipient_data: enclen bytes
+ */
+function validateBlindedPaths(data) {
+    let offset = 0;
+    // We need to parse all paths in the single offer_paths TLV value
+    let pathCount = 0;
+    while (offset < data.length) {
+        pathCount++;
+        // first_node_id: check if it's a sciddir (starts with 0x00 or 0x01) or regular point
+        if (offset >= data.length) {
+            throw new Error('Truncated offer_paths: missing first_node_id');
+        }
+        const firstByte = data[offset];
+        let firstNodeIdLen;
+        if (firstByte === 0x00 || firstByte === 0x01) {
+            // sciddir: 1 byte direction + 8 byte short_channel_id = 9 bytes
+            firstNodeIdLen = 9;
+        }
+        else if (firstByte === 0x02 || firstByte === 0x03) {
+            // Regular compressed point: 33 bytes
+            firstNodeIdLen = 33;
+        }
+        else {
+            throw new Error('Invalid first_node_id in blinded path: bad prefix byte');
+        }
+        if (offset + firstNodeIdLen > data.length) {
+            throw new Error('Truncated offer_paths: first_node_id truncated');
+        }
+        offset += firstNodeIdLen;
+        // path_key: 33-byte compressed point
+        if (offset + 33 > data.length) {
+            throw new Error('Truncated offer_paths: missing path_key');
+        }
+        const pathKeyPrefix = data[offset];
+        if (pathKeyPrefix !== 0x02 && pathKeyPrefix !== 0x03) {
+            throw new Error('Invalid path_key in blinded path: must start with 02 or 03');
+        }
+        offset += 33;
+        // num_hops: u8
+        if (offset >= data.length) {
+            throw new Error('Truncated offer_paths: missing num_hops');
+        }
+        const numHops = data[offset];
+        offset += 1;
+        if (numHops === 0) {
+            throw new Error('Invalid blinded path: num_hops must be > 0');
+        }
+        // Parse each hop
+        for (let h = 0; h < numHops; h++) {
+            // blinded_node_id: 33-byte point
+            if (offset + 33 > data.length) {
+                throw new Error('Truncated onionmsg_hop: missing blinded_node_id');
+            }
+            const blindedPrefix = data[offset];
+            if (blindedPrefix !== 0x02 && blindedPrefix !== 0x03) {
+                throw new Error('Invalid blinded_node_id: must start with 02 or 03');
+            }
+            offset += 33;
+            // enclen: u16
+            if (offset + 2 > data.length) {
+                throw new Error('Truncated onionmsg_hop: missing enclen');
+            }
+            const enclen = (data[offset] << 8) | data[offset + 1];
+            offset += 2;
+            // encrypted_recipient_data
+            if (offset + enclen > data.length) {
+                throw new Error('Truncated onionmsg_hop: encrypted_data truncated');
+            }
+            offset += enclen;
+        }
+    }
+    // Must have at least one path
+    if (pathCount === 0) {
+        throw new Error('offer_paths must contain at least one path');
+    }
+}
+/**
+ * Validate feature bits. Per the spec, unknown even feature bits must
+ * cause rejection. Odd bits are always safe to ignore.
+ */
+function validateFeatures(data) {
+    for (let byteIdx = 0; byteIdx < data.length; byteIdx++) {
+        const byte = data[byteIdx];
+        if (byte === 0) {
+            continue;
+        }
+        // Position from the right (LSB of last byte = bit 0)
+        const bitOffset = (data.length - 1 - byteIdx) * 8;
+        for (let bit = 0; bit < 8; bit++) {
+            if (byte & (1 << bit)) {
+                const featureBit = bitOffset + bit;
+                if (featureBit % 2 === 0) {
+                    throw new Error(`Unknown even feature bit ${featureBit}`);
+                }
+            }
+        }
+    }
+}
+/**
+ * Validate an offer's TLV records according to BOLT12 semantic rules.
+ */
+function validateOffer(records) {
+    let hasDescription = false;
+    let hasAmount = false;
+    let hasCurrency = false;
+    let hasIssuerId = false;
+    let hasPaths = false;
+    for (const record of records) {
+        const type = record.type;
+        // Check type is in valid offer range
+        if (!isValidOfferType(type)) {
+            if (type % 2n === 0n) {
+                throw new Error(`Invalid: unknown even field type ${type} outside offer range`);
+            }
+            // This type is out of range but odd - still invalid for offers
+            throw new Error(`Invalid: field type ${type} outside valid offer range`);
+        }
+        // Unknown even types must be rejected
+        if (!KNOWN_OFFER_TYPES.has(type) && type % 2n === 0n) {
+            throw new Error(`Unknown even TLV type ${type}`);
+        }
+        // Validate specific fields
+        switch (type) {
+            case exports.OFFER_CHAINS:
+                validateChains(record.value);
+                break;
+            case exports.OFFER_CURRENCY:
+                validateUtf8(record.value, 'offer_currency');
+                hasCurrency = true;
+                break;
+            case exports.OFFER_AMOUNT: {
+                const amount = (0, utils_js_1.readTruncatedUint)(record.value);
+                if (amount === 0n) {
+                    throw new Error('Invalid: zero offer_amount');
+                }
+                hasAmount = true;
+                break;
+            }
+            case exports.OFFER_DESCRIPTION:
+                validateUtf8(record.value, 'offer_description');
+                hasDescription = true;
+                break;
+            case exports.OFFER_FEATURES:
+                validateFeatures(record.value);
+                break;
+            case exports.OFFER_PATHS:
+                validateBlindedPaths(record.value);
+                hasPaths = true;
+                break;
+            case exports.OFFER_ISSUER:
+                validateUtf8(record.value, 'offer_issuer');
+                break;
+            case exports.OFFER_ISSUER_ID:
+                validatePoint(record.value, 'offer_issuer_id');
+                hasIssuerId = true;
+                break;
+        }
+    }
+    // Semantic validation rules:
+    // An offer with amount but no description is invalid
+    if (hasAmount && !hasDescription) {
+        throw new Error('Missing offer_description with offer_amount');
+    }
+    // Currency requires amount
+    if (hasCurrency && !hasAmount) {
+        throw new Error('Missing offer_amount with offer_currency');
+    }
+    // Must have either issuer_id or paths (or both)
+    if (!hasIssuerId && !hasPaths) {
+        throw new Error('Missing offer_issuer_id and no offer_paths');
+    }
+    return { records, hasDescription, hasAmount, hasCurrency, hasIssuerId, hasPaths };
+}
+//# sourceMappingURL=offer.js.map

package/dist/offer.js.map

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

package/dist/payer_proof.d.ts

@@ -0,0 +1,89 @@
+/**
+ * BOLT12 Payer Proof (experimental, PR #1295).
+ *
+ * A payer proof is a proof of invoice payment, encoded with the "lnp" prefix.
+ * It contains a subset of the invoice's TLV fields, allowing the payer to
+ * prove they paid a specific invoice while selectively disclosing only
+ * certain fields for privacy.
+ *
+ * New TLV types:
+ *   242 - preimage           (32-byte payment preimage)
+ *   244 - omitted_tlvs       (array of bigsize marker numbers)
+ *   246 - missing_hashes     (array of sha256 hashes for merkle reconstruction)
+ *   248 - leaf_hashes        (array of sha256 nonce hashes for included TLVs)
+ *   250 - payer_signature    (bip340sig + optional UTF-8 note)
+ */
+import type { TlvRecord } from './tlv.js';
+export declare const PP_PREIMAGE = 242n;
+export declare const PP_OMITTED_TLVS = 244n;
+export declare const PP_MISSING_HASHES = 246n;
+export declare const PP_LEAF_HASHES = 248n;
+export declare const PP_PAYER_SIGNATURE = 250n;
+export interface PayerProofFields {
+    /** Included TLV records (non-signature, non-payer-proof-specific) */
+    includedRecords: TlvRecord[];
+    /** The invoice signature (type 240) */
+    signature: Uint8Array;
+    /** Payment preimage (type 242, 32 bytes) */
+    preimage: Uint8Array | undefined;
+    /** Marker numbers for omitted TLVs (type 244) */
+    omittedTlvs: bigint[];
+    /** Missing merkle branch hashes (type 246) */
+    missingHashes: Uint8Array[];
+    /** Nonce hashes for included non-signature TLVs (type 248) */
+    leafHashes: Uint8Array[];
+    /** Payer signature (type 250) */
+    payerSignature: Uint8Array;
+    /** Optional note from payer_signature (type 250) */
+    payerNote: string;
+    /** invoice_payment_hash for preimage verification */
+    invoicePaymentHash: Uint8Array;
+    /** invoice_node_id for signature verification */
+    invoiceNodeId: Uint8Array;
+    /** invreq_payer_id for payer_signature verification */
+    payerId: Uint8Array;
+}
+/**
+ * Parse and validate a payer proof's TLV records.
+ */
+export declare function parsePayerProof(records: TlvRecord[]): PayerProofFields;
+/**
+ * Reconstruct the Merkle root from a payer proof.
+ *
+ * The tree has N positions: 1 implicit (type 0) + omitted markers + included records.
+ * Uses recursive DFS tree building to consume missing_hashes in the correct order.
+ */
+export declare function reconstructMerkleRoot(proof: PayerProofFields): Uint8Array;
+/**
+ * Verify a payer proof's signatures.
+ */
+export declare function verifyPayerProof(proof: PayerProofFields): {
+    valid: boolean;
+    merkleRoot: Uint8Array;
+    error?: string;
+};
+export interface CreatePayerProofParams {
+    /** Hex-encoded invoice TLV stream */
+    invoiceHex: string;
+    /** Hex-encoded 32-byte payment preimage */
+    preimageHex: string;
+    /** Hex-encoded 32-byte payer secret key (for BIP-340 signing) */
+    payerSecretKeyHex: string;
+    /** Additional TLV types to include beyond the required ones */
+    includedTlvTypes?: number[];
+    /** Optional payer note (UTF-8) */
+    note?: string;
+}
+export interface CreatePayerProofResult {
+    /** Hex-encoded proof TLV stream */
+    proofHex: string;
+    /** Bech32-encoded proof with "lnp" prefix */
+    proofBech32: string;
+    /** 32-byte merkle root */
+    merkleRoot: Uint8Array;
+}
+/**
+ * Create a BOLT12 payer proof from an invoice, preimage, and payer secret key.
+ */
+export declare function createPayerProof(params: CreatePayerProofParams): CreatePayerProofResult;
+//# sourceMappingURL=payer_proof.d.ts.map

package/dist/payer_proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payer_proof.d.ts","sourceRoot":"","sources":["../src/payer_proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAgB1C,eAAO,MAAM,WAAW,OAAO,CAAC;AAChC,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,cAAc,OAAO,CAAC;AACnC,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAwDvC,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,eAAe,EAAE,SAAS,EAAE,CAAC;IAC7B,uCAAuC;IACvC,SAAS,EAAE,UAAU,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,EAAE,UAAU,GAAG,SAAS,CAAC;IACjC,iDAAiD;IACjD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,8CAA8C;IAC9C,aAAa,EAAE,UAAU,EAAE,CAAC;IAC5B,8DAA8D;IAC9D,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB,iCAAiC;IACjC,cAAc,EAAE,UAAU,CAAC;IAC3B,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,kBAAkB,EAAE,UAAU,CAAC;IAC/B,iDAAiD;IACjD,aAAa,EAAE,UAAU,CAAC;IAC1B,uDAAuD;IACvD,OAAO,EAAE,UAAU,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,gBAAgB,CA+HtE;AAiHD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,UAAU,CA0CzE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAqCA;AAID,MAAM,WAAW,sBAAsB;IACrC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,UAAU,EAAE,UAAU,CAAC;CACxB;AAuHD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CA2HvF"}