🛡️ Code-Airlock

Low-Latency AI Privacy, Secret/PII Redaction & Streaming Rehydration Gateway (OpenAI Proxy + FastMCP Server)

code-airlock is a zero-trust privacy layer for LLMs and agentic coding harnesses. It intercepts sensitive credentials, financial identifiers, and personal data before they leave your machine, replaces them with deterministic session tokens (<API_KEY_1>, <PERSON_1>), and seamlessly rehydrates them back into real-time Server-Sent Events (SSE) token streams or local file writes.

• Dual Deployment Modes: Run as a drop-in OpenAI-compatible /v1/chat/completions reverse proxy or as a Model Context Protocol (MCP) server (stdio) for OpenCode, Cursor, and Claude Code.
• 2-Stage Hybrid Cascade: Combines sub-millisecond deterministic regex + mathematical checksums (Luhn, Verhoeff $D_5$, ISO 7064 MOD-97) with contextual neural NER (urchade/gliner_small-v2.1) and a curated developer allowlist.
• Zero-Delay Streaming Rehydration: Stateful sliding-window SSE parser reassembles split tokens across arbitrary 2-byte network chunks without delaying code comparison or bitwise operators (<, <<, template <typename T>).
• Minimalist Systems Footprint: ~500 lines of core runtime code (src/code_airlock/engine.py, sanitizer.py, proxy.py, mcp_server.py) plus a deterministic 2,000-row benchmark harness.

🏗️ System Architecture

flowchart TB
    classDef client fill:#1e293b,stroke:#64748b,stroke-width:2px,color:#f8fafc
    classDef stage1 fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#ecfdf5
    classDef stage2 fill:#1e3a8a,stroke:#3b82f6,stroke-width:2px,color:#eff6ff
    classDef merger fill:#312e81,stroke:#8b5cf6,stroke-width:2px,color:#f5f3ff
    classDef vault fill:#7c2d12,stroke:#f97316,stroke-width:2px,color:#fff7ed
    classDef stream fill:#4c1d95,stroke:#a855f7,stroke-width:2px,color:#faf5ff

    Client(["🖥️ Client SDK / Agent Harness<br/>(OpenAI SDK, OpenCode, Cursor, Claude Code)"]):::client

    subgraph Airlock["🛡️ CODE-AIRLOCK (proxy.py / mcp_server.py)"]
        direction TB
        subgraph Cascade["engine.py — 2-Stage Hybrid Cascade"]
            S1["⚡ Stage 1: Deterministic Fast-Pass (~0.44ms)<br/>• Regex: API_KEY, AUTH_TOKEN, EMAIL, PHONE, IPv4<br/>• Checksums: Luhn (Card), Verhoeff (ID), MOD-97 (IBAN)"]:::stage1
            S2["🧠 Stage 2: Guarded Neural NER (GLiNER-small)<br/>• Entities: PERSON, ORGANIZATION, LOCATION<br/>• Guards: 93-term TECH_ALLOWLIST + Code/Pronoun Filter"]:::stage2
            Merger{"⚖️ Span Conflict Resolver<br/>Stage 1 Overrides Stage 2<br/>Longest Span Wins"}:::merger
            S1 & S2 --> Merger
        end

        Vault[("🗄️ Ephemeral Session Vault<br/>sanitizer.py (VaultSession)<br/>Right-to-Left Tagging")]:::vault
        Rehydrator["🪟 StreamRehydrator<br/>Stateful Sliding-Window SSE & File Parser"]:::stream

        Merger --> Vault
        Vault -.->|"O(1) Token Lookup"| Rehydrator
    end

    LLM(["☁️ Upstream LLM Provider<br/>*Sees Only &lt;ENTITY_n&gt; Tokens*"]):::client

    Client -->|"1. Raw Prompt / File Read"| Cascade
    Vault -->|"2. Sanitized Payload"| LLM
    LLM -->|"3. Fragmented SSE Stream / Tool Patch"| Rehydrator
    Rehydrator -->|"4. Restored Plaintext"| Client

📊 Gold-Set Benchmark (benchmarks/gold_set.jsonl)

Evaluated on 285 developer prompts (sampled from CodeAlpaca_20K and OpenCodeInstruct with injected .env blocks, ticket escalations, billing metadata, and C++ template syntax) totaling 744 ground-truth PII spans across 11 categories:

• Hard-Negative Suite: 61/61 Passed (100% rejection of non-Luhn 16-digit order IDs, Verhoeff-invalid 12-digit numbers, MOD-97-invalid IBANs, and v192.168.1.300 version strings).
• Tech Allowlist Check: 30/30 Passed (FastAPI, Docker, Kubernetes, Redis, Postgres, AWS, Heroku, etc. produce zero false positives).

🧪 Unified 2,000-Row Benchmark Matrix

benchmarks/build_benchmarks.py deterministically generates four stratified splits into the git-ignored benchmarks/ directory (seed=42). benchmarks/benchmark.py evaluates them and writes benchmarks/BENCHMARK_RESULTS.md.

Reference result (strict exact-span matching, code-airlock v0.1.0):

• Latency: 0.194 ms p50 / 0.355 ms p95 Stage 1; 30.349 ms p50 / 39.391 ms p95 Stage 2; 30.391 ms p50 / 39.554 ms p95 total cascade.
• Per-entity support: API_KEY 756, AUTH_TOKEN 467, CREDIT_CARD 440, EMAIL 754, PHONE 465, IP_ADDRESS 442, GOVT_ID 465, IBAN_CRYPTO 465, PERSON 729, ORGANIZATION 417, LOCATION 417. Every entity is at 100% P/R/F1.
• Invariants: MCP JSON parse 100/100, JSON round-trip 100/100, adversarial SSE 2,000/2,000, hard negatives 250/250, clean rows 350/350 with zero false positives.

These are synthetic, template-composed fixtures, so the perfect headline is a regression/invariant result, not a claim of real-world accuracy. The older real-world suites (benchmarks/gold_set.jsonl: 96.7/99.1/97.9; Gitleaks artifacts: 100/88.5/93.9) remain the honest field tests.

🤗 Published Dataset

One command publishes all four splits and the auto-generated card:

python benchmarks/export_hf.py --repo-id sarthexe/pii-airlock-bench

Dataset: sarthax/pii-airlock-bench (the token owner namespace is resolved automatically).

from datasets import load_dataset
ds = load_dataset("sarthax/pii-airlock-bench")

🚀 Quickstart & MCP Setup

Option 1: Zero-Install via uvx (Recommended)

No cloning, manual virtual environments, or path debugging. Anyone with Astral's uv can run code-airlock directly from PyPI:

🤖 Claude Code (CLI)

claude mcp add code-airlock -- uvx code-airlock

💻 OpenCode (opencode.json)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "code-airlock": {
      "type": "local",
      "command": ["uvx", "code-airlock"],
      "enabled": true
    }
  }
}

🖱️ Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "code-airlock": {
      "command": "uvx",
      "args": ["code-airlock"]
    }
  }
}

🖥️ Claude Desktop (claude_desktop_config.json) & Windsurf (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "code-airlock": {
      "command": "uvx",
      "args": ["code-airlock"]
    }
  }
}

(You can also run directly from source via uvx --from git+https://github.com/sarthexe/code-airlock code-airlock).

For a local editable checkout, use the package entrypoint instead of an absolute path:

{
  "mcpServers": {
    "code-airlock": {
      "command": "python",
      "args": ["-m", "code_airlock.mcp_server"]
    }
  }
}

python -m code_airlock starts the same MCP server.

Option 2: Local Development / Manual Git Clone

git clone https://github.com/sarthexe/code-airlock.git
cd code-airlock
pip install -e ".[dev,benchmark]"

# Test tools locally over stdio
python -m code_airlock

# Or run the explicit MCP entrypoint
code-airlock-mcp

Option 3: OpenAI-Compatible Reverse Proxy (/v1/chat/completions)

Run as a transparent privacy gateway intercepting HTTP requests:

# Run with built-in zero-leak mock upstream (offline validation)
code-airlock-proxy

# Or point to a live upstream provider (OpenAI, Ollama, OpenRouter, vLLM)
export AIRLOCK_UPSTREAM_URL="https://api.openai.com"
code-airlock-proxy

The proxy binds to 127.0.0.1:8000 by default. Override with AIRLOCK_HOST / AIRLOCK_PORT.

🧠 Guiding Your Agent (.cursorrules / System Prompt)

To ensure your coding agent actually leverages the airlock tools instead of raw file reads, include this rule in your .cursorrules, CLAUDE.md, or system instructions:

# Code-Airlock Agent Guardrails
1. When reading `.env`, configuration, or log files, NEVER use standard read tools. ALWAYS call `airlock_read_file(path)` so secrets and PII are redacted into `<ENTITY_n>` tokens before hitting context.
2. When creating or editing configs, write the `<ENTITY_n>` tokens directly and call `airlock_write_file(path, content)`. The airlock will rehydrate the real secrets locally on disk without ever sending them through the LLM.
3. Call `airlock_vault_status()` to inspect active pseudonymized tokens safely (never returns plaintext values).

📁 Repository Structure

🔐 Security

Detection is best-effort and local-only. It reduces exposure but is not a guarantee that every secret is removed. See SECURITY.md for the threat model, known gaps, and private disclosure instructions.

📜 License

MIT © 2026 Sarthak Maurya. See LICENSE.