Skip to content

ROADMAP.adoc

Latest commit

 

History

History
154 lines (120 loc) · 7.77 KB

ROADMAP.adoc

File metadata and controls

154 lines (120 loc) · 7.77 KB
Raw

HTTP Capability Gateway Roadmap

Current Status (2026-04-16)

Version 0.1.0-dev. CRG grade C (achieved 2026-04-04).

The repository contains 19 Elixir modules, 2 Zig FFI parsers, 2 Idris2 ABI modules, and a growing test suite. The implementation covers the core gateway pipeline but verification is catching up. See STATE.adoc for the full picture.

MVP Scope Definition (v0.1.0)

The MVP is a narrow HTTP verb governance prefilter. It is NOT a general-purpose API gateway, load balancer, or TLS terminator. The scope is intentionally constrained so that every claim can be backed by an executed test.

What the MVP Does

  1. Policy loading: Read a YAML policy file (DSL v1) at startup and on reload.

  2. Policy validation: Reject malformed policies before compilation.

  3. Policy compilation: Compile validated policy into dual ETS tables (exact O(1) + regex O(r) + global O(1)).

  4. Trust extraction: Read trust level from X-Trust-Level header (stripped for non-trusted proxies).

  5. Verb governance: For each request, lookup the policy rule for (path, verb) and evaluate rank(trust) >= rank(exposure).

  6. Allow/deny: Forward allowed requests to a single configured backend via HTTP. Deny with 403 or stealth response.

  7. Stealth mode: Return configurable status codes (e.g. 404) instead of 403 to hide endpoint existence.

  8. Rate limiting: Per-client token bucket with trust-level-based quotas.

  9. Health/readiness probes: /health, /ready endpoints.

  10. Structured logging: JSON-formatted access decisions with telemetry.

  11. Atomic policy reload: Swap to new policy tables without downtime.

What the MVP Does NOT Do

  • No GraphQL or gRPC governance (handlers exist but are stubs; not MVP scope)

  • No multi-backend load balancing

  • No TLS termination

  • No dynamic trust scoring or control plane

  • No plugin system

  • No web UI dashboard

  • No distributed clustering

  • No Kubernetes operator

MVP Proof Requirements

Each claim above must have at least one passing test:

Claim Test File

Policy loading

test/policy_loader_test.exs

Policy validation

test/policy_validator_test.exs

Policy compilation

test/policy_compiler_test.exs

Trust extraction

test/security_test.exs (header handling)

Verb governance

test/gateway_test.exs, test/e2e_test.exs

Allow/deny decisions

test/e2e_test.exs (full lifecycle)

Stealth mode

test/gateway_test.exs (stealth describe block)

Rate limiting

test/gateway_test.exs (via plug pipeline)

Health/readiness

test/e2e_test.exs (health and readiness)

Structured logging

Telemetry events emitted (verified by integration)

Atomic policy reload

test/e2e_test.exs (hot-reload tests)

Request sanitization

test/security_test.exs

Trust spoofing prevention

test/security_test.exs (header stripping)

No atom exhaustion

test/fuzz_test.exs (arbitrary method strings)

No crash on arbitrary input

test/fuzz_test.exs (combined fuzzing)

P0 Release Blockers

  • ✓ Reconcile contradictory status docs so the repo has one truthful current-state story.

  • ✓ Add real security tests for request sanitization, header handling, SSRF resistance, and capability-token validation.

  • ✓ Add end-to-end tests for request lifecycle, policy hot reload, and upstream proxy behavior.

  • ✓ Remove tests/fuzz/placeholder.txt and add real property-based fuzz tests.

  • ✓ Define the supported MVP narrowly enough that it can be proven.

P1 Gateway Hardening

  • ✓ Benchmark routing, policy evaluation, and rate limiting. test/benchmark_test.exs.

  • ✓ Add concurrency and failure-mode tests for rate limiter, circuit breaker, and reload paths. test/concurrency_test.exs.

  • ✓ Tighten operator documentation around what protocols and trust sources are actually supported. docs/SUPPORTED-FEATURES.md.

  • ✓ Keep the runtime role constrained to prefiltering before origin-side enforcement. docs/SCOPED-DEPLOYMENT.md.

P2 Productization

  • ✓ Use the gateway in front of selected API routes first, not the whole application surface. See docs/SCOPED-DEPLOYMENT.md.

  • ✓ Add release criteria that require executed tests rather than topology percentages. See docs/RELEASE-CRITERIA.md.

  • ✓ Mark older design-only documents as historical where they no longer reflect the codebase. ROADMAP-v2.md, IMPLEMENTATION-ROADMAP.md, TOPOLOGY.md updated.

Milestones

v0.1.x - Narrow MVP

  • ❏ Truthful status docs

  • ❏ Request/path/verb governance solid

  • ❏ Capability checks and proxy path exercised end to end

v0.2.x - Trusted Prefilter

  • ❏ Security and concurrency tests in place

  • ❏ Benchmarks documented

  • ❏ Route-scoped production guidance ready

v1.0.0 - Stable Release

  • ❏ Claims match executed evidence

  • ❏ Gateway role is intentionally narrow and well proven

  • ❏ Operators can deploy it without relying on design-document assumptions

Future Directions

Broaden scope only after the narrow API-governance role is demonstrably trustworthy.

External validation — prior art for write-API anti-abuse design (2026-05-28)

While drafting a feature request to GitHub asking for a REST + GraphQL surface to create and seed repository wikis (re-file of community/community#196186), the proposal’s "anti-abuse considerations" section names five mechanisms that should be baked into any new write-API for an agent-collaborative world: per-author rate limits, token scope gating, optional human-attestation header, org-level opt-in, optional per-page review queue.

Internal audit confirmed http-capability-gateway already implements a 1:1 mapping of every one of those mechanisms in shipping code:

Proposal mechanism Gateway implementation

Per-author rate limits

RateLimiter — token-bucket keyed by {client_ip, trust_level}

Token scope gating

SafeTrust — three-level capability lattice (untrusted < authenticated < internal), formally verified in Idris2

Human-attestation header

A2ML — tamper-evident JSON envelopes with SHA-256 hashes, issuer + policy_hash, parameter redaction (see docs/A2ML-EXPLAINED.adoc)

Surfaced in audit metadata

VeriSimDB — durable append-only audit trail (capgw:audit) with structured forensic replay

Org-level opt-in

YAML Verb Governance Spec (DSL v1) compiled to ETS — per-deployment policy

Per-page review queue

K9-SVC contracts — SLA + breach policies (see docs/K9-SVC-EXPLAINED.adoc)

(Bonus, beyond proposal)

mTLS client cert → X.509 OU → capability grant; stealth mode (404 not 403); policy versioning; atom-exhaustion DoS defence

This is not a roadmap commitment to externalise the gateway as a GitHub-API drop-in — the MVP scope remains narrow per the sections above. The note is a marker for two reasons:

  1. Reference value if the GitHub request gains traction. If a Hubber engages on the discussion thread asking "do you have prior art for this design?", the gateway is the answer. The mapping above documents that answer in advance so future-Jonathan doesn’t have to re-derive it.

  2. Confidence anchor for the narrow MVP. Knowing the gateway’s design maps cleanly onto an externally-recognised problem (agent-safe write APIs in a documentation-as-code world) strengthens the argument that the narrow scope is on the right axis — even though the MVP deliberately does NOT chase the wider problem.

The discussion thread + the gateway will diverge over time; this note pins the snapshot relationship at 2026-05-28. If the discussion lands and GitHub asks for a more substantive engagement, that’s a separate scope decision documented at the point it arises, not here.