/** * @fileoverview CAR Attestation Types * * Defines types for attestations - cryptographic proofs issued by certification * authorities that verify agent capabilities, identity, or compliance. * * Attestations are the foundation of trust in the CAR system, providing * verifiable evidence that an agent has been certified at a particular level. * * @module @vorionsys/contracts/car/attestation */ import { z } from 'zod'; import { CertificationTier } from './tiers.js'; import { type DomainCode } from './domains.js'; /** * Scope types for attestations. * * Defines what aspect of an agent is being attested: * - full: Complete capability attestation * - domain: Single domain attestation * - level: Level-only attestation * - training: Training data/methodology attestation * - security: Security audit attestation * - compliance: Regulatory compliance attestation * - identity: Identity verification attestation */ export type AttestationScope = 'full' | 'domain' | 'level' | 'training' | 'security' | 'compliance' | 'identity' | 'supervision'; /** * Array of all attestation scopes. */ export declare const ATTESTATION_SCOPES: readonly AttestationScope[]; /** * Zod schema for AttestationScope validation. */ export declare const attestationScopeSchema: z.ZodEnum<["full", "domain", "level", "training", "security", "compliance", "identity", "supervision"]>; /** * Descriptions for attestation scopes. */ export declare const ATTESTATION_SCOPE_DESCRIPTIONS: Readonly>; /** * Status of an attestation. */ export type AttestationStatus = 'active' | 'expired' | 'revoked' | 'suspended' | 'pending'; /** * Zod schema for AttestationStatus validation. */ export declare const attestationStatusSchema: z.ZodEnum<["active", "expired", "revoked", "suspended", "pending"]>; /** * Evidence supporting an attestation. */ export interface AttestationEvidence { /** URL to test results */ testResults?: string; /** URL to audit report */ auditReport?: string; /** URL to training data verification */ trainingVerification?: string; /** URL to compliance documentation */ complianceDocumentation?: string; /** Additional evidence URLs */ [key: string]: string | undefined; } /** * Zod schema for AttestationEvidence validation. */ export declare const attestationEvidenceSchema: z.ZodObject<{ testResults: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, "strip", z.ZodOptional, z.objectOutputType<{ testResults: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, z.ZodOptional, "strip">, z.objectInputType<{ testResults: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, z.ZodOptional, "strip">>; /** * Cryptographic proof for an attestation. * * Follows W3C Verifiable Credentials proof format. */ export interface AttestationProof { /** Proof type (e.g., 'Ed25519Signature2020', 'JsonWebSignature2020') */ type: string; /** When the proof was created (ISO 8601) */ created: string; /** DID URL of the verification method */ verificationMethod: string; /** Purpose of the proof (e.g., 'assertionMethod') */ proofPurpose: string; /** JSON Web Signature */ jws: string; /** Optional nonce for replay protection */ nonce?: string; /** Optional challenge for interactive proofs */ challenge?: string; /** Optional domain binding */ domain?: string; } /** * Zod schema for AttestationProof validation. */ export declare const attestationProofSchema: z.ZodObject<{ type: z.ZodString; created: z.ZodString; verificationMethod: z.ZodString; proofPurpose: z.ZodString; jws: z.ZodString; nonce: z.ZodOptional; challenge: z.ZodOptional; domain: z.ZodOptional; }, "strip", z.ZodTypeAny, { type: string; created: string; verificationMethod: string; proofPurpose: string; jws: string; nonce?: string | undefined; domain?: string | undefined; challenge?: string | undefined; }, { type: string; created: string; verificationMethod: string; proofPurpose: string; jws: string; nonce?: string | undefined; domain?: string | undefined; challenge?: string | undefined; }>; /** * Attestation from a certification authority. * * Represents a verifiable claim about an agent's capabilities, identity, * or compliance status issued by a trusted certification authority. */ export interface Attestation { /** Unique attestation identifier */ id: string; /** DID of the issuing certification authority */ issuer: string; /** DID of the attested agent */ subject: string; /** Scope of the attestation */ scope: AttestationScope; /** Attested certification tier */ certificationTier: CertificationTier; /** Specific domains covered (for domain scope) */ domains?: readonly DomainCode[]; /** When the attestation was issued */ issuedAt: Date; /** When the attestation expires */ expiresAt: Date; /** Current status */ status: AttestationStatus; /** Evidence supporting the attestation */ evidence?: AttestationEvidence; /** Cryptographic proof */ proof?: AttestationProof; /** Additional metadata */ metadata?: Record; } /** * Zod schema for Attestation validation. */ export declare const attestationSchema: z.ZodObject<{ id: z.ZodString; issuer: z.ZodString; subject: z.ZodString; scope: z.ZodEnum<["full", "domain", "level", "training", "security", "compliance", "identity", "supervision"]>; certificationTier: z.ZodNativeEnum; domains: z.ZodOptional, "many">>; issuedAt: z.ZodDate; expiresAt: z.ZodDate; status: z.ZodEnum<["active", "expired", "revoked", "suspended", "pending"]>; evidence: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, "strip", z.ZodOptional, z.objectOutputType<{ testResults: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, z.ZodOptional, "strip">, z.objectInputType<{ testResults: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, z.ZodOptional, "strip">>>; proof: z.ZodOptional; challenge: z.ZodOptional; domain: z.ZodOptional; }, "strip", z.ZodTypeAny, { type: string; created: string; verificationMethod: string; proofPurpose: string; jws: string; nonce?: string | undefined; domain?: string | undefined; challenge?: string | undefined; }, { type: string; created: string; verificationMethod: string; proofPurpose: string; jws: string; nonce?: string | undefined; domain?: string | undefined; challenge?: string | undefined; }>>; metadata: z.ZodOptional>; }, "strip", z.ZodTypeAny, { id: string; status: "active" | "suspended" | "pending" | "revoked" | "expired"; expiresAt: Date; scope: "security" | "full" | "training" | "domain" | "compliance" | "level" | "identity" | "supervision"; issuedAt: Date; issuer: string; subject: string; certificationTier: CertificationTier; proof?: { type: string; created: string; verificationMethod: string; proofPurpose: string; jws: string; nonce?: string | undefined; domain?: string | undefined; challenge?: string | undefined; } | undefined; metadata?: Record | undefined; domains?: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[] | undefined; evidence?: z.objectOutputType<{ testResults: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, z.ZodOptional, "strip"> | undefined; }, { id: string; status: "active" | "suspended" | "pending" | "revoked" | "expired"; expiresAt: Date; scope: "security" | "full" | "training" | "domain" | "compliance" | "level" | "identity" | "supervision"; issuedAt: Date; issuer: string; subject: string; certificationTier: CertificationTier; proof?: { type: string; created: string; verificationMethod: string; proofPurpose: string; jws: string; nonce?: string | undefined; domain?: string | undefined; challenge?: string | undefined; } | undefined; metadata?: Record | undefined; domains?: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[] | undefined; evidence?: z.objectInputType<{ testResults: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, z.ZodOptional, "strip"> | undefined; }>; /** * Result of attestation verification. */ export interface AttestationVerificationResult { /** Whether the attestation is valid */ valid: boolean; /** Verification errors */ errors: AttestationVerificationError[]; /** Verification warnings */ warnings: AttestationVerificationWarning[]; /** Verified attestation data (if valid) */ attestation?: Attestation; /** Verification timestamp */ verifiedAt: Date; /** Verification method used */ verificationMethod?: string; } /** * Attestation verification error. */ export interface AttestationVerificationError { /** Error code */ code: AttestationVerificationErrorCode; /** Human-readable message */ message: string; } /** * Error codes for attestation verification. */ export type AttestationVerificationErrorCode = 'INVALID_SIGNATURE' | 'EXPIRED' | 'REVOKED' | 'SUSPENDED' | 'ISSUER_NOT_TRUSTED' | 'SUBJECT_MISMATCH' | 'INVALID_FORMAT' | 'PROOF_MISSING' | 'VERIFICATION_FAILED'; /** * Attestation verification warning. */ export interface AttestationVerificationWarning { /** Warning code */ code: string; /** Human-readable message */ message: string; } /** * Zod schema for AttestationVerificationError. */ export declare const attestationVerificationErrorSchema: z.ZodObject<{ code: z.ZodEnum<["INVALID_SIGNATURE", "EXPIRED", "REVOKED", "SUSPENDED", "ISSUER_NOT_TRUSTED", "SUBJECT_MISMATCH", "INVALID_FORMAT", "PROOF_MISSING", "VERIFICATION_FAILED"]>; message: z.ZodString; }, "strip", z.ZodTypeAny, { code: "EXPIRED" | "SUSPENDED" | "REVOKED" | "INVALID_FORMAT" | "INVALID_SIGNATURE" | "ISSUER_NOT_TRUSTED" | "SUBJECT_MISMATCH" | "PROOF_MISSING" | "VERIFICATION_FAILED"; message: string; }, { code: "EXPIRED" | "SUSPENDED" | "REVOKED" | "INVALID_FORMAT" | "INVALID_SIGNATURE" | "ISSUER_NOT_TRUSTED" | "SUBJECT_MISMATCH" | "PROOF_MISSING" | "VERIFICATION_FAILED"; message: string; }>; /** * Zod schema for AttestationVerificationWarning. */ export declare const attestationVerificationWarningSchema: z.ZodObject<{ code: z.ZodString; message: z.ZodString; }, "strip", z.ZodTypeAny, { code: string; message: string; }, { code: string; message: string; }>; /** * Zod schema for AttestationVerificationResult. */ export declare const attestationVerificationResultSchema: z.ZodObject<{ valid: z.ZodBoolean; errors: z.ZodArray; message: z.ZodString; }, "strip", z.ZodTypeAny, { code: "EXPIRED" | "SUSPENDED" | "REVOKED" | "INVALID_FORMAT" | "INVALID_SIGNATURE" | "ISSUER_NOT_TRUSTED" | "SUBJECT_MISMATCH" | "PROOF_MISSING" | "VERIFICATION_FAILED"; message: string; }, { code: "EXPIRED" | "SUSPENDED" | "REVOKED" | "INVALID_FORMAT" | "INVALID_SIGNATURE" | "ISSUER_NOT_TRUSTED" | "SUBJECT_MISMATCH" | "PROOF_MISSING" | "VERIFICATION_FAILED"; message: string; }>, "many">; warnings: z.ZodArray, "many">; attestation: z.ZodOptional; certificationTier: z.ZodNativeEnum; domains: z.ZodOptional, "many">>; issuedAt: z.ZodDate; expiresAt: z.ZodDate; status: z.ZodEnum<["active", "expired", "revoked", "suspended", "pending"]>; evidence: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, "strip", z.ZodOptional, z.objectOutputType<{ testResults: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, z.ZodOptional, "strip">, z.objectInputType<{ testResults: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, z.ZodOptional, "strip">>>; proof: z.ZodOptional; challenge: z.ZodOptional; domain: z.ZodOptional; }, "strip", z.ZodTypeAny, { type: string; created: string; verificationMethod: string; proofPurpose: string; jws: string; nonce?: string | undefined; domain?: string | undefined; challenge?: string | undefined; }, { type: string; created: string; verificationMethod: string; proofPurpose: string; jws: string; nonce?: string | undefined; domain?: string | undefined; challenge?: string | undefined; }>>; metadata: z.ZodOptional>; }, "strip", z.ZodTypeAny, { id: string; status: "active" | "suspended" | "pending" | "revoked" | "expired"; expiresAt: Date; scope: "security" | "full" | "training" | "domain" | "compliance" | "level" | "identity" | "supervision"; issuedAt: Date; issuer: string; subject: string; certificationTier: CertificationTier; proof?: { type: string; created: string; verificationMethod: string; proofPurpose: string; jws: string; nonce?: string | undefined; domain?: string | undefined; challenge?: string | undefined; } | undefined; metadata?: Record | undefined; domains?: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[] | undefined; evidence?: z.objectOutputType<{ testResults: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, z.ZodOptional, "strip"> | undefined; }, { id: string; status: "active" | "suspended" | "pending" | "revoked" | "expired"; expiresAt: Date; scope: "security" | "full" | "training" | "domain" | "compliance" | "level" | "identity" | "supervision"; issuedAt: Date; issuer: string; subject: string; certificationTier: CertificationTier; proof?: { type: string; created: string; verificationMethod: string; proofPurpose: string; jws: string; nonce?: string | undefined; domain?: string | undefined; challenge?: string | undefined; } | undefined; metadata?: Record | undefined; domains?: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[] | undefined; evidence?: z.objectInputType<{ testResults: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, z.ZodOptional, "strip"> | undefined; }>>; verifiedAt: z.ZodDate; verificationMethod: z.ZodOptional; }, "strip", z.ZodTypeAny, { valid: boolean; errors: { code: "EXPIRED" | "SUSPENDED" | "REVOKED" | "INVALID_FORMAT" | "INVALID_SIGNATURE" | "ISSUER_NOT_TRUSTED" | "SUBJECT_MISMATCH" | "PROOF_MISSING" | "VERIFICATION_FAILED"; message: string; }[]; warnings: { code: string; message: string; }[]; verifiedAt: Date; attestation?: { id: string; status: "active" | "suspended" | "pending" | "revoked" | "expired"; expiresAt: Date; scope: "security" | "full" | "training" | "domain" | "compliance" | "level" | "identity" | "supervision"; issuedAt: Date; issuer: string; subject: string; certificationTier: CertificationTier; proof?: { type: string; created: string; verificationMethod: string; proofPurpose: string; jws: string; nonce?: string | undefined; domain?: string | undefined; challenge?: string | undefined; } | undefined; metadata?: Record | undefined; domains?: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[] | undefined; evidence?: z.objectOutputType<{ testResults: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, z.ZodOptional, "strip"> | undefined; } | undefined; verificationMethod?: string | undefined; }, { valid: boolean; errors: { code: "EXPIRED" | "SUSPENDED" | "REVOKED" | "INVALID_FORMAT" | "INVALID_SIGNATURE" | "ISSUER_NOT_TRUSTED" | "SUBJECT_MISMATCH" | "PROOF_MISSING" | "VERIFICATION_FAILED"; message: string; }[]; warnings: { code: string; message: string; }[]; verifiedAt: Date; attestation?: { id: string; status: "active" | "suspended" | "pending" | "revoked" | "expired"; expiresAt: Date; scope: "security" | "full" | "training" | "domain" | "compliance" | "level" | "identity" | "supervision"; issuedAt: Date; issuer: string; subject: string; certificationTier: CertificationTier; proof?: { type: string; created: string; verificationMethod: string; proofPurpose: string; jws: string; nonce?: string | undefined; domain?: string | undefined; challenge?: string | undefined; } | undefined; metadata?: Record | undefined; domains?: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[] | undefined; evidence?: z.objectInputType<{ testResults: z.ZodOptional; auditReport: z.ZodOptional; trainingVerification: z.ZodOptional; complianceDocumentation: z.ZodOptional; }, z.ZodOptional, "strip"> | undefined; } | undefined; verificationMethod?: string | undefined; }>; /** * Options for creating an attestation. */ export interface CreateAttestationOptions { /** Unique identifier (auto-generated if not provided) */ id?: string; /** DID of the issuing certification authority */ issuer: string; /** DID of the attested agent */ subject: string; /** Scope of the attestation */ scope: AttestationScope; /** Attested certification tier */ certificationTier: CertificationTier; /** Specific domains covered (for domain scope) */ domains?: readonly DomainCode[]; /** Validity duration in milliseconds */ validityMs?: number; /** Evidence supporting the attestation */ evidence?: AttestationEvidence; /** Additional metadata */ metadata?: Record; } /** * Creates a new attestation. * * @param options - Attestation creation options * @returns New attestation (without proof - must be signed separately) * * @example * ```typescript * const attestation = createAttestation({ * issuer: 'did:web:certifier.example.com', * subject: 'did:web:agent.acme.com', * scope: 'full', * certificationTier: CertificationTier.T3_CERTIFIED, * validityMs: 365 * 24 * 60 * 60 * 1000, // 1 year * }); * ``` */ export declare function createAttestation(options: CreateAttestationOptions): Attestation; /** * Verifies an attestation (basic validation without cryptographic verification). * * This function performs structural and temporal validation. Cryptographic * verification of the proof requires additional libraries and is not * performed here. * * @param attestation - The attestation to verify * @param expectedSubject - Optional expected subject DID * @param trustedIssuers - Optional list of trusted issuer DIDs * @returns Verification result */ export declare function verifyAttestation(attestation: Attestation, expectedSubject?: string, trustedIssuers?: readonly string[]): AttestationVerificationResult; /** * Checks if an attestation is currently valid. * * @param attestation - The attestation to check * @returns True if the attestation is valid */ export declare function isAttestationValid(attestation: Attestation): boolean; /** * Gets the remaining validity duration of an attestation. * * @param attestation - The attestation to check * @returns Remaining validity in milliseconds (negative if expired) */ export declare function getAttestationRemainingValidity(attestation: Attestation): number; /** * Checks if an attestation covers a specific domain. * * @param attestation - The attestation to check * @param domain - The domain to check for * @returns True if the attestation covers the domain */ export declare function attestationCoversDomain(attestation: Attestation, domain: DomainCode): boolean; /** * Type guard to check if a value is a valid AttestationScope. */ export declare function isAttestationScope(value: unknown): value is AttestationScope; /** * Type guard to check if a value is a valid AttestationStatus. */ export declare function isAttestationStatus(value: unknown): value is AttestationStatus;