@attest-it/core 0.0.2 → 0.4.0

package/dist/index.d.cts

@@ -4,6 +4,25 @@ import { z } from 'zod';
  * Core types for attest-it attestation system.
  * @packageDocumentation
  */
+/**
+ * Key provider configuration in settings.
+ * @public
+ */
+interface KeyProviderSettings {
+    /** Provider type identifier */
+    type: string;
+    /** Provider-specific options */
+    options?: {
+        /** Path to private key (filesystem provider) */
+        privateKeyPath?: string | undefined;
+        /** Vault name (1Password provider) */
+        vault?: string | undefined;
+        /** Item name (1Password provider) */
+        itemName?: string | undefined;
+        /** Account identifier (1Password provider) */
+        account?: string | undefined;
+    } | undefined;
+}
 /**
  * Settings from the configuration file.
  * @public
@@ -17,24 +36,75 @@ 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;
+}
+/**
+ * Team member configuration.
+ * @public
+ */
+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;
+}
+/**
+ * Fingerprint configuration for gates.
+ * @public
+ */
+interface FingerprintConfig {
+    /** Glob patterns for paths to include in fingerprint */
+    paths: string[];
+    /** Patterns to exclude from fingerprint */
+    exclude?: string[] | undefined;
+}
+/**
+ * Gate definition - defines what needs to be signed and who can sign it.
+ * @public
+ */
+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;
 }
 /**
  * Suite definition from the configuration file.
+ * Suites are CLI-layer extensions of gates with command execution capabilities.
  * @public
  */
 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[];
 }
 /**
  * Full configuration file structure.
@@ -45,8 +115,14 @@ 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[]>;
 }
 /**
  * A single attestation entry.
@@ -114,53 +190,251 @@ declare const configSchema: z.ZodObject<{
         publicKeyPath: z.ZodDefault<z.ZodString>;
         attestationsPath: z.ZodDefault<z.ZodString>;
         defaultCommand: z.ZodOptional<z.ZodString>;
+        keyProvider: z.ZodOptional<z.ZodObject<{
+            type: z.ZodUnion<[z.ZodEnum<["filesystem", "1password"]>, z.ZodString]>;
+            options: z.ZodOptional<z.ZodObject<{
+                privateKeyPath: z.ZodOptional<z.ZodString>;
+                account: z.ZodOptional<z.ZodString>;
+                vault: z.ZodOptional<z.ZodString>;
+                itemName: z.ZodOptional<z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            }, {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            }>>;
+        }, "strict", z.ZodTypeAny, {
+            type: string;
+            options?: {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            } | undefined;
+        }, {
+            type: string;
+            options?: {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            } | undefined;
+        }>>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         maxAgeDays: z.ZodDefault<z.ZodNumber>;
         publicKeyPath: z.ZodDefault<z.ZodString>;
         attestationsPath: z.ZodDefault<z.ZodString>;
         defaultCommand: z.ZodOptional<z.ZodString>;
+        keyProvider: z.ZodOptional<z.ZodObject<{
+            type: z.ZodUnion<[z.ZodEnum<["filesystem", "1password"]>, z.ZodString]>;
+            options: z.ZodOptional<z.ZodObject<{
+                privateKeyPath: z.ZodOptional<z.ZodString>;
+                account: z.ZodOptional<z.ZodString>;
+                vault: z.ZodOptional<z.ZodString>;
+                itemName: z.ZodOptional<z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            }, {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            }>>;
+        }, "strict", z.ZodTypeAny, {
+            type: string;
+            options?: {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            } | undefined;
+        }, {
+            type: string;
+            options?: {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            } | undefined;
+        }>>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         maxAgeDays: z.ZodDefault<z.ZodNumber>;
         publicKeyPath: z.ZodDefault<z.ZodString>;
         attestationsPath: z.ZodDefault<z.ZodString>;
         defaultCommand: z.ZodOptional<z.ZodString>;
+        keyProvider: z.ZodOptional<z.ZodObject<{
+            type: z.ZodUnion<[z.ZodEnum<["filesystem", "1password"]>, z.ZodString]>;
+            options: z.ZodOptional<z.ZodObject<{
+                privateKeyPath: z.ZodOptional<z.ZodString>;
+                account: z.ZodOptional<z.ZodString>;
+                vault: z.ZodOptional<z.ZodString>;
+                itemName: z.ZodOptional<z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            }, {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            }>>;
+        }, "strict", z.ZodTypeAny, {
+            type: string;
+            options?: {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            } | undefined;
+        }, {
+            type: string;
+            options?: {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            } | undefined;
+        }>>;
     }, z.ZodTypeAny, "passthrough">>>;
-    suites: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodObject<{
+    team: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        github: z.ZodOptional<z.ZodString>;
+        publicKey: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        publicKey: string;
+        email?: string | undefined;
+        github?: string | undefined;
+    }, {
+        name: string;
+        publicKey: string;
+        email?: string | undefined;
+        github?: string | undefined;
+    }>>>;
+    gates: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        authorizedSigners: z.ZodArray<z.ZodString, "many">;
+        fingerprint: z.ZodObject<{
+            paths: z.ZodArray<z.ZodString, "many">;
+            exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            paths: string[];
+            exclude?: string[] | undefined;
+        }, {
+            paths: string[];
+            exclude?: string[] | undefined;
+        }>;
+        maxAge: z.ZodEffects<z.ZodString, string, string>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        authorizedSigners: string[];
+        fingerprint: {
+            paths: string[];
+            exclude?: string[] | undefined;
+        };
+        maxAge: string;
+    }, {
+        name: string;
+        description: string;
+        authorizedSigners: string[];
+        fingerprint: {
+            paths: string[];
+            exclude?: string[] | undefined;
+        };
+        maxAge: string;
+    }>>>;
+    suites: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+        gate: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
-        packages: z.ZodArray<z.ZodString, "many">;
+        packages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         ignore: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         command: z.ZodOptional<z.ZodString>;
+        timeout: z.ZodOptional<z.ZodString>;
+        interactive: z.ZodOptional<z.ZodBoolean>;
         invalidates: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        depends_on: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
-        packages: string[];
         description?: string | undefined;
+        gate?: string | undefined;
+        packages?: string[] | undefined;
         files?: string[] | undefined;
         ignore?: string[] | undefined;
         command?: string | undefined;
+        timeout?: string | undefined;
+        interactive?: boolean | undefined;
         invalidates?: string[] | undefined;
+        depends_on?: string[] | undefined;
     }, {
-        packages: string[];
         description?: string | undefined;
+        gate?: string | undefined;
+        packages?: string[] | undefined;
         files?: string[] | undefined;
         ignore?: string[] | undefined;
         command?: string | undefined;
+        timeout?: string | undefined;
+        interactive?: boolean | undefined;
         invalidates?: string[] | undefined;
+        depends_on?: string[] | undefined;
+    }>, {
+        description?: string | undefined;
+        gate?: string | undefined;
+        packages?: string[] | undefined;
+        files?: string[] | undefined;
+        ignore?: string[] | undefined;
+        command?: string | undefined;
+        timeout?: string | undefined;
+        interactive?: boolean | undefined;
+        invalidates?: string[] | undefined;
+        depends_on?: string[] | undefined;
+    }, {
+        description?: string | undefined;
+        gate?: string | undefined;
+        packages?: string[] | undefined;
+        files?: string[] | undefined;
+        ignore?: string[] | undefined;
+        command?: string | undefined;
+        timeout?: string | undefined;
+        interactive?: boolean | undefined;
+        invalidates?: string[] | undefined;
+        depends_on?: string[] | undefined;
     }>>, Record<string, {
-        packages: string[];
         description?: string | undefined;
+        gate?: string | undefined;
+        packages?: string[] | undefined;
         files?: string[] | undefined;
         ignore?: string[] | undefined;
         command?: string | undefined;
+        timeout?: string | undefined;
+        interactive?: boolean | undefined;
         invalidates?: string[] | undefined;
+        depends_on?: string[] | undefined;
     }>, Record<string, {
-        packages: string[];
         description?: string | undefined;
+        gate?: string | undefined;
+        packages?: string[] | undefined;
         files?: string[] | undefined;
         ignore?: string[] | undefined;
         command?: string | undefined;
+        timeout?: string | undefined;
+        interactive?: boolean | undefined;
         invalidates?: string[] | undefined;
+        depends_on?: string[] | undefined;
     }>>;
+    groups: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
 }, "strict", z.ZodTypeAny, {
     version: 1;
     settings: {
@@ -168,33 +442,119 @@ declare const configSchema: z.ZodObject<{
         publicKeyPath: string;
         attestationsPath: string;
         defaultCommand?: string | undefined;
+        keyProvider?: {
+            type: string;
+            options?: {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            } | undefined;
+        } | undefined;
     } & {
         [k: string]: unknown;
     };
     suites: Record<string, {
-        packages: string[];
         description?: string | undefined;
+        gate?: string | undefined;
+        packages?: string[] | undefined;
         files?: string[] | undefined;
         ignore?: string[] | undefined;
         command?: string | undefined;
+        timeout?: string | undefined;
+        interactive?: boolean | undefined;
         invalidates?: string[] | undefined;
+        depends_on?: string[] | undefined;
     }>;
+    team?: Record<string, {
+        name: string;
+        publicKey: string;
+        email?: string | undefined;
+        github?: string | undefined;
+    }> | undefined;
+    gates?: Record<string, {
+        name: string;
+        description: string;
+        authorizedSigners: string[];
+        fingerprint: {
+            paths: string[];
+            exclude?: string[] | undefined;
+        };
+        maxAge: string;
+    }> | undefined;
+    groups?: Record<string, string[]> | undefined;
 }, {
     version: 1;
     suites: Record<string, {
-        packages: string[];
         description?: string | undefined;
+        gate?: string | undefined;
+        packages?: string[] | undefined;
         files?: string[] | undefined;
         ignore?: string[] | undefined;
         command?: string | undefined;
+        timeout?: string | undefined;
+        interactive?: boolean | undefined;
         invalidates?: string[] | undefined;
+        depends_on?: string[] | undefined;
     }>;
     settings?: z.objectInputType<{
         maxAgeDays: z.ZodDefault<z.ZodNumber>;
         publicKeyPath: z.ZodDefault<z.ZodString>;
         attestationsPath: z.ZodDefault<z.ZodString>;
         defaultCommand: z.ZodOptional<z.ZodString>;
+        keyProvider: z.ZodOptional<z.ZodObject<{
+            type: z.ZodUnion<[z.ZodEnum<["filesystem", "1password"]>, z.ZodString]>;
+            options: z.ZodOptional<z.ZodObject<{
+                privateKeyPath: z.ZodOptional<z.ZodString>;
+                account: z.ZodOptional<z.ZodString>;
+                vault: z.ZodOptional<z.ZodString>;
+                itemName: z.ZodOptional<z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            }, {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            }>>;
+        }, "strict", z.ZodTypeAny, {
+            type: string;
+            options?: {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            } | undefined;
+        }, {
+            type: string;
+            options?: {
+                privateKeyPath?: string | undefined;
+                account?: string | undefined;
+                vault?: string | undefined;
+                itemName?: string | undefined;
+            } | undefined;
+        }>>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
+    team?: Record<string, {
+        name: string;
+        publicKey: string;
+        email?: string | undefined;
+        github?: string | undefined;
+    }> | undefined;
+    gates?: Record<string, {
+        name: string;
+        description: string;
+        authorizedSigners: string[];
+        fingerprint: {
+            paths: string[];
+            exclude?: string[] | undefined;
+        };
+        maxAge: string;
+    }> | undefined;
+    groups?: Record<string, string[]> | undefined;
 }>;
 /**
  * Type inference from Zod schema (should match AttestItConfig).
@@ -307,7 +667,7 @@ interface FingerprintResult {
  * 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)
@@ -340,8 +700,98 @@ declare function computeFingerprintSync(options: FingerprintOptions): Fingerprin
 declare function listPackageFiles(packages: string[], ignore?: string[], baseDir?: string): Promise<string[]>;
 
 /**
- * Attestation file I/O module with JSON canonicalization.
+ * Types and interfaces for key provider system.
+ *
+ * @remarks
+ * The key provider system abstracts key storage backends, allowing private keys
+ * to be stored in various locations (filesystem, 1Password, etc.) while maintaining
+ * a consistent interface for key retrieval and signing operations.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Configuration for a key provider instance.
+ * @public
+ */
+interface KeyProviderConfig {
+    /** Provider type identifier */
+    type: string;
+    /** Provider-specific configuration */
+    options: Record<string, unknown>;
+}
+/**
+ * Result of a key retrieval operation.
+ * @public
+ */
+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>;
+}
+/**
+ * Result of key generation.
+ * @public
+ */
+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 via provider.
+ * @public
+ */
+interface KeygenProviderOptions {
+    /** Path for public key output (always filesystem) */
+    publicKeyPath: string;
+    /** Overwrite existing keys */
+    force?: boolean;
+}
+/**
+ * Abstract interface for key storage providers.
+ * @public
  */
+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;
+}
 
 /**
  * Read attestations file from disk (async).
@@ -463,8 +913,12 @@ interface WriteSignedAttestationsOptions {
     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;
 }
 /**
  * Options for reading and verifying signed attestations.
@@ -550,8 +1004,12 @@ interface KeygenOptions {
  * @public
  */
 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: string | Buffer;
 }
@@ -597,7 +1055,7 @@ declare function getDefaultPublicKeyPath(): string;
  * @throws Error if OpenSSL fails or keys exist without force
  * @public
  */
-declare function generateKeyPair(options?: KeygenOptions): Promise<KeyPaths>;
+declare function generateKeyPair$1(options?: KeygenOptions): Promise<KeyPaths>;
 /**
  * Sign data using an RSA private key with SHA-256.
  *
@@ -609,7 +1067,7 @@ declare function generateKeyPair(options?: KeygenOptions): Promise<KeyPaths>;
  * @throws Error if signing fails
  * @public
  */
-declare function sign(options: SignOptions): Promise<string>;
+declare function sign$1(options: SignOptions): Promise<string>;
 /**
  * Verify a signature using an RSA public key with SHA-256.
  *
@@ -621,7 +1079,7 @@ declare function sign(options: SignOptions): Promise<string>;
  * @throws Error if verification fails (not just invalid signature)
  * @public
  */
-declare function verify(options: VerifyOptions$1): Promise<boolean>;
+declare function verify$1(options: VerifyOptions$1): Promise<boolean>;
 /**
  * Set restrictive permissions on a private key file.
  * @param keyPath - Path to the private key
@@ -629,6 +1087,65 @@ declare function verify(options: VerifyOptions$1): Promise<boolean>;
  */
 declare function setKeyPermissions(keyPath: string): Promise<void>;
 
+/**
+ * Ed25519 cryptographic operations using Node.js native crypto module.
+ *
+ * @remarks
+ * This module provides Ed25519 digital signature operations using Node.js
+ * native crypto support (available in Node 18+). Ed25519 offers better security
+ * and performance than RSA-2048 with much smaller key and signature sizes.
+ *
+ * @packageDocumentation
+ */
+/**
+ * An Ed25519 keypair with base64-encoded public key and PEM-encoded private key.
+ * @public
+ */
+interface KeyPair {
+    /** Base64-encoded public key (raw 32 bytes, ~44 characters) */
+    publicKey: string;
+    /** PEM-encoded private key */
+    privateKey: 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
+ */
+declare function generateKeyPair(): KeyPair;
+/**
+ * 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
+ */
+declare function sign(data: Buffer | string, privateKeyPem: string): string;
+/**
+ * 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
+ */
+declare function verify(data: Buffer | string, signature: string, publicKeyBase64: string): boolean;
+/**
+ * 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
+ */
+declare function getPublicKeyFromPrivate(privateKeyPem: string): string;
+
 /**
  * Verification logic for attestations.
  * @packageDocumentation
@@ -677,6 +1194,632 @@ interface VerifyResult {
  */
 declare function verifyAttestations(options: VerifyOptions): Promise<VerifyResult>;
 
+/**
+ * Filesystem-based key provider implementation.
+ *
+ * @remarks
+ * This provider stores private keys on the local filesystem, maintaining
+ * backward compatibility with the existing attest-it key storage behavior.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for creating a FilesystemKeyProvider.
+ * @public
+ */
+interface FilesystemKeyProviderOptions {
+    /** Path to the private key file (defaults to OS-specific config dir) */
+    privateKeyPath?: 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
+ */
+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;
+}
+
+/**
+ * 1Password-based key provider implementation.
+ *
+ * @remarks
+ * This provider stores private keys in 1Password and retrieves them via the
+ * `op` CLI tool. Keys are downloaded to a temporary file for signing and
+ * securely deleted after use.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for creating a OnePasswordKeyProvider.
+ * @public
+ */
+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 account.
+ * @public
+ */
+interface OnePasswordAccount {
+    /** Account UUID */
+    account_uuid: string;
+    /** User email address */
+    email: string;
+    /** Account URL */
+    url: string;
+    /** User UUID */
+    user_uuid: string;
+}
+/**
+ * Information about a 1Password vault.
+ * @public
+ */
+interface OnePasswordVault {
+    /** Vault UUID */
+    id: string;
+    /** Vault name */
+    name: 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
+ */
+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;
+}
+
+/**
+ * macOS Keychain-based key provider implementation.
+ *
+ * @remarks
+ * This provider stores private keys in the macOS Keychain and retrieves them via the
+ * `security` CLI tool. Keys are stored as base64-encoded strings and downloaded to
+ * temporary files for signing operations, then securely deleted after use.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for creating a MacOSKeychainKeyProvider.
+ * @public
+ */
+interface MacOSKeychainKeyProviderOptions {
+    /** Item name in keychain (e.g., "attest-it-private-key") */
+    itemName: string;
+}
+/**
+ * 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
+ */
+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;
+}
+
+/**
+ * Registry for key provider implementations.
+ *
+ * @remarks
+ * The registry maintains a mapping of provider types to factory functions,
+ * allowing dynamic creation of key providers based on configuration.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Type for a key provider factory function.
+ * @public
+ */
+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
+ */
+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[];
+}
+
+/**
+ * Identity system types for attest-it v2.0.
+ * @packageDocumentation
+ */
+/**
+ * Private key reference - points to where the key is stored.
+ * @public
+ */
+type PrivateKeyRef = {
+    type: 'file';
+    path: string;
+} | {
+    type: 'keychain';
+    service: string;
+    account: string;
+} | {
+    type: '1password';
+    account?: string;
+    vault: string;
+    item: string;
+    field?: string;
+};
+/**
+ * A single identity configuration.
+ * @public
+ */
+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;
+}
+/**
+ * The local config file structure at ~/.config/attest-it/config.yaml.
+ * @public
+ */
+interface LocalConfig {
+    /** Name of the currently active identity */
+    activeIdentity: string;
+    /** Map of identity names to identity configurations */
+    identities: Record<string, Identity>;
+}
+
+/**
+ * Configuration loading for local identity system.
+ * @packageDocumentation
+ */
+
+/**
+ * Error thrown when local config validation fails.
+ * @public
+ */
+declare class LocalConfigValidationError extends Error {
+    readonly issues: z.ZodIssue[];
+    constructor(message: string, issues: z.ZodIssue[]);
+}
+/**
+ * Get the path to the local config file.
+ *
+ * @returns Path to ~/.config/attest-it/config.yaml
+ * @public
+ */
+declare function getLocalConfigPath(): string;
+/**
+ * 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
+ */
+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
+ */
+declare function loadLocalConfigSync(configPath?: string): LocalConfig | null;
+/**
+ * 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
+ */
+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
+ */
+declare function saveLocalConfigSync(config: LocalConfig, configPath?: string): void;
+/**
+ * Get the active identity from a config.
+ *
+ * @param config - LocalConfig object
+ * @returns The active Identity, or undefined if not found
+ * @public
+ */
+declare function getActiveIdentity(config: LocalConfig): Identity | undefined;
+
+/**
+ * Authorization logic for attest-it v2.0.
+ * @packageDocumentation
+ */
+
+/**
+ * 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
+ */
+declare function isAuthorizedSigner(config: AttestItConfig, gateId: string, publicKey: string): boolean;
+/**
+ * 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
+ */
+declare function getAuthorizedSignersForGate(config: AttestItConfig, gateId: string): TeamMember[];
+/**
+ * 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
+ */
+declare function findTeamMemberByPublicKey(config: AttestItConfig, publicKey: string): TeamMember | undefined;
+/**
+ * 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
+ */
+declare function getGate(config: AttestItConfig, gateId: string): GateConfig | undefined;
+/**
+ * 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
+ */
+declare function parseDuration(duration: string): number;
+
+/**
+ * Seal types for attest-it v2.0.
+ * @packageDocumentation
+ */
+/**
+ * A seal represents a cryptographic attestation that a gate's fingerprint
+ * was signed by an authorized team member.
+ * @public
+ */
+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
+ */
+interface SealsFile {
+    /** Schema version for forward compatibility */
+    version: 1;
+    /** Map of gate slugs to their seals */
+    seals: Record<string, Seal>;
+}
+
+/**
+ * Seal operations for creating, verifying, and managing seals.
+ * @packageDocumentation
+ */
+
+/**
+ * Options for creating a seal.
+ * @public
+ */
+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;
+}
+/**
+ * Result of seal signature verification.
+ * @public
+ */
+interface SignatureVerificationResult {
+    /** Whether the seal signature is valid */
+    valid: boolean;
+    /** Error message if verification failed */
+    error?: string;
+}
+/**
+ * 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
+ */
+declare function createSeal(options: CreateSealOptions): Seal;
+/**
+ * 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
+ */
+declare function verifySeal(seal: Seal, config: AttestItConfig): SignatureVerificationResult;
+/**
+ * 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
+ */
+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
+ */
+declare function readSealsSync(dir: string): SealsFile;
+/**
+ * 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
+ */
+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
+ */
+declare function writeSealsSync(dir: string, sealsFile: SealsFile): void;
+
+/**
+ * Seal verification logic and states.
+ * @packageDocumentation
+ */
+
+/**
+ * Verification state for a gate's seal.
+ * @public
+ */
+type VerificationState = 'VALID' | 'MISSING' | 'STALE' | 'FINGERPRINT_MISMATCH' | 'INVALID_SIGNATURE' | 'UNKNOWN_SIGNER';
+/**
+ * Result of verifying a single gate's seal.
+ * @public
+ */
+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;
+}
+/**
+ * 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
+ */
+declare function verifyGateSeal(config: AttestItConfig, gateId: string, seals: SealsFile, currentFingerprint: string): SealVerificationResult;
+/**
+ * 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
+ */
+declare function verifyAllSeals(config: AttestItConfig, seals: SealsFile, fingerprints: Record<string, string>): SealVerificationResult[];
+
 /**
  * @attest-it/core
  *
@@ -689,4 +1832,4 @@ declare function verifyAttestations(options: VerifyOptions): Promise<VerifyResul
  */
 declare const version = "0.0.0";
 
-export { type AttestItConfig, type AttestItSettings, type Attestation, type AttestationsFile, type Config, ConfigNotFoundError, ConfigValidationError, type VerifyOptions$1 as CryptoVerifyOptions, type FingerprintOptions, type FingerprintResult, type KeyPaths, type KeygenOptions, type ReadSignedAttestationsOptions, type SignOptions, SignatureInvalidError, type SuiteConfig, type SuiteVerificationResult, type VerificationStatus, type VerifyOptions, type VerifyResult, type WriteSignedAttestationsOptions, canonicalizeAttestations, checkOpenSSL, computeFingerprint, computeFingerprintSync, createAttestation, findAttestation, findConfigPath, generateKeyPair, getDefaultPrivateKeyPath, getDefaultPublicKeyPath, listPackageFiles, loadConfig, loadConfigSync, readAndVerifyAttestations, readAttestations, readAttestationsSync, removeAttestation, resolveConfigPaths, setKeyPermissions, sign, toAttestItConfig, upsertAttestation, verify, verifyAttestations, version, writeAttestations, writeAttestationsSync, writeSignedAttestations };
+export { type AttestItConfig, type AttestItSettings, type Attestation, type AttestationsFile, type Config, ConfigNotFoundError, ConfigValidationError, type CreateSealOptions, type VerifyOptions$1 as CryptoVerifyOptions, type KeyPair as Ed25519KeyPair, FilesystemKeyProvider, type FilesystemKeyProviderOptions, type FingerprintConfig, type FingerprintOptions, type FingerprintResult, type GateConfig, type Identity, type KeyGenerationResult, type KeyPaths, type KeyProvider, type KeyProviderConfig, type KeyProviderFactory, KeyProviderRegistry, type KeyProviderSettings, type KeyRetrievalResult, type KeygenOptions, type KeygenProviderOptions, type LocalConfig, LocalConfigValidationError, MacOSKeychainKeyProvider, type MacOSKeychainKeyProviderOptions, type OnePasswordAccount, OnePasswordKeyProvider, type OnePasswordKeyProviderOptions, type OnePasswordVault, type PrivateKeyRef, type ReadSignedAttestationsOptions, type Seal, type SealVerificationResult, type SealsFile, type SignOptions, SignatureInvalidError, type SignatureVerificationResult, type SuiteConfig, type SuiteVerificationResult, type TeamMember, type VerificationState, type VerificationStatus, type VerifyOptions, type VerifyResult, type WriteSignedAttestationsOptions, canonicalizeAttestations, checkOpenSSL, computeFingerprint, computeFingerprintSync, createAttestation, createSeal, findAttestation, findConfigPath, findTeamMemberByPublicKey, generateKeyPair as generateEd25519KeyPair, generateKeyPair$1 as generateKeyPair, getActiveIdentity, getAuthorizedSignersForGate, getDefaultPrivateKeyPath, getDefaultPublicKeyPath, getGate, getLocalConfigPath, getPublicKeyFromPrivate, isAuthorizedSigner, listPackageFiles, loadConfig, loadConfigSync, loadLocalConfig, loadLocalConfigSync, parseDuration, readAndVerifyAttestations, readAttestations, readAttestationsSync, readSeals, readSealsSync, removeAttestation, resolveConfigPaths, saveLocalConfig, saveLocalConfigSync, setKeyPermissions, sign$1 as sign, sign as signEd25519, toAttestItConfig, upsertAttestation, verify$1 as verify, verifyAllSeals, verifyAttestations, verify as verifyEd25519, verifyGateSeal, verifySeal, version, writeAttestations, writeAttestationsSync, writeSeals, writeSealsSync, writeSignedAttestations };