@attest-it/core 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -631,6 +631,522 @@ declare function resolveConfigPaths(config: Config, repoRoot: string): Config;
  */
 declare function toAttestItConfig(config: Config): AttestItConfig;
 
+/**
+ * Policy configuration schema and validation for attest-it.
+ *
+ * Policy files contain trust and security-critical configuration that should
+ * be loaded from the default branch to prevent tampering by PR authors.
+ *
+ * ============================================================================
+ * IMPORTANT: DOCUMENTATION SYNC REQUIRED
+ * ============================================================================
+ * When modifying any schema in this file, you MUST also update:
+ *
+ * 1. README.md - Update the "Configuration" section's quick example
+ * 2. docs/configuration.md - Update the comprehensive configuration reference
+ * 3. schemas/policy.schema.json - Run `pnpm --filter @attest-it/core generate:schemas`
+ *
+ * The configuration format is a key part of the user experience. Any schema
+ * changes should be reflected in user-facing documentation.
+ * ============================================================================
+ */
+
+/**
+ * Zod schema for the policy configuration file.
+ *
+ * Policy files define:
+ * - Security settings (key paths, attestation storage, max age)
+ * - Team members and their public keys
+ * - Gates with authorization rules
+ *
+ * @public
+ */
+declare const policySchema: z.ZodObject<{
+    gates: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        authorizedSigners: z.ZodArray<z.ZodString, "many">;
+        description: z.ZodString;
+        fingerprint: z.ZodObject<{
+            exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            paths: z.ZodArray<z.ZodString, "many">;
+        }, "strict", z.ZodTypeAny, {
+            exclude?: string[] | undefined;
+            paths: string[];
+        }, {
+            exclude?: string[] | undefined;
+            paths: string[];
+        }>;
+        maxAge: z.ZodEffects<z.ZodString, string, string>;
+        name: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        authorizedSigners: string[];
+        description: string;
+        fingerprint: {
+            exclude?: string[] | undefined;
+            paths: string[];
+        };
+        maxAge: string;
+        name: string;
+    }, {
+        authorizedSigners: string[];
+        description: string;
+        fingerprint: {
+            exclude?: string[] | undefined;
+            paths: string[];
+        };
+        maxAge: string;
+        name: string;
+    }>>>;
+    settings: z.ZodDefault<z.ZodObject<{
+        attestationsPath: z.ZodDefault<z.ZodString>;
+        maxAgeDays: z.ZodDefault<z.ZodNumber>;
+        publicKeyPath: z.ZodDefault<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        attestationsPath: string;
+        maxAgeDays: number;
+        publicKeyPath: string;
+    }, {
+        attestationsPath?: string | undefined;
+        maxAgeDays?: number | undefined;
+        publicKeyPath?: string | undefined;
+    }>>;
+    team: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        email: z.ZodOptional<z.ZodString>;
+        github: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        publicKey: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        email?: string | undefined;
+        github?: string | undefined;
+        name: string;
+        publicKey: string;
+    }, {
+        email?: string | undefined;
+        github?: string | undefined;
+        name: string;
+        publicKey: string;
+    }>>>;
+    version: z.ZodLiteral<1>;
+}, "strict", z.ZodTypeAny, {
+    gates?: Record<string, {
+        authorizedSigners: string[];
+        description: string;
+        fingerprint: {
+            exclude?: string[] | undefined;
+            paths: string[];
+        };
+        maxAge: string;
+        name: string;
+    }> | undefined;
+    settings: {
+        attestationsPath: string;
+        maxAgeDays: number;
+        publicKeyPath: string;
+    };
+    team?: Record<string, {
+        email?: string | undefined;
+        github?: string | undefined;
+        name: string;
+        publicKey: string;
+    }> | undefined;
+    version: 1;
+}, {
+    gates?: Record<string, {
+        authorizedSigners: string[];
+        description: string;
+        fingerprint: {
+            exclude?: string[] | undefined;
+            paths: string[];
+        };
+        maxAge: string;
+        name: string;
+    }> | undefined;
+    settings?: {
+        attestationsPath?: string | undefined;
+        maxAgeDays?: number | undefined;
+        publicKeyPath?: string | undefined;
+    } | undefined;
+    team?: Record<string, {
+        email?: string | undefined;
+        github?: string | undefined;
+        name: string;
+        publicKey: string;
+    }> | undefined;
+    version: 1;
+}>;
+/**
+ * Policy configuration type inferred from the Zod schema.
+ * @public
+ */
+type PolicyConfig = z.infer<typeof policySchema>;
+/**
+ * Error thrown when policy configuration is invalid.
+ * @public
+ */
+declare class PolicyValidationError extends Error {
+    readonly issues: z.ZodIssue[];
+    constructor(message: string, issues: z.ZodIssue[]);
+}
+/**
+ * Parse policy configuration content from a string.
+ *
+ * @param content - The policy file content
+ * @param format - The format of the content ('yaml' or 'json')
+ * @returns Parsed and validated policy configuration
+ * @throws {@link PolicyValidationError} If validation fails
+ * @public
+ */
+declare function parsePolicyContent(content: string, format: 'json' | 'yaml'): PolicyConfig;
+
+/**
+ * Operational configuration schema and validation for attest-it.
+ *
+ * Operational files contain non-security-critical configuration that can
+ * be loaded from PR branches (e.g., suite definitions, command execution settings).
+ *
+ * ============================================================================
+ * IMPORTANT: DOCUMENTATION SYNC REQUIRED
+ * ============================================================================
+ * When modifying any schema in this file, you MUST also update:
+ *
+ * 1. README.md - Update the "Configuration" section's quick example
+ * 2. docs/configuration.md - Update the comprehensive configuration reference
+ * 3. schemas/config.schema.json - Run `pnpm --filter @attest-it/core generate:schemas`
+ *
+ * The configuration format is a key part of the user experience. Any schema
+ * changes should be reflected in user-facing documentation.
+ * ============================================================================
+ */
+
+/**
+ * Zod schema for the operational configuration file.
+ *
+ * Operational files define:
+ * - Command execution settings (default command, key provider)
+ * - Suite definitions with command execution details
+ * - Suite groups for organizational purposes
+ *
+ * @public
+ */
+declare const operationalSchema: z.ZodObject<{
+    groups: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    settings: z.ZodDefault<z.ZodObject<{
+        defaultCommand: z.ZodOptional<z.ZodString>;
+        keyProvider: z.ZodOptional<z.ZodObject<{
+            options: z.ZodOptional<z.ZodObject<{
+                account: z.ZodOptional<z.ZodString>;
+                itemName: z.ZodOptional<z.ZodString>;
+                privateKeyPath: z.ZodOptional<z.ZodString>;
+                vault: z.ZodOptional<z.ZodString>;
+            }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+                account: z.ZodOptional<z.ZodString>;
+                itemName: z.ZodOptional<z.ZodString>;
+                privateKeyPath: z.ZodOptional<z.ZodString>;
+                vault: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+                account: z.ZodOptional<z.ZodString>;
+                itemName: z.ZodOptional<z.ZodString>;
+                privateKeyPath: z.ZodOptional<z.ZodString>;
+                vault: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough">>>;
+            type: z.ZodUnion<[z.ZodEnum<["filesystem", "1password"]>, z.ZodString]>;
+        }, "strict", z.ZodTypeAny, {
+            options?: undefined | z.objectOutputType<{
+                account: z.ZodOptional<z.ZodString>;
+                itemName: z.ZodOptional<z.ZodString>;
+                privateKeyPath: z.ZodOptional<z.ZodString>;
+                vault: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough">;
+            type: string;
+        }, {
+            options?: undefined | z.objectInputType<{
+                account: z.ZodOptional<z.ZodString>;
+                itemName: z.ZodOptional<z.ZodString>;
+                privateKeyPath: z.ZodOptional<z.ZodString>;
+                vault: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough">;
+            type: string;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        defaultCommand?: string | undefined;
+        keyProvider?: {
+            options?: undefined | z.objectOutputType<{
+                account: z.ZodOptional<z.ZodString>;
+                itemName: z.ZodOptional<z.ZodString>;
+                privateKeyPath: z.ZodOptional<z.ZodString>;
+                vault: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough">;
+            type: string;
+        } | undefined;
+    }, {
+        defaultCommand?: string | undefined;
+        keyProvider?: {
+            options?: undefined | z.objectInputType<{
+                account: z.ZodOptional<z.ZodString>;
+                itemName: z.ZodOptional<z.ZodString>;
+                privateKeyPath: z.ZodOptional<z.ZodString>;
+                vault: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough">;
+            type: string;
+        } | undefined;
+    }>>;
+    suites: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+        command: z.ZodOptional<z.ZodString>;
+        depends_on: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        description: z.ZodOptional<z.ZodString>;
+        files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        gate: z.ZodOptional<z.ZodString>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        invalidates: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        packages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        timeout: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        command?: string | undefined;
+        depends_on?: string[] | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        gate?: string | undefined;
+        ignore?: string[] | undefined;
+        interactive?: boolean | undefined;
+        invalidates?: string[] | undefined;
+        packages?: string[] | undefined;
+        timeout?: string | undefined;
+    }, {
+        command?: string | undefined;
+        depends_on?: string[] | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        gate?: string | undefined;
+        ignore?: string[] | undefined;
+        interactive?: boolean | undefined;
+        invalidates?: string[] | undefined;
+        packages?: string[] | undefined;
+        timeout?: string | undefined;
+    }>, {
+        command?: string | undefined;
+        depends_on?: string[] | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        gate?: string | undefined;
+        ignore?: string[] | undefined;
+        interactive?: boolean | undefined;
+        invalidates?: string[] | undefined;
+        packages?: string[] | undefined;
+        timeout?: string | undefined;
+    }, {
+        command?: string | undefined;
+        depends_on?: string[] | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        gate?: string | undefined;
+        ignore?: string[] | undefined;
+        interactive?: boolean | undefined;
+        invalidates?: string[] | undefined;
+        packages?: string[] | undefined;
+        timeout?: string | undefined;
+    }>>, Record<string, {
+        command?: string | undefined;
+        depends_on?: string[] | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        gate?: string | undefined;
+        ignore?: string[] | undefined;
+        interactive?: boolean | undefined;
+        invalidates?: string[] | undefined;
+        packages?: string[] | undefined;
+        timeout?: string | undefined;
+    }>, Record<string, {
+        command?: string | undefined;
+        depends_on?: string[] | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        gate?: string | undefined;
+        ignore?: string[] | undefined;
+        interactive?: boolean | undefined;
+        invalidates?: string[] | undefined;
+        packages?: string[] | undefined;
+        timeout?: string | undefined;
+    }>>;
+    version: z.ZodLiteral<1>;
+}, "strict", z.ZodTypeAny, {
+    groups?: Record<string, string[]> | undefined;
+    settings: {
+        defaultCommand?: string | undefined;
+        keyProvider?: {
+            options?: undefined | z.objectOutputType<{
+                account: z.ZodOptional<z.ZodString>;
+                itemName: z.ZodOptional<z.ZodString>;
+                privateKeyPath: z.ZodOptional<z.ZodString>;
+                vault: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough">;
+            type: string;
+        } | undefined;
+    };
+    suites: Record<string, {
+        command?: string | undefined;
+        depends_on?: string[] | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        gate?: string | undefined;
+        ignore?: string[] | undefined;
+        interactive?: boolean | undefined;
+        invalidates?: string[] | undefined;
+        packages?: string[] | undefined;
+        timeout?: string | undefined;
+    }>;
+    version: 1;
+}, {
+    groups?: Record<string, string[]> | undefined;
+    settings?: {
+        defaultCommand?: string | undefined;
+        keyProvider?: {
+            options?: undefined | z.objectInputType<{
+                account: z.ZodOptional<z.ZodString>;
+                itemName: z.ZodOptional<z.ZodString>;
+                privateKeyPath: z.ZodOptional<z.ZodString>;
+                vault: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough">;
+            type: string;
+        } | undefined;
+    } | undefined;
+    suites: Record<string, {
+        command?: string | undefined;
+        depends_on?: string[] | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        gate?: string | undefined;
+        ignore?: string[] | undefined;
+        interactive?: boolean | undefined;
+        invalidates?: string[] | undefined;
+        packages?: string[] | undefined;
+        timeout?: string | undefined;
+    }>;
+    version: 1;
+}>;
+/**
+ * Operational configuration type inferred from the Zod schema.
+ * @public
+ */
+type OperationalConfig = z.infer<typeof operationalSchema>;
+/**
+ * Error thrown when operational configuration is invalid.
+ * @public
+ */
+declare class OperationalValidationError extends Error {
+    readonly issues: z.ZodIssue[];
+    constructor(message: string, issues: z.ZodIssue[]);
+}
+/**
+ * Parse operational configuration content from a string.
+ *
+ * @param content - The operational config file content
+ * @param format - The format of the content ('yaml' or 'json')
+ * @returns Parsed and validated operational configuration
+ * @throws {@link OperationalValidationError} If validation fails
+ * @public
+ */
+declare function parseOperationalContent(content: string, format: 'json' | 'yaml'): OperationalConfig;
+
+/**
+ * Merge policy and operational configurations into a unified AttestItConfig.
+ *
+ * This module handles the combination of security-critical policy configuration
+ * (loaded from the default branch) with operational configuration (can be loaded
+ * from PR branches) to create the complete configuration used for attestation
+ * verification.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Merges policy and operational configurations into a single AttestItConfig.
+ *
+ * The merge strategy prioritizes security-critical fields from the policy
+ * configuration while combining operational fields from both sources:
+ *
+ * - **Policy settings** (maxAgeDays, publicKeyPath, attestationsPath) are used as-is
+ * - **Operational settings** (defaultCommand, keyProvider) are added from operational config
+ * - **Team and gates** come exclusively from policy config
+ * - **Suites and groups** come exclusively from operational config
+ *
+ * @param policy - The policy configuration containing security-critical settings
+ * @param operational - The operational configuration containing suites and execution settings
+ * @returns A complete AttestItConfig ready for use in attestation operations
+ *
+ * @example
+ * ```typescript
+ * const policy = parsePolicyContent(policyYaml, 'yaml')
+ * const operational = parseOperationalContent(operationalYaml, 'yaml')
+ * const config = mergeConfigs(policy, operational)
+ * ```
+ *
+ * @public
+ */
+declare function mergeConfigs(policy: PolicyConfig, operational: OperationalConfig): AttestItConfig;
+
+/**
+ * Cross-configuration validation for split policy and operational configs.
+ *
+ * This module validates relationships between policy and operational configurations,
+ * ensuring that suite-gate references are valid and that all authorized signers
+ * are defined in the team.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Validation error types for cross-configuration validation.
+ * @public
+ */
+type ValidationErrorType = 'MISSING_TEAM_MEMBER' | 'UNKNOWN_GATE';
+/**
+ * Represents a validation error found during cross-configuration validation.
+ * @public
+ */
+interface ValidationError {
+    /** The type of validation error */
+    type: ValidationErrorType;
+    /** The suite name where the error was found (if applicable) */
+    suite?: string;
+    /** The gate name involved in the error (if applicable) */
+    gate?: string;
+    /** The signer slug that is missing (if applicable) */
+    signer?: string;
+    /** Human-readable error message explaining the issue */
+    message: string;
+}
+/**
+ * Validates that all suite-gate references and authorized signers are valid.
+ *
+ * This function performs cross-configuration validation to ensure:
+ * 1. Every suite that references a gate refers to an existing gate in the policy
+ * 2. Every authorized signer in each referenced gate is defined in the policy team
+ *
+ * These validations are critical because:
+ * - Operational config (suites) can come from PR branches
+ * - Policy config (gates, team) comes from the default branch
+ * - We must ensure PR authors cannot reference non-existent gates or signers
+ *
+ * @param policy - The policy configuration containing gates and team definitions
+ * @param operational - The operational configuration containing suite definitions
+ * @returns An array of validation errors (empty if validation passes)
+ *
+ * @example
+ * ```typescript
+ * const errors = validateSuiteGateReferences(policy, operational)
+ * if (errors.length > 0) {
+ *   console.error('Validation failed:')
+ *   for (const error of errors) {
+ *     console.error(`  - ${error.message}`)
+ *   }
+ *   throw new Error('Configuration validation failed')
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function validateSuiteGateReferences(policy: PolicyConfig, operational: OperationalConfig): ValidationError[];
+
 /**
  * Options for computing a package fingerprint.
  * @public
@@ -1384,6 +1900,18 @@ declare class OnePasswordKeyProvider implements KeyProvider {
 interface MacOSKeychainKeyProviderOptions {
     /** Item name in keychain (e.g., "attest-it-private-key") */
     itemName: string;
+    /** Path to the keychain file (optional, uses default keychain if not specified) */
+    keychain?: string;
+}
+/**
+ * Information about a macOS keychain.
+ * @public
+ */
+interface MacOSKeychain {
+    /** Full path to the keychain file */
+    path: string;
+    /** Display name (filename without extension) */
+    name: string;
 }
 /**
  * Key provider that stores private keys in macOS Keychain.
@@ -1399,6 +1927,7 @@ declare class MacOSKeychainKeyProvider implements KeyProvider {
     readonly type = "macos-keychain";
     readonly displayName = "macOS Keychain";
     private readonly itemName;
+    private readonly keychain?;
     private static readonly ACCOUNT;
     /**
      * Create a new MacOSKeychainKeyProvider.
@@ -1410,6 +1939,11 @@ declare class MacOSKeychainKeyProvider implements KeyProvider {
      * Only available on macOS platforms.
      */
     static isAvailable(): boolean;
+    /**
+     * List available keychains on the system.
+     * @returns Array of keychain information
+     */
+    static listKeychains(): Promise<MacOSKeychain[]>;
     /**
      * Check if this provider is available on the current system.
      */
@@ -1438,6 +1972,161 @@ declare class MacOSKeychainKeyProvider implements KeyProvider {
     getConfig(): KeyProviderConfig;
 }
 
+/**
+ * YubiKey-based key provider implementation.
+ *
+ * @remarks
+ * This provider stores private keys encrypted with a key derived from YubiKey
+ * HMAC-SHA1 challenge-response. The key cannot be decrypted without the physical
+ * YubiKey present. Uses HKDF to derive an AES-256-GCM encryption key from the
+ * challenge-response output.
+ *
+ * Requires the `ykman` (YubiKey Manager) CLI tool to be installed.
+ *
+ * **Security Note**: Private keys are temporarily held in memory as JavaScript
+ * strings during encryption/decryption. JavaScript strings are immutable and
+ * cannot be securely zeroed. The key remains in memory until garbage collected.
+ * For maximum security, use full-disk encryption and disable swap on systems
+ * handling sensitive keys.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for creating a YubiKeyProvider.
+ * @public
+ */
+interface YubiKeyProviderOptions {
+    /** Path to the encrypted key file */
+    encryptedKeyPath: string;
+    /** YubiKey slot to use for challenge-response (default: 2) */
+    slot?: 1 | 2;
+    /** Serial number of specific YubiKey to use (optional but recommended) */
+    serial?: string;
+}
+/**
+ * Information about a connected YubiKey.
+ * @public
+ */
+interface YubiKeyInfo {
+    /** Device serial number */
+    serial: string;
+    /** Device type (e.g., "YubiKey 5 NFC") */
+    type: string;
+    /** Firmware version */
+    firmware: string;
+}
+/**
+ * Key provider that encrypts private keys using YubiKey HMAC challenge-response.
+ *
+ * @remarks
+ * This provider uses the YubiKey HMAC-SHA1 challenge-response feature (typically slot 2)
+ * to derive an encryption key. The Ed25519 private key is encrypted with AES-256-GCM,
+ * and can only be decrypted when the correct YubiKey is present.
+ *
+ * This approach:
+ * - Works with all YubiKeys that support HMAC-SHA1 challenge-response
+ * - Preserves Ed25519 compatibility (signing happens in software)
+ * - Requires physical YubiKey presence to decrypt and use the key
+ *
+ * **Security Note**: Always use the `serial` option to bind keys to a specific YubiKey.
+ * Without serial verification, any YubiKey with the same HMAC secret could decrypt the key.
+ *
+ * @public
+ */
+declare class YubiKeyProvider implements KeyProvider {
+    readonly type = "yubikey";
+    readonly displayName = "YubiKey";
+    private readonly encryptedKeyPath;
+    private readonly slot;
+    private readonly serial?;
+    /**
+     * Create a new YubiKeyProvider.
+     * @param options - Provider options
+     * @throws Error if encryptedKeyPath is outside the attest-it config directory
+     */
+    constructor(options: YubiKeyProviderOptions);
+    /**
+     * Check if ykman CLI is installed and available.
+     * @returns true if ykman is available
+     */
+    static isInstalled(): Promise<boolean>;
+    /**
+     * Check if any YubiKey is connected.
+     * @returns true if at least one YubiKey is connected
+     */
+    static isConnected(): Promise<boolean>;
+    /**
+     * Check if HMAC challenge-response is configured on a slot.
+     * @param slot - Slot number (1 or 2)
+     * @param serial - Optional YubiKey serial number
+     * @returns true if challenge-response is configured
+     */
+    static isChallengeResponseConfigured(slot?: 1 | 2, serial?: string): Promise<boolean>;
+    /**
+     * List connected YubiKeys.
+     * @returns Array of YubiKey information
+     */
+    static listDevices(): Promise<YubiKeyInfo[]>;
+    /**
+     * Check if this provider is available on the current system.
+     * Requires ykman to be installed.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Check if an encrypted key file exists.
+     * @param keyRef - Path to encrypted key file
+     */
+    keyExists(keyRef: string): Promise<boolean>;
+    /**
+     * Get the private key by decrypting with YubiKey.
+     * Downloads to a temporary file and returns a cleanup function.
+     *
+     * **Important**: Always call the cleanup function when done to securely delete
+     * the temporary key file. The cleanup is also registered for process exit handlers.
+     *
+     * @param keyRef - Path to encrypted key file
+     * @throws Error if the key cannot be decrypted
+     */
+    getPrivateKey(keyRef: string): Promise<KeyRetrievalResult>;
+    /**
+     * Generate a new keypair and store encrypted with YubiKey.
+     * Public key is written to filesystem for repository commit.
+     *
+     * **Security Note**: Always specify a serial number to bind the key to a specific YubiKey.
+     *
+     * @param options - Key generation options
+     */
+    generateKeyPair(options: KeygenProviderOptions): Promise<KeyGenerationResult>;
+    /**
+     * Encrypt an existing private key with YubiKey challenge-response.
+     *
+     * @remarks
+     * This static method allows encrypting a private key that was generated
+     * elsewhere (e.g., by the CLI) without having to create a provider instance first.
+     *
+     * **Security Note**: Always specify a serial number to bind the key to a specific YubiKey.
+     * The serial provides defense-in-depth by ensuring only the intended YubiKey can decrypt.
+     *
+     * @param options - Encryption options
+     * @returns Path to the encrypted key file and storage description
+     * @public
+     */
+    static encryptPrivateKey(options: {
+        encryptedKeyPath: string;
+        privateKey: string;
+        serial?: string;
+        slot?: 1 | 2;
+    }): Promise<{
+        encryptedKeyPath: string;
+        storageDescription: string;
+    }>;
+    /**
+     * Get the configuration for this provider.
+     */
+    getConfig(): KeyProviderConfig;
+}
+
 /**
  * Registry for key provider implementations.
  *
@@ -1495,6 +2184,7 @@ declare class KeyProviderRegistry {
  */
 type PrivateKeyRef = {
     account: string;
+    keychain?: string;
     service: string;
     type: 'keychain';
 } | {
@@ -1503,6 +2193,11 @@ type PrivateKeyRef = {
     item: string;
     type: '1password';
     vault: string;
+} | {
+    encryptedKeyPath: string;
+    serial?: string;
+    slot?: 1 | 2;
+    type: 'yubikey';
 } | {
     path: string;
     type: 'file';
@@ -1534,11 +2229,88 @@ interface LocalConfig {
     identities: Record<string, Identity>;
 }
 
+/**
+ * User preferences management for attest-it.
+ * Stored separately from identity config to allow preferences
+ * before any identity exists.
+ * @packageDocumentation
+ */
+/**
+ * CLI experience preferences (UX-related settings).
+ * @public
+ */
+interface CliExperiencePreferences {
+    /** Whether the user has declined shell completion installation */
+    declinedCompletionInstall?: boolean;
+}
+/**
+ * User preferences stored in ~/.config/attest-it/preferences.yaml
+ * @public
+ */
+interface UserPreferences {
+    /** CLI experience and UX settings */
+    cliExperience?: CliExperiencePreferences;
+}
+/**
+ * Get the path to the preferences file.
+ *
+ * @returns Path to the preferences file
+ * @public
+ */
+declare function getPreferencesPath(): string;
+/**
+ * Load user preferences from file.
+ * Validates the file contents against the schema and returns
+ * only valid, known preferences.
+ *
+ * @returns User preferences, or empty object if file doesn't exist
+ * @public
+ */
+declare function loadPreferences(): Promise<UserPreferences>;
+/**
+ * Save user preferences to file.
+ *
+ * @param preferences - Preferences to save
+ * @public
+ */
+declare function savePreferences(preferences: UserPreferences): Promise<void>;
+/**
+ * Update a single preference value.
+ *
+ * @param key - Preference key to update
+ * @param value - New value
+ * @public
+ */
+declare function setPreference<K extends keyof UserPreferences>(key: K, value: UserPreferences[K]): Promise<void>;
+/**
+ * Get a single preference value.
+ *
+ * @param key - Preference key to get
+ * @returns Preference value, or undefined if not set
+ * @public
+ */
+declare function getPreference<K extends keyof UserPreferences>(key: K): Promise<undefined | UserPreferences[K]>;
+
 /**
  * Configuration loading for local identity system.
  * @packageDocumentation
  */
 
+/**
+ * Set a custom home directory for attest-it configuration.
+ * This is useful for testing or running with isolated state.
+ *
+ * @param dir - The directory to use, or null to reset to default
+ * @public
+ */
+declare function setAttestItHomeDir(dir: null | string): void;
+/**
+ * Get the current attest-it home directory override.
+ *
+ * @returns The override directory, or null if using default
+ * @public
+ */
+declare function getAttestItHomeDir(): null | string;
 /**
  * Error thrown when local config validation fails.
  * @public
@@ -1550,10 +2322,23 @@ declare class LocalConfigValidationError extends Error {
 /**
  * Get the path to the local config file.
  *
- * @returns Path to ~/.config/attest-it/config.yaml
+ * If a home directory override is set via setAttestItHomeDir(),
+ * returns {homeDir}/config.yaml. Otherwise returns ~/.config/attest-it/config.yaml.
+ *
+ * @returns Path to the local config file
  * @public
  */
 declare function getLocalConfigPath(): string;
+/**
+ * Get the attest-it configuration directory.
+ *
+ * If a home directory override is set via setAttestItHomeDir(),
+ * returns that directory. Otherwise returns ~/.config/attest-it.
+ *
+ * @returns Path to the configuration directory
+ * @public
+ */
+declare function getAttestItConfigDir(): string;
 /**
  * Load and validate local config from file (async).
  *
@@ -1826,4 +2611,4 @@ declare function verifyAllSeals(config: AttestItConfig, seals: SealsFile, finger
  */
 declare const version = "0.0.0";
 
-export { type AttestItConfig, type AttestItSettings, type Attestation, type AttestationsFile, type Config, ConfigNotFoundError, ConfigValidationError, type CreateSealOptions, type VerifyOptions$1 as CryptoVerifyOptions, type KeyPair as Ed25519KeyPair, FilesystemKeyProvider, type FilesystemKeyProviderOptions, type FingerprintConfig, type FingerprintOptions, type FingerprintResult, type GateConfig, type Identity, type KeyGenerationResult, type KeyPaths, type KeyProvider, type KeyProviderConfig, type KeyProviderFactory, KeyProviderRegistry, type KeyProviderSettings, type KeyRetrievalResult, type KeygenOptions, type KeygenProviderOptions, type LocalConfig, LocalConfigValidationError, MacOSKeychainKeyProvider, type MacOSKeychainKeyProviderOptions, type OnePasswordAccount, OnePasswordKeyProvider, type OnePasswordKeyProviderOptions, type OnePasswordVault, type PrivateKeyRef, type ReadSignedAttestationsOptions, type Seal, type SealVerificationResult, type SealsFile, type SignOptions, SignatureInvalidError, type SignatureVerificationResult, type SuiteConfig, type SuiteVerificationResult, type TeamMember, type VerificationState, type VerificationStatus, type VerifyOptions, type VerifyResult, type WriteSignedAttestationsOptions, canonicalizeAttestations, checkOpenSSL, computeFingerprint, computeFingerprintSync, createAttestation, createSeal, findAttestation, findConfigPath, findTeamMemberByPublicKey, generateKeyPair as generateEd25519KeyPair, generateKeyPair$1 as generateKeyPair, getActiveIdentity, getAuthorizedSignersForGate, getDefaultPrivateKeyPath, getDefaultPublicKeyPath, getGate, getLocalConfigPath, getPublicKeyFromPrivate, isAuthorizedSigner, listPackageFiles, loadConfig, loadConfigSync, loadLocalConfig, loadLocalConfigSync, parseDuration, readAndVerifyAttestations, readAttestations, readAttestationsSync, readSeals, readSealsSync, removeAttestation, resolveConfigPaths, saveLocalConfig, saveLocalConfigSync, setKeyPermissions, sign$1 as sign, sign as signEd25519, toAttestItConfig, upsertAttestation, verify$1 as verify, verifyAllSeals, verifyAttestations, verify as verifyEd25519, verifyGateSeal, verifySeal, version, writeAttestations, writeAttestationsSync, writeSeals, writeSealsSync, writeSignedAttestations };
+export { type AttestItConfig, type AttestItSettings, type Attestation, type AttestationsFile, type CliExperiencePreferences, type Config, ConfigNotFoundError, ConfigValidationError, type CreateSealOptions, type VerifyOptions$1 as CryptoVerifyOptions, type KeyPair as Ed25519KeyPair, FilesystemKeyProvider, type FilesystemKeyProviderOptions, type FingerprintConfig, type FingerprintOptions, type FingerprintResult, type GateConfig, type Identity, type KeyGenerationResult, type KeyPaths, type KeyProvider, type KeyProviderConfig, type KeyProviderFactory, KeyProviderRegistry, type KeyProviderSettings, type KeyRetrievalResult, type KeygenOptions, type KeygenProviderOptions, type LocalConfig, LocalConfigValidationError, type MacOSKeychain, MacOSKeychainKeyProvider, type MacOSKeychainKeyProviderOptions, type OnePasswordAccount, OnePasswordKeyProvider, type OnePasswordKeyProviderOptions, type OnePasswordVault, type OperationalConfig, OperationalValidationError, type PolicyConfig, PolicyValidationError, type PrivateKeyRef, type ReadSignedAttestationsOptions, type Seal, type SealVerificationResult, type SealsFile, type SignOptions, SignatureInvalidError, type SignatureVerificationResult, type SuiteConfig, type SuiteVerificationResult, type TeamMember, type UserPreferences, type ValidationError, type ValidationErrorType, type VerificationState, type VerificationStatus, type VerifyOptions, type VerifyResult, type WriteSignedAttestationsOptions, type YubiKeyInfo, YubiKeyProvider, type YubiKeyProviderOptions, canonicalizeAttestations, checkOpenSSL, computeFingerprint, computeFingerprintSync, createAttestation, createSeal, findAttestation, findConfigPath, findTeamMemberByPublicKey, generateKeyPair as generateEd25519KeyPair, generateKeyPair$1 as generateKeyPair, getActiveIdentity, getAttestItConfigDir, getAttestItHomeDir, getAuthorizedSignersForGate, getDefaultPrivateKeyPath, getDefaultPublicKeyPath, getGate, getLocalConfigPath, getPreference, getPreferencesPath, getPublicKeyFromPrivate, isAuthorizedSigner, listPackageFiles, loadConfig, loadConfigSync, loadLocalConfig, loadLocalConfigSync, loadPreferences, mergeConfigs, operationalSchema, parseDuration, parseOperationalContent, parsePolicyContent, policySchema, readAndVerifyAttestations, readAttestations, readAttestationsSync, readSeals, readSealsSync, removeAttestation, resolveConfigPaths, saveLocalConfig, saveLocalConfigSync, savePreferences, setAttestItHomeDir, setKeyPermissions, setPreference, sign$1 as sign, sign as signEd25519, toAttestItConfig, upsertAttestation, validateSuiteGateReferences, verify$1 as verify, verifyAllSeals, verifyAttestations, verify as verifyEd25519, verifyGateSeal, verifySeal, version, writeAttestations, writeAttestationsSync, writeSeals, writeSealsSync, writeSignedAttestations };