@kya-os/verifier 1.3.0

package/README.md

@@ -0,0 +1,265 @@
+# @kya-os/verifier
+
+Isomorphic verifier middleware for XMCP-I proof validation. This package provides the trust infrastructure for AI agent interactions by verifying agent identity, validating cryptographic proofs, and injecting trusted headers for downstream services.
+
+## Features
+
+- **Isomorphic Core**: Works in both Cloudflare Workers and Express environments
+- **Ed25519 Signature Verification**: Cryptographically secure proof validation using detached JWS
+- **DID Document Resolution**: Automatic resolution and caching of DID documents
+- **KTA Delegation Checking**: Integration with Know-That-AI for delegation verification
+- **Comprehensive Error Handling**: Structured errors with detailed remediation guidance
+- **Production-Ready Performance**: Built-in caching and optimization for edge deployment
+- **Security-First Design**: Comprehensive validation and audit logging
+
+## Installation
+
+```bash
+npm install @kya-os/verifier
+```
+
+## Quick Start
+
+### Cloudflare Worker
+
+```typescript
+import { verifyWorker, applyVerificationToResponse } from "@kya-os/verifier";
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const result = await verifyWorker(request, {
+      ktaBaseUrl: "https://knowthat.ai",
+      enableDelegationCheck: true,
+    });
+
+    if (!result.success) {
+      return applyVerificationToResponse(result);
+    }
+
+    // Agent is verified - process request
+    console.log("Verified agent:", result.agentContext?.did);
+    const response = await handleVerifiedRequest(request, result.agentContext);
+    return applyVerificationToResponse(result, response);
+  },
+};
+```
+
+### Express
+
+```typescript
+import express from "express";
+import {
+  verifyExpress,
+  isAuthenticated,
+  getAgentContext,
+} from "@kya-os/verifier";
+
+const app = express();
+
+// Apply verifier middleware
+app.use(
+  verifyExpress({
+    ktaBaseUrl: "https://knowthat.ai",
+    enableDelegationCheck: true,
+  })
+);
+
+app.post("/api/tools/call", (req, res) => {
+  if (!isAuthenticated(req)) {
+    return res.status(401).json({ error: "Not authenticated" });
+  }
+
+  const agent = getAgentContext(req);
+  console.log("Verified agent:", agent?.did);
+
+  // Handle tool call with verified agent context
+  res.json({ success: true, agent: agent?.did });
+});
+```
+
+## API Reference
+
+### Core Verifier
+
+#### `VerifierCore`
+
+The isomorphic core that handles proof verification logic.
+
+```typescript
+import { VerifierCore } from "@kya-os/verifier";
+
+const verifier = new VerifierCore({
+  ktaBaseUrl: "https://knowthat.ai",
+  enableDelegationCheck: true,
+  clockSkewTolerance: 120, // seconds
+  sessionTimeout: 1800, // seconds
+  allowMockData: false, // for testing only
+});
+
+const result = await verifier.verify({
+  proof: detachedProof,
+  audience: "example.com",
+  timestamp: Math.floor(Date.now() / 1000),
+});
+```
+
+#### Configuration Options
+
+- `ktaBaseUrl`: KTA base URL for delegation checking (default: "https://knowthat.ai")
+- `enableDelegationCheck`: Enable delegation verification (default: true)
+- `clockSkewTolerance`: Clock skew tolerance in seconds (default: 120)
+- `sessionTimeout`: Session timeout in seconds (default: 1800)
+- `allowMockData`: Allow mock data for testing (default: false)
+- `didCacheTtl`: DID document cache TTL in seconds (default: 300)
+- `delegationCacheTtl`: Delegation cache TTL in seconds (default: 60)
+
+### Cloudflare Worker Integration
+
+#### `verifyWorker(request, config?)`
+
+Verifies a Worker request and returns verification result.
+
+```typescript
+const result = await verifyWorker(request, {
+  ktaBaseUrl: "https://knowthat.ai",
+});
+
+if (result.success) {
+  // Access result.headers and result.agentContext
+} else {
+  // Handle result.error
+}
+```
+
+#### `applyVerificationToResponse(result, response?)`
+
+Applies verification result to a Response object.
+
+```typescript
+// Return error response
+if (!result.success) {
+  return applyVerificationToResponse(result);
+}
+
+// Apply headers to existing response
+const response = new Response("OK");
+return applyVerificationToResponse(result, response);
+```
+
+### Express Integration
+
+#### `verifyExpress(config?)`
+
+Express middleware for proof verification.
+
+```typescript
+app.use(
+  verifyExpress({
+    ktaBaseUrl: "https://knowthat.ai",
+    enableDelegationCheck: true,
+  })
+);
+```
+
+#### Helper Functions
+
+```typescript
+// Check if request is authenticated
+if (isAuthenticated(req)) {
+  // Request has verified agent
+}
+
+// Get agent context
+const agent = getAgentContext(req);
+if (agent) {
+  console.log("Agent DID:", agent.did);
+  console.log("Agent scopes:", agent.scopes);
+}
+```
+
+## Verification Process
+
+The verifier performs comprehensive validation in the following order:
+
+1. **Proof Structure Validation**: Validates JWS format and required metadata fields
+2. **Timestamp Validation**: Checks timestamp against configurable clock skew tolerance
+3. **Audience Validation**: Ensures proof audience matches request audience
+4. **Signature Verification**: Verifies Ed25519 signature using DID document public key
+5. **Delegation Checking**: Validates delegation status via KTA (if enabled and present)
+
+## Headers Injected
+
+On successful verification, the following headers are injected:
+
+- `X-Agent-DID`: Agent's decentralized identifier
+- `X-Agent-KeyId`: Key identifier used for signing
+- `X-Agent-Session`: Session identifier
+- `X-Agent-Confidence`: Always "verified" for successful verification
+- `X-Agent-Registry`: URL to agent's registry page for traceability
+- `X-Agent-Verified-At`: Unix timestamp of verification
+- `X-Agent-Scopes`: Comma-separated list of scopes (if present)
+- `X-Agent-Delegation-Ref`: Delegation reference (if present)
+
+## Error Handling
+
+The verifier returns structured errors with detailed information:
+
+```typescript
+{
+  success: false,
+  error: {
+    code: "XMCP_I_EBADPROOF",
+    message: "Invalid proof: malformed requestHash",
+    httpStatus: 400,
+    details: {
+      reason: "requestHash must be in format 'sha256:<64-char-hex>'",
+      expected: "sha256:[a-f0-9]{64}",
+      received: "invalid-hash",
+      remediation: "Check proof generation and hash format"
+    }
+  }
+}
+```
+
+### Error Codes
+
+- `XMCP_I_EBADPROOF`: Invalid or malformed proof
+- `XMCP_I_EHANDSHAKE`: Handshake validation failed (timestamp/audience)
+- `XMCP_I_ENOIDENTITY`: No proof found in request
+- `XMCP_I_EVERIFY`: Unexpected verification error
+
+## Security Considerations
+
+- **Clock Synchronization**: Ensure server clocks are synchronized (NTP recommended)
+- **HTTPS Only**: Always use HTTPS in production to protect proof transmission
+- **Cache Security**: DID documents and delegation status are cached with appropriate TTLs
+- **Error Information**: Error messages provide debugging information without leaking sensitive data
+- **Audit Logging**: All verification attempts are logged for security monitoring
+
+## Performance
+
+- **Caching**: DID documents and delegation responses are cached to reduce network calls
+- **Edge Optimization**: Designed for edge deployment with minimal cold start overhead
+- **Timeout Handling**: Network requests have appropriate timeouts to prevent hanging
+- **Memory Management**: Automatic cache cleanup prevents memory leaks
+
+## Testing
+
+The package includes comprehensive test coverage and supports mock data for testing:
+
+```typescript
+const verifier = new VerifierCore({
+  allowMockData: true, // Enables mock DIDs and delegations
+});
+
+// Mock DIDs: did:test:*
+// Mock delegations: mock:active, mock:revoked
+```
+
+## Contributing
+
+This package is part of the XMCP-I ecosystem. See the main repository for contribution guidelines.
+
+## License
+
+MIT

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAa,MAAM,yBAAyB,CAAC;AACxE,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,4BAA4B,CAAC;AAGpC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA6BD;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,QAAQ,CAAwC;IACxD,OAAO,CAAC,eAAe,CAAuC;gBAElD,MAAM,GAAE,cAAmB;IAYvC;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IAkFnE;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAkG9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAwBzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;;;;OAKG;YACW,eAAe;IAsJ7B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAwB9B;;OAEG;YACW,gBAAgB;IAwF9B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IA6ClC;;OAEG;YACW,uBAAuB;IAyBrC;;OAEG;YACW,gBAAgB;IAiD9B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiCxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAyBvB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAezB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAqB9B;;OAEG;IACI,YAAY,IAAI,IAAI;CAe5B"}