Core concepts

A few concepts underpin everything in ContextDataVault. Understanding them makes the API straightforward.

Vault

A vault is the encryption boundary. It holds secrets and context tokens, and has its own data key. All content inside a vault is encrypted with that key, which is itself wrapped by a per‑tenant key derived from the server’s master key. Vaults can be re‑keyed without exposing plaintext.

Secret

A secret is an encrypted credential — an API key, password, connection string, or any sensitive value. Secrets are:

• Encrypted at rest with AES‑256‑GCM using the vault’s data key.
• Versioned — rotation keeps history without breaking references.
• Always audited on value reads, including denied attempts.

Context token

A context token replaces sensitive text with an opaque UUID. Your application stores the token; ContextDataVault stores the underlying content. When an authorized caller resolves the token, the content is returned and the access is logged. This lets you keep sensitive context out of prompts, logs, and third‑party systems while still using it when needed.

Principal

A principal is an identity: a user, a service, or an agent. Principals authenticate with scoped API tokens, so each identity gets only the permissions it needs.

Policies and grants — the authorization model

Access is decided by two objects working together:

• A policy defines rules — time windows, rate limits, and whether an access requires approval.
• A grant binds a principal to a resource (a secret or token) under a policy.

When a principal requests a value, the vault evaluates the applicable grant and its policy, records the decision in the audit log, and returns the value only if every rule passes. Denied attempts are audited too.

Audit log

The audit log is an immutable record of every read, write, and access decision across the system. It is the source of truth for “who accessed what, when, and whether it was allowed.”