@attest-it/core 0.4.0 → 0.6.0

package/dist/core-unstripped.d.ts

@@ -94,6 +94,15 @@ export declare function canonicalizeAttestations(attestations: Attestation[]): s
  */
 export declare function checkOpenSSL(): Promise<string>;
 
+/**
+ * CLI experience preferences (UX-related settings).
+ * @public
+ */
+export declare interface CliExperiencePreferences {
+    /** Whether the user has declined shell completion installation */
+    declinedCompletionInstall?: boolean;
+}
+
 /**
  * Compute a deterministic fingerprint for a set of packages (async).
  *
@@ -765,6 +774,25 @@ export declare function generateKeyPair(options?: KeygenOptions): Promise<KeyPat
  */
 export declare function getActiveIdentity(config: LocalConfig): Identity | undefined;
 
+/**
+ * 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
+ */
+export declare function getAttestItConfigDir(): string;
+
+/**
+ * Get the current attest-it home directory override.
+ *
+ * @returns The override directory, or null if using default
+ * @public
+ */
+export declare function getAttestItHomeDir(): null | string;
+
 /**
  * Get all team members authorized to sign for a gate.
  *
@@ -802,11 +830,31 @@ export declare function getGate(config: AttestItConfig, gateId: string): GateCon
 /**
  * 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
  */
 export declare function getLocalConfigPath(): string;
 
+/**
+ * Get a single preference value.
+ *
+ * @param key - Preference key to get
+ * @returns Preference value, or undefined if not set
+ * @public
+ */
+export declare function getPreference<K extends keyof UserPreferences>(key: K): Promise<undefined | UserPreferences[K]>;
+
+/**
+ * Get the path to the preferences file.
+ *
+ * @returns Path to the preferences file
+ * @public
+ */
+export declare function getPreferencesPath(): string;
+
 /**
  * Extract the public key from an Ed25519 private key.
  *
@@ -1064,6 +1112,16 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
            */
           export declare function loadLocalConfigSync(configPath?: string): LocalConfig | null;
 
+          /**
+           * 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
+           */
+          export declare function loadPreferences(): Promise<UserPreferences>;
+
           /**
            * The local config file structure at ~/.config/attest-it/config.yaml.
            * @public
@@ -1084,6 +1142,17 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
               constructor(message: string, issues: z.ZodIssue[]);
           }
 
+          /**
+           * Information about a macOS keychain.
+           * @public
+           */
+          export declare 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.
            *
@@ -1098,6 +1167,7 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
               readonly type = "macos-keychain";
               readonly displayName = "macOS Keychain";
               private readonly itemName;
+              private readonly keychain?;
               private static readonly ACCOUNT;
               /**
                * Create a new MacOSKeychainKeyProvider.
@@ -1109,6 +1179,11 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
                * 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.
                */
@@ -1144,8 +1219,36 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
           export declare 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;
           }
 
+          /**
+           * 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
+           */
+          export declare function mergeConfigs(policy: PolicyConfig, operational: OperationalConfig): AttestItConfig;
+
           /**
            * Information about a 1Password account.
            * @public
@@ -1252,547 +1355,1162 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
           }
 
           /**
-           * Parse a duration string to milliseconds.
-           * Uses the ms library to parse strings like "30d", "7d", "24h".
-           *
-           * @param duration - Duration string (e.g., "30d", "7d", "24h")
-           * @returns Duration in milliseconds
-           * @throws {Error} If duration string is invalid
-           * @public
-           */
-          export declare function parseDuration(duration: string): number;
-
-          /**
-           * Private key reference - points to where the key is stored.
-           * @public
-           */
-          export declare type PrivateKeyRef = {
-              account: string;
-              service: string;
-              type: 'keychain';
-          } | {
-              account?: string;
-              field?: string;
-              item: string;
-              type: '1password';
-              vault: string;
-          } | {
-              path: string;
-              type: 'file';
-          };
-
-          /**
-           * Read attestations and verify the signature.
-           *
-           * This function reads the attestations file, canonicalizes the attestations,
-           * and verifies the signature using the public key. It throws an error if the
-           * file doesn't exist or if signature verification fails.
-           *
-           * @param options - Options for reading and verifying attestations
-           * @returns The attestations file if signature is valid
-           * @throws Error if attestations file not found
-           * @throws SignatureInvalidError if signature verification fails
-           * @public
-           */
-          export declare function readAndVerifyAttestations(options: ReadSignedAttestationsOptions): Promise<AttestationsFile>;
-
-          /**
-           * Read attestations file from disk (async).
-           *
-           * @param filePath - Absolute path to the attestations JSON file
-           * @returns Parsed attestations file, or null if the file doesn't exist
-           * @throws Error on parse or validation errors
-           * @public
-           */
-          export declare function readAttestations(filePath: string): Promise<AttestationsFile | null>;
-
-          /**
-           * Read attestations file from disk (sync).
-           *
-           * @param filePath - Absolute path to the attestations JSON file
-           * @returns Parsed attestations file, or null if the file doesn't exist
-           * @throws Error on parse or validation errors
-           * @public
-           */
-          export declare function readAttestationsSync(filePath: string): AttestationsFile | null;
-
-          /**
-           * Read seals from the seals.json file (async).
-           *
-           * @param dir - Directory containing .attest-it/seals.json
-           * @returns The seals file contents, or an empty seals file if the file doesn't exist
-           * @throws Error if file exists but cannot be read or parsed
-           * @public
-           */
-          export declare function readSeals(dir: string): Promise<SealsFile>;
-
-          /**
-           * Read seals from the seals.json file (sync).
-           *
-           * @param dir - Directory containing .attest-it/seals.json
-           * @returns The seals file contents, or an empty seals file if the file doesn't exist
-           * @throws Error if file exists but cannot be read or parsed
-           * @public
-           */
-          export declare function readSealsSync(dir: string): SealsFile;
-
-          /**
-           * Options for reading and verifying signed attestations.
-           * @public
-           */
-          export declare interface ReadSignedAttestationsOptions {
-              /** Path to read the attestations file from */
-              filePath: string;
-              /** Path to the public key for verification */
-              publicKeyPath: string;
-          }
-
-          /**
-           * Remove attestations for a suite.
-           *
-           * This is an immutable operation that returns a new array.
-           *
-           * @param attestations - Current array of attestations
-           * @param suite - Name of the suite to remove
-           * @returns New attestations array without the specified suite
+           * Operational configuration type inferred from the Zod schema.
            * @public
            */
-          export declare function removeAttestation(attestations: Attestation[], suite: string): Attestation[];
+          export declare type OperationalConfig = z.infer<typeof operationalSchema>;
 
           /**
-           * Resolve relative paths in the configuration against the repository root.
+           * Zod schema for the operational configuration file.
            *
-           * This converts relative paths in settings.publicKeyPath and settings.attestationsPath
-           * to absolute paths relative to the repository root.
+           * Operational files define:
+           * - Command execution settings (default command, key provider)
+           * - Suite definitions with command execution details
+           * - Suite groups for organizational purposes
            *
-           * @param config - The configuration object
-           * @param repoRoot - Absolute path to the repository root
-           * @returns Configuration with resolved absolute paths
            * @public
            */
-          export declare function resolveConfigPaths(config: Config, repoRoot: string): Config;
-
-          /**
-           * Save local config to file (async).
-           *
-           * @param config - LocalConfig object to save
-           * @param configPath - Optional path to config file. If not provided, uses default location.
-           * @throws {Error} If write fails
-           * @public
-           */
-          export declare function saveLocalConfig(config: LocalConfig, configPath?: string): Promise<void>;
-
-          /**
-           * Save local config to file (sync).
-           *
-           * @param config - LocalConfig object to save
-           * @param configPath - Optional path to config file. If not provided, uses default location.
-           * @throws {Error} If write fails
-           * @public
-           */
-          export declare function saveLocalConfigSync(config: LocalConfig, configPath?: string): void;
-
-          /**
-           * A seal represents a cryptographic attestation that a gate's fingerprint
-           * was signed by an authorized team member.
-           * @public
-           */
-          export declare interface Seal {
-              /** Gate identifier (slug) */
-              gateId: string;
-              /** SHA-256 fingerprint of the gate's content in format "sha256:..." */
-              fingerprint: string;
-              /** ISO 8601 timestamp when the seal was created */
-              timestamp: string;
-              /** Team member slug who created the seal */
-              sealedBy: string;
-              /** Base64-encoded Ed25519 signature of gateId:fingerprint:timestamp */
-              signature: string;
-          }
-
-          /**
-           * The seals file structure stored at .attest-it/seals.json.
-           * @public
-           */
-          export declare interface SealsFile {
-              /** Schema version for forward compatibility */
+          export 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;
-              /** Map of gate slugs to their seals */
-              seals: Record<string, Seal>;
-          }
-
-          /**
-           * Result of verifying a single gate's seal.
-           * @public
-           */
-          export declare interface SealVerificationResult {
-              /** Gate identifier */
-              gateId: string;
-              /** Verification state */
-              state: VerificationState;
-              /** The seal, if one exists */
-              seal?: Seal;
-              /** Human-readable message explaining the state */
-              message?: string;
-          }
-
-          /**
-           * Set restrictive permissions on a private key file.
-           * @param keyPath - Path to the private key
-           * @public
-           */
-          export declare function setKeyPermissions(keyPath: string): Promise<void>;
-
-          /**
-           * Sign data using an RSA private key with SHA-256.
-           *
-           * Uses `openssl dgst -sha256 -sign` which is universally supported across
-           * all OpenSSL and LibreSSL versions.
-           *
-           * @param options - Signing options
-           * @returns Base64-encoded signature
-           * @throws Error if signing fails
-           * @public
-           */
-          export declare function sign(options: SignOptions): Promise<string>;
-
-          /**
-           * Error thrown when signature verification fails.
-           * @public
-           */
-          export declare class SignatureInvalidError extends Error {
-              /**
-               * Create a new SignatureInvalidError.
-               * @param filePath - Path to the file that failed verification
-               */
-              constructor(filePath: string);
-          }
-
-          /**
-           * Result of seal signature verification.
-           * @public
-           */
-          export declare interface SignatureVerificationResult {
-              /** Whether the seal signature is valid */
-              valid: boolean;
-              /** Error message if verification failed */
-              error?: string;
-          }
-
-          /**
-           * Sign data with an Ed25519 private key.
-           *
-           * @param data - Data to sign (Buffer or UTF-8 string)
-           * @param privateKeyPem - PEM-encoded private key
-           * @returns Base64-encoded signature
-           * @throws Error if signing fails
-           * @public
-           */
-          export declare function signEd25519(data: Buffer | string, privateKeyPem: string): string;
-
-          /**
-           * Options for signing data.
-           * @public
-           */
-          export declare interface SignOptions {
-              /** Path to the private key file (legacy) */
-              privateKeyPath?: string;
-              /** Key provider to use for retrieving the private key */
-              keyProvider?: KeyProvider;
-              /** Key reference for the provider */
-              keyRef?: string;
-              /** Data to sign (string or Buffer) */
-              data: Buffer | string;
-          }
-
-          /**
-           * Suite definition from the configuration file.
-           * Suites are CLI-layer extensions of gates with command execution capabilities.
-           * @public
-           */
-          export declare interface SuiteConfig {
-              /** Reference to a gate (if present, inherits gate configuration) */
-              gate?: string;
-              /** Human-readable description of what this suite tests */
-              description?: string;
-              /** Glob patterns for npm packages to include in fingerprint (legacy/backward compatibility) */
-              packages?: string[];
-              /** Additional file patterns to include in fingerprint */
-              files?: string[];
-              /** Patterns to ignore when computing fingerprint */
-              ignore?: string[];
-              /** Command to execute for this suite (overrides defaultCommand) */
-              command?: string;
-              /** Timeout for command execution (duration string) */
-              timeout?: string;
-              /** Whether the command is interactive */
-              interactive?: boolean;
-              /** Other suite names that, when changed, invalidate this suite's attestation */
-              invalidates?: string[];
-              /** Array of suite names this suite depends on */
-              depends_on?: string[];
-          }
-
-          /**
-           * Result of verifying a single suite's attestation.
-           * @public
-           */
-          export declare interface SuiteVerificationResult {
-              /** Name of the suite being verified */
-              suite: string;
-              /** Current verification status */
-              status: VerificationStatus;
-              /** Current computed fingerprint for the suite */
-              fingerprint: string;
-              /** The attestation record, if one exists */
-              attestation?: Attestation;
-              /** List of files that changed (if status is FINGERPRINT_CHANGED) */
-              changedFiles?: string[];
-              /** Age of the attestation in days (if expired) */
-              age?: number;
-              /** Human-readable message explaining the status */
-              message?: string;
-          }
-
-          /**
-           * Team member configuration.
-           * @public
-           */
-          export declare interface TeamMember {
-              /** Display name for the team member */
-              name: string;
-              /** Email address (optional) */
-              email?: string | undefined;
-              /** GitHub username (optional) */
-              github?: string | undefined;
-              /** Base64-encoded Ed25519 public key */
-              publicKey: string;
-          }
-
-          /**
-           * Convert Zod-validated Config to AttestItConfig by removing undefined values.
-           *
-           * The Config type (from Zod) has optional fields as `T | undefined`,
-           * while AttestItConfig has optional fields as `T?` (can be absent, not undefined).
-           *
-           * This adapter removes any undefined values to match the AttestItConfig interface
-           * that the core functions expect.
-           *
-           * @param config - The Zod-validated configuration from loadConfig()
-           * @returns Configuration compatible with AttestItConfig
-           * @public
-           */
-          export declare function toAttestItConfig(config: Config): AttestItConfig;
-
-          /**
-           * Add or update an attestation for a suite.
-           *
-           * This is an immutable operation that returns a new array.
-           *
-           * @param attestations - Current array of attestations
-           * @param newAttestation - Attestation to add or update
-           * @returns New attestations array with the upserted attestation
-           * @throws Error if the new attestation fails validation
-           * @public
-           */
-          export declare function upsertAttestation(attestations: Attestation[], newAttestation: Attestation): Attestation[];
-
-          /**
-           * Verification state for a gate's seal.
-           * @public
-           */
-          export declare type VerificationState = 'FINGERPRINT_MISMATCH' | 'INVALID_SIGNATURE' | 'MISSING' | 'STALE' | 'UNKNOWN_SIGNER' | 'VALID';
-
-          /**
-           * Verification status codes for suite attestations.
-           * @public
-           */
-          export declare type VerificationStatus = 'EXPIRED' | 'FINGERPRINT_CHANGED' | 'INVALIDATED_BY_PARENT' | 'NEEDS_ATTESTATION' | 'SIGNATURE_INVALID' | 'VALID';
-
-          /**
-           * Verify a signature using an RSA public key with SHA-256.
-           *
-           * Uses `openssl dgst -sha256 -verify` which is universally supported across
-           * all OpenSSL and LibreSSL versions.
-           *
-           * @param options - Verification options
-           * @returns true if signature is valid
-           * @throws Error if verification fails (not just invalid signature)
-           * @public
-           */
-          export declare function verify(options: CryptoVerifyOptions): Promise<boolean>;
-
-          /**
-           * Verify all gates' seals.
-           *
-           * @param config - The attest-it configuration
-           * @param seals - The seals file containing all seals
-           * @param fingerprints - Map of gate IDs to their current fingerprints
-           * @returns Array of verification results for all gates
-           * @public
-           */
-          export declare function verifyAllSeals(config: AttestItConfig, seals: SealsFile, fingerprints: Record<string, string>): SealVerificationResult[];
-
-          /**
-           * Verify all attestations against current code state.
-           *
-           * Verification algorithm:
-           * 1. Load and verify attestations file signature
-           * 2. For each suite in config:
-           *    a. Compute current fingerprint
-           *    b. Find matching attestation
-           *    c. Compare fingerprints
-           *    d. Check age
-           * 3. Check invalidation chains
-           * 4. Return aggregated results
-           *
-           * @param options - Verification options
-           * @returns Verification result with status for each suite
-           * @public
-           */
-          export declare function verifyAttestations(options: VerifyOptions): Promise<VerifyResult>;
-
-          /**
-           * Verify an Ed25519 signature.
-           *
-           * @param data - Original data that was signed
-           * @param signature - Base64-encoded signature to verify
-           * @param publicKeyBase64 - Base64-encoded public key (raw 32 bytes)
-           * @returns true if signature is valid, false otherwise
-           * @throws Error if verification fails (not just invalid signature)
-           * @public
-           */
-          export declare function verifyEd25519(data: Buffer | string, signature: string, publicKeyBase64: string): boolean;
-
-          /**
-           * Verify a single gate's seal.
-           *
-           * @param config - The attest-it configuration
-           * @param gateId - Gate identifier to verify
-           * @param seals - The seals file containing all seals
-           * @param currentFingerprint - Current computed fingerprint for the gate
-           * @returns Verification result for the gate
-           * @public
-           */
-          export declare function verifyGateSeal(config: AttestItConfig, gateId: string, seals: SealsFile, currentFingerprint: string): SealVerificationResult;
-
-          /**
-           * Options for verifying attestations.
-           * @public
-           */
-          export declare interface VerifyOptions {
-              /** Configuration object */
-              config: AttestItConfig;
-              /** Repository root directory (defaults to process.cwd()) */
-              repoRoot?: string;
-          }
+          }, {
+              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;
+          }>;
 
           /**
-           * Result of verifying all attestations.
+           * Error thrown when operational configuration is invalid.
            * @public
            */
-          export declare interface VerifyResult {
-              /** Overall success - true if all attestations are valid */
-              success: boolean;
-              /** Whether the attestations file signature is valid */
-              signatureValid: boolean;
-              /** Verification results for each suite */
-              suites: SuiteVerificationResult[];
-              /** Error messages encountered during verification */
-              errors: string[];
+          export declare class OperationalValidationError extends Error {
+              readonly issues: z.ZodIssue[];
+              constructor(message: string, issues: z.ZodIssue[]);
           }
 
           /**
-           * Verify a seal's signature against the team member's public key.
-           *
-           * @param seal - The seal to verify
-           * @param config - The attest-it configuration containing team members
-           * @returns Verification result with success status and optional error message
-           * @public
-           */
-          export declare function verifySeal(seal: Seal, config: AttestItConfig): SignatureVerificationResult;
-
-          /**
-           * Package version
-           * @public
-           */
-          export declare const version = "0.0.0";
-
-          /**
-           * Write attestations file to disk (async).
-           *
-           * Creates parent directories if needed. The signature should be computed
-           * separately and passed in.
-           *
-           * @param filePath - Absolute path to write the attestations file
-           * @param attestations - Array of attestation entries
-           * @param signature - Cryptographic signature of the attestations
-           * @throws Error on validation or write errors
-           * @public
-           */
-          export declare function writeAttestations(filePath: string, attestations: Attestation[], signature: string): Promise<void>;
-
-          /**
-           * Write attestations file to disk (sync).
-           *
-           * Creates parent directories if needed. The signature should be computed
-           * separately and passed in.
-           *
-           * @param filePath - Absolute path to write the attestations file
-           * @param attestations - Array of attestation entries
-           * @param signature - Cryptographic signature of the attestations
-           * @throws Error on validation or write errors
-           * @public
-           */
-          export declare function writeAttestationsSync(filePath: string, attestations: Attestation[], signature: string): void;
-
-          /**
-           * Write seals to the seals.json file (async).
-           *
-           * @param dir - Directory containing .attest-it/seals.json
-           * @param sealsFile - The seals file to write
-           * @throws Error if file cannot be written
-           * @public
-           */
-          export declare function writeSeals(dir: string, sealsFile: SealsFile): Promise<void>;
-
-          /**
-           * Write seals to the seals.json file (sync).
+           * Parse a duration string to milliseconds.
+           * Uses the ms library to parse strings like "30d", "7d", "24h".
            *
-           * @param dir - Directory containing .attest-it/seals.json
-           * @param sealsFile - The seals file to write
-           * @throws Error if file cannot be written
+           * @param duration - Duration string (e.g., "30d", "7d", "24h")
+           * @returns Duration in milliseconds
+           * @throws {Error} If duration string is invalid
            * @public
            */
-          export declare function writeSealsSync(dir: string, sealsFile: SealsFile): void;
+          export declare function parseDuration(duration: string): number;
 
           /**
-           * Write attestations with a cryptographic signature.
+           * Parse operational configuration content from a string.
            *
-           * This function canonicalizes the attestations, signs them with the private key,
-           * and writes the attestations file with the signature.
-           *
-           * @param options - Options for writing signed attestations
-           * @throws Error if signing or writing fails
-           * @public
-           */
-          export declare function writeSignedAttestations(options: WriteSignedAttestationsOptions): Promise<void>;
-
-          /**
-           * Options for writing signed attestations.
-           * @public
-           */
-          export declare interface WriteSignedAttestationsOptions {
-              /** Path to write the attestations file */
-              filePath: string;
-              /** Array of attestations to write */
-              attestations: Attestation[];
-              /** Path to the private key for signing (legacy) */
-              privateKeyPath?: string;
-              /** Key provider for signing */
-              keyProvider?: KeyProvider;
-              /** Key reference for the provider */
-              keyRef?: string;
-          }
-
-          export { }
+           * @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
+               */
+           export declare function parseOperationalContent(content: string, format: 'json' | 'yaml'): OperationalConfig;
+
+           /**
+            * 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
+                */
+            export declare function parsePolicyContent(content: string, format: 'json' | 'yaml'): PolicyConfig;
+
+            /**
+             * Policy configuration type inferred from the Zod schema.
+             * @public
+             */
+            export declare type PolicyConfig = z.infer<typeof policySchema>;
+
+            /**
+             * 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
+             */
+            export 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;
+            }>;
+
+            /**
+             * Error thrown when policy configuration is invalid.
+             * @public
+             */
+            export declare class PolicyValidationError extends Error {
+                readonly issues: z.ZodIssue[];
+                constructor(message: string, issues: z.ZodIssue[]);
+            }
+
+            /**
+             * Private key reference - points to where the key is stored.
+             * @public
+             */
+            export declare type PrivateKeyRef = {
+                account: string;
+                keychain?: string;
+                service: string;
+                type: 'keychain';
+            } | {
+                account?: string;
+                field?: string;
+                item: string;
+                type: '1password';
+                vault: string;
+            } | {
+                encryptedKeyPath: string;
+                serial?: string;
+                slot?: 1 | 2;
+                type: 'yubikey';
+            } | {
+                path: string;
+                type: 'file';
+            };
+
+            /**
+             * Read attestations and verify the signature.
+             *
+             * This function reads the attestations file, canonicalizes the attestations,
+             * and verifies the signature using the public key. It throws an error if the
+             * file doesn't exist or if signature verification fails.
+             *
+             * @param options - Options for reading and verifying attestations
+             * @returns The attestations file if signature is valid
+             * @throws Error if attestations file not found
+             * @throws SignatureInvalidError if signature verification fails
+             * @public
+             */
+            export declare function readAndVerifyAttestations(options: ReadSignedAttestationsOptions): Promise<AttestationsFile>;
+
+            /**
+             * Read attestations file from disk (async).
+             *
+             * @param filePath - Absolute path to the attestations JSON file
+             * @returns Parsed attestations file, or null if the file doesn't exist
+             * @throws Error on parse or validation errors
+             * @public
+             */
+            export declare function readAttestations(filePath: string): Promise<AttestationsFile | null>;
+
+            /**
+             * Read attestations file from disk (sync).
+             *
+             * @param filePath - Absolute path to the attestations JSON file
+             * @returns Parsed attestations file, or null if the file doesn't exist
+             * @throws Error on parse or validation errors
+             * @public
+             */
+            export declare function readAttestationsSync(filePath: string): AttestationsFile | null;
+
+            /**
+             * Read seals from the seals.json file (async).
+             *
+             * @param dir - Directory containing .attest-it/seals.json
+             * @returns The seals file contents, or an empty seals file if the file doesn't exist
+             * @throws Error if file exists but cannot be read or parsed
+             * @public
+             */
+            export declare function readSeals(dir: string): Promise<SealsFile>;
+
+            /**
+             * Read seals from the seals.json file (sync).
+             *
+             * @param dir - Directory containing .attest-it/seals.json
+             * @returns The seals file contents, or an empty seals file if the file doesn't exist
+             * @throws Error if file exists but cannot be read or parsed
+             * @public
+             */
+            export declare function readSealsSync(dir: string): SealsFile;
+
+            /**
+             * Options for reading and verifying signed attestations.
+             * @public
+             */
+            export declare interface ReadSignedAttestationsOptions {
+                /** Path to read the attestations file from */
+                filePath: string;
+                /** Path to the public key for verification */
+                publicKeyPath: string;
+            }
+
+            /**
+             * Remove attestations for a suite.
+             *
+             * This is an immutable operation that returns a new array.
+             *
+             * @param attestations - Current array of attestations
+             * @param suite - Name of the suite to remove
+             * @returns New attestations array without the specified suite
+             * @public
+             */
+            export declare function removeAttestation(attestations: Attestation[], suite: string): Attestation[];
+
+            /**
+             * Resolve relative paths in the configuration against the repository root.
+             *
+             * This converts relative paths in settings.publicKeyPath and settings.attestationsPath
+             * to absolute paths relative to the repository root.
+             *
+             * @param config - The configuration object
+             * @param repoRoot - Absolute path to the repository root
+             * @returns Configuration with resolved absolute paths
+             * @public
+             */
+            export declare function resolveConfigPaths(config: Config, repoRoot: string): Config;
+
+            /**
+             * Save local config to file (async).
+             *
+             * @param config - LocalConfig object to save
+             * @param configPath - Optional path to config file. If not provided, uses default location.
+             * @throws {Error} If write fails
+             * @public
+             */
+            export declare function saveLocalConfig(config: LocalConfig, configPath?: string): Promise<void>;
+
+            /**
+             * Save local config to file (sync).
+             *
+             * @param config - LocalConfig object to save
+             * @param configPath - Optional path to config file. If not provided, uses default location.
+             * @throws {Error} If write fails
+             * @public
+             */
+            export declare function saveLocalConfigSync(config: LocalConfig, configPath?: string): void;
+
+            /**
+             * Save user preferences to file.
+             *
+             * @param preferences - Preferences to save
+             * @public
+             */
+            export declare function savePreferences(preferences: UserPreferences): Promise<void>;
+
+            /**
+             * A seal represents a cryptographic attestation that a gate's fingerprint
+             * was signed by an authorized team member.
+             * @public
+             */
+            export declare interface Seal {
+                /** Gate identifier (slug) */
+                gateId: string;
+                /** SHA-256 fingerprint of the gate's content in format "sha256:..." */
+                fingerprint: string;
+                /** ISO 8601 timestamp when the seal was created */
+                timestamp: string;
+                /** Team member slug who created the seal */
+                sealedBy: string;
+                /** Base64-encoded Ed25519 signature of gateId:fingerprint:timestamp */
+                signature: string;
+            }
+
+            /**
+             * The seals file structure stored at .attest-it/seals.json.
+             * @public
+             */
+            export declare interface SealsFile {
+                /** Schema version for forward compatibility */
+                version: 1;
+                /** Map of gate slugs to their seals */
+                seals: Record<string, Seal>;
+            }
+
+            /**
+             * Result of verifying a single gate's seal.
+             * @public
+             */
+            export declare interface SealVerificationResult {
+                /** Gate identifier */
+                gateId: string;
+                /** Verification state */
+                state: VerificationState;
+                /** The seal, if one exists */
+                seal?: Seal;
+                /** Human-readable message explaining the state */
+                message?: string;
+            }
+
+            /**
+             * 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
+             */
+            export declare function setAttestItHomeDir(dir: null | string): void;
+
+            /**
+             * Set restrictive permissions on a private key file.
+             * @param keyPath - Path to the private key
+             * @public
+             */
+            export declare function setKeyPermissions(keyPath: string): Promise<void>;
+
+            /**
+             * Update a single preference value.
+             *
+             * @param key - Preference key to update
+             * @param value - New value
+             * @public
+             */
+            export declare function setPreference<K extends keyof UserPreferences>(key: K, value: UserPreferences[K]): Promise<void>;
+
+            /**
+             * Sign data using an RSA private key with SHA-256.
+             *
+             * Uses `openssl dgst -sha256 -sign` which is universally supported across
+             * all OpenSSL and LibreSSL versions.
+             *
+             * @param options - Signing options
+             * @returns Base64-encoded signature
+             * @throws Error if signing fails
+             * @public
+             */
+            export declare function sign(options: SignOptions): Promise<string>;
+
+            /**
+             * Error thrown when signature verification fails.
+             * @public
+             */
+            export declare class SignatureInvalidError extends Error {
+                /**
+                 * Create a new SignatureInvalidError.
+                 * @param filePath - Path to the file that failed verification
+                 */
+                constructor(filePath: string);
+            }
+
+            /**
+             * Result of seal signature verification.
+             * @public
+             */
+            export declare interface SignatureVerificationResult {
+                /** Whether the seal signature is valid */
+                valid: boolean;
+                /** Error message if verification failed */
+                error?: string;
+            }
+
+            /**
+             * Sign data with an Ed25519 private key.
+             *
+             * @param data - Data to sign (Buffer or UTF-8 string)
+             * @param privateKeyPem - PEM-encoded private key
+             * @returns Base64-encoded signature
+             * @throws Error if signing fails
+             * @public
+             */
+            export declare function signEd25519(data: Buffer | string, privateKeyPem: string): string;
+
+            /**
+             * Options for signing data.
+             * @public
+             */
+            export declare interface SignOptions {
+                /** Path to the private key file (legacy) */
+                privateKeyPath?: string;
+                /** Key provider to use for retrieving the private key */
+                keyProvider?: KeyProvider;
+                /** Key reference for the provider */
+                keyRef?: string;
+                /** Data to sign (string or Buffer) */
+                data: Buffer | string;
+            }
+
+            /**
+             * Suite definition from the configuration file.
+             * Suites are CLI-layer extensions of gates with command execution capabilities.
+             * @public
+             */
+            export declare interface SuiteConfig {
+                /** Reference to a gate (if present, inherits gate configuration) */
+                gate?: string;
+                /** Human-readable description of what this suite tests */
+                description?: string;
+                /** Glob patterns for npm packages to include in fingerprint (legacy/backward compatibility) */
+                packages?: string[];
+                /** Additional file patterns to include in fingerprint */
+                files?: string[];
+                /** Patterns to ignore when computing fingerprint */
+                ignore?: string[];
+                /** Command to execute for this suite (overrides defaultCommand) */
+                command?: string;
+                /** Timeout for command execution (duration string) */
+                timeout?: string;
+                /** Whether the command is interactive */
+                interactive?: boolean;
+                /** Other suite names that, when changed, invalidate this suite's attestation */
+                invalidates?: string[];
+                /** Array of suite names this suite depends on */
+                depends_on?: string[];
+            }
+
+            /**
+             * Result of verifying a single suite's attestation.
+             * @public
+             */
+            export declare interface SuiteVerificationResult {
+                /** Name of the suite being verified */
+                suite: string;
+                /** Current verification status */
+                status: VerificationStatus;
+                /** Current computed fingerprint for the suite */
+                fingerprint: string;
+                /** The attestation record, if one exists */
+                attestation?: Attestation;
+                /** List of files that changed (if status is FINGERPRINT_CHANGED) */
+                changedFiles?: string[];
+                /** Age of the attestation in days (if expired) */
+                age?: number;
+                /** Human-readable message explaining the status */
+                message?: string;
+            }
+
+            /**
+             * Team member configuration.
+             * @public
+             */
+            export declare interface TeamMember {
+                /** Display name for the team member */
+                name: string;
+                /** Email address (optional) */
+                email?: string | undefined;
+                /** GitHub username (optional) */
+                github?: string | undefined;
+                /** Base64-encoded Ed25519 public key */
+                publicKey: string;
+            }
+
+            /**
+             * Convert Zod-validated Config to AttestItConfig by removing undefined values.
+             *
+             * The Config type (from Zod) has optional fields as `T | undefined`,
+             * while AttestItConfig has optional fields as `T?` (can be absent, not undefined).
+             *
+             * This adapter removes any undefined values to match the AttestItConfig interface
+             * that the core functions expect.
+             *
+             * @param config - The Zod-validated configuration from loadConfig()
+             * @returns Configuration compatible with AttestItConfig
+             * @public
+             */
+            export declare function toAttestItConfig(config: Config): AttestItConfig;
+
+            /**
+             * Add or update an attestation for a suite.
+             *
+             * This is an immutable operation that returns a new array.
+             *
+             * @param attestations - Current array of attestations
+             * @param newAttestation - Attestation to add or update
+             * @returns New attestations array with the upserted attestation
+             * @throws Error if the new attestation fails validation
+             * @public
+             */
+            export declare function upsertAttestation(attestations: Attestation[], newAttestation: Attestation): Attestation[];
+
+            /**
+             * User preferences stored in ~/.config/attest-it/preferences.yaml
+             * @public
+             */
+            export declare interface UserPreferences {
+                /** CLI experience and UX settings */
+                cliExperience?: CliExperiencePreferences;
+            }
+
+            /**
+             * 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
+             */
+            export declare function validateSuiteGateReferences(policy: PolicyConfig, operational: OperationalConfig): ValidationError[];
+
+            /**
+             * Represents a validation error found during cross-configuration validation.
+             * @public
+             */
+            export declare 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;
+            }
+
+            /**
+             * Validation error types for cross-configuration validation.
+             * @public
+             */
+            export declare type ValidationErrorType = 'MISSING_TEAM_MEMBER' | 'UNKNOWN_GATE';
+
+            /**
+             * Verification state for a gate's seal.
+             * @public
+             */
+            export declare type VerificationState = 'FINGERPRINT_MISMATCH' | 'INVALID_SIGNATURE' | 'MISSING' | 'STALE' | 'UNKNOWN_SIGNER' | 'VALID';
+
+            /**
+             * Verification status codes for suite attestations.
+             * @public
+             */
+            export declare type VerificationStatus = 'EXPIRED' | 'FINGERPRINT_CHANGED' | 'INVALIDATED_BY_PARENT' | 'NEEDS_ATTESTATION' | 'SIGNATURE_INVALID' | 'VALID';
+
+            /**
+             * Verify a signature using an RSA public key with SHA-256.
+             *
+             * Uses `openssl dgst -sha256 -verify` which is universally supported across
+             * all OpenSSL and LibreSSL versions.
+             *
+             * @param options - Verification options
+             * @returns true if signature is valid
+             * @throws Error if verification fails (not just invalid signature)
+             * @public
+             */
+            export declare function verify(options: CryptoVerifyOptions): Promise<boolean>;
+
+            /**
+             * Verify all gates' seals.
+             *
+             * @param config - The attest-it configuration
+             * @param seals - The seals file containing all seals
+             * @param fingerprints - Map of gate IDs to their current fingerprints
+             * @returns Array of verification results for all gates
+             * @public
+             */
+            export declare function verifyAllSeals(config: AttestItConfig, seals: SealsFile, fingerprints: Record<string, string>): SealVerificationResult[];
+
+            /**
+             * Verify all attestations against current code state.
+             *
+             * Verification algorithm:
+             * 1. Load and verify attestations file signature
+             * 2. For each suite in config:
+             *    a. Compute current fingerprint
+             *    b. Find matching attestation
+             *    c. Compare fingerprints
+             *    d. Check age
+             * 3. Check invalidation chains
+             * 4. Return aggregated results
+             *
+             * @param options - Verification options
+             * @returns Verification result with status for each suite
+             * @public
+             */
+            export declare function verifyAttestations(options: VerifyOptions): Promise<VerifyResult>;
+
+            /**
+             * Verify an Ed25519 signature.
+             *
+             * @param data - Original data that was signed
+             * @param signature - Base64-encoded signature to verify
+             * @param publicKeyBase64 - Base64-encoded public key (raw 32 bytes)
+             * @returns true if signature is valid, false otherwise
+             * @throws Error if verification fails (not just invalid signature)
+             * @public
+             */
+            export declare function verifyEd25519(data: Buffer | string, signature: string, publicKeyBase64: string): boolean;
+
+            /**
+             * Verify a single gate's seal.
+             *
+             * @param config - The attest-it configuration
+             * @param gateId - Gate identifier to verify
+             * @param seals - The seals file containing all seals
+             * @param currentFingerprint - Current computed fingerprint for the gate
+             * @returns Verification result for the gate
+             * @public
+             */
+            export declare function verifyGateSeal(config: AttestItConfig, gateId: string, seals: SealsFile, currentFingerprint: string): SealVerificationResult;
+
+            /**
+             * Options for verifying attestations.
+             * @public
+             */
+            export declare interface VerifyOptions {
+                /** Configuration object */
+                config: AttestItConfig;
+                /** Repository root directory (defaults to process.cwd()) */
+                repoRoot?: string;
+            }
+
+            /**
+             * Result of verifying all attestations.
+             * @public
+             */
+            export declare interface VerifyResult {
+                /** Overall success - true if all attestations are valid */
+                success: boolean;
+                /** Whether the attestations file signature is valid */
+                signatureValid: boolean;
+                /** Verification results for each suite */
+                suites: SuiteVerificationResult[];
+                /** Error messages encountered during verification */
+                errors: string[];
+            }
+
+            /**
+             * Verify a seal's signature against the team member's public key.
+             *
+             * @param seal - The seal to verify
+             * @param config - The attest-it configuration containing team members
+             * @returns Verification result with success status and optional error message
+             * @public
+             */
+            export declare function verifySeal(seal: Seal, config: AttestItConfig): SignatureVerificationResult;
+
+            /**
+             * Package version
+             * @public
+             */
+            export declare const version = "0.0.0";
+
+            /**
+             * Write attestations file to disk (async).
+             *
+             * Creates parent directories if needed. The signature should be computed
+             * separately and passed in.
+             *
+             * @param filePath - Absolute path to write the attestations file
+             * @param attestations - Array of attestation entries
+             * @param signature - Cryptographic signature of the attestations
+             * @throws Error on validation or write errors
+             * @public
+             */
+            export declare function writeAttestations(filePath: string, attestations: Attestation[], signature: string): Promise<void>;
+
+            /**
+             * Write attestations file to disk (sync).
+             *
+             * Creates parent directories if needed. The signature should be computed
+             * separately and passed in.
+             *
+             * @param filePath - Absolute path to write the attestations file
+             * @param attestations - Array of attestation entries
+             * @param signature - Cryptographic signature of the attestations
+             * @throws Error on validation or write errors
+             * @public
+             */
+            export declare function writeAttestationsSync(filePath: string, attestations: Attestation[], signature: string): void;
+
+            /**
+             * Write seals to the seals.json file (async).
+             *
+             * @param dir - Directory containing .attest-it/seals.json
+             * @param sealsFile - The seals file to write
+             * @throws Error if file cannot be written
+             * @public
+             */
+            export declare function writeSeals(dir: string, sealsFile: SealsFile): Promise<void>;
+
+            /**
+             * Write seals to the seals.json file (sync).
+             *
+             * @param dir - Directory containing .attest-it/seals.json
+             * @param sealsFile - The seals file to write
+             * @throws Error if file cannot be written
+             * @public
+             */
+            export declare function writeSealsSync(dir: string, sealsFile: SealsFile): void;
+
+            /**
+             * Write attestations with a cryptographic signature.
+             *
+             * This function canonicalizes the attestations, signs them with the private key,
+             * and writes the attestations file with the signature.
+             *
+             * @param options - Options for writing signed attestations
+             * @throws Error if signing or writing fails
+             * @public
+             */
+            export declare function writeSignedAttestations(options: WriteSignedAttestationsOptions): Promise<void>;
+
+            /**
+             * Options for writing signed attestations.
+             * @public
+             */
+            export declare interface WriteSignedAttestationsOptions {
+                /** Path to write the attestations file */
+                filePath: string;
+                /** Array of attestations to write */
+                attestations: Attestation[];
+                /** Path to the private key for signing (legacy) */
+                privateKeyPath?: string;
+                /** Key provider for signing */
+                keyProvider?: KeyProvider;
+                /** Key reference for the provider */
+                keyRef?: string;
+            }
+
+            /**
+             * Information about a connected YubiKey.
+             * @public
+             */
+            export declare 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
+             */
+            export 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;
+            }
+
+            /**
+             * Options for creating a YubiKeyProvider.
+             * @public
+             */
+            export declare 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;
+            }
+
+            export { }