SDKs and developer interfaces

Builds the JS SDK client from QodiqaClientConfig, validating defaults, the URL, the ops key, the timeout and retry settings. The ops key must match ok_ followed by 64 hex.

What it does

defaults, URL/ops-key/timeout/retry validation

Inputs

QodiqaClientConfig

Outputs

resource graph or ValidationError

Safeguards

ops-key format check ok_ +64 hex

Selects the credential for each JS SDK call and sets the matching headers: Bearer ops, Bearer sign or x-qodiqa-artifact. It throws AuthenticationError if the credential is missing, keeping each credential separate.

What it does

Bearer ops / Bearer sign / x-qodiqa-artifact headers; throws AuthenticationError if missing

Inputs

config keys

Outputs

headers

Safeguards

per-credential separation

JS SDK HTTP request engine handling timeout, abort and JSON. One timer covers the request and its retries, AbortSignal is mirrored, and the body is deep-cloned. The caveat: no redirect or URL guard beyond new URL.

What it does

single timer over request+retries; AbortSignal mirroring; body

Inputs

RequestOptions

Outputs

parsed JSON/Uint8Array or typed error

Depends on

global fetch

Safeguards

body deep-cloned; no redirect/URL guard beyond new URL

Caveat no redirect/URL guard beyond new URL

Retry logic aware of method and path, honouring Retry-After. It backs off exponentially from 500 ms to 30 s with full jitter under a deadline cap, and never retries POST 5xx, chat 429, OTP or MFA_LOCKED.

What it does

exp back-off 500 ms..30 s full jitter; deadline cap; no POST 5xx retry; no chat 429 retry; OTP/MFA_LOCKED never

Inputs

errors

Outputs

retried call or error

Safeguards

avoids replaying consumed artifact nonces

Operator MFA step-up that resends the request once with an OTP header when the server answers MFA_REQUIRED. It never re-drives MFA_INVALID.

What it does

one resend with X-QODIQA-OTP on MFA_REQUIRED

Outputs

request result

Safeguards

never re-drives MFA_INVALID

Error taxonomy and server-envelope parsing: reads 3 envelope shapes plus Retry-After and a request id header from status, body and headers, and returns a typed QodiqaError subclass.

What it does

3 envelope shapes + Retry-After + X-Request-ID

Inputs

status + body + headers

Outputs

typed QodiqaError subclass

Streams chat over SSE with stream:true, parsing data frames. A truncated stream raises NetworkError, and an overload before streaming starts is resent; a consumed nonce is never resent.

What it does

stream:true; data-frame parser; truncation => NetworkError; pre-stream overload re-send

Inputs

artifact, ChatRequest, signal/timeout

Outputs

AsyncGenerator<ChatStreamEvent>

Depends on

fetch ReadableStream

Safeguards

no resend of consumed nonce

Chat create with idempotency. It checks that prompt or messages is given but not both, maps the response, and throws VerificationError when a BLOCK carries an artifact reason.

What it does

prompt XOR messages check; maps response ->; BLOCK with artifact reason => VerificationError

Inputs

artifact, request, {}

Outputs

ChatResponse

Calls POST /sign after checking that the method and path are non-empty. It sends a SignRequest, returns a SignResponse, and uses a per-identity sign key.

What it does

non-empty method/path check

Inputs

SignRequest

Outputs

SignResponse

Safeguards

per-identity sign key

Calls /verify, /verify/v2 and a dry-run variant, posting the artifact in the body. The SDK returns the server verdict, which the local verifier does not trust.

What it does

POST artifact in body

Inputs

VerifyRequest

Outputs

VerifyResponse

Safeguards

server verdict (not trusted by local verifier)

Portal verify and result calls, using POST and GET. They take an artifact or an id and return an ApiResponse.

What it does

POST/GET

Inputs

Artifact / id

Outputs

ApiResponse

Attestation client covering 9 endpoints: verify, evidence, chain, get, export, summary, list and stats. It takes ids and packages, returns ApiResponse, and the admin ones depend on an ops key.

What it does

9 endpoints

Inputs

ids, packages

Outputs

ApiResponse

Depends on

ops key for admin

Fetches an evidence package with a GET call, taking an id and returning an ApiResponse. It depends on an ops key.

What it does

GET

Inputs

id

Outputs

ApiResponse

Depends on

ops key

Transparency API wrapper using GET and POST with ids or params, returning an ApiResponse. The admin calls depend on an ops key.

What it does

GET/POST

Inputs

ids/params

Outputs

ApiResponse

Depends on

ops key for admin ones

Certification and batches calls using POST and GET. They take artifacts or ids, return an ApiResponse, and depend on an ops key.

What it does

POST/GET

Inputs

artifacts/ids

Outputs

ApiResponse

Depends on

ops key

Webhook management with CRUD, check, deliveries and metrics calls. Required inputs are validated, results return as ApiResponse, tenant scoping applies, and an ops key is needed.

What it does

CRUD + check + deliveries + metrics

Inputs

required

Outputs

ApiResponse

Depends on

ops key

Safeguards

tenant scoping

Policy simulation with 3 POST calls that use an ops key. They take requests and return results, so integrators can test policies without enforcing them.

What it does

3 POSTs (ops key)

Inputs

requests

Outputs

results

Depends on

ops key

Agents, sessions, actions, tools, delegations, tool-registry, MCP and approvals calls with validation, POST, GET and PATCH, plus polling. They return protocol-V2 objects; sign key for per-action calls, ops key plus MFA for admin.

What it does

validation + POST/GET/PATCH; and polling

Inputs

tenant/agent requests

Outputs

typed protocol-V2 objects

Depends on

sign key or ops key

Safeguards

sign key for per-action, ops+MFA for admin

Generic 364-operation client that validates calls from descriptors, picks the credential and dispatches stream or binary operations. It rejects unknown parameters and follows the contract's auth.

What it does

descriptor-driven validation, credential choice, stream/binary dispatch

Inputs

OperationArgs

Outputs

unknown / async generator

Depends on

http engine

Safeguards

unknown-parameter rejection; credential by contract auth

Webhook signature verification using HMAC-SHA256 over <ts>.<body>, with multiple signatures, secret rotation and a 300 s replay tolerance. Timestamps are parsed strictly as ISO-8601 UTC.

What it does

<ts>.<body> HMAC, multi-sig/secret rotation, ISO-8601 UTC parse, tolerance 300 s

Inputs

body, X-QODIQA-Signature, X-QODIQA-Timestamp, secret(s)

Outputs

void or typed error

Depends on

node:crypto

Safeguards

strict timestamp parse

Offline artifact verification through a 6-stage ladder. It takes an artifact and a KeyProvider, returns an ArtifactVerificationResult, uses Ed25519 with domain separation and fails closed on structure.

What it does

6-stage ladder (see 2.5)

Inputs

artifact, KeyProvider

Outputs

ArtifactVerificationResult

Depends on

node:crypto

Safeguards

Ed25519, domain separation, fail-closed on structure

Canonical JSON that normalises any JS value to a canonical string and rejects unsafe types and keys. It blocks forbidden prototype keys, excess depth and cycles.

What it does

normalize + reject unsafe types/keys

Inputs

any JS value

Outputs

canonical string

Depends on

fast-json-stable-stringify

Safeguards

forbidden prototype keys, depth, cycles

Key providers: static, remote with a cache, and an archived tier. The cache has a 300 s TTL, remote fetch times out at 10 s, and only active or deprecated keys verify.

What it does

TTL cache 300 s, 10 s fetch timeout, archived fallback

Inputs

key list / discovery URL

Outputs

ResolvedKey

Depends on

fetch

State

in-memory cache

Safeguards

only active/deprecated verify

Verifies transparency proofs and Merkle paths: entry hash, leaf index, position-bound path and the entry and root signatures. Transparency keys sit in a separate trust domain.

What it does

entry hash, leaf index, position-bound path, entry+root signatures

Inputs

proof, transparency key provider

Outputs

TransparencyVerificationDetail

Depends on

node:crypto

Safeguards

separate trust domain for transparency keys

Receipt verification and binding: checks the field set, the canonical signature and the revoked-key time rule. It is revocation-aware and depends on node:crypto.

What it does

field-set, canonical sig, revoked-key time rule

Inputs

receipt, keys

Depends on

node:crypto

Safeguards

revocation-aware

Checks an external-anchor line for key, format and digest, taking a JSONL line and returning an AnchorLineResult. The digest is recomputed.

What it does

key/format/digest check

Inputs

JSONL line

Outputs

AnchorLineResult

Safeguards

digest recompute

Request hash helper computing a domain-separated SHA-256 of method, path and body and returning hex, so the request can be bound to an artifact.

What it does

domain-separated SHA-256

Inputs

method,path,body

Outputs

hex

Artifact guard middleware that verifies the artifact and binds it to the request, taking req, res and next. It answers 401/403 JSON on rejection. Compares in constant time, caps header size and keeps no replay store.

Agent proof of possession: builds a digest and signs it, and generates keys. It takes a context and an Ed25519 key and returns a base64 signature or key pair, with domain separation.

What it does

digest + sign; key generation

Inputs

ctx, Ed25519 key

Outputs

base64 sig / key pair

Depends on

node:crypto

Safeguards

domain separation

Client convenience endpoints using GET with ids and returning typed results. An ops key is needed for audit.

What it does

GET

Inputs

ids

Outputs

typed results

Safeguards

ops key for audit

JS SDK build and packaging with tsup, producing ESM, CJS and type declarations into dist/ (untracked). It depends on tsup ^0.28.1.

What it does

tsup ESM+CJS+dts

Outputs

dist/ (untracked)

Depends on

tsup

Safeguards

^0.28.1

Python SDK sync and async client with frozen config. It validates kwargs, builds the resources and checks the ops key with a regex.

What it does

validation, resource construction

Inputs

kwargs

Outputs

clients

Depends on

httpx

Safeguards

ops-key regex

Python SDK HTTP engine with retry and OTP step-up: per-attempt timeout, the same retry policy as the JS SDK and one OTP resend. It applies the same replay-safety rules.

What it does

per-attempt timeout; same retry policy as JS; one OTP resend

Inputs

method,path,json

Outputs

parsed JSON or error

Depends on

httpx

Safeguards

same replay-safety rules

Python SDK streaming, sync and async: parses SSE, checks for truncation and resends after an overload before the stream starts. It takes an artifact, request and timeout and returns an iterator or async iterator.

What it does

SSE parse, truncation check, pre-stream overload resend

Inputs

artifact, request, timeout

Outputs

iterator / async iterator

Depends on

httpx

Python SDK exceptions and mapping, using the same taxonomy as the JS SDK plus SigningError, SerializationError and CryptoKeyError. It maps status and body to exceptions.

What it does

same taxonomy as JS plus SigningError/SerializationError/CryptoKeyError

Inputs

status/body

Outputs

exceptions

Python SDK resource methods for sign, chat, verify, portal, attestation, transparency, evidence, certification, webhooks and simulation. They validate input and encode path segments, which prevents path injection.

What it does

path-segment encoding, validation

Inputs

dict models

Outputs

dict results

Safeguards

segment encoding prevents path injection

Python SDK agents, actions and governance resources, with the same endpoints as the JS SDK plus authorize_and_wait(timeout_s,poll_s). They take dict requests and return dicts.

What it does

same endpoints as JS; authorize_and_wait(timeout_s,poll_s)

Inputs

dict requests

Outputs

dicts

Python SDK generic operation layer, sync and async, with the same validation as the JS SDK. It takes a name with path, query, body and headers, returns JSON or an iterator, and rejects unknown parameters.

What it does

same validation as JS; sync/async

Inputs

name + path/query/body/headers

Outputs

JSON / iterator

Safeguards

unknown-param rejection

Python SDK webhook verification, as in the JS SDK, with a 300 s tolerance. It uses hmac and returns None or an error.

What it does

as JS (tolerance 300 s)

Inputs

as JS

Outputs

None / error

Depends on

hmac

Python SDK offline verification of artifacts, transparency, receipts and anchors, sync and async, as in the JS SDK plus extra async classes. It uses Ed25519 and depends on cryptography and httpx.

What it does

as JS; extra async classes

Inputs

artifact, key provider

Outputs

results

Depends on

cryptography, httpx

Safeguards

Ed25519

Python port of canonical JSON that rejects non-integer floats. Keys use UTF-16 order and numbers are integer-only; forbidden keys, cycles and depth are rejected.

What it does

UTF-16 key order, integer-only numbers

Inputs

Python value

Outputs

string

Safeguards

forbidden keys, cycles, depth

Python artifact guard with FastAPI and Django middleware, as the JS guard, with a 1 MiB body cap. It returns a GuardResult or a 401, 403 or 413 response; fastapi and django are optional.

What it does

as JS guard; body cap 1 MiB

Inputs

request pieces

Outputs

GuardResult / 401/403/413

Depends on

fastapi/django optional

Caveat fastapi/django optional

Python agent proof using the same digest as the JS SDK. It takes a context and key and returns a base64 signature, with domain separation, and depends on cryptography.

What it does

same digest as JS

Inputs

ctx,key

Outputs

b64 sig

Depends on

cryptography

Safeguards

domain separation

Python pagination iterators, sync and async, that iterate over a fetcher and yield items one by one, so callers can walk paged results.

What it does

iteration

Inputs

fetcher

Outputs

items

Python SDK packaging with setuptools, producing a wheel as output. The build/ directory it writes is untracked.

What it does

setuptools

Outputs

wheel (untracked build/)

Go SDK generic operation client with retries, OTP and streaming. It validates descriptors, applies the context deadline over retries and caps responses at 64 MiB; it does not follow redirects and allows only http(s) without userinfo.

What it does

descriptor validation; context deadline over retries; response cap 64 MiB

Inputs

Config, CallArgs

Outputs

*Response / *EventStream / *Error

Depends on

stdlib, embedded

Safeguards

no redirects; http(s) w/o userinfo

Go SDK error classification into 13 kinds, with a 12-reason verification set. It takes a status and reason and returns an *Error.

What it does

13 kinds; 12-reason verification set

Inputs

status+reason

Outputs

*Error

Go SDK canonicalization and hashes using the protocol-V1 canonical form and the ES number format. It takes JSON and returns strings or bytes, rejecting forbidden keys and depth beyond 1000.

What it does

protocol-V1 canonical form (ES number format)

Inputs

JSON

Outputs

strings/bytes

Depends on

stdlib

Safeguards

forbidden keys, depth 1000

Go SDK artifact verifier with DecideArtifact and the transparency ladder, including lifecycle and time limits. It takes an artifact, keys and now, returns a result or Decision, and fails closed.

What it does

ladder + lifecycle/time limits

Inputs

artifact, keys, now

Outputs

result / Decision

Depends on

crypto/ed25519

Safeguards

fail-closed; panic-resistant per TestVerifierNeverPanicsOnHostileInput

Go live smoke program that runs sign, verify, chat, a generic op and the error map against a running gateway. It takes env URL and keys and prints PASS or FAIL lines.

What it does

sign, verify, chat, generic op, error map

Inputs

env URL+keys

Outputs

PASS/FAIL lines

Depends on

running gateway

Java SDK generic operation client with the same logic as the Go SDK, including the deadline over retries. It uses JDK HttpClient and Jackson, and returns Response, EventStream or QodiqaException.

What it does

same logic as Go; deadline over retries

Inputs

CallArgs

Outputs

Response / EventStream / QodiqaException

Depends on

JDK HttpClient, Jackson

Java SDK canonicalization, verification and transparency, as in the Go SDK. It takes a JsonNode, returns results and depends on JCA Ed25519.

What it does

as Go

Inputs

JsonNode

Outputs

results

Depends on

JCA Ed25519

Java live smoke program that makes gateway calls using the environment and writes to stdout. It needs a running gateway.

What it does

gateway calls

Inputs

env

Outputs

stdout

Depends on

running gateway

qodiqa-js relay that signs and then relays a request with the artifact header, handling timeout, cancel and retry; an enforced request goes only if opted in.

qodiqa-js retry, timeout, cancellation and errors: status-based back-off and typed errors such as RetryLimitExceededError. It never retries cancelled or timed-out calls.

What it does

status-based back-off; typed errors

Inputs

options

Outputs

RetryLimitExceededError etc.

Safeguards

never retries cancelled/timeout

qodiqa_py local Ed25519 signing, validation and request binding. Validation runs 14 steps, fails closed and allows 60 s of skew. It takes DER keys and envelopes, returns decision dicts, and compares in constant time.

What it does

14-step fail-closed validation incl. 60 s skew

Inputs

DER keys, envelopes

Outputs

decision dicts

Depends on

cryptography

Safeguards

domain separation; timing-safe compare

qodiqa_py canonical JSON, ordering keys by UTF-16 and following further canonicalisation rules. It takes a value and returns a string.

What it does

UTF-16 key order etc.

Inputs

value

Outputs

string

qodiqa_py HTTP client (QodiqaClient) using a urllib POST with a 10 s timeout and no retry. It parses error bodies into RequestError and relays the JSON from url, body and sign_token.

What it does

urllib POST, 10 s timeout, no retry, error body parse to RequestError

Inputs

url, body, sign_token

Outputs

relayed JSON

Depends on

urllib

The qodiqa CLI launcher with dev and help commands. It spawns the process, forwards signals and passes through the exit code, taking argv and depending on node.

What it does

spawn, signal forwarding, exit-code passthrough

Inputs

argv

Outputs

process

Depends on

node

The qodiqa dev command orchestrates a local sandbox: Redis and PG docker containers plus a sandbox provider. It prints a running gateway and keys, binds to loopback, uses a throw-away DB and removes provider keys.

What it does

Redis/PG docker containers, sandbox provider

Inputs

flags above

Outputs

running local gateway + keys printed

Depends on

Docker, node

State

tmpfs PG, temp dir

Safeguards

loopback binding; throw-away DB; provider keys removed

Operation table generator with a drift check (--check). It writes 4 generated files and 4 vector copies and embeds a hash of the contract.

Static check between the SDKs and OpenAPI, covering SC-1 to SC-4. It reads the SDK files and the contract, writes a JSON report, exits 1 on a violation and detects auth drift.

What it does

SC-1..SC-4

Inputs

SDK sources + contract

Outputs

JSON report, exit 1 on violation

State

optional --json file

Safeguards

auth-drift detection

Live contract and SDK probes that boot a real server and validate live responses against the schema. They write JSON evidence and need PG, Redis, a built dist and a Python venv.

What it does

schema validation of live responses; SDK probes

Inputs

boots real server

Outputs

JSON evidence

Depends on

PG, Redis, built dist, Python venv

State

evidence file

Artifact vectors: cross-language conformance data kept as a tracked file and consumed by the JS, Python, Go and Java checks.

What it does

cross-language conformance data

Outputs

consumed by JS/Py/Go/Java checks

State

tracked file

Webhook vectors with a drift check: regenerates and compares them, and overwrites the tracked vector file unless --signer is used. It takes a server signer and returns an exit code.

What it does

regenerate and compare; overwrite when not --signer

Inputs

server signer

Outputs

exit code

State

rewrites tracked vector file