@attest-it/core 0.0.0

package/dist/core-unstripped.d.ts

@@ -0,0 +1,711 @@
+import { z } from 'zod';
+
+/**
+ * Supported signature algorithms.
+ * @public
+ */
+export declare type Algorithm = 'ed25519' | 'rsa';
+
+/**
+ * A single attestation entry.
+ * @public
+ */
+export declare interface Attestation {
+    /** Test suite name (e.g., "unit", "integration") */
+    suite: string;
+    /** SHA-256 fingerprint of test files in format "sha256:<hex>" */
+    fingerprint: string;
+    /** ISO 8601 timestamp when attestation was created */
+    attestedAt: string;
+    /** User who created the attestation */
+    attestedBy: string;
+    /** Command that was executed */
+    command: string;
+    /** Exit code (must be 0 for valid attestation) */
+    exitCode: 0;
+}
+
+/**
+ * Attestations file structure.
+ * @public
+ */
+export declare interface AttestationsFile {
+    /** Schema version for forward compatibility */
+    schemaVersion: '1';
+    /** Array of attestations */
+    attestations: Attestation[];
+    /** Base64-encoded signature over canonical attestations array */
+    signature: string;
+}
+
+/**
+ * Full configuration file structure.
+ * @public
+ */
+export declare interface AttestItConfig {
+    /** Configuration schema version */
+    version: 1;
+    /** Global settings for attestation behavior */
+    settings: AttestItSettings;
+    /** Named test suites with their configurations */
+    suites: Record<string, SuiteConfig>;
+}
+
+/**
+ * Settings from the configuration file.
+ * @public
+ */
+export declare interface AttestItSettings {
+    /** Maximum age in days before an attestation expires */
+    maxAgeDays: number;
+    /** Path to the public key file used for signature verification */
+    publicKeyPath: string;
+    /** Path to the attestations file */
+    attestationsPath: string;
+    /** Default command to execute for attestation (can be overridden per suite) */
+    defaultCommand?: string;
+    /** Cryptographic algorithm to use for signatures */
+    algorithm: 'ed25519' | 'rsa';
+}
+
+/**
+ * Compute canonical JSON representation for signing.
+ *
+ * Implements RFC 8785 JSON Canonicalization Scheme. The canonicalize package provides:
+ * 1. Keys sorted lexicographically (Unicode code point order)
+ * 2. No whitespace between tokens
+ * 3. No trailing commas
+ * 4. Strings escaped using \uXXXX for control characters
+ * 5. Numbers: no leading zeros, no +, use lowercase 'e' for exponent
+ * 6. UTF-8 encoding
+ *
+ * @param attestations - Array of attestations to canonicalize
+ * @returns Canonical JSON string representation
+ * @throws Error if canonicalization fails
+ * @public
+ */
+export declare function canonicalizeAttestations(attestations: Attestation[]): string;
+
+/**
+ * Check if OpenSSL is available and get version info.
+ * @returns OpenSSL version string
+ * @throws Error if OpenSSL is not available
+ * @public
+ */
+export declare function checkOpenSSL(): Promise<string>;
+
+/**
+ * Compute a deterministic fingerprint for a set of packages (async).
+ *
+ * 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)
+ * 4. Concatenate all file hashes in sorted order
+ * 5. Compute final SHA256 of concatenated hashes
+ * 6. Return "sha256:" + hex(fingerprint)
+ *
+ * @param options - Configuration for fingerprint computation
+ * @returns Result containing the fingerprint hash and list of files processed
+ * @throws Error if packages array is empty or if package paths don't exist
+ * @public
+ */
+export declare function computeFingerprint(options: FingerprintOptions): Promise<FingerprintResult>;
+
+/**
+ * Compute a deterministic fingerprint for a set of packages (sync).
+ *
+ * @param options - Configuration for fingerprint computation
+ * @returns Result containing the fingerprint hash and list of files processed
+ * @throws Error if packages array is empty or if package paths don't exist
+ * @public
+ * @see {@link computeFingerprint} for the async version
+ */
+export declare function computeFingerprintSync(options: FingerprintOptions): FingerprintResult;
+
+/**
+ * Type inference from Zod schema (should match AttestItConfig).
+ * This is the same as AttestItConfig but with defaults applied.
+ * @public
+ */
+export declare type Config = z.infer<typeof configSchema>;
+
+/**
+ * Error thrown when configuration file cannot be found.
+ * @public
+ */
+export declare class ConfigNotFoundError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Zod schema for the full configuration file.
+ */
+declare const configSchema: z.ZodObject<{
+    settings: z.ZodDefault<z.ZodObject<{
+        algorithm: z.ZodDefault<z.ZodEnum<["ed25519", "rsa"]>>;
+        attestationsPath: z.ZodDefault<z.ZodString>;
+        defaultCommand: z.ZodOptional<z.ZodString>;
+        maxAgeDays: z.ZodDefault<z.ZodNumber>;
+        publicKeyPath: z.ZodDefault<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        algorithm: "ed25519" | "rsa";
+        attestationsPath: string;
+        defaultCommand?: string | undefined;
+        maxAgeDays: number;
+        publicKeyPath: string;
+    }, {
+        algorithm?: "ed25519" | "rsa" | undefined;
+        attestationsPath?: string | undefined;
+        defaultCommand?: string | undefined;
+        maxAgeDays?: number | undefined;
+        publicKeyPath?: string | undefined;
+    }>>;
+    suites: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodObject<{
+        command: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        invalidates: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        packages: z.ZodArray<z.ZodString, "many">;
+    }, "strict", z.ZodTypeAny, {
+        command?: string | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        ignore?: string[] | undefined;
+        invalidates?: string[] | undefined;
+        packages: string[];
+    }, {
+        command?: string | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        ignore?: string[] | undefined;
+        invalidates?: string[] | undefined;
+        packages: string[];
+    }>>, Record<string, {
+        command?: string | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        ignore?: string[] | undefined;
+        invalidates?: string[] | undefined;
+        packages: string[];
+    }>, Record<string, {
+        command?: string | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        ignore?: string[] | undefined;
+        invalidates?: string[] | undefined;
+        packages: string[];
+    }>>;
+    version: z.ZodLiteral<1>;
+}, "strict", z.ZodTypeAny, {
+    settings: {
+        algorithm: "ed25519" | "rsa";
+        attestationsPath: string;
+        defaultCommand?: string | undefined;
+        maxAgeDays: number;
+        publicKeyPath: string;
+    };
+    suites: Record<string, {
+        command?: string | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        ignore?: string[] | undefined;
+        invalidates?: string[] | undefined;
+        packages: string[];
+    }>;
+    version: 1;
+}, {
+    settings?: {
+        algorithm?: "ed25519" | "rsa" | undefined;
+        attestationsPath?: string | undefined;
+        defaultCommand?: string | undefined;
+        maxAgeDays?: number | undefined;
+        publicKeyPath?: string | undefined;
+    } | undefined;
+    suites: Record<string, {
+        command?: string | undefined;
+        description?: string | undefined;
+        files?: string[] | undefined;
+        ignore?: string[] | undefined;
+        invalidates?: string[] | undefined;
+        packages: string[];
+    }>;
+    version: 1;
+}>;
+
+/**
+ * Error thrown when configuration is invalid.
+ * @public
+ */
+export declare class ConfigValidationError extends Error {
+    readonly issues: z.ZodIssue[];
+    constructor(message: string, issues: z.ZodIssue[]);
+}
+
+/**
+ * Create a new attestation entry.
+ *
+ * @param params - Parameters for creating the attestation
+ * @param params.suite - Name of the test suite
+ * @param params.fingerprint - Fingerprint of the packages in sha256 format
+ * @param params.command - Command that was executed
+ * @param params.attestedBy - Optional username (defaults to current OS user)
+ * @returns Validated attestation object
+ * @throws Error if attestation validation fails
+ * @public
+ */
+export declare function createAttestation(params: {
+    attestedBy?: string;
+    command: string;
+    fingerprint: string;
+    suite: string;
+}): Attestation;
+
+/**
+ * Options for verifying signatures.
+ * @public
+ */
+export declare interface CryptoVerifyOptions {
+    /** Path to the public key file */
+    publicKeyPath: string;
+    /** Original data that was signed */
+    data: Buffer | string;
+    /** Base64-encoded signature to verify */
+    signature: string;
+}
+
+/**
+ * Find an attestation for a specific suite.
+ *
+ * @param attestations - Attestations file containing all attestations
+ * @param suite - Name of the suite to find
+ * @returns The attestation if found, undefined otherwise
+ * @public
+ */
+export declare function findAttestation(attestations: AttestationsFile, suite: string): Attestation | undefined;
+
+/**
+ * Find the configuration file in default locations.
+ *
+ * Searches in this order:
+ * 1. .attest-it/config.yaml
+ * 2. .attest-it/config.yml
+ * 3. .attest-it/config.json
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Absolute path to the config file, or null if not found
+ * @public
+ */
+export declare function findConfigPath(startDir?: string): null | string;
+
+/**
+ * Options for computing a package fingerprint.
+ * @public
+ */
+export declare interface FingerprintOptions {
+    /** Package directories to include */
+    packages: string[];
+    /** Glob patterns to exclude from fingerprint */
+    ignore?: string[];
+    /** Base directory for resolving paths */
+    baseDir?: string;
+}
+
+/**
+ * Result of computing a package fingerprint.
+ * @public
+ */
+export declare interface FingerprintResult {
+    /** The fingerprint in "sha256:..." format */
+    fingerprint: string;
+    /** List of files included in fingerprint calculation */
+    files: string[];
+    /** Number of files processed */
+    fileCount: number;
+}
+
+/**
+ * Generate a new keypair using OpenSSL.
+ * @param options - Generation options
+ * @returns Paths to generated keys
+ * @throws Error if OpenSSL fails or keys exist without force
+ * @public
+ */
+export declare function generateKeyPair(options?: KeygenOptions): Promise<KeyPaths>;
+
+/**
+ * Get the default private key path based on OS.
+ * - macOS/Linux: ~/.config/attest-it/private.pem
+ * - Windows: %APPDATA%\attest-it\private.pem
+ * @public
+ */
+export declare function getDefaultPrivateKeyPath(): string;
+
+/**
+ * Get the default public key path (in repo).
+ * @public
+ */
+export declare function getDefaultPublicKeyPath(): string;
+
+/**
+ * Options for key generation.
+ * @public
+ */
+export declare interface KeygenOptions {
+    /** Algorithm to use (default: ed25519) */
+    algorithm?: Algorithm;
+    /** Path for private key (default: OS-specific config dir) */
+    privatePath?: string;
+    /** Path for public key (default: repo root) */
+    publicPath?: string;
+    /** Overwrite existing keys (default: false) */
+    force?: boolean;
+}
+
+/**
+ * Paths to a generated keypair.
+ * @public
+ */
+export declare interface KeyPaths {
+    /** Path to the private key file */
+    privatePath: string;
+    /** Path to the public key file */
+    publicPath: string;
+}
+
+/**
+ * List files in packages, respecting ignore patterns (async).
+ *
+ * @param packages - Array of package directory paths
+ * @param ignore - Optional glob patterns to exclude
+ * @param baseDir - Base directory for resolving paths (defaults to cwd)
+ * @returns Array of relative file paths
+ * @public
+ */
+export declare function listPackageFiles(packages: string[], ignore?: string[], baseDir?: string): Promise<string[]>;
+
+/**
+ * Load and validate configuration from a file (async).
+ *
+ * @param configPath - Optional path to config file. If not provided, searches default locations.
+ * @returns Validated configuration object
+ * @throws {@link ConfigNotFoundError} If config file cannot be found
+     * @throws {@link ConfigValidationError} If validation fails
+         * @public
+         */
+     export declare function loadConfig(configPath?: string): Promise<Config>;
+
+     /**
+      * Load and validate configuration from a file (sync).
+      *
+      * @param configPath - Optional path to config file. If not provided, searches default locations.
+      * @returns Validated configuration object
+      * @throws {@link ConfigNotFoundError} If config file cannot be found
+          * @throws {@link ConfigValidationError} If validation fails
+              * @public
+              */
+          export declare function loadConfigSync(configPath?: string): Config;
+
+          /**
+           * Read attestations and verify the signature.
+           *
+           * This function reads the attestations file, canonicalizes the attestations,
+           * and verifies the signature using the public key. It throws an error if the
+           * file doesn't exist or if signature verification fails.
+           *
+           * @param options - Options for reading and verifying attestations
+           * @returns The attestations file if signature is valid
+           * @throws Error if attestations file not found
+           * @throws SignatureInvalidError if signature verification fails
+           * @public
+           */
+          export declare function readAndVerifyAttestations(options: ReadSignedAttestationsOptions): Promise<AttestationsFile>;
+
+          /**
+           * Attestation file I/O module with JSON canonicalization.
+           */
+
+          /**
+           * Read attestations file from disk (async).
+           *
+           * @param filePath - Absolute path to the attestations JSON file
+           * @returns Parsed attestations file, or null if the file doesn't exist
+           * @throws Error on parse or validation errors
+           * @public
+           */
+          export declare function readAttestations(filePath: string): Promise<AttestationsFile | null>;
+
+          /**
+           * Read attestations file from disk (sync).
+           *
+           * @param filePath - Absolute path to the attestations JSON file
+           * @returns Parsed attestations file, or null if the file doesn't exist
+           * @throws Error on parse or validation errors
+           * @public
+           */
+          export declare function readAttestationsSync(filePath: string): AttestationsFile | null;
+
+          /**
+           * Options for reading and verifying signed attestations.
+           * @public
+           */
+          export declare interface ReadSignedAttestationsOptions {
+              /** Path to read the attestations file from */
+              filePath: string;
+              /** Path to the public key for verification */
+              publicKeyPath: string;
+          }
+
+          /**
+           * Remove attestations for a suite.
+           *
+           * This is an immutable operation that returns a new array.
+           *
+           * @param attestations - Current array of attestations
+           * @param suite - Name of the suite to remove
+           * @returns New attestations array without the specified suite
+           * @public
+           */
+          export declare function removeAttestation(attestations: Attestation[], suite: string): Attestation[];
+
+          /**
+           * Resolve relative paths in the configuration against the repository root.
+           *
+           * This converts relative paths in settings.publicKeyPath and settings.attestationsPath
+           * to absolute paths relative to the repository root.
+           *
+           * @param config - The configuration object
+           * @param repoRoot - Absolute path to the repository root
+           * @returns Configuration with resolved absolute paths
+           * @public
+           */
+          export declare function resolveConfigPaths(config: Config, repoRoot: string): Config;
+
+          /**
+           * Set restrictive permissions on a private key file.
+           * @param keyPath - Path to the private key
+           * @public
+           */
+          export declare function setKeyPermissions(keyPath: string): Promise<void>;
+
+          /**
+           * Sign data using a private key.
+           * @param options - Signing options
+           * @returns Base64-encoded signature
+           * @throws Error if signing fails
+           * @public
+           */
+          export declare function sign(options: SignOptions): Promise<string>;
+
+          /**
+           * Error thrown when signature verification fails.
+           * @public
+           */
+          export declare class SignatureInvalidError extends Error {
+              /**
+               * Create a new SignatureInvalidError.
+               * @param filePath - Path to the file that failed verification
+               */
+              constructor(filePath: string);
+          }
+
+          /**
+           * Options for signing data.
+           * @public
+           */
+          export declare interface SignOptions {
+              /** Path to the private key file */
+              privateKeyPath: string;
+              /** Data to sign (string or Buffer) */
+              data: Buffer | string;
+          }
+
+          /**
+           * Suite definition from the configuration file.
+           * @public
+           */
+          export declare interface SuiteConfig {
+              /** Human-readable description of what this suite tests */
+              description?: string;
+              /** Glob patterns for npm packages to include in fingerprint */
+              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;
+              /** Other suite names that, when changed, invalidate this suite's attestation */
+              invalidates?: string[];
+          }
+
+          /**
+           * Result of verifying a single suite's attestation.
+           * @public
+           */
+          export declare interface SuiteVerificationResult {
+              /** Name of the suite being verified */
+              suite: string;
+              /** Current verification status */
+              status: VerificationStatus;
+              /** Current computed fingerprint for the suite */
+              fingerprint: string;
+              /** The attestation record, if one exists */
+              attestation?: Attestation;
+              /** List of files that changed (if status is FINGERPRINT_CHANGED) */
+              changedFiles?: string[];
+              /** Age of the attestation in days (if expired) */
+              age?: number;
+              /** Human-readable message explaining the status */
+              message?: string;
+          }
+
+          /**
+           * Convert Zod-validated Config to AttestItConfig by removing undefined values.
+           *
+           * The Config type (from Zod) has optional fields as `T | undefined`,
+           * while AttestItConfig has optional fields as `T?` (can be absent, not undefined).
+           *
+           * This adapter removes any undefined values to match the AttestItConfig interface
+           * that the core functions expect.
+           *
+           * @param config - The Zod-validated configuration from loadConfig()
+           * @returns Configuration compatible with AttestItConfig
+           * @public
+           */
+          export declare function toAttestItConfig(config: Config): AttestItConfig;
+
+          /**
+           * Add or update an attestation for a suite.
+           *
+           * This is an immutable operation that returns a new array.
+           *
+           * @param attestations - Current array of attestations
+           * @param newAttestation - Attestation to add or update
+           * @returns New attestations array with the upserted attestation
+           * @throws Error if the new attestation fails validation
+           * @public
+           */
+          export declare function upsertAttestation(attestations: Attestation[], newAttestation: Attestation): Attestation[];
+
+          /**
+           * Verification status codes for suite attestations.
+           * @public
+           */
+          export declare type VerificationStatus = 'EXPIRED' | 'FINGERPRINT_CHANGED' | 'INVALIDATED_BY_PARENT' | 'NEEDS_ATTESTATION' | 'SIGNATURE_INVALID' | 'VALID';
+
+          /**
+           * Verify a signature using a public key.
+           * @param options - Verification options
+           * @returns true if signature is valid
+           * @throws Error if verification fails (not just invalid signature)
+           * @public
+           */
+          export declare function verify(options: CryptoVerifyOptions): Promise<boolean>;
+
+          /**
+           * Verify all attestations against current code state.
+           *
+           * Verification algorithm:
+           * 1. Load and verify attestations file signature
+           * 2. For each suite in config:
+           *    a. Compute current fingerprint
+           *    b. Find matching attestation
+           *    c. Compare fingerprints
+           *    d. Check age
+           * 3. Check invalidation chains
+           * 4. Return aggregated results
+           *
+           * @param options - Verification options
+           * @returns Verification result with status for each suite
+           * @public
+           */
+          export declare function verifyAttestations(options: VerifyOptions): Promise<VerifyResult>;
+
+          /**
+           * Options for verifying attestations.
+           * @public
+           */
+          export declare interface VerifyOptions {
+              /** Configuration object */
+              config: AttestItConfig;
+              /** Repository root directory (defaults to process.cwd()) */
+              repoRoot?: string;
+          }
+
+          /**
+           * Result of verifying all attestations.
+           * @public
+           */
+          export declare interface VerifyResult {
+              /** Overall success - true if all attestations are valid */
+              success: boolean;
+              /** Whether the attestations file signature is valid */
+              signatureValid: boolean;
+              /** Verification results for each suite */
+              suites: SuiteVerificationResult[];
+              /** Error messages encountered during verification */
+              errors: string[];
+          }
+
+          /**
+           * Package version
+           * @public
+           */
+          export declare const version = "0.0.0";
+
+          /**
+           * Write attestations file to disk (async).
+           *
+           * Creates parent directories if needed. The signature should be computed
+           * separately and passed in.
+           *
+           * @param filePath - Absolute path to write the attestations file
+           * @param attestations - Array of attestation entries
+           * @param signature - Cryptographic signature of the attestations
+           * @throws Error on validation or write errors
+           * @public
+           */
+          export declare function writeAttestations(filePath: string, attestations: Attestation[], signature: string): Promise<void>;
+
+          /**
+           * Write attestations file to disk (sync).
+           *
+           * Creates parent directories if needed. The signature should be computed
+           * separately and passed in.
+           *
+           * @param filePath - Absolute path to write the attestations file
+           * @param attestations - Array of attestation entries
+           * @param signature - Cryptographic signature of the attestations
+           * @throws Error on validation or write errors
+           * @public
+           */
+          export declare function writeAttestationsSync(filePath: string, attestations: Attestation[], signature: string): void;
+
+          /**
+           * Write attestations with a cryptographic signature.
+           *
+           * This function canonicalizes the attestations, signs them with the private key,
+           * and writes the attestations file with the signature.
+           *
+           * @param options - Options for writing signed attestations
+           * @throws Error if signing or writing fails
+           * @public
+           */
+          export declare function writeSignedAttestations(options: WriteSignedAttestationsOptions): Promise<void>;
+
+          /**
+           * Options for writing signed attestations.
+           * @public
+           */
+          export declare interface WriteSignedAttestationsOptions {
+              /** Path to write the attestations file */
+              filePath: string;
+              /** Array of attestations to write */
+              attestations: Attestation[];
+              /** Path to the private key for signing */
+              privateKeyPath: string;
+          }
+
+          export { }