ShadowVault — The Privacy Layer for AI Agent Tools & MCP

§ 02 / INTERACTIVE PRODUCT

Interactive Privacy Lab & Tool Simulator

Test how real customer PII is dehydrated into valid mathematical tokens for cloud LLMs, then safely restored at local private tool boundaries.

Scenario:

AGENT PROMPT INPUT: Session: session_playground_01

🛡️ Active Checksums: Luhn (Card) • Verhoeff (Aadhaar) • PAN • UPI • Email

Ready to protect

01. DEHYDRATION TIME

—

Regex & Checksum Scan

02. TOOL RE-HYDRATION

—

@vault_guard Parameter Swap

03. SSE STREAM BUFFER

—

Holdback Lookahead Buffer

04. ACTIVE MAPPINGS

0 active

AES-256-GCM Blind Index

STAGE 01 LOCAL PERIMETER Client & Local Tool

Detected Sensitive Entities (Local):

Local Tool Parameter Swap: stripe_chargeback_mcp_tool

Arguments hydrated with real values right before tool execution:

Sanitized Tool Return Payload:

STAGE 02 CLOUD LLM WIRE OpenAI / Anthropic Logs

Safe Prompt (Format-Preserving Tokens):

Downstream Schema & Algorithm Checksums:

SSE Stream Output (StreamHydrator):

STAGE 03 CRYPTOGRAPHIC VAULT AES-256-GCM

Session Mapping Table:

AES-256 Reveal

Type	Synthetic Token	Storage

At-Rest Cipher: AES-256-GCM + Blind Index

Memory Store: SQLite In-Memory with TTL

Policy Enforcement: Fail-Closed Enabled

§ 03 / IMPLEMENTATION GUIDE

Drop-In Python Quickstart (12 Lines)

Protect any Python function or agent tool in seconds. The decorator @vault_guard re-hydrates real PII right before your tool executes and sanitizes return values automatically.

Dependencies: Zero heavy ML (pure Python)

quickstart.py

# pip install shadow-vault
from shadow_vault import ShadowVault, vault_guard

vault = ShadowVault()

# 1. Protect your internal tool: automatically receives real PII, returns masked PII
@vault_guard(vault=vault, session_id_arg="session_id")
def charge_customer(email: str, card: str, session_id: str = "default") -> dict:
    # Tool executes with REAL PII: email='alice@example.com', card='4532 0151 1283 0366'
    return {"status": "PAID", "receipt": email, "backup_phone": "+91 9876543210"}

# 2. Dehydrate safe prompt for the Cloud LLM:
prompt = vault.dehydrate("Charge alice@example.com on card 4532 0151 1283 0366", session_id="s1")
# Prompt becomes: "Charge u_c09753@shadow.vault on card 4000009995970590" (Valid Luhn!)

# 3. Model executes tool with synthetic tokens -> returns sanitized output back to agent state:
result = charge_customer(email="u_c09753@shadow.vault", card="4000009995970590", session_id="s1")
# Result: {'status': 'PAID', 'receipt': 'u_c09753@shadow.vault', 'backup_phone': '+919000597059'}

§ 04 / RUNTIME PROTOCOL

Zero-Code Model Context Protocol (MCP) Gateway

Wrap any existing MCP server (Node.js, Python, Go, Rust, SQLite) with a transparent stdio privacy proxy. Intercept JSON-RPC messages between Claude Desktop, Cursor, and your tools with zero application code changes.

claude_desktop_config.json Claude Desktop & Cursor

{
  "mcpServers": {
    "secure-sqlite": {
      "command": "shadow-vault",
      "args": [
        "mcp-proxy",
        "--session-id", "claude_session",
        "--fail-closed",
        "--",
        "uvx", "mcp-server-sqlite", "--db", "customers.db"
      ]
    }
  }
}

The proxy automatically swaps synthetic tokens back to real records when Claude executes a tool, and re-dehydrates results before sending them back to Anthropic.

LangChain & LangGraph StateGraph Agentic Frameworks

from langchain_openai import ChatOpenAI
from shadow_vault import ShadowVault, protect_tool, ShadowVaultChatWrapper

vault = ShadowVault()

# Protect LangChain Tool
safe_tool = protect_tool(lookup_customer_db, vault=vault, session_id="s1")

# Protect ChatModel: prompts dehydrated, tool arguments kept synthetic
llm = ChatOpenAI(model="gpt-4o")
safe_llm = ShadowVaultChatWrapper(llm=llm, vault=vault, session_id="s1")

Ensures 0% raw PII enters LangGraph checkpoints, SQLite memory savers, or external wire telemetry.

§ 05 / MATHEMATICAL FOUNDATIONS

Supported Entities & Checksum Integrity

Unlike regex-only scanners that flag random numbers, ShadowVault couples strict regex boundaries with mathematical checksum verification (Global + India standards).

Entity Type	Mathematical Checksum / Standard	Real Sample	Synthetic Format-Preserving Token
CREDIT_CARD	Luhn Checksum Modulo 10 (13–19 digits)	4532 0151 1283 0366	4000009995970590 (Luhn valid!)
AADHAAR	Verhoeff Dihedral D5 Algorithm (12 digits)	3675 9834 6016	999905970594 (Verhoeff valid!)
PAN_CARD	Indian Income Tax Format ([A-Z]{5}[0-9]{4}[A-Z]{1})	ABCDE1234F	SHDWV7059Z
UPI_ID	Evaluated before email (@okaxis, @okhdfcbank, @paytm)	dhiraj@okaxis	u_a81c25@okshadow
EMAIL	RFC-5322 (ignores internal @shadow.vault handles)	alice@example.com	u_c09753@shadow.vault
PHONE	E.164, Indian mobile (+91 [6-9]\d{9}), US/NANP	+91 9876543210	+919000597059 (10-digit mobile)
SSN	US Social Security Number (Area/Group/Serial checks)	219-45-7890	900-99-7059 (Unissued area code)
API_KEY	OpenAI (sk-...), GitHub (ghp_...), Google (AIza...)	sk-live-51A2B3C4D5E...	sk-sv-shadow-c09753000...

§ 06 / SECURITY ASSURANCE

Independent Cryptographic Verification CLI

ShadowVault ships with zero-key self-audit tools. Verify all 6 cryptographic, mathematical, and streaming invariants locally on your machine with one command:

$ shadow-vault verify

100% REPRODUCIBLE

============================================================================

SHADOWVAULT INDEPENDENT SECURITY & REPRODUCIBILITY AUDIT

============================================================================

[Check 1/6] Cryptographic AEAD Roundtrip & Tamper Rejection... PASSED

[Check 2/6] Blind Index Independence & Cross-Session Isolation... PASSED

[Check 3/6] Checksum Integrity (Luhn Mod 10 & Verhoeff D5)... PASSED

[Check 4/6] Format-Preserving Token Dehydration & Hydration... PASSED

[Check 5/6] StreamHydrator Lookahead Buffer (Torn Token Reassembly)... PASSED

[Check 6/6] Fail-Closed Governance & Leak Interception... PASSED

----------------------------------------------------------------------------

AUDIT RESULT: 6/6 CHECKS PASSED (100% VERIFIED)

Status: Verified Ready for Agent Integration & Deployment.

Ecosystem Architectural Comparison

Why traditional document PII redactors fail in agentic tool-calling workflows

Capability	ShadowVault	Microsoft Presidio	Rizzo PII
Primary Architecture	AI Agent Tools & MCP	Document Extraction NLP	Italian Legal Anonymization
Format-Preserving Tokens	Yes (Pydantic valid)	No (<EMAIL>)	No (<LOC>)
Reversible Tool Boundaries	Yes (@vault_guard)	Manual glue needed	No (One-way redaction)
Model Context Protocol (MCP)	Yes (stdio gateway)	No	No
Runtime Core Footprint	~0 MB (Pure Python)	~500 MB (spaCy / PyTorch)	Trained Model Weights