Harden and standardize Auth and Payment Express middleware (#361)

* Harden and standardize Express middleware packages

* Resolve Sonar findings

* Raise middleware patch coverage

* Cover middleware security branches

Author: ty-everett

docs/architecture/layers.md

@@ -2,12 +2,12 @@
 id: architecture-layers
 title: Stack Layers
 kind: meta
-version: "n/a"
-last_updated: "2026-05-01"
-last_verified: "2026-05-01"
+version: 'n/a'
+last_updated: '2026-05-01'
+last_verified: '2026-05-01'
 review_cadence_days: 30
 status: stable
-tags: ["architecture", "layers"]
+tags: ['architecture', 'layers']
 ---
 
 # Stack Layers
@@ -20,14 +20,14 @@ The stack is organized in three primary layers with supporting components that c
 
 These packages are not a fourth vertical layer. They sit alongside the main stack and usually connect through the BRC-100 wallet interface, `@bsv/sdk` primitives, or direct service APIs.
 
-| Capability | Packages | What it provides | Connects through |
-|------------|----------|------------------|------------------|
-| Data overlays | @bsv/overlay, @bsv/overlay-express, @bsv/overlay-topics | Topic managers, lookup services, SHIP/SLAP discovery, and shared on-chain context | `@bsv/sdk` transactions, overlay services |
-| P2P messaging and payments | @bsv/message-box-client, @bsv/authsocket, @bsv/paymail | Store-and-forward encrypted messages, live authenticated channels, BRC-29 payment derivation | BRC-100 wallet, BRC-103/104 auth |
-| Identity | @bsv/auth-express-middleware, @bsv/authsocket | BRC-31 HTTP handshake and peer identity framework | BRC-100 wallet, BRC-103/104 peer framework |
-| Monetization | @bsv/402-pay, @bsv/payment-express-middleware | HTTP 402 payment-gated APIs and micropayment middleware | BRC-100 wallet, BRC-121 HTTP 402 |
-| Tokens | @bsv/btms, @bsv/btms-permission-module | Token metadata, wallet permission display context, and BRC-48 PushDrop flows | BRC-100 wallet, overlay topics |
-| Storage | @bsv/overlay-topics, UHRP | Universal Hash Resolution for content-addressed files | UHRP servers, BRC-26 |
+| Capability                 | Packages                                                | What it provides                                                                             | Connects through                                                               |
+| -------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Data overlays              | @bsv/overlay, @bsv/overlay-express, @bsv/overlay-topics | Topic managers, lookup services, SHIP/SLAP discovery, and shared on-chain context            | `@bsv/sdk` transactions, overlay services                                      |
+| P2P messaging and payments | @bsv/message-box-client, @bsv/authsocket, @bsv/paymail  | Store-and-forward encrypted messages, live authenticated channels, BRC-29 payment derivation | BRC-100 wallet, BRC-103/104 auth                                               |
+| Identity                   | @bsv/auth-express-middleware, @bsv/authsocket           | BRC-31 HTTP handshake and peer identity framework                                            | BRC-100 wallet, BRC-103/104 peer framework                                     |
+| Monetization               | @bsv/402-pay, @bsv/payment-express-middleware           | BRC-121 HTTP 402 plus the distinct legacy authenticated payment flow                         | BRC-100 wallet; BRC-121 for `402-pay`; BRC-103/104 + BRC-29 for PaymentExpress |
+| Tokens                     | @bsv/btms, @bsv/btms-permission-module                  | Token metadata, wallet permission display context, and BRC-48 PushDrop flows                 | BRC-100 wallet, overlay topics                                                 |
+| Storage                    | @bsv/overlay-topics, UHRP                               | Universal Hash Resolution for content-addressed files                                        | UHRP servers, BRC-26                                                           |
 
 ## Foundation: @bsv/sdk
 
@@ -57,17 +57,17 @@ Any BRC-100-compliant wallet can be swapped below this boundary without changing
 
 `@bsv/wallet-toolbox` is not a single monolithic wallet. It is a set of composable modules:
 
-| Module | Role |
-|--------|------|
-| `WalletStorageManager` | Orchestrates persistence providers (active + backup + incremental sync) |
-| `KnexWalletStorage` | SQL persistence (SQLite, MySQL, PostgreSQL) |
-| `IndexedDBWalletStorage` | Browser persistence |
-| `RemoteWalletStorage` | Remote storage over HTTPS (for relay setups) |
-| `Monitor` | Background daemon: confirms transactions, acquires Merkle proofs, rebroadcasts stalled txs |
-| `PrivilegedKeyManager` | Handles the privileged-mode keyring for identity operations |
-| `ShamirWalletManager` | Shamir secret sharing for key backup |
-| `WalletSigner` | Bridges BRC-100 `signAction` to `@bsv/sdk` signing internals |
-| `Services` | Container wiring ARC, Chaintracks, WhatsOnChain |
+| Module                   | Role                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------------ |
+| `WalletStorageManager`   | Orchestrates persistence providers (active + backup + incremental sync)                    |
+| `KnexWalletStorage`      | SQL persistence (SQLite, MySQL, PostgreSQL)                                                |
+| `IndexedDBWalletStorage` | Browser persistence                                                                        |
+| `RemoteWalletStorage`    | Remote storage over HTTPS (for relay setups)                                               |
+| `Monitor`                | Background daemon: confirms transactions, acquires Merkle proofs, rebroadcasts stalled txs |
+| `PrivilegedKeyManager`   | Handles the privileged-mode keyring for identity operations                                |
+| `ShamirWalletManager`    | Shamir secret sharing for key backup                                                       |
+| `WalletSigner`           | Bridges BRC-100 `signAction` to `@bsv/sdk` signing internals                               |
+| `Services`               | Container wiring ARC, Chaintracks, WhatsOnChain                                            |
 
 Wallet builders compose these into a BRC-100 `Wallet`. The resulting object is the same interface that `@bsv/simple` and other app-layer packages use.
 

docs/guides/http-402-payments.md

@@ -1,10 +1,10 @@
 ---
 id: guide-http-402
-title: "HTTP 402 Payment Gating"
+title: 'HTTP 402 Payment Gating'
 kind: guide
-version: "1.0.1"
-last_updated: "2026-07-26"
-last_verified: "2026-07-26"
+version: '1.0.1'
+last_updated: '2026-07-26'
+last_verified: '2026-07-26'
 review_cadence_days: 30
 status: stable
 tags: [guide, payments, http-402, brc-121, monetization]
@@ -20,6 +20,7 @@ tags: [guide, payments, http-402, brc-121, monetization]
 ## What you'll build
 
 A complete end-to-end payment system:
+
 - **Server**: Express middleware that gates endpoints by payment, validates transactions
 - **Client**: Auto-paying fetch wrapper that transparently handles 402 responses
 - **Flow**: Client requests resource → server responds 402 with payment details → client signs & pays → access granted
@@ -85,31 +86,31 @@ async function setupServer() {
     network: 'main',
     storageUrl: 'https://store-us-1.bsvb.tech'
   })
-  
+
   // 2. Create payment middleware
   const paymentMiddleware = createPaymentMiddleware({
     wallet,
-    calculatePrice: (path) => {
+    calculatePrice: path => {
       // Dynamic pricing by route
-      if (path === '/api/premium') return 1000  // 1000 satoshis
-      if (path === '/api/free') return 0        // Free
-      return 100  // Default 100 satoshis
+      if (path === '/api/premium') return 1000 // 1000 satoshis
+      if (path === '/api/free') return 0 // Free
+      return 100 // Default 100 satoshis
     }
   })
-  
+
   // 3. Build Express app
   const app = express()
   app.use(bodyParser.json())
   app.use(paymentMiddleware)
-  
+
   // 4. Define routes
   app.get('/api/free', (req, res) => {
     res.json({
       message: 'Free content',
       paid: false
     })
   })
-  
+
   app.get('/api/premium', (req, res) => {
     res.json({
       message: 'Premium content — paid!',
@@ -118,15 +119,15 @@ async function setupServer() {
       sender: req.payment?.senderIdentityKey
     })
   })
-  
+
   return app
 }
 
 // Start server
 async function main() {
   const app = await setupServer()
   const port = process.env.PORT || 3000
-  
+
   app.listen(port, () => {
     console.log(`Payment server running on http://localhost:${port}`)
     console.log('- GET /api/free: No payment required')
@@ -138,6 +139,7 @@ main().catch(console.error)
 ```
 
 The middleware chain:
+
 1. **Payment middleware** checks if payment is required and validates provided payment headers
 2. **Route handler** receives the request only if payment was accepted or the route is free
 
@@ -146,6 +148,7 @@ The middleware chain:
 When client requests a paid endpoint without payment, the server responds with 402 and payment details.
 
 The payment middleware automatically:
+
 - Calculates required satoshis via `calculatePrice()`
 - Returns 402 status if unpaid
 - Includes headers:
@@ -166,18 +169,19 @@ dotenv.config()
 export async function setupPaymentClient() {
   // Initialize wallet for signing payments
   const wallet = new WalletClient()
-  
+
   // Create a fetch wrapper that auto-handles 402
   const fetch402 = create402Fetch({
     wallet,
-    cacheTimeoutMs: 30 * 60 * 1000  // Cache paid content for 30 minutes
+    cacheTimeoutMs: 30 * 60 * 1000 // Cache paid content for 30 minutes
   })
-  
+
   return fetch402
 }
 ```
 
 `create402Fetch()` returns a fetch-compatible function that:
+
 - Catches 402 responses
 - Signs a payment transaction
 - Retries with payment headers
@@ -191,7 +195,7 @@ Create `requests.ts` in client:
 export async function accessFreeContent(fetch402: any) {
   const response = await fetch402('http://localhost:3000/api/free')
   const data = await response.json()
-  
+
   console.log('Free content:', data)
   return data
 }
@@ -200,7 +204,7 @@ export async function accessPremiumContent(fetch402: any) {
   // Automatically handles 402 and pays
   const response = await fetch402('http://localhost:3000/api/premium')
   const data = await response.json()
-  
+
   console.log('Premium content:', data)
   return data
 }
@@ -213,6 +217,7 @@ export async function clearPaymentCache(fetch402: any) {
 ```
 
 When client calls `fetch402('/api/premium')`:
+
 1. Sends request (no payment)
 2. Receives 402 with `x-bsv-sats: 1000` and `x-bsv-server`
 3. Generates a fresh nonce and timestamp, then derives the payment address with BRC-29
@@ -235,20 +240,16 @@ export async function manualPayment(
   serverIdentityKey: string
 ) {
   // Build payment headers manually
-  const headers = await constructPaymentHeaders(
-    wallet,
-    serverUrl,
-    satoshis,
-    serverIdentityKey
-  )
-  
+  const headers = await constructPaymentHeaders(wallet, serverUrl, satoshis, serverIdentityKey)
+
   // Use with custom fetch
   const response = await fetch(serverUrl, { headers })
   return response
 }
 ```
 
 Manual header construction gives you:
+
 - `x-bsv-beef`: Base64-encoded transaction proof
 - `x-bsv-sender`: Your identity public key
 - `x-bsv-nonce`: Derivation prefix (random 8 bytes)
@@ -272,35 +273,35 @@ async function main() {
     network: 'main',
     storageUrl: 'https://store-us-1.bsvb.tech'
   })
-  
+
   // Setup middleware
   const paymentMiddleware = createPaymentMiddleware({
     wallet,
-    calculatePrice: (path) => {
+    calculatePrice: path => {
       if (path === '/api/premium') return 1000
       if (path === '/api/free') return 0
       return 100
     }
   })
-  
+
   // Create app
   const app = express()
   app.use(bodyParser.json())
   app.use(paymentMiddleware)
-  
+
   // Routes
   app.get('/api/free', (req, res) => {
     res.json({ message: 'Free content', paid: false })
   })
-  
+
   app.get('/api/premium', (req, res) => {
     res.json({
       message: 'Premium content',
       paid: true,
       satoshisPaid: req.payment?.satoshisPaid || 0
     })
   })
-  
+
   // Start
   app.listen(3000, () => {
     console.log('Server on http://localhost:3000')
@@ -319,23 +320,23 @@ import { WalletClient } from '@bsv/sdk'
 async function main() {
   // Setup wallet
   const wallet = new WalletClient()
-  
+
   // Create auto-paying fetch
   const fetch402 = create402Fetch({
     wallet,
     cacheTimeoutMs: 30 * 60 * 1000
   })
-  
+
   console.log('Accessing free content...')
   let response = await fetch402('http://localhost:3000/api/free')
   let data = await response.json()
   console.log('Free:', data)
-  
+
   console.log('\nAccessing premium content (will auto-pay 1000 sats)...')
   response = await fetch402('http://localhost:3000/api/premium')
   data = await response.json()
   console.log('Premium:', data)
-  
+
   console.log('\nAccessing premium again (cached, no new payment)...')
   response = await fetch402('http://localhost:3000/api/premium')
   data = await response.json()
@@ -378,7 +379,11 @@ npx ts-node main.ts
 → If cache timeout is very long, client may use stale payments for different resources. Use moderate timeout (30 min is safe)
 
 **"Replay protection"**
-→ Server wallet rejects duplicate payment internalization. Each payment must use a fresh nonce and transaction.
+→ For `@bsv/402-pay`, freshness fields bind the proof but the wallet must also
+avoid newly accepting the same transaction twice. For
+`@bsv/payment-express-middleware`, inject a durable atomic
+transaction-ID replay store in multi-process deployments; its derivation
+prefix is not a single-use replay database.
 
 ## What to read next