@kya-os/mcp 1.10.1 → 1.11.0

package/README.md

@@ -1,8 +1,8 @@
 <p align="center">
-  <a href="https://kya-os.ai">
+  <a href="https://kya-os.org">
     <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://kya-os.ai/mcp/images/logo-mark_white.svg">
-      <img alt="" src="https://kya-os.ai/mcp/images/logo-mark_black.svg" width="64">
+      <source media="(prefers-color-scheme: dark)" srcset="https://kya-os.org/mcp/images/logo-mark_white.svg">
+      <img alt="" src="https://kya-os.org/mcp/images/logo-mark_black.svg" width="64">
     </picture>
   </a>
 </p>
@@ -13,7 +13,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@kya-os/mcp"><img src="https://img.shields.io/npm/v/@kya-os/mcp" alt="npm"></a>
-  <a href="https://kya-os.ai/mcp"><img src="https://img.shields.io/badge/spec-KYA--OS-blue" alt="spec"></a>
+  <a href="https://kya-os.org/mcp"><img src="https://img.shields.io/badge/spec-KYA--OS-blue" alt="spec"></a>
   <a href="https://identity.foundation/working-groups/agent-and-authorization.html"><img src="https://img.shields.io/badge/DIF-TAAWG-purple" alt="DIF TAAWG"></a>
   <a href="./LICENSE"><img src="https://img.shields.io/github/license/decentralized-identity/kya-os-mcp" alt="license"></a>
 </p>
@@ -108,6 +108,46 @@ When an agent calls `checkout` without a delegation credential, it gets back a `
 
 ---
 
+## Turn proofs into a verifiable audit trail
+
+Detached proofs establish origin and bind request/response content. The
+`@kya-os/mcp/audit` service composes those proofs and the full authorization
+lifecycle into an atomically ordered, signed ledger with RFC 9162 checkpoints,
+independent observations, privacy-separated evidence, and offline replay
+bundles.
+
+```typescript
+import { withKyaOs, NodeCryptoProvider } from '@kya-os/mcp';
+import { createAuditTrail } from '@kya-os/mcp/audit';
+
+const audit = createAuditTrail({
+  recorder: checkpointRecorderClient, // or createLocalAuditRecorder(...)
+  delivery: 'required',
+  hasher,
+  ledgerId: 'kya:tenant-opaque:prod:primary',
+  expectedLedgerEpochId: 'epoch-2026-07',
+  tenantRef,
+  producer: pairwiseProducerRef,
+  sourceId: 'mcp-server-1',
+  binding: 'urn:kya-os:audit-binding:mcp:2025-11-25',
+  privacy: { classification: 'internal', retentionClass: 'audit-365d' },
+  clock: Date,
+});
+
+await withKyaOs(server, { crypto: new NodeCryptoProvider(), audit });
+```
+
+The MCP adapter records intent, terminal success/failure, denial/challenge,
+proof, delegation, authorization, and replay-rejection paths without copying raw
+tool arguments or response bodies. Delivery and assurance claims are explicit;
+unsafe high-assurance combinations fail at startup.
+
+See [AUDITABILITY.md](./AUDITABILITY.md) for the trust model, provider contracts,
+assurance profiles, Checkpoint integration, replay CLI, and production checklist.
+Run the local walkthrough with `npm run example:audit-trail`.
+
+---
+
 ## Typed, DID-anchored identity: the Entity Card
 
 Proofs answer *what an agent did*. The **Entity Card** answers *who is calling* — a typed, DID-anchored identity (`agent`, `mcp`, `client`, `verifier`, `human`) an entity publishes once and every discovery rail can index. It is claim-minimal: it asserts only identity, type, declared capabilities, and accountability locators. The trust **level** (L1/L2/L3) is never self-claimed — a verifier RECOMPUTES it from evidence. Three ergonomic calls, imported from the published `@kya-os/mcp/card` subpath:
@@ -165,6 +205,28 @@ This starts all example servers and opens [MCP Inspector](https://github.com/mod
 
 Also available: [outbound-delegation](./examples/outbound-delegation/) (gateway pattern), [verify-proof](./examples/verify-proof/) (standalone verification), [statuslist](./examples/statuslist/) (revocation lifecycle), [cheqd-dlr](./examples/cheqd-dlr/) (operator DID linkage + DLR publishing).
 
+## Try it against the live server
+
+[![Live deployment probe](https://github.com/decentralized-identity/kya-os-mcp/actions/workflows/live-probe.yml/badge.svg)](https://github.com/decentralized-identity/kya-os-mcp/actions/workflows/live-probe.yml)
+
+A public reference deployment runs the latest published release, with the identity `did:web:demo-mcp.kya-os.ai`.
+Every surface is a plain HTTPS fetch, so no privileged access is needed to check any claim it makes.
+
+| Surface | URL |
+|---------|-----|
+| MCP endpoint (streamable-http) | `https://demo-mcp.kya-os.ai/mcp` |
+| DID document | [/.well-known/did.json](https://demo-mcp.kya-os.ai/.well-known/did.json) |
+| Entity Card | [/card.json](https://demo-mcp.kya-os.ai/card.json) |
+| Revocation status list | [/status-list](https://demo-mcp.kya-os.ai/status-list) |
+| Exactly what is running | [/provenance](https://demo-mcp.kya-os.ai/provenance) |
+
+Connect [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to `https://demo-mcp.kya-os.ai/mcp`, call `vault_read`, and inspect the proof in `_meta`.
+Then verify that proof yourself with [examples/verify-proof](./examples/verify-proof/), which resolves the server's `did:web` over the public internet and checks the signature.
+A guided browser walkthrough of the same server (valid proof, tamper, replay, stolen key, live revocation, cross-language re-verification) runs at [poc.kya-os.ai](https://poc.kya-os.ai).
+
+The [daily probe](./.github/workflows/live-probe.yml) in CI performs those same read-only checks: it fetches the discovery surfaces, round-trips a real tool call over MCP, and verifies the returned proof against the publicly resolved DID.
+The server is operated by a maintainer on pinned releases; this repo does not deploy it, it independently verifies it.
+
 ---
 
 ## What's under the hood
@@ -177,6 +239,7 @@ Also available: [outbound-delegation](./examples/outbound-delegation/) (gateway
 | **Delegation credentials** | W3C Verifiable Credentials with scope constraints, rooted at a Responsible Party |
 | **Revocation** | StatusList2021 bitstring with cascading revocation |
 | **Replay prevention** | Nonce-based handshake with timestamp skew validation |
+| **Verifiable auditability** | Typed producer events, authoritative atomic recorder, signed chain receipts, RFC 9162 checkpoints, independent observation, encrypted evidence references, replay bundles, and offline CLI |
 | **Extensible** | Bring your own KMS, HSM, nonce cache (Redis, DynamoDB, KV), or DID method |
 
 ### Multi-instance deployments