{"_id":"@agentchurch/l402","_rev":"2-2b5cb4898268f1850755ad63863bc59a","name":"@agentchurch/l402","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@agentchurch/l402","version":"0.1.0","keywords":["l402","lightning","bitcoin","402","payment","macaroon","lsat","lnd","micropayments","edge"],"license":"MIT","_id":"@agentchurch/l402@0.1.0","maintainers":[{"name":"hypnolabs","email":"bitbrujo@gmail.com"}],"homepage":"https://github.com/HypnoLabs-io/l402-ts#readme","bugs":{"url":"https://github.com/HypnoLabs-io/l402-ts/issues"},"dist":{"shasum":"b8c19aacfdbb2d54671c4d2b43b632d3d83e3e9e","tarball":"https://registry.npmjs.org/@agentchurch/l402/-/l402-0.1.0.tgz","fileCount":15,"integrity":"sha512-cfP9k0Pgorj3ttHyIRAH2O5SWcrUExySsfpEr9PTd7NETkN5vZ97CW/tzjHrLejbpZXdpb17c/dNV8ejKHsW9A==","signatures":[{"sig":"MEUCIQDC8Cb7TQqj9e2SPADnTZ3Q+kTiqRrh5ZIkJ2N77N3v7QIgUPGUZch/x3U/SAsbTS5gC7itc2yjux/+eXb3lJ5fWdI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35366},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./lnd":{"types":"./dist/lnd-client.d.ts","import":"./dist/lnd-client.js"}},"gitHead":"8537c0444fcee1ca95aed78dd1f130fd98916070","scripts":{"test":"vitest run","build":"tsc","prepublishOnly":"npm run build && vitest run"},"_npmUser":{"name":"hypnolabs","email":"bitbrujo@gmail.com"},"repository":{"url":"git+https://github.com/HypnoLabs-io/l402-ts.git","type":"git"},"_npmVersion":"10.9.8","description":"L402 (Lightning HTTP 402) payment protocol for TypeScript — HMAC-SHA256 macaroons, challenge/verify, and an LND REST invoice client. Edge-safe core.","directories":{},"sideEffects":false,"_nodeVersion":"22.23.1","dependencies":{"@noble/hashes":"^2.0.1"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.18","typescript":"^5.9.3","@types/node":"^26.1.1"},"_npmOperationalInternal":{"tmp":"tmp/l402_0.1.0_1784672362909_0.573796612509877","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agentchurch/l402","version":"0.1.1","description":"L402 (Lightning HTTP 402) payment protocol for TypeScript — HMAC-SHA256 macaroons, challenge/verify, and an LND REST invoice client. Edge-safe core.","license":"MIT","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./lnd":{"types":"./dist/lnd-client.d.ts","import":"./dist/lnd-client.js"}},"sideEffects":false,"scripts":{"build":"tsc","test":"vitest run","prepublishOnly":"npm run build && vitest run"},"repository":{"type":"git","url":"git+https://github.com/HypnoLabs-io/l402-ts.git"},"homepage":"https://github.com/HypnoLabs-io/l402-ts#readme","bugs":{"url":"https://github.com/HypnoLabs-io/l402-ts/issues"},"keywords":["l402","lightning","bitcoin","402","payment","macaroon","lsat","lnd","micropayments","edge"],"engines":{"node":">=18"},"dependencies":{"@noble/hashes":"^2.0.1"},"devDependencies":{"@types/node":"^26.1.1","typescript":"^5.9.3","vitest":"^4.0.18"},"_id":"@agentchurch/l402@0.1.1","gitHead":"c6a58c0d8fe9714919375dd23260549785d2aad3","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-2ZZiatZ7NAbYoLXYLIltyKLW8pJ7l6Q3heSBqMTh6CVl6Gan1MB6v4RBe2Vpp2ri19dpDzRx5mmivSCj3aueZw==","shasum":"f9404f04aebe9510b32532177630775e368caab4","tarball":"https://registry.npmjs.org/@agentchurch/l402/-/l402-0.1.1.tgz","fileCount":15,"unpackedSize":33503,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDnMGDpXc97joHSpC1rI0BSiuyCSBpHlP4ykh+MaGtcuQIhAInLTvE4bvEwj2QCVvOrP0lDOjlyPhFkLwgYVWAAP9kq"}]},"_npmUser":{"name":"hypnolabs","email":"bitbrujo@gmail.com"},"directories":{},"maintainers":[{"name":"hypnolabs","email":"bitbrujo@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/l402_0.1.1_1784673175897_0.15075022078417422"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-21T22:19:22.772Z","modified":"2026-07-21T22:32:56.257Z","0.1.0":"2026-07-21T22:19:23.063Z","0.1.1":"2026-07-21T22:32:56.097Z"},"bugs":{"url":"https://github.com/HypnoLabs-io/l402-ts/issues"},"license":"MIT","homepage":"https://github.com/HypnoLabs-io/l402-ts#readme","keywords":["l402","lightning","bitcoin","402","payment","macaroon","lsat","lnd","micropayments","edge"],"repository":{"type":"git","url":"git+https://github.com/HypnoLabs-io/l402-ts.git"},"description":"L402 (Lightning HTTP 402) payment protocol for TypeScript — HMAC-SHA256 macaroons, challenge/verify, and an LND REST invoice client. Edge-safe core.","maintainers":[{"name":"hypnolabs","email":"bitbrujo@gmail.com"}],"readme":"# @agentchurch/l402\n\n**Charge for HTTP requests with Bitcoin Lightning.** This library implements L402, the protocol that turns HTTP's `402 Payment Required` status into a real payment flow: your server quotes a price, the client pays a Lightning invoice, and the retry carries cryptographic proof of payment. No accounts, no API keys, no payment processor.\n\nIt was extracted from [Agent Church](https://www.agentchurch.ai), where it runs in production letting AI agents pay for services autonomously. Machine-to-machine payments are L402's sweet spot — an agent can read the challenge, pay, and retry without a human in the loop.\n\n**What's in the box:**\n\n- The full server side: mint challenges, parse `Authorization` headers, verify payments.\n- An [LND](https://github.com/lightningnetwork/lnd) REST client for creating invoices (works with Umbrel and other self-signed-cert nodes).\n- The core is **Edge-safe** — verification is pure crypto ([@noble/hashes](https://github.com/paulmillr/noble-hashes)), so it runs in Next.js middleware, Cloudflare Workers, and Deno. The LND client is Node-only and lives on a separate subpath so it never enters your Edge bundle.\n\n## How the protocol works\n\n1. Client requests a paid endpoint → server responds `402` with a macaroon (a signed token) and a Lightning invoice.\n2. Client pays the invoice and receives the **preimage** — a secret that only exists once payment settles.\n3. Client retries with `Authorization: L402 <macaroon>:<preimage>`.\n4. Server checks the macaroon's signature and that the preimage hashes to the invoice's payment hash. Payment proven, no database lookup.\n\n## Install\n\n```bash\nnpm install @agentchurch/l402\n```\n\n## Usage\n\n**Quote a price** (Node — needs your LND node to mint the invoice):\n\n```ts\nimport { buildL402Challenge, formatWWWAuthenticate, rootKeyFromEnv } from \"@agentchurch/l402\";\nimport { createLndClient } from \"@agentchurch/l402/lnd\";\n\nconst lnd = createLndClient({ restUrl: \"https://your-node:8080\", macaroonHex: process.env.LND_MACAROON_HEX! });\nconst { paymentHash, invoice } = await lnd.createInvoice(5000, \"premium_api access\");\n\nconst challenge = buildL402Challenge(rootKeyFromEnv(), {\n  paymentHash, invoice,\n  service: \"premium_api\",\n  amountSats: 5000,\n  location: \"api.example.com\",\n});\n\n// 402 response with: WWW-Authenticate: formatWWWAuthenticate(challenge)\n```\n\n**Verify the payment** (anywhere, including Edge):\n\n```ts\nimport { parseL402Authorization, verifyL402Token, l402CaveatsMatch } from \"@agentchurch/l402\";\n\nconst token = parseL402Authorization(request.headers.get(\"Authorization\"));\nconst result = token && verifyL402Token(rootKey, token);\n\nif (result?.valid && l402CaveatsMatch(result, \"premium_api\", 5000)) {\n  // Paid. Serve the request.\n}\n```\n\n`l402CaveatsMatch` matters: it stops a token bought for a cheap service being replayed against an expensive one.\n\n**One payment, one use?** That part is yours — verification proves the payment is real, not that it's unused. If your endpoint is pay-per-call, store consumed preimages (a unique-constrained table works) and reject repeats. If one payment should grant a session, skip this; the token's expiry caveat bounds its lifetime.\n\n## Reference\n\n- Root key: 32-byte hex (`openssl rand -hex 32`), kept secret; it signs and verifies every macaroon.\n- Macaroon primitives (`createMacaroon`, `verifyMacaroonSignature`, serialization) are exported if you need lower-level control.\n- Serialization is base64(JSON) — simple and debuggable. Clients treat the macaroon as an opaque string, which is all L402 requires, so standard L402 clients interoperate.\n- Full types are shipped; the `.d.ts` files document every export.\n\n## License\n\n[MIT](LICENSE) © Hypno Labs\n","readmeFilename":"README.md"}