@attest-it/core 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,691 @@
+import { z } from 'zod';
+
+/**
+ * Core types for attest-it attestation system.
+ * @packageDocumentation
+ */
+/**
+ * Settings from the configuration file.
+ * @public
+ */
+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';
+}
+/**
+ * Suite definition from the configuration file.
+ * @public
+ */
+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[];
+}
+/**
+ * Full configuration file structure.
+ * @public
+ */
+interface AttestItConfig {
+    /** Configuration schema version */
+    version: 1;
+    /** Global settings for attestation behavior */
+    settings: AttestItSettings;
+    /** Named test suites with their configurations */
+    suites: Record<string, SuiteConfig>;
+}
+/**
+ * A single attestation entry.
+ * @public
+ */
+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
+ */
+interface AttestationsFile {
+    /** Schema version for forward compatibility */
+    schemaVersion: '1';
+    /** Array of attestations */
+    attestations: Attestation[];
+    /** Base64-encoded signature over canonical attestations array */
+    signature: string;
+}
+/**
+ * Verification status codes for suite attestations.
+ * @public
+ */
+type VerificationStatus = 'EXPIRED' | 'FINGERPRINT_CHANGED' | 'INVALIDATED_BY_PARENT' | 'NEEDS_ATTESTATION' | 'SIGNATURE_INVALID' | 'VALID';
+/**
+ * Result of verifying a single suite's attestation.
+ * @public
+ */
+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;
+}
+
+/**
+ * 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;
+}>;
+/**
+ * Type inference from Zod schema (should match AttestItConfig).
+ * This is the same as AttestItConfig but with defaults applied.
+ * @public
+ */
+type Config = z.infer<typeof configSchema>;
+/**
+ * Error thrown when configuration is invalid.
+ * @public
+ */
+declare class ConfigValidationError extends Error {
+    readonly issues: z.ZodIssue[];
+    constructor(message: string, issues: z.ZodIssue[]);
+}
+/**
+ * Error thrown when configuration file cannot be found.
+ * @public
+ */
+declare class ConfigNotFoundError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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
+ */
+declare function findConfigPath(startDir?: string): null | 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
+ */
+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
+ */
+declare function loadConfigSync(configPath?: string): Config;
+/**
+ * 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
+ */
+declare function resolveConfigPaths(config: Config, repoRoot: string): Config;
+/**
+ * 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
+ */
+declare function toAttestItConfig(config: Config): AttestItConfig;
+
+/**
+ * Options for computing a package fingerprint.
+ * @public
+ */
+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
+ */
+interface FingerprintResult {
+    /** The fingerprint in "sha256:..." format */
+    fingerprint: string;
+    /** List of files included in fingerprint calculation */
+    files: string[];
+    /** Number of files processed */
+    fileCount: number;
+}
+/**
+ * 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
+ */
+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
+ */
+declare function computeFingerprintSync(options: FingerprintOptions): FingerprintResult;
+/**
+ * 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
+ */
+declare function listPackageFiles(packages: string[], ignore?: string[], baseDir?: string): Promise<string[]>;
+
+/**
+ * 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
+ */
+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
+ */
+declare function readAttestationsSync(filePath: string): AttestationsFile | null;
+/**
+ * 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
+ */
+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
+ */
+declare function writeAttestationsSync(filePath: string, attestations: Attestation[], signature: string): void;
+/**
+ * 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
+ */
+declare function findAttestation(attestations: AttestationsFile, suite: string): Attestation | undefined;
+/**
+ * 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
+ */
+declare function upsertAttestation(attestations: Attestation[], newAttestation: Attestation): Attestation[];
+/**
+ * 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
+ */
+declare function removeAttestation(attestations: Attestation[], suite: string): Attestation[];
+/**
+ * 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
+ */
+declare function canonicalizeAttestations(attestations: Attestation[]): string;
+/**
+ * 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
+ */
+declare function createAttestation(params: {
+    attestedBy?: string;
+    command: string;
+    fingerprint: string;
+    suite: string;
+}): Attestation;
+/**
+ * Options for writing signed attestations.
+ * @public
+ */
+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;
+}
+/**
+ * Options for reading and verifying signed attestations.
+ * @public
+ */
+interface ReadSignedAttestationsOptions {
+    /** Path to read the attestations file from */
+    filePath: string;
+    /** Path to the public key for verification */
+    publicKeyPath: string;
+}
+/**
+ * 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
+ */
+declare function writeSignedAttestations(options: WriteSignedAttestationsOptions): Promise<void>;
+/**
+ * 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
+ */
+declare function readAndVerifyAttestations(options: ReadSignedAttestationsOptions): Promise<AttestationsFile>;
+/**
+ * Error thrown when signature verification fails.
+ * @public
+ */
+declare class SignatureInvalidError extends Error {
+    /**
+     * Create a new SignatureInvalidError.
+     * @param filePath - Path to the file that failed verification
+     */
+    constructor(filePath: string);
+}
+
+/**
+ * Cryptographic utilities for key generation, signing, and verification.
+ *
+ * @remarks
+ * This module provides cryptographic operations using OpenSSL for key management
+ * and signature verification. It supports Ed25519 and RSA algorithms.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Supported signature algorithms.
+ * @public
+ */
+type Algorithm = 'ed25519' | 'rsa';
+/**
+ * Paths to a generated keypair.
+ * @public
+ */
+interface KeyPaths {
+    /** Path to the private key file */
+    privatePath: string;
+    /** Path to the public key file */
+    publicPath: string;
+}
+/**
+ * Options for key generation.
+ * @public
+ */
+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;
+}
+/**
+ * Options for signing data.
+ * @public
+ */
+interface SignOptions {
+    /** Path to the private key file */
+    privateKeyPath: string;
+    /** Data to sign (string or Buffer) */
+    data: Buffer | string;
+}
+/**
+ * Options for verifying signatures.
+ * @public
+ */
+interface VerifyOptions$1 {
+    /** Path to the public key file */
+    publicKeyPath: string;
+    /** Original data that was signed */
+    data: Buffer | string;
+    /** Base64-encoded signature to verify */
+    signature: string;
+}
+/**
+ * Check if OpenSSL is available and get version info.
+ * @returns OpenSSL version string
+ * @throws Error if OpenSSL is not available
+ * @public
+ */
+declare function checkOpenSSL(): Promise<string>;
+/**
+ * Get the default private key path based on OS.
+ * - macOS/Linux: ~/.config/attest-it/private.pem
+ * - Windows: %APPDATA%\attest-it\private.pem
+ * @public
+ */
+declare function getDefaultPrivateKeyPath(): string;
+/**
+ * Get the default public key path (in repo).
+ * @public
+ */
+declare function getDefaultPublicKeyPath(): string;
+/**
+ * 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
+ */
+declare function generateKeyPair(options?: KeygenOptions): Promise<KeyPaths>;
+/**
+ * Sign data using a private key.
+ * @param options - Signing options
+ * @returns Base64-encoded signature
+ * @throws Error if signing fails
+ * @public
+ */
+declare function sign(options: SignOptions): Promise<string>;
+/**
+ * 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
+ */
+declare function verify(options: VerifyOptions$1): Promise<boolean>;
+/**
+ * Set restrictive permissions on a private key file.
+ * @param keyPath - Path to the private key
+ * @public
+ */
+declare function setKeyPermissions(keyPath: string): Promise<void>;
+
+/**
+ * Verification logic for attestations.
+ * @packageDocumentation
+ */
+
+/**
+ * Options for verifying attestations.
+ * @public
+ */
+interface VerifyOptions {
+    /** Configuration object */
+    config: AttestItConfig;
+    /** Repository root directory (defaults to process.cwd()) */
+    repoRoot?: string;
+}
+/**
+ * Result of verifying all attestations.
+ * @public
+ */
+interface VerifyResult {
+    /** Overall success - true if all attestations are valid */
+    success: boolean;
+    /** Whether the attestations file signature is valid */
+    signatureValid: boolean;
+    /** Verification results for each suite */
+    suites: SuiteVerificationResult[];
+    /** Error messages encountered during verification */
+    errors: string[];
+}
+/**
+ * Verify 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
+ */
+declare function verifyAttestations(options: VerifyOptions): Promise<VerifyResult>;
+
+/**
+ * @attest-it/core
+ *
+ * Core functionality for the attest-it testing framework.
+ * @packageDocumentation
+ */
+/**
+ * Package version
+ * @public
+ */
+declare const version = "0.0.0";
+
+export { type Algorithm, 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 };