Data inventory#

Requirement: PRV-001 (with PRV-002, PRV-004, PRV-005, DB-008). Derived from migrations/*.sql and the code that reads and cleans each table. It covers personal data, secrets and identifiers; purely technical tables are omitted.

Protection column legend

• plain — stored as plaintext in PostgreSQL. ProudAuth does not encrypt the database as a whole; use storage/disk encryption and access control.
• AEAD — AES-256-GCM under a key derived from the root keys (keys.md), bound to the row by associated data.
• SHA-256 — unkeyed digest of a high-entropy secret (not reversible in practice).
• HMAC — keyed verifier of a low-entropy code; useless without the root key.
• Argon2id — password verifier, optionally peppered.
• digest (guessable) — unkeyed SHA-256 of a low-entropy value such as an email address; anyone with database access can confirm a guessed value.

Retention column describes what the code does today. "Kept" means no automatic deletion exists.

Ownership and export. The operator running the deployment is responsible for all of it; within a realm, these roles decide over each section's data and these paths export it (exit-and-export.md). Fields that are secrets (verifiers, seeds, keys, token digests) are never exported, whichever section they are in (What cannot be exported).

Accounts and credentials#

Sessions, tokens and authentication#

Organizations, authorization, support#

Evidence, delivery and jobs#

SAML#

Migration 0060 (saml.md). Persistent NameIDs are rows of pairwise_subjects (sector saml:<application id>), deleted with the account like other pairwise subjects.

Assertions themselves are not stored. The identity a SAML connection asserts is stored like any federated identity (external_identities).

Directory integration#

Migration 0065 (directory.md, outbound-provisioning.md).

Security events, cross-organization access and other evidence#

Migrations 0057–0059 and 0080–0083 (shared-signals.md, federation-transfer.md, partner-access.md, container-registry.md, authentication-flows.md).

Registry tokens and reconstructed entitlement histories (ADV-011) are not stored; issuances, denials and reconstructions are audit events.

Protocol, machine-identity and authorization extensions#

Migrations 0047–0056 (workload-federation.md, dynamic-client-registration.md, relationship-authorization.md, elevation-and-access-reviews.md, mutual-tls.md).

None of these tables is in the realm data export, except the is_agent flag of service principals, the owners of policies and hooks, the hotp flag of the credential summary and the protocol options of clients (in the configuration document).

Tables without personal data#

These tables hold configuration, protocol state or bookkeeping and no personal data: realms, realm_custom_domains, api_resources, scopes, roles, role_permissions, policies, policy_versions, project_grants, client_origins, client_redirect_uris, client_resource_grants, resource_server_clients, organization_domains, organization_aliases, notification_templates, client_assertion_jtis (client assertion IDs until they expire), credential_expiry_alerts (which machine credential was reported), hook_invocations (outcome, latency and error category per hook call; deleted after 7 days), event_stream_horizon, audit_archive_state and system_state. TestDataInventoryCoversTables fails when a migration adds a table that is neither in a section above nor in this list.

Data sent outside the deployment#

Only to destinations the operator or an administrator configures:

HTTP calls made while serving a request (hooks, upstream identity providers, challenge providers) also carry a traceparent header: the request's trace ID (random, or continued from the caller's own traceparent) and span ID, no request data (API-012).

Data residency#

PRV-003. ProudAuth does not choose where data is stored; it lets the operator keep connectors within chosen destinations and reports the deployment's label:

With privacy.residency.allowed_destinations set (host names or .domain suffixes), a destination outside the list is refused when a webhook, hook, organization mail server, upstream identity provider or workload trust key set is saved (422 validation_failed on the field, like other egress-policy violations; PRV-003, TestResidencyAtSave) and at every connection, including DNS changes later (configuration.md, internal/egress/residency_test.go). privacy.residency.region is a label shown by /status with destinations_restricted (monitoring.md); ProudAuth cannot observe or enforce where the database, backups or logs are located.

Account deletion#

DELETE /users/{user} (administrator), the scheduled completion of a self-service deletion request (POST /me/deletion-request, after privacy.deletion_grace_period, default 14 days; the request sends the deletion_scheduled notice, and until the deletion is due the owner can cancel it by signing in, which offers nothing but the cancel_deletion step: headless-authentication.md, USR-012), the merged-away account of an executed account merge (POST /account-merges/{id}/execute), and the lifecycle rules for expired unverified registrations and unused guest accounts (below):

• revokes sessions, grants, refresh families, opaque tokens and support grants;
• deletes identifiers, credentials, recovery codes, passkeys, external identities, password history, remembered devices, pairwise subject mappings and notification preferences;
• marks memberships removed, clears the metadata of every membership the account had (USR-009), and revokes the user's automation credentials;
• suppresses the account's queued notifications and erases the payload and recipient of every notification job about it, at once rather than at delivery.payload_retention (migration 0048). Every message about an account records it (notification_jobs.user_id): login codes, password-reset, verification and magic-link messages, security and support-access notices, group notices, and any message sent to one of the account's addresses. Messages queued before this was recorded are found through their user or challenge reference;
• deletes its certificate bindings (PROV-016) and the relationship tuples that name it as subject (AZ-021); revokes the pending and accepted shares it made or received (removing the tuple of an accepted share it made, as a revocation does) and clears the message of every share naming it (AZ-027); revokes its elevation eligibilities, cancels its pending elevation requests and ends an active elevation, whose role assignment then expires at once and is removed by lifecycle.expiry (AZ-024; TestAccountDeletionCoverage);
• ends pending work about the account: scheduled assisted recoveries (pending or approved) and pending account merges in which it is either account become cancelled, and a pending registration approval becomes expired;
• clears profile, metadata and required actions and sets the state deleted;
• writes digest-only tombstones for each identifier and for the user ID;
• clears the source-supplied details (metadata, source_subject_id, the actor's display) of imported historical audit records whose subject is the account, unless an active legal hold covers them (MIG-016); records imported later for the deleted account are stored without those details unless a legal hold covers them (a hold on their organization, a realm-wide hold or a hold on the account), in which case they keep them (PRV-004);
• records audit user.deleted and outbox user.deleted.

Owned objects come first (USR-020, APP-001, APP-014, TestDeletionNeedsOwnershipTransfer). DELETE /users/{user} and POST /me/deletion-request are refused with 409 last_owner while the account is the only active owner of an organization (extension organizations on the administrator route) or is the recorded owner of live objects, listed in the extension owned: projects (not archived), clients (not decommissioned), service_principals (not deleted), resources and identity_providers (active). Move them first: one project with POST /projects/{project}/ownership-transfer (owner_user_id of an active account and/or owner_organization_id, and a reason; optional If-Match; audited project.ownership_transferred), or everything at once with POST /users/{user}/ownership-transfer {"to_user_id": "usr_..."}, which moves every object the account owns, in any state, to another account and answers {"transferred": {"project": 2, "client": 1}} (kinds with nothing to move are left out). The transfer needs realm.projects.write, realm.clients.write, realm.service_principals.write, realm.resources.write, realm.identity_providers.write, realm.policies.write, realm.hooks.write and realm.webhooks.write together, and the new owner must be an account of the realm in state active or recovery_restricted (422 on owner_user_id otherwise); each move is audited as <kind>.ownership_transferred (category configuration, metadata previous_owner_user_id and owner_user_id) and increments the object's version, so an ETag read before the transfer no longer matches If-Match. The transfer also moves the authorization policies, pre-action hooks and webhook subscriptions the account owns (authorization_policy, hook and webhook in transferred; a plugin-managed hook or subscription keeps its plugin, only its accountable owner changes; TestOwnershipTransferCoversExtensions). Such objects do not block the deletion; one left behind is listed as owner_departed by the ownership report (machine-clients.md), and POST /hooks/{id}/ownership-transfer, POST /webhooks/{id}/ownership-transfer or POST /policies/{policy}/ownership-transfer ({"owner_user_id"}, optional If-Match; realm.hooks.write, realm.webhooks.write or realm.policies.write) gives it a new owner, also when it has none. The check runs when the deletion is requested, and again when a scheduled self-service deletion falls due: while the account is then the only active owner of an organization that is not being deleted, or owns live objects, the deletion is postponed by 24 hours and recorded as user.deletion.postponed (reason OWNERSHIP_NOT_TRANSFERRED, metadata organizations and owned with the IDs per kind), every day until the ownership is moved. A lifecycle deletion and the merged-away account of a merge are not checked again.

It does not delete: the users row and ID, session rows (with IP and user agent) and grants (until privacy.session_retention after they were revoked), consents and invitations addressed to the user (until privacy.history_retention once revoked or ended), terms acceptances, registration approvals, assisted-recovery requests, merge records and subject aliases, suppression entries for the user's addresses, audit events (until audit retention, or longer under a legal hold) and their archived copies, the rest of imported historical audit records (type, time, outcome, content hash, until retention), webhook delivery payloads (until privacy.history_retention), job records (export payloads until privacy.export_retention), or data in backups (PRV-005). Restore reconciliation re-applies deletions to restored backups, including the clearing of imported audit records (backup-restore.md).

Deletion propagation report#

PRV-005, internal/httpapi/privacy.go, TestDeletionPropagationStatus. GET /api/v1/realms/{realm}/users/{user}/deletion-status (realm.users.read) reports, for a deleted account, where its data still exists. It is derived from what is stored at the time of the request, not from a separate log; an account that is not deleted gets 409 conflict (with its state), an unknown one 404.

{"user_id": "usr_...", "deleted_at": "2026-10-11T08:00:00Z",
 "stages": [{"stage": "connectors", "state": "pending", "count": 2,
             "details": "user.deleted event published to webhook subscribers; ..."}, ...]}

Each stage has stage, state (done, pending, retained or unknown), optional count and until, and details:

Organization deletion#

TEN-011, TEN-024, TestOrganizationDeletionWorkflow. GET /organizations/{org}/deletion-preview (org.delete) counts what a deletion affects: active_members, pending_invitations, active_grants, owned_projects, owned_clients (active clients of the organization's projects and service principals), provisioning_connectors, active_support_grants, role_assignments, groups, verified_domains, owned_service_principals, active_automation_credentials, webhook_subscriptions, identity_providers, mail_server_configured, consent_preauthorizations, export_results, pending_jobs, retained_audit_events and active_legal_holds (the holds that cover the organization's evidence: holds on the organization, realm-wide holds, and subject holds on anyone with a membership in it), and lists in retained what is kept: audit events (until audit retention, longer under a legal hold), the organization record as a deleted tombstone, memberships and invitations as removed or revoked records, and members' federated identity links (with the provider disabled).

DELETE /organizations/{org} (org.delete, recent authentication) answers 202 {"state": "deleting", "job_id"} and, in that transaction, revokes the organization's sessions, grants, pending invitations and automation credentials; disables its provisioning connectors, service principals, webhook subscriptions and identity providers; suspends its active owned projects and the active clients of those projects and of its service principals, and revokes those clients' refresh tokens; revokes its consent pre-authorizations; erases the results of all its jobs and cancels its other queued jobs (running ones are asked to stop); and publishes organization.deleted. A job of the organization that is still running when the deletion starts stores no result: it ends cancelled with last_error "organization deleted while the job ran" (the deletion job itself excepted). The worker then finishes at its next run (there is no grace period, and it cannot be cancelled): it deletes role assignments, group memberships, aliases, the organization's notification settings (sender and mail server with its password) and webhook subscriptions (with their deliveries), erases identity providers' client secrets, revokes the owned clients' credentials and erases their secret digests and public keys (key IDs and display prefixes stay), marks memberships removed, domains removed and join requests withdrawn, and turns the organization into a tombstone (organization.deletion.completed). Audit events are not changed.

The deletion job runs only while its requester still holds org.delete (evaluated as if the organization were still active). Otherwise it dead-letters ("permanent job failure: the requester no longer holds org.delete") and the organization stays deleting until someone authorized sends DELETE /organizations/{org} again, which queues a new job (202); while a deletion job is queued or running, another DELETE is 409 (TestOrganizationDeletionRequesterRechecked). Relationship tuples and sharing records of the organization are not removed (relationship-authorization.md).

Account lifecycle jobs#

USR-015, internal/identity/lifecycle.go, TestUserLifecycleJobs. The worker task lifecycle.users runs every 10 minutes and applies these rules to each realm (including suspended realms):

• Each run handles at most 100 accounts per rule and realm, oldest first. Every account is re-checked against the rule and changed in its own transaction, so a sign-in or an administrator change that happened meanwhile wins. Changes are recorded with the actor system. A realm whose run fails does not stop the others; the task reports the first error after every realm ran.
• GET /api/v1/realms/{realm}/lifecycle/preview (realm.users.read) is the dry run: {"dry_run": true, "batch_size": 100, "rules": [{"name", "action", "due", "sample_user_ids"}]} with the number of accounts each rule would select now and up to 20 of their IDs. Nothing is changed.
• Administrators schedule a suspension with PUT /api/v1/realms/{realm}/users/{user}/scheduled-deactivation {"at": "RFC 3339", "reason": "..."} (realm.users.suspend; at must be in the future; refused for accounts being deleted) and cancel it with DELETE on the same path. Both are audited (user.deactivation_scheduled with deactivate_at, user.deactivation_cancelled), and administrator user views show deactivate_at.
• Protected accounts are never treated as dormant, but a scheduled deactivation applies to any active account.

Identity read evidence#

USR-018, AUD-015, TestIdentityReadEvidence. Reads of account records are not logged by default. With realm policy data_access.log_identity_reads: true:

• GET /users/{user} records user.read with the account as subject;
• GET /users records user.search with result_count and filtered (whether a q search term was given);

both in the audit category data_access, with the calling administrator or support operator as actor and masked telling whether the caller received the masked view (callers with support.users.read but not realm.users.read). The event holds no profile or contact data, and it is written before the data is returned: if it cannot be written, the request fails. Query the evidence with GET /audit-events?category=data_access.

Audit retention and legal holds#

AUD-007, AUD-009, internal/audit/query.go (PruneExpired), internal/audit/holds.go, migration 0044, TestAuditRetentionCategoriesAndHolds. The worker task retention.cleanup (every 5 minutes, up to 100 batches per run) deletes sealed audit events whose retention has passed:

• the deployment's retention of an event is privacy.audit_retention_by_category[<category>] when its category is listed, otherwise privacy.audit_retention (400 days);
• a realm can keep its evidence longer with the realm policy audit.retention_days, and an organization with its policy audit_retention_days (PATCH /organizations/{org}); both are 0 (not set) or 30–3650 days (422 otherwise). An event is pruned only when every retention that applies to it (deployment or category, realm, organization) has passed, so a scope can only extend retention, never shorten it. All are measured from occurred_at;
• category emergency is never pruned, and neither is an event matched by an active legal hold;
• events are removed one by one, so a batch can lose its events over several passes as different retentions expire. The first pass over a batch is recorded in audit_prunes and later ones in audit_prune_log, both append-only, and the chain still verifies (incidents.md);
• with privacy.audit_archive_dir set, only batches the archive already holds are pruned, so nothing is pruned before the first archive run and a stopped archive also stops retention.

Every removal goes through the database function proudauth_audit_prune (owner-run, SECURITY DEFINER). It never removes unsealed events, category emergency or events under an active legal hold, refuses batches not yet archived once the archive has forked after a restore, and writes the audit_prunes / audit_prune_log rows itself. The guard trigger accepts a delete only from the table owner with the retention flag set, which only the function does. With separate database roles (storage.runtime_role) the runtime role has no DELETE on audit_events, audit_batches, audit_prunes or audit_prune_log, only EXECUTE on the function, so the service's credentials cannot delete held, emergency or unsealed evidence. The function does not check age, though: the retention periods and the archive progress are applied by the worker, so a stolen runtime credential can still prune other sealed events early, recorded like retention (the archive keeps the copies). In a single-role deployment the runtime role is the owner and can delete audit rows directly; separate the roles where that matters (installation.md).

The same task deletes imported historical audit records (imported_audit_events, MIG-016, up to 1000 per run) once privacy.audit_retention_by_category.imported, or else privacy.audit_retention, has passed since they were imported (their occurred_at can be years older). A longer realm (audit.retention_days) or organization (audit_retention_days) retention keeps them longer too, also counted from the import. Legal holds apply to them by realm, organization and local subject_id; a hold on a person does not match records where that person is only the source-stated actor.

A legal hold keeps evidence regardless of retention. POST /api/v1/realms/{realm}/audit-legal-holds (realm.audit.legal_hold, held by the built-in realm-admin role; an MFA session) takes a reason of 5–500 characters and optionally organization_id and subject_id:

Neither ID is checked against existing organizations or accounts, and events without a realm (operator events written by identity-cli) cannot be held. GET .../audit-legal-holds lists the realm's holds (id, organization_id, subject_id, reason, created_by_id, created_at, released_by_id, released_at), active ones first, at most 500. POST .../audit-legal-holds/{id}/release ends a hold (404 if it is unknown or already released); retention applies to its events again at the next run. Placing and releasing are audited as audit.legal_hold.placed (with the reason) and audit.legal_hold.released, in category audit; a release also raises the configuration_change security signal and a security.alert event. Held evidence is kept in the database only as long as the hold, so also export it (POST /audit-exports) if it must outlive a database restore.

Audit corrections#

AUD-007. Audit events are never edited, also not by administrators. A mistaken or incomplete record is corrected by a new event linked to it:

POST /api/v1/realms/{realm}/audit-events/evt_.../corrections
{"reason": "INC-77: the ticket reference was wrong", "correction": {"ticket": "INC-77"}}

• Needs realm.audit.correct (privileged; held by the built-in realm-admin role through realm.*) and, for users, an MFA session. reason is 5–1000 characters; correction is an optional object of at most 8 KiB as JSON, redacted like other audit metadata. Only events of the caller's realm can be corrected (404 otherwise, also for operator events without a realm); a correction can itself be corrected.
• The answer is 201 {"event_id", "corrects_event_id"}. The correction is the audit event audit.correction (category configuration, the caller as actor, the original's organization, target audit_event with the original's ID; metadata corrects_event_id, corrects_type, reason, correction), sealed into the chain like any other. The original never changes.
• Find the corrections of an event with GET /audit-events?type=audit.correction&target_id=<event id>. A retried request without an Idempotency-Key records a second correction.
• A correction follows its own retention, not the original's.

Known data-minimization gaps#

• auth_transactions holds the full client IP address and the user agent while a transaction is pending (per-IP budgets need the address), and sessions keeps user agents until the session row is deleted (PRV-002).
• The per-network verification budget counts by full address, not by /24 or /48.
• Imported audit metadata is redacted only by member name (secret-looking keys and bearer-token or JWT-shaped values); other personal data the source supplied, such as IP addresses, is stored as given.
• Active consents, pending invitations, consent pre-authorizations, registration approvals, assisted-recovery requests, account-merge records, notification suppressions, terms acceptances, legal holds and audit archive files have no retention job.
• A failing step of retention.cleanup no longer stops the others: every step runs, and the run reports the failed ones together (<step>: <error>); the failed step's data stays until the cause is fixed. Watch proudauth_worker_runs_total{task="retention.cleanup",outcome="error"} and the worker task failed log line.
• Account deletion does not touch access review items about the account; the client registration records keep the registrant's IP address, and none of these tables has a retention job (Protocol, machine-identity and authorization extensions).
• Account deletion does not touch lifecycle workflow tables: runs, attempts and approvals about a deleted account (or decided by it) keep its user ID until privacy.history_retention purges the finished runs; a run still in progress keeps it longer. Workflows and revisions (with approver IDs in their definitions) are kept until the workflow is deleted.
• Plugins and their versions (signed packages, uploader and reviewer IDs, review notes) have no retention job and no deletion API.
• Migration adapters write the capability report, mapping template and, with --write-documents, the converted import documents (with password verifiers and TOTP seeds) to files on the operator's machine (mode 0600); ProudAuth does not track or delete them (migration-adapters.md).
• A deleted account's directory link keeps the entry's immutable ID (with source state deleted) until the connector is deleted, so the directory entry is not imported again (Directory integration).
• Organization relationships, flow revisions and federation transfer summaries are kept indefinitely (Security events, cross-organization access and other evidence).