Audit Overview

audit.svc (binary audit-svc.bin) is the kis.ai platform’s tamper-evident audit logging service. It is one binary, one subsystem, one HTTP listener: per-tenant, Merkle-tree-backed append-only logs with signed tree heads and RFC 6962 inclusion proofs, served over /submit, /head, /seal, /read, /inclusion-proof, and /logs. Background sealer, syncer, and anchorer workers keep heads fresh and durable.

Auth is a JWT bearer token plus an X-Tenant header — the chassis cross-checks the JWT tenant claim against the header. Per-tenant Ed25519 signing keys live in vault and are fetched on demand. There is no database: log state lives on disk under <base_dir>/<tenant>/<log_id>/.

Tenants and logs

Every operation is scoped by a (tenant, log_id) pair. Tenant always comes from the X-Tenant header (the chassis verifies it matches the JWT tenant claim); log_id always comes from the request body. On disk, a log lives at <base_dir>/<tenant>/<log_id>/. There is no pre-registration — logs are created on first /submit.

Append-only Merkle logs

Each submission is hashed into the leaf chain via SHA-256; the log’s current root is an RFC 6962 Merkle root. Sequences are dense, 0-indexed integers. The on-disk segment package is append-only and protected by a POSIX file lock — exactly one writer per log at a time.

Signed tree heads

Periodically (per the configured seal_interval), the sealer worker computes the current Merkle root and signs it with the tenant’s Ed25519 key. Consumers verify entries by combining an inclusion proof with a signed head; see the verification recipe in the HTTP API.

Signing keys in vault

Each tenant’s Ed25519 private key lives at a configurable vault path (audit.signer.vault_path_template, with {tenant} substituted). audit.svc fetches the key on first use for that tenant, parses it (PKCS#8 or raw PEM), and caches the in-memory signer. There is no per-call vault round-trip; rotation currently requires a service restart.

Background workers

Three workers run on tickers. The sealer forces fresh signed heads on the configured cadence, the syncer ships sealed segments to remote storage, and the anchorer posts heads to external transparency systems. All three have per-target exponential backoff (30 s → 1 h) and panic recovery, so one broken downstream never disables the others.

The HTTP API is the canonical description of what the binary serves — HTTP+JSON request/response shapes, status codes, headers, error format, multi-tenancy rules, and the verification recipe — and is derived from the same surface as the machine-readable OpenAPI contract. The authoritative architectural reference is the internal design spec; the docs here distill its operational and consumer-facing parts.

Continue with:

• Quickstart — five minutes from a JWT to your first verified record
• HTTP API — endpoint reference, error format, multi-tenancy rules, and the verification recipe
• Operations — deploy, configure, provision per-tenant vault keys, monitor, and recover (single-node SOP; HA is deferred)
• Platform Integration — architecture, package map, and extension points for maintaining or extending audit.svc
• End-to-End Testing — test layers, per-package recipes, and the curl + OpenAPI acceptance flow