fix(node): harden Arweave anchoring and add verification (#26)

.env.example

@@ -46,9 +46,37 @@ GITLAWB_DB_RETRY_MAX_SECS=60
 GITLAWB_PINATA_JWT=
 GITLAWB_PINATA_UPLOAD_URL=https://uploads.pinata.cloud/v3/files
 
-# ── Arweave permanent anchoring (Irys devnet) ─────────────────────────────
-# Leave empty to disable Arweave anchoring.
-GITLAWB_IRYS_URL=https://devnet.irys.xyz
+# ── Arweave permanent anchoring (Bundler / Arweave gateway) ───────────────────
+# Bundler URL for permanent anchoring. Leave empty to disable anchoring.
+# (Legacy name: GITLAWB_IRYS_URL)
+# Anchoring is PAID, and the node refuses to start when a bundler URL is set
+# without BOTH GITLAWB_BUNDLER_ACCOUNT (a funded account) and
+# GITLAWB_BUNDLER_TOKEN (the token that account holds): Irys bills uploads at
+# /tx/{token} via the x-irys-paid-by header, so a URL with no funded account and
+# token would silently fail every anchor. Default (empty) disables anchoring.
+GITLAWB_BUNDLER_URL=
+# To enable, uncomment the devnet block below and fund the account via the
+# bundler's devnet faucet (https://docs.irys.xyz/devnet/faucet), or use the
+# production block with a funded wallet and https://node2.irys.xyz.
+# Anchoring is PAID and needs the funded-account pair AND an explicit
+# GITLAWB_ARWEAVE_GATEWAY for the SAME network: the node refuses to start with
+# a bundler URL but no gateway, because an anchor is only resolvable through
+# the gateway of the network that recorded it.
+#
+# Devnet:
+#GITLAWB_BUNDLER_URL=https://devnet.irys.xyz
+#GITLAWB_BUNDLER_ACCOUNT=<funded account address on devnet>
+#GITLAWB_BUNDLER_TOKEN=matic
+#GITLAWB_ARWEAVE_GATEWAY=https://devnet.irys.xyz
+#
+# Production (mainnet Irys + Arweave):
+#GITLAWB_BUNDLER_URL=https://node2.irys.xyz
+#GITLAWB_BUNDLER_ACCOUNT=<funded account address on mainnet>
+#GITLAWB_BUNDLER_TOKEN=ethereum
+#GITLAWB_ARWEAVE_GATEWAY=https://arweave.net
+# Per-client-IP rate limit for the unauthenticated /api/v1/arweave/verify/:tx_id
+# endpoint, in requests per hour. 0 disables. Default 120.
+GITLAWB_ARWEAVE_RATE_LIMIT=120
 
 # ── Base L2 smart contracts ───────────────────────────────────────────────
 GITLAWB_CHAIN_RPC_URL=https://sepolia.base.org

Cargo.toml

@@ -52,7 +52,7 @@ chrono = { version = "0.4", features = ["serde"] }
 # uuid
 uuid = { version = "1", features = ["v4"] }
 # http client
-reqwest = { version = "0.12", features = ["blocking", "json", "multipart", "rustls-tls"], default-features = false }
+reqwest = { version = "0.12", features = ["blocking", "json", "multipart", "rustls-tls", "stream"], default-features = false }
 # HMAC
 hmac = "0.12"
 

README.md

@@ -363,7 +363,11 @@ Important node settings:
 | `GITLAWB_IPFS_RATE_LIMIT` | Max `/ipfs/{cid}` requests per client IP per hour (route flood brake). 0 disables. Default 600. |
 | `GITLAWB_TIGRIS_BUCKET` | Optional S3/Tigris shared repo storage bucket. |
 | `GITLAWB_PINATA_JWT` | Optional Pinata/IPFS warm-storage pinning. |
-| `GITLAWB_IRYS_URL` | Optional Irys/Arweave permanent anchoring. |
+| `GITLAWB_BUNDLER_URL` | Bundler URL for Arweave permanent anchoring (e.g., https://devnet.irys.xyz for devnet, https://node2.irys.xyz for mainnet Irys). Leave empty to disable. (Legacy name: `GITLAWB_IRYS_URL`). |
+| `GITLAWB_BUNDLER_ACCOUNT` | Funded bundler account (public address/identity) that pays for uploads. The node's ANS-104 signature proves authorship, not payment — Irys only serves items backed by a funded account — so the node refuses to start when a bundler URL is set without this. It is sent as the `x-irys-paid-by` header on every upload. |
+| `GITLAWB_BUNDLER_TOKEN` | Payment-token slug the funded account holds (e.g. `matic` on devnet, `ethereum` on mainnet). Irys bills uploads at `/tx/{token}`, so this names the token, not an API key, and is NOT sent as `x-irys-paid-by` (that header carries the account). The node refuses to start when a bundler URL is set without it. |
+| `GITLAWB_ARWEAVE_GATEWAY` | Arweave gateway used to resolve anchors for `/verify` and the anchors listing. Has no default: the node refuses to start when a bundler is configured without an explicit gateway, because an anchor is only resolvable through the gateway of the network that recorded it (a devnet bundler pairs with the devnet gateway, mainnet Irys with `https://arweave.net`). |
+| `GITLAWB_ARWEAVE_RATE_LIMIT` | Per-client-IP rate limit for the verify endpoint, requests per hour (defaults to 120; `0` disables). |
 
 Production note: change the default Postgres password before exposing a node publicly.
 

SECURITY.md

@@ -28,12 +28,18 @@ We will acknowledge receipt within 48 hours and aim to release a fix within 14 d
 - Every git object is content-addressed via CIDv1 (SHA-256)
 - Tamper-evident by construction — a modified object changes its CID
 
-**UCAN token validation**
-- Bootstrap UCAN tokens are issued at registration.
-- A supplied token's signature, audience, expiry, and proof-chain attenuation are validated.
-- Tokens use a signed JSON wire format with expiry.
+**UCAN capability tokens**
+- Issued at registration as a signed JSON envelope `{ "payload": {...}, "s": "<base64url Ed25519 signature over the payload JSON>" }` — not a JWT
+- Capability-scoped: `git/push`, `git/fetch`, `issue/create`, `pr/open`
+- Expiry enforced on every verification
+- The auth middleware (`require_ucan_chain`) verifies the full delegation chain when the `X-Ucan` header is present: the UCAN issuer must match the HTTP Signature identity, the audience must be this node's DID, and every proof in the chain must be cryptographically sound with no capability escalation
 - Capability grants are not yet consulted by repository write authorization; see the limitations below.
 
+**Authorization**
+- Every repo-scoped read and mutation binds the caller to an authorization decision before serving or mutating anything
+- Per-repository read enforcement is wired: `authorize_repo_read` denies with the same 404 a missing repo returns, and content endpoints pass the specific path so a withheld subtree is denied even on an otherwise-public repo
+- Owner-only mutations (visibility, webhooks, protected branches, merges) are gated to the repo owner; star/unstar, replica registration, and bounty actions have their own intended gates
+
 **Smart contracts (Base Sepolia testnet)**
 - `GitlawbDIDRegistry` — on-chain DID → document registry
 - `GitlawbNameRegistry` — human name → DID registry
@@ -53,6 +59,12 @@ We will acknowledge receipt within 48 hours and aim to release a fix within 14 d
 
 These are documented limitations of the current live release. They should be prioritized without breaking existing nodes during rolling upgrades.
 
+### UCAN chain validation is optional per request
+- The middleware verifies the full UCAN delegation chain only when the client presents an `X-Ucan` header. Requests without the header pass through unchanged, so agents that predate UCAN delegation are not forced off.
+- **Impact:** A client can still authenticate with a bare RFC 9421 HTTP Signature and skip delegation-chain enforcement entirely; capability delegation is enforced only for clients that opt into presenting a UCAN.
+- **Mitigation:** Keep write endpoints signed, treat public nodes as public infrastructure, and treat trust scores as soft rate-limiting signals rather than authorization.
+- **Fix target:** make UCAN presentation mandatory for pushes (planned together with owner-push enforcement).
+
 ### Repository write authorization defaults
 - `git-receive-pack` verifies HTTP Signatures, but `GITLAWB_ENFORCE_OWNER_PUSH` defaults to `false` for compatibility during rollout.
 - **Impact:** With the default setting, a valid signature authenticates the pusher but does not require that DID to be the repository owner.
@@ -111,7 +123,7 @@ These are documented limitations of the current live release. They should be pri
 | Key storage | PKCS#8 PEM, 0600 permissions |
 | Content hashing | SHA-256 via CIDv1 |
 | HTTP Signatures | RFC 9421 (Ed25519 + SHA-256 Content-Digest) |
-| UCAN tokens | Signed JSON object (Ed25519 signature) |
+| UCAN tokens | Signed JSON envelope (Ed25519 over the payload JSON), not JWT |
 | On-chain | ECDSA secp256k1 (Base L2 / Ethereum) |
 
 ---