http-capability-gateway

Table of Contents

• 1. Overview
• 2. Why This Exists
• 3. MVP Scope
• 4. Verb Governance Spec (DSL v1)
• 5. Architecture (MVP)
• 6. Running the Gateway
• 7. Roadmap
  • 7.1. Phase 2
  • 7.2. Phase 3
  • 7.3. Phase 4
• 8. Philosophy
• 9. 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.

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 FormBD integration. Those will grow around this core in later phases.

4. Verb Governance Spec (DSL v1)

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

5. Architecture (MVP)

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

6. Running the Gateway

• Install Elixir

• Clone the repository

• Provide a policy file under config/policy.yaml

• Start the gateway:

mix run --no-halt

7. Roadmap

7.1. Phase 2

• Trust engine (ETS)

• Rate limits

• mTLS support

• Expanded stealth profiles

7.2. Phase 3

• Control plane

• Hot policy reloads

• FormBD integration for provenance

7.3. Phase 4

• V-based data plane

• Distributed gateways

• Agent introspection

• Constraint engine

• FQLdt proofs

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

9. License

MIT (or your preferred license)