@bsv/402-pay 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# @bsv/402-pay
+
+[BRC-121](https://github.com/bitcoin-sv/BRCs/blob/master/payments/0121.md) Simple 402 Payments -- server middleware and client for BSV micropayments over HTTP.
+
+## Install
+
+```sh
+npm install @bsv/402-pay
+```
+
+Peer dependency: `@bsv/sdk >= 2.0.0`
+
+## Server
+
+### Express middleware
+
+```ts
+import express from 'express'
+import { createPaymentMiddleware } from '@bsv/402-pay/server'
+
+const app = express()
+
+app.use('/articles/:slug', createPaymentMiddleware({
+  wallet,  // WalletInterface from @bsv/sdk
+  calculatePrice: (path) => {
+    // Return price in satoshis, or undefined to skip payment
+    return 100
+  }
+}))
+
+app.get('/articles/:slug', (req, res) => {
+  // req.payment is set if payment was accepted
+  res.send('Paid content here')
+})
+```
+
+### Low-level validation
+
+```ts
+import { validatePayment, send402 } from '@bsv/402-pay/server'
+
+// In any HTTP handler:
+const result = await validatePayment(req, wallet)
+if (!result) {
+  send402(res, serverIdentityKey, 100)
+  return
+}
+// Payment accepted — serve content
+```
+
+## Client
+
+### Fetch wrapper
+
+```ts
+import { create402Fetch } from '@bsv/402-pay/client'
+
+const fetch402 = create402Fetch({ wallet })
+
+// Automatically handles 402 responses with payment
+const response = await fetch402('https://example.com/articles/foo')
+const html = await response.text()
+
+// Clear the payment cache
+fetch402.clearCache()
+```
+
+## Headers
+
+| Header | Direction | Description |
+|---|---|---|
+| `x-bsv-sats` | Server → Client | Required satoshi amount |
+| `x-bsv-server` | Server → Client | Server identity public key |
+| `x-bsv-beef` | Client → Server | Base64-encoded BEEF transaction |
+| `x-bsv-sender` | Client → Server | Client identity public key |
+| `x-bsv-nonce` | Client → Server | Base64-encoded derivation prefix |
+| `x-bsv-time` | Client → Server | Unix millisecond timestamp |
+| `x-bsv-vout` | Client → Server | Payment output index |
+
+## Replay Protection
+
+Two mechanisms prevent replay attacks:
+
+1. **Timestamp freshness** -- `x-bsv-time` must be within 30 seconds of the server's clock
+2. **Transaction uniqueness** -- `internalizeAction` returns `isMerge: true` for previously seen transactions
+
+## License
+
+See LICENSE

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+import type { WalletInterface } from '@bsv/sdk';
+export interface Payment402Options {
+    /** The client's wallet instance */
+    wallet: WalletInterface;
+    /** Cache timeout in milliseconds for paid content (default: 30 minutes) */
+    cacheTimeoutMs?: number;
+}
+/**
+ * Creates a fetch wrapper that automatically handles 402 Payment Required responses.
+ *
+ * When a 402 is received, the wrapper constructs a BRC-121 payment using the
+ * provided wallet and retransmits the request with payment headers.
+ *
+ * Usage:
+ * ```ts
+ * import { create402Fetch } from '@bsv/402-pay/client'
+ *
+ * const fetch402 = create402Fetch({ wallet })
+ * const response = await fetch402('https://example.com/articles/foo')
+ * ```
+ */
+export declare function create402Fetch(options: Payment402Options): ((url: string, init?: RequestInit) => Promise<Response>) & {
+    clearCache: () => void;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAG/C,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,MAAM,EAAE,eAAe,CAAA;IACvB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAQD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,UAY1B,MAAM,SAAQ,WAAW,KAAQ,OAAO,CAAC,QAAQ,CAAC;;EAiGhF"}

package/dist/client.js

@@ -0,0 +1,111 @@
+import { PublicKey, Utils, Random } from '@bsv/sdk';
+import { BRC29_PROTOCOL_ID, HEADERS } from './constants.js';
+/**
+ * Creates a fetch wrapper that automatically handles 402 Payment Required responses.
+ *
+ * When a 402 is received, the wrapper constructs a BRC-121 payment using the
+ * provided wallet and retransmits the request with payment headers.
+ *
+ * Usage:
+ * ```ts
+ * import { create402Fetch } from '@bsv/402-pay/client'
+ *
+ * const fetch402 = create402Fetch({ wallet })
+ * const response = await fetch402('https://example.com/articles/foo')
+ * ```
+ */
+export function create402Fetch(options) {
+    const { wallet, cacheTimeoutMs = 30 * 60 * 1000 } = options;
+    const cache = new Map();
+    /**
+     * Clears the payment cache. Call this when the user clears history
+     * or when you want to force re-payment.
+     */
+    function clearCache() {
+        cache.clear();
+    }
+    async function fetch402(url, init = {}) {
+        // Check cache
+        const cached = cache.get(url);
+        if (cached && (Date.now() - cached.timestamp) < cacheTimeoutMs) {
+            return new Response(cached.body, {
+                status: cached.response.status,
+                headers: cached.response.headers
+            });
+        }
+        // Initial request
+        const res = await fetch(url, init);
+        if (res.status !== 402) {
+            return res;
+        }
+        // Read 402 headers
+        const satsHeader = res.headers.get(HEADERS.SATS);
+        const serverHeader = res.headers.get(HEADERS.SERVER);
+        if (!satsHeader || !serverHeader)
+            return res;
+        const satoshis = Number.parseInt(satsHeader);
+        if (isNaN(satoshis) || satoshis <= 0)
+            return res;
+        // Construct payment
+        const serverIdentityKey = serverHeader;
+        const nonce = Utils.toBase64(Random(8));
+        const time = String(Date.now());
+        const timeSuffixB64 = Buffer.from(time).toString('base64');
+        const originator = new URL(url).origin;
+        // Derive recipient public key via BRC-42
+        const { publicKey: derivedPubKey } = await wallet.getPublicKey({
+            protocolID: BRC29_PROTOCOL_ID,
+            keyID: `${nonce} ${timeSuffixB64}`,
+            counterparty: serverIdentityKey
+        }, originator);
+        const pkh = PublicKey.fromString(derivedPubKey).toHash('hex');
+        // Get sender identity key
+        const { publicKey: senderIdentityKey } = await wallet.getPublicKey({ identityKey: true }, originator);
+        // Create payment transaction
+        const actionResult = await wallet.createAction({
+            description: `Paid Content: ${new URL(url).pathname}`,
+            outputs: [{
+                    satoshis,
+                    lockingScript: `76a914${pkh}88ac`,
+                    outputDescription: '402 web payment',
+                    customInstructions: JSON.stringify({
+                        derivationPrefix: nonce,
+                        derivationSuffix: timeSuffixB64,
+                        serverIdentityKey
+                    }),
+                    tags: ['402-payment']
+                }],
+            labels: ['402-payment'],
+            options: { randomizeOutputs: false }
+        }, originator);
+        const txBase64 = Utils.toBase64(actionResult.tx);
+        // Retransmit with payment headers
+        const paidRes = await fetch(url, {
+            ...init,
+            headers: {
+                ...init.headers,
+                [HEADERS.BEEF]: txBase64,
+                [HEADERS.SENDER]: senderIdentityKey,
+                [HEADERS.NONCE]: nonce,
+                [HEADERS.TIME]: time,
+                [HEADERS.VOUT]: '0'
+            }
+        });
+        // Cache successful responses
+        if (paidRes.ok) {
+            const body = await paidRes.text();
+            cache.set(url, {
+                response: paidRes,
+                body,
+                timestamp: Date.now()
+            });
+            return new Response(body, {
+                status: paidRes.status,
+                headers: paidRes.headers
+            });
+        }
+        return paidRes;
+    }
+    return Object.assign(fetch402, { clearCache });
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEnD,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAe3D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,OAA0B;IACvD,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAA;IAC3D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAA;IAE3C;;;OAGG;IACH,SAAS,UAAU;QACjB,KAAK,CAAC,KAAK,EAAE,CAAA;IACf,CAAC;IAED,KAAK,UAAU,QAAQ,CAAC,GAAW,EAAE,OAAoB,EAAE;QACzD,cAAc;QACd,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC7B,IAAI,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,cAAc,EAAE,CAAC;YAC/D,OAAO,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE;gBAC/B,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM;gBAC9B,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO;aACjC,CAAC,CAAA;QACJ,CAAC;QAED,kBAAkB;QAClB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;QAClC,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,OAAO,GAAG,CAAA;QACZ,CAAC;QAED,mBAAmB;QACnB,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QAChD,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QACpD,IAAI,CAAC,UAAU,IAAI,CAAC,YAAY;YAAE,OAAO,GAAG,CAAA;QAE5C,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;QAC5C,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC;YAAE,OAAO,GAAG,CAAA;QAEhD,oBAAoB;QACpB,MAAM,iBAAiB,GAAG,YAAY,CAAA;QACtC,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;QACvC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;QAC/B,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;QAC1D,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,CAAA;QAEtC,yCAAyC;QACzC,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC;YAC7D,UAAU,EAAE,iBAAiB;YAC7B,KAAK,EAAE,GAAG,KAAK,IAAI,aAAa,EAAE;YAClC,YAAY,EAAE,iBAAiB;SAChC,EAAE,UAAU,CAAC,CAAA;QAEd,MAAM,GAAG,GAAG,SAAS,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,KAAK,CAAW,CAAA;QAEvE,0BAA0B;QAC1B,MAAM,EAAE,SAAS,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAChE,EAAE,WAAW,EAAE,IAAI,EAAE,EACrB,UAAU,CACX,CAAA;QAED,6BAA6B;QAC7B,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC;YAC7C,WAAW,EAAE,iBAAiB,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;YACrD,OAAO,EAAE,CAAC;oBACR,QAAQ;oBACR,aAAa,EAAE,SAAS,GAAG,MAAM;oBACjC,iBAAiB,EAAE,iBAAiB;oBACpC,kBAAkB,EAAE,IAAI,CAAC,SAAS,CAAC;wBACjC,gBAAgB,EAAE,KAAK;wBACvB,gBAAgB,EAAE,aAAa;wBAC/B,iBAAiB;qBAClB,CAAC;oBACF,IAAI,EAAE,CAAC,aAAa,CAAC;iBACtB,CAAC;YACF,MAAM,EAAE,CAAC,aAAa,CAAC;YACvB,OAAO,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE;SACrC,EAAE,UAAU,CAAC,CAAA;QAEd,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAc,CAAC,CAAA;QAE5D,kCAAkC;QAClC,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC/B,GAAG,IAAI;YACP,OAAO,EAAE;gBACP,GAAI,IAAI,CAAC,OAA8C;gBACvD,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ;gBACxB,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,iBAAiB;gBACnC,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK;gBACtB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI;gBACpB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG;aACpB;SACF,CAAC,CAAA;QAEF,6BAA6B;QAC7B,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC;YACf,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,CAAA;YACjC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;gBACb,QAAQ,EAAE,OAAO;gBACjB,IAAI;gBACJ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;aACtB,CAAC,CAAA;YACF,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;gBACxB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,OAAO,EAAE,OAAO,CAAC,OAAO;aACzB,CAAC,CAAA;QACJ,CAAC;QAED,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,UAAU,EAAE,CAAC,CAAA;AAChD,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,25 @@
+import type { WalletProtocol } from '@bsv/sdk';
+/** BRC-29 protocol ID for key derivation */
+export declare const BRC29_PROTOCOL_ID: WalletProtocol;
+/** Header prefix for all BRC-121 headers */
+export declare const HEADER_PREFIX = "x-bsv-";
+/** Header names */
+export declare const HEADERS: {
+    /** Server → Client: required satoshi amount */
+    readonly SATS: "x-bsv-sats";
+    /** Server → Client: server identity public key */
+    readonly SERVER: "x-bsv-server";
+    /** Client → Server: base64-encoded BEEF transaction */
+    readonly BEEF: "x-bsv-beef";
+    /** Client → Server: client identity public key */
+    readonly SENDER: "x-bsv-sender";
+    /** Client → Server: base64-encoded derivation prefix */
+    readonly NONCE: "x-bsv-nonce";
+    /** Client → Server: Unix millisecond timestamp */
+    readonly TIME: "x-bsv-time";
+    /** Client → Server: output index (decimal string) */
+    readonly VOUT: "x-bsv-vout";
+};
+/** Default payment window: 30 seconds */
+export declare const DEFAULT_PAYMENT_WINDOW_MS = 30000;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAE9C,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,EAAE,cAAoC,CAAA;AAEpE,4CAA4C;AAC5C,eAAO,MAAM,aAAa,WAAW,CAAA;AAErC,mBAAmB;AACnB,eAAO,MAAM,OAAO;IAClB,+CAA+C;;IAE/C,kDAAkD;;IAElD,uDAAuD;;IAEvD,kDAAkD;;IAElD,wDAAwD;;IAExD,kDAAkD;;IAElD,qDAAqD;;CAE7C,CAAA;AAEV,yCAAyC;AACzC,eAAO,MAAM,yBAAyB,QAAS,CAAA"}

package/dist/constants.js

@@ -0,0 +1,24 @@
+/** BRC-29 protocol ID for key derivation */
+export const BRC29_PROTOCOL_ID = [2, '3241645161d8'];
+/** Header prefix for all BRC-121 headers */
+export const HEADER_PREFIX = 'x-bsv-';
+/** Header names */
+export const HEADERS = {
+    /** Server → Client: required satoshi amount */
+    SATS: `${HEADER_PREFIX}sats`,
+    /** Server → Client: server identity public key */
+    SERVER: `${HEADER_PREFIX}server`,
+    /** Client → Server: base64-encoded BEEF transaction */
+    BEEF: `${HEADER_PREFIX}beef`,
+    /** Client → Server: client identity public key */
+    SENDER: `${HEADER_PREFIX}sender`,
+    /** Client → Server: base64-encoded derivation prefix */
+    NONCE: `${HEADER_PREFIX}nonce`,
+    /** Client → Server: Unix millisecond timestamp */
+    TIME: `${HEADER_PREFIX}time`,
+    /** Client → Server: output index (decimal string) */
+    VOUT: `${HEADER_PREFIX}vout`
+};
+/** Default payment window: 30 seconds */
+export const DEFAULT_PAYMENT_WINDOW_MS = 30_000;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAEA,4CAA4C;AAC5C,MAAM,CAAC,MAAM,iBAAiB,GAAmB,CAAC,CAAC,EAAE,cAAc,CAAC,CAAA;AAEpE,4CAA4C;AAC5C,MAAM,CAAC,MAAM,aAAa,GAAG,QAAQ,CAAA;AAErC,mBAAmB;AACnB,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,+CAA+C;IAC/C,IAAI,EAAE,GAAG,aAAa,MAAM;IAC5B,kDAAkD;IAClD,MAAM,EAAE,GAAG,aAAa,QAAQ;IAChC,uDAAuD;IACvD,IAAI,EAAE,GAAG,aAAa,MAAM;IAC5B,kDAAkD;IAClD,MAAM,EAAE,GAAG,aAAa,QAAQ;IAChC,wDAAwD;IACxD,KAAK,EAAE,GAAG,aAAa,OAAO;IAC9B,kDAAkD;IAClD,IAAI,EAAE,GAAG,aAAa,MAAM;IAC5B,qDAAqD;IACrD,IAAI,EAAE,GAAG,aAAa,MAAM;CACpB,CAAA;AAEV,yCAAyC;AACzC,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { HEADERS, HEADER_PREFIX, BRC29_PROTOCOL_ID, DEFAULT_PAYMENT_WINDOW_MS } from './constants.js';
+export { createPaymentMiddleware, validatePayment, send402 } from './server.js';
+export type { PaymentMiddlewareOptions, PaymentResult, PaymentRequest, PaymentResponse } from './server.js';
+export { create402Fetch } from './client.js';
+export type { Payment402Options } from './client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAA;AACrG,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC/E,YAAY,EAAE,wBAAwB,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC3G,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,6 @@
+// BRC-121: Simple 402 Payments
+// https://github.com/bitcoin-sv/BRCs/blob/master/payments/0121.md
+export { HEADERS, HEADER_PREFIX, BRC29_PROTOCOL_ID, DEFAULT_PAYMENT_WINDOW_MS } from './constants.js';
+export { createPaymentMiddleware, validatePayment, send402 } from './server.js';
+export { create402Fetch } from './client.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,kEAAkE;AAElE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAA;AACrG,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAE/E,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA"}

package/dist/server.d.ts

@@ -0,0 +1,51 @@
+import { type WalletInterface } from '@bsv/sdk';
+export interface PaymentResult {
+    accepted: boolean;
+    satoshisPaid: number;
+    senderIdentityKey: string;
+}
+export interface PaymentMiddlewareOptions {
+    /** The server's wallet instance */
+    wallet: WalletInterface;
+    /** Function that returns the price in satoshis for a given request path. Return 0 or undefined to skip payment. */
+    calculatePrice: (path: string) => number | undefined;
+    /** Payment freshness window in milliseconds (default: 30000) */
+    paymentWindowMs?: number;
+}
+/**
+ * Generic request/response interface so the middleware is not coupled to Express.
+ * Works with Express, Fastify, or any framework that provides headers, path, status, and set.
+ */
+export interface PaymentRequest {
+    path: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+export interface PaymentResponse {
+    status(code: number): PaymentResponse;
+    set(headers: Record<string, string>): PaymentResponse;
+    end(): void;
+}
+/**
+ * Sends a 402 Payment Required response with price and server identity headers.
+ */
+export declare function send402(res: PaymentResponse, serverIdentityKey: string, sats: number): void;
+/**
+ * Validates payment headers on an incoming request.
+ * Returns a PaymentResult if the payment is valid, or null if the request should be rejected.
+ */
+export declare function validatePayment(req: PaymentRequest, wallet: WalletInterface, paymentWindowMs?: number): Promise<PaymentResult | null>;
+/**
+ * Creates an Express-compatible middleware function for BRC-121 payments.
+ *
+ * Usage:
+ * ```ts
+ * import { createPaymentMiddleware } from '@bsv/402-pay/server'
+ *
+ * app.use('/articles/:slug', createPaymentMiddleware({
+ *   wallet,
+ *   calculatePrice: (path) => 100
+ * }))
+ * ```
+ */
+export declare function createPaymentMiddleware(options: PaymentMiddlewareOptions): (req: any, res: any, next: any) => Promise<any>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAe,MAAM,UAAU,CAAA;AAG5D,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,iBAAiB,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,mCAAmC;IACnC,MAAM,EAAE,eAAe,CAAA;IACvB,mHAAmH;IACnH,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;IACpD,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;CACvD;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAA;IACrC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,eAAe,CAAA;IACrD,GAAG,IAAI,IAAI,CAAA;CACZ;AAED;;GAEG;AACH,wBAAgB,OAAO,CACrB,GAAG,EAAE,eAAe,EACpB,iBAAiB,EAAE,MAAM,EACzB,IAAI,EAAE,MAAM,GACX,IAAI,CAMN;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,eAAe,EACvB,eAAe,GAAE,MAAkC,GAClD,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CA2C/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,IAIzD,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,GAAG,kBA+B5C"}

package/dist/server.js

@@ -0,0 +1,104 @@
+import { Utils, Beef } from '@bsv/sdk';
+import { HEADERS, DEFAULT_PAYMENT_WINDOW_MS } from './constants.js';
+/**
+ * Sends a 402 Payment Required response with price and server identity headers.
+ */
+export function send402(res, serverIdentityKey, sats) {
+    res.set({
+        [HEADERS.SATS]: String(sats),
+        [HEADERS.SERVER]: serverIdentityKey
+    });
+    res.status(402).end();
+}
+/**
+ * Validates payment headers on an incoming request.
+ * Returns a PaymentResult if the payment is valid, or null if the request should be rejected.
+ */
+export async function validatePayment(req, wallet, paymentWindowMs = DEFAULT_PAYMENT_WINDOW_MS) {
+    const h = (name) => {
+        const v = req.headers[name];
+        return Array.isArray(v) ? v[0] : v;
+    };
+    const sender = h(HEADERS.SENDER);
+    const beef = h(HEADERS.BEEF);
+    const nonce = h(HEADERS.NONCE);
+    const time = h(HEADERS.TIME);
+    const vout = h(HEADERS.VOUT);
+    if (!sender || !beef || !nonce || !time || !vout)
+        return null;
+    // Validate timestamp freshness
+    const timestamp = Number(time);
+    if (isNaN(timestamp) || Math.abs(Date.now() - timestamp) > paymentWindowMs)
+        return null;
+    const beefArr = Utils.toArray(beef, 'base64');
+    Beef.fromBinary(beefArr); // validates structure
+    const result = await wallet.internalizeAction({
+        tx: beefArr,
+        outputs: [{
+                outputIndex: Number.parseInt(vout),
+                protocol: 'wallet payment',
+                paymentRemittance: {
+                    derivationPrefix: nonce,
+                    derivationSuffix: Buffer.from(time).toString('base64'),
+                    senderIdentityKey: sender
+                }
+            }],
+        description: `Payment for ${req.path}`
+    });
+    // Reject replayed transactions
+    if (result.isMerge)
+        return null;
+    return {
+        accepted: true,
+        satoshisPaid: 0, // actual amount is validated by the wallet during internalization
+        senderIdentityKey: sender
+    };
+}
+/**
+ * Creates an Express-compatible middleware function for BRC-121 payments.
+ *
+ * Usage:
+ * ```ts
+ * import { createPaymentMiddleware } from '@bsv/402-pay/server'
+ *
+ * app.use('/articles/:slug', createPaymentMiddleware({
+ *   wallet,
+ *   calculatePrice: (path) => 100
+ * }))
+ * ```
+ */
+export function createPaymentMiddleware(options) {
+    const { wallet, calculatePrice, paymentWindowMs } = options;
+    let identityKey = '';
+    return async (req, res, next) => {
+        try {
+            if (!identityKey) {
+                const { publicKey } = await wallet.getPublicKey({ identityKey: true });
+                identityKey = publicKey;
+            }
+            const price = calculatePrice(req.path);
+            if (!price)
+                return next();
+            const hasPayment = req.headers[HEADERS.BEEF];
+            if (!hasPayment) {
+                return send402(res, identityKey, price);
+            }
+            const result = await validatePayment(req, wallet, paymentWindowMs);
+            if (!result) {
+                return send402(res, identityKey, price);
+            }
+            req.payment = { ...result, satoshisPaid: price };
+            next();
+        }
+        catch {
+            if (!identityKey) {
+                res.status(500).end();
+            }
+            else {
+                const price = calculatePrice(req.path) ?? 100;
+                send402(res, identityKey, price);
+            }
+        }
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@bsv/402-pay",
+  "version": "0.1.0",
+  "description": "BRC-121 Simple 402 Payments — server middleware and client for BSV micropayments over HTTP",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "bsv",
+    "402",
+    "payment",
+    "micropayments",
+    "brc-121",
+    "middleware"
+  ],
+  "author": "Deggen <d.kellenschwiler@bsvassociation.org>",
+  "license": "SEE LICENSE IN LICENSE",
+  "peerDependencies": {
+    "@bsv/sdk": ">=2.0.0"
+  },
+  "devDependencies": {
+    "@bsv/sdk": "^2.0.13",
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  }
+}