server-node should serve client/fcaptcha.js by default (single-origin widget delivery)

[PanoramicRum]

Problem

FCaptcha ships two halves of the integration in one repo:

• server-node/server.js (and server-python/, server-go/) — exposes the API: /health, /api/verify, /api/score, /api/token/verify, /api/pow/challenge, /api/challenge.
• client/fcaptcha.js — the 98 KB browser widget that collects behavioural signals, calls /api/challenge, solves the PoW, and returns a token.

The browser needs client/fcaptcha.js. None of the server implementations serve it. So an operator who deploys server-node is missing the widget bundle that every consumer expects to be reachable at the same origin as the API.

Why it's a problem in practice

Consumers (e.g. anti-abuse libraries that integrate FCaptcha) typically expose a single serverUrl to clients, and the browser fetches the widget from <serverUrl>/fcaptcha.js. That implicit contract — "your FCaptcha deployment serves both the API and the widget at one origin" — is what most integrators expect. Today, every operator has to either:

1. Bundle client/fcaptcha.js into their own frontend (extra build step per integrator).
2. Host it as a static asset on a separate origin (CDN / nginx) and rewire the integration to point at that.
3. Patch the server.

I just hit this in PanoramicRum/nimiq-simple-faucet#113 and worked around it with a one-line sed injection in our Dockerfile that adds app.use('/fcaptcha.js', express.static('/app/client/fcaptcha.js')). Verified it works end-to-end (faucet → fcaptcha widget loads inside Nimiq Pay's WebView over LAN).

Suggested fix

Implicit by default, opt-out via env.

• Server serves /fcaptcha.js from client/fcaptcha.js automatically. Zero config. Most consumers benefit immediately, and the implicit single-origin contract gets honoured.
• An env var (FCAPTCHA_SERVE_CLIENT=false) lets operators turn it off if they prefer to host the widget on a CDN / edge cache and serve it themselves. Rare case; opt-out keeps it simple.

Three-line change in server-node/server.js:

const path = require('path');
// ...
if (process.env.FCAPTCHA_SERVE_CLIENT !== 'false') {
  app.use('/fcaptcha.js', express.static(path.join(__dirname, '..', 'client', 'fcaptcha.js')));
}

Same idea applies to server-python and server-go for parity.

Docs change

Even with this merged, INSTALLATION.md should explicitly document the layering — both the implicit single-origin default and the CDN-hosting escape hatch. Today the README and INSTALLATION.md don't say anything about how the widget bundle reaches the browser, which is why every integrator hits this.

Happy to send a PR

I can send a PR for server-node with the change above plus the INSTALLATION.md note. Wanted to file this first so you can push back on the design (FCAPTCHA_SERVE_CLIENT name, default value, opt-in vs opt-out) before I write code. Parity changes for server-python and server-go can follow as separate PRs.

Found while integrating FCaptcha into a Nimiq Pay Mini App — full integration notes at PanoramicRum/nimiq-simple-faucet#113.

[PanoramicRum]

Quick follow-up: I've drafted the server-node change on a branch in my fork: PanoramicRum/FCaptcha:serve-client-bundle. Two files changed (server-node/server.js + INSTALLATION.md), 23 insertions, 0 deletions. Verified locally: default serves /fcaptcha.js (HTTP 200, ~98 KB) and leaves /health and the API untouched; FCAPTCHA_SERVE_CLIENT=false opts out cleanly.

Holding off opening the PR until you've reacted to the design here. I'd rather amend the branch than ask you to argue against a default in PR review. The two open questions:

1. Opt-out vs opt-in. I drafted it as opt-out (FCAPTCHA_SERVE_CLIENT=false to disable) because that delivers the implicit-single-origin contract to existing consumers without requiring config. Happy to flip to opt-in (FCAPTCHA_SERVE_CLIENT=true to enable) if you'd prefer the more conservative default for downstreams who haven't asked for the new route — one-line change either way.
2. Env var name. FCAPTCHA_SERVE_CLIENT was a guess; rename to taste. Anything matching your existing env-var conventions works.

Whatever you'd prefer, I'll amend the branch and then open the PR. Or just say "open it" and I will.

Out of scope for this draft: server-python and server-go parity. Happy to send those as separate PRs once the shape here is approved.