The identity context
A token belongs to the context it was created under, and only that context can restore it.
subject is your own identifier for the end user, or for the session. It is never a value the end user supplied about themselves. scope narrows the binding further, for example to one conversation or one purpose.
A context is required whenever anything is tokenized. The check happens up front, before any network call, so a missing context fails on your first request and not on the first real piece of personal data.
What “refused” means
A response that carries another context’s token is refused:
- By default the restore throws
RestoreDeniedError. The message says how many tokens were refused, never which, and never the values.
- With
onDenied: "leave", the tokens are left in place and counted in denied.
A token turning up in a response for someone it does not belong to is either a model repeating something it should not have seen, or an attempt to read another user’s data through yours. Either way, returning the value would be the leak. A refused restore is reported to your console as a count.
The vault
Tokenized values live in a vault. The default is process memory.
The default store is bounded and expiring, and a restart loses all of it. That is the right default for a store the SDK does not encrypt: the only copy of the original is one your own process already held.
Your own vault
A vault implements get(token) and set(token, entry), and optionally deleteContext(contextId) (delete_context in Python), which forget needs. Each entry holds the value and the opaque id of the context it belongs to.
The SDK never encrypts what it stores. A vault that persists must encrypt at rest itself, and must be protected as carefully as the data it holds.
A stable key
Pass a stable key if you use a vault that outlives the process. A token is a keyed digest, so a stable key keeps the same value on the same token across restarts. Restoring does not depend on the key, because restore looks the token up in the vault.
The context id stored in a vault is a hash of the context, not your user id.
Erasure
forget removes everything held for one identity. Afterwards nothing protected under that context can be restored, including responses still in flight.
Use it for a right-to-erasure request. It throws if the configured vault has no deleteContext.
Collisions
A token is a keyed digest cut to 12 hex characters, which is 48 bits. Before settling on a token, Cloak checks the vault. If the slot is held by a different value it moves to a longer token rather than overwrite it, because restoring the wrong person’s value would be worse than any failure to restore.
