Skip to main content

Pseudonymous Principals and Erasure

While the evidence vault is on, new audit events do not carry email addresses or free-text comments. They carry an opaque pseudonym for the person instead. The link from the pseudonym to the person is stored in one place, so a super_admin can remove it. This page describes what changes, and the steps to unlink a person.

None of this is legal advice. It describes technical controls and their limits. Whether it meets an obligation in your situation is for you and your advisers to decide.

What changes in new events​

This applies only to events recorded after the vault was turned on, and only while it stays on. Events recorded before are never rewritten.

Event dataWithout the vaultWith the vault on
Approval recipients, in the audit event of an approval-required decision and in approval.pendingThe email addressesrecipientPseudonyms: one pseudonym per recipient who is a member of your organization, and recipientCount. An address that is not a member is counted and not recorded
An approver's comment, in the approve, reject and revoke eventsThe comment textcommentDigest (sha256: of the text) and commentLength. The text stays only on the approval itself

Unchanged: user ids in events, the approval notification and its email, webhook bodies, and what the approval API returns. Those need the real values to do their job.

A pseudonym is an opaque id (pnm_ and 32 hex characters), one for each user of each organization. It is created the first time an event needs it.

Find or resolve a pseudonym​

All the routes on this page need a signed-in super_admin and the evidence.vault entitlement. API keys are refused.

RouteReturns
GET /v1/principals?user_id=...The pseudonym of that member of your organization. 404 if there is none yet, or it was erased
GET /v1/principals/{pseudonym}{ version, pseudonym, user_id, created_at, erased_at }. user_id is null once erased. Another organization's or an unknown pseudonym is 404

Unlinking a person​

Do the steps in this order. After step 5 the references can no longer be listed.

  1. Deactivate the member. An active member cannot be erased (409 principal_active).
  2. Find the pseudonym with GET /v1/principals?user_id=....
  3. List the vault references: GET /v1/principals/{pseudonym}/vault-refs. It returns the claimed pointers of decisions and outcomes whose authenticated principal is that user, newest first (limit up to 200 and offset), and key_refs, the distinct key references over all of them, not only the page. Calls made with an API key are not linked to a person, so they never appear here. If your enforcement points mostly use API keys, this list can be short or empty; use your own records of which key protects which principal group.
  4. Destroy the keys in your key service. OpenProdkt never holds a key and never calls your key service, so this step is yours. Cloud key services delete after a waiting period (AWS KMS: 7 to 30 days), and a key that is disabled or pending deletion already cannot decrypt. Until deletion completes, the records are still recoverable by anyone who can re-enable the key.
  5. Erase the pseudonym: POST /v1/principals/{pseudonym}/erase.
  6. Check: GET /v1/principals/{pseudonym} now shows user_id: null and erased_at, and the audit trail has a principal.erased event.

What erase does​

In one transaction it:

  • removes the link from the pseudonym to the person. The row stays as a record that the pseudonym was erased,
  • clears the comment text of approvals that person reviewed in your organization,
  • records principal.erased with the pseudonym, the time and the super_admin who did it.

Repeating it changes nothing and answers 200. A member who is reactivated later gets a new pseudonym.

What erase does not do​

  • It does not destroy a key. OpenProdkt cannot, and its record that you erased a pseudonym is not evidence that your keys are gone.
  • It does not delete the account. The user, their role and their API keys are unchanged, and so are user ids that appear in existing events. A user id is neither a name nor an address, but it identifies the account while the account exists.
  • It does not rewrite events. Events from before the vault was on keep the data they hold, and so do their exports. Events recorded afterwards keep the pseudonym, which no longer leads to a person.
  • It does not delete the encrypted records. They stay in your storage, readable or not depending on your keys.
  • It does not remove the comment digests. The audit events keep commentDigest and commentLength. A digest of a short or predictable comment, such as approved, can be confirmed by guessing the text.

Limits​

  • The vault and the pseudonyms are technical controls, not a statement that an erasure, retention or privacy obligation is met.
  • Pseudonyms cover approval recipients and comments. Other places where a person's data may appear, such as your own webhook receivers, mail logs or Console sessions, are outside this feature.
  • Only a deactivated member can be erased.