{"id":"a72b9e9d-ca16-4b74-9790-3407072eb1b7","slug":"sovereign-vault","kind":"mcp","name":"sovereign-vault","summary":"Reversible PII tokenization for LLM pipelines — send documents to cloud AI without exposing real data. Part of LexiPro Sovereign OS.","owner":"brokenbartender","repoUrl":"https://github.com/brokenbartender/sovereign-vault","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-05-04T03:22:34.000Z","addedAt":"2026-10-21T08:50:10.487Z","logoUrl":"https://avatars.githubusercontent.com/u/225426015?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["data-analytics"],"tags":["agentic-ai","anthropic","compliance","data-privacy","gdpr","gliner","hipaa","llm"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T16:09:01.615Z","sample":false,"url":"https://conduits.dev/tools/sovereign-vault","language":"Python","transports":["stdio"],"install":{"pypi":"sovereign-vault"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# sovereign-vault\n\n**Reversible PII tokenization for LLM pipelines.**\n\nSend documents containing real names, SSNs, emails, and account numbers to any cloud AI — Claude, Gemini, GPT — without exposing the actual values. The AI reasons about relationships and patterns on placeholder tokens. You reconstruct the real values locally after the response comes back.\n\n```\npip install sovereign-vault\n```\n\n[![PyPI version](https://badge.fury.io/py/sovereign-vault.svg)](https://pypi.org/project/sovereign-vault/)\n[![Downloads](https://img.shields.io/pypi/dm/sovereign-vault.svg)](https://pypi.org/project/sovereign-vault/)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![CI](https://github.com/brokenbartender/sovereign-vault/actions/workflows/ci.yml/badge.svg)](https://github.com/brokenbartender/sovereign-vault/actions)\n\n---\n\n## The problem\n\nYou have documents with names, SSNs, emails, and account numbers. You need a cloud AI to analyze patterns, identify anomalies, or summarize findings. But you can't send the raw PII — compliance, legal, or common sense says no.\n\nStandard redaction destroys the data permanently. The AI then can't reason about cross-entity relationships — *\"the same person appears in both transactions\"* becomes impossible once everything is `[REDACTED]`.\n\n### Why not just redact?\n\n| Approach | Cross-entity reasoning | Reversible | Cloud-safe | Compliance-ready |\n|----------|:---------------------:|:----------:|:----------:|:----------------:|\n| **Raw PII** | ✅ | N/A | ❌ Violation | ❌ |\n| **`[REDACTED]`** | ❌ All identity destroyed | ❌ | ✅ | ⚠️ Partial |\n| **Synthetic data** | ⚠️ Inconsistent mappings | ❌ | ✅ | ⚠️ Partial |\n| **Differential privacy** | ❌ Noise destroys fidelity | ❌ | ✅ | ✅ |\n| **sovereign-vault** | ✅ Same person = same token | ✅ | ✅ | ✅ |\n\n## The solution\n\nSovereign Vault replaces PII with **stable, HMAC-bound tokens** per session. The same value always maps to the same token, so AI can track relationships across a document. You reconstruct locally after the cloud call.\n\n```python\nfrom sovereign_vault import VaultSession\n\nwith VaultSession() as vault:\n    abstract = vault.tokenize(\n        \"John Doe (SSN: 123-45-6789) transferred funds to \"\n        \"Jane Smith (SSN: 987-65-4321) via john@firm.com on 2024-01-15.\"\n    )\n    # abstract:\n    # \"[[PERSON_A1B2C3D4_e5f6a7]] (SSN: [[SSN_B8C9D0E1_f2a3b4]]) transferred\n    #  funds to [[PERSON_F5G6H7I8_j9k0l1]] (SSN: [[SSN_J2K3L4M5_n6o7p8]])\n    #  via [[EMAIL_N9O0P1Q2_r3s4t5]] on 2024-01-15.\"\n\n    response = your_llm_client.complete(abstract)  # cloud sees only tokens\n\n    result = vault.reconstruct(response)  # real values restored locally\n    # VaultSession.destroy() called automatically on context exit\n```\n\nNo disk writes. No persistence between sessions. The mapping lives in RAM and is wiped on `destroy()`.\n\n---\n\n## Detection layers\n\nThree layers run in sequence. Each is optional — the system never falls below Layer 1 reliability.\n\n| Layer | Method | Confidence | Requires |\n|-------|--------|-----------|---------|\n| 1 — Regex | Deterministic structural patterns | 1.0 | Nothing (always active) |\n| 2 — GLiNER | Probabilistic NLP NER | 0.85× model score | `pip install sovereign-vault[ner]` |\n| 3 — Ollama | Contextual LLM sweep | 0.65 | Local Ollama + `pip install sovereign-vault[llm]` |\n\nLayer 3 triggers only when GLiNER finds fewer than 3 entities — handles implicit identifiers and role references that regex and NER miss.\n\n**Regex catches:** SSN, phone, email, IP address, credit card, passport, Michigan DL, court case numbers\n\n**GLiNER catches:** person names, organizations, locations, addresses, DOB, financial accounts, government IDs, medical record numbers\n\n**Ollama catches:** contextual identifiers — \"the defendant\", \"Account #XYZ\", implicit role-based references\n\n---\n\n## Installation\n\n```bash\n# Core (regex only — no dependencies)\npip install sovereign-vault\n\n# With NLP entity recognition\npip install sovereign-vault[ner]\n\n# With local LLM sweep (requires Ollama running locally)\npip install sovereign-vault[llm]\n\n# Everything\npip install sovereign-vault[all]\n```\n\n---\n\n## Usage\n\n### Basic round-trip\n\n```python\nfrom sovereign_vault import VaultSession\n\nraw = \"Alice (alice@corp.com, SSN 123-45-6789) authorized the transfer.\"\n\nwith VaultSession(use_gliner=False, use_ollama=False) as vault:\n    abstract = vault.tokenize(raw)\n    # Send `abstract` to cloud AI\n    cloud_response = call_your_cloud_ai(abstract)\n    restored = vault.reconstruct(cloud_response)\n```\n\n### LENIENT mode — cloud paraphrased some tokens\n\n```python\nwith VaultSession(recon_mode=ReconMode.LENIENT) as vault:\n    abstract = vault.tokenize(raw)\n    cloud_response = call_cloud(abstract)\n    # Won't raise even if cloud dropped or paraphrased some tokens\n    restored = vault.reconstruct(cloud_response)\n```\n\n### SEALED mode — abstract output only, no reconstruction\n\n```python\nwith VaultSession(seal_mode=SealMode.SEALED) as vault:\n    abstract = vault.tokenize(raw)\n    # Reconstruction is intentionally disabled\n    # Use when the abstract output IS the final product\n```\n\n### Audit log — chain of custody, no real values\n\n```python\nvault = VaultSession()\nvault.tokenize(raw)\nfor entry in vault.audit_log():\n    print(entry[\"label\"], entry[\"source_layer\"], entry[\"confidence\"])\nvault.destroy()\n```\n\n### Multi-session / server use\n\n```python\nfrom sovereign_vault import new_session, get_session, drop_session\n\nsid, vault = new_session()\nabstract = vault.tokenize(raw)\n# ... pass sid to the next step in your pipeline ...\nvault2 = get_session(sid)\nrestored = vault2.reconstruct(cloud_output)\ndrop_session(sid)  # destroys and deregisters\n```\n\n---\n\n## Security model\n\n- **RAM-only, session-scoped** — no disk writes, no persistence between sessions\n- **HMAC-bound tokens** — each token carries an HMAC tag derived from a 32-byte session secret; tampered or injected tokens raise `VaultSealBreach`\n- **Injection prevention** — input containing pre-existing `[[...]]` vault token format is rejected immediately\n- **Entropy leak detection** — `reconstruct()` flags high-entropy tokens in cloud output that may be inferred identifiers\n- **Best-effort memory wipe** — `destroy()` overwrites real values with random bytes before clearing\n\n---\n\n## Reconstruction modes\n\n| Mode | Behavior |\n|------|----------|\n| `ReconMode.STRICT` (default) | Raises `VaultReconstructionDegraded` if cloud dropped any vault token |\n| `ReconMode.LENIENT` | Allows partial reconstruction — logs missing tokens as warnings |\n| `SealMode.SEALED` | Disables reconstruction entirely — raises `VaultSealBreach` if attempted |\n\n---\n\n## Use cases\n\n- **Forensic e-discovery** — send document patterns to cloud AI without exposing real names or case numbers\n- **HIPAA pipelines** — analyze medical records cross-entity without raw patient identifiers leaving your perimeter\n- **Financial fraud detection** — transaction pattern analysis without raw account numbers\n- **Gov/defense document processing** — reason about relationships in sensitive case files\n- **Cross-agent PII passing** — sanitize data moving between local and cloud agents in an agentic pipeline\n\n---\n\n## Part of the LexiPro Sovereign OS Ecosystem\n\nsovereign-vault is the **privacy layer** of [LexiPro Sovereign OS](https://lexipro.online) — a local-first agentic AI platform running 15 MCP servers, 228 tools, and 20 agent personas on sovereign hardware. In the full OS, it powers **Workflow O (Privacy Bridge)**: tokenize before any cloud call, reconstruct locally after, audit trail preserved.\n\nsovereign-vault can also function as an **MCP middleware proxy** — intercepting `tools/call`, `resources/read`, and `prompts/get` JSON-RPC 2.0 traffic to tokenize PII before it reaches any third-party LLM. See [`examples/mcp_tool_server.py`](examples/mcp_tool_server.py) for a reference implementation.\n\nPowered by:\n- **[Anthropic Claude](https://anthropic.com)** — Tier 5 reasoning backbone for multi-file analysis\n- **[Google Gemini](https://deepmind.google/technologies/gemini/)** — OSINT, research, and long-context processing\n- **[Ollama](https://ollama.ai)** — Layer 3 local LLM sweep (Gemma, Llama) for contextual entity detection\n- **[GLiNER](https://github.com/urchade/GLiNER)** — Layer 2 zero-shot NLP NER for named entity recognition\n\n📖 **Documentation:** [Architecture](docs/ARCHITECTURE.md) · [Threat Model](docs/THREAT_MODEL.md) · [Compliance](docs/COMPLIANCE.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing guidelines, and security boundaries.\n\nIssues and PRs welcome. The detection layer system is designed for extension — add new regex patterns to `REGEX_PATTERNS`, new GLiNER entity types to `_GLINER_TYPES`, or swap the Ollama model via `ollama_model` parameter.\n\n---\n\n## Known Limitations\n\n| Limitation | Impact | Mitigation |\n|------------|--------|------------|\n| RAM-only storage | Vault lost if process crashes mid-pipeline | Call `vault.destroy()` in a `finally` block; checkpoint vault keys externally if needed |\n| Probabilistic NER (GLiNER/Ollama) | Novel PII formats may not be detected | Use `coverage_report()` after tokenize to assess detection quality |\n| Regex layer only on plain text | HTML entities, encoded chars may slip through | Pre-normalize input with `html.unescape()` before tokenizing |\n| Session-scoped tokens | Same real value gets different token in different sessions | Design your pipeline to tokenize once per document, not per chunk |\n| Not a legal compliance layer | Sovereign Vault assists compliance; it cannot replace legal review | Combine with your organization's data classification policy |\n\n---\n\n## Comparison: Sovereign Vault vs. alternatives\n\n| Feature | sovereign-vault | Microsoft Presidio | AWS Comprehend PII | Simple regex redaction |\n|---------|----------------|-------------------|-------------------|----------------------|\n| Reversible tokenization | Yes | No (replace only) | No | No |\n| HMAC integrity on tokens | Yes | No | No | No |\n| Offline capable | Yes (regex layer) | Partial | No (API) | Yes |\n| Named entity detection | Yes (GLiNER + Ollama) | Yes (spaCy) | Yes (cloud) | No |\n| STRICT mode audit trail | Yes | No | No | No |\n| Cloud cost | $0 (local) | $0 (local) | Per-call | $0 |\n| Setup complexity | pip install | pip + models + server | AWS credentials | None |\n\n\n---\n\n## Compliance Disclaimer\n\nSovereign Vault is a **technical tool** that assists with PII handling in LLM\npipelines. It is not a legal compliance product and does not constitute legal\nadvice.\n\n**GDPR / HIPAA / CCPA:** Tokenizing PII before sending it to a cloud model\nreduces exposure but does not by itself satisfy the requirements of any data\nprotection regulation. Your compliance obligations depend on your specific use\ncase, data classification, and organizational policies. Consult qualified legal\ncounsel before deploying in regulated environments.\n\n**What sovereign-vault does:**\n- Replaces PII with HMAC-bound tokens so cloud AI never receives raw values\n- Provides an audit trail of all vaulted entities (no real values in log)\n- Wipes vault from RAM on `destroy()` call\n\n**What sovereign-vault does NOT do:**\n- Guarantee detection of all PII in all languages and formats\n- Provide legal indemnification or certification\n- Replace a data classification policy or DPO review\n- Encrypt data at rest (vault is RAM-only by design)\n\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\nBuilt by [Broken Arrow Entertainment LLC](https://lexipro.online) · Sovereign Intelligence Systems Group\n"}