@attest-it/core 0.0.2 → 0.4.0

package/dist/core-public.d.ts

@@ -41,8 +41,14 @@ export declare interface AttestItConfig {
     version: 1;
     /** Global settings for attestation behavior */
     settings: AttestItSettings;
+    /** Team members mapped by slug */
+    team?: Record<string, TeamMember>;
+    /** Gates defining authorization and fingerprinting */
+    gates?: Record<string, GateConfig>;
     /** Named test suites with their configurations */
     suites: Record<string, SuiteConfig>;
+    /** Named groups of suites */
+    groups?: Record<string, string[]>;
 }
 
 /**
@@ -58,6 +64,8 @@ export declare interface AttestItSettings {
     attestationsPath: string;
     /** Default command to execute for attestation (can be overridden per suite) */
     defaultCommand?: string;
+    /** Key provider configuration for signing attestations */
+    keyProvider?: KeyProviderSettings;
 }
 
 /**
@@ -92,7 +100,7 @@ export declare function checkOpenSSL(): Promise<string>;
  * Algorithm:
  * 1. List all files in packages (respecting ignore globs)
  * 2. Sort files lexicographically by relative path
- * 3. For each file: compute SHA256(relativePath + "\0" + content)
+ * 3. For each file: compute SHA256(relativePath + ":" + content)
  * 4. Concatenate all file hashes in sorted order
  * 5. Compute final SHA256 of concatenated hashes
  * 6. Return "sha256:" + hex(fingerprint)
@@ -134,90 +142,374 @@ export declare class ConfigNotFoundError extends Error {
  * Zod schema for the full configuration file.
  */
 declare const configSchema: 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;
+    }>>>;
+    groups: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
     settings: z.ZodDefault<z.ZodObject<{
         attestationsPath: z.ZodDefault<z.ZodString>;
         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>;
+            }, "strict", z.ZodTypeAny, {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            }, {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            }>>;
+            type: z.ZodUnion<[z.ZodEnum<["filesystem", "1password"]>, z.ZodString]>;
+        }, "strict", z.ZodTypeAny, {
+            options?: {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            } | undefined;
+            type: string;
+        }, {
+            options?: {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            } | undefined;
+            type: string;
+        }>>;
         maxAgeDays: z.ZodDefault<z.ZodNumber>;
         publicKeyPath: z.ZodDefault<z.ZodString>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         attestationsPath: z.ZodDefault<z.ZodString>;
         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>;
+            }, "strict", z.ZodTypeAny, {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            }, {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            }>>;
+            type: z.ZodUnion<[z.ZodEnum<["filesystem", "1password"]>, z.ZodString]>;
+        }, "strict", z.ZodTypeAny, {
+            options?: {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            } | undefined;
+            type: string;
+        }, {
+            options?: {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            } | undefined;
+            type: string;
+        }>>;
         maxAgeDays: z.ZodDefault<z.ZodNumber>;
         publicKeyPath: z.ZodDefault<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         attestationsPath: z.ZodDefault<z.ZodString>;
         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>;
+            }, "strict", z.ZodTypeAny, {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            }, {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            }>>;
+            type: z.ZodUnion<[z.ZodEnum<["filesystem", "1password"]>, z.ZodString]>;
+        }, "strict", z.ZodTypeAny, {
+            options?: {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            } | undefined;
+            type: string;
+        }, {
+            options?: {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            } | undefined;
+            type: string;
+        }>>;
         maxAgeDays: z.ZodDefault<z.ZodNumber>;
         publicKeyPath: z.ZodDefault<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>>;
-    suites: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodObject<{
+    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.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[];
+        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[];
+        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[];
+        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[];
+        packages?: string[] | undefined;
+        timeout?: 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;
+    groups?: Record<string, string[]> | undefined;
     settings: {
         attestationsPath: string;
         defaultCommand?: string | undefined;
+        keyProvider?: {
+            options?: {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            } | undefined;
+            type: string;
+        } | undefined;
         maxAgeDays: number;
         publicKeyPath: string;
     } & { [k: string]: unknown };
     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[];
+        packages?: string[] | undefined;
+        timeout?: string | undefined;
     }>;
+    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;
+    groups?: Record<string, string[]> | undefined;
     settings?: undefined | z.objectInputType<{
         attestationsPath: z.ZodDefault<z.ZodString>;
         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>;
+            }, "strict", z.ZodTypeAny, {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            }, {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            }>>;
+            type: z.ZodUnion<[z.ZodEnum<["filesystem", "1password"]>, z.ZodString]>;
+        }, "strict", z.ZodTypeAny, {
+            options?: {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            } | undefined;
+            type: string;
+        }, {
+            options?: {
+                account?: string | undefined;
+                itemName?: string | undefined;
+                privateKeyPath?: string | undefined;
+                vault?: string | undefined;
+            } | undefined;
+            type: string;
+        }>>;
         maxAgeDays: z.ZodDefault<z.ZodNumber>;
         publicKeyPath: z.ZodDefault<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">;
     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[];
+        packages?: string[] | undefined;
+        timeout?: string | undefined;
     }>;
+    team?: Record<string, {
+        email?: string | undefined;
+        github?: string | undefined;
+        name: string;
+        publicKey: string;
+    }> | undefined;
     version: 1;
 }>;
 
@@ -249,6 +541,31 @@ export declare function createAttestation(params: {
     suite: string;
 }): Attestation;
 
+/**
+ * Create a seal by signing the canonical string: gateId:fingerprint:timestamp
+ *
+ * @param options - Seal creation options
+ * @returns The created seal
+ * @throws Error if signing fails
+ * @public
+ */
+export declare function createSeal(options: CreateSealOptions): Seal;
+
+/**
+ * Options for creating a seal.
+ * @public
+ */
+export declare interface CreateSealOptions {
+    /** Gate identifier (slug) */
+    gateId: string;
+    /** SHA-256 fingerprint of the gate's content */
+    fingerprint: string;
+    /** Team member slug creating the seal */
+    sealedBy: string;
+    /** PEM-encoded Ed25519 private key for signing */
+    privateKey: string;
+}
+
 /**
  * Options for verifying signatures.
  * @public
@@ -262,6 +579,73 @@ export declare interface CryptoVerifyOptions {
     signature: string;
 }
 
+/**
+ * An Ed25519 keypair with base64-encoded public key and PEM-encoded private key.
+ * @public
+ */
+export declare interface Ed25519KeyPair {
+    /** Base64-encoded public key (raw 32 bytes, ~44 characters) */
+    publicKey: string;
+    /** PEM-encoded private key */
+    privateKey: string;
+}
+
+/**
+ * Key provider that stores private keys on the filesystem.
+ *
+ * @remarks
+ * This is the default provider and maintains backward compatibility with
+ * existing attest-it installations. Private keys are stored at:
+ * - macOS/Linux: ~/.config/attest-it/private.pem
+ * - Windows: %APPDATA%\attest-it\private.pem
+ *
+ * @public
+ */
+export declare class FilesystemKeyProvider implements KeyProvider {
+    readonly type = "filesystem";
+    readonly displayName = "Filesystem";
+    private readonly privateKeyPath;
+    /**
+     * Create a new FilesystemKeyProvider.
+     * @param options - Provider options
+     */
+    constructor(options?: FilesystemKeyProviderOptions);
+    /**
+     * Check if this provider is available.
+     * Filesystem provider is always available.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Check if a key exists at the given path.
+     * @param keyRef - Path to the private key file
+     */
+    keyExists(keyRef: string): Promise<boolean>;
+    /**
+     * Get the private key path for signing.
+     * Returns the path directly with a no-op cleanup function.
+     * @param keyRef - Path to the private key file
+     */
+    getPrivateKey(keyRef: string): Promise<KeyRetrievalResult>;
+    /**
+     * Generate a new keypair and store on filesystem.
+     * @param options - Key generation options
+     */
+    generateKeyPair(options: KeygenProviderOptions): Promise<KeyGenerationResult>;
+    /**
+     * Get the configuration for this provider.
+     */
+    getConfig(): KeyProviderConfig;
+}
+
+/**
+ * Options for creating a FilesystemKeyProvider.
+ * @public
+ */
+export declare interface FilesystemKeyProviderOptions {
+    /** Path to the private key file (defaults to OS-specific config dir) */
+    privateKeyPath?: string;
+}
+
 /**
  * Find an attestation for a specific suite.
  *
@@ -286,6 +670,27 @@ export declare function findAttestation(attestations: AttestationsFile, suite: s
  */
 export declare function findConfigPath(startDir?: string): null | string;
 
+/**
+ * Find a team member by their public key.
+ *
+ * @param config - The attest-it configuration
+ * @param publicKey - Base64-encoded Ed25519 public key
+ * @returns The team member with matching public key, or undefined if not found
+ * @public
+ */
+export declare function findTeamMemberByPublicKey(config: AttestItConfig, publicKey: string): TeamMember | undefined;
+
+/**
+ * Fingerprint configuration for gates.
+ * @public
+ */
+export declare interface FingerprintConfig {
+    /** Glob patterns for paths to include in fingerprint */
+    paths: string[];
+    /** Patterns to exclude from fingerprint */
+    exclude?: string[] | undefined;
+}
+
 /**
  * Options for computing a package fingerprint.
  * @public
@@ -312,6 +717,32 @@ export declare interface FingerprintResult {
     fileCount: number;
 }
 
+/**
+ * Gate definition - defines what needs to be signed and who can sign it.
+ * @public
+ */
+export declare interface GateConfig {
+    /** Human-readable name for the gate */
+    name: string;
+    /** Description of what this gate protects */
+    description: string;
+    /** Team member slugs authorized to sign for this gate */
+    authorizedSigners: string[];
+    /** Fingerprint configuration */
+    fingerprint: FingerprintConfig;
+    /** Maximum age before attestation expires (duration string like "30d", "7d", "24h") */
+    maxAge: string;
+}
+
+/**
+ * Generate a new Ed25519 keypair.
+ *
+ * @returns A keypair with base64-encoded public key and PEM-encoded private key
+ * @throws Error if key generation fails
+ * @public
+ */
+export declare function generateEd25519KeyPair(): Ed25519KeyPair;
+
 /**
  * Generate a new RSA-2048 keypair using OpenSSL.
  *
@@ -325,6 +756,25 @@ export declare interface FingerprintResult {
  */
 export declare function generateKeyPair(options?: KeygenOptions): Promise<KeyPaths>;
 
+/**
+ * Get the active identity from a config.
+ *
+ * @param config - LocalConfig object
+ * @returns The active Identity, or undefined if not found
+ * @public
+ */
+export declare function getActiveIdentity(config: LocalConfig): Identity | undefined;
+
+/**
+ * Get all team members authorized to sign for a gate.
+ *
+ * @param config - The attest-it configuration
+ * @param gateId - The gate identifier (slug)
+ * @returns Array of authorized team members, or empty array if gate not found
+ * @public
+ */
+export declare function getAuthorizedSignersForGate(config: AttestItConfig, gateId: string): TeamMember[];
+
 /**
  * Get the default private key path based on OS.
  * - macOS/Linux: ~/.config/attest-it/private.pem
@@ -339,6 +789,75 @@ export declare function getDefaultPrivateKeyPath(): string;
  */
 export declare function getDefaultPublicKeyPath(): string;
 
+/**
+ * Get the gate configuration for a given gate ID.
+ *
+ * @param config - The attest-it configuration
+ * @param gateId - The gate identifier (slug)
+ * @returns The gate configuration, or undefined if not found
+ * @public
+ */
+export declare function getGate(config: AttestItConfig, gateId: string): GateConfig | undefined;
+
+/**
+ * Get the path to the local config file.
+ *
+ * @returns Path to ~/.config/attest-it/config.yaml
+ * @public
+ */
+export declare function getLocalConfigPath(): string;
+
+/**
+ * Extract the public key from an Ed25519 private key.
+ *
+ * @param privateKeyPem - PEM-encoded private key
+ * @returns Base64-encoded public key (raw 32 bytes)
+ * @throws Error if extraction fails
+ * @public
+ */
+export declare function getPublicKeyFromPrivate(privateKeyPem: string): string;
+
+/**
+ * A single identity configuration.
+ * @public
+ */
+export declare interface Identity {
+    /** Identity name (unique identifier) */
+    name: string;
+    /** Email address associated with this identity */
+    email?: string;
+    /** GitHub username associated with this identity */
+    github?: string;
+    /** Base64 Ed25519 public key */
+    publicKey: string;
+    /** Reference to where the private key is stored */
+    privateKey: PrivateKeyRef;
+}
+
+/**
+ * Check if a public key belongs to an authorized signer for a gate.
+ *
+ * @param config - The attest-it configuration
+ * @param gateId - The gate identifier (slug)
+ * @param publicKey - Base64-encoded Ed25519 public key to check
+ * @returns true if the public key belongs to an authorized signer for the gate
+ * @public
+ */
+export declare function isAuthorizedSigner(config: AttestItConfig, gateId: string, publicKey: string): boolean;
+
+/**
+ * Result of key generation.
+ * @public
+ */
+export declare interface KeyGenerationResult {
+    /** Path or reference to the private key */
+    privateKeyRef: string;
+    /** Path to the public key file (always filesystem for commit to repo) */
+    publicKeyPath: string;
+    /** Human-readable storage location description */
+    storageDescription: string;
+}
+
 /**
  * Options for key generation.
  * @public
@@ -352,6 +871,17 @@ export declare interface KeygenOptions {
     force?: boolean;
 }
 
+/**
+ * Options for key generation via provider.
+ * @public
+ */
+export declare interface KeygenProviderOptions {
+    /** Path for public key output (always filesystem) */
+    publicKeyPath: string;
+    /** Overwrite existing keys */
+    force?: boolean;
+}
+
 /**
  * Paths to a generated keypair.
  * @public
@@ -363,6 +893,124 @@ export declare interface KeyPaths {
     publicPath: string;
 }
 
+/**
+ * Abstract interface for key storage providers.
+ * @public
+ */
+export declare interface KeyProvider {
+    /** Unique identifier for this provider type */
+    readonly type: string;
+    /** Human-readable name for display */
+    readonly displayName: string;
+    /**
+     * Check if this provider is available on the current system.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Check if a key exists in this provider.
+     * @param keyRef - Provider-specific key reference
+     */
+    keyExists(keyRef: string): Promise<boolean>;
+    /**
+     * Retrieve the private key for signing.
+     * Returns a temporary file path that can be passed to OpenSSL.
+     * Caller MUST call cleanup() after signing is complete.
+     */
+    getPrivateKey(keyRef: string): Promise<KeyRetrievalResult>;
+    /**
+     * Generate a new keypair and store the private key.
+     * Public key is always written to filesystem for repository commit.
+     */
+    generateKeyPair(options: KeygenProviderOptions): Promise<KeyGenerationResult>;
+    /**
+     * Get the configuration needed to use this provider.
+     */
+    getConfig(): KeyProviderConfig;
+}
+
+/**
+ * Configuration for a key provider instance.
+ * @public
+ */
+export declare interface KeyProviderConfig {
+    /** Provider type identifier */
+    type: string;
+    /** Provider-specific configuration */
+    options: Record<string, unknown>;
+}
+
+/**
+ * Type for a key provider factory function.
+ * @public
+ */
+export declare type KeyProviderFactory = (config: KeyProviderConfig) => KeyProvider;
+
+/**
+ * Registry for key provider implementations.
+ *
+ * @remarks
+ * The registry allows registration of custom key providers and provides
+ * a factory method to create provider instances from configuration.
+ *
+ * Note: This class is used as a namespace for static methods.
+ * @public
+ */
+export declare class KeyProviderRegistry {
+    private static providers;
+    /**
+     * Register a key provider factory.
+     * @param type - Provider type identifier
+     * @param factory - Factory function to create provider instances
+     */
+    static register(type: string, factory: KeyProviderFactory): void;
+    /**
+     * Create a key provider from configuration.
+     * @param config - Provider configuration
+     * @returns A key provider instance
+     * @throws Error if the provider type is not registered
+     */
+    static create(config: KeyProviderConfig): KeyProvider;
+    /**
+     * Get all registered provider types.
+     * @returns Array of provider type identifiers
+     */
+    static getProviderTypes(): string[];
+}
+
+/**
+ * Key provider configuration in settings.
+ * @public
+ */
+export declare interface KeyProviderSettings {
+    /** Provider type identifier */
+    type: string;
+    /** Provider-specific options */
+    options?: {
+        account?: string | undefined;
+        itemName?: string | undefined;
+        privateKeyPath?: string | undefined;
+        vault?: string | undefined;
+    } | undefined;
+}
+
+/**
+ * Result of a key retrieval operation.
+ * @public
+ */
+export declare interface KeyRetrievalResult {
+    /**
+     * Path to the private key file.
+     * For ephemeral providers, this is a temporary file that must be cleaned up.
+     */
+    keyPath: string;
+    /**
+     * Cleanup function to call after signing is complete.
+     * For filesystem provider, this is a no-op.
+     * For 1Password provider, this securely deletes the temp file.
+     */
+    cleanup: () => Promise<void>;
+}
+
 /**
  * List files in packages, respecting ignore patterns (async).
  *
@@ -396,6 +1044,243 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
               */
           export declare function loadConfigSync(configPath?: string): Config;
 
+          /**
+           * Load and validate local config from file (async).
+           *
+           * @param configPath - Optional path to config file. If not provided, uses default location.
+           * @returns Validated LocalConfig object, or null if file does not exist
+           * @throws {LocalConfigValidationError} If validation fails
+           * @public
+           */
+          export declare function loadLocalConfig(configPath?: string): Promise<LocalConfig | null>;
+
+          /**
+           * Load and validate local config from file (sync).
+           *
+           * @param configPath - Optional path to config file. If not provided, uses default location.
+           * @returns Validated LocalConfig object, or null if file does not exist
+           * @throws {LocalConfigValidationError} If validation fails
+           * @public
+           */
+          export declare function loadLocalConfigSync(configPath?: string): LocalConfig | null;
+
+          /**
+           * The local config file structure at ~/.config/attest-it/config.yaml.
+           * @public
+           */
+          export declare interface LocalConfig {
+              /** Name of the currently active identity */
+              activeIdentity: string;
+              /** Map of identity names to identity configurations */
+              identities: Record<string, Identity>;
+          }
+
+          /**
+           * Error thrown when local config validation fails.
+           * @public
+           */
+          export declare class LocalConfigValidationError extends Error {
+              readonly issues: z.ZodIssue[];
+              constructor(message: string, issues: z.ZodIssue[]);
+          }
+
+          /**
+           * Key provider that stores private keys in macOS Keychain.
+           *
+           * @remarks
+           * This provider requires macOS and uses the `security` CLI tool.
+           * Private keys are stored as base64-encoded strings in the keychain and decoded
+           * to temporary files for signing operations.
+           *
+           * @public
+           */
+          export declare class MacOSKeychainKeyProvider implements KeyProvider {
+              readonly type = "macos-keychain";
+              readonly displayName = "macOS Keychain";
+              private readonly itemName;
+              private static readonly ACCOUNT;
+              /**
+               * Create a new MacOSKeychainKeyProvider.
+               * @param options - Provider options
+               */
+              constructor(options: MacOSKeychainKeyProviderOptions);
+              /**
+               * Check if this provider is available.
+               * Only available on macOS platforms.
+               */
+              static isAvailable(): boolean;
+              /**
+               * Check if this provider is available on the current system.
+               */
+              isAvailable(): Promise<boolean>;
+              /**
+               * Check if a key exists in the keychain.
+               * @param keyRef - Item name in keychain
+               */
+              keyExists(keyRef: string): Promise<boolean>;
+              /**
+               * Get the private key from keychain for signing.
+               * Downloads to a temporary file and returns a cleanup function.
+               * @param keyRef - Item name in keychain
+               * @throws Error if the key does not exist in keychain
+               */
+              getPrivateKey(keyRef: string): Promise<KeyRetrievalResult>;
+              /**
+               * Generate a new keypair and store private key in keychain.
+               * Public key is written to filesystem for repository commit.
+               * @param options - Key generation options
+               */
+              generateKeyPair(options: KeygenProviderOptions): Promise<KeyGenerationResult>;
+              /**
+               * Get the configuration for this provider.
+               */
+              getConfig(): KeyProviderConfig;
+          }
+
+          /**
+           * Options for creating a MacOSKeychainKeyProvider.
+           * @public
+           */
+          export declare interface MacOSKeychainKeyProviderOptions {
+              /** Item name in keychain (e.g., "attest-it-private-key") */
+              itemName: string;
+          }
+
+          /**
+           * Information about a 1Password account.
+           * @public
+           */
+          export declare interface OnePasswordAccount {
+              /** Account UUID */
+              account_uuid: string;
+              /** User email address */
+              email: string;
+              /** Account URL */
+              url: string;
+              /** User UUID */
+              user_uuid: string;
+          }
+
+          /**
+           * Key provider that stores private keys in 1Password.
+           *
+           * @remarks
+           * This provider requires the `op` CLI tool to be installed and authenticated.
+           * Private keys are stored as documents in 1Password and downloaded to
+           * temporary files for signing operations.
+           *
+           * @public
+           */
+          export declare class OnePasswordKeyProvider implements KeyProvider {
+              readonly type = "1password";
+              readonly displayName = "1Password";
+              private readonly account?;
+              private readonly vault;
+              private readonly itemName;
+              /**
+               * Create a new OnePasswordKeyProvider.
+               * @param options - Provider options
+               */
+              constructor(options: OnePasswordKeyProviderOptions);
+              /**
+               * Check if the 1Password CLI is installed.
+               * @returns True if `op` command is available
+               */
+              static isInstalled(): Promise<boolean>;
+              /**
+               * List all 1Password accounts.
+               * @returns Array of account information
+               */
+              static listAccounts(): Promise<OnePasswordAccount[]>;
+              /**
+               * List vaults in a specific account.
+               * @param account - Account email (optional if only one account)
+               * @returns Array of vault information
+               */
+              static listVaults(account?: string): Promise<OnePasswordVault[]>;
+              /**
+               * Check if this provider is available.
+               * Requires `op` CLI to be installed and authenticated.
+               */
+              isAvailable(): Promise<boolean>;
+              /**
+               * Check if a key exists in 1Password.
+               * @param keyRef - Item name in 1Password
+               */
+              keyExists(keyRef: string): Promise<boolean>;
+              /**
+               * Get the private key from 1Password for signing.
+               * Downloads to a temporary file and returns a cleanup function.
+               * @param keyRef - Item name in 1Password
+               * @throws Error if the key does not exist in 1Password
+               */
+              getPrivateKey(keyRef: string): Promise<KeyRetrievalResult>;
+              /**
+               * Generate a new keypair and store private key in 1Password.
+               * Public key is written to filesystem for repository commit.
+               * @param options - Key generation options
+               */
+              generateKeyPair(options: KeygenProviderOptions): Promise<KeyGenerationResult>;
+              /**
+               * Get the configuration for this provider.
+               */
+              getConfig(): KeyProviderConfig;
+          }
+
+          /**
+           * Options for creating a OnePasswordKeyProvider.
+           * @public
+           */
+          export declare interface OnePasswordKeyProviderOptions {
+              /** 1Password account email (optional if only one account) */
+              account?: string;
+              /** Vault name or ID where the key is stored */
+              vault: string;
+              /** Item name in 1Password */
+              itemName: string;
+          }
+
+          /**
+           * Information about a 1Password vault.
+           * @public
+           */
+          export declare interface OnePasswordVault {
+              /** Vault UUID */
+              id: string;
+              /** Vault name */
+              name: 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.
            *
@@ -411,10 +1296,6 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
            */
           export declare function readAndVerifyAttestations(options: ReadSignedAttestationsOptions): Promise<AttestationsFile>;
 
-          /**
-           * Attestation file I/O module with JSON canonicalization.
-           */
-
           /**
            * Read attestations file from disk (async).
            *
@@ -435,6 +1316,26 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
            */
           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
@@ -471,6 +1372,70 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
            */
           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 */
+              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
@@ -503,34 +1468,69 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
               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 */
-              privateKeyPath: string;
+              /** 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 */
-              packages: 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[];
           }
 
           /**
@@ -554,6 +1554,21 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
               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.
            *
@@ -582,6 +1597,12 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
            */
           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
@@ -601,6 +1622,17 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
            */
           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.
            *
@@ -620,6 +1652,30 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
            */
           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
@@ -646,6 +1702,16 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
               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
@@ -680,6 +1746,26 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
            */
           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.
            *
@@ -701,8 +1787,12 @@ export declare function listPackageFiles(packages: string[], ignore?: string[],
               filePath: string;
               /** Array of attestations to write */
               attestations: Attestation[];
-              /** Path to the private key for signing */
-              privateKeyPath: string;
+              /** Path to the private key for signing (legacy) */
+              privateKeyPath?: string;
+              /** Key provider for signing */
+              keyProvider?: KeyProvider;
+              /** Key reference for the provider */
+              keyRef?: string;
           }
 
           export { }