release: prepare v0.4.0 HTTP transport release

AGENTS.md

@@ -24,14 +24,21 @@ The repo ships:
 - npm scope: **`@marmarlabs`** (do not change).
 - 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);
+  build provenance).
+- **v0.4.0 is release-prepared on the `release/v0.4.0-http-polish`
+  branch** — all packages bumped to `0.4.0`, opt-in HTTP MCP
+  transport implemented (PR #27 landed), docs/examples updated,
+  HTTP smoke wired. **Not yet on npm**; publishing happens through
+  the Trusted Publishing workflow only after maintainer approval.
+  Predecessor PRs:
+  [#23](https://github.com/marmar9615-cloud/agentbridge-protocol/pull/23) (design),
+  [#24](https://github.com/marmar9615-cloud/agentbridge-protocol/pull/24) (transport abstraction),
+  [#25](https://github.com/marmar9615-cloud/agentbridge-protocol/pull/25) (adopter docs/examples),
+  [#26](https://github.com/marmar9615-cloud/agentbridge-protocol/pull/26) (OpenAPI regression fixtures),
+  [#27](https://github.com/marmar9615-cloud/agentbridge-protocol/pull/27) (HTTP transport + bearer auth).
+- Stdio remains the default and only-when-unset transport. HTTP is
+  **opt-in** via `AGENTBRIDGE_TRANSPORT=http`. 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).

CHANGELOG.md

@@ -6,23 +6,103 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [0.4.0] — release-prepared — HTTP MCP Transport + Auth
+
+> Release-prepared on `release/v0.4.0-http-polish`. Not yet on npm
+> until the Trusted Publishing workflow is dispatched. See
+> [`docs/releases/v0.4.0.md`](docs/releases/v0.4.0.md) for the full
+> notes.
+
 ### Added
 
-- [`docs/adopter-quickstart.md`](docs/adopter-quickstart.md) - an
-  existing-app onboarding guide for adding AgentBridge manifests,
-  action endpoints, CLI validation, scanner checks, MCP client setup,
-  and production safety review.
-- [`docs/manifest-patterns.md`](docs/manifest-patterns.md) - reusable
-  manifest/action patterns for read actions, draft actions,
-  confirmation-required mutations, idempotent calls, resources, and
-  auth/contact metadata.
-- [`examples/adopter-quickstart/`](examples/adopter-quickstart/) -
-  static valid manifest examples for adopter onboarding, including a
-  minimal order manifest and a production-shaped safe fixture.
-- OpenAPI converter regression fixtures and tests covering action-name
-  normalization, method-risk inference, request/response schema
-  conversion, skipped methods, metadata inheritance, and current
-  unsupported security/example mapping behavior.
+- **Opt-in Streamable HTTP MCP transport.** New
+  [`apps/mcp-server/src/transports/http.ts`](apps/mcp-server/src/transports/http.ts)
+  wraps `StreamableHTTPServerTransport` from
+  `@modelcontextprotocol/sdk` behind:
+  - static bearer-token auth (`Authorization: Bearer <token>`,
+    constant-time compare via `crypto.timingSafeEqual`),
+  - exact-`URL.origin` allowlist for inbound `Origin` headers,
+  - loopback-by-default bind (`127.0.0.1`); public bind requires
+    both auth and a non-empty Origin allowlist or fails closed at
+    startup,
+  - query-string-token rejection with HTTP `400`,
+  - body size cap (reuses `AGENTBRIDGE_MAX_RESPONSE_BYTES`),
+  - `OPTIONS` preflight only for allowed origins; CORS responses
+    echo the exact origin and never use wildcard with credentials.
+  Endpoint `POST /mcp`. JSON responses (no SSE in v0.4.0).
+  Stateless mode.
+- **Transport abstraction.** New
+  [`apps/mcp-server/src/server.ts`](apps/mcp-server/src/server.ts)
+  with the `createMcpServer()` factory and shared `TOOLS` /
+  `dispatchTool` exports; both transports use the same factory so
+  every safety check, confirmation gate, target-origin allowlist,
+  idempotency, and audit redaction is shared.
+- **HTTP env vars.** `AGENTBRIDGE_TRANSPORT` (`stdio` default |
+  `http`), `AGENTBRIDGE_HTTP_HOST` (default `127.0.0.1`),
+  `AGENTBRIDGE_HTTP_PORT` (default `3333`),
+  `AGENTBRIDGE_HTTP_AUTH_TOKEN` (required for HTTP mode, ≥ 16
+  chars, never logged), `AGENTBRIDGE_HTTP_ALLOWED_ORIGINS`
+  (inbound Origin allowlist, independent from outbound
+  `AGENTBRIDGE_ALLOWED_TARGET_ORIGINS`). Full table:
+  [`docs/security-configuration.md`](docs/security-configuration.md).
+- **HTTP smoke.** New [`scripts/http-mcp-smoke.mjs`](scripts/http-mcp-smoke.mjs)
+  spawns the dist binary in HTTP mode on an ephemeral port and
+  exercises auth (missing/wrong/query-string), Origin allowlist,
+  valid `initialize` returning `serverInfo {agentbridge, 0.4.0}`,
+  and the public-bind / missing-token fail-closed paths. Wired
+  into `npm run smoke:external` and exposed as `npm run smoke:http`.
+- **HTTP client recipe.** New
+  [`examples/http-client-config/`](examples/http-client-config/)
+  with `curl` smoke tests, generic hosted-client JSON config, and
+  security warnings.
+- **CLI HTTP block.** `agentbridge mcp-config` now prints an
+  experimental HTTP transport block alongside the stdio snippets,
+  with placeholder env-var resolution (no literal tokens).
+- **Threat model T14 implemented.** [`docs/threat-model.md`](docs/threat-model.md)
+  T14 rewritten to enumerate the v0.4.0 mitigations (auth
+  required, no query tokens, exact Origin match,
+  loopback-by-default bind, public-bind fail-closed, stdout
+  hygiene preserved) and the remaining gaps (OAuth resource
+  server, token rotation, richer scopes, caller-identity
+  propagation into audit, deployment guides).
+- **Release docs.** New [`docs/releases/v0.4.0.md`](docs/releases/v0.4.0.md);
+  v1-readiness checklist updated; roadmap marks v0.4.0 as
+  release-prepared.
+- (From v0.4.0-line maintenance work, already on `main`)
+  [`docs/adopter-quickstart.md`](docs/adopter-quickstart.md),
+  [`docs/manifest-patterns.md`](docs/manifest-patterns.md),
+  [`examples/adopter-quickstart/`](examples/adopter-quickstart/),
+  OpenAPI converter regression fixtures and tests
+  ([`examples/openapi-regression/`](examples/openapi-regression/),
+  `packages/openapi/src/tests/openapi-fixtures.test.ts`).
+
+### Changed
+
+- All workspace packages bumped from `0.3.0` → `0.4.0`.
+- Workspace dependency ranges bumped from `^0.3.0` → `^0.4.0`.
+- `SERVER_VERSION` in
+  [`apps/mcp-server/src/server.ts`](apps/mcp-server/src/server.ts)
+  bumped from `0.3.0` → `0.4.0` so `serverInfo.version` reflects
+  the release.
+- `apps/mcp-server/src/index.ts` now picks transport via
+  `resolveTransport()` (defaults `stdio`); fatal-error format and
+  stdio behavior are bit-identical to v0.3.0 when
+  `AGENTBRIDGE_TRANSPORT` is unset.
+- `scripts/external-adopter-smoke.mjs` runs the HTTP smoke as a
+  final step against the freshly built dist.
+
+### Compatibility
+
+- **Existing stdio installs are unchanged.** No env var changes
+  required. `npx -y @marmarlabs/agentbridge-mcp-server` continues
+  to launch the stdio MCP server. `serverInfo` reads
+  `{ name: "agentbridge", version: "0.4.0" }`. Tools, resources,
+  prompts, and call shapes are byte-identical to v0.3.0.
+- Manifest schema unchanged (still `v0.1`).
+- CLI commands unchanged. `agentbridge mcp-config` adds an HTTP
+  block but keeps every existing snippet.
 
 ## [0.3.0] — 2026-04-28 — Production Foundations
 

CLAUDE.md

@@ -177,3 +177,6 @@ Every new feature ships with a test. Categories of tests we currently maintain:
   — 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/releases/v0.4.0.md](docs/releases/v0.4.0.md) — v0.4.0
+  release notes (release-prepared on
+  `release/v0.4.0-http-polish`; not yet on npm).

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.3.0](https://img.shields.io/badge/Status-v0.3.0-blue)]()
+[![Status: v0.4.0-rc](https://img.shields.io/badge/Status-v0.4.0--rc-blue)]()
 [![npm](https://img.shields.io/npm/v/@marmarlabs/agentbridge-sdk?label=%40marmarlabs%2Fagentbridge-sdk)](https://www.npmjs.com/package/@marmarlabs/agentbridge-sdk)
 
 </div>
@@ -22,19 +22,36 @@
 
 **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).
+**v0.4.0 is release-prepared** on the `release/v0.4.0-http-polish`
+branch — all packages bumped to `0.4.0`, the opt-in HTTP MCP
+transport implemented, docs and examples updated, and HTTP smoke
+wired into the local pre-publish flow. **Not yet on npm**;
+publishing happens through the existing Trusted Publishing
+workflow only after maintainer approval. See
+[docs/releases/v0.4.0.md](docs/releases/v0.4.0.md) for the full
+release notes.
+
+The v0.4.0 line adds:
+- An **opt-in Streamable HTTP MCP transport** with static
+  bearer-token auth, exact-origin allowlist, and loopback-by-
+  default bind. **stdio remains the default** for local desktop
+  clients — nothing about the existing stdio behavior changes.
+  HTTP is opt-in via `AGENTBRIDGE_TRANSPORT=http` and **fails
+  closed** on missing token, missing Origin allowlist for
+  public bind, or token-in-query-string. Design:
+  [docs/designs/http-mcp-transport-auth.md](docs/designs/http-mcp-transport-auth.md);
+  ADR: [docs/adr/0001-http-mcp-transport.md](docs/adr/0001-http-mcp-transport.md).
+- An **adopter quickstart** ([docs/adopter-quickstart.md](docs/adopter-quickstart.md))
+  and **manifest-pattern catalogue**
+  ([docs/manifest-patterns.md](docs/manifest-patterns.md)) for
+  existing-app onboarding.
+- **OpenAPI converter regression fixtures**
+  ([examples/openapi-regression](examples/openapi-regression))
+  pinning stable mapping behavior.
+
 Neither v0.3.0 nor v0.4.0 alone is v1.0 production readiness;
-both are steps toward it.
+both are steps toward it. The HTTP transport is **experimental**
+in v0.4.0.
 
 ```bash
 npm install @marmarlabs/agentbridge-sdk @marmarlabs/agentbridge-core
@@ -50,8 +67,10 @@ 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.3.0.md](docs/releases/v0.3.0.md)
-for the current release,
+For release notes, see [docs/releases/v0.4.0.md](docs/releases/v0.4.0.md)
+for the in-flight release,
+[docs/releases/v0.3.0.md](docs/releases/v0.3.0.md) for the latest
+shipped 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
@@ -886,7 +905,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. The v0.4.0 design is in [docs/designs/http-mcp-transport-auth.md](docs/designs/http-mcp-transport-auth.md).
+- **HTTP MCP transport.** Stdio works for desktop clients; hosted/centralized agents need an authenticated HTTP transport. **Implemented as opt-in in v0.4.0** behind `AGENTBRIDGE_TRANSPORT=http` with bearer-token auth, exact-origin allowlist, and loopback-by-default bind. Design: [docs/designs/http-mcp-transport-auth.md](docs/designs/http-mcp-transport-auth.md). Recipe: [examples/http-client-config](examples/http-client-config).
 - **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/demo-app/package.json

@@ -1,15 +1,15 @@
 {
   "name": "agentbridge-demo-app",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": true,
   "scripts": {
     "dev": "next dev -p 3000",
     "build": "next build",
     "start": "next start -p 3000"
   },
   "dependencies": {
-    "@marmarlabs/agentbridge-core": "^0.3.0",
-    "@marmarlabs/agentbridge-sdk": "^0.3.0",
+    "@marmarlabs/agentbridge-core": "^0.4.0",
+    "@marmarlabs/agentbridge-sdk": "^0.4.0",
     "next": "^15.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",

apps/mcp-server/README.md

@@ -1,8 +1,11 @@
 # @marmarlabs/agentbridge-mcp-server
 
-stdio MCP server that exposes [AgentBridge](https://github.com/marmar9615-cloud/agentbridge-protocol)
+MCP server that exposes [AgentBridge](https://github.com/marmar9615-cloud/agentbridge-protocol)
 actions to MCP clients (OpenAI Codex, Claude Desktop, Cursor, custom)
-with confirmation gates, origin pinning, and audit logging.
+with confirmation gates, origin pinning, and audit logging. Default
+**stdio** transport for local desktop clients; opt-in **Streamable
+HTTP** transport (v0.4.0) with bearer-token auth for hosted /
+centralized clients.
 
 ## Install
 
@@ -138,17 +141,22 @@ example manifests) and pre-canned prompts for common workflows.
 
 ## Status
 
-Public release. **v0.3.0** is the "Production Foundations" release:
-stricter remote-target allowlist, configurable timeouts/TTLs, an
-MCP stdout-hygiene test, a threat model, a v1.0 readiness checklist,
-a draft npm Trusted Publishing workflow, and updated docs. **Not
-yet v1.0** — see the
+Public release. **v0.3.0** shipped Production Foundations
+(stricter remote-target allowlist, configurable timeouts/TTLs,
+MCP stdout-hygiene test, threat model, v1.0 readiness checklist,
+Trusted Publishing workflow). **v0.4.0** is release-prepared
+on the `release/v0.4.0-http-polish` branch and adds an opt-in
+Streamable HTTP transport with static bearer-token auth, exact-
+origin allowlist, loopback-by-default bind, and HTTP smoke wired
+into the local pre-publish flow. Stdio remains the default; HTTP
+is opt-in via `AGENTBRIDGE_TRANSPORT=http`. **Not yet v1.0** —
+see the
 [v1-readiness checklist](https://github.com/marmar9615-cloud/agentbridge-protocol/blob/main/docs/v1-readiness.md)
 for what we still owe before declaring production-ready.
 
 AgentBridge is suitable for local development, manifest authoring,
 scanner workflows, OpenAPI import, and MCP experiments. With the
-v0.3.0 controlled-staging configuration (see
+v0.3.0+ controlled-staging configuration (see
 [production-readiness.md](https://github.com/marmar9615-cloud/agentbridge-protocol/blob/main/docs/production-readiness.md))
 it is also suitable for internal staging deployments behind an
 explicit origin allowlist. It is not yet production security

apps/mcp-server/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@marmarlabs/agentbridge-mcp-server",
-  "version": "0.3.0",
-  "description": "stdio MCP server that exposes AgentBridge actions to AI agents with confirmation gates, origin pinning, and audit logging.",
+  "version": "0.4.0",
+  "description": "MCP server that exposes AgentBridge actions to AI agents with confirmation gates, origin pinning, and audit logging. Default stdio transport plus an opt-in Streamable HTTP transport with bearer auth.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/marmar9615-cloud/agentbridge-protocol.git",
     "directory": "apps/mcp-server"
   },
   "homepage": "https://github.com/marmar9615-cloud/agentbridge-protocol",
-  "keywords": ["agentbridge", "mcp", "ai-agents", "model-context-protocol", "stdio"],
+  "keywords": ["agentbridge", "mcp", "ai-agents", "model-context-protocol", "stdio", "http"],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -34,8 +34,8 @@
     "start": "tsx src/index.ts"
   },
   "dependencies": {
-    "@marmarlabs/agentbridge-core": "^0.3.0",
-    "@marmarlabs/agentbridge-scanner": "^0.3.0",
+    "@marmarlabs/agentbridge-core": "^0.4.0",
+    "@marmarlabs/agentbridge-scanner": "^0.4.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "ajv": "^8.17.0"
   }

apps/mcp-server/src/server.ts

@@ -34,7 +34,7 @@ import { STATIC_RESOURCES, readResource } from "./resources";
 // Server identity. Bumps in lockstep with @marmarlabs/agentbridge-mcp-server's
 // package version on every release.
 export const SERVER_NAME = "agentbridge";
-export const SERVER_VERSION = "0.3.0";
+export const SERVER_VERSION = "0.4.0";
 
 // ── Tool descriptors ─────────────────────────────────────────────────
 //

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

@@ -28,11 +28,21 @@ Per [`docs/designs/http-mcp-transport-auth.md §13`](../../../../docs/designs/ht
    `AGENTBRIDGE_HTTP_*`) parsed in `../config.ts`. stdio path
    untouched and verified by the existing
    [`stdio-hygiene.test.ts`](../tests/stdio-hygiene.test.ts).
-3. **PR 3 — docs / examples / smoke tests.** Polishes
+3. **PR 3 — docs / examples / smoke / version bump.** ✅
+   release-prepared on `release/v0.4.0-http-polish`. Lockstep
+   bump to `0.4.0` (every workspace `package.json` plus
+   `SERVER_VERSION` in [`../server.ts`](../server.ts)). Adds
+   [`examples/http-client-config/`](../../../../examples/http-client-config/),
+   wires
+   [`scripts/http-mcp-smoke.mjs`](../../../../scripts/http-mcp-smoke.mjs)
+   into `npm run smoke:external`, and updates
+   [`docs/releases/v0.4.0.md`](../../../../docs/releases/v0.4.0.md),
    [`docs/security-configuration.md`](../../../../docs/security-configuration.md),
    [`docs/mcp-client-setup.md`](../../../../docs/mcp-client-setup.md),
-   adds an `examples/http-client-config/` directory, an external
-   smoke test, and bumps all six packages to `0.4.0`.
+   [`docs/threat-model.md`](../../../../docs/threat-model.md), and
+   [`packages/cli/src/commands/mcp-config.ts`](../../../../packages/cli/src/commands/mcp-config.ts)
+   to surface an HTTP block. Publishing happens through the
+   Trusted Publishing workflow only after maintainer approval.
 
 ## Hard rules for the implementation