[Ardem2025]

Summary

This PR introduces Reversible PII Token Vault — an enterprise-grade bidirectional pseudonymization and outbound detokenization mechanism for OmniRoute.

When enabled (PII_REVERSIBLE_VAULT_ENABLED=true), sensitive personal data (emails, phones, national IDs, SSN/CPF, and custom PII patterns) are pseudonymized into surrogate tokens before reaching upstream LLM providers, and transparently re-hydrated on egress back to the client.

Architecture & Key Highlights

1. Inbound Pseudonymization (src/shared/utils/inputSanitizer.ts)

   • Instead of destructive, irreversible placeholders like [PHONE_REDACTED], detected PII items are mapped to surrogate tokens (<<PII_EMAIL_1>>, <<PII_PHONE_2>>).
   • Zero sensitive PII is transmitted upstream to external LLMs (Google, OpenAI, Anthropic, DeepSeek, etc.).

2. Zero-TTFT Speculative Streaming Detokenization (open-sse/handlers/chatCore/streamingPipeline.ts)

   • Implemented via a lightweight WHATWG TransformStream (createDetokenizingStream).
   • Zero TTFT Overhead: Standard text chunks are enqueued and emitted immediately. Speculative buffering activates strictly when an opening < prefix is detected at the tail of a chunk.
   • Transparently handles tokens split across arbitrary network chunk boundaries (e.g. <<PII_PH + ONE_1>>).
   • Uses safeJsonEscape to guarantee valid JSON string escaping within SSE delta frames.

3. Non-Streaming JSON Support (open-sse/handlers/chatCore/nonStreamingJsonResponse.ts)

   • Automatically detokenizes non-streaming responses (buildNonStreamingJsonResponse) with accurate Content-Length computation.

4. Zero-Disk Retention & DoS Protection (src/lib/pii/tokenVault.ts)

   • Zero-Disk Invariant: Token-to-value mappings are maintained strictly in Node.js heap memory (TokenVaultManager) and are never written to disk or logs.
   • LRU Eviction: Default capacity of 5,000 active mappings (PII_VAULT_MAX_ENTRIES) protects against memory bloat.
   • Short Sliding TTL: Mappings expire automatically after 120s (PII_VAULT_TTL_MS).
   • Clean Event Loop: Sweeper timer uses timer.unref(), ensuring worker threads and test runners exit cleanly without dangling handles.

5. Opt-in Compliance (Hard Rule feat: v0.2.0 — advanced routing services, cost analytics, pricing overhaul #20)

   • The feature is completely opt-in and defaults to false (PII_REVERSIBLE_VAULT_ENABLED=false). Existing behavior is 100% preserved when disabled.

Test Coverage

Added comprehensive unit test suite in tests/unit/pii/tokenVault.test.ts (7/7 tests passing):

• ✔ TokenVaultManager - surrogate generation, reuse, and TTL expiration
• ✔ TokenVaultManager - LRU capacity eviction
• ✔ createDetokenizingStream - Zero-TTFT fast path without tokens
• ✔ createDetokenizingStream - detokenizes single chunk with surrogate tokens
• ✔ createDetokenizingStream - speculative buffer across split chunk boundary
• ✔ detokenizeResponsePayload - non-streaming JSON body detokenization
• ✔ safeJsonEscape - preserves quotes and special characters inside SSE

[diegosouzapw]

Thanks @Ardem2025, a reversible vault is a good idea and keeping it opt-in is exactly right. One design issue we would like to fix together before merging: the vault is a single process-wide map, so a response in one request can restore a token that was minted for another request (for example a model echoing <<PII_EMAIL_1>>), which would leak another user's value. If you scope the vault to the request (or add a per-request nonce to the token), register the flag in featureFlagDefinitions with a false default, run Prettier, and add a test for two concurrent requests, this will be in good shape. Happy to push those changes on your branch if you prefer.

[Ardem2025]

Thanks for the thorough review and great catch, @diegosouzapw! That's a critical point regarding cross-request token leakage.

I've updated the PR accordingly:

1. Request-Scoped Isolation & Nonces: Vaults are now scoped per request via AsyncLocalStorage and surrogate tokens include a unique random nonce (<<PII_<TYPE>_<NONCE>_<SEQ>>>). Outbound detokenization resolves strictly against the originating request vault, preventing cross-request token restoration.
2. Feature Flag Registration: Added PII_REVERSIBLE_VAULT_ENABLED with default false (category security) to featureFlagDefinitions.ts and synced docs/reference/FEATURE_FLAGS.md.
3. Concurrent Request Tests: Added unit test coverage in tests/unit/guardrails/tokenVault.test.ts for concurrent non-streaming and streaming requests with cross-echoed tokens to verify data isolation.
4. Formatting: Ran Prettier across all touched files.

Pushed in commit a369e10d2.