@thecryptodonkey/toll-booth 3.6.0 → 3.7.1

package/dist/core/toll-booth.js

@@ -65,6 +65,19 @@ export function createTollBooth(config) {
                 const challengeHeaders = {};
                 const challengeBody = {};
                 const normalisedPrice = normalisedPricing[req.path] ?? { sats: defaultAmount };
+                // HEAD requests return a lightweight price probe without creating
+                // invoices or storing state. Useful for lnget --dry-run and indexers.
+                if (req.method === 'HEAD') {
+                    if (normalisedPrice.sats !== undefined) {
+                        challengeHeaders['X-L402-Price-Sats'] = String(normalisedPrice.sats);
+                    }
+                    if (normalisedPrice.usd !== undefined) {
+                        challengeHeaders['X-L402-Price-Usd'] = String(normalisedPrice.usd);
+                    }
+                    challengeHeaders['WWW-Authenticate'] = 'L402 price-only';
+                    challengeBody.message = 'Payment required.';
+                    return { action: 'challenge', status: 402, headers: challengeHeaders, body: challengeBody };
+                }
                 for (const rail of rails) {
                     if (rail.canChallenge && !rail.canChallenge(normalisedPrice))
                         continue;

package/dist/macaroon.js

@@ -1,5 +1,14 @@
+import { randomBytes } from 'node:crypto';
 import { newMacaroon, importMacaroon } from 'macaroon';
 const LOCATION = 'toll-booth';
+/**
+ * Aperture-compatible L402 identifier layout (version 0):
+ *   [0..1]   uint16 big-endian version (0)
+ *   [2..33]  32-byte payment hash
+ *   [34..65] 32-byte random token ID
+ */
+const L402_ID_VERSION = 0;
+const L402_ID_SIZE = 66;
 const KNOWN_CAVEATS = new Set(['payment_hash', 'credit_balance', 'currency', 'route', 'expires', 'ip']);
 /** Caveat keys that encode monetary value and must not be set via the caveats parameter. */
 const RESERVED_CAVEAT_KEYS = new Set(['payment_hash', 'credit_balance', 'currency']);
@@ -16,7 +25,7 @@ const MAX_CUSTOM_CAVEATS = 16;
 export function mintMacaroon(rootKey, paymentHash, creditBalanceSats, caveats, currency) {
     const keyBytes = hexToBytes(rootKey);
     const m = newMacaroon({
-        identifier: paymentHash,
+        identifier: encodeL402Identifier(paymentHash),
         location: LOCATION,
         rootKey: keyBytes,
         version: 2,
@@ -68,13 +77,15 @@ export function verifyMacaroon(rootKey, macaroonBase64, context) {
                 return 'duplicate caveat';
             return null;
         }, []);
-        // Use the immutable identifier as the authoritative payment hash —
-        // it is set at mint time and covered by the root signature.
-        const json = m.exportJSON();
-        const identifier = json.i;
+        // Decode the aperture-compatible binary identifier to extract the
+        // payment hash.  The identifier is set at mint time and covered by
+        // the root signature, so it cannot be tampered with.
+        const paymentHash = decodeL402Identifier(m.identifier);
+        if (!paymentHash)
+            return { valid: false };
         const caveats = parseCaveats(macaroonBase64);
         // Cross-check: the payment_hash caveat must match the identifier
-        if (caveats.payment_hash && caveats.payment_hash !== identifier) {
+        if (caveats.payment_hash && caveats.payment_hash !== paymentHash) {
             return { valid: false };
         }
         if (context) {
@@ -108,7 +119,7 @@ export function verifyMacaroon(rootKey, macaroonBase64, context) {
         const currency = caveats.currency ?? 'sat';
         return {
             valid: true,
-            paymentHash: identifier,
+            paymentHash,
             creditBalance,
             currency,
             customCaveats: Object.keys(customCaveats).length > 0 ? customCaveats : undefined,
@@ -153,6 +164,22 @@ export function parseCaveats(macaroonBase64) {
     }
     return result;
 }
+function encodeL402Identifier(paymentHash) {
+    const id = new Uint8Array(L402_ID_SIZE);
+    id[0] = (L402_ID_VERSION >> 8) & 0xff;
+    id[1] = L402_ID_VERSION & 0xff;
+    id.set(hexToBytes(paymentHash), 2);
+    id.set(randomBytes(32), 34);
+    return id;
+}
+function decodeL402Identifier(id) {
+    if (id.length < L402_ID_SIZE)
+        return undefined;
+    const version = (id[0] << 8) | id[1];
+    if (version !== L402_ID_VERSION)
+        return undefined;
+    return bytesToHex(id.slice(2, 34));
+}
 function hexToBytes(hex) {
     const bytes = new Uint8Array(hex.length / 2);
     for (let i = 0; i < hex.length; i += 2) {
@@ -160,6 +187,9 @@ function hexToBytes(hex) {
     }
     return bytes;
 }
+function bytesToHex(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
 function uint8ToBase64(bytes) {
     return Buffer.from(bytes).toString('base64');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thecryptodonkey/toll-booth",
-  "version": "3.6.0",
+  "version": "3.7.1",
   "type": "module",
   "description": "Monetise any API with HTTP 402 payments. Payment-rail agnostic middleware for Express, Hono, Deno, Bun, and Workers.",
   "license": "MIT",