Security and threat model

What Tokenhush protects

The gateway sits between an AI coding tool and the model provider. Requests that pass through it are the requests it can work on; coverage is exactly as wide as that local path.

Prompt injection turned into exfiltration

Back-fill runs in one direction only: responses returned to the client. A placeholder that shows up in an outbound body stays a placeholder, so the original value is not forwarded.

A local process or web page reaches the gateway

The service binds loopback only (127.0.0.1 + [::1]). A Host allowlist is always enforced, the control API requires a per-run bearer token stored with 0600 permissions, and requests carrying an Origin get a same-origin check.

DNS rebinding

Host and Origin header validation stops a malicious domain that resolves to 127.0.0.1 from impersonating a trusted origin.

Placeholder collision

Placeholders come from an HMAC-deterministic mapping with a high-entropy suffix, so two secrets do not share one placeholder and a wrong back-fill cannot be triggered by a collision.

Audit log tampering

Records are append-only, and each record's hash includes the previous record's hash (HMAC chain, key in the OS keyring), so after-the-fact edits are detectable.

Plaintext written to disk

Request and response content is not stored by default. The audit trail records metadata only unless you explicitly opt in to content logging.

What Tokenhush does not protect

The public core covers tools that accept a custom base URL or endpoint. Everything outside that path is explicitly out of scope, and the list below is part of the security posture rather than fine print.

• Cursor agent traffic, ChatGPT and Claude desktop apps, and browser web UIs.These do not expose a base-URL setting, and covering them needs system-level interception with a root certificate. The public core implements neither, so this traffic does not pass through the gateway.
• Auth and refresh flows to fixed domains. With a Claude subscription, OAuth authorization and refresh always go to platform.claude.com and claude.ai, never through the gateway. Only inference requests follow the base URL, so credentials for those flows sit outside the redaction path by design.
• Values the detectors do not flag. Detection is deterministic and high-precision-first. Unflagged content travels as it normally would, which is the honest boundary of the tool.
• Third-party-verifiable compliance proof. The local HMAC chain makes tampering detectable, but it is not a compliance attestation. Do not read it as one.
• Tool-side telemetry endpoints. Some tools send their own telemetry to services such as PostHog or Sentry. Those endpoints bypass base-URL redirection and are not on the gateway's path.

Hard invariants

Five rules define the security model. The public core locks them with named tests, and this page restates them for readers who are evaluating the tool.

1. Back-fill is inbound only. Placeholders are replaced only on responses returned to the client, never on outbound requests.
2. No plaintext stored by default. Audit records are metadata-only unless content logging is explicitly enabled.
3. No root certificate, no MITM by default. System-level interception is an explicit opt-in and is not implemented in the public core.
4. Loopback only. The local service binds 127.0.0.1 and [::1], with the guardrails described above.
5. Fail-safe, not fail-open. When the gateway cannot tell whether content is sensitive, it prefers over-redaction or allows with a warning; it does not silently emit unredacted plaintext. The policy is configurable.

The local audit trail

Audit is designed to answer "what passed through the gateway" without becoming a second copy of your data. Records stay on your machine and contain metadata only by default.

Storage

Append-only SQLite in the local data directory.

Contents

Provider, endpoint, time, byte counts, redaction counts, and sensitive types. No request or response content by default.

Integrity

Each record's hash includes the previous record's hash (HMAC chain); the key is stored in the OS keyring.

Retention

14 days by default, configurable in a suggested range of 7 to 30 days.

Honest boundary

A local HMAC chain detects after-the-fact edits. It is not third-party-verifiable compliance proof.

Key handling

• V1 is passthrough. Your tools keep their own provider keys; the gateway forwards them, and it does not store them.
• If storage is ever needed. A future multi-account mode that stores keys would use the cross-platform OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service), together with a gateway token and Origin validation.
• Honest degradation. Without an OS keyring, storage falls back to a restricted file with 0600 permissions, and the active backend is reported explicitly rather than silently.

Where detection is honest

Detection is deterministic and high-precision-first: known key prefixes, high-entropy strings, JSON Web Tokens, private-key headers, Luhn-checked card numbers, and email addresses, backed by an allowlist and one-click release. No model calls, no semantic guessing.

• False positives (over-redaction) degrade the experience: the model receives a placeholder where a literal value was.
• False negatives (under-redaction) are the real risk: content the rules do not flag travels as it normally would.

The project does not make absolute claims. The approved claim is high-confidence secret interception plus full auditability.

Telemetry and site analytics

Two separate systems, stated separately.

Responsible disclosure

Public sources

Every statement on this page is drawn from the open-source core:

• Security model: threat model, invariants, audit integrity
• Architecture: goals and non-goals
• Supported tools and V1 coverage limits
• Known limitations, including auth and refresh domains
• Report a vulnerability