Deployment, dependencies and operational tooling

Root package manifest declaring 13 dependencies, 9 optional and 14 dev, with engines node>=22 and overrides. npm install resolution fills node_modules; overrides pin qs, sharp, onnxruntime-web and tar.

What it does

npm install resolution

Outputs

node_modules

Depends on

npm

State

(v3, 1001 pkgs)

Safeguards

overrides for qs/sharp/onnxruntime-web/tar

Installs git hooks on npm install by setting git config to .githooks. It does nothing outside a git work tree and writes the entry to .git/config.

What it does

git config.githooks; no-op outside a work tree

Inputs

git work tree

Outputs

config entry

Depends on

git

State

.git/config

HTTP stack made up of 58 route and app files, with security headers and a CORS policy.

What it does

58 route/app files

Safeguards

security headers, CORS policy

PostgreSQL client and migrator that keeps a separate connection pool for each role and is configured through QODIQA_PG_* variables. It depends on PostgreSQL.

What it does

pools per role

Inputs

QODIQA_PG_*

Depends on

PostgreSQL

State

PG

Safeguards

per-role pools

Managed Redis client configured through REDIS_URL and REDIS_TLS* settings, which include TLS options. It depends on a Redis server and keeps state there.

What it does

managed client

Inputs

REDIS_URL, REDIS_TLS*

Depends on

Redis

State

Redis

Safeguards

TLS options

Embedding inference stack that tokenises text and runs ONNX to produce embeddings. Uses vendored model files, with model integrity checks, and sharp as a transitive dependency.

What it does

tokenise + ONNX

Inputs

text

Outputs

embeddings

Depends on

sharp (transitive), model files

State

vendored model files

Safeguards

model integrity

LLM provider SDK layer with adapter calls for OpenAI, Azure, Mistral, Llama and local/Ollama. The base adapter depends on node-fetch.

What it does

adapter calls (OpenAI, Azure, Mistral, Llama, local/Ollama)

Inputs

provider config

Outputs

provider responses

Depends on

node-fetch (base adapter)

Covers the validation, PDF and canonical JSON dependencies, which are listed as active parts of the build.

What it does

Active

Selects a KMS, HSM, Vault, Azure or GCP provider at boot through QODIQA_KMS_PROVIDER, for key wrap and sign. KEK and signing stay outside the process; 6 optional packages are needed.

What it does

provider selected at boot

Inputs

QODIQA_KMS_PROVIDER

Outputs

key wrap/sign

Depends on

6 optional packages

Safeguards

KEK/signing outside process

Optional enterprise identity support for authentication, using openid-client, node-saml and ldapts with IdP config to produce sessions.

Dependency audit gate that runs npm audit --json and filters results by exceptions that expire, so expiry forces review. It reads AUDIT_LEVEL, needs network, and exits 0, 1 or 2.

Lockfile integrity verification that runs integrity checks over node_modules and returns an exit code. It relies on the integrity hashes recorded in the lockfile.

What it does

integrity checks

Inputs

node_modules

Outputs

exit code

Safeguards

integrity hashes

Runs supply-chain checks over the lockfile that warn or fail and return an exit code. Setting SUPPLY_CHAIN_FAIL_ON_WARN makes warnings count as failures.

What it does

checks; warn/fail

Inputs

lockfile

Outputs

exit

Safeguards

SUPPLY_CHAIN_FAIL_ON_WARN

Generates a CycloneDX SBOM from node_modules and writes it to a file. The SBOM lists 367 components and follows spec version 1.5.

What it does

generate

Inputs

node_modules

Outputs

SBOM file (367 components; spec 1.5)

State

file

Licence artefacts kept as documents, including an LGPL disclosure as the listed safeguard for third-party licence terms.

Secret scanning in a hook and in CI using gitleaks with --exit-code=1 over git diff and history, with 7 custom rules and a report file. Needs gitleaks 8.x.

What it does

gitleaks --exit-code=1

Inputs

git diff/history

Depends on

gitleaks 8.x

State

report file

Safeguards

7 custom rules

Evidence-size guard that refuses staged files over 5 MiB or raw logger output, aborting the commit. A path list in .evidence-approvals is owner-approved.

What it does

refuse >5 MiB / raw logger output

Inputs

staged files,.evidence-approvals

Outputs

commit abort

Depends on

git

Safeguards

owner-approved path list

Prohibited-object push guard that checks reachability by object id for pushed SHAs and refuses the push. It blocks leaked-key and licence-restricted blobs using manifests.

What it does

reachability by object id

Inputs

pushed SHAs

Outputs

push refusal

Depends on

node

State

manifests under

Safeguards

blocks leaked-key / licence-restricted blobs

Gateway image build, multi-stage, from the repo context through an allow-list. Output is a qodiqa image: non-root 1000, root-owned code 0750, no npm, a forbidden-file gate and setuid strip. Base is a node:22-slim digest.

What it does

multi-stage; hardened user; setuid strip; content gate

Inputs

repo context via allow-list

Outputs

image qodiqa:*

Depends on

node:22-slim digest

State

image layers

Safeguards

non-root 1000, root-owned code 0750, no npm, forbidden-file gate, setuid strip

Build-context allow-list that excludes everything with * and then re-includes what is needed, producing a minimal context. Secrets are excluded at any depth.

What it does

* then re-includes

Outputs

minimal context

Safeguards

secrets excluded at any depth

Backup/DR image built on alpine 3.21 (pinned by digest) with the pg16 client. It passes the content gate and runs non-root.

What it does

alpine + pg16 client

Outputs

image

Depends on

alpine 3.21 digest

Safeguards

content gate, non-root

Image content gate that inspects the image filesystem for forbidden content, size and non-root user, given an image tag and --max-gb. It detects key, cert and env files and writes a JSON report; needs docker.

What it does

inspect image fs for forbidden content, size, non-root

Inputs

image tag, --max-gb

Outputs

JSON report

Depends on

docker

State

json out

Safeguards

key/cert/env detection

Production-profile container boot gate that boots the image with real TLS dependencies, passes the boot validator, checks /ready and makes a real decision. Result is JSON; needs docker.

What it does

boots image with real TLS deps, passes boot validator, /ready, a real decision

Inputs

image

Outputs

JSON

Depends on

docker

State

JSON artefact

Safeguards

production boot validator

Compose production reference with redis, postgres (TLS) and the gateway, hardened with read-only FS, cap_drop ALL, no-new-privileges, seccomp, TLS/mTLS Redis and pinned digests. Uses named volumes and .env variables.

What it does

redis+postgres(TLS)+gateway, hardened

Inputs

.env vars

Outputs

stack

Depends on

docker

State

named volumes

Safeguards

read-only FS, cap_drop ALL, no-new-privileges, seccomp, TLS/mTLS Redis, digests

Seccomp profiles that give containers a syscall allow-list in docker, so that only the listed system calls are permitted.

What it does

syscall allow-list

Depends on

docker

Safeguards

syscall filtering

Reverse-proxy example fragment for nginx that shows TLS termination in front of the gateway. It is only an example, not a deployed configuration.

What it does

example fragment

Depends on

nginx

Safeguards

TLS termination (example)

Caveat example

Kubernetes base with a namespace, SA, secret and configmap, PVC, default-deny NetworkPolicies and 8 backup CronJobs. Applies as k8s objects; PVCs hold state.

What it does

namespace, SA, secret/configmap, PVC, default-deny NetworkPolicies, 8 backup CronJobs

Outputs

objects

Depends on

k8s

State

PVCs

Safeguards

default-deny netpol

Single-node Kubernetes overlay that runs a StatefulSet with 1 replica on a PVC. Replicas 1 is the stated correctness bound.

What it does

StatefulSet x1

Outputs

objects

Depends on

k8s

State

PVC

Safeguards

replicas 1 correctness bound

Distributed Kubernetes overlay that runs a Deployment of 3 replicas plus a PDB, producing k8s objects. The boot validator refuses setups that do not meet its rules.

What it does

Deployment x3 + PDB

Outputs

objects

Depends on

k8s

Safeguards

boot validator refusal

Example Kubernetes overlays for hsm, vault-transit, external-secrets, monitoring and tls-ingress, applied as patches. They depend on k8s, vault, ESO and Prometheus.

What it does

patches

Outputs

objects

Depends on

k8s, vault, ESO, Prometheus

Root kustomization guard that is intentionally unbuildable, so building it from the root fails on purpose. This prevents an accidental deploy, and it relies on kubectl.

What it does

intentionally unbuildable

Outputs

fail

Depends on

kubectl

Safeguards

prevents accidental deploy

Helm chart with deployment, migrate-job, ingress, hpa, pdb, netpol and monitoring, producing a release. Defaults include netpol, apparmor and TLS; needs helm and k8s, with a PVC.

What it does

deployment, migrate-job, ingress, hpa, pdb, netpol, monitoring

Outputs

release

Depends on

helm, k8s

State

PVC

Safeguards

netpol, apparmor, TLS defaults

Terraform module with a kind example that creates a namespace, a secret and a helm_release from variables. The tf state is not present.

What it does

namespace, secret, helm_release

Inputs

variables

Outputs

release

Depends on

terraform, providers

State

tf state (not present)

Caveat tf state (not present)

Systemd backup units: 12 timers and services that write backups, using /etc/qodiqa/ as input. They run as user qodiqa and need bash and pg tools.

What it does

12 timers/services

Inputs

/etc/qodiqa/

Outputs

backups

Depends on

bash, pg tools

State

backup dirs

Safeguards

user qodiqa

Validates manifests against the production boot validator by running kustomize render, checks and a memory floor over k8s overlays and compose. Prints PASS or FAIL; uses the real validator, with optional --json.

What it does

kustomize render + + memory floor

Inputs

k8s overlays, compose

Outputs

PASS/FAIL list

Depends on

kubectl, js-yaml

State

optional --json

Safeguards

uses real validator

Generates and checks Grafana dashboards from the metrics registry, with the dashboards held as JSON files, as the generate and check steps.

What it does

generate/check

Inputs

metrics registry

Outputs

JSON

State

files

Public operations list that holds 23 operations. It is kept as a data file and provides the list as data output.

What it does

23 operations

Outputs

data

State

file

Main check pipeline of 26 jobs, run on push and PR, producing statuses and artefacts. Uses SHA-pinned actions and a least-privilege token; needs PG17, Redis7, docker and trivy.

What it does

26 jobs

Inputs

push/PR

Outputs

statuses, artefacts

Depends on

PG17, Redis7, docker, trivy

State

artefacts

Safeguards

SHA-pinned actions, least-privilege token

Acceptance job in CI that migrates the database and runs npm run acceptance, saving an evidence artefact. Depends on PG17.

What it does

migrate + npm run acceptance

Outputs

evidence artefact

Depends on

PG17

Backup and restore DR in CI that runs file, PG and distributed DR cycles on a daily cron and on push. Includes an encrypted backup variant and a KEK roundtrip; depends on PG15 and Redis7.

What it does

file + PG + distributed DR cycles

Inputs

cron daily + push

Depends on

PG15, Redis7

Safeguards

encrypted backup variant, KEK roundtrip

Three CI jobs that check for documentation drift, claims and specs equal to code. They depend on python.

What it does

3 jobs

Depends on

python

Kubernetes manifest validation in CI that does a kind dry-run and topology asserts, filtered by changed paths. Depends on kind.

What it does

kind dry-run; topology asserts

Inputs

path-filtered

Depends on

kind

Load-check gate in CI that runs perf lock-in checks and the load gate on pushes to main, producing an artefact report. Depends on PG and Redis.

What it does

perf lock-in checks + load gate

Inputs

push main

Outputs

report

Depends on

PG, Redis

State

artefact

Mutation testing with stryker over the 36 mutate: entries, run on cron or PR. Writes stryker-report/ and keeps an incremental cache.

What it does

stryker on the 36 mutate: entries

Inputs

cron / PR

Outputs

stryker-report/

Depends on

stryker

State

incremental cache

Scheduled daily security scans that run audit, secret-scan, sbom and dep-verify, with SARIF and dependency-graph output. The gitleaks sha256 is pinned.

What it does

audit, secret-scan, sbom, dep-verify

Inputs

cron daily

Outputs

SARIF/Dep graph

Depends on

gitleaks

Safeguards

pinned gitleaks sha256

Release gate triggered by a v* tag that reuses 6 workflows, then runs the image gate and creates a draft GH release. There is no auto-publish. Needs docker and trivy.

What it does

reuse 6 workflows then image gate then draft release

Inputs

tag v*

Outputs

draft GH release

Depends on

docker, trivy

State

release artefact

Safeguards

no auto-publish

Dependabot configuration that opens pull requests on a monthly schedule for dependency updates, and depends on GitHub.

Local CI substitute that does a fresh clone, runs the gates and compares a twice-built image for reproducibility. Input is a rev; evidence goes to a dir.

Component gate split that runs both halves independently, using a serial list of about 80 patterns against a parallel negative-lookahead. Reports PASS or FAIL per half and avoids catalog races; needs PG and Redis.

What it does

runs both halves independently; a ~80-pattern serial list vs parallel negative-lookahead

Outputs

PASS/FAIL per half

Depends on

PG, Redis

Safeguards

avoids catalog races

Preflight that checks Redis ping, PG migration state, Ollama, the keystore path and free RAM. Exits 0 or 1 with reasons.

What it does

checks Redis ping, PG migration state, Ollama, keystore path, free RAM

Inputs

env

Outputs

exit 0/1 with reasons

Depends on

redis, pg

Live-target guards that refuse live or same-as-source PG targets by raising an exception, which prevents writes to the live cluster.

What it does

refuse live/same-as-source targets

Inputs

PG target

Outputs

exception

Safeguards

prevents writes to the live cluster

Architecture constraints checked with depcruise: 9 rules with budgeted warnings over src, services and middleware, against a baseline. It enforces layering and returns an exit code.

What it does

9 rules, budgeted warnings

Inputs

src services middleware

Outputs

exit

Depends on

depcruise

State

baseline

Safeguards

layering enforcement

Lint and typecheck with a regression budget: eslint plus tsc with a per-file error budget, tracked in a baseline file. Returns an exit code.

What it does

eslint; tsc per-file error budget

Outputs

exit

Depends on

eslint, tsc

State

baseline file

Fuzzing with libFuzzer oracles, taking seconds and a corpus and keeping corpus files. The oracle is that an untrusted input never gives ok:true.

Documentation drift gates that map changes in code to the documentation updates they require. They compare docs and code and return an exit code.

What it does

map source→doc updates

Inputs

docs, source

Outputs

exit

OpenAPI generation and check: generates the spec from the route table, and --check detects drift between the spec and the code, keeping specs equal to code.

What it does

generate / --check drift

Inputs

route table

State

file

Safeguards

specs=code

Protocol vectors generated, then independently verified in JS and Python through cross-language verification. Vector files are written and the verifier is independent.

What it does

generate vectors, cross-language verify

Inputs

protocol

Outputs

vector files

Depends on

python

State

files

Safeguards

independent verifier

SDK to OpenAPI checks, static and live: extracts SDK HTTP calls, compares them to the spec, and runs live against a booted server. Returns an exit code.

What it does

extract SDK HTTP calls; compare; live run against booted server

Inputs

SDK sources, spec

Outputs

exit

Depends on

SDKs

Provisions and revokes signing identities out of band, issuing or revoking keys for an admin and writing to the key store. The admin plane may be off.

What it does

out-of-band key issue/revoke

Inputs

admin

Outputs

key store entries

Depends on

key store

State

key files

Safeguards

admin plane may be off

Caveat admin plane may be off

Issues the first admin API key for RBAC bootstrap, given the store path, and writes it to the RBAC store. The key is printed once, when it is issued.

What it does

issue first admin API key

Inputs

store path

Outputs

printed once

State

RBAC store

Offline key operations: rotates an expired artifact key, seals key files, archives public trust keys and runs KEK migrations. Production requires sealed key stores (OA-RC-2 per header).

What it does

rotate expired artifact key, seal key files, archive public trust keys, KEK migrations

Inputs

key stores

Outputs

updated files

State

key files

Safeguards

sealed key stores required in production (OA-RC-2 per header)

Audit-chain maintenance: re-sequences the mirror, seeds the chain head, exports NDJSON and makes incremental log backups. Changes DB and files in PG, with a live-target guard.

What it does

re-sequence mirror, seed chain head, export NDJSON, incremental log backup

Inputs

PG, audit log

Outputs

DB/file changes

Depends on

PG

State

PG

Safeguards

live-target guard

File to PG and control-plane migration that imports legacy JSON into PostgreSQL rows. The import is idempotent, so it can be run again safely.

What it does

idempotent import

Inputs

legacy JSON

Outputs

PG rows

Depends on

PG

State

PG

DR backup, restore, validate, verify and retention cycle covering file components plus PG (pg_dump layer, AUT-14/15), encryption, checksums and a manifest. Restores into a clean target, with encrypted archives (DD-005), a signed audit base check and a restore-target guard.

What it does

file components + PG (pg_dump layer, AUT-14/15) + encryption + checksums + manifest; restore into clean target; probes validate

Inputs

stores, PG

Outputs

backup dirs, metrics.prom

Depends on

PG tools

State

backups

Safeguards

encrypted archives (DD-005), signed audit base check, restore- target guard

PostgreSQL shell backups with full, incremental and verify tiers, WAL archive and audit-log backup, driven by env. Uses HMAC with optional encryption (DEP-12); needs pg_dump and openssl.

What it does

full/incremental/verify tiers, WAL archive, audit-log backup

Inputs

env

Outputs

files

Depends on

pg_dump etc., openssl

State

backup dir

Safeguards

HMAC + optional encryption (DEP-12)

Dev bootstrap and sandbox that creates an isolated ephemeral environment with a throwaway PG database and a sandbox provider, yielding a running gateway. An isolation guard (F17) applies.

What it does

isolated ephemeral env, throwaway PG DB, sandbox provider

Outputs

running gateway

Depends on

PG/Redis/ports

State

temp DB/dirs

Safeguards

isolation guard (F17)

Demo and e2e tooling that seeds a demo and runs a full-flow measurement with a stub or Ollama provider, writing evidence to <sha>/. A measure isolation check (S-03) applies.

What it does

seed demo; full-flow measurement with stub/Ollama provider

Outputs

<sha>/

Depends on

PG, Redis

State

evidence

Safeguards

measure isolation check S-03

Security tools that generate a route-guard table, privilege matrix, definer audit, anonymous sweep and publication gate. Verifies each route has a declared guard, applies a definer call-site policy, and refuses to publish secret-shaped content.

What it does

generated tables; checks

Inputs

live app / catalog

Outputs

evidence md

Depends on

PG for matrix

State

files

Safeguards

verifies each route has a declared guard; definer call-site policy; publish refusal on secret-shaped content

Semantic measurement harness that runs measurement blocks over frozen corpora using onnx models, and writes stdout and evidence. Frozen-set hashes guard the inputs.

What it does

measurement blocks

Inputs

frozen corpora

Outputs

stdout/evidence

Depends on

onnx models

State

evidence

Safeguards

frozen-set hashes

Fine-tune, export and fidelity tools and spikes, covering training, export and validation on a GPU pod or local venv. Datasets in, model files out; needs Python venvs.

What it does

training/export/validation (GPU pod or local venv)

Inputs

datasets

Outputs

model files

Depends on

Python venvs

State

model artefacts

Performance harnesses for load, latency, DB and Redis benchmarks that produce reports. They depend on a running PG and Redis.

What it does

load/latency/DB/Redis benchmarks

Outputs

reports

Depends on

PG, Redis

Public-export and scrub tooling that scrubs and verifies a curated public export from a tree into an export dir. Publication-policy checks apply; uses js-yaml.

What it does

scrub and verify a curated public export

Inputs

tree

Outputs

export dir

Depends on

js-yaml

Safeguards

publication-policy checks

Check-DB and temp cleanup sweep that enumerates orphan check DBs and directories in PG and temp, producing a candidate list. Deletion is governed elsewhere and not exercised.

What it does

enumerate orphan check DBs/dirs

Inputs

PG, temp

Outputs

candidate list

Depends on

PG

Safeguards

deletion governed by (not exercised)

Caveat deletion governed by (not exercised)

TLA+ model check that runs TLC (Java) and returns an exit code. The negative configs are expected to fail, and the run depends on Java.

What it does

TLC runs; negative configs must fail

Outputs

exit

Depends on

TLC (Java)

KMS/HSM emulator runners that start Vault dev, LocalStack and SoftHSM2 containers and run the adapters unmodified. Needs docker and stores evidence.

IdP and LDAP integration check that runs Dex v2.41.1 and OpenLDAP in docker, with the output written to the directory PLAN/verificare/F10-idp.

What it does

Dex v2.41.1 + OpenLDAP

Inputs

docker

Outputs

output dir PLAN/verificare/F10-idp

Depends on

docker

Reference external anchor witness that co-signs an anchor in another trust domain (mode exec), producing a signature from a separate trust domain.

What it does

co-sign in another trust domain (mode exec)

Inputs

anchor

Outputs

signature

Safeguards

separate trust domain

Independent audit reproduction kit that runs an independent chain verifier on evidence and reports pass or fail. Depends on python.

What it does

independent chain verifier

Inputs

evidence

Outputs

pass/fail

Depends on

python

Safeguards

independent re-verification

Boot-rules doc generator that reads the boot validator and generates a doc from it, and writes it out as a doc.

What it does

generates

Inputs

boot validator

Outputs

doc

State

doc