bolt12-utils 0.1.0

package/src/index.ts

@@ -0,0 +1,132 @@
+/**
+ * bolt12-decoder: Pure JS/TS BOLT12 implementation.
+ *
+ * Supports decoding and validating BOLT12 offers, invoice requests,
+ * and invoices using only pure JavaScript dependencies:
+ *   - @noble/curves for secp256k1/schnorr
+ *   - @noble/hashes for SHA256
+ */
+
+export { decodeBolt12, encodeBolt12 } from './bech32.js';
+export { readBigSize, writeBigSize } from './bigsize.js';
+export { parseTlvStream, type TlvRecord } from './tlv.js';
+export { computeMerkleRoot, taggedHash, verifySignature } from './merkle.js';
+export { validateOffer } from './offer.js';
+/**
+ * @deprecated Use `extractGeneratedOfferFields` and `GeneratedOfferFields` from
+ * the auto-generated module instead. These hand-written exports use non-spec
+ * field names (e.g. `description` instead of `offer_description`) and only
+ * cover offers — the generated module covers all BOLT12 message types.
+ */
+export {
+  extractOfferFields,
+  type OfferFields,
+  type Chain,
+} from './fields.js';
+export {
+  parsePayerProof,
+  reconstructMerkleRoot,
+  verifyPayerProof,
+  createPayerProof,
+  type PayerProofFields,
+  type CreatePayerProofParams,
+  type CreatePayerProofResult,
+} from './payer_proof.js';
+
+// Auto-generated types and extractors from BOLT12 spec CSV
+export {
+  // Offer
+  type OfferFields as GeneratedOfferFields,
+  extractOfferFields as extractGeneratedOfferFields,
+  KNOWN_OFFER_TYPES,
+  OFFER_TLV_NAMES,
+  // Invoice request
+  type InvoiceRequestFields,
+  extractInvoiceRequestFields,
+  KNOWN_INVOICE_REQUEST_TYPES,
+  INVOICE_REQUEST_TLV_NAMES,
+  // Invoice
+  type InvoiceFields,
+  extractInvoiceFields,
+  KNOWN_INVOICE_TYPES,
+  INVOICE_TLV_NAMES,
+  // Invoice error
+  type InvoiceErrorFields,
+  extractInvoiceErrorFields,
+  KNOWN_INVOICE_ERROR_TYPES,
+  INVOICE_ERROR_TLV_NAMES,
+  // Subtypes
+  type BlindedPayinfo,
+  type FallbackAddress,
+  // Constants (all)
+  OFFER_CHAINS, OFFER_METADATA, OFFER_CURRENCY, OFFER_AMOUNT,
+  OFFER_DESCRIPTION, OFFER_FEATURES, OFFER_ABSOLUTE_EXPIRY,
+  OFFER_PATHS, OFFER_ISSUER, OFFER_QUANTITY_MAX, OFFER_ISSUER_ID,
+  INVREQ_METADATA, INVREQ_CHAIN, INVREQ_AMOUNT, INVREQ_FEATURES,
+  INVREQ_QUANTITY, INVREQ_PAYER_ID, INVREQ_PAYER_NOTE, INVREQ_PATHS,
+  INVREQ_BIP_353_NAME, SIGNATURE,
+  INVOICE_PATHS, INVOICE_BLINDEDPAY, INVOICE_CREATED_AT,
+  INVOICE_RELATIVE_EXPIRY, INVOICE_PAYMENT_HASH, INVOICE_AMOUNT,
+  INVOICE_FALLBACKS, INVOICE_FEATURES, INVOICE_NODE_ID,
+} from './generated.js';
+
+import { decodeBolt12, type Bolt12HRP } from './bech32.js';
+import { parseTlvStream, type TlvRecord } from './tlv.js';
+import { computeMerkleRoot, verifySignature } from './merkle.js';
+import { validateOffer } from './offer.js';
+import { extractOfferFields, type OfferFields } from './fields.js';
+import { parsePayerProof, createPayerProof, type PayerProofFields, type CreatePayerProofParams, type CreatePayerProofResult } from './payer_proof.js';
+
+export interface DecodedOffer extends OfferFields {
+  hrp: Bolt12HRP;
+  offer_id: Uint8Array;
+}
+
+/**
+ * Decode and validate a BOLT12 offer string.
+ *
+ * Returns typed fields directly:
+ *   const { description, amount, issuer_id, offer_id } = decodeOffer(str);
+ */
+export function decodeOffer(bolt12String: string): DecodedOffer {
+  const { hrp, data } = decodeBolt12(bolt12String);
+
+  if (hrp !== 'lno') {
+    throw new Error(`Expected offer (lno), got ${hrp}`);
+  }
+
+  const records = parseTlvStream(data);
+
+  // Validate offer semantics
+  validateOffer(records);
+
+  // Extract typed fields
+  const fields = extractOfferFields(records);
+
+  // Compute offer_id (merkle root of all TLVs)
+  const offer_id = computeMerkleRoot(records);
+
+  return { ...fields, hrp, offer_id };
+}
+
+export interface DecodedPayerProof {
+  hrp: Bolt12HRP;
+  records: TlvRecord[];
+  proof: PayerProofFields;
+}
+
+/**
+ * Decode and validate a BOLT12 payer proof string (experimental, PR #1295).
+ */
+export function decodePayerProof(bolt12String: string): DecodedPayerProof {
+  const { hrp, data } = decodeBolt12(bolt12String);
+
+  if (hrp !== 'lnp') {
+    throw new Error(`Expected payer proof (lnp), got ${hrp}`);
+  }
+
+  const records = parseTlvStream(data);
+  const proof = parsePayerProof(records);
+
+  return { hrp, records, proof };
+}

package/src/merkle.ts

@@ -0,0 +1,163 @@
+/**
+ * Merkle tree computation for BOLT12 signature verification.
+ *
+ * Each TLV record is paired with a nonce derived from the first TLV:
+ *   leaf    = H("LnLeaf", tlv_bytes)
+ *   nonce   = H(SHA256("LnNonce" || first_tlv_bytes), type_bytes)
+ *   branch  = H("LnBranch", sorted(leaf, nonce))
+ *
+ * These branches are then paired up in a binary tree:
+ *   parent  = H("LnBranch", sorted(left, right))
+ *
+ * The root of the tree is the merkle root (offer_id for offers).
+ *
+ * Signature verification uses:
+ *   msg = H("lightning" || messagename || "signature", merkle_root)
+ */
+
+import { sha256 } from '@noble/hashes/sha2';
+import { concatBytes } from '@noble/hashes/utils';
+import { schnorr } from '@noble/curves/secp256k1';
+import type { TlvRecord } from './tlv.js';
+import { writeBigSize } from './bigsize.js';
+import { compareBytes } from './utils.js';
+
+const encoder = new TextEncoder();
+
+/**
+ * Tagged hash: H(tag, msg) = SHA256(SHA256(tag) || SHA256(tag) || msg)
+ */
+export function taggedHash(tag: Uint8Array, msg: Uint8Array): Uint8Array {
+  const tagHash = sha256(tag);
+  return sha256(concatBytes(tagHash, tagHash, msg));
+}
+
+/**
+ * Tagged hash using a pre-computed tag hash.
+ */
+function taggedHashWithHash(tagHash: Uint8Array, msg: Uint8Array): Uint8Array {
+  return sha256(concatBytes(tagHash, tagHash, msg));
+}
+
+/**
+ * Serialize a single TLV record to its wire format (type + length + value).
+ */
+export function tlvToBytes(record: TlvRecord): Uint8Array {
+  const typeBytes = writeBigSize(record.type);
+  const lengthBytes = writeBigSize(record.length);
+  return concatBytes(typeBytes, lengthBytes, record.value);
+}
+
+/**
+ * Compute a branch from a pair of nodes, ordering them lexicographically.
+ */
+export function branchHash(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const branchTagHash = sha256(encoder.encode('LnBranch'));
+  const [smaller, larger] = compareBytes(a, b) < 0 ? [a, b] : [b, a];
+  return taggedHashWithHash(branchTagHash, concatBytes(smaller, larger));
+}
+
+/** Signature TLV type range (240-1000 inclusive). */
+function isSignatureType(type: bigint): boolean {
+  return type >= 240n && type <= 1000n;
+}
+
+/**
+ * Compute per-TLV branch hashes (leaf+nonce combined).
+ * Returns the branch hash for each non-signature TLV, and the nonce tag hash.
+ */
+export function computePerTlvBranches(records: TlvRecord[]): {
+  branches: Uint8Array[];
+  nonceTagHash: Uint8Array;
+  leafTagHash: Uint8Array;
+  branchTagHash: Uint8Array;
+} {
+  const nonSig = records.filter(r => !isSignatureType(r.type));
+  if (nonSig.length === 0) {
+    throw new Error('Cannot compute merkle root of empty TLV set');
+  }
+
+  // Nonce tag: SHA256("LnNonce" || first_record_bytes)
+  const firstRecBytes = tlvToBytes(nonSig[0]);
+  const nonceTagHash = sha256(concatBytes(encoder.encode('LnNonce'), firstRecBytes));
+
+  const leafTagHash = sha256(encoder.encode('LnLeaf'));
+  const branchTagHash = sha256(encoder.encode('LnBranch'));
+
+  const branches: Uint8Array[] = nonSig.map((record) => {
+    const recBytes = tlvToBytes(record);
+    const typeBytes = writeBigSize(record.type);
+
+    const leaf = taggedHashWithHash(leafTagHash, recBytes);
+    const nonce = taggedHashWithHash(nonceTagHash, typeBytes);
+
+    // Combine leaf and nonce with lexicographic ordering
+    const [smaller, larger] = compareBytes(leaf, nonce) < 0 ? [leaf, nonce] : [nonce, leaf];
+    return taggedHashWithHash(branchTagHash, concatBytes(smaller, larger));
+  });
+
+  return { branches, nonceTagHash, leafTagHash, branchTagHash };
+}
+
+/**
+ * Build merkle tree from per-TLV branch hashes, bottom-up.
+ */
+function buildMerkleTree(nodes: Uint8Array[]): Uint8Array {
+  const branchTagHash = sha256(encoder.encode('LnBranch'));
+
+  while (nodes.length > 1) {
+    const parents: Uint8Array[] = [];
+    let i = 0;
+    while (i < nodes.length) {
+      if (i + 1 < nodes.length) {
+        const [smaller, larger] = compareBytes(nodes[i], nodes[i + 1]) < 0
+          ? [nodes[i], nodes[i + 1]]
+          : [nodes[i + 1], nodes[i]];
+        parents.push(taggedHashWithHash(branchTagHash, concatBytes(smaller, larger)));
+        i += 2;
+      } else {
+        parents.push(nodes[i]);
+        i += 1;
+      }
+    }
+    nodes = parents;
+  }
+
+  return nodes[0];
+}
+
+/**
+ * Compute the merkle root from an array of TLV records.
+ *
+ * Excludes signature TLVs (types 240-1000) from the tree.
+ */
+export function computeMerkleRoot(records: TlvRecord[]): Uint8Array {
+  const { branches } = computePerTlvBranches(records);
+  return buildMerkleTree([...branches]);
+}
+
+/**
+ * Compute the signature verification message.
+ * tag = "lightning" + messagename + "signature"
+ */
+export function signatureTag(messageName: string): Uint8Array {
+  return encoder.encode(`lightning${messageName}signature`);
+}
+
+/**
+ * Verify a BIP340 Schnorr signature on a BOLT12 message.
+ */
+export function verifySignature(
+  messageName: string,
+  merkleRoot: Uint8Array,
+  pubkey32: Uint8Array,
+  signature: Uint8Array,
+): boolean {
+  const tag = signatureTag(messageName);
+  const msg = taggedHash(tag, merkleRoot);
+  try {
+    return schnorr.verify(signature, msg, pubkey32);
+  } catch {
+    return false;
+  }
+}

package/src/offer.ts

@@ -0,0 +1,328 @@
+/**
+ * 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)
+ */
+
+import { secp256k1 } from '@noble/curves/secp256k1';
+import type { TlvRecord } from './tlv.js';
+import { readTruncatedUint } from './utils.js';
+
+// Offer TLV type numbers
+export const OFFER_CHAINS = 2n;
+export const OFFER_METADATA = 4n;
+export const OFFER_CURRENCY = 6n;
+export const OFFER_AMOUNT = 8n;
+export const OFFER_DESCRIPTION = 10n;
+export const OFFER_FEATURES = 12n;
+export const OFFER_ABSOLUTE_EXPIRY = 14n;
+export const OFFER_PATHS = 16n;
+export const OFFER_ISSUER = 18n;
+export const OFFER_QUANTITY_MAX = 20n;
+export const OFFER_ISSUER_ID = 22n;
+
+const KNOWN_OFFER_TYPES = new Set([
+  OFFER_CHAINS,
+  OFFER_METADATA,
+  OFFER_CURRENCY,
+  OFFER_AMOUNT,
+  OFFER_DESCRIPTION,
+  OFFER_FEATURES,
+  OFFER_ABSOLUTE_EXPIRY,
+  OFFER_PATHS,
+  OFFER_ISSUER,
+  OFFER_QUANTITY_MAX,
+  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: bigint): boolean {
+  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: Uint8Array, fieldName: string): string {
+  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: Uint8Array, fieldName: string): void {
+  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.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: Uint8Array): void {
+  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: Uint8Array): void {
+  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: number;
+    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: Uint8Array): void {
+  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}`);
+        }
+      }
+    }
+  }
+}
+
+export interface ValidatedOffer {
+  records: TlvRecord[];
+  hasDescription: boolean;
+  hasAmount: boolean;
+  hasCurrency: boolean;
+  hasIssuerId: boolean;
+  hasPaths: boolean;
+}
+
+/**
+ * Validate an offer's TLV records according to BOLT12 semantic rules.
+ */
+export function validateOffer(records: TlvRecord[]): ValidatedOffer {
+  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 OFFER_CHAINS:
+        validateChains(record.value);
+        break;
+
+      case OFFER_CURRENCY:
+        validateUtf8(record.value, 'offer_currency');
+        hasCurrency = true;
+        break;
+
+      case OFFER_AMOUNT: {
+        const amount = readTruncatedUint(record.value);
+        if (amount === 0n) {
+          throw new Error('Invalid: zero offer_amount');
+        }
+        hasAmount = true;
+        break;
+      }
+
+      case OFFER_DESCRIPTION:
+        validateUtf8(record.value, 'offer_description');
+        hasDescription = true;
+        break;
+
+      case OFFER_FEATURES:
+        validateFeatures(record.value);
+        break;
+
+      case OFFER_PATHS:
+        validateBlindedPaths(record.value);
+        hasPaths = true;
+        break;
+
+      case OFFER_ISSUER:
+        validateUtf8(record.value, 'offer_issuer');
+        break;
+
+      case 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 };
+}