feat(adr-124/architecture): schema-validation gate + Streamable HTTP transport (ADR-124 §3)
Advances SPARC Phase 3 (Architecture): wires the phase-2 schema barrel into
the MCP CallTool dispatch loop, and scaffolds the Streamable HTTP transport
with Origin-validation and bearer-token auth as specified in ADR-124 §3/§6.
Sub-task (a) — Uniform Zod validation gate in src/index.ts:
- Import TOOL_INPUT_SCHEMAS + McpError + ErrorCode from SDK
- CallTool handler: before dispatch, looks up schema by tool name using
Object.prototype.hasOwnProperty (safe for dotted keys) then runs
schema.safeParse(args); failures throw McpError(InvalidParams) so the
caller receives a typed JSON-RPC error rather than a wrapped string
- Re-throws McpError instances unchanged (policy errors propagate cleanly)
Sub-task (b) — src/http-transport.ts (new, 145 LOC):
- buildHttpApp(mcpServer, opts): creates Node.js http.Server +
StreamableHTTPServerTransport without binding; testable in isolation
- createHttpTransport(mcpServer, opts): binds and resolves when listening
- isOriginAllowed(origin, allowedOrigins): pure function — undefined origin
allowed (non-browser), present origin validated against allowlist,
'*' disables gate for local-dev
- Bearer-token gate: RVAGENT_HTTP_TOKEN env or opts.bearerToken; missing/
wrong token → 401 before any JSON-RPC processing
- Bind default: 127.0.0.1 per MCP spec security requirement (ADR-124 §3)
- Transport connect() only in createHttpTransport (not buildHttpApp) to
avoid exactOptionalPropertyTypes false-incompatibility in test contexts
New test: tests/http-transport.test.ts (11 assertions):
- isOriginAllowed() unit ×5: undefined allowed, allowlist hit/miss, wildcard,
case-sensitivity (RFC 6454)
- Origin-validation integration ×3: cross-origin → 403 with error body,
allowed origin → non-403, no Origin → non-403
- Bearer-token integration ×3: missing → 401, wrong → 401, correct → non-401
Fix: @types/express added as devDep (express is transitive from SDK ^1.29.0).
Test results: 61/61 PASS (+11 new)
Build: tsc clean, zero errors.
ACs touched: ADR-124 §3 (dual-transport architecture), §6 (Origin validation,
127.0.0.1 bind, bearer-token auth slot). SPARC Phase 3 gate criteria met:
API contracts typed, module boundaries established, no circular deps.
Next iter target: Phase 4 (Refinement) — implement ruview.bfld.last_scan +
ruview.bfld.subscribe tool handlers (BFLD wire format stable post-ADR-118),
register them in the TOOLS array using the new schema-validation gate.
Co-Authored-By: claude-flow <ruv@ruv.net>
092152bd73