Cryptography, evidence and verification

Signs and verifies 32-byte digests with Ed25519, taking a digest Buffer and PKCS8/SPKI DER keys and returning a base64 signature or a boolean. Verify never throws; length checks cover the 32 B hash and 64 B signature.

What it does

(null,…); verify never throws

Inputs

digest Buffer, PKCS8/SPKI DER

Outputs

base64 sig / bool

Depends on

node:crypto

Safeguards

length checks (32 B hash, 64 B sig)

Domain-separated SHA-256 with a domain registry, hashing domain and canonical string into a 32-byte Buffer. Per-class tags keep the hash domains apart.

What it does

SHA256(domain‖canonical)

Inputs

domain, canonical string

Outputs

32-byte Buffer

Safeguards

per-class tags

Authenticates key records with an HMAC-SHA256 seal over canonical JSON, with AAD binding. Returns a MAC hex or failures; sealed files fail closed and the records live in key files.

What it does

canonical JSON → HMAC-SHA256

Inputs

record, where

Outputs

MAC hex / failures

State

in key files

Safeguards

fail-closed sealed files; prod

Application field encryption using an HKDF subkey and AES-256-GCM, taking a value, purpose and aad. Returns a qfe1. string or {$qfe}; purpose and row AAD bind it, prod forces it required, and it needs a KEK.

What it does

HKDF subkey, AES-256-GCM

Inputs

value, purpose, aad

Outputs

qfe1. string / {$qfe}

Depends on

KEK

State

PG JSONB columns (callers)

Safeguards

purpose+row AAD; prod forces required

Encrypts private keys at rest with AES-256-GCM (12 B IV), a KEK fingerprint and HKDF sub-keys. A DER key with scope and AAD becomes a blob, protected by AAD binding and a fingerprint guard.

What it does

AES-GCM 12 B IV; HMAC fingerprint

Inputs

DER key, scope, AAD

Outputs

blob

State

keys files, subject_pseudonym_keys

Safeguards

AAD-bound blobs; fingerprint guard

Artifact key store that generates, persists, loads and reports status of keys, using env paths and the KEK to produce in-memory frozen records. Files are 0600 atomic with MAC, plaintext scan and zeroize; data lives in data/ or QODIQA_KEYS_PATH.

Revokes keys, including provider-side: sets local status to revoked, calls native revoke and records it, emitting audit events. A per-key mutex serialises it and it fails closed.

What it does

local status→revoked, native revoke, record

Inputs

/, opts

Outputs

audit events

Depends on

providers/base REVOCATION_METHODS

Safeguards

per-key mutex; fail-closed

Key manager facade, the single access point for keys: returns the cluster-aware active key or a native sentinel. It refuses a key retired cluster-wide.

What it does

cluster-aware active key; native sentinel

Outputs

key material / sentinel

Safeguards

retired-cluster-wide refusal

Scheduler for automatic rotation and follower reload: an hourly due-check under a Redis lock performs graceful rotation, with a 5-min reload. Lock plus fence protect it, it fails closed, and it emits rotations and metrics.

What it does

hourly due-check; Redis lock; graceful rotation; 5-min reload

Inputs

env

Outputs

rotations, metrics

Depends on

(Redis)

Safeguards

lock + fence; fail-closed

Expiry monitoring and tenant key health: ticks over key records and raises WARN or CRITICAL on key records, emitting metrics and events.

What it does

tick WARN/CRITICAL

Inputs

key records

Outputs

metrics/events

Parses key ids from a string with a regex. A strict regex and an overflow guard bound what it accepts.

Distributed rotation lock with fencing on Redis, using SET NX PX, a Lua release and a fence, and returning a lock handle. State is in Redis keys, and it fails closed on Redis loss.

What it does

SET NX PX + Lua release + fence

Inputs

Redis

Outputs

lock handle

Depends on

Redis (ioredis /client)

State

Redis keys

Safeguards

fail-closed on Redis loss

KMS provider factory and gate: validates configuration from QODIQA_KMS_*, builds and inits providers and wires the KEK. Emits providers and FATAL events, and refuses to start on bad settings.

What it does

validate, build, init, wire KEK

Inputs

QODIQA_KMS_*

Outputs

providers, FATAL events

Depends on

zod, providers

Safeguards

refuse start on bad

Local KEK provider that converts hex to a 32 B KEK from QODIQA_KEY_ENCRYPTION_KEY, held in env. It accepts only a strict 64-hex value.

What it does

hex→32 B

Inputs

QODIQA_KEY_ENCRYPTION_KEY

Outputs

KEK

State

env

Safeguards

strict 64-hex

Vault KV KEK provider using node-vault KV v2, reading its settings from VAULT_* and returning the KEK. Authenticates by AppRole or token with a TLS CA.

What it does

node-vault KV v2

Inputs

VAULT_*

Outputs

KEK

Depends on

node-vault

State

Vault

Safeguards

AppRole/token, TLS CA

Vault Transit native Ed25519 signing: sign, generate and revoke through node-vault. Takes a key name and a 32 B digest and returns a 64 B signature; keys are non-exportable and signatures are verified before release.

What it does

transit sign/gen/revoke

Inputs

key name, 32 B digest

Outputs

64 B sig

Depends on

node-vault

State

Vault

Safeguards

non-exportable keys; verify-before-release

AWS KMS KEK provider that wraps a data key using GenerateDataKey and Decrypt, with an EDK file, configured by AWS_KMS_*. The KEY-PL-17 guard and zeroize protect it.

What it does

GenerateDataKey/Decrypt, EDK file

Inputs

AWS_KMS_*

Outputs

KEK

Depends on

@aws

State

file

Safeguards

KEY-PL-17 guard, zeroize

Azure Key Vault KEK wrap, configured by AZURE_* and returning the KEK from a wrapped-key file. The KEY-PL-17 guard applies.

GCP KMS KEK wrap using encrypt/decrypt or RSA-OAEP, configured by GCP_KMS_* and returning the KEK from a wrapped-key file. The KEY-PL-17 guard applies.

What it does

encrypt/decrypt or RSA-OAEP

Inputs

GCP_KMS_*

Outputs

KEK

Depends on

@google-cloud/kms

State

wrapped-key file

Safeguards

KEY-PL-17 guard

PKCS#11 HSM Ed25519 signing using CKM_EDDSA to sign, generate and destroy keys, configured by HSM_PKCS11_* and returning a 64 B signature. Uses a PIN file and destroys the key on revoke.

What it does

CKM_EDDSA sign, gen, destroy

Inputs

HSM_PKCS11_*

Outputs

64 B sig

Depends on

pkcs11js

State

HSM + key index file

Safeguards

PIN file, destroy on revoke

Resilience wrappers around provider calls: deadline, retry with backoff, circuit breaker and health. They return a wrapped provider and fail fast when the circuit is open.

What it does

timeout, backoff, circuit

Inputs

provider calls

Outputs

wrapped provider

Safeguards

fail-fast when open

Wrapped-key provisioning guard: in prod it refuses implicit KEK generation when a wrapped key is absent and raises the error KMS_WRAPPED_KEY_MISSING. Covered by KEY-PL-17.

What it does

prod refuses implicit KEK generation

Inputs

env

Outputs

error KMS_WRAPPED_KEY_MISSING

Safeguards

KEY-PL-17

Admin endpoints for KEK rotation and MAC-keyring rotation, run under a lock; local providers are refused with 409. Takes an operator and returns a version, recording the operator in the audit event.

What it does

under lock; local refused 409

Inputs

operator

Outputs

version

State

KEK provider

Safeguards

lock, operator in audit event

Caveat local refused 409

Key admin lifecycle API for operators: takes an operator request and returns JSON. Access is protected by RBAC and step-up.

Standalone offline key tooling: one logged rotation, seal files and a public archive, driven from a CLI with the KEK and writing files. It refuses to run unless its preconditions hold.

What it does

one logged rotation / seal files / public archive

Inputs

CLI + KEK

Outputs

files

State

key files

Safeguards

refuses unless preconditions

Artifact signing, local and native: validates the envelope and key strictly, then signs and returns a frozen artifact. Depends on canonicalize and ed25519.

What it does

validate;; sign

Inputs

envelope, key

Outputs

frozen artifact

Depends on

canonicalize, ed25519

Safeguards

strict input validation

The POST /sign issuance route: takes an identity key, payload and request and returns the artifact JSON, writing an audit record. Identity scope, a TTL clamp and native verify-before-release protect it.

Signing identities for machine callers: SHA-256 key hash and validators, with create, update, issue, revoke and resolve operations returning records. Env-scoped, with the SIGN_ARTIFACT permission and expiry; kept in the control plane (PG) or a seed.

What it does

SHA-256 key hash; validators

Inputs

create/update/issue/revoke/resolve

Outputs

records

Depends on

collection

State

control plane (PG) / seed

Safeguards

env-scoped, permission SIGN_ARTIFACT, expiry

Cluster-wide key status timeline built by a forward-only merge, giving the effective timeline. Stored in control_plane_records in PG mode; status never goes backwards.

What it does

forward-only merge

Outputs

effective timeline

State

control_plane_records (PG mode)

Safeguards

never backwards

Server environment and permission matrix: maps QODIQA_ENVIRONMENT or NODE_ENV to an env string that the rest of the server uses to decide how it behaves.

Artifact verification, active on /verify and /ai/chat: checks an artifact and returns EXECUTE or BLOCK with a reason. It checks the canonical signature, tenant binding and lifecycle.

What it does

Active (/verify, /ai/chat)

Inputs

artifact

Outputs

EXECUTE/BLOCK + reason

Safeguards

canonical-sig, tenant binding, lifecycle

Public key set endpoints publish the non-revoked public keys over HTTP as JSON, reading from the key stores. The endpoints are rate limited.

What it does

publish non-revoked public keys

Inputs

HTTP

Outputs

JSON

Depends on

key stores

Safeguards

rate limited

Standalone JS verifier tool, not wired into the server (CLI): checks an artifact plus request against a key file or URL and prints a JSON verdict. It does not trust keys embedded in the artifact.

What it does

Not wired (CLI)

Inputs

artifact+request, key file/URL

Outputs

JSON verdict

Depends on

node crypto

Safeguards

no trust in embedded keys

Standalone Python verifier tool that takes the same inputs as the JS one and returns a verdict. It needs the cryptography or pynacl library.

What it does

needs cryptography or pynacl

Inputs

same

Outputs

verdict

Depends on

python libs

Public verification portal logic, store and API: runs 8 checks on an artifact and returns a report plus a PG row in portal_verifications. Checks are split into advisory and gating.

What it does

8 checks

Inputs

artifact

Outputs

report, PG row

Depends on

chain store

State

portal_verifications

Safeguards

advisory vs gating checks

Normative protocol spec and its generated sections: regenerates and diffs them from code constants and returns an exit code. A drift gate catches mismatches; state lives in docs.

What it does

regenerate/diff

Inputs

code constants

Outputs

exit code

State

docs

Safeguards

drift gate

Standalone vector generation tool: produces test vectors from production code, so they are derived from production. Depends on production modules and writes vector files.

What it does

produce vectors

Inputs

production code

Depends on

production modules

State

vector files

Safeguards

derived from production

Standalone independent JS verification of vector files: re-derives each vector on its own and returns an exit code. It does not import from src/.

What it does

independent re-derivation

Inputs

vector files

Outputs

exit code

Safeguards

no src/ import

Standalone independent Python verification of vector files: re-derives each vector on its own and returns an exit code. Depends on python.

What it does

re-derivation

Inputs

vector files

Outputs

exit code

Depends on

python

Standalone generator of webhook and artifact conformance vectors from the production signer, with a drift check. Outputs JSON vectors and uses a fixed check key.

What it does

generate from production signer; drift check

Outputs

JSON vectors

Depends on

production

State

files

Safeguards

fixed check key

Builds audit entries to schema and hash versions v1–v8 from fields, returning a frozen entry. Active on every append; uses a domain-separated hash and shape rules, with state in audit_chain.

What it does

Active (every append)

Inputs

fields

Outputs

frozen entry

Depends on

hashing

State

/ audit_chain

Safeguards

domain-sep hash; shape rules

Single-node durable audit chain with WAL, fsync and anchor, active at module load and on all enforcement paths. fsync ordering, O(1) replay and duplicate checks, and a fail-closed boot protect it; it writes .wal and .sum files.

What it does

Active (module load + all enforcement paths)

Inputs

fields

Outputs

entry;,.wal,.sum

Depends on

fs, pg mirror

State

(+.sum,.wal)

Safeguards

fsync ordering, replay/dup O(1), fail-closed boot

Distributed audit chain ordered in PG, using a head-row lock transaction to append entries. Tables audit_chain and audit_chain_head hold state, with UNIQUE prev_hash, artifact and nonce.

What it does

head-row lock tx

Inputs

fields

Outputs

entry

Depends on

PG pool

State

audit_chain, audit_chain_head

Safeguards

UNIQUE prev_hash/artifact/nonce

Group commit with mirror-writer back-pressure: batches appends and serialises the PG mirror, driven by env and exposing counters. A depth latch limits the backlog; state is in audit_chain.

What it does

batch append; serialized PG mirror

Inputs

env

Outputs

counters

Depends on

pg-audit-backend

State

audit_chain

Safeguards

depth latch

Checksum anchor written to both a file and PG: it writes the .sum file and audit_checksum_anchor from a count and returns a verdict. The two sit in separate failure domains.

What it does

write.sum + audit_checksum_anchor

Inputs

count

Outputs

verdict

Depends on

PG

State

.sum, PG table

Safeguards

separate failure domain

Live chain verifier, active by default (ON): reads env and emits events and metrics while keeping its own state in a file or PG. It never repairs the chain.

What it does

Active (default ON)

Inputs

env

Outputs

events/metrics, state

Depends on

audit-log, pg

State

verifier state (file/PG)

Safeguards

never repairs

Startup gates for mirror recovery, consistency and continuity, comparing file and PG. The result is a boot refusal or a recovery, and the gate fails closed.

PG lag and count monitors: count rows in PG and raise WARN or CRITICAL from PG. They do not auto-repair.

What it does

counts

Inputs

PG

Outputs

WARN/CRITICAL

Depends on

PG

Safeguards

no auto-repair

Single-instance guard: reads env signals and refuses to start, reporting a boot error, so that two instances cannot create forked chains.

What it does

refuse

Inputs

env signals

Outputs

boot error

Safeguards

prevents forked chains

Optional lifecycle entries with a reconciler and COMMIT: writes INTENT, STREAM_OPENED, DECISION and COMMIT entries for a request lifecycle into the audit chain. It fails closed before the provider call.

What it does

INTENT/STREAM_OPENED/DECISION/COMMIT

Inputs

request lifecycle

Outputs

entries

Depends on

audit-log, recovery queue

State

audit chain

Safeguards

fail-closed before provider call

Signed checkpoints taken from a chain position, signed with Ed25519 and stored in audit_signed_checkpoints, plus a transparency leaf. Kept in PG and a sidecar; boot verification fails closed.

Witness co-signing of a checkpoint, with local or exec witnesses, refusing rollback, equivocation and fork. Returns a cosignature; independence is flagged none-local-witness when no outside witness exists.

What it does

rollback/equivocation/fork refusal; local or exec

Inputs

checkpoint

Outputs

cosignature

Depends on

operator exec

State

witness log

Safeguards

independence flagged none-local-witness

Anchor export and verification: writes a JSONL export and re-verifies the chain against the anchors. The file path is QODIQA_ANCHOR_EXPORT_PATH; a torn tail is refused.

What it does

JSONL export; re-verify chain

Inputs

env

Outputs

export file

Depends on

witness

State

QODIQA_ANCHOR_EXPORT_PATH file

Safeguards

torn-tail refuse

External anchors via git, OTS or RFC3161: queues and publishes through git or operator exec, writing external_anchors rows and git commits. qodiqa itself makes no network call, and retries are capped.

What it does

queue + publish via git or operator exec

Inputs

env

Outputs

external_anchors rows; git commits

Depends on

git, operator exec

State

PG external_anchors

Safeguards

no network by qodiqa; capped retries

Proof assembler: gathers entries, chain path, leaf, proof, receipt, anchors and keys for a tenant into one qodiqa-proof/1 JSON. Another tenant gets a tenant-isolated 404.

What it does

gather entries, chain path, leaf, proof, receipt, anchors, keys

Inputs

tenant

Outputs

qodiqa-proof/1 JSON

Depends on

audit-log, transparency, anchors

Safeguards

tenant-isolated 404

Platform audit event store: ingests, searches and correlates logger events in the PG table platform_audit_events. Reads go through the reporting role.

What it does

ingest/search/correlate

Inputs

logger events

Outputs

PG platform_audit_events

Depends on

PG

State

PG

Safeguards

reads via reporting role

Audit routes: HTTP endpoints for integrity, verifier, timeline and retention that return JSON. They require the READ_AUDIT permission and step-up.

What it does

integrity/verifier/timeline/retention endpoints

Inputs

HTTP

Outputs

JSON

Depends on

audit-log

Safeguards

READ_AUDIT, step-up

Merkle tree per RFC 6962: computes root, inclusion and consistency proofs over an array of entry hash hex values using node crypto. Leaf and node prefixes are 0x00 and 0x01.

What it does

root, inclusion, consistency

Inputs

entry hash hex array

Outputs

proofs

Depends on

node crypto

Safeguards

prefixes 0x00/0x01

Block-checkpointed Merkle: computes root and path in O(n/block) from block hashes, giving the same output as the plain tree. Checkpoints in PG are derived data, and a mismatch is caught by the signed root.

What it does

O(n/block) root/path

Inputs

block hashes

Outputs

same output

Depends on

PG transparency_merkle_checkpoints

State

PG

Safeguards

derived data; mismatch caught by signed root

Entry registration and root generation: hashes, signs and chains a payload, then produces a root, writing PG rows to transparency_log_entries, transparency_roots and head tables. A head lock and signature protect it.

What it does

hash, sign, chain; root

Inputs

payload

Outputs

PG rows

State

transparency_log_entries, transparency_roots, head tables

Safeguards

head lock, signature

Root scheduler: fires on time or count triggers, driven by env, to produce signed roots through the registrar. State is in PG and a single-flight guard prevents overlap.

What it does

time/count triggers

Inputs

env

Outputs

signed roots

Depends on

registrar

State

PG

Safeguards

single-flight guard

Software transparency signer: signs a digest with Ed25519 through the key store, returning a signature. The key lives in a key file and signing is purpose-separated.

What it does

Ed25519 via key store

Inputs

digest

Outputs

sig

State

key file

Safeguards

purpose-separated

Transparency signer for HSM: currently only a stub that throws when it is called, so it does not yet provide HSM signing and cannot be relied on for signatures.

What it does

stub, throws

Caveat stub, throws

Receipts: signs a decision and leaf as JCS-P1 and stores them with a TTL, returning a receipt. Held in Redis or memory with bounded retention, and depends on the transparency signer.

What it does

sign JCS-P1; store TTL

Inputs

decision, leaf

Outputs

receipt

Depends on

transparency signer, Redis/memory

State

Redis or memory

Safeguards

bounded retention

Enforcement bridge and journal health: registers a leaf for a decision using a queue, journal and buffer, returning the leaf or a 503 when unavailable. It refuses EXECUTE when the window exceeds the bound.

What it does

leaf registration with queue/journal/buffer

Inputs

decision

Outputs

leaf; 503 when unavailable

Depends on

registrar, recovery manager

State

PG, journal dir, memory

Safeguards

refuse EXECUTE when window > bound

Transparency API: takes HTTP requests and returns JSON proofs, with state in PG. Reads are public and writes are admin only.

Optional gap scanner and gap framework, conditional on TRANSPARENCY_SCANNER_ENABLED=true and off by default. Reads PG and emits gap events and alerts, using PG advisory locks; root authenticity follows ST23.

What it does

Conditional (TRANSPARENCY_SCANNER_ENABLED=true; default off)

Inputs

PG

Outputs

gap events/alerts

Depends on

PG advisory locks

State

gap_scanner_state

Safeguards

root authenticity ST23

Caveat default off

Evidence record hash with an 11-step verify, active: takes an audit entry and key info and returns a record or a verdict. Hashing is domain-separated with schema versions; records live in evidence_chain_records.

What it does

Active

Inputs

audit entry, key info

Outputs

record / verdict

Depends on

hashing

State

evidence_chain_records

Safeguards

domain-sep, schema versions

Evidence chain store: locked insert, verify and range verify of audit entries into PG rows. The table is INSERT-only and a head lock serialises writes.

What it does

locked insert, verify, range verify

Inputs

audit entry

Outputs

rows

Depends on

PG

State

PG

Safeguards

INSERT-only, head lock

Evidence package generation, sealing and verification, active at /evidence/package/*. Produces package JSON on demand without stored state; the seal key is resolved from the store.

What it does

Active /evidence/package/*

Outputs

package JSON

Depends on

audit-log

State

none (on demand)

Safeguards

seal key resolved from store

Evidence bundle of a package plus an inclusion proof, active at /evidence/package/:id/bundle. Returns bundle JSON; an envelope seal binds the proof to the package.

What it does

Active /evidence/package/:id/bundle

Outputs

bundle JSON

Safeguards

envelope seal binds proof to package

Evidence base after a prune: verifies the checkpoint binding from the PG prune record and returns a base or an error. Kept in audit_chain_prunes and fail-closed.

What it does

verify checkpoint binding

Inputs

PG prune record

Outputs

base/err

Depends on

checkpoint verify

State

audit_chain_prunes

Safeguards

fail-closed

Evidence APIs, active: take HTTP requests and return JSON, PDF or CSV via the generator, with state in PG. RBAC and step-up apply.

What it does

Active

Inputs

HTTP

Outputs

JSON/PDF/CSV

Depends on

generator

State

PG

Safeguards

RBAC, step-up

Data-subject-request (DSR) lifecycle orchestration as a state machine over admin requests, producing requests and events in dsr_requests and dsr_request_events. A transition table and attestation protect it.

What it does

state machine

Inputs

admin requests

Outputs

requests/events

Depends on

PG

State

dsr_requests, dsr_request_events

Safeguards

transition table, attestation

Erasure with a pseudonym and a definer function, active: turns a request into tombstones and key destruction. Uses owner-run definer functions with per-subject key deletion, and depends on the consent store.

What it does

Active

Inputs

request

Outputs

tombstones, key destroy

Depends on

PG definer funcs, consent store

State

PG

Safeguards

owner-run definer, per-subject key deletion

Rectification, restriction and portability, active: turns a request into records and an export stored in dsr_rectifications and dsr_exports. The export carries a checksum; depends on ConsentStore.

What it does

Active

Inputs

request

Outputs

records, export

Depends on

ConsentStore

State

dsr_rectifications, dsr_exports

Safeguards

export checksum

Control registry, collection, validation and scoring, active at /compliance: takes a period and framework and returns scores, kept in compliance_reports and child tables. Reads PG through the reporting role.

What it does

Active /compliance

Inputs

period, framework

Outputs

scores

Depends on

PG (reporting role)

State

compliance_reports + children

Report signing and verification with Ed25519 over a domain hash: wraps report JSON in an envelope, stored in compliance_report_signatures. Native sign is supported.

What it does

Ed25519 over domain hash

Inputs

report JSON

Outputs

envelope

State

compliance_report_signatures

Safeguards

native sign supported

Report export in JSON, HTML or PDF (via pdfkit): takes a report and turns it into files, one per chosen format, using the pdfkit library for the PDF output.

What it does

JSON/HTML/PDF (pdfkit)

Inputs

report

Outputs

files

Depends on

pdfkit

AI disclosure: builds a header plus a body object from tenant, provider and model, using the tenant semantic registry and tenant config.

What it does

header + body object

Inputs

tenant, provider, model

Outputs

disclosure

Depends on

tenant semantic registry

State

tenant config

Persistence recovery with queue, worker, journal and DLQ, active: failed writes are retried from persistence_recovery_queue and the journal dir. A durable fallback chain protects them; depends on PG.

What it does

Active

Inputs

failed writes

Outputs

retried writes

Depends on

PG

State

persistence_recovery_queue, journal dir

Safeguards

durable fallback chain

Demo signer service that calls the gateway /sign with a visitor prompt and returns an artifact header. It applies a quota and a strict body.

What it does

calls gateway /sign

Inputs

visitor prompt

Outputs

artifact header

Depends on

gateway

Safeguards

quota, strict body