Threat model

This document describes the adversary assumptions, trust boundaries, and security controls built into CloakAPI. It also states honestly what CloakAPI does not protect against.

In-scope assumptions

The following properties are assumed to hold for the system to provide its stated guarantees:

Property	Implementation
Transport encryption	All connections between client, gateway, and LLM providers use TLS 1.2 or 1.3 with modern AEAD cipher suites; legacy protocols (TLS 1.1 and older) are rejected at the edge.
Signed receipts	Every LLM response is sealed with a signed receipt envelope, ECDSA P-256 signed with a key from the `gw-prod-YYYY-qN` rotation cycle. Receipts are chain-linked via SHA-256 to a transparency seed.
Tokenisation before egress (client-side)	On the client-side ways — the browser chat, the desktop app, the browser extension, or the local proxy (`base_url=http://localhost:8799/v1`) — customer PII is tokenised on the customer’s own device, so personal data never leaves the machine and the gateway receives only opaque tokens. The gateway itself is a blind token relay: it forwards what the client sends and never inspects, detects, or tokenises content on our servers. A bare OpenAI/Anthropic SDK pointed straight at `api.cloakapi.io` is therefore blind-relayed as-is — not tokenised by us. To tokenise with a plain SDK, run the local proxy (see Quickstart Option C).
Receipt JWKS public	Signing public keys are served at `https://api.cloakapi.io/api/.well-known/cloakapi-receipt-pubkeys.jwks` and are independently verifiable without trusting CloakAPI.

Adversaries we defend against

1. Compromised LLM provider

Threat: An attacker gains read access to an LLM provider’s inference infrastructure and observes all prompt traffic in plaintext.

Control: On the client-side ways (browser chat, desktop, extension, local proxy) tokenisation occurs pre-egress on the customer’s device, so the payload reaching the LLM provider contains structural tokens ([NAME:a1b2], [EMAIL:c3d4]), not the underlying values. A compromised provider cannot reconstruct the original PII without the tokenisation map, which is never sent to the provider. The gateway is a blind relay and does not tokenise server-side — with a bare SDK pointed straight at api.cloakapi.io, whatever the client sends is relayed as-is, so this control holds only when a client-side way performs the tokenisation.

Limitation: This protection degrades if the customer’s application de-tokenises values before sending prompts, or if the LLM system prompt itself contains PII injected by the application layer.

2. Malicious insider at LLM provider

Threat: An employee with access to LLM serving infrastructure attempts to extract customer data from stored prompt logs.

Control: Same as above — gateway sends tokens, not plaintext. Additionally, CloakAPI does not retain prompt content. The gateway stores only the signed receipt metadata (token counts, model ID, timestamp, hash chain link). Prompt body is never persisted server-side.

Limitation: CloakAPI cannot enforce LLM provider data-retention policies. Enterprise customers should review each provider’s DPA and enable prompt logging opt-out where available.

3. Network MITM between gateway and LLM provider

Threat: An attacker with a position on the network between api.cloakapi.io and the upstream LLM API intercepts or modifies traffic.

Control: TLS with strict certificate verification in the gateway process. Outbound connections to OpenAI, Anthropic, Google Gemini, xAI Grok, and DeepSeek enforce full peer and hostname verification (CURLOPT_SSL_VERIFYPEER / VERIFYHOST=2) against the system trust store. Modifications to the response body would invalidate the ECDSA signature on the receipt. Certificate/CA pinning is not currently deployed.

Limitation: An attacker who can insert a trusted CA into the gateway’s trust store — or who compromises a public CA — would break this control. This scenario is equivalent to (or as severe as) gateway infrastructure compromise (see “adversaries we don’t defend against”).

4. Compromised customer endpoint (server-side application)

Threat: A customer’s backend server using the CloakAPI SDK is compromised. The attacker attempts to exfiltrate data or forge receipts.

Control: API keys can be rotated or revoked on demand; both deactivate the old key immediately. Receipts are signed by CloakAPI’s keys, not the customer’s. A compromised endpoint cannot forge a valid receipt for a response it fabricated. Rotation invalidates the compromised key.

Limitation: A compromised backend has full access to tokenisation maps, so it can de-tokenise any intercepted receipts or future prompts. The integrity guarantee (receipt authenticity) is preserved; the confidentiality guarantee depends on the customer’s own endpoint security.

Adversaries we do NOT defend against

Compromised customer browser running the tokeniser

If the customer’s browser is already compromised (malware, XSS with full DOM access, malicious browser extension with <all_urls> permission), an attacker can observe PII values before tokenisation. CloakAPI’s WASM tokeniser operates in the same browser context. There is no feasible defence against a fully compromised browser at the application layer.

OS-level keyloggers on the customer machine

A keylogger or screen-capture malware on the user’s device observes keystrokes or screen pixels before any application layer processes them. This is outside CloakAPI’s threat boundary.

Compromised CloakAPI infrastructure

If the CloakAPI gateway itself is compromised — including the key management system, the gateway process, or the HSM interface — all guarantees break down. CloakAPI is a trusted intermediary. Customers who cannot accept this trust dependency should run a self-hosted gateway instance (self-hosted deployment, roadmap).

Quantum adversary with harvested ciphertext

ECDSA P-256 and TLS 1.3 (X25519 key exchange) are not post-quantum secure. A future adversary harvesting TLS sessions today could decrypt them with a cryptographically relevant quantum computer. Post-quantum migration is on the roadmap but not deployed.

Trust boundaries

Customer browser / SDK
        │
        │  Tokenised payload (no raw PII)
        ▼
CloakAPI Gateway (api.cloakapi.io)
        │
        │  Receipt signed here (ECDSA P-256, kid: gw-prod-YYYY-qN)
        │  Transparency seed written to append-only log
        │
        ▼
LLM Provider (OpenAI / Anthropic / Google Gemini / xAI Grok / DeepSeek)
        │
        │  Token response (structural tokens)
        ▼
CloakAPI Gateway
        │
        │  Seals signed receipt envelope
        ▼
Customer application

The critical trust boundary is between the customer’s device and the CloakAPI gateway. PII must be tokenised on the customer side of this boundary. Everything to the right of the gateway (LLM providers) sees only tokens.

Control-to-threat mapping

Control	Threat mitigated
Pre-egress WASM tokenisation	Compromised LLM provider; malicious insider at LLM provider
TLS with strict certificate verification (gateway → provider)	Network MITM
ECDSA P-256 receipt signatures	Tampering with response content; forged receipts
SHA-256 chain links (transparency seeds)	Retroactive deletion or modification of receipt log
API key rotation (immediate deactivation)	Compromised customer endpoint key
Public JWKS at well-known URL	Enables independent third-party receipt verification
No server-side prompt retention	Reduces blast radius of gateway infrastructure compromise

Known limitations

Tokenisation coverage is not exhaustive. The current PII engine covers 13 entity types (EMAIL, PHONE, SSN, PERSONNUMMER, IBAN, CREDIT_CARD, IP_ADDRESS, IP_ADDRESS_V6, DATE_OF_BIRTH, PASSPORT, NAME, ADDRESS, ORGANIZATION). Sensitive data outside these categories will flow through as plaintext tokens. See Detection coverage for honest evasion cases.
Receipts prove authenticity, not privacy. A signed receipt proves that a specific response was returned by the gateway for a specific tokenised request. It does not prove that the upstream LLM provider did not log the request.
Transparency log is opt-in. Orgs must enable transparency participation. A receipt from an org that has not opted in is still cryptographically signed but does not appear in the public seed feed.
HSM deployment is conditional. Standard accounts use software-backed key material (PEM files under restrictive permissions in the isolated gateway container). Full HSM deployment (dedicated hardware security module, audited key ceremony) is available on enterprise request. See Key rotation.
SLSA provenance is planned. Current build provenance is SLSA L0. SLSA L3 is on the roadmap. See Reproducibility.