Backend data model

Design document, published from the repository at docs/backend/DATA_MODEL.md.

Schema: apps/api/prisma/schema.prisma. Migrations: apps/api/prisma/migrations.

The database uses three PostgreSQL schemas. Each holds a different class of data, so access can be granted, audited and backed up per class.

SchemaHoldsProtection
metaPublic metadata: data whose disclosure would not harm a user (public keys, statuses, commitments, public proofs, configuration, audit trail)Integrity via constraints and optimistic concurrency
vaultEncrypted key material: QuantLayer Quantum custody keysSealed inside the Rust module under a per-key KEK derived from QUANTLAYER_KEK; plaintext never reaches JavaScript or the database
sensitiveSensitive user informationAES-256-GCM field encryption (row-bound AAD), or only keyed hashes (blind indexes, token verifiers)

Never stored, anywhere

DataWhat happens instead
Private keys (users, issuers, platform)Users keep their own keys. Issuer and platform keys exist only sealed in vault.protected_keys.
Raw ZK witnesses (identity secrets, credential salts and attributes, Merkle paths submitted for proving)Sealed with ML-KEM-768 + AES-256-GCM when received. Only ciphertext reaches the queue (Redis), and it is deleted when the job finishes.
Credential claim values and holder secrets (disclosures, subject salt)Returned once to the issuer's caller. The issuer keeps a claim-free record.
API key secrets, session tokensOnly HMAC-SHA256 verifiers under a KEK-derived key.
Wallet addresses in clearBlind index for lookups, plus AES-256-GCM ciphertext.
Authorization evidence (signatures, proofs, presentations)Only the decision, reason, request digest and policy are logged.

Key hierarchy

QUANTLAYER_KEK is 32 bytes, supplied by the secret manager. Every other key is derived from it with HKDF-SHA256 (salt QUANTLAYER-KDF-V1) and a purpose label:

LabelUse
field/<purpose>/v<n>AES-256-GCM key per sensitive column family (identity-aggregate, wallet-account)
blind-index/v1HMAC key for equality lookups on encrypted values
token/v1HMAC key for API key and session verifiers
custody/<keyId>KEK handed to the Rust module to seal and unseal one custody key

Ciphertexts record a key version (key_version), and wrapped keys record kek_id, so a rotation can re-encrypt progressively.

Tables

meta: public metadata

TableContents
projects, api_keysDeveloper projects (owner is a blind index) and API key metadata (scopes, status, expiry). No secrets.
audit_eventsSecurity-relevant actions. Actors are opaque ids (key id, project id, blind index).
identitiesPublic projection: DID, controller, status, revision, verification methods (public keys).
issuers, status_lists, issued_credentialsIssuer registrations, signed status lists (public bitstrings), claim-free credential records.
credential_status_events, onchain_credential_statusCredential status index: every status change from the API or the chain, plus the current on-chain status.
merkle_trees, merkle_leaves, roots, nullifiersCommitment trees (leaves are hiding commitments), the root registry and spent nullifiers.
proof_requests, proof_jobsProof requests (public inputs, challenge) and job status tracking (status, attempts, public result or protocol error).
verification_policies, policy_minimums, authorization_nonces, revocations, authorization_decisionsThe authorization engine's state. Nonces are single-use by primary key.
pqc_key_ringsPublic key rings of custody keys (versions, algorithms, public keys, states).
chain_transactions, chain_cursors, chain_eventsTransaction monitoring and the indexer's cursor and decoded events.

vault: encrypted key material

TableContents
protected_keys(key_id, version) → blob, kek_id. The blob is sealed by quantlayer-pqc. Revoking a version deletes its blob.

sensitive: sensitive user information

TableContents
identity_aggregatesFull identity aggregate (account links, recovery guardians, status reason). AES-256-GCM, AAD identity_aggregates:<did>:<revision>.
account_linksActive account → DID, keyed by blind index. The primary key enforces "one identity per account".
wallet_accountsWallets that signed in: blind index and encrypted CAIP-10 account.
wallet_sessionsSession verifiers (HMAC), expiry and revocation.
api_key_secretsAPI key verifiers (HMAC). Deleted on revocation.

Operational notes

  • Privileges. Grant the application role access to all three schemas. Grant reporting and support roles meta only.
  • Backups. Back up vault and sensitive together with a record of QUANTLAYER_KEK_ID. QUANTLAYER_KEK itself is backed up only in the secret manager, never alongside the dump.
  • Redis. Redis holds only transient data: rate-limit counters, single-use challenges and queued jobs, which carry sealed witnesses. Do not enable persistence to shared storage.