PRECINCT Gateway

Overview

The PRECINCT Gateway is the centralized enforcement point for all agent-to-tool communication in the PRECINCT architecture. It functions as a reverse proxy that sits between AI agents and upstream MCP servers, ensuring every request is evaluated against security policy before reaching any tool.

The gateway implements the complete 13-layer defense-in-depth middleware chain and governs all five planes of the PRECINCT architecture: LLM/Model Egress, Context/Memory, Tool, Control Loop, and Ingress/Event.

How It Works

When an agent sends a tool call, the gateway intercepts the JSON-RPC request and routes it through the middleware chain. Each layer makes an independent security decision. If any layer denies the request, processing halts and a structured error code is returned to the agent. If all layers approve, the request is forwarded to the upstream MCP server with real credentials injected at the last possible moment.

API Surface

The gateway exposes a minimal API surface. The primary endpoint handles all MCP JSON-RPC traffic. Additional endpoints support health checking and response firewall handle dereference.

Listening Modes

• Dev mode: http://localhost:9090. Plain HTTP for local development and evaluation. No mTLS required. Suitable for make up workflows.
• SPIFFE mTLS mode: https://localhost:9443. Production mode with SPIFFE mTLS authentication. All clients must present a valid SVID. Required for production deployments.

Request Processing

The following is a detailed walkthrough of what happens when an agent sends a tool call through the gateway. Each step corresponds to a layer in the 13-layer middleware chain.

1. SPIFFE Identity Verification (Layer 3)

The gateway extracts the caller's SPIFFE ID from the mTLS handshake. The SVID (SPIFFE Verifiable Identity Document) is validated against the SPIRE trust bundle. If the SVID is expired, revoked, or from an untrusted domain, the request is rejected with spiffe_auth_required.

2. Audit Logging (Layer 4)

A structured JSONL audit record is written with a unique decision ID. Each record includes a hash of the previous record, forming a tamper-evident chain. The audit log captures: timestamp, SPIFFE ID, requested tool, parameters (redacted), and the eventual decision (allow/deny with reason).

3. Tool Registry Check (Layer 5)

The requested tool is looked up in the Capability Registry. The gateway computes the SHA-256 hash of the tool's current state and compares it to the registered hash. If the hashes do not match, a rug-pull attack is assumed and the request is denied with tool_hash_mismatch. If the tool is not registered at all, the request is denied with tool_not_in_registry.

4. OPA Policy Evaluation (Layer 6)

The gateway constructs an OPA input document containing the caller's SPIFFE ID, the requested tool, the request parameters, session context, and environmental metadata. This document is evaluated against the loaded Rego policy bundle. Policies can express fine-grained rules such as "agent X may call tool Y only with parameter Z during business hours." Denied requests receive authz_policy_denied.

5. DLP Credential Blocking (Layer 7)

The DLP scanner inspects the request payload for sensitive data patterns. Detected patterns include:

• AWS access keys and secret keys
• GitHub personal access tokens
• PEM-encoded private keys and certificates
• API keys matching common provider formats
• Personally identifiable information (PII)

If credentials or sensitive data are detected, the request is denied with dlp_credentials_detected. Prompt injection patterns trigger dlp_injection_detected.

6. Session Risk Tracking (Layer 8)

The session context engine accumulates behavioral signals across requests within the same session. It tracks tool invocation patterns, data access sequences, and cumulative risk indicators. If an agent's behavior pattern resembles known exfiltration or lateral movement patterns, the session risk score is elevated.

Layer 8 now includes EscalationScore tracking that detects gradual privilege escalation across sessions. Each action's escalation contribution is calculated as Impact x (4 - Reversibility). The cumulative score is evaluated against three thresholds: Warning (≥ 15), Critical (≥ 25), and Emergency (≥ 40). When the Emergency threshold is reached, the request is denied with escalation_emergency. The current escalation score is propagated via the X-Precinct-Escalation-Score response header for downstream observability.

7. Step-Up Gating (Layer 9)

For high-risk operations (as defined by policy), the step-up gate dispatches a guard model to evaluate whether the operation should proceed. The guard model receives the full request context and returns an independent risk assessment. If the risk exceeds the configured threshold, the request is denied with stepup_required.

Step-up gating now incorporates irreversibility classification as an input signal. Actions are classified into four tiers: Low (read), Medium (create), High (modify), and Critical (delete/destroy). Critical-tier actions automatically trigger step-up evaluation regardless of the current risk score. The data classification tier is propagated via the X-Precinct-Data-Classification response header.

8. Deep Scan (Layer 10)

An asynchronous prompt injection detection layer dispatches the request content to a specialized guard model trained to identify injection attempts, jailbreak patterns, and adversarial inputs. This layer runs asynchronously to minimize latency impact on the fast path.

9. Rate Limit Check (Layer 11)

Per-identity token bucket rate limiting enforced via KeyDB. Each SPIFFE identity has a configurable rate limit budget. When the budget is exhausted, subsequent requests are denied with rate_limit_exceeded until tokens are replenished.

10. Circuit Breaker Check (Layer 12)

The circuit breaker monitors upstream MCP server health. If an upstream is experiencing failures above the configured threshold, the circuit opens and subsequent requests are immediately denied with circuit_breaker_open rather than contributing to a cascade failure.

11. Token Substitution (Layer 13)

The final layer before egress. The gateway scans the outbound request for opaque token references and resolves them to real credentials via SPIKE. The real credentials are injected into the request immediately before it is forwarded to the upstream MCP server. No middleware layer upstream of this point ever sees real credentials.

Error Codes

When the gateway denies a request, it returns a structured error code that enables agents to understand the reason for denial and adapt their behavior. Each error code maps to a specific middleware layer and denial reason.

Diagnostic Response Headers

The gateway propagates diagnostic metadata via response headers to support downstream observability and policy decisions. These headers are included on responses that traverse the relevant middleware layers.

Response Firewall

The gateway does not only inspect inbound requests. Responses from upstream MCP servers also pass through a response firewall before being returned to the agent.

When an upstream tool returns sensitive data (credentials, tokens, connection strings, or other privileged information), the response firewall replaces the raw values with opaque handles. The agent receives a handle that is meaningless outside the gateway context.

If the agent (or a downstream consumer with appropriate identity) needs the original value, it can call the POST /data/dereference endpoint with the handle. The gateway verifies the caller's SPIFFE identity against the access control policy for that handle before returning the original value.

Pluggable Extension Slots

The gateway supports three named extension slots for integrating third-party security services into the middleware chain. Extensions are external HTTP sidecar services that receive a structured request payload, evaluate it, and return an allow/block/flag decision. No gateway code changes are required to add, remove, or reconfigure extensions.

Extension Slot Positions

Each slot is positioned at a carefully chosen point in the 13-layer middleware chain where third-party inspection is both safe and useful. If no extensions are configured for a slot, the middleware is a zero-cost pass-through.

Extension Protocol

Extensions communicate with the gateway via HTTP POST. The gateway sends a structured ExtensionRequest payload to each extension's endpoint and expects a structured ExtensionResponse in return.

Request Payload (ExtensionRequest)

{
  "version": "1",
  "request_id": "d-29fa...",
  "trace_id": "abc123...",
  "timestamp": "2026-02-22T14:30:00Z",
  "slot": "post_inspection",
  "request": {
    "method": "tools/call",
    "tool_name": "file_read",
    "body": "<base64-encoded request body>",
    "spiffe_id": "spiffe://trust-domain/agent/xyz",
    "security_flags": [],
    "session_id": "sess-001"
  }
}

Which fields are included in the request object is controlled per-extension via the request_fields configuration. Extensions only receive the data they need.

Response Payload (ExtensionResponse)

{
  "version": "1",
  "decision": "allow",
  "flags": [],
  "reason": "",
  "http_status": 0,
  "error_code": ""
}

Extensions return one of three decisions:

• allow: The request passes through to the next layer.
• block: The request is denied. The gateway returns a structured error to the agent using the extension's error_code and http_status if provided.
• flag: The request continues, but the supplied flags are appended to the request's SecurityFlagsCollector for downstream layers to consider.

Configuration

Extensions are defined in a YAML registry file (config/extensions.yaml). The registry is hot-reloaded via file-system watch (fsnotify). Adding or modifying extensions does not require a gateway restart.

version: "1"
extensions:
  - name: content-scanner
    slot: post_inspection
    enabled: true
    endpoint: http://localhost:8090/scan
    timeout_ms: 2000
    fail_mode: fail_open
    priority: 100
    description: "Scans request content for policy violations"
    filters:
      methods: ["tools/call"]
      tools: []
    request_fields:
      include_body: true
      include_spiffe_id: true
      include_tool_name: true
      include_security_flags: false
    circuit_breaker:
      failure_threshold: 5
      reset_timeout_ms: 30000

Within a slot, extensions execute in priority order (lower value runs first). Filters control which requests are dispatched to each extension; empty filter lists match all requests.

Fail Modes

Each extension declares a fail mode that determines gateway behavior when the extension sidecar is unreachable or returns an error:

• fail_open: On error, skip this extension and continue processing. The request proceeds as if the extension were not configured. Appropriate for advisory or non-critical extensions.
• fail_closed: On error, deny the request with extension_unavailable_fail_closed. No request passes through if the extension cannot evaluate it. Appropriate for mandatory compliance checks.

Per-Extension Circuit Breakers

Each extension can optionally configure a circuit breaker to prevent cascading failures. When the number of consecutive failures reaches the failure_threshold, the circuit opens and the extension is skipped (or denied, depending on fail mode) until the reset_timeout_ms has elapsed. After the timeout, the circuit enters half-open state and allows one probe request through.

Reference Implementation

The PRECINCT repository includes a reference content-scanner sidecar that demonstrates the extension protocol. It registers in the post_inspection slot, receives base64-encoded request bodies, applies configurable scanning rules, and returns allow/block/flag decisions. It serves as a starting point for building custom extensions.

Configuration

The gateway is configured through a combination of YAML files, OPA policy bundles, and environment variables. The key configuration surfaces are:

Capability Registry V2

A YAML-based registry that defines all tools and models the gateway is authorized to mediate. Each entry includes the tool's name, upstream endpoint, expected SHA-256 hash, allowed callers, rate limit budget, and any tool-specific policy overrides.

OPA Policy Bundles

Rego policy files organized into bundles. Policies are version-controlled and can be updated at runtime via OPA's bundle API. The gateway reloads policy bundles periodically without requiring a restart.

DLP Rule Configuration

Regular expression patterns and detection rules for the DLP scanning layer. Rules define which patterns constitute credentials, PII, or injection attempts, along with the action to take (block, flag, or log) when a pattern is matched.

Rate Limit Budgets

Per-identity and per-tool rate limit budgets defined as token bucket parameters: bucket capacity, refill rate, and refill interval. Budgets can be overridden per SPIFFE identity to accommodate different agent workloads.

SPIFFE Trust Domain Configuration

Trust domain settings for SPIFFE/SPIRE integration. Defines the trust domain name, SPIRE server endpoint, trust bundle refresh interval, and SVID rotation parameters.

Performance

The gateway is designed around two processing paths with distinct latency profiles. The fast path handles the majority of requests with minimal overhead. The deep path adds guard model evaluation for high-risk requests.

Per-Middleware Latency Breakdown

An outer observability wrapper (Request Metrics, step 0) captures timing, size, and routing metadata (<0.1ms overhead). Each enforcement layer below emits timing spans observable in any OTel-compatible backend (Jaeger, Grafana Tempo, Datadog).