http-capability-gateway is a lightweight, policy-driven HTTP governance layer that enforces a declarative, auditable model of HTTP verb exposure in front of existing services.
This project introduces a minimal viable implementation of a new category: a capability gateway for HTTP. It does not replace nginx or Apache. Instead, it governs what they are allowed to do.
The gateway loads a Verb Governance Spec (DSL v1), validates it, compiles it into fast enforcement rules, and applies those rules to real HTTP traffic. Every decision is logged in structured form for audit and introspection.
Modern systems expose HTTP methods inconsistently and often accidentally. DELETE, PUT, PATCH, OPTIONS, and even HEAD can leak capabilities or create attack surface when left unmanaged.
Traditional reverse proxies do not provide:
-
per-verb governance
-
narrative or provenance
-
reversible policy artefacts
-
trust-aware verb exposure
-
structured constraints
-
intentional stealthing or deception
http-capability-gateway introduces a principled, schema-driven approach to HTTP method governance without disrupting existing infrastructure.
The MVP focuses on the smallest coherent loop:
-
Load a Verb Governance Spec from disk
-
Validate it against a top-level schema
-
Compile it into fast, matchable rules
-
Enforce those rules on real HTTP traffic
-
Emit structured logs for every decision
No trust engine, no dynamic scoring, no control plane, no FormBD integration. Those will grow around this core in later phases.
The DSL defines:
-
global verb rules
-
route-specific overrides
-
stealth profiles
-
narrative metadata
Example:
service:
name: ledger-api
version: 1
environment: dev
verbs:
GET: { exposure: public }
POST: { exposure: authenticated }
DELETE: { exposure: internal }
routes:
- path: /accounts
verbs:
DELETE:
exposure: internal
narrative: "Account deletion requires internal trust."
stealth:
profiles:
limited:
unauthenticated: 405
untrusted: 404
narrative:
purpose: "Define safe verb exposure for ledger operations."Policy File (DSL)
|
v
Policy Loader → Validator → Compiler
|
v
Gateway (Elixir)
|
v
HTTP Traffic → Enforcement → JSON Logs-
Install Elixir
-
Clone the repository
-
Provide a policy file under
config/policy.yaml -
Start the gateway:
mix run --no-haltPolicy lookups use a three-tier strategy that eliminates full-table scans:
-
Tier 1 — Exact Path (O(1)): Literal route patterns (no regex metacharacters) are stored with
{:exact, path, verb}ETS keys. A direct hash lookup resolves 90%+ of requests instantly. -
Tier 2 — Regex Routes (O(r)): Patterns containing regex metacharacters are tested only against other regex routes, not the entire table.
-
Tier 3 — Global Rules (O(1)): If no route matches, a final
{:global, verb}lookup catches global verb defaults.
For a 1000-route policy, this reduces from ~1000 regex evaluations per request to 1 hash lookup (typical case) or ~50 regex evaluations (edge case).
All responses (including health/metrics endpoints) include OWASP-recommended security headers:
-
X-Content-Type-Options: nosniff— prevent MIME-type sniffing -
X-Frame-Options: DENY— prevent clickjacking -
Referrer-Policy: strict-origin-when-cross-origin— limit referrer leakage -
Cache-Control: no-store, no-cache, must-revalidate— prevent caching of policy decisions -
Connection: close— prevent connection reuse across trust boundaries
This project treats governance as a first-class engineering concern. Policies are artefacts. Artefacts are reversible. Decisions have provenance. HTTP verbs become capabilities, not accidents.
