fix(express): share host runtime across framework extensions

[ty-everett]

Program and scope

• Tracker or issue: final upstream gate for the Message Box/AuthSocket hardening rollout and p2ppsr adoption.
• Why this change is needed: published packages that mount into a consumer-owned Express application must share that application's runtime and declaration graph. Installing private Express 5 copies breaks otherwise-supported Express 4 consumers and can create incompatible request types.
• Repo-wide audit result: all published Express users were classified. @bsv/paymail, @bsv/auth-express-middleware, @bsv/payment-express-middleware, and @bsv/wallet-relay extend a host application and are fixed here. @bsv/overlay-express and @bsv/wallet-toolbox instantiate and own their internal servers, so their regular Express dependencies remain correct.
• Also included: dependency-graph scoping for docs example packaging, so unrelated examples are not built by CI.
• Explicitly out of scope: auth/payment wire protocol changes, infrastructure images, and downstream p2ppsr manifest/deployment changes.
• Exact head SHA reviewed: 1d0a9b79ec796112581f0a6bc6abbadf84d71b25

Impact

• No public package source or manifest changed
• Public package source or manifest changed; affected packages are listed below
• Infrastructure source, dependency, image, or deployment configuration changed
• Public types and packed-consumer behavior changed
• Security-sensitive runtime boundary changed
• Documentation or examples changed

Affected packages and intended patch versions (publication occurs only through the protected release workflow after merge):

• @bsv/auth-express-middleware@2.1.7
• @bsv/payment-express-middleware@2.1.5
• @bsv/paymail@2.4.6
• @bsv/wallet-relay@0.3.4

Verification

• Local toolchain: Node 24.18.0 and pnpm 10.33.2.
• Full workspace: build, typecheck, lint, root/package formatting, health:check (129/129), and audit:security (zero known vulnerabilities) all pass.
• Exact packed artifacts: all four packages pass their package artifact checks and strict clean TypeScript consumers on Express 4.22.1 + @types/express 4.17.23 and Express 5.2.1 + @types/express 5.0.6, with no nested Express runtime or type graph.
• Coverage: auth 104 tests (92.99% statements / 89.73% branches); payment 39 tests (97.91% / 98.13%); paymail 82 tests (99.83% / 97.72%); wallet-relay 140 tests (81.24% / 72.97%).
• Mutation: auth-express-bytes 82.67%; payment-replay 95.24%; paymail-address 92.16%; wallet-pairing 89.29%.
• Governance regression: repository health identifies host framework extensions, rejects runtime/type ownership regressions, requires allowlisted package selectors, and requires Express 4/5 clean-consumer tarball QA.
• Generated package/reference docs and facts checks pass.
• Hosted CI: exact-head CI run 30673419660 passed, including all applicable package, consumer, coverage, mutation, security, and merge gates; infrastructure and conformance were correctly skipped by scope.
• Complete diff self-reviewed for correctness, security, compatibility, public API, artifacts, dependencies, docs, and operations
• All applicable checks are terminal and successful on the exact head; scope-based skips are expected and merge-gate validated

Security and dependencies

• Changelog, runtime relevance, peer compatibility, transitive graph, lockfile, and audit results reviewed
• No protocol or trust-boundary behavior changed; existing security, negative, and conformance suites remain selected through the dependency graph
• Exact-head CodeQL has no new alert
• Exact-head Sonar evidence reports zero new/accepted issues and zero unreviewed hotspots
• No override, advisory dismissal, quality suppression, skipped test, or lifecycle-script broadening added
• Workflow permissions remain least privilege

The host framework and its matching declarations are required peers for packages whose root API mounts Express routers/middleware. Wallet Relay keeps them optional because its Express integration is an optional server surface. Development copies remain only for each package's own build/tests. Consumers therefore receive one compatible Express 4 or 5 graph.

Dependency evidence

• Release notes and necessity: all four patch releases correct published host-framework ownership; release notes and migration guidance identify the Express 4/5 peer contract.
• Runtime, build, and peer compatibility: Node remains >=22; exact tarballs compile against both supported Express majors, their matching declarations, strict TypeScript 5.9, and SDK 2.2.17.
• Deduplicated lockfile: regenerated with lifecycle scripts disabled; development Express copies remain local to package QA while published manifests expose host runtime/types only as peers.
• Audit and CodeQL: local high/critical audit is clean; exact-head CodeQL and zero-finding Sonar gates are required before merge.
• Package and consumer tests: 365 package tests across the four packages, ESM/CJS artifact checks, four targeted mutation suites, and eight clean Express-major consumer installations.
• Bundle and performance impact: no runtime protocol branch is added; consumers avoid redundant Express runtime/type installations. CI documentation examples are now limited to the affected first-party closure.
• Affected public package versions: auth-express 2.1.6 -> 2.1.7; payment-express 2.1.4 -> 2.1.5; paymail 2.4.5 -> 2.4.6; wallet-relay 0.3.3 -> 0.3.4.

Release and operations

• No npm publication was performed from a workstation or this PR
• All required package patch bumps are included
• No infrastructure image needs rebuilding for this source-only package change
• Documentation, migration guidance, release notes, and rollback are current

After protected npm publication, downstream p2ppsr consumers will adopt the released versions, validate in CI/staging, and deploy through their owning repositories. Rollback is a consumer version pin; no protocol or persisted-data migration is involved.

Completion evidence

• Review conversations currently resolved; will be rechecked at the exact merge head
• Documentation, migration notes, release notes, and operator guidance are current
• No pending, failed, stale, cancelled, or unexpectedly skipped check remains
• One qualified maintainer approval is sufficient; admin merge is explicitly operator-authorized after all exact-head gates pass

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[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