Implementation Guide

Use the canonical exports from @kya-os/mcp/audit. Do not create a parallel event interface, hand-roll canonicalization, or accept recorder authority fields from producers.

npm install @kya-os/mcp@^1.11.0

Producer integration

Construct one AuditTrailService per durable source identity. Its configuration declares the recorder client, delivery mode, ledger, tenant and producer references, source ID, protocol binding, default privacy policy, hasher, clock, source-state provider, and optional durable outbox.

import {
  createAuditTrail,
  type AuditCapabilities,
  type AuditRecorderClient,
  type AuditSourceStateProvider,
} from "@kya-os/mcp/audit";

const capabilities: AuditCapabilities = {
  profile: "AAP-2",
  recorderTopology: "managed",
  delivery: "buffered",
  journalDurability: "durable",
  atomicAppend: true,
  sourceHighWater: false,
  merkleCheckpoints: false,
  independentObservation: false,
  supportingAnchors: [],
  evidenceRetention: "separate",
};

const audit = createAuditTrail({
  recorder,
  delivery: "buffered",
  hasher,
  ledgerId: "tenant-ledger",
  tenantRef,
  producer,
  sourceId: "mcp-worker-us-central-1",
  binding: "urn:kya-os:audit-binding:mcp",
  privacy: {
    classification: "confidential",
    retentionClass: "security-90d",
  },
  clock: { now: () => Date.now() },
  sourceState,
  outbox,
  capabilities,
});

Here recorder implements AuditRecorderClient; sourceState implements AuditSourceStateProvider; and a buffered production deployment supplies a durable AuditOutboxProvider. The constructor rejects assurance claims that exceed configured mechanics.

Record typed lifecycle events through audit.record(). Treat recorded, pending, and failed as distinct outcomes. For required delivery, do not perform the protected side effect unless the required audit intent has been accepted. Retrying a direct submission with the same event ID must also reuse the exact occurrence time and content; buffered retries already preserve frozen bytes.

Durable edge producer

For Cloudflare, use a dedicated SQLite Durable Object for audit source state and FIFO outbox. Do not share the object with MCP sessions, pickup, OAuth, delegation, or consent state. Give it a separate binding and migration, alarm-based retry with bounded backoff, and an observable dead-letter state.

Authorization or consent state transitions that require an audit intent should claim and enqueue in one local transaction. OAuth callback state should be leased and single-consumer so a replay cannot produce a second authorization or terminal event.

Recorder integration

An authoritative recorder must:

1. authenticate the workload and derive tenant and producer authority server-side;
2. bound body size and request rate before parsing expensive content;
3. validate canonical schemas and reject unknown fields;
4. persist and verify encrypted evidence before append;
5. atomically compare and append exact canonical entry bytes;
6. sign through a protected key service and return the complete signed entry;
7. make identical retries idempotent and divergent identity reuse a conflict;
8. write projections asynchronously and reconcile them against the journal.

AuditRecorderService, AuditJournalProvider, AuditEvidenceProvider, and the provider contract tests supply the portable core. Production adapters must preserve their concurrency, idempotency, and failure semantics.

Verify before acknowledgement

Remote producer clients must validate all of the following before deleting an outbox item:

• returned producer event equals the frozen submitted event;
• event, entry, evidence-manifest, and receipt digests recompute exactly;
• ledger and expected epoch match policy;
• sequence and predecessor are well formed;
• recorder signer and algorithm are authorized;
• the receipt signature is valid over canonical receipt bytes.

HTTP success alone is not an audit acknowledgement.

Checkpoints and replay

Use AuditCheckpointBuilder to create signed RFC 9162 checkpoints and inclusion or consistency proofs. Run checkpoint creation against a stable journal high-water mark. For AAP-4, send checkpoints to an independently operated observer and verify its signed observation chain.

Use AuditReplayBundleExporter for deterministic signed inventories and verifyAuditBundle for offline, policy-driven verification. Supply trust through AuditVerificationPolicyV1; never trust keys embedded only in the bundle.

Release gates

Before advertising the feature:

• validate runtime Zod, packaged JSON Schema, and hosted schema parity;
• exercise every start and terminal branch with golden events;
• run provider contract, concurrent append, idempotency, retry, restart, and crash-boundary tests;
• verify producer backpressure, outbox recovery, checkpoint proofs, observer conflict, evidence failure, restore, and key-transition scenarios;
• render unavailable and gap states in the UI;
• rehearse retention, legal hold, disposal, and incident runbooks;
• verify the live schema and documentation URLs after deployment.