docs(proposals): VEP-0004 — HTTP transport for vouch serve (draft)

[dripsmvcp]

Summary

• Adds VEP-0004 (draft) proposing an HTTP transport for vouch serve (--transport http), per the project process that requires a written, maintainer-accepted proposal before any code for a new transport (feat: HTTP transport for vouch serve (--transport http) [VEP] #94 is tagged [VEP]).
• No implementation — this PR is the design record only. Indexed in proposals/README.md as draft.

Why a VEP and not a code PR

proposals/README.md requires a VEP for "any new transport," reviewed and marked accepted before implementation. HTTP transport qualifies, so this opens the design for discussion rather than shipping a server.

What the VEP proposes

• vouch serve --transport http [--host 127.0.0.1] [--port …] [--token …] [--allow-public], reusing the existing shared _handle_request dispatch table (same kb.* surface as MCP/JSONL — no new methods).
• POST /rpc carrying the same JSONL envelope as VEP-0002; plus unauthenticated GET /capabilities and GET /healthz.
• Safe by default: binds 127.0.0.1; refuses any non-loopback bind unless --allow-public and a bearer token are set. Constant-time token compare, no TLS in-process (reverse-proxy terminates), CORS denied. The review gate is unchanged.
• Zero new runtime dependencies (stdlib http.server).

Open questions for reviewers (in the VEP)

• Bespoke JSONL-over-HTTP vs MCP streamable-HTTP (the issue mentions a future Claude plugin) — leaning JSONL-first.
• Default port; per-method (read vs write) authz; whether host/port/token belong in config.yaml.

Test Plan

• N/A — documentation only (no code paths changed)
• Adds proposals/VEP-0004-http-transport.md (status draft) and the index row in proposals/README.md

Refs #94 (implementation lands in separate PRs once/if the VEP is accepted)

Summary by CodeRabbit

Release Notes

• New Features

  • Added HTTP transport (vouch serve --transport http) exposing RPC, capabilities, and health check endpoints
  • Configurable host, port, bearer token authentication, and optional public binding
  • Default localhost-only binding with secure opt-in for remote access

• Documentation

  • HTTP transport specification added to official documentation
  • HTTP transport proposal (VEP-0004) documented

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 566ff2af-262b-40ae-9bc1-ff1821c03d7b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR introduces an HTTP transport for the Vouch knowledge base via vouch serve --transport http. The implementation adds a threaded HTTP server exposing the existing kb.* dispatch surface over three endpoints: POST /rpc (with bearer-token auth), GET /healthz, and GET /capabilities. The server binds to localhost by default and refuses public binds without both --allow-public and a configured token. Request-scoped actor attribution via the X-Vouch-Agent header flows through context variables into audit logs.

Changes

HTTP Transport Feature

Layer / File(s)	Summary
Request-scoped actor attribution infrastructure src/vouch/jsonl_server.py	ContextVar _actor and updated _agent() function enable per-request actor tracking without process-wide state mutation, allowing HTTP and other transports to set audit actor per request.
HTTP transport server implementation src/vouch/http_server.py	Threaded HTTP server implements /rpc (JSONL envelope dispatch, optional bearer-token auth), /healthz (unauthenticated), and /capabilities (unauthenticated). Enforces loopback-by-default bind policy and strict Content-Length validation. Sets request actor via context for audit trail.
CLI integration for HTTP transport src/vouch/cli.py	The serve command adds HTTP transport option with --host, --port, --token, and --allow-public flags, dispatching to the new run_http function and converting runtime errors to user-friendly messages.
Capability advertisement for HTTP transport src/vouch/capabilities.py	The capabilities() return value adds "http" to the advertised transports list.
Comprehensive HTTP server test suite tests/test_http_server.py	226 lines of test coverage validating RPC dispatch, error handling, token authentication, unauthenticated GET access, bind-policy guardrails, X-Vouch-Agent actor attribution, and edge cases including negative Content-Length rejection.
VEP-0004 HTTP transport proposal proposals/VEP-0004-http-transport.md	Formal proposal documenting scope, motivation, design choices, endpoint specifications, auth model, bind policy, security implications, and open questions for HTTP transport feature.
Normative specification updates spec/transports.md	Adds HTTP transport section defining endpoints, JSONL envelope framing, bearer-token authorization, bind policy, and actor attribution. Updates transport comparison table and future transports discussion.
Documentation index and changelog CHANGELOG.md, proposals/README.md	Changelog documents HTTP transport v0.1.0 feature; VEP index adds VEP-0004 with draft status.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• feat: HTTP transport with bearer-token auth and SSE streaming for vouch serve #153: Both changes implement the HTTP transport feature with identical code structure (src/vouch/http_server.py, bearer-token auth, CLI flags, capability advertisement, and comprehensive tests), indicating direct alignment.

Poem

🐇 A server bound to localhost, secure and snug,
With /rpc envelopes in JSON, no need for a hug—
Bearer tokens at the gate, actors in the light,
The HTTP transport dances, loopback-safe and bright!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: adding VEP-0004 documentation for an HTTP transport proposal. It is specific, concise, and directly describes the primary content—a design proposal that is being added and indexed as draft.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[dripsmvcp]

@plind-junior This PR is ready for review. I've added the HTTP transport feature to be used for claude code and codex integration

[plind-junior]

LGTM!