http-capability-gateway

Table of Contents

• 1. Overview
  • 1.1. Current Status
• 2. Why This Exists
• 3. MVP Scope
• 4. Quick Start
  • 4.1. Installation
  • 4.2. Basic Usage
• 5. Verb Governance Spec (DSL v1)
  • 5.1. Structure
  • 5.2. Supported HTTP Verbs
  • 5.3. Path Matching
  • 5.4. Stealth Mode
• 6. Configuration
  • 6.1. Environment Variables
  • 6.2. Elixir Config
• 7. Trust Levels
• 8. Logging
• 9. Testing
• 10. Architecture (MVP)
• 11. Performance Optimisations (v1.0.0)
  • 11.1. Tiered ETS Lookup
  • 11.2. Security Headers
• 12. Project Structure
• 13. Roadmap
  • 13.1. Phase 2
  • 13.2. Phase 3
  • 13.3. Phase 4
• 14. Contributing
• 15. Philosophy
• 16. License

1. Overview

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.

1.1. Current Status

This repository contains a real Elixir gateway implementation, but it should currently be treated as a narrow, in-progress API governance layer rather than a fully proven front door for an entire site.

• The core policy pipeline exists: loader, validator, compiler, gateway, proxy, telemetry.

• The main remaining gaps are security depth, end-to-end verification, and benchmark evidence.

• Read ROADMAP.adoc, TEST-NEEDS.md, and PROOFS_NEEDED.md together when judging readiness.

It provides:

• Declarative Verb Governance: Define allowed HTTP verbs globally and per-route

• Stealth Mode: Return configurable status codes (404, 403, etc.) for unauthorized requests

• Fast Policy Enforcement Architecture: ETS-backed lookups and compiled policy rules; benchmark evidence still needs to be formalized

• Trust Level Integration: Current implementation is header-based, with mTLS-oriented direction documented but not the primary proved path yet

• Comprehensive Logging: Structured JSON logs with telemetry metrics

• Backend Proxy: Transparent proxying to backend services with header preservation

Wondering how this works? See EXPLAINME.adoc.

2. Why This Exists

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.

3. MVP Scope

The MVP focuses on the smallest coherent loop:

1. Load a Verb Governance Spec from disk

2. Validate it against a top-level schema

3. Compile it into fast, matchable rules

4. Enforce those rules on real HTTP traffic

5. Emit structured logs for every decision

No trust engine, no dynamic scoring, no control plane, no VeriSimDB integration. Those will grow around this core in later phases.

4. Quick Start

4.1. Installation

# Clone the repository
git clone https://github.com/hyperpolymath/http-capability-gateway.git
cd http-capability-gateway

# Install dependencies
mix deps.get

# Compile
mix compile

4.2. Basic Usage

1. Create a policy file (config/policy.yaml):

   dsl_version: "1"
   governance:
     global_verbs:
       - GET
       - POST
     routes:
       - path: "/api/admin"
         verbs: [GET]
       - path: "/api/users/[0-9]+"
         verbs: [GET, PUT, DELETE]
   stealth:
     enabled: true
     status_code: 404

2. Configure backend (config/dev.exs):

   config :http_capability_gateway,
     policy_path: "examples/policy-dev.yaml",
     backend_url: "http://localhost:4000",
     port: 4000

3. Start the gateway:

   mix run --no-halt
   
   # Or with interactive shell
   iex -S mix

4. Test requests:

   # Allowed: GET on global route
   curl http://localhost:4000/api/public
   # Returns: proxied response from backend
   
   # Denied: DELETE not in global verbs
   curl -X DELETE http://localhost:4000/api/public
   # Returns: 404 (stealth mode)
   
   # Allowed: PUT on specific route
   curl -X PUT http://localhost:4000/api/users/123
   # Returns: proxied response from backend

5. Verb Governance Spec (DSL v1)

5.1. Structure

dsl_version: "1"  # Required: policy format version

governance:
  # Global verbs: allowed on all routes unless overridden
  global_verbs:
    - GET
    - POST

  # Route-specific rules (optional)
  routes:
    - path: "/api/admin"
      verbs: [GET]  # Only GET allowed, overrides global
    - path: "/api/users/[0-9]+"  # Regex patterns supported
      verbs: [GET, PUT, DELETE]

stealth:  # Optional stealth mode configuration
  enabled: true
  status_code: 404  # Status code for denied requests

Earlier-format DSL (v0) uses a richer service/verbs/narrative structure:

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."

5.2. Supported HTTP Verbs

GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS

5.3. Path Matching

• Literal paths: /api/users

• Regex patterns: /api/users/[0-9]+ (numeric user IDs)

• Wildcard patterns: /api/posts/.+ (any post path)

5.4. Stealth Mode

When a request is denied:

• Stealth enabled: Returns configured status code (e.g., 404) with empty body

• Stealth disabled: Returns 403 Forbidden

Valid stealth status codes: 200, 301, 302, 403, 404, 410, 500, 503

6. Configuration

6.1. Environment Variables

# Policy file path (default: config/policy.yaml)
export POLICY_PATH=/path/to/policy.yaml

# Backend URL (required)
export BACKEND_URL=http://backend:4000

# Gateway port (default: 4000)
export PORT=4000

# Trust level header name (default: x-trust-level)
export TRUST_LEVEL_HEADER=x-trust-level

6.2. Elixir Config

config/config.exs (shared config):

import Config

config :http_capability_gateway,
  backend_url: System.get_env("BACKEND_URL", "http://localhost:4000"),
  port: String.to_integer(System.get_env("PORT", "4000")),
  trust_level_header: System.get_env("TRUST_LEVEL_HEADER", "x-trust-level")

config/dev.exs (development):

import Config

config :http_capability_gateway,
  policy_path: "examples/policy-dev.yaml",
  log_level: :debug

config/prod.exs (production):

import Config

config :http_capability_gateway,
  policy_path: System.get_env("POLICY_PATH"),
  log_level: :info

7. Trust Levels

Extract trust levels from mTLS certificates or HTTP headers:

# From header (current implementation)
curl -H "X-Trust-Level: high" http://localhost:4000/api/admin

Trust levels can be used for:

• Audit logging

• Fine-grained access control (future feature)

• Rate limiting (future feature)

8. Logging

Structured JSON logs with telemetry:

{
  "timestamp": "2026-01-22T23:00:00.000Z",
  "level": "info",
  "message": "request_handled",
  "request_id": "req-abc123",
  "method": "GET",
  "path": "/api/users/123",
  "trust_level": "high",
  "verb_allowed": true,
  "stealth_triggered": false,
  "response_status": 200,
  "duration_ms": 45
}

9. Testing

# Run all tests
mix test

# Run specific test file
mix test test/policy_loader_test.exs

# Run property-based tests only
mix test --only property

# Run performance tests
mix test --only performance

# Run with coverage
mix test --cover

Current tests cover the policy pipeline and some gateway behavior, but the repo still needs materially stronger evidence in the following areas:

• security tests for token validation, request sanitization, and SSRF resistance

• end-to-end request lifecycle tests

• concurrency and reload testing

• formal benchmark runs

Do not treat the current suite as sufficient proof for whole-site gateway deployment.

10. Architecture (MVP)

Policy File (DSL)
       |
       v
Policy Loader → Validator → Compiler
       |
       v
Gateway (Elixir)
       |
       v
HTTP Traffic → Enforcement → JSON Logs

See TOPOLOGY.md for a full visual architecture map and completion dashboard.

11. Performance Optimisations (v1.0.0)

11.1. Tiered ETS Lookup

Policy 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).

Performance-oriented design is present, but the benchmark story is not yet strong enough to advertise hard numbers as release evidence. A performance test file exists; benchmarking and concurrency validation are still tracked as open work in ROADMAP.adoc and TEST-NEEDS.md.

11.2. Security Headers

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

12. Project Structure

http-capability-gateway/
├── lib/
│   └── http_capability_gateway/
│       ├── application.ex        # OTP application
│       ├── gateway.ex            # HTTP gateway (Plug.Router)
│       ├── proxy.ex              # Backend proxy (Req)
│       ├── policy_loader.ex      # YAML policy loading
│       ├── policy_validator.ex   # DSL v1 validation
│       ├── policy_compiler.ex    # ETS compilation
│       ├── logging.ex            # Structured logging
│       └── log_formatter.ex      # JSON log formatter
├── test/                         # Current automated tests
├── config/                       # Elixir config files and default policy
├── examples/                     # Example policies
└── docs/                         # API documentation

13. Roadmap

Use ROADMAP.adoc as the current roadmap. The short version:

• core policy pipeline exists

• tests exist but are not yet strong enough for broad production claims

• the recommended near-term role is route-scoped API prefiltering, not full-site gateway responsibility

• benchmark, E2E, and security-hardening work remain open

13.1. Phase 2

• Rate limits

• Expanded stealth profiles

• Hot policy reloads

13.2. Phase 3

• Control plane

• VeriSimDB integration for provenance

• Distributed gateways

13.3. Phase 4

• Agent introspection

• Constraint engine

• Formal proofs

14. Contributing

Contributions welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Add tests for new features

4. Ensure mix test passes

5. Submit a pull request

15. Philosophy

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.

16. License

SPDX-License-Identifier: PMPL-1.0-or-later
See LICENSE.

Author: Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
Repository: github.com/hyperpolymath/http-capability-gateway