javascript-solid-server 0.0.100 → 0.0.102

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: **289 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.102",
   "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,297 @@
+/**
+ * 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, verifyMrc20Anchor, jcs } from '../mrc20.js';
+import fs from 'fs-extra';
+import path from 'path';
+
+const DEFAULT_COST = 1; // satoshis per request
+
+// --- Replay protection ---
+const replayFile = () => path.join(process.env.DATA_ROOT || './data', '.well-known/webledgers/replay.json');
+
+async function loadReplaySet() {
+  try {
+    const data = await fs.readFile(replayFile(), 'utf8');
+    return new Set(JSON.parse(data));
+  } catch { return new Set(); }
+}
+
+async function saveReplaySet(set) {
+  await fs.ensureDir(path.dirname(replayFile()));
+  await fs.writeFile(replayFile(), JSON.stringify([...set]));
+}
+
+async function checkAndRecordState(stateHash) {
+  const seen = await loadReplaySet();
+  if (seen.has(stateHash)) return false; // replay!
+  seen.add(stateHash);
+  await saveReplaySet(seen);
+  return true;
+}
+
+// --- 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, anchor: obj.anchor };
+  }
+  // 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, anchor: obj.anchor };
+  }
+  // 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)'
+          });
+        }
+
+        // Replay protection: reject duplicate state hashes
+        const stateHash = jcs(deposit.state);
+        const isNew = await checkAndRecordState(stateHash);
+        if (!isNew) {
+          return reply.code(400).send({ error: 'Replay: this state has already been used for a deposit' });
+        }
+
+        let result;
+
+        // Anchor verification (if anchor data provided)
+        if (deposit.anchor && deposit.anchor.pubkey && deposit.anchor.stateStrings) {
+          result = await verifyMrc20Anchor({
+            state: deposit.state,
+            prevState: deposit.prevState,
+            toAddress: payAddress,
+            pubkey: deposit.anchor.pubkey,
+            stateStrings: deposit.anchor.stateStrings,
+            mempoolUrl,
+            network: deposit.anchor.network || 'testnet4'
+          });
+        } else {
+          // Fallback: verify chain integrity only (no anchor check)
+          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',
+          ...(result.address ? { anchor: result.address } : {})
+        });
+      }
+
+      // --- 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
+  };
+}