feat(mcp-server): add opt-in HTTP transport with bearer auth

[marmar9615-cloud]

v0.4.0 implementation PR 2 — opt-in Streamable HTTP MCP transport
with static bearer-token auth, exact-origin allowlist, and
loopback-by-default bind. stdio remains the default and only
runtime transport unless an operator explicitly sets
AGENTBRIDGE_TRANSPORT=http.

Refs #22. Design: docs/designs/http-mcp-transport-auth.md.
Predecessor PRs: #23 (design), #24 (transport abstraction).

Codex parallel context: #25 (docs/examples PR) merged while this work was in progress. This branch was rebased cleanly onto the new main; no Codex PR #25 file was modified.

Summary

• Wraps StreamableHTTPServerTransport from @modelcontextprotocol/sdk behind:
  • bearer-token auth (constant-time compare; Authorization: Bearer <token> only; query-string tokens rejected with 400),
  • Origin header allowlist (exact URL.origin match; no wildcard, no prefix),
  • loopback-by-default bind (127.0.0.1); public bind requires both auth and a non-empty Origin allowlist or fails closed at startup,
  • request-body size cap (reuses AGENTBRIDGE_MAX_RESPONSE_BYTES),
  • OPTIONS preflight (only for allowed origins; Access-Control-Allow-Origin always echoes the exact origin — never wildcard with credentials).
• Reuses the v0.4.0 PR refactor(mcp-server): prepare transport abstraction for HTTP #24 createMcpServer() factory. Auth/Origin/bind checks sit in front of transport.handleRequest(); the dispatcher in server.ts and the safety code in safety.ts stay transport-agnostic.
• Endpoint: POST /mcp. JSON responses (no SSE in v0.4.0). Stateless mode.

Env vars added

Env var	Default	Purpose
AGENTBRIDGE_TRANSPORT	stdio	stdio | http. Unknown values fall back to stdio with stderr warning.
AGENTBRIDGE_HTTP_HOST	127.0.0.1	Bind interface. Loopback default; non-loopback is "public bind" with extra validation.
AGENTBRIDGE_HTTP_PORT	3333	TCP port. 0 = ephemeral (used by tests). Range 0–65535.
AGENTBRIDGE_HTTP_AUTH_TOKEN	unset	Required for http mode. Static bearer token. ≥ 16 chars. Never logged, never echoed.
AGENTBRIDGE_HTTP_ALLOWED_ORIGINS	unset	Comma-separated inbound Origin allowlist; required for non-loopback bind.

The inbound AGENTBRIDGE_HTTP_ALLOWED_ORIGINS is independent from the outbound AGENTBRIDGE_ALLOWED_TARGET_ORIGINS. Documented in docs/security-configuration.md and the design doc.

Auth behavior

• Missing Authorization → 401 (with WWW-Authenticate: Bearer realm="agentbridge-mcp").
• Malformed Authorization (e.g. Basic) → 401.
• Wrong bearer token → 401. Constant-time compare; tokens length-padded so timing leaks don't reveal length. Response body never echoes either token.
• Token in URL query string (?token=, ?access_token=, ?bearer=, ?auth=, ?authorization=) → 400 token_in_query_string. Rejected before any tool runs.
• Valid bearer + initialize → 200 with the same serverInfo {agentbridge, 0.3.0} and tools/list as stdio.
• The bearer token never appears in stderr, response bodies, or thrown error messages.

Origin / CORS behavior

• Request with Origin not in allowlist → 403 forbidden_origin.
• Request with no Origin (CLI/server clients) → allowed if bearer is valid; no Access-Control-* headers in the response.
• Allowed Origin → response includes Access-Control-Allow-Origin: <exact origin> + Access-Control-Allow-Credentials: true + Vary: Origin. Never * with credentials.
• OPTIONS preflight from unknown Origin → 403.
• OPTIONS preflight from allowed Origin → 204 with safe CORS headers.
• Prefix-attack and port-mismatch Origins are rejected (covered by tests).

Host binding behavior

• AGENTBRIDGE_HTTP_HOST defaults to 127.0.0.1 (loopback). No special checks beyond auth.
• Non-loopback host (0.0.0.0, 10.0.0.5, etc.) is "public bind". validateHttpStartup:
  • throws AGENTBRIDGE_HTTP_AUTH_TOKEN is required … when token missing,
  • throws Public bind to <host> requires AGENTBRIDGE_HTTP_ALLOWED_ORIGINS to be set … when origins missing.
• Successful non-loopback start emits a one-line stderr notice: [agentbridge-mcp-http] non-loopback bind to <host> — auth and Origin allowlist are required and have been verified.

Tests added

File	Cases	Covers
http-config.test.ts	23	AGENTBRIDGE_TRANSPORT default + parsing; HTTP env-var defaults, ranges, clamping; origin normalization; malformed origins; inbound-vs-outbound separation.
http-transport.test.ts	26	Real HTTP server on ephemeral port. Auth (missing/malformed/wrong/valid + query-string + token-never-leaks). Origin (unknown / prefix attack / port mismatch / allowed / no-Origin / OPTIONS). Host binding (loopback default; non-loopback warning; public bind fail-closed). Endpoint routing (404 / 400 / 413).

Existing 125 tests continue to pass: stdio-hygiene 3/3, call-action 10/10, safety 20/20, server-factory 4/4, config 11/11, plus 92 cross-package suites. 174/174 green.

Verification

npm run typecheck:clean   # green
npm test                  # 174/174 green (125 prior + 23 http-config + 26 http-transport)
npm run build             # six packages OK; mcp-server bundle 40.3 KB ESM
npm run pack:dry-run      # six tarballs OK at 0.3.0; file counts unchanged
node apps/mcp-server/dist/index.js < /dev/null   # stdio: clean exit 0
# stdio JSON-RPC smoke (initialize + tools/list) — serverInfo + tool list
#   byte-identical to pre-PR2 binary; stderr empty.
# HTTP smoke (port 0 ephemeral; tests live in /tmp/http-smoke.mjs locally):
#   no-auth     → 401 unauthorized (missing Authorization)
#   wrong-token → 401 unauthorized (invalid bearer token)
#   query-token → 400 token_in_query_string
#   bad-origin  → 403 forbidden_origin
#   auth-init   → 200 + serverInfo {agentbridge, 0.3.0}; stderr never contained the token.
# HTTP startup safety:
#   AGENTBRIDGE_TRANSPORT=http (no token) → exit 1, fatal: "AGENTBRIDGE_HTTP_AUTH_TOKEN is required"
#   public bind without origins           → exit 1, fatal: "Public bind ... requires AGENTBRIDGE_HTTP_ALLOWED_ORIGINS"

Confirmations

• ✅ stdio remains the default. No HTTP runs unless AGENTBRIDGE_TRANSPORT=http.
• ✅ HTTP requires auth; public bind requires both auth and Origin allowlist.
• ✅ Tokens in URL query strings rejected with 400.
• ✅ Bearer token never logged, never echoed, never in error messages.
• ✅ Constant-time bearer comparison via crypto.timingSafeEqual.
• ✅ Confirmation gate, origin pinning (outbound), target-origin allowlist, idempotency, audit redaction, simulated destructive demo actions — all unchanged.
• ✅ Stdout hygiene preserved in stdio mode (verified by stdio-hygiene.test.ts 3/3 + a fresh JSON-RPC subprocess smoke).
• ✅ No package versions changed (still 0.3.0). Lockstep bump to 0.4.0 lands with implementation PR 3 per the design's migration plan.
• ✅ No npm publish, no git tag, no GitHub release.
• ✅ Dependabot PRs untouched.
• ✅ Codex PR docs: add adopter quickstart and manifest patterns #25 untouched. This branch was rebased cleanly onto 4929f14.

Test plan

• npm run typecheck:clean green locally.
• npm test — 174/174 green locally.
• npm run build — six packages OK.
• npm run pack:dry-run — six tarballs OK at 0.3.0; file counts unchanged.
• stdio smoke against built dist — bit-identical to pre-PR2.
• HTTP smoke against built dist — auth, origin, query-token, public-bind invariants verified end-to-end.
• CI green on Node 20.x and 22.x.
• Main CI green after merge.
• release-check green on main.

Recommended next PR

v0.4.0 implementation PR 3 — HTTP docs/examples/smoke polish + lockstep version bump to 0.4.0, then release readiness.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: eb030b5843

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Normalize bracketed IPv6 bind host before listen

This call passes opts.host straight into server.listen, but resolveHttpConfig/LOOPBACK_HOSTS treats [::1] as a valid loopback host. In Node, bracketed IPv6 is URL syntax, not a valid listen host, so AGENTBRIDGE_HTTP_HOST=[::1] fails startup with ENOTFOUND instead of binding loopback. Either strip brackets before listen or reject bracketed hosts with a clear validation error.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Include CORS headers on unauthorized responses

For requests from an allowed Origin, this branch returns 401 before any Access-Control-Allow-Origin headers are written (those are only added later on the success path). In browser-based MCP clients, that turns auth failures into generic CORS errors, so callers cannot read the JSON error/status to handle token refresh or diagnose bad credentials. Mirror the allowed-origin CORS headers on 401/other error responses after origin validation passes.

Useful? React with 👍 / 👎.