docs: design v0.4.0 HTTP MCP transport and auth

[marmar9615-cloud]

First step toward v0.4.0 — opt-in HTTP MCP transport with
authentication and Origin validation. Docs only. No runtime
change. stdio remains the default.

Refs #22.

Summary

• Adds full design doc: docs/designs/http-mcp-transport-auth.md
  covering transport modes, env vars, bearer-auth model, Origin /
  CORS rules, host binding, the shared dispatcher architecture
  (createMcpServer() factory), audit-event extension, testing
  plan, migration plan, decision log, and open questions.
• Adds companion ADR: docs/adr/0001-http-mcp-transport.md.
• Adds in-tree mirror of the GitHub tracking issue at
  docs/issues/v0.4.0-http-transport-auth.md
  so future PRs can link to a stable path even if issue v0.4.0 — HTTP MCP transport + auth #22 ever
  gets renumbered.
• Adds a tiny scaffolding directory at
  apps/mcp-server/src/transports/README.md
  — empty landing pad for the implementation PRs. Not imported
  anywhere; tsup does not pick it up; the published tarball is
  unchanged (verified via npm run pack:dry-run).
• Updates docs/roadmap.md — v0.3.0 marked
  shipped; v0.4.0 design line marked in flight.
• Updates docs/v1-readiness.md —
  status block reflects v0.3.0 published + v0.4.0 in flight;
  criteria build(deps): bump zod from 3.25.76 to 4.3.6 #8 and build(deps): bump marked from 14.1.4 to 18.0.2 #9 marked design-complete.
• Updates docs/threat-model.md — T14
  ("Future HTTP transport risks") links to the design and lists
  the concrete mitigations the design commits to.
• Updates docs/production-readiness.md
  — "MCP HTTP mode (planned)" becomes "designed; implementation
  pending" with headline properties.
• Updates docs/security-configuration.md
  — adds a forthcoming-env-vars section for AGENTBRIDGE_HTTP_*;
  keeps the v0.3.0 table intact.
• Updates README.md / AGENTS.md /
  CLAUDE.md — status reflects v0.3.0 shipped +
  v0.4.0 design in flight; references to the new design doc and
  ADR added.

What this PR is not

• No HTTP server implementation. The runtime stdio behavior
  is bit-for-bit unchanged.
• No package version bump. Per the design's migration plan,
  versions move to 0.4.0 in the follow-up implementation PR
  series — not now.
• No npm publish. No tag. No GitHub release.
• Dependabot PRs untouched. No merges, no edits.
• No safety regression. Confirmation gate, origin pinning,
  target-origin allowlist, audit redaction, loopback default,
  simulated destructive demo actions — all unchanged.

Verification commands

npm run typecheck:clean   # green
npm test                  # 121/121 green on Node 24
npm run build             # all six packages OK
npm run pack:dry-run      # all six tarballs OK at 0.3.0

Test plan

• npm run typecheck:clean passes locally.
• npm test — 121/121 tests pass locally.
• npm run build — all six publishable packages build.
• npm run pack:dry-run — all six tarballs OK at 0.3.0; no
  file-count changes (the source-tree
  apps/mcp-server/src/transports/README.md is correctly
  excluded from the published tarball per the package's
  files allowlist).
• CI (Node 20.x and 22.x) green on this PR.
• Main CI green after merge.

Recommended follow-ups (not part of this PR)

Per the migration plan in the design doc:

1. Implementation PR 1 — transport abstraction. Extract a
   createMcpServer() factory in apps/mcp-server/src/server.ts
   and refactor the stdio entry to call it. Zero behavior change.
2. Implementation PR 2 — HTTP transport + bearer auth. Wire
   StreamableHTTPServerTransport from
   @modelcontextprotocol/sdk behind auth + Origin + bind
   checks; add the AGENTBRIDGE_HTTP_* env vars.
3. Implementation PR 3 — docs / examples / smoke tests.
   examples/http-client-config/, security-configuration table,
   updated mcp-client-setup recipes.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0c43aba3af

ℹ️ 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]

Clarify 0.0.0.0 handling in public-bind predicate

This rule is internally inconsistent: it first describes hosts outside {127.0.0.1, ::1, localhost, 0.0.0.0} as potentially public, then immediately says 0.0.0.0 is treated as public. If implementation follows the set membership literally, wildcard bind can be misclassified and skip the startup fail-hard checks for auth/origin. Please rewrite this as an unambiguous predicate (e.g., loopback-only allowlist, with 0.0.0.0 explicitly non-loopback/public).

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Align public-bind Origin requirement with ADR/design

This requirement says missing AGENTBRIDGE_HTTP_ALLOWED_ORIGINS on public bind may "warn or fail," but the new ADR/design in this same commit commit to fail-hard behavior for public bind without an Origin allowlist. Keeping a weaker requirement in the tracking issue creates conflicting guidance for implementation PRs and can lead to shipping a warning-only path that weakens the intended security posture.

Useful? React with 👍 / 👎.