x402-rack 0.1.0

data/.claude/plans/20260326-rack-stack-architecture.md

@@ -0,0 +1,304 @@
+# Architecture: The Rack Stack for BSV HTTP Services
+
+## Overview
+
+HTTP services monetised with BSV require several orthogonal concerns to be handled: identity, payment, fee sponsorship, and settlement. These concerns compose naturally as a Rack middleware stack, where each layer handles one responsibility and passes context downstream.
+
+This plan defines the component parts and their boundaries. It is deliberately not concerned with implementation specifics — it maps the jigsaw pieces and how they fit together.
+
+## The Stack
+
+```
+┌─────────────────────────────────────────────┐
+│  TLS (transport security)                   │  Not our concern — handled by web server
+├─────────────────────────────────────────────┤
+│  BRC-104 Auth Middleware (optional)         │  Identity — who is this?
+├─────────────────────────────────────────────┤
+│  X402 Middleware (gatekeeper)               │  Payment gating — have they paid?
+├─────────────────────────────────────────────┤
+│  Application                                │  Business logic — serve the resource
+└─────────────────────────────────────────────┘
+
+         ┌──────────────┐
+         │   Gateways   │  Settlement — how do they pay?
+         └──────┬───────┘
+                │
+    ┌───────────┼───────────┐
+    │           │           │
+┌───┴────┐  ┌───┴────┐ ┌────┴────┐
+│ BSV    │  │  BSV   │ │ BRC-105 │  ... extensible
+│ Proof  │  │  Pay   │ │ Gateway │
+└───┬────┘  └───┬────┘ └────┬────┘
+    │           │           │
+    └───────────┼───────────┘
+                │
+         ┌──────┴───────┐
+         │  BSV Wallet  │  Server-side wallet (BRC-100 interface)
+         │  (bsv-wallet │  Manages keys, UTXOs, signing
+         │   gem)       │  via baskets: nonces, fees, revenue
+         └──────┬───────┘
+                │
+         ┌──────┴───────┐
+         │   bsv-sdk    │  Primitives — keys, txs, scripts, ARC
+         └──────────────┘
+```
+
+## Layer 1: Identity (BRC-103/104)
+
+**What**: Mutual authentication between client and server. Establishes who is making the request.
+
+**Rack middleware**: Verifies `x-bsv-auth-*` headers, validates BRC-103 signatures over the request (method, path, query, whitelisted headers, body). Places the authenticated identity into the Rack env.
+
+**Provides to downstream**: `env['brc103.identity_key']` (33-byte compressed public key), session nonces, certificate data.
+
+**Optional**: Not all payment flows require identity. Anonymous payments (merkleworks x402, BSV-pay) work without this layer. BRC-105 payments require it.
+
+**Not our gem**: This would be a separate gem (`brc104-rack` or similar). Our x402 middleware doesn't depend on it — it just benefits from it when present.
+
+## Layer 2: Payment Gating (X402 Middleware)
+
+**What**: The gatekeeper. Decides whether a request should be served based on payment status.
+
+**Responsibilities**:
+- Route matching — is this request to a protected endpoint?
+- Challenge issuance — poll gateways, return 402 with challenge headers
+- Proof dispatch — detect which proof header arrived, dispatch to the matching gateway
+- Access control — gateway says allow/deny, middleware serves or rejects
+
+**Does NOT do**:
+- Sign transactions
+- Hold private keys
+- Decode blockchain data
+- Talk to ARC or any network service
+- Know what chain or protocol is being used
+
+**Rack env it reads**: route configuration, gateway list. Optionally `env['brc103.identity_key']` (passes through to gateways that need it).
+
+**Rack env it sets**: settlement result (for downstream logging/receipt headers).
+
+**This is our gem**: `x402-rack`.
+
+## Layer 3: Settlement (Gateways)
+
+**What**: The bridge between HTTP and blockchain. Each gateway knows one settlement protocol.
+
+**Responsibilities**:
+- Build challenge data (headers + partial tx templates)
+- Verify and settle proofs/payments
+- Interact with external services (ARC, treasury, wallets)
+- Can hold keys and sign transactions
+
+**Gateway types identified so far**:
+
+### BSV PayGateway (our BSV-native scheme — Coinbase v2 headers)
+- **Challenge**: `PaymentRequired` JSON with BSV in `accepts` array + partial tx template (payment output only)
+- **Settlement**: verify tx structure, broadcast via ARC, return `Payment-Response`
+- **Headers**: `Payment-Required` / `Payment-Signature` / `Payment-Response`
+- **Needs**: ARC only
+- **Identity**: not required
+- **Ecosystem**: standard x402 v2 — interoperable with any Coinbase-compatible client
+
+### BSV ProofGateway (merkleworks x402)
+- **Challenge**: pre-signed partial tx template (nonce at input 0 with 0xC3, payment output at output 0) + merkleworks challenge JSON (binding, expiry)
+- **Settlement**: verify tx structure, check mempool via ARC
+- **Headers**: `X402-Challenge` / `X402-Proof`
+- **Needs**: treasury (nonce key) + ARC
+- **Identity**: not required
+- **Ecosystem**: merkleworks BSV-specific
+
+### BRC-105 Gateway (future)
+- **Challenge**: derivation prefix + satoshis required (multiple `x-bsv-payment-*` headers)
+- **Settlement**: verify derivation, validate tx via BRC-100 wallet (`internalizeAction`)
+- **Headers**: `x-bsv-payment-*` / `x-bsv-payment`
+- **Needs**: BRC-100 wallet
+- **Identity**: REQUIRED (reads `env['brc103.identity_key']` for derivation)
+- **Ecosystem**: BSV Association BRC standard
+
+## Server-Side Wallet (`bsv-wallet` gem)
+
+### One wallet, multiple roles
+
+The treasury, delegator, and payment receipt functions are not separate services — they are **roles** a single wallet plays, distinguished by which baskets and keys they use.
+
+| Role | Basket | Key | Operations |
+|------|--------|-----|------------|
+| Treasury | `x402-nonces` | Nonce key | `createAction` (mint nonces, sign templates), `listOutputs` |
+| Delegator | `x402-fees` | Fee key | `signAction` (sign fee inputs), `listOutputs` |
+| Payment receipt | `x402-revenue` | Payee key | `internalizeAction` (accept payments), `listOutputs` |
+
+### BRC-100 as the API boundary
+
+The wallet exposes a BRC-100 interface (or the subset we need). Gateways talk to the wallet exclusively through these methods. They never touch keys directly. The wallet is the security boundary.
+
+**BRC-100 methods we need** (subset of the full 28+ method spec):
+- `createAction` — construct and sign transactions (nonce minting, template signing)
+- `signAction` — sign previously created transactions (fee input signing)
+- `internalizeAction` — accept incoming transactions (payment receipt)
+- `listOutputs` — query UTXOs by basket (find nonces, fee UTXOs, revenue)
+- `getPublicKey` — derive keys (BRC-29 derivations for BRC-105, nonce keys)
+
+### Where it lives
+
+The `bsv-ruby-sdk` repo (`sgbett/bsv-ruby-sdk`) already has:
+- A monorepo pattern with multiple gemspecs (`bsv-sdk`, `bsv-attest`)
+- A basic wallet at `lib/bsv/wallet/wallet.rb` (single-key, UTXO funding + signing)
+- Full key management including BIP-32 HD derivation
+- Transaction construction with BIP-143 sighash (FORKID)
+- ARC provider
+- BEEF serialisation
+
+The `bsv-wallet` gem adds a third gemspec to this repo:
+- BRC-100 interface layer over the existing primitives
+- Basket-based UTXO tracking (nonces, fees, revenue)
+- Multi-key support
+- Builds on the existing `BSV::Wallet::Wallet` as the internal engine
+
+### Deployment options
+
+The BRC-100 interface works regardless of deployment:
+
+1. **In-process** — `require 'bsv-wallet'`, gateway calls wallet methods directly. Simplest. Keys in the same process.
+2. **Local service** — wallet runs as a separate process, gateways call via HTTP. Process isolation.
+3. **Remote service** — wallet on a different machine. Network boundary. Strongest isolation.
+
+Same interface, different transports. Start with in-process, separate later if needed.
+
+### Separation from middleware
+
+The wallet gem has a strict public API (BRC-100 methods only). The `x402-rack` gem depends on `bsv-wallet` but only through this interface. The middleware itself (`X402::Middleware`) never talks to the wallet — only gateways do.
+
+```
+x402-rack (no keys, no wallet dependency)
+  └── X402::Middleware
+  └── X402::BSV::ProofGateway ──→ BSV::Wallet (BRC-100 API)
+  └── X402::BSV::PayGateway ────→ BSV::Wallet (BRC-100 API, for ARC only)
+```
+
+## External Services
+
+### ARC (BSV transaction processor)
+- Broadcasts transactions and returns acceptance/rejection
+- Queries mempool visibility for already-broadcast txs
+- Used by: wallet (via `bsv-sdk` ARC provider)
+- API: https://docs.bsvblockchain.org/important-concepts/details/spv/broadcasting
+
+### Delegator (client-side concern)
+- Adds fee inputs to client-constructed partial txs, signs only its fee inputs
+- Used by: clients (not servers). The server stack never talks to the delegator.
+- Separate service entirely — could be operated by the gateway operator or a third party
+- Could itself be powered by a `bsv-wallet` instance in the "fees" role
+
+## How Identity Flows Through the Stack
+
+```
+Request arrives
+    │
+    ▼
+BRC-104 Auth Middleware
+    │  Verifies x-bsv-auth-* headers
+    │  Sets env['brc103.identity_key'] = "02abc..."
+    │  Sets env['brc103.certificates'] = [...]
+    │
+    ▼
+X402 Middleware
+    │  Reads route config → protected, costs 100 sats
+    │  No proof header → issue challenges
+    │  Passes env (including identity) to each gateway
+    │
+    ├── PayGateway.challenge_headers(request, route)
+    │   Returns Payment-Required header (v2 JSON with BSV in accepts)
+    │
+    ├── ProofGateway.challenge_headers(request, route)
+    │   Returns X402-Challenge header (merkleworks format)
+    │
+    ├── BRC105Gateway.challenge_headers(request, route)
+    │   Reads env['brc103.identity_key']
+    │   If present → returns x-bsv-payment-* headers (with derivation prefix)
+    │   If absent → returns {} (declines — can't work without identity)
+    │
+    ▼
+402 Response with all non-empty challenge headers
+```
+
+A client with a BRC-100 wallet and BRC-103 auth gets all three challenge options. A standard x402 v2 client gets the `Payment-Required` header and can pay with BSV. A merkleworks-specific client uses `X402-Challenge`. The client picks whichever it supports.
+
+## How Payment Flows Through the Stack
+
+```
+Request arrives with proof header
+    │
+    ▼
+BRC-104 Auth Middleware (if present)
+    │  Authenticates, sets env['brc103.identity_key']
+    │
+    ▼
+X402 Middleware
+    │  Reads route config → protected, costs 100 sats
+    │  Detects proof header
+    │
+    ├── Has Payment-Signature? → dispatch to PayGateway.settle!()
+    │   Gateway verifies tx, broadcasts via ARC
+    │   Returns: allow + settlement result + Payment-Response header
+    │
+    ├── Has X402-Proof? → dispatch to ProofGateway.settle!()
+    │   Gateway verifies tx, checks mempool via ARC
+    │   Returns: allow + settlement result
+    │
+    ├── Has x-bsv-payment? → dispatch to BRC105Gateway.settle!()
+    │   Gateway verifies derivation + tx via BRC-100 wallet
+    │   Returns: allow + settlement result
+    │
+    ▼
+Allow → forward to application (with receipt headers if provided)
+Deny → return error to client
+```
+
+## What Each Component Knows
+
+| Component | Knows about HTTP | Knows about BSV | Knows about identity | Holds keys |
+|-----------|:---:|:---:|:---:|:---:|
+| BRC-104 Auth Middleware | Yes | Signatures only | Yes — its job | Session keys |
+| X402 Middleware | Yes | No | Passes through | No |
+| ProofGateway | Headers only | Via wallet | No | No — wallet holds them |
+| PayGateway | Headers only | Via wallet | No | No — wallet holds them |
+| BRC-105 Gateway | Headers only | Via wallet | Yes (reads from env) | No — wallet holds them |
+| BSV Wallet | No | Yes — its job | No | Yes — the security boundary |
+| ARC | No | Yes | No | No |
+| Delegator | No | Via wallet | No | No — wallet holds them |
+| Client | Yes | Yes | Optionally | Wallet keys |
+
+## Gem Boundaries
+
+| Gem | Repo | Contains |
+|-----|------|---------|
+| `bsv-sdk` | `sgbett/bsv-ruby-sdk` | Primitives — keys, transactions, scripts, ARC provider |
+| `bsv-wallet` | `sgbett/bsv-ruby-sdk` | BRC-100 wallet interface, basket UTXO tracking, multi-key management. Depends on `bsv-sdk`. |
+| `x402-rack` | `sgbett/x402-rack` | X402::Middleware (gatekeeper), gateway interface, X402::BSV::ProofGateway, X402::BSV::PayGateway. Gateways depend on `bsv-wallet`. |
+| `brc104-rack` (future) | Separate | BRC-104 auth middleware |
+| `bsv-x402` (npm) | `sgbett/bsv-x402` | Client-side fetch wrapper, CWI integration |
+
+### Dependency chain
+
+```
+x402-rack
+  └── bsv-wallet (BRC-100 interface only)
+        └── bsv-sdk (primitives)
+```
+
+The middleware itself has no dependency on `bsv-wallet` or `bsv-sdk`. Only the gateway classes do. A pure middleware deployment (dispatching to remote gateways) wouldn't need the BSV gems at all.
+
+## Design Principles
+
+1. **Each layer handles one concern.** Auth is auth. Payment is payment. Settlement is settlement. They compose, they don't merge.
+
+2. **The gatekeeper is dumb.** It dispatches. It doesn't understand what it's dispatching. Blockchain knowledge lives in gateways.
+
+3. **Gateways are pluggable.** New settlement protocols = new gateway classes. No middleware changes.
+
+4. **Identity is optional and upstream.** Payment gating works without identity. Identity enriches the options (BRC-105) but doesn't gate them.
+
+5. **External services are the gateway's concern.** The middleware never talks to ARC, wallets, or treasuries. Gateways own those relationships.
+
+6. **The client chooses.** Multiple challenge headers, client picks. Payment content negotiation.
+
+7. **State lives on-chain.** No server-side nonce pools, no session tracking, no balance ledgers. The blockchain is the state (with one exception: BRC-105's derivation prefix tracking, which is the BRC-100 wallet's concern).

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,33 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+
+Metrics/CollectionLiteralLength:
+  Enabled: false

data/CLAUDE.md

@@ -0,0 +1,47 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+x402-rack is a Ruby gem providing Rack middleware for the x402 protocol (BSV settlement-gated HTTP). Currently in early development (v0.1.0). Requires Ruby >= 3.1.
+
+## Commands
+
+```bash
+# Install dependencies
+bin/setup
+
+# Run tests
+bundle exec rake spec
+
+# Run a single test file
+bundle exec rspec spec/x402_spec.rb
+
+# Run a single example by line number
+bundle exec rspec spec/x402_spec.rb:4
+
+# Lint
+bundle exec rubocop
+
+# Lint with auto-fix
+bundle exec rubocop -A
+
+# Run all checks (tests + lint) — this is the CI default
+bundle exec rake
+```
+
+## Architecture
+
+Standard Ruby gem layout generated by `bundle gem`:
+
+- `lib/x402.rb` — main entry point, defines `X402` module
+- `lib/x402/version.rb` — version constant
+- `sig/x402.rbs` — RBS type signatures
+- `x402-rack.gemspec` — gem specification (dependencies defined here, not in Gemfile)
+
+## Code Style
+
+- Double quotes for strings (enforced by RuboCop)
+- `frozen_string_literal: true` magic comment on all Ruby files
+- Target Ruby version: 3.1

data/DESIGN.md

@@ -0,0 +1,216 @@
+# x402-rack Design Notes (DRAFT)
+
+## Architecture
+
+### Middleware as Dispatcher (`X402::Middleware`)
+
+The Rack middleware is a **pure dispatcher** — the gatekeeper. It has no blockchain knowledge. It:
+
+1. Matches incoming requests against protected routes
+2. Polls each configured gateway for challenge headers, returns all of them in the 402 response
+3. Checks which proof/payment header the client sent, dispatches to the matching gateway
+4. The gateway returns allow/deny — the middleware serves or rejects accordingly
+
+The middleware never decodes transactions, checks mempool, broadcasts, or interacts with any blockchain network. It manages HTTP headers, route matching, and dispatch.
+
+**The gatekeeper MUST NOT sign transactions or hold private keys.**
+
+### Gateways (`X402::BSV::ProofGateway`, `X402::BSV::PayGateway`)
+
+Gateways are pluggable backends that handle chain-specific settlement. They **can** hold keys and sign transactions — they are separate components from the gatekeeper. Each gateway:
+
+- Builds challenge data (including partial transaction templates)
+- Verifies and settles proofs
+- Interacts with ARC and/or a treasury service via the BSV wallet
+
+The gateway interface:
+
+```ruby
+#   #challenge_headers(rack_request, route) → Hash
+#   #proof_header_names → Array<String>
+#   #settle!(header_name, proof_payload, rack_request, route) → result
+```
+
+The boundary test: could someone write `X402::EVM::Gateway` implementing this interface without touching `lib/x402/`? If yes, the separation is correct.
+
+### Multi-Protocol Support
+
+Different x402 ecosystems use different HTTP headers. A server can send **multiple challenge headers** simultaneously — the client picks the one it can satisfy. This is payment content negotiation.
+
+| Scheme | Challenge header | Proof header | Receipt header |
+|--------|-----------------|--------------|----------------|
+| BSV-pay (ours) | `Payment-Required` | `Payment-Signature` | `Payment-Response` |
+| BSV-proof (merkleworks) | `X402-Challenge` | `X402-Proof` | — |
+
+Our PayGateway uses the Coinbase v2 headers (`Payment-*`) — the standard x402 ecosystem language. The ProofGateway uses the merkleworks `X402-*` headers. Header namespaces are reserved per ecosystem: `Payment-*` (Coinbase v2 / ours), `X402-*` (merkleworks), `x-bsv-*` (BRC-105 / BSV Association).
+
+## Unified Template Model
+
+### Both gateways produce partial transaction templates
+
+The challenge includes a **partial transaction template** that the client extends by adding funding inputs (and optionally change outputs). This model unifies the two BSV schemes.
+
+**Base behaviour** (`X402::BSV::Gateway`): build a partial tx with the payment output (amount to payee) and an OP_RETURN request binding output.
+
+**ProofGateway override**: prepends the nonce UTXO input at index 0, signed with `SIGHASH_SINGLE | ANYONECANPAY | FORKID (0xC3)`. This locks the payment output (output 0) while allowing the client to append inputs and outputs freely.
+
+**PayGateway**: inherits the base behaviour. Payment output + OP_RETURN binding, no nonce.
+
+The client's job is identical regardless of scheme: add funding inputs, sign, and either broadcast (BSV-proof) or hand to the server (BSV-pay). The delegator fits the same way in both flows.
+
+### Progressive enhancement via `extra.partialTx`
+
+For the PayGateway's `Payment-Required` challenge (Coinbase v2 format), the partial tx template is carried in the `extra` field of the `accepts` entry:
+
+```json
+{
+  "x402Version": 2,
+  "resource": { "url": "/api/expensive" },
+  "accepts": [
+    {
+      "scheme": "exact",
+      "network": "bsv:mainnet",
+      "amount": "100",
+      "asset": "BSV",
+      "payTo": "1A1zP1...",
+      "maxTimeoutSeconds": 60,
+      "extra": {
+        "partialTx": "<base64 of partial tx template>"
+      }
+    }
+  ]
+}
+```
+
+**Basic client** (any x402 v2 client): ignores `extra.partialTx`, constructs a tx from scratch using `payTo` + `amount`.
+
+**Smart client** (BSV-aware): reads `extra.partialTx`, extends the template by adding funding inputs and signing.
+
+The template is an optimisation, not a requirement. `payTo` + `amount` are always sufficient.
+
+### Request binding via OP_RETURN
+
+The partial tx template includes an OP_RETURN output binding the payment to the specific request:
+
+```
+Output 0: payment (amount to payee)
+Output 1: OP_RETURN <SHA256(method + path + query)>
+```
+
+At settlement, the gateway recomputes the hash and verifies it matches. Prevents template redirection between endpoints. Cheap (~30 bytes), on-chain, verifiable. Configurable strict/permissive mode.
+
+### Why 0xC3 for the nonce signature
+
+`SIGHASH_SINGLE | ANYONECANPAY | FORKID`:
+- `SIGHASH_SINGLE`: commits only to `output[input_index]` — the nonce at input 0 protects only output 0 (the payment)
+- `ANYONECANPAY`: excludes other inputs — funding and fee inputs can be appended freely
+- `FORKID`: BSV fork ID flag (required)
+
+Using `0xC1` (`SIGHASH_ALL | ANYONECANPAY`) would commit to ALL outputs, breaking extensibility.
+
+## Two BSV Schemes
+
+### BSV-proof (merkleworks x402 spec)
+
+Client broadcasts, server checks mempool. Proof-of-payment model.
+
+**Headers**: `X402-Challenge` / `X402-Proof`
+
+**Challenge**: merkleworks JSON format including a pre-signed partial tx template (Profile B) with nonce UTXO at input 0 signed with `0xC3`, payment output at output 0, plus request binding metadata, expiry, and `require_mempool_accept: true`.
+
+**Settlement**: gateway verifies tx structure, checks nonce spent at input 0, checks payment output, queries ARC for mempool visibility.
+
+**Why client broadcasts** (per Rui at merkleworks): broadcasting is settlement, not authorisation. Server-side broadcast pushes the server towards a stateful payment processor. Client-side broadcast keeps it stateless.
+
+**Requires**: treasury (nonce provision + template signing) + ARC (mempool queries).
+
+### BSV-pay (our BSV-native scheme)
+
+Server broadcasts via ARC. Uses Coinbase v2 header spec.
+
+**Headers**: `Payment-Required` / `Payment-Signature` / `Payment-Response`
+
+**Challenge**: Coinbase v2 `PaymentRequired` with BSV in `accepts` array, `extra.partialTx` carrying the template (payment output + OP_RETURN binding).
+
+**Settlement**: gateway verifies payment output, verifies OP_RETURN binding, broadcasts to ARC (`X-WaitFor: SEEN_ON_NETWORK`, 5s timeout). ARC 200 → allow. ARC error → relay to client.
+
+**No nonces needed**: ARC is the replay gate. Each tx can only be accepted once.
+
+**Requires**: ARC only. No treasury, no nonce provision.
+
+### Comparison
+
+| | BSV-proof (merkleworks) | BSV-pay (ours) |
+|---|---|---|
+| Header spec | Merkleworks `X402-*` | Coinbase v2 `Payment-*` |
+| Challenge header | `X402-Challenge` | `Payment-Required` |
+| Proof header | `X402-Proof` | `Payment-Signature` |
+| Receipt header | — | `Payment-Response` |
+| Template contains | Nonce input (signed 0xC3) + payment output | Payment output + OP_RETURN binding |
+| Who broadcasts | Client | Server (via ARC) |
+| Nonce needed | Yes (challenge binding) | No (ARC is replay gate) |
+| Request binding | Yes (in challenge metadata) | Yes (OP_RETURN in template) |
+| Settlement check | Mempool visibility query | ARC broadcast response |
+| Treasury needed | Yes | No |
+| Minimum infrastructure | Treasury + ARC | ARC only |
+| Ecosystem compatibility | Merkleworks BSV clients | Any x402 v2 client |
+
+## Component Boundaries
+
+| Component | Responsibility | Keys? |
+|-----------|---------------|-------|
+| **Gatekeeper** (`X402::Middleware`) | HTTP dispatch, route matching | No — MUST NOT hold keys |
+| **Gateway** (`X402::BSV::*Gateway`) | Challenge templates, settlement, ARC interaction | Via wallet |
+| **BSV Wallet** (`bsv-wallet` gem) | Key management, UTXO tracking, signing | Yes — the security boundary |
+| **Treasury** (wallet role) | Mints nonce UTXOs, signs templates | Via wallet's nonce basket |
+| **Delegator** (separate service) | Adds fee inputs, signs only fee inputs | Yes — but not our concern |
+| **Client** (browser + CWI wallet) | Extends template, signs funding inputs | Yes — client's wallet |
+
+### Server-side wallet
+
+The `bsv-wallet` gem (in the `sgbett/bsv-ruby-sdk` monorepo) provides a BRC-100 interface. Gateways talk to the wallet exclusively through this API — they never touch keys directly. The wallet is the security boundary.
+
+One wallet, multiple roles via baskets:
+
+| Role | Basket | Operations |
+|------|--------|------------|
+| Treasury | `x402-nonces` | `createAction` (mint nonces, sign templates), `listOutputs` |
+| Delegator | `x402-fees` | `signAction` (sign fee inputs), `listOutputs` |
+| Payment receipt | `x402-revenue` | `internalizeAction` (accept payments), `listOutputs` |
+
+### Dependency chain
+
+```
+x402-rack (no keys, no wallet dependency in middleware)
+  └── X402::BSV::*Gateway → bsv-wallet (BRC-100 interface)
+                                └── bsv-sdk (primitives)
+```
+
+## Ecosystem Context
+
+**Coinbase x402 v2** (broad ecosystem): client signs authorisation, facilitator broadcasts. Headers: `Payment-Required` / `Payment-Signature` / `Payment-Response`.
+
+**Merkleworks x402** (BSV-specific): client broadcasts, server checks mempool. Headers: `X402-Challenge` / `X402-Proof`.
+
+**BRC-105** (BSV Association BRC, future): mutual auth (BRC-103) + derivation-based payments. Headers: `x-bsv-payment-*`.
+
+Our middleware supports all header conventions via the multi-gateway dispatch model. Our PayGateway speaks the standard Coinbase v2 language, making BSV a first-class citizen in the broader x402 ecosystem.
+
+## Client Side
+
+The x402 flow requires a client that intercepts 402 responses, parses challenges, extends transaction templates, handles fee delegation, and presents proof/payment. This is handled by [`bsv-x402`](https://www.npmjs.com/package/bsv-x402) — a separate JavaScript/TypeScript library ([`sgbett/bsv-x402`](https://github.com/sgbett/bsv-x402) on GitHub).
+
+The client wraps `fetch()` and uses BRC-100 (`window.CWI`) to interact with compliant BSV wallets for transaction construction and signing. See that project's documentation for architecture and integration details.
+
+## Current State
+
+The middleware (`X402::Middleware`), configuration, and protocol layer (challenge/proof structures, request binding, base64url encoding) are implemented. BSV-specific logic currently lives in `X402::Verification::SettlementChecks` and needs to migrate into the gateway classes.
+
+Next steps:
+1. Extract the gateway interface from the middleware
+2. Implement `X402::BSV::Gateway` base class (payment output + OP_RETURN template)
+3. Implement `X402::BSV::ProofGateway` (merkleworks compatibility)
+4. Implement `X402::BSV::PayGateway` (BSV-native, ARC broadcast, Coinbase v2 headers)
+5. Refactor middleware to multi-gateway dispatch
+
+See [`.claude/plans/20260325-bsv-module.md`](.claude/plans/20260325-bsv-module.md) for the detailed implementation plan and [`.claude/plans/20260326-rack-stack-architecture.md`](.claude/plans/20260326-rack-stack-architecture.md) for the full rack stack architecture.

data/LICENSE.txt

@@ -0,0 +1,56 @@
+Open BSV License Version 5 – granted by BSV Association, Grafenauweg 6, 6300
+Zug, Switzerland (CHE-427.008.338) ("Licensor"), to you as a user (henceforth
+"You", "User" or "Licensee").
+
+For the purposes of this license, the definitions below have the following
+meanings:
+
+"Bitcoin Protocol" means the protocol implementation, cryptographic rules,
+network protocols, and consensus mechanisms in the Bitcoin White Paper as
+described here https://protocol.bsvblockchain.org.
+
+"Bitcoin White Paper" means the paper entitled 'Bitcoin: A Peer-to-Peer
+Electronic Cash System' published by 'Satoshi Nakamoto' in October 2008.
+
+"BSV Blockchains" means:
+  (a) the Bitcoin blockchain containing block height #556767 with the hash
+      "000000000000000001d956714215d96ffc00e0afda4cd0a96c96f8d802b1662b" and
+      that contains the longest honest persistent chain of blocks which has been
+      produced in a manner which is consistent with the rules set forth in the
+      Network Access Rules; and
+  (b) the test blockchains that contain the longest honest persistent chains of
+      blocks which has been produced in a manner which is consistent with the
+      rules set forth in the Network Access Rules.
+
+"Network Access Rules" or "Rules" means the set of rules regulating the
+relationship between BSV Association and the nodes on BSV based on the Bitcoin
+Protocol rules and those set out in the Bitcoin White Paper, and available here
+https://bsvblockchain.org/network-access-rules.
+
+"Software" means the software the subject of this licence, including any/all
+intellectual property rights therein and associated documentation files.
+
+BSV Association grants permission, free of charge and on a non-exclusive and
+revocable basis, to any person obtaining a copy of 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 and conditioned upon the following conditions:
+
+1 - The text "© BSV Association," and this license shall be included in all
+copies or substantial portions of the Software.
+2 - The Software, and any software that is derived from the Software or parts
+thereof, must only be used on the BSV Blockchains.
+
+For the avoidance of doubt, this license is granted subject to and conditioned
+upon your compliance with these terms only. In the event of non-compliance, the
+license shall extinguish and you can be enjoined from violating BSV's
+intellectual property rights (incl. damages and similar related claims).
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES REGARDING ENTITLEMENT,
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS THEREOF 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.