feat(server-express): add paywall + paywallConfig options

[levalleux-ludo]

Summary

• Adds optional paywall (a PaywallProvider) and paywallConfig to ExpressMiddlewareOptions and MountX402bOptions.
• When supplied and the request's Accept header prefers text/html, the 402 challenge is rendered as an HTML document via paywall.generateHtml(...) (with currentUrl built from ${protocol}://${host}${originalUrl}) instead of the canonical JSON body.
• All other cases (JSON Accept, missing Accept, paywall.supports() returns false, no paywall configured, settle-phase requests) keep the existing JSON challenge unchanged — no regression.

Implementation notes

• A local structural PaywallProviderLike interface in src/internal/x402-challenge.ts keeps @bosonprotocol/x402-paywall an optional integration. Consumers wanting HTML 402s install the paywall package separately; this adapter never imports it at runtime.
• Both expressMiddleware and mountX402b's commit routes funnel through the same shared respondWithChallenge helper, so the content-negotiation rules can't drift between the two entry points.
• A devDep on @bosonprotocol/x402-paywall powers one CI-level smoke test that exercises the real evmEscrowPaywall through the middleware — catches structural drift between PaywallProviderLike here and the upstream PaywallProvider shape.

Notes

• Depends on feat: add @bosonprotocol/x402-paywall package #78 (@bosonprotocol/x402-paywall); base is set accordingly. GitHub will auto-rebase to main once feat: add @bosonprotocol/x402-paywall package #78 (and its own base feat: add initial implementation of x402-client-browser with tests and docs #77) merges.
• The integration test's vitest timeout is bumped to 30 s because dynamically importing the paywall pulls the 4.7 MB CJS bundle and can run slow under parallel turbo workers.

Test plan

• `pnpm --filter @bosonprotocol/x402-server-express build` — clean
• `pnpm --filter @bosonprotocol/x402-server-express test` — 32/32 (22 existing + 10 new)
• Repo-wide `pnpm build` — 16/16 successful
• Repo-wide `pnpm test` — 32/32 successful
• Repo-wide `pnpm lint` — 16/16 successful
• Repo-wide `pnpm format:check` — clean

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a61906ad-15ed-4bab-87e6-131cbe99207c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch add-x402-server-express-paywall

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Adds optional HTML paywall rendering for 402 challenges in @bosonprotocol/x402-server-express, using content negotiation to switch between the canonical JSON x402 challenge body and a paywall-generated HTML document.

Changes:

• Add paywall / paywallConfig options to expressMiddleware and mountX402b and funnel both through a shared respondWithChallenge helper.
• Implement content negotiation in respondWithChallenge to serve text/html via paywall.generateHtml(...) when the request prefers HTML.
• Add a new test suite (including a smoke test using the real @bosonprotocol/x402-paywall) and wire the paywall package as a dev dependency.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
typescript/packages/server-express/test/paywall.test.ts	Adds unit + integration tests for HTML-vs-JSON 402 challenge negotiation and paywall wiring.
typescript/packages/server-express/src/mount.ts	Extends MountX402bOptions with paywall options and routes commit-route 402s through the shared challenge responder.
typescript/packages/server-express/src/middleware.ts	Extends ExpressMiddlewareOptions with paywall options and routes missing-X-PAYMENT 402s through the shared challenge responder.
typescript/packages/server-express/src/internal/x402-challenge.ts	Adds paywall/provider “like” types and implements HTML vs JSON challenge negotiation + currentUrl building.
typescript/packages/server-express/package.json	Adds @bosonprotocol/x402-paywall as a devDependency for the integration smoke test.
pnpm-lock.yaml	Lockfile updates to include the paywall workspace package and its dependency graph changes.
.changeset/server-express-paywall-option.md	Changeset documenting the new options and behavior for the server-express package.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[TateLyman]

Ran a focused code-read on the new browser paywall 402 path. No wallet signing, payment headers, live facilitator calls, or paid calls.

Two launch-risk notes before this is used behind a real domain/CDN:

1. The response now content-negotiates the same URL between JSON and HTML, but the helper does not set Vary: Accept or Cache-Control: no-store on either branch. Because the HTML body contains an injected window.x402b state payload and the JSON branch is the canonical machine challenge, I would make the 402 challenge explicitly non-cacheable and vary on Accept so an intermediary cannot reuse an HTML paywall for an agent/client expecting JSON, or reuse stale requirements for a later request.

2. buildCurrentUrl() uses req.protocol + Host. Behind a TLS-terminating proxy, Express often sees req.protocol === "http" unless trust proxy is configured; the paywall can then inject http://... as the retry URL even though the browser loaded the page over HTTPS. That can break browser retry/mixed-content behavior and can also misalign the URL the buyer retries with the resource URL the seller intended. I would either let callers pass an explicit canonical currentUrl/origin, or document/test the proxy requirement with X-Forwarded-Proto/trusted host handling.

Suggested test additions:

• Accept: text/html response asserts Vary includes Accept and Cache-Control: no-store.
• Proxied request fixture verifies the injected currentUrl stays https://seller.example/... when the app runs behind TLS termination, or confirms the documented override is used.

The feature shape looks useful; these are mostly deployment-boundary issues around browser paywalls and agent-readable 402s.

[levalleux-ludo]

Ran a focused code-read on the new browser paywall 402 path. No wallet signing, payment headers, live facilitator calls, or paid calls.

Two launch-risk notes before this is used behind a real domain/CDN:

1. The response now content-negotiates the same URL between JSON and HTML, but the helper does not set Vary: Accept or Cache-Control: no-store on either branch. Because the HTML body contains an injected window.x402b state payload and the JSON branch is the canonical machine challenge, I would make the 402 challenge explicitly non-cacheable and vary on Accept so an intermediary cannot reuse an HTML paywall for an agent/client expecting JSON, or reuse stale requirements for a later request.
2. buildCurrentUrl() uses req.protocol + Host. Behind a TLS-terminating proxy, Express often sees req.protocol === "http" unless trust proxy is configured; the paywall can then inject http://... as the retry URL even though the browser loaded the page over HTTPS. That can break browser retry/mixed-content behavior and can also misalign the URL the buyer retries with the resource URL the seller intended. I would either let callers pass an explicit canonical currentUrl/origin, or document/test the proxy requirement with X-Forwarded-Proto/trusted host handling.

Suggested test additions:

• Accept: text/html response asserts Vary includes Accept and Cache-Control: no-store.
• Proxied request fixture verifies the injected currentUrl stays https://seller.example/... when the app runs behind TLS termination, or confirms the documented override is used.

The feature shape looks useful; these are mostly deployment-boundary issues around browser paywalls and agent-readable 402s.

Thanks @TateLyman
I really appreciate your contribution

[levalleux-ludo]

Thanks @TateLyman — both remarks were fully valid and we've folded them into this PR in ff34cbd.

1. Vary: Accept + Cache-Control: no-store. Confirmed: the 402 body carries per-request signature state (offer.sellerSig, single-use token-auth nonces) and the HTML branch injects the full requirements into window.x402b — definitely not cache-safe. The spec itself flags this in docs/boson-impl-01-escrow-scheme.md (caching is explicitly deferred until EscrowPaymentRequirements gains an absolute expiresAt). respondWithChallenge now stamps both headers on both branches before writing the body, set once at the top so the rule can't drift between HTML and JSON. New assertions on each branch lock the contract in.

2. req.protocol behind a TLS-terminating proxy. Confirmed — Express only honors X-Forwarded-Proto when app.set('trust proxy', ...) is configured, and we documented neither path. Two-pronged fix:

• JSDoc on the paywall option in both ExpressMiddlewareOptions and MountX402bOptions now recommends app.set('trust proxy', ...) and explains why (the window.x402b.currentUrl retry URL would otherwise come back as http:// from an HTTPS-loaded page and hit mixed-content blocking).
• New currentUrl?: string | ((req) => string) option on both adapter entry points lets deployments pin the canonical retry URL explicitly when trust proxy alone isn't sufficient (e.g. when the public origin differs from what reaches Express, or when you want the retry URL pinned to a fixed checkout endpoint).

Both of your suggested tests are in: cache-header assertions on each branch, a trust proxy + X-Forwarded-Proto: https fixture, and string + resolver fixtures for the currentUrl override.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

[TateLyman]

Thanks Ludo. The two patch directions look right from the PR readback: Vary: Accept plus Cache-Control: no-store is now centralized on the 402 response path, and the currentUrl override / trust-proxy docs cover the TLS-termination case. That closes the two deployment-boundary notes I raised. Scope here was code-read only; I did not sign requests, send payment headers, hit live facilitators, or attempt paid calls.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 4 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported