AI gateway, providers, agents and tools

Mints an HMAC execution token using HMAC-SHA256 over a domain-separated message with a monotonic value. The token relies on a dedicated 256-bit secret and takes its time only from the server-side clock.

What it does

HMAC-SHA256 over domain-sep message with monotonic

Inputs

(64-hex)

Depends on

ARTIFACT_DOMAINS

Safeguards

dedicated 256-bit secret; server-side clock only

Verifies an execution token by checking its shape, TTL of 60s, future timestamps and an HMAC compare done in constant time. It never throws, and it fails closed if the secret cannot be read.

What it does

shape/TTL/future/HMAC compare, never throws

Inputs

ctx

Outputs

boolean

Depends on

same

Safeguards

fail-closed on secret error

Asserts the execution invariant before any dispatch, using 7 violation codes and writing a CRITICAL log before it throws UNVERIFIED_EXECUTION_ATTEMPT. In-memory counters track attempts, and the check binds structure and cryptography.

What it does

7 violation codes, CRITICAL log before throw

Outputs

throws UNVERIFIED_EXECUTION_ATTEMPT; counters

Depends on

logger

State

in-memory counters

Safeguards

structural + cryptographic binding

Provisions the execution secret from QODIQA_EXECUTION_INVARIANT_SECRET, validates it as 64-hex and caches it. It returns a Buffer(32) or throws, reads from the environment only, and is purpose-isolated from the KEK.

What it does

64-hex validation, cache

Inputs

QODIQA_EXECUTION_INVARIANT_SECRET

Outputs

Buffer(32) or throw

Depends on

env

State

env only

Safeguards

purpose-isolated from KEK

Resolves the KEK and scoped KEKs from environment variables, requiring 64-hex values. For scoped keys it rejects trivial repeating patterns, and it returns a Buffer.

What it does

64-hex, trivial-pattern rejection for scoped

Inputs

KEK env vars

Outputs

Buffer

Depends on

env

State

env

Safeguards

repeating-pattern rejection

Non-streaming execution entry: runs the invariant first, then a cancel check, a registry check and metadata, before handing the call to the router. It returns a normalized response.

What it does

invariant → cancel check → registry check → meta → router

Inputs

provider, body, ctx, signal

Outputs

normalized response

Depends on

router, providers shim

Safeguards

invariant first statement

Streaming execution entry built as an async generator that uses yield*. It takes the same inputs as the non-streaming entry, emits {delta} chunks and applies the same invariant.

What it does

async generator, yield*

Inputs

same

Outputs

{delta} chunks

Safeguards

same invariant

Shim that checks a provider name for membership in the router lists. It returns a boolean or the lists, and an unknown name gives PROVIDER_UNAVAILABLE.

What it does

membership in router lists

Inputs

name

Outputs

boolean/lists

Depends on

router

Safeguards

unknown name → PROVIDER_UNAVAILABLE

Holds the provider config table, allowlists and defaults, applying validity rules, additive extras and a load-time default assertion. Placeholder keys do not enable a provider, and boot fails on an inconsistent default.

What it does

validity rules, additive extras, load-time default assertion

Inputs

env

Outputs

frozen configs

State

env

Safeguards

placeholder keys don't enable; boot fails on inconsistent default

Parses timeout environment variables with a strict integer parse and returns milliseconds. An invalid value falls back to the default and logs a WARN.

What it does

strict int parse

Inputs

env name

Outputs

ms

Depends on

logger

State

env

Safeguards

invalid → default + WARN

Computes the output token cap as the minimum of the configured value and the artifact value, taken from env or a signed V2 artifact. The result is an integer or null.

What it does

min of both

Inputs

configured, artifact

Outputs

int/null

State

env/signed V2 artifact

Safeguards

caps output

Enforces the model allowlist with a shape check and Set membership. It returns ok or PROVIDER_MODEL_NOT_ALLOWED and is default-deny, except when the Set is empty.

What it does

shape + Set membership

Inputs

config, model

Outputs

ok/ PROVIDER_MODEL_NOT_ALLOWED

Depends on

config

Safeguards

default-deny except empty Set

Validates outbound messages against rules: up to 50 msgs, 32 KiB and allowed roles. It returns rejection codes for a body outside those payload bounds.

What it does

rules

Inputs

body

Outputs

rejection codes

Safeguards

payload bounds

Routes a provider call and fails over to another provider, returning a response or a PROVIDER_* error plus telemetry. Failover needs authorisation, an allowlist applies per hop, and at most 1 hop is made.

What it does

see C.3.2

Inputs

provider, body, meta, signal

Outputs

response or PROVIDER_* error; telemetry

Depends on

adapters, breaker, health, load, compat

State

in-memory

Safeguards

failover authorisation, allowlist per hop, 1 hop max

Gates failover by authorisation: without an authorizer the default is deny. It returns {ok} or a refusal, and it scopes the decision to caller consent and identity.

What it does

default-deny without authorizer

Outputs

{ok} / refusal with.

Depends on

logger

Safeguards

caller consent/identity scope

Routes streaming calls with failover, using native streaming or a single-chunk fallback. Failover is allowed only before any output, and is suppressed after the first chunk is accepted.

What it does

native or single-chunk fallback; failover only before any output

Inputs

same

Outputs

{delta}

Depends on

adapters, breaker

State

in-memory

Safeguards

failover suppressed after first chunk/accept

Circuit breaker with CLOSED, OPEN and HALF_OPEN states that lets one probe through. It counts failures, emits state transitions and INFO events, and fails fast, using a monotonic clock.

What it does

CLOSED/OPEN/HALF_OPEN, one probe

Inputs

counted failures

Outputs

state transitions, INFO events

Depends on

monotonic clock

State

per-process

Safeguards

fast-fail

Tracks provider health over a score window and flags degraded providers so calls skip them. The state is per-process, and it redirects early to a healthy failover target.

What it does

score window

Inputs

outcomes

Outputs

degraded flag

Depends on

env

State

per-process

Safeguards

early redirect to healthy failover

Keeps an in-flight load counter in a per-process map. It is fed by begin and track calls and read back with get(name).

What it does

counter map

Inputs

begin/track

Outputs

get(name)

State

per-process

Applies retry with backoff, making 1 retry only for a 429 or a no-response error. It returns the delay and emits events, which avoids double billing.

What it does

1 retry for 429 / no-response only

Inputs

error

Outputs

delay events

Safeguards

avoids double billing

Sets a per-call deadline and a stream idle deadline, aborting with PROVIDER_TIMEOUT when exceeded. It also bounds the body size to 8 MiB and applies a whole-call timeout.

What it does

abort + PROVIDER_TIMEOUT

Safeguards

bounded body size (8 MiB), whole-call timeout

Classifies provider errors through a mapping table, turning a raw error into a PROVIDER_* code. 4xx errors are not counted by the circuit breaker.

What it does

mapping table (C.3.3)

Inputs

raw error

Outputs

PROVIDER_* code

Safeguards

4xx not breaker-counted

Normalises provider responses: a string up to 4 MiB with no NUL and integer token counts. It returns a frozen response, and anything invalid becomes PROVIDER_INVALID_RESPONSE.

What it does

string ≤4 MiB, no NUL, int token counts

Inputs

parsed fields

Outputs

frozen response

Safeguards

invalid → PROVIDER_INVALID_RESPONSE

OpenAI non-streaming adapter built on the openai SDK. It takes a body and returns a normalized response, using a fixed base URL, a load-time SSRF assert and no redirects.

What it does

SDK

Inputs

body

Outputs

normalized

Depends on

openai pkg

Safeguards

fixed base URL, load-time SSRF assert, no redirects

OpenAI streaming adapter using the SDK stream, taking a body and returning deltas. It performs a terminal-signal check on the stream and shares the non-streaming adapter's dependency.

What it does

SDK stream

Inputs

body

Outputs

deltas

Depends on

same

Safeguards

terminal-signal check

Anthropic non-streaming adapter that calls /v1/messages through fetch. It takes a body and returns a normalized response, with a fixed URL and no redirects.

What it does

/v1/messages

Inputs

body

Outputs

normalized

Depends on

fetch

Safeguards

fixed URL, no redirects

Anthropic SSE streaming adapter with a custom SSE parser. It takes a body and returns deltas, maps error events, and requires message_stop to treat the stream as complete.

What it does

custom SSE parser

Inputs

body

Outputs

deltas, error events mapped

Depends on

fetch

Safeguards

message_stop required

Gemini adapter, marked Active, with no native stream. It takes a body and returns a normalized response through fetch, and checks the model path against a regex.

What it does

Active (no native stream)

Inputs

body

Outputs

normalized

Depends on

fetch

Safeguards

model path regex

Caveat no native stream

Mistral adapter, with streaming, that goes through the OpenAI SDK. It takes a body and returns a normalized response or deltas, and asserts the URL at load time.

What it does

OpenAI SDK

Inputs

body

Outputs

normalized/deltas

Depends on

openai pkg

Safeguards

load-time URL assert

Llama adapter, with streaming, that uses the OpenAI SDK against an operator URL. It takes a body and returns a normalized response or deltas, using a guarded agent.

What it does

OpenAI SDK vs operator URL

Inputs

body

Outputs

normalized/deltas

Depends on

openai pkg

Safeguards

guarded agent

Local, Ollama-compatible adapter, with streaming, that talks to an OpenAI-compatible endpoint. It returns a normalized response or deltas, using a guarded agent and an optional private-net block.

What it does

OpenAI-compatible endpoint

Inputs

body

Outputs

normalized/deltas

Depends on

openai pkg, ssrf

Safeguards

guarded agent, optional private-net block

Caveat optional private-net block

Azure OpenAI adapter, with streaming, built on the AzureOpenAI SDK. It takes a body and returns a normalized response or deltas, with a strict-public agent and a deployment-name regex.

What it does

AzureOpenAI SDK

Inputs

body

Outputs

normalized/deltas

Depends on

openai pkg

Safeguards

strict-public agent, deployment-name regex

Acquires an Azure Entra token with a client-credentials POST and caches it in memory. It reads AZURE_* env values, returns a bearer token, checks the token URL for SSRF and validates GUIDs.

What it does

client-credentials POST to, cache

Inputs

AZURE_* env

Outputs

bearer token

Depends on

fetch

State

memory cache

Safeguards

SSRF check on token URL, GUID validation

Bedrock Converse adapter that sends a SigV4 signed POST through fetch. It takes a body and returns a normalized response, with region and model regex checks and a host allowlist.

What it does

SigV4 signed POST

Inputs

body

Outputs

normalized

Depends on

fetch

Safeguards

region/model regex, host allowlist

Serves dynamic OpenAI-compatible providers with a per-name client cache, reading registry records from the control-plane collection. Safeguards are MAC integrity, key-to-host binding and a strict-public setting.

What it does

per-name client cache

Inputs

registry record

Outputs

normalized/deltas

Depends on

control plane

State

control-plane collection

Safeguards

MAC integrity, key↔host binding, strict-public

Guards provider URLs and addresses with an allowlist and an address policy. It checks URLs and resolved addresses, returns valid or refused plus a guarded agent, always blocks metadata and link-local addresses, and applies a rebinding guard.

What it does

allowlist + address policy

Inputs

URLs, resolved addresses

Outputs

valid/refused; guarded agent

Depends on

dns/net

Safeguards

metadata/link-local always blocked; rebinding guard

Composes two abort signals into a single signal through a linked controller. The function takes two signals as input and returns one combined signal as its output.

What it does

linked controller

Inputs

two signals

Outputs

signal

Canonicalises evidence packages and hashes them with SHA-256. Any input is reduced to one hash, because the safeguard is a single canonical form for every package.

What it does

+ SHA-256

Inputs

any

Outputs

hash

Safeguards

single canonical form

A shim that re-exports another module, so existing import paths keep working. It adds no behaviour of its own.

Accounts for tokens and cost with Prometheus counters and a normalised ranking. It takes tariffs and returns cost micros and a ranking, drawing on health and load, with state kept in metrics.

What it does

Prometheus counters; normalised ranking

Inputs

tariffs

Outputs

cost micros / ranking

Depends on

health, load

State

metrics

Routes by policy (cheapest, fastest, least-loaded or ordered) by ordering candidates and then authorising each. It reads ROUTING policies and the request, and returns provider, model and routed. Each candidate is authorised and checked against an allowlist.

What it does

candidate ordering + authorize

Inputs

ROUTING policies, request

Outputs

provider/model/routed

Depends on

ABAC cond, config, health, load

State

policies

Safeguards

per-candidate authorisation, allowlist

Canonicalises the AI-chat path by decoding and normalising a raw path into a route class. A path that cannot be decoded is treated as ai_chat.

What it does

decode/normalise

Inputs

raw path

Outputs

route class

Safeguards

undecodable → treated as ai_chat

Enforces the SSE lifecycle (C.5 steps 1-15) and emits SSE frames plus audit DECISION and COMMIT entries. It is fail-closed for INTENT and STREAM_OPENED, handles aborts, and relies on audit and transparency state.

What it does

C.5 steps 1-15

Inputs

res, req, artifact

Outputs

SSE frames, audit DECISION, COMMIT

Depends on

audit, transparency

State

audit chain, transparency

Safeguards

fail-closed INTENT/STREAM_OPENED, abort handling

Output check-then-release gate: runs a keyword check per delta and an embedding check per 400 characters or more, with a fail-closed timeout. No unchecked byte is released.

What it does

keyword per delta, embedding per ≥400 chars, fail-closed timeout

Inputs

deltas

Outputs

released text / block

Depends on

semantic engine

State

memory

Safeguards

no unchecked byte released

Keeps an active stream registry in memory as a map, with stream metadata in and ids and counts out. On shutdown it cancels streams with a graceful close that records a DECISION.

What it does

map

Inputs

stream meta

Outputs

ids, counts

State

memory

Safeguards

graceful close with DECISION

Cancels a stream when the client disconnects, aborting with 'client_disconnect' when the response emits 'close'. It writes a CLIENT_DISCONNECT record to audit, listening on the response (DD-019).

What it does

abort 'client_disconnect'

Inputs

res 'close'

Outputs

CLIENT_DISCONNECT record

State

audit

Safeguards

listens on response (DD-019)

Aborts a stream through a timer when the timeout env value elapses, and writes STREAM_TIMEOUT to audit. It is fail-closed.

What it does

timer abort

Inputs

env

Outputs

STREAM_TIMEOUT

State

audit

Safeguards

fail-closed

Makes a mandatory stream audit append with a retry reconciler, writing an audit entry and a transparency leaf. It keeps evidence even on failure, and includes a guard for unrepresentable text.

What it does

mandatory append, retry

Inputs

stream result

Outputs

audit entry, transparency leaf

Depends on

audit-log

State

audit chain / PG

Safeguards

evidence even on failure; unrepresentable-text guard

Normalises input on streams so that streamed content is handled in a consistent form before it is checked.

Validates a header value by checking its length and character set, within set bounds. It takes the header as input and returns either valid or a reason explaining the rejection.

What it does

length/charset

Inputs

header

Outputs

valid/reason

Safeguards

bounds

Computes a request fingerprint as a domain-separated SHA-256 over the tenant, key and provider values, and returns the result as a hex string for use in the request flow.

What it does

domain-sep SHA-256

Inputs

tenant/key/provider

Outputs

hex

Depends on

hashing

Safeguards

domain separation

Redis reservation store using SET NX PX, XX and DEL on key and fingerprint records. It fails closed when Redis is not ready, and keys are tenant-prefixed.

What it does

SET NX PX, XX, DEL

Inputs

key, fingerprint

Outputs

records

Depends on

Redis

State

Redis

Safeguards

fail-closed if not ready; tenant-prefixed key

Idempotency gate that handles replay, conflict and in-progress requests, polling up to 10 s against the store. It takes the request context and returns an outcome, mapped to 409 or 503.

What it does

poll up to 10 s

Inputs

request ctx

Outputs

outcome

Depends on

store

State

Redis

Safeguards

409/503 mapping

Builds the surface policies and chain, validated with zod across 34 surfaces. It reads env and tenant, user and key settings and returns a policy chain from validated config.

What it does

zod; 34 surfaces

Inputs

env, tenants/users/keys

Outputs

policy chain

Depends on

zod

State

env (+optional overrides)

Safeguards

validated config

Sliding-window rate limit using a Lua SW counter, with either fail-closed behaviour or an in-memory fallback when degraded. It returns 429 or allow per surface and raises a CRITICAL alert on degrade.

What it does

Lua SW counter; fail-closed or in-memory fallback

Inputs

request identity

Outputs

429 / allow

Depends on

Redis

State

Redis rl:v2

Safeguards

per-surface, CRITICAL alert on degrade

Manages agent identity and session records (CRUD) with validation and TTL and budget caps, stored in PG or memory. Safeguards are issued UUIDs and an optional Ed25519 key.

What it does

validation, TTL/budget caps

Inputs

spec

Outputs

records

Depends on

PG or memory

State

PG tables or memory

Safeguards

issued UUIDs, optional Ed25519 key

Verifies an Ed25519 agent request proof and returns a caller object. This gives a per-request proof of possession, so each request carries its own evidence from the calling agent.

What it does

Ed25519 verify

Inputs

proof

Outputs

caller object

Safeguards

per-request possession proof

Kill registry that aborts running tool calls in memory, taking controllers with labels and returning counts. The abort is immediate and local.

What it does

in-memory abort

Inputs

controllers+labels

Outputs

counts

State

memory

Safeguards

immediate local abort

Versioned tool registry with a pending-review flow (C.8.2), stored in PG or memory. It takes a spec and returns tool rows, using a schema-hash TOCTOU check and a self-approval ban.

What it does

C.8.2

Inputs

spec

Outputs

tool rows

Depends on

PG/memory

State

PG tool_registry

Safeguards

schema-hash TOCTOU, self-approval ban

Validates a value against a strict JSON-Schema subset with no regex support, returning ok or a path. The default is false.

What it does

strict subset, no regex

Inputs

schema, value

Outputs

ok/path

Safeguards

default false

Applies tool argument constraints for path, url, sql and command classes, default-deny per class. It returns ok or denied, and depends on ssrf checks.

What it does

default-deny per class

Inputs

tool, args

Outputs

ok/denied

Depends on

ssrf

Safeguards

default deny file/db/api/command

Computes a canonical action hash with JCS-P1 and a domain-separated SHA-256 over the action parts, returned as hex. The safeguards listed are domain separation and a chain.

Signs and verifies action artifacts with Ed25519 and a validity of 60 s, returning an artifact or a reason. Safeguards are tenant-to-key binding and a key timeline.

What it does

Ed25519, ≤60 s

Inputs

payload

Outputs

artifact / reason

Depends on

ed25519

Safeguards

tenant↔key binding, key timeline

Authorisation endpoint (C.8.3) that takes a body and returns a 200 artifact, a 202 pending or BLOCK. It uses agents, registry, plans, delegations, approvals, ABAC and DLP, is refusal-by-default and logs audit events.

What it does

C.8.3

Inputs

body

Outputs

200 artifact / 202 pending / BLOCK

Depends on

agents, registry, plans, delegations, approvals, ABAC, DLP

State

PG/memory + audit log events

Safeguards

refusal-by-default, DLP, ABAC

Manages plans with atomic step counting, stored in PG action_plans or memory. It takes steps and returns a plan, with a bounded number of steps.

What it does

atomic step counting

Inputs

steps

Outputs

plan

Depends on

PG action_plans /memory

State

PG/memory

Safeguards

bounded steps

Executor with a replay ledger that writes ACTION_INTENT and COMMIT audit entries (C.8.6 step 2). Each artifact is one-shot and the hash is recomputed, with state in PG action_executions or memory.

What it does

C.8.6 step 2

Inputs

artifact, tool, args

Outputs

execution, audit entries

Depends on

registry, agents, approvals, delegations, audit

State

PG action_executions / memory

Safeguards

one-shot artifact, hash recompute

Server registry with pinned identity and a config MAC-hash, validating and hashing a server spec into records. An https server requires an SPKI pin, and a tamper check applies.

What it does

validation, hash

Inputs

server spec

Outputs

records

Depends on

PG mcp_servers /memory

State

PG/memory

Safeguards

https requires SPKI pin, tamper check

Streamable-HTTP client using JSON-RPC and SSE with limits, applying connect-time SSRF and pin checks. It takes server, tool and args and returns a result, with no redirect and size and time caps.

What it does

JSON-RPC, SSE, limits

Inputs

server, tool, args

Outputs

result

Depends on

http/https

Safeguards

SSRF, pin, no redirect, size/time caps

Screens tool results with multi-variant regex and semantic and embedding engines for prompt-injection heuristics. It returns ALLOW with a delimiter or BLOCK, uses an untrusted delimiter and withholds non-text.

What it does

multi-variant regex + engines

Inputs

tool result

Outputs

ALLOW delimited / BLOCK

Depends on

semantic

Safeguards

untrusted delimiter, withheld non-text

Revocation watcher that polls every 1 s and aborts on a revocation. It takes ids and returns a stop function, giving cross-replica revocation within about 1 s.

What it does

1 s poll → abort

Inputs

ids

Outputs

stop fn

Depends on

registries, agents, delegations

Safeguards

cross-replica revocation within ≈1 s

Checks local model server availability with a GET against Ollama. The latest check lists 5 models available on the local server, recorded on 2026-10-27.

What it does

GET

Outputs

5 models listed (2026-10-27 07:39Z)

Depends on

Ollama

Caveat (2026-10-27 07:39Z)

Endpoint /v1/tools/call (C.8.6) that takes an artifact, tool and args and returns EXECUTE, BLOCK or ERROR with a receipt. It relies on the executor, mcp and DLP, with audit and ledger state.

What it does

C.8.6

Inputs

artifact, tool, args

Outputs

EXECUTE/BLOCK/ERROR + receipt

Depends on

executor, mcp*, DLP

State

audit + ledger

Safeguards

see C.8.6

Handles delegation chains: signed chains with attenuation and a revoke cascade, stored in PG(104) or memory. Safeguards are a depth cap and a cycle check.

What it does

signed chain, attenuation, revoke cascade

Inputs

request

Outputs

tokens

Depends on

PG(104)/memory

State

PG/memory

Safeguards

depth cap, cycle check

Runs human approval of tool actions as a state machine, producing signed approvals. It stores state in PG(106) or memory, uses webhooks and audit, and applies an independence rule and MFA step-up.

What it does

state machine

Inputs

request/decision

Outputs

signed approvals

Depends on

PG(106)/memory, webhooks, audit

State

PG/memory

Safeguards

independence rule, MFA step-up

Runs 8 portal checks over an artifact and produces a report as output. The logic is pure, so the checks have no side effects of their own.

What it does

8 checks

Inputs

artifact

Outputs

report

Safeguards

pure logic

Persists portal records to PG as rows, saving through a recovery queue so that a failed save can be recovered later instead of being lost, depending on PG.

What it does

PG save with recovery queue

Inputs

records

Outputs

rows

Depends on

PG

State

PG

MAC keyring that computes HMAC tags with an encrypted keystore held in a file. Safeguards are a KEK fingerprint, rotation, and no auto-generation in prod.

What it does

HMAC with encrypted keystore

Inputs

purpose, message

Outputs

tag/verify

Depends on

KEK

State

file

Safeguards

KEK fingerprint, rotation, prod no-autogen

API key lifecycle math covering TTL, grace and status, computed from key records and returning fields. It depends on env and applies a rotation grace.

What it does

TTL/grace/status

Inputs

key records

Outputs

fields

Depends on

env

Safeguards

rotation grace

Admin API for dynamic providers: register, update and compare. It takes a spec, returns JSON, keeps state in the control plane, and sits behind the admin stack with step-up.

What it does

register/update/compare

Inputs

spec

Outputs

JSON

State

control plane

Safeguards

admin stack + step-up