@speeddev/l402-express 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tryspeed.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# @speeddev/l402-express
+
+[![npm version](https://img.shields.io/badge/npm-0.1.0-blue)](https://www.npmjs.com/package/@speeddev/l402-express)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node.js: >=18](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen)](https://nodejs.org)
+
+Express middleware that enforces [L402](https://docs.lightning.engineering/the-lightning-network/l402) payment-required flows using [Speed](https://www.tryspeed.com) Lightning invoices and macaroon credentials.
+
+---
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Configuration reference](#configuration-reference)
+- [Generating the macaroon secret](#generating-the-macaroon-secret)
+- [API key security](#api-key-security)
+- [Environment variables](#environment-variables)
+- [Error responses](#error-responses)
+- [TypeScript](#typescript)
+- [License](#license)
+
+---
+
+## How it works
+
+L402 is an HTTP-native payment protocol built on Lightning Network. The flow has three steps:
+
+1. **Challenge** — a client makes a request to a protected endpoint without payment credentials. The middleware responds with `402 Payment Required`, a Lightning invoice (created via the Speed API), and a signed macaroon.
+2. **Payment** — the client pays the Lightning invoice and receives a preimage (proof of payment).
+3. **Access** — the client retries the request with an `Authorization: L402 <macaroon>:<preimage>` header. The middleware verifies the macaroon signature, the caveats (method, path, amount, currency, expiry), and the preimage against the payment hash. On success the request is forwarded to your route handler.
+
+Responses to verified requests are cached for the duration of the macaroon's TTL (10 minutes), so replaying a valid credential returns the cached response instantly without hitting your handler again.
+
+---
+
+## Prerequisites
+
+- **Node.js 18 or higher**
+- **Express 4 or higher**
+- **A Speed account and API key** — sign up and manage keys at [app.tryspeed.com/dashboard](https://app.tryspeed.com/dashboard)
+
+### Getting a Speed API key
+
+1. Log in to the [Speed Web Application](https://app.tryspeed.com/dashboard).
+2. Select the mode — **Test** for development, **Live** for production.
+3. Navigate to **Developers → API keys → Standard keys**.
+4. Click **Reveal key** to copy your secret key (prefix `sk_test_…` or `sk_live_…`).
+
+Use your **publishable key** or **secret key** as the `speedApiKey` option. The publishable key is sufficient for creating payments. Secret keys (`sk_test_…` / `sk_live_…`) work too but carry broader account privileges — prefer the publishable key when it covers your use case.
+
+---
+
+## Installation
+
+```bash
+npm install @speeddev/l402-express
+```
+
+`express` is a peer dependency and must be installed separately if you have not done so already:
+
+```bash
+npm install express
+```
+
+---
+
+## Quick start
+
+```js
+import express from 'express';
+import l402Middleware from '@speeddev/l402-express';
+
+const app = express();
+
+app.use(
+  l402Middleware({
+    speedApiKey: process.env.SPEED_KEY,
+    macaroonSecret: process.env.SPEED_MACAROON_SECRET,
+    configs: [
+      {
+        method: 'GET',
+        path: '/api/report',
+        amount: 100,       // $1.00 USD
+        currency: 'USD',
+        targetCurrency: 'SATS',
+      },
+    ],
+  })
+);
+
+app.get('/api/report', (req, res) => {
+  res.json({ data: 'paid content here' });
+});
+
+app.listen(3000);
+```
+
+Any route not listed in `configs` passes through freely without a payment check.
+
+---
+
+## Configuration reference
+
+### Middleware options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `speedApiKey` | `string` | Yes | Your Speed secret API key (`sk_test_…` or `sk_live_…`). |
+| `macaroonSecret` | `string` | Yes | 32-byte hex-encoded secret used to sign and verify macaroons. Generate one with `npx l402-generate-secret`. |
+| `caveatTtlMs` | `number` | No | Macaroon TTL in milliseconds. Defaults to 10 minutes when omitted. Must be a positive number if provided. |
+| `configs` | `RouteConfig[]` | Yes | Array of route-level payment rules. |
+
+### RouteConfig
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `method` | `string` | Yes | HTTP method to match, uppercase (e.g. `'GET'`, `'POST'`). |
+| `path` | `string` | Yes | [path-to-regexp](https://github.com/pillarjs/path-to-regexp) pattern (e.g. `'/api/resource/:id'`). |
+| `amount` | `number` | Yes | Payment amount in the smallest unit of `currency` (e.g. cents for `USD`, whole units for `SATS`). |
+| `currency` | `string` | Yes | ISO 4217 currency code for the payment amount (e.g. `'USD'`, `'EUR'`, `'SATS'`). |
+| `targetCurrency` | `string` | No | Cryptocurrency to settle in: `'SATS'`, `'USDT'`, or `'USDC'`. Defaults to `'SATS'` when omitted. |
+
+**Example — charge $2.50 USD, settle in SATS:**
+
+```js
+{
+  method: 'POST',
+  path: '/api/generate',
+  amount: 250,
+  currency: 'USD',
+  targetCurrency: 'SATS',
+}
+```
+
+**Example — charge 1000 sats directly:**
+
+```js
+{
+  method: 'GET',
+  path: '/api/data',
+  amount: 1000,
+  currency: 'SATS',
+}
+```
+
+---
+
+## Generating the macaroon secret
+
+The macaroon secret is a private 32-byte key used to sign credentials. It must be kept secret — anyone who obtains it can forge valid macaroons.
+
+Generate one with the CLI tool bundled in this package:
+
+```bash
+npx l402-generate-secret
+```
+
+This prints a 64-character hex string. Store it as an environment variable and never commit it to source control.
+
+```
+b3f1a2c4e5d6...  ← copy this into SPEED_MACAROON_SECRET
+```
+
+Rotate this secret if you suspect it has been compromised. All previously issued macaroons will immediately become invalid.
+
+---
+
+## API key security
+
+Speed API keys carry full account privileges. Follow these practices:
+
+- **Never** embed secret keys in client-side code, public repositories, or anywhere outside a secure server environment.
+- Store keys in environment variables or a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault).
+- Use **Test mode keys** (`sk_test_…`) during development and **Live mode keys** (`sk_live_…`) in production only.
+- If a key is compromised, rotate it immediately from **Developers → API keys** in the [Speed dashboard](https://app.tryspeed.com/dashboard). A rotated key is permanently disabled; you cannot rotate the same key again within 24 hours.
+- Consider [restricted API keys](https://app.tryspeed.com/apikeys/restricted-keys) to limit the scope of what each key can do.
+
+---
+
+## Environment variables
+
+The middleware does not read environment variables directly. Pass your secrets explicitly via the options object:
+
+```js
+l402Middleware({
+  speedApiKey: process.env.SPEED_KEY,
+  macaroonSecret: process.env.SPEED_MACAROON_SECRET,
+  configs: [...],
+})
+```
+
+Recommended `.env` layout (use [dotenv](https://github.com/motdotla/dotenv) or your platform's secret injection):
+
+```env
+SPEED_KEY=sk_test_...
+SPEED_MACAROON_SECRET=<64-char hex from npx l402-generate-secret>
+```
+
+---
+
+## Error responses
+
+| Status | Condition | Body |
+|---|---|---|
+| `402` | No `Authorization` header — payment required. | `{}` with `WWW-Authenticate` header containing the macaroon and Lightning invoice. |
+| `400` | `Authorization` header present but malformed or macaroon verification failed. | `{ "message": "Malformed 'authorization' header" }` |
+| `401` | Preimage does not match the payment hash in the macaroon. | `{ "message": "Invalid payment preimage" }` |
+| `409` | A request with the same macaroon is already being processed. | `{ "message": "Payment is already being processed" }` |
+| `500` | Speed API call failed when creating the invoice. | `{ "message": "Internal server error" }` |
+
+### WWW-Authenticate header format
+
+```
+L402 macaroon="<base64-encoded macaroon>", invoice="<BOLT11 invoice>"
+```
+
+The client pays the `invoice` and uses the returned preimage together with the `macaroon` to form the `Authorization` header:
+
+```
+Authorization: L402 <macaroon>:<preimage>
+```
+
+---
+
+## TypeScript
+
+The package ships with a bundled declaration file. No `@types` package is needed. Named types `RouteConfig` and `L402MiddlewareOptions` are available as named exports.
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/bin/generate-secret.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import crypto from 'crypto';
+console.log(crypto.randomBytes(32).toString('hex'));

package/constants.js

@@ -0,0 +1,26 @@
+export const MACAROON_VERSION = 2;
+
+export const CAVEAT_KEYS = {
+    AMOUNT: 'amount',
+    CURRENCY: 'currency',
+    METHOD: 'method',
+    PATH: 'path',
+    PAYMENT_HASH: 'payment_hash',
+    EXPIRES_AT: 'expires_at'
+};
+
+export const HEADERS = {
+    AUTHORIZATION: 'authorization',
+    WWW_AUTHENTICATE: 'www-authenticate',
+};
+
+export const DEFAULT_CAVEAT_TTL_MS = 1000 * 60 * 10;
+export const DEFAULT_TARGET_CURRENCY = 'SATS';
+export const HASH_ALGORITHM = 'SHA-256';
+export const L402_SCHEME = 'L402';
+export const MACAROON_SECRET_HEX_LENGTH = 64;
+export const MAX_CAVEATS = 20;
+export const SPEED_BASE_URL = 'https://api.tryspeed.com';
+export const SPEED_PAYMENT_METHOD = 'lightning';
+export const VALID_TARGET_CURRENCIES = [DEFAULT_TARGET_CURRENCY, 'USDT', 'USDC'];
+export const FETCH_TIMEOUT_MS = 10_000;

package/errors.js

@@ -0,0 +1,7 @@
+export const ERROR_MESSAGES = {
+    INTERNAL_SERVER_ERROR: "Internal server error",
+    PAYMENT_ALREADY_PROCESSING: "Payment is already being processed",
+    MALFORMED_AUTH_HEADER: "Malformed 'authorization' header",
+    INVALID_PREIMAGE: "Invalid payment preimage",
+    TOO_MANY_CAVEATS: "Macaroon contains too many caveats",
+};

package/index.d.ts

@@ -0,0 +1,80 @@
+import type { RequestHandler } from 'express';
+
+/** HTTP method string (uppercase). */
+export type HttpMethod =
+  | 'GET'
+  | 'POST'
+  | 'PUT'
+  | 'PATCH'
+  | 'DELETE'
+  | 'HEAD'
+  | 'OPTIONS';
+
+/**
+ * Per-route payment configuration.
+ *
+ * @example
+ * { method: 'GET', path: '/api/data', amount: 1000, currency: 'USD' }
+ */
+export interface RouteConfig {
+  /** HTTP method to match (case-sensitive, uppercase). */
+  method: HttpMethod;
+  /**
+   * Express-style path pattern passed to `path-to-regexp`.
+   * @example '/api/resource/:id'
+   */
+  path: string;
+  /** Payment amount in the smallest unit of `currency` (e.g. cents for USD, sats for SATS). */
+  amount: number;
+  /** ISO 4217 currency code or `'SATS'` for satoshis. */
+  currency: string;
+  /**
+   * Target settlement currency for the Speed invoice.
+   * Defaults to `'SATS'` when omitted.
+   */
+  targetCurrency?: string;
+}
+
+/** Options passed to the `l402Middleware` factory. */
+export interface L402MiddlewareOptions {
+  /** Speed API key used to create Lightning invoices. */
+  speedApiKey: string;
+  /** Hex-encoded secret used to sign and verify macaroons. */
+  macaroonSecret: string;
+  /**
+   * Macaroon TTL in milliseconds. Defaults to 10 minutes when omitted.
+   * Must be a positive number if provided.
+   */
+  caveatTtlMs?: number;
+  /**
+   * Route-level payment rules.
+   * Routes not listed here are passed through without a payment check.
+   */
+  configs: RouteConfig[];
+}
+
+/**
+ * Creates an Express middleware that enforces L402 payment-required flows.
+ *
+ * - Unlisted routes pass through freely.
+ * - Requests without an `Authorization` header receive a `402` challenge
+ *   containing a Speed Lightning invoice and a signed macaroon.
+ * - Requests with a valid `L402 <macaroon>:<preimage>` credential are
+ *   forwarded to the next handler; responses are cached for the macaroon TTL.
+ *
+ * @example
+ * ```ts
+ * import l402Middleware from '@speeddev/l402-express';
+ *
+ * app.use(l402Middleware({
+ *   speedApiKey: process.env.SPEED_KEY!,
+ *   macaroonSecret: process.env.SPEED_MACAROON_SECRET!,
+ *   configs: [
+ *     { method: 'GET', path: '/api/data', amount: 1000, currency: 'USD' },
+ *   ],
+ * }));
+ * ```
+ */
+declare function l402Middleware(options: L402MiddlewareOptions): RequestHandler;
+
+export default l402Middleware;

package/index.js

@@ -0,0 +1,150 @@
+import { importMacaroon } from 'macaroon';
+import { match } from 'path-to-regexp';
+import { createMacaroon, verifyMacaroon } from './macaroon.js';
+import { createSpeedInvoice } from './speed.js';
+import NodeCache from 'node-cache';
+import { webcrypto } from 'node:crypto';
+import { CAVEAT_KEYS, HEADERS, L402_SCHEME, HASH_ALGORITHM, MAX_CAVEATS } from './constants.js';
+import { ERROR_MESSAGES } from './errors.js';
+import { validateOptions } from './validation.js';
+
+const decoder = new TextDecoder();
+
+const l402Middleware = ({ speedApiKey, macaroonSecret, caveatTtlMs, configs }) => {
+    validateOptions({ speedApiKey, macaroonSecret, caveatTtlMs, configs });
+
+    const cache = new NodeCache();
+    const lock = new Map();
+
+    const endpointMatchers = configs.map(config => ({
+        method: config.method,
+        matchPath: match(config.path),
+        config,
+    }));
+
+    return async (request, response, next) => {
+
+        const endpointConfig = getEndpointConfig(request, endpointMatchers);
+        if (isFreeEndpoint(endpointConfig)) {
+            next();
+            return;
+        }
+        if (isPaymentMissing(request)) {
+            await sendPaymentChallenge(response, endpointConfig, speedApiKey, macaroonSecret, caveatTtlMs);
+            return;
+        }
+
+        const authorizationHeader = request.headers[HEADERS.AUTHORIZATION].trim();
+        if (authorizationHeader.length > 2048) {
+            return response.status(400).json({ message: ERROR_MESSAGES.MALFORMED_AUTH_HEADER });
+        }
+        const l402Match = authorizationHeader.match(
+            /^L402\s+([^:\s]+):([^:\s]+)$/i
+        );
+        if (!l402Match) {
+            response.status(400).json({ message: ERROR_MESSAGES.MALFORMED_AUTH_HEADER });
+            return;
+        }
+
+        const [, encodedMacaroon, receivedPreimage] = l402Match;
+        let macaroonIdentifier;
+        try {
+            const macaroonObject = JSON.parse(
+                Buffer.from(encodedMacaroon, 'base64').toString('utf8')
+            );
+            const macaroon = importMacaroon(macaroonObject);
+            if (macaroon.caveats.length > MAX_CAVEATS) {
+                response.status(400).json({ message: ERROR_MESSAGES.TOO_MANY_CAVEATS });
+                return;
+            }
+            macaroonIdentifier = Buffer.from(macaroon.identifier).toString("utf-8");
+
+            const cachedResponse = cache.get(macaroonIdentifier);
+            if (cachedResponse) {
+                response.status(cachedResponse.status).set('Content-Type', cachedResponse.contentType).send(cachedResponse.body);
+                return;
+            }
+
+            verifyMacaroon(macaroon, endpointConfig, macaroonSecret);
+            const preimageValid = await isPreimageValid(macaroon, receivedPreimage);
+
+            if (lock.get(macaroonIdentifier)) {
+                response.status(409).json({ message: ERROR_MESSAGES.PAYMENT_ALREADY_PROCESSING });
+                return;
+            }
+
+            if (preimageValid) {
+                lock.set(macaroonIdentifier, true);
+                const expiresAt = Number(extractCaveatFromMacaroon(macaroon, CAVEAT_KEYS.EXPIRES_AT));
+                const originalSend = response.send.bind(response);
+                response.send = (body) => {
+                    const ttl = Math.floor((expiresAt - Date.now()) / 1000);
+                    if (ttl > 0) {
+                        cache.set(macaroonIdentifier, { body, contentType: response.getHeader('Content-Type'), status: response.statusCode }, ttl);
+                    }
+                    return originalSend(body);
+                };
+                response.on('finish', () => {
+                    lock.delete(macaroonIdentifier);
+                });
+                next();
+            } else {
+                response.status(401).json({ message: ERROR_MESSAGES.INVALID_PREIMAGE });
+            }
+        } catch (error) {
+            console.error(error);
+            response.status(400).json({ message: ERROR_MESSAGES.MALFORMED_AUTH_HEADER });
+            if (macaroonIdentifier) lock.delete(macaroonIdentifier);
+        }
+    }
+};
+
+async function sendPaymentChallenge(response, endpointConfig, speedApiKey, macaroonSecret, caveatTtlMs) {
+    try {
+        const invoiceResponse = await createSpeedInvoice(endpointConfig.currency, endpointConfig.amount, endpointConfig.targetCurrency, speedApiKey);
+        const lightningInvoice = invoiceResponse.payment_method_options.lightning.payment_request;
+        const macaroon = createMacaroon(endpointConfig, lightningInvoice, macaroonSecret, caveatTtlMs);
+        response.status(402).set(HEADERS.WWW_AUTHENTICATE, `${L402_SCHEME} macaroon="${macaroon}", invoice="${lightningInvoice}"`).json({});
+    } catch (err) {
+        console.error(err);
+        response.status(500).json({ message: ERROR_MESSAGES.INTERNAL_SERVER_ERROR });
+    }
+}
+
+function getEndpointConfig(request, endpointMatchers) {
+    const entry = endpointMatchers.find(
+        e => e.method === request.method && e.matchPath(request.path)
+    );
+    return entry?.config;
+}
+
+function isFreeEndpoint(endpointConfig) {
+    return endpointConfig == undefined;
+}
+
+function isPaymentMissing(request) {
+    const authorizationHeader = request.headers[HEADERS.AUTHORIZATION];
+    return !authorizationHeader?.trim();
+}
+
+function extractCaveatFromMacaroon(macaroon, caveatKey) {
+    const prefix = `${caveatKey} = `;
+    for (const c of macaroon.caveats) {
+        const decoded = decoder.decode(c.identifier);
+        if (decoded.startsWith(prefix)) return decoded.slice(prefix.length);
+    }
+    return null;
+}
+
+async function computePreimageHash(preimage) {
+    const hashBuffer = await webcrypto.subtle.digest(HASH_ALGORITHM, Buffer.from(preimage, 'hex'));
+    return Buffer.from(hashBuffer).toString("hex");
+}
+
+async function isPreimageValid(macaroon, receivedPreimage) {
+    const paymentHash = extractCaveatFromMacaroon(macaroon, CAVEAT_KEYS.PAYMENT_HASH);
+    const receivedPaymentHash = await computePreimageHash(receivedPreimage);
+    return paymentHash === receivedPaymentHash;
+}
+
+export default l402Middleware;

package/macaroon.js

@@ -0,0 +1,50 @@
+import { newMacaroon } from 'macaroon';
+import { decode } from 'light-bolt11-decoder';
+import { MACAROON_VERSION, CAVEAT_KEYS, DEFAULT_CAVEAT_TTL_MS } from './constants.js';
+import { randomUUID } from 'node:crypto';
+
+export function createMacaroon(routeConfig, bolt11Invoice, macaroonSecret, caveatTtlMs) {
+  const paymentHashSection = decode(bolt11Invoice).sections.find(s => s.name === CAVEAT_KEYS.PAYMENT_HASH);
+  if (!paymentHashSection) {
+    throw new Error('Invalid BOLT11 invoice: missing payment_hash');
+  }
+  const paymentHash = paymentHashSection.value;
+  const macaroon = newMacaroon({
+    version: MACAROON_VERSION,
+    rootKey: Buffer.from(macaroonSecret, 'hex'),
+    identifier: randomUUID(),
+  });
+  const effectiveTtlMs = caveatTtlMs ?? DEFAULT_CAVEAT_TTL_MS;
+
+  macaroon.addFirstPartyCaveat(`${CAVEAT_KEYS.PAYMENT_HASH} = ${paymentHash}`);
+  macaroon.addFirstPartyCaveat(`${CAVEAT_KEYS.EXPIRES_AT} = ${Date.now() + effectiveTtlMs}`);
+  macaroon.addFirstPartyCaveat(`${CAVEAT_KEYS.METHOD} = ${routeConfig.method}`);
+  macaroon.addFirstPartyCaveat(`${CAVEAT_KEYS.PATH} = ${routeConfig.path}`);
+  macaroon.addFirstPartyCaveat(`${CAVEAT_KEYS.AMOUNT} = ${routeConfig.amount}`);
+  macaroon.addFirstPartyCaveat(`${CAVEAT_KEYS.CURRENCY} = ${routeConfig.currency}`);
+  const serializedMacaroon = macaroon.exportJSON();
+  return Buffer.from(JSON.stringify(serializedMacaroon)).toString('base64');
+}
+
+export function verifyMacaroon(macaroon, routeConfig, macaroonSecret) {
+  macaroon.verify(
+    Buffer.from(macaroonSecret, 'hex'),
+    (caveat) => {
+      if (caveat === `${CAVEAT_KEYS.METHOD} = ${routeConfig.method}`) return;
+      if (caveat === `${CAVEAT_KEYS.PATH} = ${routeConfig.path}`) return;
+      if (caveat === `${CAVEAT_KEYS.AMOUNT} = ${routeConfig.amount}`) return;
+      if (caveat === `${CAVEAT_KEYS.CURRENCY} = ${routeConfig.currency}`) return;
+
+      const [caveatKey, caveatValue] = caveat.split(' = ');
+      if (caveatKey === CAVEAT_KEYS.PAYMENT_HASH) return;
+      if (caveatKey === CAVEAT_KEYS.EXPIRES_AT) {
+        const expiresAt = Number(caveatValue);
+        if (isNaN(expiresAt) || Date.now() > expiresAt) return `caveat not satisfied: ${caveat}`;
+        return;
+      }
+
+      return `caveat not satisfied: ${caveat}`;
+    },
+    []
+  );
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@speeddev/l402-express",
+  "version": "0.1.0",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "bin": {
+    "l402-generate-secret": "bin/generate-secret.js"
+  },
+  "scripts": {
+    "test": "node --test specs/test.js"
+  },
+  "author": "Speed <support@tryspeed.com>",
+  "license": "MIT",
+  "description": "Express middleware for L402 Lightning Network payments — issues Speed payment challenges, verifies macaroon credentials, and gates API access to paid requests only",
+  "keywords": [
+    "l402",
+    "lightning",
+    "bitcoin",
+    "payments",
+    "express",
+    "middleware",
+    "macaroon",
+    "speed"
+  ],
+  "homepage": "https://github.com/TrySpeed/speed-agentic-payment-sdk/tree/main/server/javascript/express#readme",
+  "bugs": {
+    "url": "https://github.com/TrySpeed/speed-agentic-payment-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TrySpeed/speed-agentic-payment-sdk.git",
+    "directory": "server/javascript/express"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "constants.js",
+    "errors.js",
+    "macaroon.js",
+    "speed.js",
+    "validation.js",
+    "bin/"
+  ],
+  "type": "module",
+  "dependencies": {
+    "light-bolt11-decoder": "^3.2.0",
+    "macaroon": "^3.0.4",
+    "node-cache": "^5.1.2",
+    "path-to-regexp": "^8.4.2"
+  },
+  "peerDependencies": {
+    "express": ">=4.19.2"
+  }
+}

package/speed.js

@@ -0,0 +1,25 @@
+import { SPEED_BASE_URL, DEFAULT_TARGET_CURRENCY, SPEED_PAYMENT_METHOD, FETCH_TIMEOUT_MS } from './constants.js';
+
+export async function createSpeedInvoice(currency, amount, targetCurrency, apiKey) {
+    const invoicePayload = {
+        currency,
+        amount,
+        target_currency: targetCurrency ?? DEFAULT_TARGET_CURRENCY,
+        payment_methods: [SPEED_PAYMENT_METHOD]
+    };
+
+    const apiResponse = await fetch(`${SPEED_BASE_URL}/payments`, {
+        headers: {
+            "Authorization": `Basic ${Buffer.from(`${apiKey}:`).toString('base64')}`,
+            "Content-Type": "application/json",
+        },
+        method: "POST",
+        body: JSON.stringify(invoicePayload),
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!apiResponse.ok) {
+        const errorBody = await apiResponse.text();
+        throw new Error(`Speed API error (${apiResponse.status}): ${errorBody}`);
+    }
+    return apiResponse.json();
+}

package/validation.js

@@ -0,0 +1,50 @@
+import { MACAROON_SECRET_HEX_LENGTH } from './constants.js';
+
+const HEX_RE = new RegExp(`^[0-9a-fA-F]{${MACAROON_SECRET_HEX_LENGTH}}$`);
+
+export function validateOptions({ speedApiKey, macaroonSecret, caveatTtlMs, configs }) {
+    if (!speedApiKey || typeof speedApiKey !== 'string') {
+        throw new Error('l402: speedApiKey must be a non-empty string');
+    }
+
+    if (!macaroonSecret || typeof macaroonSecret !== 'string') {
+        throw new Error('l402: macaroonSecret must be a non-empty string');
+    }
+    if (!HEX_RE.test(macaroonSecret)) {
+        throw new Error(`l402: macaroonSecret must be a ${MACAROON_SECRET_HEX_LENGTH}-character hex string (32 bytes). Generate one with: npx l402-generate-secret`);
+    }
+
+    if (!Array.isArray(configs) || configs.length === 0) {
+        throw new Error('l402: configs must be a non-empty array');
+    }
+
+    if (caveatTtlMs !== undefined && (typeof caveatTtlMs !== 'number' || caveatTtlMs <= 0)) {
+        throw new Error('l402: caveatTtlMs must be a positive number');
+    }
+
+    const seen = new Set();
+    for (let i = 0; i < configs.length; i++) {
+        const c = configs[i];
+        const label = `configs[${i}]`;
+
+        if (!c.method || typeof c.method !== 'string') {
+            throw new Error(`l402: ${label}.method must be a non-empty string (e.g. 'GET')`);
+        }
+        c.method = c.method.toUpperCase();
+        if (!c.path || typeof c.path !== 'string') {
+            throw new Error(`l402: ${label}.path must be a non-empty string`);
+        }
+        if (typeof c.amount !== 'number' || !isFinite(c.amount) || c.amount <= 0) {
+            throw new Error(`l402: ${label}.amount must be a positive finite number`);
+        }
+        if (!c.currency || typeof c.currency !== 'string') {
+            throw new Error(`l402: ${label}.currency must be a non-empty string (e.g. 'USD', 'SATS')`);
+        }
+
+        const key = `${configs[i].method.toUpperCase()}:${configs[i].path}`;
+        if (seen.has(key)) {
+            throw new Error(`l402: duplicate route label — ${key} is already defined`);
+        }
+        seen.add(key);
+    }
+}