@kya-os/mcp-i/dist/runtime/delegation/vc-verifier.d.ts

The TypeScript MCP framework with identity features built-in

/**
 * Delegation Credential Verifier
 *
 * Progressive enhancement verification for W3C Delegation Credentials.
 * Follows the Edge-Delegation-Verification.md pattern:
 *
 * Stage 1: Fast basic checks (no network, early rejection)
 * Stage 2: Parallel advanced checks (signature, status)
 * Stage 3: Combined results
 *
 * Related Spec: MCP-I §4.3, W3C VC Data Model 1.1
 * Python Reference: Edge-Delegation-Verification.md
 */
import { JWK } from 'jose';
import { DelegationCredential } from '@kya-os/contracts/delegation';
import { CredentialStatus } from '@kya-os/contracts/vc';
/**
 * Verification result for delegation credentials
 */
export interface DelegationVCVerificationResult {
    /** Whether the delegation credential is valid */
    valid: boolean;
    /** Reason for invalid result (if valid=false) */
    reason?: string;
    /** Stage at which verification completed */
    stage: 'basic' | 'signature' | 'status' | 'complete';
    /** Whether result came from cache */
    cached?: boolean;
    /** Performance metrics */
    metrics?: {
        basicCheckMs?: number;
        signatureCheckMs?: number;
        statusCheckMs?: number;
        totalMs: number;
    };
    /** Details about what was checked */
    checks?: {
        basicValid?: boolean;
        signatureValid?: boolean;
        statusValid?: boolean;
    };
}
/**
 * Options for verification
 */
export interface VerifyDelegationVCOptions {
    /** Skip cache and force fresh verification */
    skipCache?: boolean;
    /** Skip signature verification (faster, less secure) */
    skipSignature?: boolean;
    /** Skip status checking (faster, may miss revocations) */
    skipStatus?: boolean;
    /** DID resolver for fetching public keys */
    didResolver?: DIDResolver;
    /** Status list resolver for checking revocation */
    statusListResolver?: StatusListResolver;
}
/**
 * DID Resolver interface
 */
export interface DIDResolver {
    /**
     * Resolve a DID to get the DID Document
     * @param did - The DID to resolve
     * @returns DID Document with verification methods
     */
    resolve(did: string): Promise<DIDDocument | null>;
}
/**
 * DID Document (simplified)
 */
export interface DIDDocument {
    id: string;
    verificationMethod?: VerificationMethod[];
    authentication?: (string | VerificationMethod)[];
    assertionMethod?: (string | VerificationMethod)[];
}
/**
 * Verification Method
 */
export interface VerificationMethod {
    id: string;
    type: string;
    controller: string;
    publicKeyJwk?: JWK;
    publicKeyBase58?: string;
    publicKeyMultibase?: string;
}
/**
 * Status List Resolver interface
 */
export interface StatusListResolver {
    /**
     * Check if a credential is revoked via StatusList2021
     * @param status - The credential status entry
     * @returns true if revoked, false otherwise
     */
    checkStatus(status: CredentialStatus): Promise<boolean>;
}
/**
 * Delegation Credential Verifier
 *
 * Implements progressive enhancement pattern from Edge-Delegation-Verification.md:
 * 1. Fast basic checks (no network) - early rejection
 * 2. Parallel advanced checks (signature + status)
 * 3. Combined results
 */
export declare class DelegationCredentialVerifier {
    private didResolver?;
    private statusListResolver?;
    private cache;
    private cacheTtl;
    constructor(options?: {
        didResolver?: DIDResolver;
        statusListResolver?: StatusListResolver;
        cacheTtl?: number;
    });
    /**
     * Verify a delegation credential with progressive enhancement
     *
     * Per Edge-Delegation-Verification.md:41-102
     *
     * @param vc - The delegation credential to verify
     * @param options - Verification options
     * @returns Verification result
     */
    verifyDelegationCredential(vc: DelegationCredential, options?: VerifyDelegationVCOptions): Promise<DelegationVCVerificationResult>;
    /**
     * Stage 1: Validate basic properties (no network calls)
     *
     * Fast path for early rejection of invalid delegations.
     * Per Edge-Delegation-Verification.md:155-186
     *
     * @param vc - The delegation credential
     * @returns Validation result
     */
    private validateBasicProperties;
    /**
     * Stage 2a: Verify signature
     *
     * Per Edge-Delegation-Verification.md:191-234
     *
     * @param vc - The delegation credential
     * @param didResolver - Optional DID resolver
     * @returns Verification result
     */
    private verifySignature;
    /**
     * Stage 2b: Check credential status via StatusList2021
     *
     * @param status - The credential status entry
     * @param statusListResolver - Optional status list resolver
     * @returns Status check result
     */
    private checkCredentialStatus;
    /**
     * Find verification method in DID document
     *
     * @param didDoc - The DID document
     * @param verificationMethodId - The verification method ID
     * @returns Verification method or undefined
     */
    private findVerificationMethod;
    /**
     * Get from cache
     */
    private getFromCache;
    /**
     * Set in cache
     */
    private setInCache;
    /**
     * Clear cache
     */
    clearCache(): void;
    /**
     * Clear cache entry for specific VC
     */
    clearCacheEntry(id: string): void;
}
/**
 * Create a delegation credential verifier
 *
 * Convenience factory function.
 *
 * @param options - Verifier options
 * @returns DelegationCredentialVerifier instance
 */
export declare function createDelegationVerifier(options?: {
    didResolver?: DIDResolver;
    statusListResolver?: StatusListResolver;
    cacheTtl?: number;
}): DelegationCredentialVerifier;