Runtime, startup and configuration

Chooses between a synchronous or async-bootstrap export and builds the app through startup. It reads the KMS and config-secrets provider settings and exits with code 1 if bootstrap fails (fail-closed).

What it does

Choose sync or async-bootstrap export; build app via startup

Inputs

QODIQA_KMS_PROVIDER, QODIQA_CONFIG_SECRETS_PROVIDER

Outputs

exports app (+) or Promise

Safeguards

fail-closed exit 1 on bootstrap

Runs the production entry: bootstraps KMS, then config secrets, then loads the server. Any failure ends the process with exit 1, so the gateway fails closed instead of starting half-configured.

What it does

KMS bootstrap, config-secrets bootstrap, load server

Inputs

env

Outputs

process exit 1 on any failure

Depends on

same

Safeguards

fail-closed

Dispatches the development command line by spawning a child process and forwarding signals to it. It reports its result through exit codes 0, 1 and 2, relying on node child_process.

What it does

spawn; signal forwarding

Inputs

argv

Outputs

exit codes 0/1/2

Depends on

node child_process

Hardens the process at startup: sets the process title and umask 027, installs crash handlers and runs a cluster check. It crashes on unknown state rather than continuing, and reads NODE_ENV.

What it does

title, umask 027, crash handlers, cluster check

Inputs

NODE_ENV

Outputs

process-level

Depends on

/

Safeguards

umask, crash-on-unknown-state

Resolves the deployment mode and rewrites related settings from QODIQA_DEPLOYMENT_MODE, QODIQA_PG_ENABLED and QODIQA_AUDIT_ORDERING_MODE plus replica and migrate variables. Invalid input exits 1, fail-closed with a webhook.

What it does

resolve, rewrite

Inputs

QODIQA_DEPLOYMENT_MODE, QODIQA_PG_ENABLED, QODIQA_AUDIT_ORDERING_MODE, replica/migrate vars

Outputs

exit 1 on invalid

Safeguards

fail-closed + webhook

Validates the whole environment at boot against a Zod schema and 41 rules. Fatal problems raise BOOT_VALIDATION_FATAL and exit 1; others become warnings. Rules cover secret strength, TLS, anchoring and semantic override bans.

What it does

Zod schema + RULES

Inputs

whole env

Outputs

BOOT_VALIDATION_FATAL + exit 1, warnings

Depends on

zod

State

memory

Safeguards

secret strength, TLS, anchoring, semantic override bans

Holds the pattern lists used to judge the quality of placeholder and secret strings. It takes strings in and returns status codes; its safeguard is placeholder detection.

What it does

pattern lists

Inputs

strings

Outputs

status codes

Safeguards

placeholder detection

Parses the ops, admin and diagnostics configuration into a frozen object from QODIQA_OPS_*, QODIQA_ADMIN_ENABLED, QODIQA_DIAGNOSTICS_ENABLED and health variables. It emits OPS_CONFIG_* events and checks allowlist syntax; planes default off in prod.

What it does

parse + frozen object

Inputs

QODIQA_OPS_*, QODIQA_ADMIN_ENABLED, QODIQA_DIAGNOSTICS_ENABLED, health vars

Outputs

events OPS_CONFIG_*

Depends on

logger

Safeguards

allowlist syntax check, planes default off in prod

Gathers PG, Redis, keys and semantic facts into a boot report. It writes a BOOT_REPORT log and optionally a JSON file at QODIQA_BOOT_REPORT_PATH. The report is secret-free.

What it does

gather PG/Redis/keys/semantic facts

Inputs

facts + deps

Outputs

BOOT_REPORT log, optional file QODIQA_BOOT_REPORT_PATH

Depends on

pg pool, redis cfg, semantic cfg

State

optional JSON file

Safeguards

secret-free

Initialises, fetches and applies config-secrets providers, mutating the environment from the provider type and Vault variables. It clears stale managed secrets; the vault-kv path uses node-vault.

Runs phase-1 module-load initialisation from the environment, starting stores and monitors. It depends on many modules, and fail-closed gates guard the startup so a failed step stops it.

Covers the startup sequence that takes the app to an HTTP listener and schedulers, with all other parts as dependencies. The S1–S24 gates protect it.

Enforces the production durability gate: requires PG and readable evidence stores when NODE_ENV says production. If the requirement is not met, it exits with a FATAL error (fail-closed).

What it does

require PG + readable evidence stores

Inputs

NODE_ENV

Outputs

FATAL exit

Safeguards

fail-closed

Attempts a login with the migration role's placeholder credential, controlled by QODIQA_PG_ROLE_CREDENTIAL_GATE. Outcomes are FATAL, ERROR or WARN, and roles with public passwords are blocked.

What it does

attempt login

Inputs

QODIQA_PG_ROLE_CREDENTIAL_GATE

Outputs

FATAL/ERROR/WARN

Depends on

PG

Safeguards

blocks public-password roles

Refuses to start when STRICT_REPLAY would be unsafe, judging from Redis persistence diagnostics. The result is exit 1, which keeps replay protection intact.

What it does

refuse start if unsafe

Inputs

Redis persistence diag

Outputs

exit 1

Safeguards

replay protection

Monitors runtime degradation by turning gateway state events into gauges, including redis_store_up and execution_integrity_full. It listens to store emitters and depends on metrics.

What it does

gateway state events + gauges

Inputs

store emitters

Outputs

metrics redis_store_up, execution_integrity_full

Depends on

metrics

Sets server timeouts before the server begins listening, using PORT, QODIQA_BIND_HOST and timeout settings. The timeouts guard against slowloris-style attacks.

What it does

set server timeouts before listen

Inputs

PORT, QODIQA_BIND_HOST, timeouts

Outputs

listener

Depends on

http

Safeguards

slowloris-style timeouts

Validates proxy configuration with warnings at boot and answers per-request with 400 BLOCK bodies. It reads TRUSTED_PROXY, QODIQA_ALLOWED_HOSTS, ENFORCE_HTTPS_PROTO and MAX_FORWARDED_DEPTH, defending against host-header injection and XFF forging.

What it does

warnings at boot; per-request 400s

Inputs

TRUSTED_PROXY, QODIQA_ALLOWED_HOSTS, ENFORCE_HTTPS_PROTO, MAX_FORWARDED_DEPTH

Outputs

BLOCK bodies

Safeguards

host-header injection, XFF forging

Gates startup on mirror, chain and checkpoint checks over PG and audit files, exiting 1 on failure. It depends on the audit modules and is fail-closed.

Starts the embedding classifier pool and initialises it, using QODIQA_INFERENCE_WORKERS and QODIQA_SEM_EMBEDDING_ENABLED. If it is not READY the process exits 1, refusing to start without the screening layer.

What it does

pool + init

Inputs

QODIQA_INFERENCE_WORKERS, QODIQA_SEM_EMBEDDING_ENABLED

Outputs

exit 1 if not READY

Depends on

semantic modules

Safeguards

refuse start without screening layer

Starts the schedulers after the server is listening, based on PG flags. It depends on the scanners and similar components, and it starts the timers only once the listener is up.

What it does

start timers

Inputs

PG flags

Depends on

scanners etc.

Resolves the client IP using a trust predicate and a right-to-left walk over socket, XFF and X-Real-IP values. It never trusts a proxy blindly.

What it does

trust predicate, right-to-left walk

Inputs

socket, XFF, X-Real-IP

Safeguards

no blind proxy trust

Composes the Express app by wiring the middleware chain and mounting the routers from a context object. The layered composition is its stated safeguard.

What it does

middleware + mounts

Inputs

ctx

Outputs

Express app

Depends on

routers

Safeguards

layered

Patches async handlers so a rejected promise is passed on through next(err), relying on Express internals. This prevents a crash on async rejection.

Sets security headers using helmet plus a Permissions-Policy, depending on NODE_ENV. Safeguards include HSTS in prod, frame deny and CSP.

What it does

helmet + Permissions-Policy

Inputs

NODE_ENV

Outputs

headers

Depends on

helmet

Safeguards

HSTS (prod), frame deny, CSP

Overrides the Content-Security-Policy header for API responses by wrapping it in a strict CSP. The strict policy is the safeguard, and the CSP header is the output of this step.

Generates a request id as a UUID using the crypto module and exposes it both as a response header and in the request locals, so each request can be identified in later steps.

Parses request bodies with a size limit taken from MAX_BODY_BYTES, plus a verify step. It rejects invalid UTF-8 and answers 400 or 413 when a body is refused.

What it does

+ verify

Inputs

MAX_BODY_BYTES

Outputs

400/413

Safeguards

rejects invalid UTF-8

Drains requests using a counter and answers 503 once draining has started, so new requests are turned away while the count of active requests falls.

What it does

counter + 503

Gates requests with the kill switch: answers 503 when the switch is active or its state is unavailable, and emits a metric. State lives in the control plane, and the gate fails closed.

What it does

503 when active/unavailable

Outputs

metric

State

control plane

Safeguards

fail-closed

Optional operator authentication for ops routes using a Bearer or X-Ops-Token credential, with federation as a dependency. Comparison is timing-safe and failures lock out, with lockout state kept in Redis.

Matches client addresses against an IP allowlist by CIDR, configured through QODIQA_OPS_IP_ALLOWLIST*. Non-matching requests get 403, and a misconfiguration denies all.

What it does

CIDR match

Inputs

QODIQA_OPS_IP_ALLOWLIST*

Outputs

403

Safeguards

deny-all on misconfig

Gates the plane routes, answering 404 when a plane is disabled. Because disabled planes return 404, the planes cannot be enumerated from outside.

What it does

404 when disabled

Safeguards

non-enumerable planes

Hardens the health probe with optional ops authentication or loopback-only access, controlled by flags. Rejected callers receive 401 or 403.

What it does

optional ops auth / loopback only

Inputs

flags

Outputs

401/403

Resolves RBAC and checks a permission, answering 403 on denial. It emits RBAC_* events and a metric, and the default is deny.

What it does

403 deny

Inputs

permission

Outputs

RBAC_* events/metric

Safeguards

default deny

Assembles the admin protection stack as ordered arrays of layers, applied in the order rate-limit, allowlist, auth, RBAC, gate. It lists no outputs or dependencies.

What it does

ordered arrays

Inputs

layers

Safeguards

rate-limit→allowlist→auth→RBAC→gate

Requires MFA step-up using the X-QODIQA-OTP header and the MFA module, with an MFA store. Failures return 4xx or 5xx, and an exemption list of 18 applies.

Authenticates signing credentials from a Bearer token through identity lookup and lockout. Lockout and assurance checks protect the path.

What it does

identity lookup, lockout

Inputs

Bearer

Safeguards

lockout, assurance

Authenticates portal sessions by verifying a Bearer session token and checking the user is live. Session version revocation invalidates old sessions.

What it does

verify, live user check

Inputs

Bearer session token

Safeguards

session version revocation

Wraps authentication so the layers run only if a credential header is present. There is no silent downgrade of a presented credential.

What it does

run layers iff credential header present

Safeguards

no silent downgrade

Sets the API version header and the deprecation headers on responses, so clients can see which API version served them and whether an endpoint is deprecated.

What it does

set headers

Outputs

headers

Enforces the request content type by answering 415 and producing a BLOCK outcome for any content type that is not supported.

Performs graceful shutdown on signals, ending with exit codes. It flushes in order across all stores it depends on, which is its stated safeguard.

What it does

Active

Inputs

signals

Outputs

exit codes

Depends on

all stores

Safeguards

ordered flush

Monitors the event loop with a histogram and a state, using perf_hooks and the QODIQA_EVENT_LOOP_* settings. It publishes gauges and events.

What it does

histogram, state

Inputs

QODIQA_EVENT_LOOP_*

Outputs

gauges/events

Depends on

perf_hooks

Tracks readiness as a flag with state transitions, and publishes the changes as metrics and events so other components can follow whether the service is ready.

What it does

flag + transitions

Outputs

metrics/events

Logs startup and clock diagnostics as events, drawing on the redis configuration. No credentials are logged, so the diagnostics can be read without exposing secrets.

Sends an early critical notification with a fetch POST that times out after 3 s, to the address in ALERT_WEBHOOK_URL. It never throws, so a failed notification cannot break startup.

What it does

fetch POST, 3 s

Inputs

ALERT_WEBHOOK_URL

Outputs

webhook

Depends on

fetch

Safeguards

never throws

Runs a named background task function and returns results and metrics, using the task registry and metrics. Failure isolation keeps one failing task from affecting others.

Registers the background tasks in a registry of 19 entries. Each entry is explicitly classified, which is the safeguard that keeps the set of tasks reviewable.

What it does

19 entries

Safeguards

explicit classification

Keeps task context using AsyncLocalStorage, so that work run by the background task runner can be tied to the task registry entry it belongs to.

What it does

AsyncLocalStorage

Writes raw diagnostics by emitting JSON objects directly to stderr. It takes no listed inputs and sends its output straight to the standard error stream.

What it does

write JSON

Outputs

stderr

Provides the NTP documentation check, covering the documentation that relates to network time synchronisation for the platform.

Covers the bootstrap for the split between the deployment and the KMS provider, which separates deployment configuration from the key management service provider.

Starts an isolated development bootstrap with npm run dev, reading .env and QODIQA_DEV_*. It launches a child gateway using a temp dir and an optional dev DB, protected by an isolation guard.

What it does

Active (npm run dev)

Inputs

.env, QODIQA_DEV_*

Outputs

child gateway

State

temp dir, optional dev DB

Safeguards

isolation guard

Command line that brings up a local sandbox gateway using Docker Redis and PG plus the sandbox provider. PG runs on tmpfs, and real provider keys are stripped.

What it does

Docker Redis/PG + sandbox provider

Inputs

flags

Outputs

local gateway

Depends on

docker

State

tmpfs PG

Safeguards

real provider keys stripped

Sandbox LLM provider that echoes requests and streams SSE responses over HTTP. It binds only to 127.0.0.1, which is its stated safeguard.

What it does

echo + SSE

Inputs

HTTP

Outputs

responses

Depends on

http

Safeguards

binds 127.0.0.1

Supplies the policy set used by the sandbox. The policies are kept in a file and loaded from it, so the sandbox runs against a defined set of rules.

What it does

policy set for sandbox

State

file

Standalone runtime preflight tool that runs 5 checks against REDIS_URL, QODIQA_PG_*, OLLAMA_BASE_URL and QODIQA_KEYS_PATH, using redis and pg. It exits 0 or 1, with optional files.

What it does

5 checks

Inputs

REDIS_URL, QODIQA_PG_*, OLLAMA_BASE_URL, QODIQA_KEYS_PATH

Outputs

exit 0/1

Depends on

redis, pg

Standalone benchmark command line tool. It runs the suites chosen through its flags and writes reports as output, and it can keep optional files for its state.

Standalone protocol harness that loops through sign, verify and policy steps and reports an exit code. It depends on many core modules.

What it does

sign/verify/policy loop

Outputs

exit code

Depends on

many core modules

Holds the error catalog of 182 codes, which feeds an OpenAPI extension so that the documented API errors match the codes the platform can return.

What it does

182 codes

Outputs

OpenAPI extension

Produces canonical JSON by normalising and sorting any input into a string, using fast-json-stable-stringify. It rejects unsafe keys and types.

What it does

normalize+sort

Inputs

any

Outputs

string

Depends on

fast-json-stable-stringify

Safeguards

rejects unsafe keys/types

Parses pagination from query parameters and builds the pagination meta for a response. The page size is capped at 500, which bounds how much one response can return.

What it does

parse/meta

Inputs

query

Safeguards

caps page size 500

Builds a Content-Disposition header from a filename in an injection-safe way. CRLF characters are stripped from the filename, preventing header injection.

What it does

header injection-safe

Inputs

filename

Outputs

header

Safeguards

CRLF strip

Guards CSV cells against formula injection by prefixing a quote to the cell value. It takes a cell as input and protects spreadsheet users who open exported files.

What it does

prefix quote

Inputs

cell

Safeguards

formula injection

Reorders rows into hash-link order and provides a streaming linker. It takes rows as input and detects forks in the chain.

What it does

reorder / streaming linker

Inputs

rows

Safeguards

detects forks

Implements a timeout race, a small helper that lets an operation compete against a timer so a slow call can be cut off. It is active.

Defines the policy files. The dev set has 5 policies: POL-001 REQUIRE_CONSENT, POL-002 BLOCK_IP, POL-003 TIME_WINDOW (disabled), POL-004 RATE_LIMIT and POL-NEW RATE_LIMIT; the prod example adds 4. A policy loader reads them from a file.

What it does

dev: 5 policies POL-001 REQUIRE_CONSENT, POL-002 BLOCK_IP, POL-003 TIME_WINDOW(disabled), POL-004 RATE_LIMIT, POL-NEW RATE_LIMIT; prod example: + 4 (REQUIRE_CONSENT_BASELINE, BLOCK_IP_DENYLIST(disabled), PER_USER_RATE_LIMIT, BUSINESS_HOURS_WINDOW(disabled))

Depends on

policy loader

State

file