Audit Layer

The KYA-OS producer, recorder, checkpoint, and replay protocol

Security objective

The Audit Layer lets a verifier answer four separate questions:

  1. What did the producer claim happened? A versioned producer event captures the action, outcome, correlation, and evidence commitments.
  2. What did the recorder accept, and in what order? A recorder assigns epoch, sequence, time, predecessor digest, and a signed receipt.
  3. Can missing or conflicting history be detected? Source linkage, high-water reconciliation, and RFC 9162 checkpoints expose gaps and inconsistent views.
  4. Can another party verify the result later? A signed replay bundle carries entries, proofs, observations, anchors, and an explicit verification policy.

The event is not proof that an action occurred. It is a producer statement that becomes tamper-evident when accepted into a declared ledger scope.

Protocol flow

Loading diagram...

For managed deployments, Checkpoint is the recorder. Self-hosted deployments retain recorder authority and can use the same @kya-os/mcp/audit contracts and provider interfaces.

Producer event

The producer owns occurrence time, stable event identity, source ordering, correlation, action, outcome, and privacy classification. Sensitive detail belongs in encrypted evidence; the event contains only a commitment and reference.

{
  "schema": "https://schema.kya-os.org/v1/protocol/audit/event/v1.0.0",
  "eventId": "01K0AUDIT7Q9H8G6M5N4P3R2T1",
  "eventType": "tool.call.completed",
  "eventVersion": "1.0.0",
  "binding": "urn:kya-os:audit-binding:mcp",
  "occurredAt": 1784743200000,
  "tenantRef": {
    "kind": "keyed_commitment",
    "value": "sha256:13f6b08ac7ab2f5b7d91a0c85c71e606a440a96ac5d6b14e8134876460558d70",
    "keyId": "tenant-ref-2026-07"
  },
  "source": {
    "producer": { "kind": "public_did", "did": "did:web:tools.example" },
    "sourceId": "mcp-worker-us-central-1",
    "sourceSequence": "42",
    "previousSourceEventDigest": "sha256:64c9c50e3f755f66fbe74f1c41bd56f6d4ff2c88d47d4f461f4c44c358b3efea"
  },
  "correlationId": "mcp-request-8c2e",
  "action": { "category": "mcp.tool", "name": "customer.lookup" },
  "outcome": "succeeded",
  "authorization": {
    "source": "delegation",
    "decision": "allowed",
    "delegationRef": "urn:kya-os:delegation:7e43"
  },
  "evidence": [],
  "details": { "family": "tool", "phase": "completed", "attempt": "1" },
  "privacy": { "classification": "confidential", "retentionClass": "security-90d" }
}

The live schema is audit/event/v1.0.0. All protocol schemas are discoverable through the schema registry.

Recorder entry and receipt

The recorder authenticates the workload, derives tenant authority server-side, validates evidence before append, and atomically compares and appends against the current epoch head. It preserves:

  • exact canonical entry bytes and the signed envelope;
  • parsed JSON for inspection, never as the preservation format;
  • a unique logical event identity for idempotent retries;
  • epoch sequence and predecessor linkage;
  • recorder key identity and integrity suite.

The producer must verify the complete response before acknowledging delivery: event digest, entry digest, receipt digest, signature, ledger, epoch, and evidence manifest.

Checkpoints, observations, and replay

RFC 9162 checkpoints commit a ledger prefix to a Merkle root. Inclusion proofs show that an entry is in that prefix; consistency proofs show that a later checkpoint extends an earlier one. An independent observer can sign the checkpoint it saw, and optional WORM, RFC 3161, or SCITT receipts can anchor the checkpoint outside the recorder's trust boundary.

A replay bundle is a deterministic, signed inventory. It declares its selection range and marks each component as included, redacted, disposed, unavailable, or policy_excluded; omission is never silently treated as success. Verification produces independent verdicts for cryptographic integrity, chain integrity, checkpoints, anchors, scope completeness, authorization as observed, and current authorization.

Audit Assurance Profiles

KYA-OS reports the highest profile justified by healthy deployed mechanics:

ProfileClaim
AAP-0 · NoneNo audit assurance
AAP-1 · RecordedStructured capture of delivered instrumented events
AAP-2 · ChainedOrdered tamper-evident accepted history for a declared scope
AAP-3 · TransparentEfficient inclusion, consistency, and declared source-gap evidence
AAP-4 · ObservedConflicting observed views are detectable relative to independently known checkpoints

Profiles are derived, not configured labels. A deployment must fail closed if its advertised profile exceeds its delivery, durability, append, checkpoint, observation, anchor, or evidence capabilities.

Continue reading