@kya-os/verifier 1.3.0

package/dist/core.js

@@ -0,0 +1,678 @@
+import { importJWK, jwtVerify } from "jose";
+import { AGENT_HEADERS, ERROR_HTTP_STATUS } from "@kya-os/contracts/verifier";
+/**
+ * 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 class VerifierCore {
+    constructor(config = {}) {
+        this.didCache = new Map();
+        this.delegationCache = new Map();
+        this.config = {
+            ktaBaseUrl: config.ktaBaseUrl || "https://knowthat.ai",
+            enableDelegationCheck: config.enableDelegationCheck ?? true,
+            clockSkewTolerance: config.clockSkewTolerance ?? 120,
+            sessionTimeout: config.sessionTimeout ?? 1800, // 30 minutes
+            allowMockData: config.allowMockData ?? false,
+            didCacheTtl: config.didCacheTtl ?? 300, // 5 minutes
+            delegationCacheTtl: config.delegationCacheTtl ?? 60, // 1 minute
+        };
+    }
+    /**
+     * 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.
+     */
+    async verify(context) {
+        const startTime = Date.now();
+        try {
+            // 1. Validate proof structure
+            const structureError = this.validateProofStructure(context.proof);
+            if (structureError) {
+                this.logVerificationAttempt(context, false, structureError.code);
+                return this.createErrorResult(structureError);
+            }
+            // 2. Verify timestamp and session validity
+            const timestampError = this.validateTimestamp(context.proof.meta, context.timestamp);
+            if (timestampError) {
+                this.logVerificationAttempt(context, false, timestampError.code);
+                return this.createErrorResult(timestampError);
+            }
+            // 3. Verify audience matches
+            const audienceError = this.validateAudience(context.proof.meta, context.audience);
+            if (audienceError) {
+                this.logVerificationAttempt(context, false, audienceError.code);
+                return this.createErrorResult(audienceError);
+            }
+            // 4. Verify Ed25519 signature
+            const signatureError = await this.verifySignature(context.proof);
+            if (signatureError) {
+                this.logVerificationAttempt(context, false, signatureError.code);
+                return this.createErrorResult(signatureError);
+            }
+            // 5. Check delegation if enabled and present
+            if (this.config.enableDelegationCheck &&
+                context.proof.meta.delegationRef) {
+                const delegationError = await this.verifyDelegation(context.proof.meta.delegationRef, context.proof.meta.did, context.proof.meta.kid);
+                if (delegationError) {
+                    this.logVerificationAttempt(context, false, delegationError.code);
+                    return this.createErrorResult(delegationError);
+                }
+            }
+            // 6. Generate trusted headers and context
+            const headers = this.generateHeaders(context.proof.meta);
+            const agentContext = this.generateAgentContext(context.proof.meta);
+            const duration = Date.now() - startTime;
+            this.logVerificationAttempt(context, true, "SUCCESS", duration);
+            return {
+                success: true,
+                headers,
+                agentContext,
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            this.logVerificationAttempt(context, false, "UNEXPECTED_ERROR", duration);
+            return this.createErrorResult({
+                code: "XMCP_I_EVERIFY",
+                message: error instanceof Error ? error.message : "Verification failed",
+                httpStatus: 500,
+                details: {
+                    reason: "Unexpected error during verification",
+                    remediation: "Check proof format and try again",
+                },
+            });
+        }
+    }
+    /**
+     * Validate proof structure with comprehensive checks
+     */
+    validateProofStructure(proof) {
+        if (!proof.jws || typeof proof.jws !== "string") {
+            return {
+                code: "XMCP_I_EBADPROOF",
+                message: "Invalid proof: missing or invalid JWS",
+                httpStatus: 400,
+                details: {
+                    reason: "JWS field is required and must be a string",
+                    expected: "string",
+                    received: typeof proof.jws,
+                },
+            };
+        }
+        if (!proof.meta || typeof proof.meta !== "object") {
+            return {
+                code: "XMCP_I_EBADPROOF",
+                message: "Invalid proof: missing or invalid meta",
+                httpStatus: 400,
+                details: {
+                    reason: "Meta field is required and must be an object",
+                    expected: "object",
+                    received: typeof proof.meta,
+                },
+            };
+        }
+        const requiredFields = [
+            "did",
+            "kid",
+            "ts",
+            "nonce",
+            "audience",
+            "sessionId",
+            "requestHash",
+            "responseHash",
+        ];
+        for (const field of requiredFields) {
+            if (!proof.meta[field]) {
+                return {
+                    code: "XMCP_I_EBADPROOF",
+                    message: `Invalid proof: missing required field '${field}'`,
+                    httpStatus: 400,
+                    details: {
+                        reason: `Field '${field}' is required in proof meta`,
+                        expected: "non-empty value",
+                        received: proof.meta[field],
+                    },
+                };
+            }
+        }
+        // Validate hash format
+        const hashRegex = /^sha256:[a-f0-9]{64}$/;
+        if (!hashRegex.test(proof.meta.requestHash)) {
+            return {
+                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: proof.meta.requestHash,
+                },
+            };
+        }
+        if (!hashRegex.test(proof.meta.responseHash)) {
+            return {
+                code: "XMCP_I_EBADPROOF",
+                message: "Invalid proof: malformed responseHash",
+                httpStatus: 400,
+                details: {
+                    reason: "responseHash must be in format 'sha256:<64-char-hex>'",
+                    expected: "sha256:[a-f0-9]{64}",
+                    received: proof.meta.responseHash,
+                },
+            };
+        }
+        // Validate DID format
+        if (!proof.meta.did.startsWith("did:")) {
+            return {
+                code: "XMCP_I_EBADPROOF",
+                message: "Invalid proof: malformed DID",
+                httpStatus: 400,
+                details: {
+                    reason: "DID must start with 'did:'",
+                    expected: "did:*",
+                    received: proof.meta.did,
+                },
+            };
+        }
+        return null;
+    }
+    /**
+     * Validate timestamp with configurable clock skew tolerance
+     */
+    validateTimestamp(meta, currentTimestamp) {
+        const now = currentTimestamp || Math.floor(Date.now() / 1000);
+        const skew = this.config.clockSkewTolerance;
+        if (meta.ts < now - skew || meta.ts > now + skew) {
+            return {
+                code: "XMCP_I_EHANDSHAKE",
+                message: "Invalid proof: timestamp outside acceptable range",
+                httpStatus: 401,
+                details: {
+                    reason: `Timestamp ${meta.ts} is outside ±${skew}s window`,
+                    expected: `${now - skew} to ${now + skew}`,
+                    received: meta.ts,
+                    remediation: "Check NTP sync; adjust XMCP_I_TS_SKEW_SEC if needed",
+                },
+            };
+        }
+        return null;
+    }
+    /**
+     * Validate audience matches expected value
+     */
+    validateAudience(meta, expectedAudience) {
+        if (meta.audience !== expectedAudience) {
+            return {
+                code: "XMCP_I_EHANDSHAKE",
+                message: "Invalid proof: audience mismatch",
+                httpStatus: 401,
+                details: {
+                    reason: "Proof audience does not match request audience",
+                    expected: expectedAudience,
+                    received: meta.audience,
+                },
+            };
+        }
+        return null;
+    }
+    /**
+     * 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.
+     */
+    async verifySignature(proof) {
+        try {
+            // For testing with mock data, skip actual signature verification
+            if (this.config.allowMockData && proof.meta.did.startsWith("did:test:")) {
+                // Parse JWS components for basic validation
+                const jwsParts = proof.jws.split(".");
+                if (jwsParts.length !== 3 || jwsParts[1] !== "") {
+                    return {
+                        code: "XMCP_I_EBADPROOF",
+                        message: "Invalid detached JWS format",
+                        httpStatus: 403,
+                        details: {
+                            reason: "Detached JWS must have format 'header..signature'",
+                            expected: "header..signature",
+                            received: `${jwsParts.length} parts, payload: '${jwsParts[1]}'`,
+                        },
+                    };
+                }
+                const [headerB64] = jwsParts;
+                const header = JSON.parse(Buffer.from(headerB64, "base64url").toString());
+                if (header.alg !== "EdDSA") {
+                    return {
+                        code: "XMCP_I_EBADPROOF",
+                        message: "Invalid JWS: unsupported algorithm",
+                        httpStatus: 403,
+                        details: {
+                            reason: "Only EdDSA algorithm is supported",
+                            expected: "EdDSA",
+                            received: header.alg,
+                        },
+                    };
+                }
+                if (header.kid !== proof.meta.kid) {
+                    return {
+                        code: "XMCP_I_EBADPROOF",
+                        message: "Invalid JWS: key ID mismatch",
+                        httpStatus: 403,
+                        details: {
+                            reason: "JWS header kid must match proof meta kid",
+                            expected: proof.meta.kid,
+                            received: header.kid,
+                        },
+                    };
+                }
+                // Mock signature verification passes for test DIDs
+                return null;
+            }
+            // Parse JWS components - detached JWS has format: header..signature
+            const jwsParts = proof.jws.split(".");
+            if (jwsParts.length !== 3 || jwsParts[1] !== "") {
+                return {
+                    code: "XMCP_I_EBADPROOF",
+                    message: "Invalid detached JWS format",
+                    httpStatus: 403,
+                    details: {
+                        reason: "Detached JWS must have format 'header..signature'",
+                        expected: "header..signature",
+                        received: `${jwsParts.length} parts, payload: '${jwsParts[1]}'`,
+                    },
+                };
+            }
+            const [headerB64, , signatureB64] = jwsParts;
+            // Parse and validate header
+            const header = JSON.parse(Buffer.from(headerB64, "base64url").toString());
+            if (header.alg !== "EdDSA") {
+                return {
+                    code: "XMCP_I_EBADPROOF",
+                    message: "Invalid JWS: unsupported algorithm",
+                    httpStatus: 403,
+                    details: {
+                        reason: "Only EdDSA algorithm is supported",
+                        expected: "EdDSA",
+                        received: header.alg,
+                    },
+                };
+            }
+            if (header.kid !== proof.meta.kid) {
+                return {
+                    code: "XMCP_I_EBADPROOF",
+                    message: "Invalid JWS: key ID mismatch",
+                    httpStatus: 403,
+                    details: {
+                        reason: "JWS header kid must match proof meta kid",
+                        expected: proof.meta.kid,
+                        received: header.kid,
+                    },
+                };
+            }
+            // Fetch public key from DID document with caching
+            const publicKey = await this.fetchPublicKeyWithCache(proof.meta.did, proof.meta.kid);
+            if (!publicKey) {
+                return {
+                    code: "XMCP_I_EBADPROOF",
+                    message: "Unable to resolve public key",
+                    httpStatus: 403,
+                    details: {
+                        reason: "Could not fetch public key from DID document",
+                        remediation: "Ensure DID document is accessible and contains the key",
+                    },
+                };
+            }
+            // Create canonical payload for detached signature verification
+            // This MUST match the exact format used by the runtime
+            const canonicalPayload = this.createCanonicalPayload(proof.meta);
+            const payloadB64 = Buffer.from(canonicalPayload, "utf8").toString("base64url");
+            // Reconstruct complete JWS for verification
+            const completeJWS = `${headerB64}.${payloadB64}.${signatureB64}`;
+            // Verify signature using JOSE
+            const jwk = await importJWK(publicKey);
+            await jwtVerify(completeJWS, jwk, {
+                algorithms: ["EdDSA"],
+            });
+            return null;
+        }
+        catch (error) {
+            return {
+                code: "XMCP_I_EBADPROOF",
+                message: "Signature verification failed",
+                httpStatus: 403,
+                details: {
+                    reason: error instanceof Error ? error.message : "Unknown error",
+                    remediation: "Check proof signature and public key",
+                },
+            };
+        }
+    }
+    /**
+     * Create canonical payload that matches runtime implementation
+     * Uses JSON Canonicalization Scheme (JCS) for deterministic ordering
+     */
+    createCanonicalPayload(meta) {
+        // Create payload object with exact field ordering as runtime
+        const payload = {
+            audience: meta.audience,
+            nonce: meta.nonce,
+            requestHash: meta.requestHash,
+            responseHash: meta.responseHash,
+            sessionId: meta.sessionId,
+            ts: meta.ts,
+        };
+        // Add optional fields in canonical order
+        if (meta.scopeId) {
+            payload.scopeId = meta.scopeId;
+        }
+        if (meta.delegationRef) {
+            payload.delegationRef = meta.delegationRef;
+        }
+        // Use JSON.stringify with sorted keys for canonicalization
+        // This implements a simplified JCS - for production, consider using a proper JCS library
+        return JSON.stringify(payload, Object.keys(payload).sort());
+    }
+    /**
+     * Verify delegation status via KTA with caching
+     */
+    async verifyDelegation(delegationRef, did, keyId) {
+        try {
+            // Check cache first
+            const cached = this.delegationCache.get(delegationRef);
+            if (cached && cached.expiresAt > Date.now()) {
+                return this.validateDelegationResponse(cached.response, did, keyId);
+            }
+            if (this.config.allowMockData) {
+                // Mock delegation for testing
+                if (delegationRef.startsWith("mock:")) {
+                    const mockResponse = {
+                        active: delegationRef !== "mock:revoked",
+                        did,
+                        keyId,
+                        scopes: ["*"],
+                    };
+                    return this.validateDelegationResponse(mockResponse, did, keyId);
+                }
+                // For other delegation refs in test mode, assume they're valid
+                const mockResponse = {
+                    active: true,
+                    did,
+                    keyId,
+                    scopes: ["*"],
+                };
+                return this.validateDelegationResponse(mockResponse, did, keyId);
+            }
+            const response = await fetch(`${this.config.ktaBaseUrl}/api/v1/delegations/${encodeURIComponent(delegationRef)}`, {
+                method: "GET",
+                headers: {
+                    "Content-Type": "application/json",
+                    "User-Agent": "XMCP-I-Verifier/1.0",
+                },
+                // Add timeout for production reliability
+                signal: AbortSignal.timeout(5000),
+            });
+            if (!response || !response.ok) {
+                if (response && response.status === 404) {
+                    return {
+                        code: "XMCP_I_EBADPROOF",
+                        message: "Delegation not found",
+                        httpStatus: 403,
+                        details: {
+                            reason: "Delegation reference not found in KTA",
+                            remediation: "Check delegation reference and ensure it exists",
+                        },
+                    };
+                }
+                throw new Error(`KTA API error: ${response.status}`);
+            }
+            const delegation = (await response.json());
+            // Cache the response
+            this.delegationCache.set(delegationRef, {
+                response: delegation,
+                expiresAt: Date.now() + this.config.delegationCacheTtl * 1000,
+            });
+            return this.validateDelegationResponse(delegation, did, keyId);
+        }
+        catch (error) {
+            // Treat delegation check failures as verification failures
+            console.warn("Delegation verification failed:", error);
+            return {
+                code: "XMCP_I_EBADPROOF",
+                message: "Delegation verification failed",
+                httpStatus: 403,
+                details: {
+                    reason: error instanceof Error ? error.message : "Unknown error",
+                    remediation: "Check KTA connectivity and delegation status",
+                },
+            };
+        }
+    }
+    /**
+     * Validate delegation response
+     */
+    validateDelegationResponse(delegation, expectedDid, expectedKeyId) {
+        if (!delegation.active) {
+            return {
+                code: "XMCP_I_EBADPROOF",
+                message: "Delegation revoked or inactive",
+                httpStatus: 403,
+                details: {
+                    reason: "Delegation is not active",
+                    remediation: "Renew delegation or use direct identity",
+                },
+            };
+        }
+        if (delegation.did !== expectedDid || delegation.keyId !== expectedKeyId) {
+            return {
+                code: "XMCP_I_EBADPROOF",
+                message: "Delegation identity mismatch",
+                httpStatus: 403,
+                details: {
+                    reason: "Delegation does not match proof identity",
+                    expected: `${expectedDid}#${expectedKeyId}`,
+                    received: `${delegation.did}#${delegation.keyId}`,
+                },
+            };
+        }
+        if (delegation.expiresAt && delegation.expiresAt < Date.now() / 1000) {
+            return {
+                code: "XMCP_I_EBADPROOF",
+                message: "Delegation expired",
+                httpStatus: 403,
+                details: {
+                    reason: "Delegation has expired",
+                    remediation: "Renew delegation",
+                },
+            };
+        }
+        return null;
+    }
+    /**
+     * Fetch public key from DID document with caching
+     */
+    async fetchPublicKeyWithCache(did, keyId) {
+        const cacheKey = `${did}#${keyId}`;
+        const cached = this.didCache.get(cacheKey);
+        if (cached && cached.expiresAt > Date.now()) {
+            return this.extractPublicKey(cached.document, keyId);
+        }
+        const didDoc = await this.fetchDIDDocument(did);
+        if (!didDoc) {
+            return null;
+        }
+        // Cache the DID document
+        this.didCache.set(cacheKey, {
+            document: didDoc,
+            expiresAt: Date.now() + this.config.didCacheTtl * 1000,
+        });
+        return this.extractPublicKey(didDoc, keyId);
+    }
+    /**
+     * Fetch DID document from well-known endpoint
+     */
+    async fetchDIDDocument(did) {
+        try {
+            if (this.config.allowMockData && did.startsWith("did:test:")) {
+                // Mock DID document for testing
+                return {
+                    id: did,
+                    verificationMethod: [
+                        {
+                            id: `#key-test-1`,
+                            type: "Ed25519VerificationKey2020",
+                            controller: did,
+                            publicKeyJwk: {
+                                kty: "OKP",
+                                crv: "Ed25519",
+                                x: "mock-public-key-data",
+                            },
+                        },
+                    ],
+                };
+            }
+            // Convert DID to well-known URL for did:web
+            if (!did.startsWith("did:web:")) {
+                throw new Error("Only did:web is supported");
+            }
+            const domain = did.replace("did:web:", "").replace(/:/g, "/");
+            const didDocUrl = `https://${domain}/.well-known/did.json`;
+            const response = await fetch(didDocUrl, {
+                headers: {
+                    Accept: "application/did+json, application/json",
+                    "User-Agent": "XMCP-I-Verifier/1.0",
+                },
+                // Add timeout for production reliability
+                signal: AbortSignal.timeout(5000),
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch DID document: ${response.status}`);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            console.warn("Failed to fetch DID document:", error);
+            return null;
+        }
+    }
+    /**
+     * Extract public key from DID document
+     */
+    extractPublicKey(didDoc, keyId) {
+        try {
+            // Find verification method
+            const verificationMethod = didDoc.verificationMethod?.find((vm) => vm.id === `#${keyId}` || vm.id === `${didDoc.id}#${keyId}`);
+            if (!verificationMethod) {
+                throw new Error(`Key ${keyId} not found in DID document`);
+            }
+            // Convert to JWK format if needed
+            if (verificationMethod.publicKeyJwk) {
+                return verificationMethod.publicKeyJwk;
+            }
+            if (verificationMethod.publicKeyMultibase) {
+                // Convert multibase to JWK (simplified for Ed25519)
+                // This is a placeholder - real implementation would use proper multibase decoding
+                return {
+                    kty: "OKP",
+                    crv: "Ed25519",
+                    x: verificationMethod.publicKeyMultibase.slice(1), // Remove multibase prefix
+                };
+            }
+            throw new Error("Unsupported public key format");
+        }
+        catch (error) {
+            console.warn("Failed to extract public key:", error);
+            return null;
+        }
+    }
+    /**
+     * Generate trusted headers for successful verification
+     */
+    generateHeaders(meta) {
+        const headers = {
+            [AGENT_HEADERS.DID]: meta.did,
+            [AGENT_HEADERS.KEY_ID]: meta.kid,
+            [AGENT_HEADERS.SESSION]: meta.sessionId,
+            [AGENT_HEADERS.CONFIDENCE]: "verified",
+            [AGENT_HEADERS.VERIFIED_AT]: Math.floor(Date.now() / 1000).toString(),
+        };
+        if (meta.scopeId) {
+            headers[AGENT_HEADERS.SCOPES] = meta.scopeId;
+        }
+        if (meta.delegationRef) {
+            headers[AGENT_HEADERS.DELEGATION_REF] = meta.delegationRef;
+        }
+        // Add registry URL for traceability
+        headers[AGENT_HEADERS.REGISTRY] = `${this.config.ktaBaseUrl}/agents/${encodeURIComponent(meta.did)}`;
+        return headers;
+    }
+    /**
+     * Generate agent context for MCP recipients
+     */
+    generateAgentContext(meta) {
+        return {
+            did: meta.did,
+            keyId: meta.kid,
+            subject: meta.delegationRef ? meta.did : undefined,
+            scopes: meta.scopeId ? meta.scopeId.split(",") : [],
+            session: meta.sessionId,
+            confidence: "verified",
+            delegationRef: meta.delegationRef,
+            registry: `${this.config.ktaBaseUrl}/agents/${encodeURIComponent(meta.did)}`,
+            verifiedAt: Math.floor(Date.now() / 1000),
+        };
+    }
+    /**
+     * Create error result from structured error
+     */
+    createErrorResult(error) {
+        return {
+            success: false,
+            error: {
+                code: error.code,
+                message: error.message,
+                details: error.details,
+                httpStatus: error.httpStatus ||
+                    ERROR_HTTP_STATUS[error.code] ||
+                    500,
+            },
+        };
+    }
+    /**
+     * Log verification attempt for security monitoring
+     */
+    logVerificationAttempt(context, success, reason, duration) {
+        // In production, this would integrate with your logging system
+        const logEntry = {
+            timestamp: new Date().toISOString(),
+            did: context.proof?.meta?.did || "unknown",
+            audience: context.audience,
+            success,
+            reason,
+            duration,
+            sessionId: context.proof?.meta?.sessionId,
+        };
+        // For now, just console.log - in production, use structured logging
+        console.log("XMCP-I Verification:", JSON.stringify(logEntry));
+    }
+    /**
+     * Clean up expired cache entries
+     */
+    cleanupCache() {
+        const now = Date.now();
+        for (const [key, value] of this.didCache.entries()) {
+            if (value.expiresAt <= now) {
+                this.didCache.delete(key);
+            }
+        }
+        for (const [key, value] of this.delegationCache.entries()) {
+            if (value.expiresAt <= now) {
+                this.delegationCache.delete(key);
+            }
+        }
+    }
+}
+//# sourceMappingURL=core.js.map