HTTP API and request lifecycle

Builds the Express app, registering the global middleware chain and then mounting the routers; the order is load-bearing. It returns the app without listening, and checks pin the ordering hazards.

What it does

builds Express app, registers global chain then mounts (order is load-bearing)

Inputs

ctx

Outputs

Express app (no listen)

Depends on

all routers

Safeguards

ordering hazards pinned by checks

Sets security headers, CSP, proxy validation, CORS, metrics and tracing at the start of the chain, including X-Request-ID. Safeguards are an allow-list CORS, a strict API CSP for JSON and a trusted proxy list.

What it does

sets headers; =, X-Request-ID; via trusted-proxy resolver

Inputs

HTTP request

Outputs

headers, req fields

Depends on

(other parts)

Safeguards

allow-list CORS, strict API CSP for JSON, trusted proxy list

Drains requests after shutdown begins by answering 503 SERVICE_SHUTTING_DOWN, and sets Cache-Control: no-store. An in-memory counter tracks the drain, and the gate fails closed on shutdown.

What it does

503 SERVICE_SHUTTING_DOWN after shutdown begins; Cache- Control: no-store

Inputs

request

Outputs

503 / header

Depends on

runtime

State

in-memory counter

Safeguards

fail-closed on shutdown

Parses JSON bodies with a strict UTF-8 check (TextDecoder fatal), rejects non-UTF-8 charsets and enforces a size limit. It answers 413 PAYLOAD_TOO_LARGE or 400 MALFORMED_JSON, the envelope depending on the path.

What it does

strict UTF-8 (TextDecoder fatal), rejects non-UTF-8 charset, saves; 413 PAYLOAD_TOO_LARGE / 400 MALFORMED_JSON (envelope depends on path)

Inputs

request body, MAX_BODY_BYTES (64 KiB default)

Outputs

event

Safeguards

UTF-8 only (SPEC S-072), size cap

Handles unmatched paths and thrown errors: protocol and probe prefixes get a decision-shaped body, others the management envelope. ControlPlaneError keeps its status and code, and no stack or message is leaked.

What it does

protocol/probe prefixes get decision-shaped body, others management envelope; ControlPlaneError keeps status/code

Inputs

unmatched path / thrown error

Outputs

404 / 500 / control-plane status

Safeguards

no stack/message leaked (generic message)

Routes a rejection from an async handler to next(err) instead of crashing, relying on the runtime. This avoids process exit.

What it does

routes rejection to next(err)

Inputs

rejected async handler

Depends on

runtime

Safeguards

avoids process exit

Sets the X-QODIQA-API-Version: v1 header on responses for /v1/* routes, so clients can see the API version that served the call. It is registered after most /v1 mounts.

What it does

sets X-QODIQA-API-Version: v1; registered after most /v1 mounts (see)

Inputs

/v1/*

Outputs

response header

Handles POST /sign in a 16-step flow using a Bearer signing key and the request body. It returns 200 and a SIGN_DECISION event, protected by per-identity API keys, lockout, scope checks, anti-spoofing, TTL<=60 s and native-signature self-verify.

What it does

16-step flow

Inputs

Bearer signing key; body

Outputs

200; SIGN_DECISION event

Depends on

providers, validation/*

State

none in-route (keys/identities in stores)

Safeguards

per-identity API key, lockout, env scope, provider scope, reserved-claim anti-spoofing, TTL<=60 s, native-signature self-verify

Authenticates and admits /sign requests: IP throttle, admission, token resolve (store or OIDC), lockout, SIGN_ARTIFACT permission, then freeze. Refusals are 401, 403, 429 or 503 BLOCK bodies; lockout is 10/60 s -> 300 s and storage outages fail closed.

What it does

IP throttle -> admission -> token resolve (store or OIDC) -> lockout -> permission SIGN_ARTIFACT -> freeze

Inputs

Authorization header

Outputs

401/403/429/503 BLOCK bodies

Depends on

Redis lockout

State

Redis (lockout), control plane (identities)

Safeguards

constant decision shapes; lockout 10/60 s -> 300 s; storage outage fail-closed

Runs the full non-stream pipeline for POST /ai/chat and its 3 aliases, taking the x-qodiqa-artifact header and body. It returns 200 EXECUTE or BLOCK, or a 4xx/5xx, with signature, binding, nonce and execution-token checks and fail-closed evidence.

Streaming path for /ai/chat with the same enforcement: refuses output on DLP or content rules, applies a pre-stream timeout only, and delivers SSE. Output-rule failures fail closed, and abort CQ-06 applies.

What it does

same enforcement, refuses output DLP/content rules, pre-stream timeout only, SSE

Inputs

stream:true

Outputs

SSE or JSON BLOCK

Depends on

(other part)

State

audit/leaf via

Safeguards

fail-closed on output rules, abort CQ-06

Caveat pre-stream timeout only

Runs enforcement pipeline steps E1-E8: identity limit, classification budget, scope, idempotency, effective policies and drift. It returns an ALLOW descriptor or BLOCK, writing audit and leaf on post-signature BLOCK; pre-auth rejects are never audited.

What it does

identity limit, classification budget, scope, idempotency, effective policies, drift

Inputs

artifact, request

Outputs

ALLOW descriptor or BLOCK

Depends on

validation, core/*

State

audit+leaf on post-signature BLOCK

Safeguards

pre-auth rejects never audited

Provides idempotency in /ai/chat: validates the key, reserves it, replays a completed EXECUTE byte-for-byte and releases on every non-EXECUTE exit. It echoes Idempotency-Key and sets Idempotency-Replayed: true, with tenant-scoped fingerprints.

What it does

validate key, reserve, replay completed EXECUTE byte-for-byte with fresh, release on every non-EXECUTE exit

Inputs

Idempotency-Key

Outputs

Idempotency-Key echo, Idempotency-Replayed: true

Depends on

/store

State

Redis idempotency store

Safeguards

tenant-scoped fingerprint, no stream support

Caveat no stream support

Applies semantic checks in the route to the request text and, with the RESPONSE surface, the provider output, plus an embedding gate and an OUTPUT_TOO_LARGE cap. A block withholds the response and writes audit and leaf.

Runs the DLP, content-rule, routing and budget stages: input content rules, DLP transform or block, policy routing with a failover authoriser, atomic budget reserve, settle and refund, and output rules. Events are COST_ACCOUNTED and DLP_TRANSFORM.

What it does

input content rules, DLP transform/block, policy routing with failover authoriser, atomic budget reserve/settle/refund, output rules

Inputs

body, policies

Outputs

BLOCK reasons, COST_ACCOUNTED / DLP_TRANSFORM events

Depends on

stage modules (other parts)

State

budget store

Safeguards

authoriser re-runs for routed target

Executes the provider call by minting an HMAC execution token and an INTENT audit entry, then returning a normalised response with the model and routing. The invariant is asserted twice and INTENT fails closed.

What it does

mint HMAC token -> INTENT entry -> normalized response

Inputs

verified artifact, body

Outputs

model, routing

Depends on

providers/router

State

INTENT audit entry + leaf

Safeguards

invariant asserted twice, INTENT fail-closed

Writes ALLOW evidence: a mandatory audit append, a transparency leaf (queued or journalled if PG fails), a signed receipt, commit tracker and AI-disclosure. The EXECUTE body carries transparency{}, and failure returns 503 with outcome details.

What it does

mandatory ALLOW append, leaf (queue/journal if PG fails), signed receipt, commit tracker, AI-disclosure

Inputs

executed result

Outputs

EXECUTE body with transparency{} and; receipt if persisted

State

audit chain, transparency log, receipt store

Safeguards

fail-closed 503 with outcome details

Writes BLOCK evidence: a DECISION entry for BLOCK, a best-effort leaf, a receipt, and AUT-09 reconcile registration when closing an open lifecycle. It guards against unrepresentable text and raises CRITICAL on gaps.

What it does

DECISION entry (BLOCK), best-effort leaf, receipt, AUT-09 reconcile registration when closing an open lifecycle

Inputs

block args

Outputs

audit entry hash, receipt

Depends on

transparency

State

audit chain, transparency log

Safeguards

unrepresentable-text guard, CRITICAL on gaps

Maps error codes to HTTP statuses and sets BLOCK status according to mode (decision or status). It returns the status plus Retry-After.

What it does

code -> HTTP; BLOCK status by mode (decision/status)

Inputs

error code / reason

Outputs

status + Retry-After

Dry-run POST /verify and /verify/v2 with strict schemas, dry-run stores, a dry-run policy and semantic parity. It returns 200 EXECUTE or BLOCK, or 400 on malformed input, limited to 30/60 per min with a 5 s timeout.

What it does

strict schemas, with dry-run stores, dry-run policy, semantic parity

Outputs

200 EXECUTE/BLOCK, 400 on malformed

State

none (read-only)

Safeguards

rate limit 30/60 per min, 5 s timeout

Wraps stores for dry runs, using peek instead of register, record or increment, so the stores are non-mutating. Verify can therefore never consume a nonce.

What it does

/peek/ instead of register/record/increment

Inputs

stores

Outputs

non-mutating stores

Safeguards

verify can never consume a nonce

Gates requests on the kill switch before any work, answering 503 KILL_SWITCH_ACTIVE or STATE_UNAVAILABLE with Retry-After 30. State comes from the control plane, and it fails closed when state cannot be read.

What it does

503 KILL_SWITCH_ACTIVE / STATE_UNAVAILABLE + Retry-After 30 before any work

Inputs

request

Outputs

503 body

Depends on

(injected)

State

control plane

Safeguards

fails closed when state cannot be read

Controls admission with an in-flight cap and bounded FIFO queue; families are sign 64/128, ai_chat 16/32, verify 64/128, actions 64/128 and tools 16/32 with a 1 s queue timeout. Refusals return 503 SERVER_OVERLOADED and write no evidence.

What it does

in-flight cap + bounded FIFO queue; families sign 64/128, ai_chat 16/32, verify 64/128, actions 64/128, tools 16/32, queue timeout 1 s

Inputs

route family

Outputs

503 SERVER_OVERLOADED + Retry-After; /ready component

Depends on

metrics, audit-log backpressure

State

in-memory

Safeguards

no evidence written on refusal, nonce unconsumed

Validates the request with strict zod: request, payload<=8192 B, ttl and v2. It returns the parsed body or a rejection, with strict keys and depth and size caps as safeguards.

Validates steps 1-7 on the artifact and request using revocation and nonce/anomaly checks backed by Redis. It returns a frozen allow or deny result and fails closed on every store error.

Checks the Ed25519 envelope: schema, canonical signature, key resolve, verify, tenant match, time bounds and key lifecycle. Only canonical base64 signatures are accepted, with a domain-separated hash; the result is EXECUTE or BLOCK.

What it does

schema, canonical signature, key resolve, verify, tenant match, time bounds, key lifecycle

Inputs

artifact

Outputs

EXECUTE/BLOCK

Depends on

ed25519

State

key store

Safeguards

canonical base64 signatures only, domain-separated hash

Checks request binding V1: a UUID v4 id and 64-hex hash are recomputed and compared. The result is bound or REQUEST_MISMATCH, using domain QODIQA::REQUEST::V1 and a constant-time compare.

Handles Protocol V2: claims, JCS-P1 and binding V2, with version classification, crit handling, a header-bound request hash and strict canonicalization. It returns ok/version or a refusal reason; unknown critical claims and content-coded bodies are refused.

What it does

version classification, crit handling, header-bound request hash, strict canonicalization

Inputs

artifact

Outputs

ok/version or refusal reason

Safeguards

unknown critical claim refused, content-coded bodies refused

Registers nonces and detects anomalies in one Lua EVAL (nonce SET NX PX, per-key and global sliding windows, restart barrier) or a sequential path. Outcomes are registered, replay, unprovable or anomaly, stored under qodiqa:req:v2:* and anomaly:v2:*, and a store error fails closed.

What it does

single Lua EVAL (nonce SET NX PX, per-key and global sliding windows, restart barrier) or sequential path

Inputs

expiry, tenant

Outputs

registered/replay/unprovable/anomaly

Depends on

Redis

State

Redis keys qodiqa:req:v2:*, anomaly:v2:*

Safeguards

fail-closed on store error

Adapter that requires an explicit boolean and delegates policy evaluation, taking policies, store, artifact and attributes. It returns allowed with provenance or a denial, and has no implicit default.

Provides signing helpers that validate the envelope, Ed25519-sign (locally or natively) and compute the canonical hash. The result is a frozen artifact.

What it does

validate envelope, Ed25519 sign (local or native), canonical hash

Inputs

envelope, key

Outputs

frozen artifact

Validates multi-turn conversations by role, size and count rules and normalises them to provider messages. It returns a reason or null, with caps of 50 msgs / 32 KiB / 128 KiB.

What it does

role/size/count rules, normalize to provider messages

Inputs

messages/system

Outputs

reason or null

Safeguards

caps 50 msgs / 32 KiB / 128 KiB

Wraps zod with zod-3 compatible messages, an integer check and depth and size helpers, working from zod errors. It depends on zod 4.6.7.

What it does

zod-3 compatible messages, integer check, depth/size helpers

Inputs

zod errors

Depends on

zod 4.6.7

Handles POST /v1/actions/authorize, approvals and plans: agent, session, tool-registry, schema and budget checks produce an action artifact (Ed25519 <=60 s). It returns 200, 201 or 202, or BLOCK, with sign-style auth and ABAC/DLP attributes.

What it does

agent/session/tool-registry/schema/budget checks -> action artifact (Ed25519 <=60 s)

Inputs

signing identity

Outputs

200/201/202 or BLOCK

Depends on

agents, approvals, delegation, mcp/

State

plan/approval/agent stores

Safeguards

sign-style auth, ABAC/DLP attributes

Handles POST /v1/delegations: issue, verify, get and revoke. Issuance is an authorised action, chains verify offline and revocation cascades. Tokens are signed and attenuated.

What it does

issuance is an authorised action; chain verify offline; cascade revoke

Inputs

signing identity

Outputs

delegation token/chain

Safeguards

signed tokens, attenuation

Handles POST /v1/tools/call: the executor re-checks hash, replay and policy, then makes an SSRF-guarded MCP call, screens the result and issues ACTION_COMMIT. It returns 200 with a result and receipt; no stdio, no redirects, pinned identity.

What it does

executor re-checks hash, replay, policy; SSRF-guarded MCP call; result screening; ACTION_COMMIT

Inputs

signing identity

Outputs

200 result + receipt

Depends on

*

State

audit entries

Safeguards

no stdio, no redirects, pinned identity

Administers agents, sessions, the tool registry, MCP servers and approvals with CRUD and lifecycle on per-tenant RLS stores. Every change needs MFA step-up; permissions are MANAGE_/READ_*, and an approver must differ from the requester.

What it does

CRUD / lifecycle on per-tenant RLS stores; MFA step-up on all changes

Inputs

operator

Outputs

management envelope

Depends on

actions/, mcp, approvals

State

PG control records

Safeguards

permissions MANAGE_/READ_*, approver != requester

Public transparency API with entry, entries, roots, verify, proof, receipt and consistency endpoints; verify persists only if authenticated. It returns JSON from the PG/file log, limited to 120/min and 30/min on verify.

What it does

entry, entries, root(s), verify, proof, receipt, consistency; verify persists only if authenticated

Inputs

ids / ranges

Outputs

JSON

Depends on

*

State

transparency log (PG/file)

Safeguards

120/min + 30/min on verify

Public verification portal: submit a verification, then fetch the result and a report as JSON or PDF. The IP is withheld, and results for anonymous callers are ephemeral.

What it does

submit verification, fetch result and report (JSON/PDF), IP withheld

Inputs

{artifact...} / ids

Outputs

JSON/PDF

Depends on

evidence chain

State

portal store

Safeguards

ephemeral for anonymous

Public attestation endpoints that verify artifact or evidence JSON and fetch an attestation, using the evidence stores and the attestation store. They apply the same safeguards as the public verification portal.

Public certification endpoints to get a certification, a summary and a certificate, backed by the certification store. Rate limited, and returns JSON.

What it does

get certification, summary, certificate

Outputs

JSON

State

certification store

Safeguards

rate limited

Serves /health, /ready and /health/redis: liveness, readiness of 10 components (9 required) and Redis store health. It returns 200 or 503 JSON, with optional ip allow, loopback or auth.

What it does

liveness; readiness of 10 components (9 required); Redis store health

Inputs

GET

Outputs

200/503 JSON

Depends on

stores, pool, admission

Safeguards

optional ip allow / loopback / auth

Latches audit persistence health after 3 consecutive AUDIT_PERSISTENCE_FAILED results and recovers on a successful append or fsync probe, using the probe file .qodiqa-ready-probe in the audit dir. The state feeds /ready.

What it does

latch after 3 consecutive AUDIT_PERSISTENCE_FAILED; recover on append or fsync probe

Inputs

append outcomes

Outputs

for /ready

Depends on

audit-log

State

probe file.qodiqa-ready-probe in audit dir

Serves /metrics as Prometheus text and /diagnostics as a JSON snapshot with versions, pid, pool stats and monitors. Access is behind an IP allow, ops token and gate.

What it does

Prometheus text; JSON snapshot incl. versions, pid, pool stats, monitors

Inputs

GET

Outputs

text / JSON

Depends on

observability/metrics, monitors

Safeguards

(IP allow, ops token, gate)

Offers heap, GC and CPU profilers under /diagnostics/profile/, behind a second kill switch. Two independent gates protect it, and it takes GET or POST requests and returns JSON.

What it does

heap/GC/CPU profilers behind a second kill switch

Inputs

GET/POST

Outputs

JSON

Safeguards

two independent gates

Dashboard API and SSE covering overview, executions, blocked, replays, anomalies, status and activity, plus an SSE stream. It is served from in-memory state or the collector and needs the VIEW_DASHBOARD read permission.

What it does

overview, executions, blocked, replays, anomalies, status, activity, SSE stream

Inputs

GET

Outputs

JSON / SSE

Depends on

(collector)

State

in-memory/collector

Safeguards

READ perm VIEW_DASHBOARD

Serves /audit: the artifact audit record, a timeout-bounded chain integrity walk and verifier status or manual verify. It requires READ_AUDIT, with a tighter limiter on manual verify.

What it does

artifact audit record, chain integrity walk (timeout-bounded), verifier status/manual verify

Inputs

GET/POST

Outputs

management envelope

Depends on

audit-log, verifier

State

audit chain

Safeguards

READ_AUDIT, tighter limiter on manual verify

Serves /audit-viewer: search, timeline, export, per-artifact views and investigations, kept in an investigation store. It requires READ_AUDIT and is limited to 60/min.

What it does

search, timeline, export, per-artifact views, investigations

Inputs

GET/POST

Outputs

JSON / export

Depends on

audit-log, investigation store

State

investigation store

Safeguards

READ_AUDIT, 60/min

Serves /audit-store: central audit search, correlation and stats, plus retention policies and legal holds, held in the central store on PG. It requires READ_AUDIT or MANAGE_RETENTION.

What it does

central audit store search/correlation/stats; retention policies and legal holds

Inputs

GET/POST/DELETE

Outputs

JSON

Depends on

retention

State

central store (PG)

Safeguards

READ_AUDIT / MANAGE_RETENTION

Serves /evidence and /v1/evidence: JSON, PDF, audit, verify and bundle evidence packages, including an offline-verifiable bundle. It requires GENERATE_EVIDENCE and sets a CSP for PDF.

What it does

JSON/PDF/audit/verify/bundle evidence packages (offline- verifiable bundle)

Inputs

GET

Outputs

JSON/PDF

State

audit/transparency reads

Safeguards

GENERATE_EVIDENCE; CSP for PDF

Serves /evidence-chain: search, chain segment, verify range, 7-step record verification and CSV export, from the evidence chain store. It needs READ or VERIFY_EVIDENCE_CHAIN permission.

What it does

search, chain segment, verify range, 7-step record verification, CSV export

Inputs

GET/POST

Outputs

JSON/CSV

State

evidence chain store

Safeguards

READ/VERIFY_EVIDENCE_CHAIN

Serves /provenance: policy history, reconstruct, diff, lineage, integrity, report and dashboard, from the provenance store. It needs READ_POLICY_PROVENANCE or INVESTIGATE_POLICIES.

What it does

policy history/reconstruct/diff/lineage/integrity/report/dashboard

Inputs

GET/POST

Outputs

JSON

State

provenance store

Safeguards

READ_POLICY_PROVENANCE / INVESTIGATE_POLICIES

Serves /policy-ui to list, validate and read policies; writes create governed change requests, with versions, diff and rollback. It uses maker-checker, READ/MANAGE_POLICIES permissions and a 60/min limit.

What it does

list/validate/read policies; writes create governed change requests; versions/diff/rollback

Inputs

GET/POST/PUT

Outputs

JSON

Depends on

store

State

policy store, change requests

Safeguards

maker-checker, READ/MANAGE_POLICIES, 60/min

Serves /v1/policy/governance: the maker-checker lifecycle, rollback and emergency override, kept in the change-request store. Each transition has a distinct permission and every mutation needs MFA.

What it does

maker-checker lifecycle, rollback, emergency override

Inputs

GET/POST

Outputs

JSON

Depends on

*

State

change-request store

Safeguards

distinct permissions per transition, MFA on every mutation

Runs read-only policy simulation, comparison and batch simulation (batch <=100) under /v1/policy/simulate. It needs READ_POLICIES and is exempt from step-up.

What it does

read-only simulation (:true), batch <=100

Inputs

POST

Outputs

JSON

Safeguards

READ_POLICIES, no step-up (exempt)

Serves /v1/policy/visual/* with graph, tree, deps, stats, highlight, flow and export views for the policy visual builder. It needs READ_POLICIES.

What it does

graph/tree/deps/stats/highlight/flow/export

Inputs

POST/GET

Outputs

JSON

Depends on

policy visual builder

Safeguards

READ_POLICIES

Serves /key-admin: inventory, health, rotate, graceful, revoke and recover per client, KEK and MAC keyring rotation, and purge. It needs MANAGE_KEYS with step-up and a Redis rotation lock.

What it does

inventory, health, rotate/graceful/revoke/recover per client, KEK and MAC keyring rotation, purge

Inputs

GET/POST

Outputs

JSON

State

key store, Redis lock

Safeguards

MANAGE_KEYS, step-up, rotation lock

Serves /rbac for roles, users, API keys (ok_...), permissions and MFA enrolment, backed by the RBAC store and custom roles. It needs MANAGE_ or READ_USERS, has a revoke ceiling and uses MFA.

What it does

roles, users, API keys (ok_...), permissions, MFA enrolment

Inputs

GET/POST/PATCH/PUT/DELETE

Outputs

JSON

Depends on

*

State

RBAC store, custom roles

Safeguards

MANAGE_/READ_USERS, revoke ceiling, MFA

Serves /signing-identities for identity CRUD and issuing or revoking an sk_ API key. Permissions are READ or MANAGE_SIGNING_IDENTITIES, and the key is shown once.

What it does

identity CRUD, issue/revoke sk_ API key

Inputs

GET/POST/PATCH/PUT/DELETE

Outputs

JSON

State

control plane

Safeguards

READ/MANAGE_SIGNING_IDENTITIES, key shown once

Serves /consent: grant, list, get, revoke, suspend, resume, actor revoke, audit, status, history, verify and health. It needs MANAGE_CONSENT, uses strict schemas and alias normalisation, and publishes revocations over Redis pub/sub.

Serves /compliance: frameworks, controls, and report generate, list, get, verify and download as JSON, PDF or HTML, stored in PG. It needs READ_COMPLIANCE or GENERATE_REPORT and keeps report integrity.

What it does

frameworks, controls, report generate/list/get/verify/download (JSON/PDF/HTML)

Inputs

GET/POST

Outputs

JSON/PDF/HTML

Depends on

*

State

report store (PG)

Safeguards

READ_COMPLIANCE / GENERATE_REPORT, report integrity

Serves /v1/webhooks: endpoint CRUD, metrics, trial delivery and delivery history. The secret is returned once, URLs must be HTTPS-only and deliveries are signed.

What it does

endpoint CRUD, metrics, trial delivery, deliveries; secret returned once

Inputs

all

Outputs

JSON

Depends on

*

State

webhook store

Safeguards

HTTPS-only URLs, signed deliveries

Serves /v1/prq, the recovery dead-letter queue: queue stats plus DLQ list, get, replay and archive. It needs READ or MANAGE_RECOVERY_QUEUE.

What it does

queue stats, DLQ list/get/replay/archive

Inputs

GET/POST/DELETE

Outputs

JSON

State

recovery queue

Safeguards

READ/MANAGE_RECOVERY_QUEUE

Serves /v1/admin/organizations and /tenants: the organization and tenant registry, organization membership and portal session revoke, held in the control plane. It needs MANAGE_USERS.

What it does

org/tenant registry, org membership, portal session revoke

Inputs

CRUD + portal-user session revoke

Outputs

JSON

Depends on

registries

State

control plane

Safeguards

MANAGE_USERS

Admin routes for the global kill switch (activate, release), the provider compat registry, per-artifact revocation and the GDPR DSR workflow. They use dedicated permissions and MFA, with state in the control plane or DSR store.

What it does

global kill switch activate/release; provider compat registry; per-artifact revoke; GDPR DSR workflow

Inputs

operator

Outputs

JSON

Depends on

providers, dsr

State

control plane / DSR store

Safeguards

dedicated permissions, MFA

Serves /v1/proofs: a downloadable qodiqa-proof/1 bundle for one request, read from audit, transparency and receipt data. It needs READ_AUDIT_PROOFS (+FULL_CHAIN) and returns a tenant-scoped 404.

What it does

downloadable qodiqa-proof/1 bundle for one request

Inputs

GET

Outputs

JSON

State

audit/transparency/receipt reads

Safeguards

READ_AUDIT_PROOFS (+FULL_CHAIN), tenant-scoped 404

Admin and batch endpoints for the transparency log, portal, attestation and certification: register entries, root generation, chain validation, histories, exports, evaluation and batch jobs. Permissions are per router; /portal and /v1/attestation admin are not step-up gated.

Mounts /alerts only: list, acknowledge, resolve, suppress and stream alerts from the alert store, as JSON or SSE. It needs READ_AUDIT plus MANAGE_ALERTS.

What it does

alert list/ack/resolve/suppress/stream

Inputs

operator

Outputs

JSON/SSE

State

alert store

Safeguards

READ_AUDIT + MANAGE_ALERTS

Applies the admin and ops protection stack in order: pre-gate, rate limit, ip allow, auth, permission, then plane gate. Failures return 401, 403, 404 or 429; plane kill switches are non-enumerable (R-09).

What it does

pre-gate -> rate limit -> ip allow -> -> -> permission -> plane gate

Inputs

credentials

Outputs

401/403/404/429

Depends on

rbac

State

RBAC store, Redis lockout

Safeguards

plane kill switches non-enumerable (R-09)

Requires MFA step-up per mutation using a TOTP or recovery code from the X-QODIQA-OTP header. SSO assurance can bypass it; failures return 401, 403, 429 or 503, with a lock after 5 failures per 15 min.

What it does

TOTP/recovery code per mutation; SSO assurance bypass; spec declaration

Inputs

X-QODIQA-OTP

Outputs

401/403/429/503

Depends on

(injected)

State

mfa store

Safeguards

lock after 5 failures/15 min

Optional authentication for public verify routes: with no credential the caller is anonymous and ephemeral, and with a credential the full admin stack runs. A bad credential is never downgraded.

What it does

none -> anonymous ephemeral; presented -> full admin stack

Inputs

optional credential

Outputs

pass-through or stack errors

Safeguards

bad credential never downgraded

Permission guard that throws at mount when a permission is missing, outside non-production mode (SEC-07). Mounting therefore fails closed instead of leaving a route unprotected.

What it does

throws at mount when missing outside non-production mode (SEC-07)

Inputs

factory

Outputs

middleware

Safeguards

fail-closed mounting

SAML SSO: login redirects with signed relay state, ACS exchanges the assertion for an operator session token, and metadata is served. Errors are uniform with a generic 401; a per-client limiter applies.

What it does

redirect with signed relay state; ACS -> operator session token; generic 401

Inputs

GET login, POST acs (urlencoded 256 KiB), GET metadata

Outputs

JSON token

State

rbac store

Safeguards

per-client limiter, uniform errors

LDAP sign-in: a directory bind followed by a token, from a POST login of 4 KiB. It is limited to 10/min per address, with per-user lockout.

Tenant portal OIDC, session and API: PKCE login, callback verification, tenant claim check, MFA assurance and session mint, plus /api me, keys, consent, usage and export. Logout revokes sessions; state and session use HMAC and dev-login is blocked in production.

What it does

PKCE login, callback verification, tenant claim check, MFA assurance, session mint, /api me,keys,consent,usage,export; logout revokes sessions

Inputs

browser GET login/callback, session bearer

Outputs

redirects / JSON / CSV

Depends on

usage metering

State

portal user store

Safeguards

HMAC state and session, dev-login blocked in production

Issues and checks portal session tokens and flow state as HMAC-SHA256 base64url tokens lasting 8 h and 5 min, keyed by QODIQA_PORTAL_SESSION_SECRET. Fields are strictly checked and the module is stateless.

What it does

HMAC-SHA256 base64url tokens, 8 h / 5 min

Inputs

secret QODIQA_PORTAL_SESSION_SECRET

Outputs

token / payload or null

State

none (stateless; revocation via)

Safeguards

strict field checks

Builds the response envelopes for management success and errors, from data or a code, using the logger. Messages are generic, and the exact envelope shapes are not stated.

Declares which response envelope is allowed for each route file, tied to the openapi module, so route responses stay within the permitted shapes.

What it does

declares allowed envelope per route file

Inputs

route file

Depends on

openapi/

Holds the block HTTP status class table (14 classes) and checks for duplicates at load. It maps a reason to a status and depends on semantic reasons.

What it does

class table (14 classes), duplicate check at load

Inputs

reason

Outputs

status

Depends on

semantic reasons

Spec generator that assembles the 3.1.0 document and error catalog from static registries into a frozen spec object, cached in memory. It depends on constants and errors/catalog.

What it does

assembles 3.1.0 document + error catalog

Inputs

static registries

Outputs

frozen spec object

Depends on

constants, errors/catalog

State

in-memory cache

Route registry and components: hand-maintained declarations of 364 operations and 84 schemas, producing the paths and components of the spec.

What it does

hand-maintained declarations of 364 operations, 84 schemas

Outputs

paths/components

Live route parity harness that wraps the real app to record mount paths and walk the stack, then compares the route set against the spec.

What it does

wraps / to record mount paths and walk the stack

Inputs

real app

Outputs

route set vs spec

Writes or checks (--check) the committed contract and detects drift, reporting an exit code and sha256. It depends on the generator.

Builds the public API subset by filtering the contract and pruning components into an openapi file covering 23 ops. It depends on the contract.

What it does

filter + prune components -> openapi. (23 ops)

Outputs

file

Depends on

contract

Generates a reference document grouped by tag and writes it out to a file, giving a readable overview of the API operations.

What it does

grouped by tag

Outputs

file

Serves the Swagger UI and spec endpoints: JSON and YAML spec, an HTML page and vendored assets. Assets carry SRI sha384, names are allow-listed and nosniff is set.

What it does

JSON/YAML spec, HTML page, vendored assets with SRI

Inputs

GET

Outputs

text/json/html

Depends on

generator

Safeguards

SRI sha384, allow-listed asset names, nosniff

Serves static console and admin pages: the explainer and Execution Studio (/sign then /ai/chat), dashboard, audit viewer, policy editor and approvals. They use no inline script, and a fetch wrapper adds the bearer key.

What it does

explainer + Execution Studio (/sign then /ai/chat), dashboard, audit viewer, policy editor, approvals

Inputs

browser

Outputs

HTML/JS

Depends on

API above

State

(operator key only)

Safeguards

no inline script; fetch wrapper adds bearer key

Serves tenant portal pages that redirect to /tenant-portal/login, take the token from the URL fragment and call /tenant-portal/api/*. The fragment-borne token is the safeguard.

What it does

redirect to /tenant-portal/login; token from URL fragment; calls /tenant-portal/api/*

Inputs

browser

Outputs

HTML

State

none shown

Safeguards

fragment-borne token