javascript-solid-server 0.0.100 → 0.0.101

package/LICENSE

@@ -1,6 +1,7 @@
                     GNU AFFERO GENERAL PUBLIC LICENSE
                        Version 3, 19 November 2007
 
+ Copyright (C) 2025-2026 Melvin Carvalho
  Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.

package/README.md

@@ -46,6 +46,7 @@ A minimal, fast, JSON-LD native Solid server.
 - **Nostr Relay** - Integrated NIP-01/NIP-11/NIP-16 relay on the same port (`wss://your.pod/relay`)
 - **Invite-Only Registration** - CLI-managed invite codes for controlled signups
 - **Storage Quotas** - Per-user storage limits with CLI management
+- **HTTP 402 Paid Access** - Monetize API endpoints with per-request sat payments (`--pay`)
 - **Security** - Blocks access to dotfiles (`.git/`, `.env`, etc.) except Solid-specific ones
 
 ### HTTP Methods
@@ -151,6 +152,10 @@ jss --help             # Show help
 | `--public` | Allow unauthenticated access (skip WAC) | false |
 | `--read-only` | Disable PUT/DELETE/PATCH methods | false |
 | `--live-reload` | Auto-refresh browser on file changes | false |
+| `--pay` | Enable HTTP 402 paid access for /pay/* | false |
+| `--pay-cost <n>` | Cost per request in satoshis | 1 |
+| `--pay-mempool-url <url>` | Mempool API URL for deposit verification | (testnet4) |
+| `--pay-address <addr>` | Address for receiving deposits | - |
 | `--mongo` | Enable MongoDB-backed /db/ route | false |
 | `--mongo-url <url>` | MongoDB connection URL | mongodb://localhost:27017 |
 | `--mongo-database <name>` | MongoDB database name | solid |
@@ -179,6 +184,9 @@ export JSS_PUBLIC=true
 export JSS_READ_ONLY=true
 export JSS_LIVE_RELOAD=true
 export JSS_SOLIDOS_UI=true
+export JSS_PAY=true
+export JSS_PAY_COST=10
+export JSS_PAY_ADDRESS=your-address
 export JSS_MONGO=true
 export JSS_MONGO_URL=mongodb://localhost:27017
 export JSS_MONGO_DATABASE=solid
@@ -810,6 +818,47 @@ curl -X DELETE http://localhost:3000/db/alice/notes/1 \
 
 Supported formats: `50MB`, `1GB`, `500KB`, `1TB`
 
+## HTTP 402 Paid Access
+
+Monetize API endpoints with per-request satoshi payments. Resources under `/pay/*` require NIP-98 authentication and a positive balance.
+
+```bash
+jss start --pay --pay-cost 10 --pay-address your-address
+```
+
+### Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/pay/.balance` | Check your balance (NIP-98 auth) |
+| POST | `/pay/.deposit` | Deposit sats via TXO URI (`txid:vout`) |
+| GET | `/pay/*` | Paid resource access (deducts balance) |
+
+### How It Works
+
+1. Authenticate with NIP-98 (Nostr HTTP Auth)
+2. Check balance at `/pay/.balance`
+3. Deposit sats by POSTing a TXO URI to `/pay/.deposit`
+4. Access paid resources — each request deducts the configured cost
+5. Balance tracked in a [Web Ledger](https://webledgers.org/) at `/.well-known/webledgers/webledgers.json`
+
+### Example
+
+```bash
+# Check balance
+curl -H "Authorization: Nostr <base64-event>" http://localhost:3000/pay/.balance
+
+# Deposit (post a confirmed transaction output)
+curl -X POST -H "Authorization: Nostr <base64-event>" \
+  http://localhost:3000/pay/.deposit \
+  -d "txid:vout"
+
+# Access paid resource
+curl -H "Authorization: Nostr <base64-event>" http://localhost:3000/pay/my-resource
+```
+
+Deposit verification uses the mempool API (default: testnet4). The `X-Balance` and `X-Cost` headers are returned on successful paid requests.
+
 ## Authentication
 
 ### Simple Tokens (Development)
@@ -1113,7 +1162,7 @@ npm run benchmark
 npm test
 ```
 
-Currently passing: **229 tests** (including 27 conformance tests)
+Currently passing: **279 tests** (including 27 conformance tests)
 
 ### Conformance Test Harness (CTH)
 
@@ -1155,7 +1204,8 @@ src/
 ├── handlers/
 │   ├── resource.js       # GET, PUT, DELETE, HEAD, PATCH
 │   ├── container.js      # POST, pod creation
-│   └── git.js            # Git HTTP backend
+│   ├── git.js            # Git HTTP backend
+│   └── pay.js            # HTTP 402 paid access
 ├── storage/
 │   ├── filesystem.js     # File operations
 │   └── quota.js          # Storage quota management
@@ -1203,6 +1253,8 @@ src/
 │       ├── collections.js # Followers/following
 │       ├── mastodon.js  # Mastodon API (apps, instance, verify_credentials)
 │       └── oauth.js     # OAuth 2.0 authorize/token flow
+├── webledger.js          # Web Ledger balance tracking (webledgers.org)
+├── mrc20.js              # State chain verification
 ├── remotestorage.js      # remoteStorage protocol (draft-dejong-remotestorage-22)
 ├── rdf/
 │   ├── turtle.js         # Turtle <-> JSON-LD

package/bin/jss.js

@@ -80,6 +80,11 @@ program
   .option('--public', 'Allow unauthenticated access (skip WAC, open read/write)')
   .option('--read-only', 'Disable PUT/DELETE/PATCH methods (read-only mode)')
   .option('--live-reload', 'Inject live reload script into HTML (auto-refresh on changes)')
+  .option('--pay', 'Enable HTTP 402 paid access for /pay/* routes')
+  .option('--no-pay', 'Disable HTTP 402 paid access')
+  .option('--pay-cost <n>', 'Cost per request in satoshis (default: 1)', parseInt)
+  .option('--pay-mempool-url <url>', 'Mempool API URL for deposit verification')
+  .option('--pay-address <addr>', 'Address for receiving deposits')
   .option('--mongo', 'Enable MongoDB-backed /db/ route')
   .option('--no-mongo', 'Disable MongoDB-backed /db/ route')
   .option('--mongo-url <url>', 'MongoDB connection URL (default: mongodb://localhost:27017)')
@@ -146,6 +151,10 @@ program
         public: config.public,
         readOnly: config.readOnly,
         liveReload: config.liveReload,
+        pay: config.pay,
+        payCost: config.payCost,
+        payMempoolUrl: config.payMempoolUrl,
+        payAddress: config.payAddress,
         mongo: config.mongo,
         mongoUrl: config.mongoUrl,
         mongoDatabase: config.mongoDatabase,
@@ -184,6 +193,7 @@ program
           }
           console.log('     Do not expose to the internet!');
         }
+        if (config.pay) console.log(`  Pay: ${config.payCost} sat/req (402 enabled)`);
         if (config.mongo) console.log(`  MongoDB: ${config.mongoUrl} (${config.mongoDatabase})`);
         if (config.readOnly) console.log('  Read-only: enabled (PUT/DELETE/PATCH disabled)');
         console.log('\n  Press Ctrl+C to stop\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "javascript-solid-server",
-  "version": "0.0.100",
+  "version": "0.0.101",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",
@@ -19,6 +19,7 @@
     "start": "node bin/jss.js start",
     "dev": "node --watch bin/jss.js start",
     "test": "node --test --test-concurrency=1 'test/*.test.js'",
+    "test:live-reload": "node test/live-reload.standalone.js",
     "test:cth": "node scripts/test-cth-compat.js",
     "benchmark": "node benchmark.js"
   },

package/src/config.js

@@ -83,6 +83,12 @@ export const defaults = {
   // Live reload - inject script to auto-refresh browser on file changes
   liveReload: false,
 
+  // HTTP 402 paid access
+  pay: false,
+  payCost: 1,
+  payMempoolUrl: 'https://mempool.space/testnet4',
+  payAddress: null,
+
   // MongoDB-backed /db/ route
   mongo: false,
   mongoUrl: 'mongodb://localhost:27017',
@@ -138,6 +144,10 @@ const envMap = {
   JSS_PUBLIC: 'public',
   JSS_READ_ONLY: 'readOnly',
   JSS_LIVE_RELOAD: 'liveReload',
+  JSS_PAY: 'pay',
+  JSS_PAY_COST: 'payCost',
+  JSS_PAY_MEMPOOL_URL: 'payMempoolUrl',
+  JSS_PAY_ADDRESS: 'payAddress',
   JSS_MONGO: 'mongo',
   JSS_MONGO_URL: 'mongoUrl',
   JSS_MONGO_DATABASE: 'mongoDatabase',
@@ -167,7 +177,7 @@ function parseEnvValue(value, key) {
   if (value.toLowerCase() === 'false') return false;
 
   // Numeric values for known numeric keys
-  if ((key === 'port' || key === 'nostrMaxEvents') && !isNaN(value)) {
+  if ((key === 'port' || key === 'nostrMaxEvents' || key === 'payCost') && !isNaN(value)) {
     return parseInt(value, 10);
   }
 
@@ -305,6 +315,7 @@ export function printConfig(config) {
   console.log(`  Subdomains:    ${config.subdomains ? (config.baseDomain || 'enabled') : 'disabled'}`);
   console.log(`  Mashlib:       ${config.mashlibModule ? `module (${config.mashlibModule})` : config.mashlibCdn ? `CDN v${config.mashlibVersion}` : config.mashlib ? 'local' : 'disabled'}`);
   console.log(`  SolidOS UI:    ${config.solidosUi ? 'enabled' : 'disabled'}`);
+  if (config.pay) console.log(`  Pay:           ${config.payCost} sat/req`);
   if (config.mongo) console.log(`  MongoDB:       ${config.mongoUrl} (${config.mongoDatabase})`);
   console.log('─'.repeat(40));
 }

package/src/handlers/pay.js

@@ -0,0 +1,248 @@
+/**
+ * HTTP 402 Payment Required middleware
+ *
+ * Enables paid access to resources under /pay/* prefix.
+ * Authentication via NIP-98. Balance tracking via Web Ledgers spec.
+ *
+ * Routes:
+ *   GET  /pay/.balance  — check your balance
+ *   POST /pay/.deposit  — deposit sats (TXO URI) or tokens (MRC20 state proof)
+ *   GET  /pay/*         — paid resource access (requires balance >= cost)
+ *   PUT  /pay/*         — upload resources (standard auth)
+ *
+ * Ledger: /.well-known/webledgers/webledgers.json (webledgers.org spec)
+ *
+ * References:
+ *   - Web Ledgers spec: https://webledgers.org/
+ *   - NIP-98 HTTP Auth: https://nips.nostr.com/98
+ *   - TXO URI: https://www.npmjs.com/package/txo_parser
+ *   - MRC20 profile: https://blocktrails.org/
+ */
+
+import { getNostrPubkey, pubkeyToDidNostr } from '../auth/nostr.js';
+import { readLedger, writeLedger, getBalance, credit, debit } from '../webledger.js';
+import { verifyMrc20Deposit } from '../mrc20.js';
+
+const DEFAULT_COST = 1; // satoshis per request
+
+// --- Deposit verification via mempool API ---
+
+async function verifySatsDeposit(txoUri, mempoolUrl) {
+  const match = txoUri.match(/([0-9a-f]{64}):(\d+)/i);
+  if (!match) {
+    return { valid: false, amount: 0, error: 'Invalid TXO URI format (expected txid:vout)' };
+  }
+  const [, txid, voutStr] = match;
+  const vout = parseInt(voutStr, 10);
+
+  try {
+    const resp = await fetch(`${mempoolUrl}/api/tx/${txid}`);
+    if (!resp.ok) return { valid: false, amount: 0, error: 'Transaction not found' };
+    const tx = await resp.json();
+    const output = tx.vout?.[vout];
+    if (!output) return { valid: false, amount: 0, error: `Output index ${vout} not found` };
+    return { valid: true, amount: output.value };
+  } catch (err) {
+    return { valid: false, amount: 0, error: `Mempool API error: ${err.message}` };
+  }
+}
+
+/**
+ * Parse deposit request body — returns either a sats TXO URI or MRC20 state proof
+ * @param {*} body - Request body (Buffer, string, or parsed object)
+ * @returns {{type: 'sats', txo: string} | {type: 'mrc20', state: object, prevState: object} | {type: 'unknown'}}
+ */
+function parseDepositBody(body) {
+  // Buffer → string first
+  if (Buffer.isBuffer(body)) {
+    const str = body.toString('utf8').trim();
+    // Try JSON parse
+    try {
+      const obj = JSON.parse(str);
+      return classifyDepositObject(obj);
+    } catch {
+      // Not JSON — treat as TXO URI string
+      return { type: 'sats', txo: str };
+    }
+  }
+
+  // Already parsed object
+  if (body && typeof body === 'object') {
+    return classifyDepositObject(body);
+  }
+
+  // String
+  if (typeof body === 'string') {
+    const trimmed = body.trim();
+    try {
+      const obj = JSON.parse(trimmed);
+      return classifyDepositObject(obj);
+    } catch {
+      return { type: 'sats', txo: trimmed };
+    }
+  }
+
+  return { type: 'unknown' };
+}
+
+function classifyDepositObject(obj) {
+  // Explicit type field
+  if (obj.type === 'mrc20' && obj.state && obj.prevState) {
+    return { type: 'mrc20', state: obj.state, prevState: obj.prevState };
+  }
+  // Auto-detect: if it has state + prevState with MRC20 profile
+  if (obj.state?.profile === 'mono.mrc20.v0.1' && obj.prevState) {
+    return { type: 'mrc20', state: obj.state, prevState: obj.prevState };
+  }
+  // Fall back to TXO URI in .txo field
+  if (obj.txo) {
+    return { type: 'sats', txo: obj.txo };
+  }
+  return { type: 'unknown' };
+}
+
+// --- Check if URL is a /pay/ route ---
+
+export function isPayRequest(url) {
+  const path = url.split('?')[0];
+  return path.startsWith('/pay/') || path === '/pay';
+}
+
+// --- preHandler hook for /pay/* routes ---
+
+/**
+ * Create pay preHandler hook
+ * @param {object} options
+ * @param {number} options.cost - Cost per request in satoshis (default 1)
+ * @param {string} options.mempoolUrl - Mempool API base URL
+ * @param {string} options.payAddress - Pod's MRC20 address for receiving token transfers
+ * @returns {function} Fastify preHandler hook
+ */
+export function createPayHandler(options = {}) {
+  const cost = options.cost ?? DEFAULT_COST;
+  const mempoolUrl = options.mempoolUrl ?? 'https://mempool.space/testnet4';
+  const payAddress = options.payAddress ?? null;
+
+  return async function payHandler(request, reply) {
+    const url = request.url.split('?')[0];
+    if (!isPayRequest(request.url)) return;
+
+    // --- GET /pay/.balance ---
+    if (url === '/pay/.balance' && request.method === 'GET') {
+      const pubkey = await getNostrPubkey(request);
+      if (!pubkey) {
+        return reply.code(401).send({ error: 'NIP-98 authentication required' });
+      }
+      const didUri = pubkeyToDidNostr(pubkey);
+      const ledger = await readLedger();
+      return reply.send({
+        did: didUri,
+        balance: getBalance(ledger, didUri),
+        cost,
+        unit: 'sat'
+      });
+    }
+
+    // --- POST /pay/.deposit ---
+    if (url === '/pay/.deposit' && request.method === 'POST') {
+      const pubkey = await getNostrPubkey(request);
+      if (!pubkey) {
+        return reply.code(401).send({ error: 'NIP-98 authentication required' });
+      }
+
+      const deposit = parseDepositBody(request.body);
+
+      // --- MRC20 token deposit ---
+      if (deposit.type === 'mrc20') {
+        if (!payAddress) {
+          return reply.code(400).send({
+            error: 'MRC20 deposits not configured (no payAddress set)'
+          });
+        }
+
+        const result = verifyMrc20Deposit({
+          state: deposit.state,
+          prevState: deposit.prevState,
+          toAddress: payAddress
+        });
+
+        if (!result.valid) {
+          return reply.code(400).send({ error: result.error });
+        }
+
+        const didUri = pubkeyToDidNostr(pubkey);
+        const ledger = await readLedger();
+        const newBalance = credit(ledger, didUri, result.amount);
+        await writeLedger(ledger);
+
+        return reply.send({
+          did: didUri,
+          deposited: result.amount,
+          ticker: result.ticker,
+          balance: newBalance,
+          unit: 'token'
+        });
+      }
+
+      // --- Sats deposit (TXO URI) ---
+      if (deposit.type === 'sats') {
+        const result = await verifySatsDeposit(deposit.txo, mempoolUrl);
+        if (!result.valid) {
+          return reply.code(400).send({ error: result.error });
+        }
+
+        const didUri = pubkeyToDidNostr(pubkey);
+        const ledger = await readLedger();
+        const newBalance = credit(ledger, didUri, result.amount);
+        await writeLedger(ledger);
+
+        return reply.send({
+          did: didUri,
+          deposited: result.amount,
+          balance: newBalance,
+          unit: 'sat'
+        });
+      }
+
+      return reply.code(400).send({
+        error: 'Invalid deposit format. Send a TXO URI string or MRC20 state proof.',
+        formats: {
+          sats: 'POST body: "<txid>:<vout>" or {"txo": "<txid>:<vout>"}',
+          mrc20: 'POST body: {"type": "mrc20", "state": {...}, "prevState": {...}}'
+        }
+      });
+    }
+
+    // --- GET/HEAD /pay/* — paid resource access ---
+    if (request.method === 'GET' || request.method === 'HEAD') {
+      const pubkey = await getNostrPubkey(request);
+      if (!pubkey) {
+        return reply.code(401).send({
+          error: 'NIP-98 authentication required',
+          deposit: '/pay/.deposit'
+        });
+      }
+
+      const didUri = pubkeyToDidNostr(pubkey);
+      const ledger = await readLedger();
+      const { success, balance } = debit(ledger, didUri, cost);
+
+      if (!success) {
+        return reply.code(402).send({
+          error: 'Payment Required',
+          balance,
+          cost,
+          unit: 'sat',
+          deposit: '/pay/.deposit'
+        });
+      }
+
+      await writeLedger(ledger);
+      reply.header('X-Balance', String(balance));
+      reply.header('X-Cost', String(cost));
+      return; // continue to normal resource handler
+    }
+
+    // PUT/DELETE/POST — continue to normal WAC auth + resource handler
+  };
+}

package/src/mrc20.js

@@ -0,0 +1,146 @@
+/**
+ * MRC20 Token Verification
+ *
+ * Verifies MRC20 state chain integrity and extracts transfer operations.
+ * Used by the pay middleware to accept token deposits.
+ *
+ * MRC20 profile: mono.mrc20.v0.1
+ * State chain: each state links to previous via SHA-256 of JCS-encoded state.
+ *
+ * References:
+ *   - Blocktrails: https://blocktrails.org/
+ *   - JCS (RFC 8785): JSON Canonicalization Scheme
+ */
+
+import crypto from 'crypto';
+
+const MRC20_PROFILE = 'mono.mrc20.v0.1';
+const TRANSFER_OP = 'urn:mono:op:transfer';
+
+/**
+ * JSON Canonicalization Scheme (RFC 8785)
+ * Produces deterministic JSON — sorted keys, no whitespace.
+ * @param {*} obj
+ * @returns {string}
+ */
+export function jcs(obj) {
+  if (obj === null || typeof obj !== 'object') return JSON.stringify(obj);
+  if (Array.isArray(obj)) return '[' + obj.map(v => jcs(v)).join(',') + ']';
+  const keys = Object.keys(obj).sort();
+  return '{' + keys.map(k => JSON.stringify(k) + ':' + jcs(obj[k])).join(',') + '}';
+}
+
+/**
+ * SHA-256 hex digest of a string
+ * @param {string} str
+ * @returns {string} Hex hash
+ */
+export function sha256Hex(str) {
+  return crypto.createHash('sha256').update(str).digest('hex');
+}
+
+/**
+ * Verify state chain link: state.prev must equal SHA-256(JCS(prevState))
+ * @param {object} state - Current state
+ * @param {object} prevState - Previous state
+ * @returns {{valid: boolean, error?: string}}
+ */
+export function verifyStateLink(state, prevState) {
+  if (!state || !prevState) {
+    return { valid: false, error: 'Missing state or prevState' };
+  }
+
+  const expectedPrev = sha256Hex(jcs(prevState));
+  if (state.prev !== expectedPrev) {
+    return { valid: false, error: `State chain break: expected prev ${expectedPrev}, got ${state.prev}` };
+  }
+
+  // Verify sequence number
+  if (typeof state.seq === 'number' && typeof prevState.seq === 'number') {
+    if (state.seq !== prevState.seq + 1) {
+      return { valid: false, error: `Sequence mismatch: expected ${prevState.seq + 1}, got ${state.seq}` };
+    }
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate that a state object is a valid MRC20 state
+ * @param {object} state
+ * @returns {{valid: boolean, error?: string}}
+ */
+export function validateMrc20State(state) {
+  if (!state || typeof state !== 'object') {
+    return { valid: false, error: 'State must be an object' };
+  }
+  if (state.profile !== MRC20_PROFILE) {
+    return { valid: false, error: `Invalid profile: expected ${MRC20_PROFILE}, got ${state.profile}` };
+  }
+  if (!Array.isArray(state.ops)) {
+    return { valid: false, error: 'State must have ops array' };
+  }
+  if (typeof state.prev !== 'string') {
+    return { valid: false, error: 'State must have prev hash' };
+  }
+  return { valid: true };
+}
+
+/**
+ * Extract transfer operations targeting a specific address
+ * @param {object} state - MRC20 state
+ * @param {string} toAddress - Recipient address to filter by
+ * @returns {Array<{from: string, to: string, amt: number}>} Matching transfers
+ */
+export function extractTransfersTo(state, toAddress) {
+  if (!state.ops || !Array.isArray(state.ops)) return [];
+  return state.ops.filter(op =>
+    op.op === TRANSFER_OP && op.to === toAddress && typeof op.amt === 'number' && op.amt > 0
+  );
+}
+
+/**
+ * Get total amount transferred to an address in a state
+ * @param {object} state - MRC20 state
+ * @param {string} toAddress - Recipient address
+ * @returns {number} Total amount transferred
+ */
+export function totalTransferredTo(state, toAddress) {
+  const transfers = extractTransfersTo(state, toAddress);
+  return transfers.reduce((sum, op) => sum + op.amt, 0);
+}
+
+/**
+ * Verify an MRC20 deposit: validate state chain + extract transfer amount
+ * @param {object} params
+ * @param {object} params.state - New state containing transfer ops
+ * @param {object} params.prevState - Previous state (for chain verification)
+ * @param {string} params.toAddress - Pod's address to check transfers against
+ * @returns {{valid: boolean, amount: number, ticker?: string, error?: string}}
+ */
+export function verifyMrc20Deposit(params) {
+  const { state, prevState, toAddress } = params;
+
+  // Validate MRC20 format
+  const stateCheck = validateMrc20State(state);
+  if (!stateCheck.valid) return { valid: false, amount: 0, error: stateCheck.error };
+
+  const prevCheck = validateMrc20State(prevState);
+  if (!prevCheck.valid) return { valid: false, amount: 0, error: `prevState: ${prevCheck.error}` };
+
+  // Verify state chain link
+  const linkCheck = verifyStateLink(state, prevState);
+  if (!linkCheck.valid) return { valid: false, amount: 0, error: linkCheck.error };
+
+  // Extract transfers to pod
+  const amount = totalTransferredTo(state, toAddress);
+  if (amount <= 0) {
+    return { valid: false, amount: 0, error: `No transfers to ${toAddress} found in state ops` };
+  }
+
+  return {
+    valid: true,
+    amount,
+    ticker: state.ticker || 'UNKNOWN'
+  };
+}

package/src/server.js

@@ -14,6 +14,7 @@ import { idpPlugin } from './idp/index.js';
 import { isGitRequest, isGitWriteOperation, handleGit } from './handlers/git.js';
 import { AccessMode } from './wac/parser.js';
 import { registerNostrRelay } from './nostr/relay.js';
+import { createPayHandler, isPayRequest } from './handlers/pay.js';
 import { activityPubPlugin, getActorHandler } from './ap/index.js';
 import { remoteStoragePlugin } from './remotestorage.js';
 import { dbPlugin } from './db/index.js';
@@ -42,6 +43,10 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
  * @param {string} options.apSummary - ActivityPub bio/summary
  * @param {string} options.apNostrPubkey - Nostr pubkey for identity linking
  * @param {boolean} options.webidTls - Enable WebID-TLS client certificate auth (default false)
+ * @param {boolean} options.pay - Enable HTTP 402 paid /pay/* routes (default false)
+ * @param {number} options.payCost - Cost per request in satoshis (default 1)
+ * @param {string} options.payMempoolUrl - Mempool API base URL (default testnet4)
+ * @param {string} options.payAddress - Pod's MRC20 address for receiving token transfers
  */
 export function createServer(options = {}) {
   // Content negotiation is OFF by default - we're a JSON-LD native server
@@ -90,6 +95,11 @@ export function createServer(options = {}) {
   const mongoEnabled = options.mongo ?? false;
   const mongoUrl = options.mongoUrl ?? 'mongodb://localhost:27017';
   const mongoDatabase = options.mongoDatabase ?? 'solid';
+  // HTTP 402 paid /pay/ routes are OFF by default
+  const payEnabled = options.pay ?? false;
+  const payCost = options.payCost ?? 1;
+  const payMempoolUrl = options.payMempoolUrl ?? 'https://mempool.space/testnet4';
+  const payAddress = options.payAddress ?? null; // Pod's MRC20 address for token deposits
 
   // Set data root via environment variable if provided
   if (options.root) {
@@ -102,6 +112,8 @@ export function createServer(options = {}) {
     logger: loggerEnabled ? { level: options.logLevel || 'info' } : false,
     disableRequestLogging: true,
     trustProxy: true,
+    // Force close connections on server.close() (useful for tests with WebSockets)
+    forceCloseConnections: options.forceCloseConnections ?? false,
     // Handle raw body for non-JSON content
     bodyLimit: 10 * 1024 * 1024, // 10MB
     // Gracefully handle client TCP errors (ECONNRESET, EPIPE, etc.)
@@ -311,6 +323,11 @@ export function createServer(options = {}) {
       return;
     }
 
+    // Allow pay routes through when pay is enabled (.balance, .deposit)
+    if (payEnabled && isPayRequest(request.url)) {
+      return;
+    }
+
     const segments = request.url.split('/').map(s => s.split('?')[0]); // Remove query strings
     const hasForbiddenDotfile = segments.some(seg =>
       seg.startsWith('.') &&
@@ -355,6 +372,11 @@ export function createServer(options = {}) {
     });
   }
 
+  // HTTP 402 Payment Required handler for /pay/* routes
+  if (payEnabled) {
+    fastify.addHook('preHandler', createPayHandler({ cost: payCost, mempoolUrl: payMempoolUrl, payAddress }));
+  }
+
   // Authorization hook - check WAC permissions
   // Skip for pod creation endpoint (needs special handling)
   fastify.addHook('preHandler', async (request, reply) => {
@@ -378,6 +400,7 @@ export function createServer(options = {}) {
         (activitypubEnabled && apPaths.some(p => request.url === p || request.url.startsWith(p + '?'))) ||
         isProfileAP ||
         request.url.startsWith('/storage/') ||
+        (payEnabled && isPayRequest(request.url)) ||
         (mongoEnabled && (request.url === '/db' || request.url.startsWith('/db/'))) ||
         mashlibPaths.some(p => request.url === p || request.url.startsWith(p + '.'))) {
       return;