fix(auth): preserve received payment headers and configure server payload capacity

[ty-everett]

Program and scope

BRC-105 payments can carry valid Atomic BEEF larger than the hardened HTTP header ceilings. This restores compatibility at the transport boundary without changing BRC100 calls, signed wire bytes or wallet data. Coordination: BotBoard #596.

• SDK client capacity increases fourfold: 32 KiB ordinary values, 256 KiB aggregate names/values, 512 headers, 1 KiB names and 256 KiB requested-certificate policy. Only x-bsv-payment may use the full aggregate request budget. Response-frame overhead rises to 512 KiB.
• Auth and payment middleware impose no header byte/count ceiling after receipt. Auth's body budget excludes headers; the deprecated payment maxPaymentHeaderBytes field remains accepted but ignored. HTTP servers, proxies, CDNs and WAFs own transport admission.
• Optional local AuthMessageValidationOptions on Peer and snapshotAuthMessage supports a positive explicit general-payload byte budget or null to delegate to the transport. Omission preserves legacy SDK policy. Auth middleware selects delegation and requires SDK 2.8.5, removing the indirect SDK envelope ceiling for received headers.
• CI coverage aggregation now installs its existing locked compiler before classifying declaration-only edits. A clean-workspace rehearsal passes the unchanged 90% gate at 97.06%; no coverage exemptions are added.
• General payload delegation preserves metadata, dense bytes, owned snapshots, signature, handshake/certificate, session and replay validation. Canonical payment parsing, pricing and wallet acceptance remain required.

Out of scope: BRC100 API/wire changes, wallet schemas, pricing, payment/replay relaxation, unrelated package revisions and #569.

Exact head reviewed: 25b4c676c85cc7f2d8c427cf77abb9fa1874a1b7. All applicable hosted checks passed at that head.

Impact

• Public package source or manifest changed
• Additive public types/configuration changed
• Security-sensitive boundary changed
• Documentation and migration guidance changed

Patch candidates, as explicitly directed by the maintainer: @bsv/sdk 2.8.5, @bsv/auth-express-middleware 2.2.8, @bsv/payment-express-middleware 2.1.8. None is published by this PR.

Verification

Final local validation uses the governed Node 24.18.0 and pnpm 10.33.2 toolchain.

• SDK full coverage: 210 suites / 7,442 tests pass; 94.30% statements, 87.95% branches, 96.04% functions, 95.44% lines.
• Auth middleware: 201 tests pass, 93.19% branches. Payment middleware: 55 tests pass, 95.53% branches.
• Repository patch coverage: 97.10% (201/207 changed line/branch points) against main b2f1989306b6f64677deff89f39596491e448d97; target 90%.
• Portable TypeScript conformance: 6,491 pass / 211 unchanged governed skips.
• Coverage compiler bootstrap: fresh managed workspace passes with frozen root-only dependencies; all 8 patch-coverage regression tests pass.
• Workspace build/typecheck, lint, formatting and security audit pass. Root health also passes after mutation sandbox cleanup; no policy exception is introduced.
• All three pack:check commands pass: exact exports/declarations/maps, strict resolution, clean ESM/CJS and Express 4/5 runtime consumers. SDK exact-tarball Vite/esbuild/UMD browser checks pass within governed budgets.
• SDK auth HTTP mutation scope includes the new payload policy and ownership regressions: 88.54% (238 killed, 48 timeouts, 37 survived; 323 total), above the governed target. Existing unchanged middleware mutation targets passed at 94.32% (auth bytes) and 94.44% (payment replay).
• Boundary tests cover exact client limits and next-byte rejection, UTF-8 byte accounting, real signed 128 KiB HTTP requests, tamper rejection, middleware headers over 1 MiB, deprecated-cap behavior, finite server budgets, >4 MiB delegated Peer payloads, metadata/non-general bounds and immutable policy/message snapshots. Top-level descriptors are captured once before policy selection, so a changing proxy cannot supply different message types for policy and validation.
• Complete diff self-reviewed for correctness, security, compatibility, public API, artifacts, dependencies, documentation and operations
• All applicable hosted checks are terminal and successful on the exact head: CI 36047564046, attempt 2. The first attempt lost a localhost connection in one wallet-toolbox test; its targeted retry passed all 69 selected suites (734 tests), including that exact fragmented-wallet case. Aggregated patch coverage is 97.10%; hosted SDK mutation is 88.54% (260 killed, 26 timeouts, 37 survived), with the same surviving mutants as the local run. No test or gate was weakened.

Security and dependency evidence

Auth middleware's required SDK peer moves to ^2.8.5 because it uses the new local policy. Workspace dependencies remain linked; no third-party graph or lockfile change. Canonical framing, invalid-header rejection, body budgets, authentication and replay protection remain. This deliberately transfers header admission to the HTTP layer; operators must verify the complete route before accepting larger proofs. Clients still need sufficient client capacity for larger responses.

• No new override, advisory dismissal, suppression or skipped test
• Audit and package/consumer compatibility reviewed
• Exact-head CodeQL has no new alert: run 36047564149, both analyses on PR merge commit 4fda8de69dcedbc2c01ee34dd04db07e7b26204e report zero results; alert 288 is automatically fixed and its review thread is resolved.
• Exact-head zero-new Sonar findings gate passed; no new issues or unreviewed hotspots. The complete repository merge gate also passes.

Release and operations

• No workstation npm publication
• Three patch bumps, generated facts, release notes, API documentation and migration guidance included
• No BRC100 application or wallet-data migration; existing conforming apps remain compatible
• Protected publication and registry/provenance verification complete

After green review and merge, use protected publication, verify exact npm artifacts, then upgrade consumers and validate their configured HTTP routes. Publication and deployment remain separate acceptance steps.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

❌ Patch coverage is 94.59459% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/sdk/src/auth/AuthMessageValidation.ts	92.30%	3 Missing and 3 partials ⚠️

📢 Thoughts on this report? Let us know!

[ty-everett]

Authoring maintainer review of 25b4c676c85cc7f2d8c427cf77abb9fa1874a1b7: no unresolved issue in the complete diff. I reviewed request/response framing, canonical payment validation and replay behavior, metadata and certificate bounds, ownership of message/configuration snapshots, legacy default behavior, exported types, package peers/artifacts, documentation and CI permissions.

The optional server policy is locally selected and captured once; it cannot be changed by a received message. Middleware preserves received headers for validation. SDK clients retain the documented higher capacities, and existing BRC100 calls, signed bytes and wallet records remain compatible. The three patch versions follow the maintainer's explicit release decision.

CI 36047564046 attempt 2 passes the complete merge gate, including 97.10% patch coverage and 88.54% SDK auth mutation score. The isolated first-attempt localhost failure passed on its targeted retry without changing source or weakening assertions. CodeQL on the PR merge ref has zero open alerts; its previous finding is automatically fixed and the review thread is resolved. Sonar zero-new and Socket checks pass.

Approve integration under the repository's maintainer review policy. Actual npm publication remains gated on reviewed main validation and exact protected candidate/attestation verification.