pii-airlock 0.2.0__tar.gz

pii_airlock-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,52 @@
+name: Bug report
+description: Something doesn't work as documented
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report! For **security vulnerabilities**, do not file a
+        public issue — see [SECURITY.md](../../SECURITY.md).
+        **Never paste real PII or a mapping file.** Use fake data in examples.
+  - type: input
+    id: version
+    attributes:
+      label: pii-airlock version
+      placeholder: "e.g. 0.2.0  (pii-airlock --version)"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options: [macOS, Linux, Windows, Other]
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "e.g. 3.12.4"
+    validations:
+      required: true
+  - type: dropdown
+    id: workflow
+    attributes:
+      label: Which workflow?
+      options: [CLI pipe, Gateway (proxy), Claude Code hooks, Other]
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Minimal commands or code. Use fake data only.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected vs actual behavior
+    validations:
+      required: true

pii_airlock-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/matinfo/pii-airlock/security/advisories/new
+    about: Report privately. Do not open a public issue for security problems.
+  - name: Question / discussion
+    url: https://github.com/matinfo/pii-airlock/discussions
+    about: Ask questions and share usage ideas.

pii_airlock-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: Feature request
+description: Suggest an improvement (new provider, language, format, …)
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options: [New provider adapter, New language, File format, Gateway, Hooks, CLI, Docs, Other]
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered

pii_airlock-0.2.0/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      python-deps:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

pii_airlock-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,16 @@
+<!-- Thanks for contributing! Keep PRs focused. Never include real PII. -->
+
+## What & why
+
+<!-- What does this change and what problem does it solve? -->
+
+## How verified
+
+- [ ] `ruff check .` passes
+- [ ] `pytest -q` passes
+- [ ] Added/updated tests for the change
+- [ ] Updated docs (README / AGENTS.md / CHANGELOG) if user-facing
+
+## Notes
+
+<!-- Breaking changes, follow-ups, anything reviewers should know. -->

pii_airlock-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Full Python range on Linux; representative versions on macOS + Windows
+        # to prove cross-OS behaviour without a 15-job matrix.
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        include:
+          - os: macos-latest
+            python-version: "3.12"
+          - os: macos-latest
+            python-version: "3.13"
+          - os: windows-latest
+            python-version: "3.12"
+          - os: windows-latest
+            python-version: "3.13"
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (with dev extras)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        # Unit tests stub out Presidio/spaCy, so no model download is needed.
+        # The proxy tests exercise the real ASGI stack with a mocked upstream.
+        run: pytest -q

pii_airlock-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+# Publishes on a GitHub Release. Uses PyPI Trusted Publishing (OIDC) — no API
+# token stored in the repo. One-time setup: create the project's trusted
+# publisher on PyPI (https://docs.pypi.org/trusted-publishers/) pointing at this
+# repo + workflow, and create a "pypi" environment in the repo settings.
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Check metadata
+        run: |
+          python -m pip install twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pii_airlock-0.2.0/.gitignore

@@ -0,0 +1,19 @@
+# Mapping files contain REAL PII — never commit them.
+*.pii-map.json
+*.pii-map.*
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# OS
+.DS_Store

pii_airlock-0.2.0/AGENTS.md

@@ -0,0 +1,136 @@
+# Integrating pii-airlock with AI coding agents
+
+pii-airlock keeps real PII out of LLM traffic for the agents and clients you
+already use. There are two integration styles:
+
+- **Gateway** — point the client's *base URL* at the local proxy. Transparent,
+  bidirectional (scrubs the request, restores the response). Best for chat-style
+  and OpenAI/Anthropic/Gemini-compatible clients.
+- **Hooks** — Claude Code's native guardrail events. Best for agentic, tool-using
+  sessions where rewriting the payload would interfere with the tool loop.
+
+Start the gateway once:
+
+```bash
+pipx inject pii-airlock 'pii-airlock[proxy]'
+pii-airlock proxy            # http://127.0.0.1:8745  (127.0.0.1 only by default)
+```
+
+---
+
+## Setting an environment variable (all platforms)
+
+Most clients read a base-URL environment variable. Set it in the shell that
+launches the client:
+
+| Shell / OS | Command |
+|---|---|
+| bash / zsh (macOS, Linux) | `export OPENAI_BASE_URL=http://127.0.0.1:8745/openai` |
+| fish | `set -x OPENAI_BASE_URL http://127.0.0.1:8745/openai` |
+| PowerShell (Windows) | `$env:OPENAI_BASE_URL = "http://127.0.0.1:8745/openai"` |
+| cmd.exe (Windows) | `set OPENAI_BASE_URL=http://127.0.0.1:8745/openai` |
+
+Swap the variable/route for the provider (`/anthropic`, `/gemini`) as below.
+
+---
+
+## Per-agent setup
+
+### Claude Code  *(recommended: hooks)*
+
+Claude Code is agentic — it moves files and runs commands. Use the **hooks** so
+PII is surfaced without disturbing the tool loop:
+
+```bash
+pii-airlock install-hook            # both events, project scope
+pii-airlock install-hook --scope user
+```
+
+| Leak vector | Covered by |
+|---|---|
+| PII you type in a prompt | `UserPromptSubmit` |
+| PII in a file Claude reads | `PreToolUse` |
+| PII in a shell command Claude runs | `PreToolUse` |
+
+> You *can* also route Claude Code's API traffic through the gateway with
+> `ANTHROPIC_BASE_URL`, but tool-call arguments aren't restored, which can affect
+> agentic runs. Prefer hooks for Claude Code; use the gateway for chat clients.
+
+### Codex CLI / OpenAI SDK / OpenAI-compatible tools
+
+```bash
+export OPENAI_BASE_URL=http://127.0.0.1:8745/openai
+```
+
+Works with the official OpenAI SDKs, the Codex CLI, `litellm` (`api_base=...`),
+`vllm`/Ollama front-ends, and most "OpenAI-compatible" tools.
+
+### Anthropic SDK
+
+```bash
+export ANTHROPIC_BASE_URL=http://127.0.0.1:8745/anthropic
+```
+
+### Cursor
+
+Settings → **Models** → enable *Override OpenAI Base URL* and set it to:
+
+```
+http://127.0.0.1:8745/openai
+```
+
+(Use a model served through an OpenAI-compatible endpoint.)
+
+### Continue.dev (VS Code / JetBrains)
+
+In `~/.continue/config.json`, set `apiBase` on the model:
+
+```json
+{
+  "models": [
+    { "title": "via pii-airlock", "provider": "openai",
+      "model": "gpt-4o", "apiBase": "http://127.0.0.1:8745/openai" }
+  ]
+}
+```
+
+### Aider
+
+```bash
+export OPENAI_API_BASE=http://127.0.0.1:8745/openai
+aider
+```
+
+### Google Gemini (google-genai SDK)
+
+```python
+from google import genai
+from google.genai.types import HttpOptions
+
+client = genai.Client(
+    api_key="...",
+    http_options=HttpOptions(base_url="http://127.0.0.1:8745/gemini"),
+)
+```
+
+> Gemini's non-SSE streaming is buffered then restored as one response. Pass
+> `alt=sse` if your client supports it for live streaming.
+
+---
+
+## Adding a provider
+
+Adding a provider is one small adapter — see
+[`pii_scrub/payload.py`](pii_scrub/payload.py): implement `scrub_request`
+(where user text lives) and `restore_response` (where model text lives), register
+it, add tests. PRs welcome (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+
+## Verify it's working
+
+```bash
+pii-airlock proxy &
+export OPENAI_BASE_URL=http://127.0.0.1:8745/openai
+# Run your client with a fake email/name in the prompt, then check the provider
+# dashboard / logs: you should see <EMAIL_ADDRESS_1>, not the real value, while
+# your client still shows the real value in the answer.
+```

pii_airlock-0.2.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+- **Renamed to `pii-airlock`** (`pii-scrub` was unavailable on PyPI). The PyPI
+  package, the CLI command, and the GitHub repository are now `pii-airlock`;
+  config lives at `~/.config/pii-airlock/` and `./.pii-airlock.yaml`. Only the
+  internal Python import package stays `pii_scrub` (invisible to users).
+
+### Fixed
+- **Gateway robustness:** upstream connection/timeout failures now return a clean
+  `502` instead of a traceback; a missing spaCy model returns `503` and **never
+  forwards the request** (no PII leak on failure); the raw query string is
+  forwarded so multi-value params and Gemini's `?key=` are preserved exactly.
+- **Packaging:** `config.default.yaml` is now shipped inside the package and the
+  built-in `Config` carries default model mappings. Previously a non-editable
+  install (PyPI / `pipx`) could load an empty model map and fail with "No spaCy
+  models configured". Now a fresh install works out of the box.
+
+### Added
+- Community layer: README badges, `AGENTS.md` (per-agent integration matrix),
+  `SECURITY.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `CHANGELOG.md`, issue/PR
+  templates, Dependabot, and a PyPI trusted-publishing release workflow.
+
+## [0.2.0] - 2026-06-20
+
+### Added
+- **Universal gateway** (`pii-airlock proxy`): a local reverse proxy that scrubs
+  PII out of outbound requests and restores it in responses (including SSE
+  streams), for any provider. Base-URL shim — no TLS interception.
+- **Payload adapters** (`pii_scrub/payload.py`): provider-agnostic core with
+  OpenAI-compatible, Anthropic, and Gemini adapters. Adding a provider is one
+  small adapter.
+- `StreamRestorer` reassembles placeholder tokens split across stream chunks.
+- `[proxy]` optional dependency group (httpx, starlette, uvicorn).
+- `AGENTS.md` per-agent integration guide; SECURITY, CONTRIBUTING, CODE_OF_CONDUCT.
+
+### Changed
+- Detection is now serialized with a lock so the engine is safe to share across
+  threads (used by the gateway).
+- Mapping files are created `0600` atomically via `os.open` (no world-readable
+  window on POSIX).
+- README rewritten for accuracy: explicit guarantees & limitations; the false
+  "no data ever leaves your machine" blanket claim was removed (the gateway
+  forwards *scrubbed* traffic).
+- CI now runs on Linux, macOS and Windows.
+
+### Removed
+- Unused `csv` extra (CSV/JSON handling uses the standard library).
+
+## [0.1.0] - 2026-06-20
+
+### Added
+- Reversible CLI: `scrub`, `restore`, `detect`, `download-models`.
+- Deterministic placeholder tokens (`<TYPE_N>`) with a reversible mapping store.
+- Multilingual detection on Microsoft Presidio + spaCy (English + French defaults).
+- Format handlers: plain text, CSV, JSON (stdlib), `.docx` and PDF (optional extras).
+- Claude Code guardrail hooks: `PreToolUse` and `UserPromptSubmit`, plus
+  `install-hook`.
+- Config override chain: bundled defaults → user → project → CLI flags.
+
+[Unreleased]: https://github.com/matinfo/pii-airlock/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/matinfo/pii-airlock/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/matinfo/pii-airlock/releases/tag/v0.1.0

pii_airlock-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,57 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards and
+will take appropriate and fair corrective action in response to any behavior
+they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers at **m.meylan@gmail.com**. All complaints will be
+reviewed and investigated promptly and fairly. Community leaders are obligated to
+respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

pii_airlock-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to pii-airlock
+
+Thanks for helping make PII safer for AI workflows. Contributions of all kinds
+are welcome: bug reports, docs, new language configs, and new provider adapters.
+
+## Quick start
+
+```bash
+git clone https://github.com/matinfo/pii-airlock
+cd pii-airlock
+python -m venv .venv && . .venv/bin/activate    # Windows: .venv\Scripts\activate
+pip install -e ".[dev,all]"
+```
+
+## Before you open a PR
+
+```bash
+ruff check .        # lint (also: ruff format .)
+pytest -q           # unit + integration tests, fully offline
+```
+
+Both must pass. CI runs them on Linux (Python 3.10–3.14) and on macOS + Windows.
+
+- Tests stub Presidio/spaCy, so they need no model download and no network.
+- Keep new code lint-clean and add tests for new behavior.
+- Match the surrounding style (type hints, `from __future__ import annotations`,
+  small focused modules).
+
+## Good first contributions
+
+- **Add a language.** spaCy ships models for many languages — see the README
+  "Adding a language". A docs PR listing a working `{lang: model}` pair is useful.
+- **Add a provider adapter.** Implement a `PayloadAdapter` in
+  `pii_scrub/payload.py` (one class: where user text lives in the request, where
+  model text lives in the response) and register it. Add tests in
+  `tests/test_payload.py` mirroring the existing ones. See `AGENTS.md`.
+- **Custom recognizers** to improve detection (e.g. locale-specific phone/ID
+  formats) via Presidio's recognizer registry.
+
+## Commit & PR conventions
+
+- Conventional-commit style subjects are appreciated (`feat:`, `fix:`, `docs:`…).
+- Describe the user-facing change and how you verified it.
+- One logical change per PR where practical.
+
+## Reporting bugs / security
+
+- Bugs: open an issue using the template.
+- Security vulnerabilities: **do not** open a public issue — see
+  [SECURITY.md](SECURITY.md).
+
+By contributing you agree your contributions are licensed under the project's
+[MIT License](LICENSE).

pii_airlock-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pii-scrub contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.