Evidence Vault
By default OpenProdkt records digests and metadata of a call, never its content. The evidence vault is an optional way to keep the content too, without OpenProdkt ever holding it. Your enforcement point encrypts the call's input and output with a key that you hold, stores the encrypted record in storage that you own, and tells OpenProdkt only where it put it.
The vault is available with the evidence.vault entitlement on an Enterprise licence, which also needs the optional evidence feature (evidence.enabled). It is off until a super_admin turns it on.
What stays where
| You | OpenProdkt | |
|---|---|---|
| The content of the call (input and output) | Encrypted in your process, stored in your storage | Never sent, never stored |
| The encryption key | Held in your key service | Never held, never requested |
| A pointer to the encrypted record | Created by your enforcement point | Stored as a claim, never read |
| The opt-in flag | Stored, changed by a super_admin |
OpenProdkt never calls your key service or your storage. It cannot read, fetch or verify a record, and it makes no decision from the pointer.
Turn it on
- Confirm that your licence includes
evidence.vault.GET /v1/evidence-vaultreturnsentitled: truewhen it does. - A signed-in
super_adminenables it:
PUT /v1/evidence-vault
Content-Type: application/json
{ "enabled": true }
GET /v1/evidence-vault returns { version, organization_id, enabled, entitled, updated_at, updated_by }. API keys cannot change the flag, and neither can other roles. Enabling without the entitlement is refused with 403. Disabling never needs it. Every change is recorded with an evidence.vault.settings.changed audit event, and the history of changes is append-only.
- Configure the vault in your enforcement point. The Go, Python and TypeScript SDK guards support it (see SDKs). The MCP adapter supports it as a Go library option for embedders who supply their own storage writer and key service client; the
openprodkt-mcp-pepcommand does not turn it on yet. The Envoy adapter does not support it.
What a request carries
An evaluation (POST /v1/evaluate, POST /v1/proxy/evaluate) and an outcome report (POST /v1/proxy/outcomes) accept two optional members. A request carries one of them at most.
vault_ref points to a record you stored:
| Member | Rule |
|---|---|
kind | input on an evaluation, output on an outcome report |
object_key | 1 to 512 printable ASCII characters |
version_id | 1 to 512 printable ASCII characters |
key_ref | 1 to 256 printable ASCII characters. Names your key; it is not the key |
ciphertext_digest | sha256: and 64 lowercase hex characters, the digest of the stored encrypted record |
vault_gap says why a record was not written: { "reason": "..." } with key_service_unavailable, storage_unavailable, record_too_large or write_failed.
The whole member is at most 1 KiB. Unknown members are refused.
| Situation | Answer |
|---|---|
Malformed member, wrong kind, or both members | 400 invalid_vault_ref. The message never repeats a value. Nothing is recorded |
vault_ref and no evidence.vault entitlement | 403 entitlement module not enabled |
vault_ref and the flag is off | 422 vault_not_enabled. Nothing is recorded |
vault_ref and the flag cannot be read | 503 vault_unavailable. Retry |
vault_gap while the entitlement is missing or the flag is off | Ignored, and the request proceeds as usual |
Requests without these members behave exactly as before.
What OpenProdkt records
While the vault is on, each decision and each outcome records one of:
- the pointer you sent, exactly as validated,
- the gap reason you reported, or
- the gap
absent, set by OpenProdkt, when the request carried neither.
Decisions and outcomes recorded before you enabled the vault, or while it was off, hold nothing.
The first outcome report for an operation is authoritative, including its vault state. A later identical report with different vault members is accepted as a retry and does not change what was recorded.
The audit events for the decision and the outcome carry the same information in a vault member. A pointer is labelled claimed, because OpenProdkt never verified it. A gap names its reason and source: client for a reason you reported, server for absent. Webhook and notification payloads never carry it.
When a decision or an outcome records a gap, the background worker also writes one evidence.vault.gap audit event per asset, side, reason and UTC day, so a stream of calls with the same gap produces one event a day, not one per call. The audit coverage counts show exact totals. See Audit for the event fields.
The pointer cannot change the outcome of a call. The same request with and without a pointer gets the same decision.
When a write fails
The enforcement point decides, in your environment, what a failed write means. The defaults of the OpenProdkt SDKs and adapter:
- The input record cannot be written. The call is refused: no evaluation, no tool call. This is the default, so a missing record never goes unnoticed.
- Digest-only mode. You can choose to continue instead. The call proceeds and the evaluation carries a
vault_gap, which is recorded. - The output record cannot be written. The tool already ran, so its result is returned unchanged. The real outcome is reported with a
vault_gapand no pointer, and the call is never run again.
The vault therefore depends on your key service and your storage being available when it is enforced fail-closed.
Limits
- The pointer is a claim. OpenProdkt cannot confirm that the object exists, that the key is yours or that the record is what the pointer says.
- Erasure is yours to perform. Destroying the key in your key service makes the stored record unreadable. OpenProdkt neither holds nor destroys the key. Cloud key services delete after a waiting period (AWS KMS: 7 to 30 days), so it is not instant, and the encrypted record itself remains in storage.
- Existing events are not rewritten. Events recorded before the vault, and any personal data they hold, are unchanged.
- Plain digests can be guessed. The payload digest of a call with a short or predictable argument can be confirmed by guessing the argument. The vault does not change that.
- Pseudonymous principals are covered separately. While the vault is on, new audit events carry pseudonyms instead of recipient addresses and a digest instead of approval comments. See Pseudonymous Principals and Erasure.
- Not a compliance control. The vault is a technical control. Whether it meets an obligation in your situation is for you and your advisers to decide.