How Tokenhush works

The path of one request

The gateway sits between your tool and the model provider. It reads each outbound request in full, rewrites detected values as placeholders, and keeps the placeholder mapping local to the session.

1. Outbound request

   The gateway reads the full JSON body and walks every leaf, running all six detectors. Each match becomes a session-scoped placeholder such as__PII_email_9f2c8a4b6d1e__. The redacted body is forwarded upstream.

2. Upstream

   The provider receives the redacted request body, with placeholders where matches were found. Values the detectors did not flag still travel as they normally would, which is why detector quality is the honest boundary of the tool.

3. Inbound response

   Placeholders that come back are replaced with the original values, and only on the path to the client. Streaming responses are handled incrementally, including placeholders split across chunk boundaries.

4. Local audit

   Each request appends a metadata-only record to a local store: provider, path, byte counts, detector hits. Content is not recorded unless you explicitly opt in, and records are chained with an HMAC so tampering is detectable.

The outbound-never-back-fill invariant

The invariant closes a specific attack path. Prompt injection can try to make a coding tool echo a stored secret into a new outbound request. If the gateway replaced placeholders on the way out, that request would carry the original value to the model. Because back-fill is inbound-only, a placeholder that appears in an outbound body stays a placeholder.

• A design invariant, not a protection guarantee. Detection is deterministic and precision-first: false positives degrade model output, false negatives let content through. The honest claim is high-confidence interception plus full auditability, not a promise that nothing sensitive can ever leave.
• The mapping is in-memory and session-scoped. Restarting the gateway drops it, so a later back-fill can surface a placeholder in output. That is safe degradation, not a leak.
• You keep control of exceptions. An allowlist keeps chosen literals out of redaction, and content plugins can add your own inspector and transformer steps.

What the six detectors cover

Detection is deliberately deterministic: rules that are cheap, explainable, and tunable. No model calls, no semantic guessing.

Secret prefixes

Known key shapes such as sk-, AKIA, or ghp_.

High-entropy strings

Long random-looking tokens that do not carry a named prefix.

JSON Web Tokens

Three-part signed tokens, recognized by structure.

PEM private-key headers

Private-key material pasted into a prompt or file.

Payment card numbers

Candidate numbers confirmed with the Luhn checksum, not digit count alone.

Email addresses

Common PII that tends to appear in prompts, diffs, and logs.

Beyond the built-in rules, the core exposes two extension paths: an allowlist for literals that must never be redacted, and content plugins (Inspector and Transformer) that run inside the pipeline. V1 supports compile-time plugins only, as described in thepublic plugin documentation.

Where the gateway fits

Coverage starts with any tool that accepts a custom base URL or endpoint: the CLI and IDE tools listed in the public README. Tools that do not expose that setting, such as some IDE agents, desktop chat apps, and browser UIs, are outside the public core's scope. It installs no root certificate and performs no system-level interception.

Traffic from your tool to the gateway stays on the loopback interface. Traffic from the gateway to the provider goes out over HTTPS, carrying the redacted request body.

Public sources

This page summarizes material published in the open-source core:

• How it works (README)
• Data flow, components, and hard invariants
• Threat model and detector trade-offs
• Content plugins (Inspector / Transformer)