@kya-os/verifier 1.5.9 → 1.6.1

package/README.md

@@ -191,14 +191,14 @@ The verifier performs comprehensive validation in the following order:
 
 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)
+- `KYA-Agent-DID`: Agent's decentralized identifier
+- `KYA-Agent-KeyId`: Key identifier used for signing
+- `KYA-Agent-Session`: Session identifier
+- `KYA-Agent-Confidence`: Always "verified" for successful verification
+- `KYA-Agent-Registry`: URL to agent's registry page for traceability
+- `KYA-Verified-At`: Unix timestamp of verification
+- `KYA-Agent-Scopes`: Comma-separated list of scopes (if present)
+- `KYA-Delegation-Ref`: Delegation reference (if present)
 
 ## Error Handling
 

package/dist/core.d.ts

@@ -0,0 +1,145 @@
+import type { DetachedProof } from "@kya-os/contracts/proof";
+import type { VerifierResult } from "@kya-os/contracts/verifier";
+/**
+ * Configuration for the verifier core
+ */
+export interface VerifierConfig {
+    /**
+     * KTA base URL for delegation checking
+     */
+    ktaBaseUrl?: string;
+    /**
+     * Enable delegation checking via KTA
+     */
+    enableDelegationCheck?: boolean;
+    /**
+     * Clock skew tolerance in seconds
+     */
+    clockSkewTolerance?: number;
+    /**
+     * Session timeout in seconds
+     */
+    sessionTimeout?: number;
+    /**
+     * Maximum age for proofs in seconds (prevents replay of old proofs)
+     */
+    proofMaxAge?: number;
+    /**
+     * Allow mock data for testing
+     */
+    allowMockData?: boolean;
+    /**
+     * Cache TTL for DID documents in seconds
+     */
+    didCacheTtl?: number;
+    /**
+     * Cache TTL for delegation status in seconds
+     */
+    delegationCacheTtl?: number;
+}
+/**
+ * Context for proof verification
+ */
+export interface VerificationContext {
+    proof: DetachedProof;
+    audience: string;
+    timestamp?: number;
+}
+/**
+ * Isomorphic verifier core for XMCP-I proof validation
+ *
+ * This is the heart of the trust system - it verifies that AI agents
+ * are who they claim to be and have the authority to perform actions.
+ */
+export declare class VerifierCore {
+    private config;
+    private didCache;
+    private delegationCache;
+    constructor(config?: VerifierConfig);
+    /**
+     * Verify a detached proof and return verification result
+     *
+     * This is the main entry point for proof verification. It performs
+     * a comprehensive validation of the agent's identity and authorization.
+     */
+    verify(context: VerificationContext): Promise<VerifierResult>;
+    /**
+     * Validate proof structure with comprehensive checks
+     */
+    private validateProofStructure;
+    /**
+     * Validate timestamp with configurable clock skew tolerance
+     */
+    private validateTimestamp;
+    /**
+     * Validate audience matches expected value
+     */
+    private validateAudience;
+    /**
+     * Verify Ed25519 signature using JOSE with proper detached JWS handling
+     *
+     * This is the cryptographic heart of the verification process.
+     * It ensures the proof was signed by the claimed identity.
+     *
+     * CRITICAL for full JWS: proof.meta must match the signed JWT payload.
+     * Otherwise an attacker could tamper with meta (audience, timestamp, nonce)
+     * while keeping a valid signature. We validate meta against the decoded
+     * payload before trusting meta for any security decisions.
+     */
+    private verifySignature;
+    /**
+     * Validate that proof.meta matches the decoded JWT payload.
+     * Required for full JWS to prevent meta tampering (audience, timestamp, nonce)
+     * while keeping a valid signature. Returns StructuredError on mismatch.
+     */
+    private validateMetaMatchesPayload;
+    /**
+     * Create canonical payload that matches runtime implementation
+     * Uses JSON Canonicalization Scheme (JCS) RFC 8785 for deterministic ordering
+     *
+     * CRITICAL: Must match the JWT payload structure used by proof generators.
+     * Generators use standard JWT claims (aud, sub, iss) plus custom claims.
+     */
+    private createCanonicalPayload;
+    /**
+     * Verify delegation status via KTA with caching
+     */
+    private verifyDelegation;
+    /**
+     * Validate delegation response
+     */
+    private validateDelegationResponse;
+    /**
+     * Fetch public key from DID document with caching
+     */
+    private fetchPublicKeyWithCache;
+    /**
+     * Fetch DID document from well-known endpoint
+     */
+    private fetchDIDDocument;
+    /**
+     * Extract public key from DID document
+     */
+    private extractPublicKey;
+    /**
+     * Generate trusted headers for successful verification
+     */
+    private generateHeaders;
+    /**
+     * Generate agent context for MCP recipients
+     */
+    private generateAgentContext;
+    /**
+     * Create error result from structured error
+     */
+    private createErrorResult;
+    /**
+     * Log verification attempt for security monitoring
+     */
+    private logVerificationAttempt;
+    /**
+     * Clean up expired cache entries
+     */
+    cleanupCache(): void;
+}
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAEA,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,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;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;IAavC;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IAqFnE;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAkG9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsFzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;;;;;;;;;OAUG;YACW,eAAe;IAuK7B;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAiHlC;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IA0B9B;;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"}