docs: design v0.4.0 HTTP MCP transport and auth

AGENTS.md

@@ -22,10 +22,17 @@ The repo ships:
 ## Current state
 
 - npm scope: **`@marmarlabs`** (do not change).
-- Latest published release: **v0.2.2** on npm and on GitHub
-  (Latest, stable). v0.3.0 is in progress on this branch
-  ("Production Foundations" — docs, stricter remote allowlist,
-  configurable bounds, draft Trusted Publishing workflow).
+- Latest published release: **v0.3.0** on npm and on GitHub
+  (Latest, stable; published via npm Trusted Publishing with SLSA
+  build provenance). The v0.2.x line shipped first public release,
+  docs cleanup, and Codex onboarding; v0.3.0 added production
+  foundations (stricter remote allowlist, configurable bounds,
+  Trusted Publishing workflow, threat model, v1.0 readiness
+  checklist, stdout-hygiene test).
+- Currently in flight: **v0.4.0** — opt-in HTTP MCP transport with
+  authentication and Origin validation. stdio remains the default.
+  Design in [docs/designs/http-mcp-transport-auth.md](docs/designs/http-mcp-transport-auth.md);
+  ADR in [docs/adr/0001-http-mcp-transport.md](docs/adr/0001-http-mcp-transport.md).
 - Manifest schema: v0.1, stable for the v0.x line. Will be frozen
   for v1.x per [docs/v1-readiness.md](docs/v1-readiness.md).
 
@@ -163,7 +170,11 @@ If a change weakens any of these, stop and ask before continuing.
   — every env var the MCP server honors.
 - [docs/trusted-publishing.md](docs/trusted-publishing.md) — npm
   Trusted Publishing plan and draft workflow.
+- [docs/designs/http-mcp-transport-auth.md](docs/designs/http-mcp-transport-auth.md)
+  — v0.4.0 HTTP MCP transport + auth design.
+- [docs/adr/0001-http-mcp-transport.md](docs/adr/0001-http-mcp-transport.md)
+  — ADR for the HTTP transport decision.
 - [docs/roadmap.md](docs/roadmap.md) — what's planned beyond v0.3.x
-  (signed manifests, HTTP MCP transport, OAuth scope enforcement,
+  (HTTP MCP transport, signed manifests, OAuth scope enforcement,
   distributed audit storage, …).
 - [SECURITY.md](SECURITY.md) — how to report security issues.

CLAUDE.md

@@ -173,3 +173,7 @@ Every new feature ships with a test. Categories of tests we currently maintain:
   every MCP server env var.
 - [docs/trusted-publishing.md](docs/trusted-publishing.md) — the npm
   publishing path toward v1.0 (Trusted Publishing + provenance).
+- [docs/designs/http-mcp-transport-auth.md](docs/designs/http-mcp-transport-auth.md)
+  — v0.4.0 HTTP MCP transport + auth design.
+- [docs/adr/0001-http-mcp-transport.md](docs/adr/0001-http-mcp-transport.md)
+  — ADR for adding the opt-in HTTP MCP transport.

README.md

@@ -11,7 +11,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Next.js](https://img.shields.io/badge/Next.js-15-black?logo=next.js&logoColor=white)](https://nextjs.org/)
 [![MCP](https://img.shields.io/badge/MCP-1.0-orange)](https://modelcontextprotocol.io)
-[![Status: v0.2.2](https://img.shields.io/badge/Status-v0.2.2-blue)]()
+[![Status: v0.3.0](https://img.shields.io/badge/Status-v0.3.0-blue)]()
 [![npm](https://img.shields.io/npm/v/@marmarlabs/agentbridge-sdk?label=%40marmarlabs%2Fagentbridge-sdk)](https://www.npmjs.com/package/@marmarlabs/agentbridge-sdk)
 
 </div>
@@ -20,15 +20,21 @@
 
 ## Status
 
-**AgentBridge v0.2.2 is live on npm under the `@marmarlabs` scope.**
-v0.2.0 was the first public release, v0.2.1 was a docs-only cleanup
-patch, and v0.2.2 adds first-class OpenAI Codex onboarding.
-**v0.3.0 (in flight)** adds production-foundation work — a stricter
-remote-target allowlist, configurable timeouts/TTLs, an MCP stdout
-hygiene test, a draft npm Trusted Publishing workflow, and a v1.0
-readiness checklist (see [docs/v1-readiness.md](docs/v1-readiness.md)).
-v0.3.0 is **not** v1.0 production readiness — it's the foundation
-for it.
+**AgentBridge v0.3.0 is live on npm under the `@marmarlabs` scope**
+(published via npm Trusted Publishing with SLSA build provenance).
+The v0.2.x line shipped the first public release, a docs cleanup
+patch, and OpenAI Codex onboarding; v0.3.0 added production-
+foundation work — a stricter remote-target allowlist, configurable
+timeouts/TTLs, an MCP stdout-hygiene test, the Trusted Publishing
+workflow, a security threat model, and the v1.0 readiness
+checklist (see [docs/v1-readiness.md](docs/v1-readiness.md)).
+**v0.4.0 (in flight)** adds an opt-in HTTP MCP transport with
+authentication and Origin validation while preserving stdio as the
+default — see
+[docs/designs/http-mcp-transport-auth.md](docs/designs/http-mcp-transport-auth.md)
+and [docs/adr/0001-http-mcp-transport.md](docs/adr/0001-http-mcp-transport.md).
+Neither v0.3.0 nor v0.4.0 alone is v1.0 production readiness;
+both are steps toward it.
 
 ```bash
 npm install @marmarlabs/agentbridge-sdk @marmarlabs/agentbridge-core
@@ -44,11 +50,13 @@ distributed audit storage are roadmap items (see
 [docs/roadmap.md](docs/roadmap.md)). Destructive demo actions remain
 simulated.
 
-For release notes, see [docs/releases/v0.2.2.md](docs/releases/v0.2.2.md)
+For release notes, see [docs/releases/v0.3.0.md](docs/releases/v0.3.0.md)
 for the current release,
-[docs/releases/v0.2.1.md](docs/releases/v0.2.1.md) for the docs cleanup
-patch, and [docs/releases/v0.2.0.md](docs/releases/v0.2.0.md) for the
-first public release.
+[docs/releases/v0.2.2.md](docs/releases/v0.2.2.md) for the Codex
+onboarding release,
+[docs/releases/v0.2.1.md](docs/releases/v0.2.1.md) for the docs
+cleanup patch, and [docs/releases/v0.2.0.md](docs/releases/v0.2.0.md)
+for the first public release.
 
 ---
 
@@ -860,6 +868,8 @@ CI runs `npm install`, typecheck, all tests, and Next.js builds on Node 20.x and
 | [docs/threat-model.md](docs/threat-model.md) | Full threat catalogue with current mitigations and v1.0 targets. |
 | [docs/security-configuration.md](docs/security-configuration.md) | Every env var the MCP server honors, with defaults, ranges, and recipes. |
 | [docs/trusted-publishing.md](docs/trusted-publishing.md) | npm Trusted Publishing plan and the draft `release-publish.yml` workflow. |
+| [docs/designs/http-mcp-transport-auth.md](docs/designs/http-mcp-transport-auth.md) | v0.4.0 HTTP MCP transport + auth design. |
+| [docs/adr/0001-http-mcp-transport.md](docs/adr/0001-http-mcp-transport.md) | ADR for adding the opt-in HTTP MCP transport. |
 | [docs/roadmap.md](docs/roadmap.md) | What's shipped, what's next. |
 | [spec/agentbridge-manifest.v0.1.md](spec/agentbridge-manifest.v0.1.md) | The manifest specification. |
 | [AGENTS.md](AGENTS.md) | Short, model-neutral working notes for any AI coding agent (Codex, Claude, Cursor, custom). |
@@ -876,7 +886,7 @@ Near-term, in rough priority order:
 - **Signed manifests.** A published manifest carries a publisher signature an agent can verify offline. Removes the need to trust the host you're talking to.
 - **Standardized risk taxonomy.** Move from `low | medium | high` to a richer model: `read`, `write-self`, `write-others`, `financial`, `irreversible`. Lets agents reason about action consequences more precisely.
 - **Policy primitives.** First-class support for cost caps, rate limits, business-hours gating, and N-of-M approver workflows declared *in the manifest*.
-- **HTTP MCP transport.** stdio works for desktop clients; production agents need an authenticated HTTP transport.
+- **HTTP MCP transport.** stdio works for desktop clients; production agents need an authenticated HTTP transport. The v0.4.0 design is in [docs/designs/http-mcp-transport-auth.md](docs/designs/http-mcp-transport-auth.md).
 - **Cross-app workflows.** Let an agent compose actions from multiple AgentBridge surfaces with consistent confirmation semantics across them.
 - **Browser fallback + auto-generation.** When a site doesn't publish a manifest, run a Playwright probe and *generate* a starter manifest from visible buttons and forms — give app teams a one-click on-ramp.
 - **Manifest registry.** Optional public index of manifests so agents can discover what surfaces exist for a given task ("find me an app that can refund a Stripe charge").

apps/mcp-server/src/transports/README.md

@@ -0,0 +1,54 @@
+# `apps/mcp-server/src/transports/`
+
+Reserved landing pad for the v0.4.0 HTTP MCP transport
+implementation. Empty on purpose.
+
+## Why this directory exists now
+
+The v0.4.0 design PR (docs-only) creates this directory so the
+follow-up implementation PRs have an obvious home and reviewers
+have a concrete file path to look for. **Nothing in here is
+imported from `index.ts`. There is no runtime effect.**
+
+## What lands here
+
+Per [`docs/designs/http-mcp-transport-auth.md`](../../../../docs/designs/http-mcp-transport-auth.md):
+
+1. **PR 1 — transport abstraction.** A `createMcpServer()` factory
+   in `../server.ts` (or similar). The two transport entry points
+   (`stdio.ts` and `http.ts`) live here. stdio is refactored to
+   call the factory; behavior unchanged.
+2. **PR 2 — HTTP transport + bearer auth.** `http.ts` wires
+   `StreamableHTTPServerTransport` from `@modelcontextprotocol/sdk`
+   behind an auth + Origin + bind check. New env vars
+   (`AGENTBRIDGE_HTTP_*`) parsed in `../config.ts`.
+3. **PR 3 — docs / examples / smoke tests.** Updates
+   [`docs/security-configuration.md`](../../../../docs/security-configuration.md),
+   [`docs/mcp-client-setup.md`](../../../../docs/mcp-client-setup.md),
+   and adds an `examples/http-client-config/` directory.
+
+## Hard rules for the implementation
+
+These are restated from the design doc and the ADR
+([`docs/adr/0001-http-mcp-transport.md`](../../../../docs/adr/0001-http-mcp-transport.md)):
+
+- stdio remains the default. No regression in the stdio path is
+  acceptable.
+- HTTP requires authentication. No unauthenticated remote HTTP.
+  Public bind without auth fails hard at startup.
+- Tokens go in the `Authorization: Bearer <token>` header. Tokens
+  in URL query strings are rejected with `400`.
+- `Origin` header validation is exact-origin match against
+  `AGENTBRIDGE_HTTP_ALLOWED_ORIGINS`. No prefix match, no
+  wildcard.
+- Default bind is `127.0.0.1`. Public bind requires both auth and
+  an Origin allowlist.
+- The dispatcher is shared. The same `callAction` /
+  `confirmations` / `safety` / `audit` / `idempotency` code paths
+  serve both transports. Auth and Origin live **in front of**
+  `transport.handleRequest()`, not inside the dispatcher.
+- Bearer token values never appear in audit, in stderr, or in
+  HTTP error bodies.
+
+If a change here weakens any of those, stop and reread the design
+doc and the ADR before continuing.

docs/adr/0001-http-mcp-transport.md

@@ -0,0 +1,189 @@
+# ADR 0001 — Add an opt-in HTTP MCP transport
+
+- **Status.** Proposed (v0.4.0 design phase).
+- **Date.** 2026-04-28.
+- **Deciders.** AgentBridge maintainers; tracked in
+  [issue #22](https://github.com/marmar9615-cloud/agentbridge-protocol/issues/22)
+  and [`docs/issues/v0.4.0-http-transport-auth.md`](../issues/v0.4.0-http-transport-auth.md).
+- **Companion design doc.** [`docs/designs/http-mcp-transport-auth.md`](../designs/http-mcp-transport-auth.md).
+
+## Context
+
+AgentBridge currently exposes its MCP server only over stdio
+([`apps/mcp-server/src/index.ts`](../../apps/mcp-server/src/index.ts)).
+stdio is the right default for local desktop MCP clients (Codex,
+Claude Desktop, Cursor, custom): no listening socket, no TLS, no
+auth dance, credentials sourced from env vars handed to the
+subprocess.
+
+The MCP specification, however, defines two transports — **stdio**
+and **Streamable HTTP** — and hosted/centralized agent platforms
+cannot launch a local subprocess. Without an HTTP transport, those
+platforms can only reach AgentBridge through ad-hoc bridges, which
+defeats the safety guarantees we're building.
+
+Three constraints frame the decision:
+
+1. **Stdio must keep working unchanged.** Existing local installs
+   are the active user base.
+2. **HTTP must be safe by default.** The threat surface of an HTTP
+   transport is materially larger than stdio (network reachability,
+   browser CORS, credential exposure, multi-tenant collisions). v0.3.0
+   established the safety story (loopback default, exact-origin
+   allowlist, stdout hygiene, threat model); HTTP transport must
+   inherit that posture, not weaken it.
+3. **No production-readiness regression.** Shipping HTTP transport
+   does not by itself satisfy the v1.0 criteria in
+   [`docs/v1-readiness.md`](../v1-readiness.md), but it must not
+   set those criteria back either.
+
+## Decision
+
+AgentBridge will add an **opt-in Streamable HTTP MCP transport** in
+the v0.4.0 release line, alongside the existing stdio transport,
+with the following non-negotiable properties:
+
+1. **stdio remains the default.** No flag or env var change is
+   required for existing users. `AGENTBRIDGE_TRANSPORT=stdio` is
+   the implicit default; the same `npx -y
+   @marmarlabs/agentbridge-mcp-server` invocation continues to
+   work.
+2. **HTTP mode is opt-in.** Operators turn it on explicitly with
+   `--transport http` or `AGENTBRIDGE_TRANSPORT=http`.
+3. **HTTP requires authentication.** Phase 1 is a static bearer
+   token sourced from `AGENTBRIDGE_HTTP_AUTH_TOKEN`, presented in
+   the `Authorization: Bearer <token>` header. Tokens in URL query
+   strings are rejected with `400`.
+4. **HTTP validates the `Origin` header.** When `Origin` is
+   present, exact-origin match against
+   `AGENTBRIDGE_HTTP_ALLOWED_ORIGINS` (no prefix matching, no
+   wildcard). Unknown origins respond `403`.
+5. **HTTP binds to `127.0.0.1` by default.** Public bind requires
+   both auth and an Origin allowlist; the server fails hard at
+   startup if either is missing.
+6. **Tool dispatch is shared.** Both transports use the exact same
+   tool implementations, confirmation gate, origin pinning,
+   target-origin allowlist, idempotency, and audit redaction. No
+   parallel safety paths.
+7. **Audit events distinguish transports.** Events gain a
+   `transport` field and an optional `caller` block. Bearer token
+   values never appear in audit, ever.
+8. **OAuth 2.1 is designed-for, not implemented.** v0.4.0 ships
+   the static-bearer mode; the design leaves room for a JWT/OAuth
+   resource-server mode in a later release without breaking the
+   v0.4 surface.
+
+## Consequences
+
+### Positive
+
+- Hosted and centralized agent platforms can integrate without an
+  ad-hoc bridge.
+- The safety story we established in v0.3.0 (loopback default,
+  exact-origin allowlist, stdout hygiene, threat model) extends
+  cleanly to HTTP — we add new checks in front of the existing
+  dispatcher, not new branches inside it.
+- The `createMcpServer()` factory clarifies the shape of the
+  server and unblocks future consumers (custom transports,
+  embedded usage).
+- v1.0 criterion #8 (HTTP MCP transport) becomes satisfiable.
+- Threat model T14 ("Future HTTP transport risks") gains concrete
+  mitigations.
+
+### Neutral
+
+- New env vars (`AGENTBRIDGE_HTTP_*`). They are additive and live
+  on a documented namespace separate from
+  `AGENTBRIDGE_ALLOWED_TARGET_ORIGINS` so the inbound/outbound
+  distinction is unambiguous.
+- The audit event shape grows by two optional fields. Backwards-
+  compatible for readers; documented in `core`'s schemas when the
+  implementation lands.
+
+### Negative
+
+- Increased surface area for the MCP server: a listening socket,
+  an HTTP request handler, CORS, session lifecycle. Each is a
+  potential vulnerability.
+- More configuration knobs operators must understand. We mitigate
+  with conservative defaults (loopback, auth required) and a
+  table in [`docs/security-configuration.md`](../security-configuration.md)
+  when the implementation lands.
+- Bearer-token rotation operationally falls on the operator. We
+  document `openssl rand -hex 32` and a "rotate by restart"
+  recipe; first-class rotation is a v0.4.x follow-up.
+- A class of mistakes (forgetting to set
+  `AGENTBRIDGE_HTTP_AUTH_TOKEN` while binding publicly) gets
+  caught at startup, not at request time. The fail-hard behavior
+  is explicit.
+
+## Alternatives considered
+
+### A. stdio only
+
+Defer HTTP indefinitely; tell operators to run a separate proxy
+or fork a custom transport.
+
+- **Rejected** because it pushes integration cost onto every
+  hosted-MCP user and forces ad-hoc bridges that won't share our
+  safety code path.
+
+### B. HTTP without authentication
+
+Ship HTTP with no auth, document loud warnings, rely on
+network-layer controls (firewalls, VPNs).
+
+- **Rejected** because it inverts the v0.3.0 safety posture. An
+  unauthenticated HTTP MCP endpoint is equivalent to remote shell
+  access for any agent that can reach it. Network controls are a
+  defense in depth, not a substitute for app-level auth.
+
+### C. Full OAuth 2.1 in v0.4.0
+
+Stand up an OAuth 2.1 authorization server (or require an
+external one), implement JWT verification, audience validation,
+scope enforcement, dynamic client registration up front.
+
+- **Rejected for v0.4.0** because OAuth is its own multi-PR
+  project and would significantly delay the basic HTTP path. The
+  static-bearer design captures the actual security property
+  ("caller proved possession of a secret") with far less
+  operational surface area. The verifier abstraction in the
+  design preserves the OAuth path for a later release.
+
+### D. Separate HTTP code path
+
+Implement HTTP as a standalone server with its own
+tool-dispatch logic and parallel safety code, leaving stdio
+untouched.
+
+- **Rejected** because two safety code paths is two places to
+  miss a fix. The whole point of the `createMcpServer()`
+  factoring is one dispatcher, one set of safety checks, two
+  thin transport adapters.
+
+### E. Hosted AgentBridge service
+
+Run AgentBridge as a hosted multi-tenant service so HTTP
+transport is "just an internal detail."
+
+- **Rejected** because it conflicts with v1.0 non-goal #1 in
+  [`docs/v1-readiness.md`](../v1-readiness.md): AgentBridge
+  stays a self-hosted set of packages. A hosted offering, if
+  ever, is a separate project.
+
+## Links
+
+- Tracking issue: [#22](https://github.com/marmar9615-cloud/agentbridge-protocol/issues/22)
+  / [`docs/issues/v0.4.0-http-transport-auth.md`](../issues/v0.4.0-http-transport-auth.md).
+- Design doc: [`docs/designs/http-mcp-transport-auth.md`](../designs/http-mcp-transport-auth.md).
+- Roadmap: [`docs/roadmap.md`](../roadmap.md) (v0.4.0 line).
+- v1 readiness: [`docs/v1-readiness.md`](../v1-readiness.md)
+  criterion #8.
+- Threat model: [`docs/threat-model.md`](../threat-model.md) T14
+  (Future HTTP transport risks).
+- Production readiness: [`docs/production-readiness.md`](../production-readiness.md)
+  — the "MCP HTTP mode (planned)" section.
+- Security configuration: [`docs/security-configuration.md`](../security-configuration.md)
+  — the `AGENTBRIDGE_HTTP_*` table arrives with the
+  implementation PR.