@compass-ai/nova 1.0.72 → 1.0.74

package/dist/utils/crypto.d.ts

@@ -0,0 +1,351 @@
+/**
+ * Cryptographic utilities for encryption/decryption of sensitive data.
+ *
+ * This module provides secure cryptographic operations for the Compass CLI,
+ * including AES-256-GCM encryption/decryption, secure random generation,
+ * hashing, and HMAC signatures.
+ *
+ * Security features:
+ * - AES-256-GCM authenticated encryption
+ * - PBKDF2 key derivation with 100,000 iterations
+ * - Cryptographically secure random number generation
+ * - Constant-time string comparison to prevent timing attacks
+ * - SHA-256 hashing for data integrity
+ * - HMAC-SHA256 for message authentication
+ */
+/**
+ * Encrypts plaintext data using AES-256-GCM authenticated encryption.
+ *
+ * The encryption process:
+ * 1. Generates a random salt for key derivation
+ * 2. Derives an encryption key from the password using PBKDF2
+ * 3. Generates a random initialization vector (IV)
+ * 4. Encrypts the data using AES-256-GCM
+ * 5. Combines salt + IV + auth tag + ciphertext into a single output
+ *
+ * The output format is: salt (32 bytes) + IV (16 bytes) + tag (16 bytes) + ciphertext
+ * All encoded as base64 for safe storage and transmission.
+ *
+ * @param plaintext - The string data to encrypt
+ * @param password - The password used for key derivation
+ * @returns Base64-encoded encrypted data containing salt, IV, tag, and ciphertext
+ *
+ * @example
+ * ```typescript
+ * const encrypted = encrypt('my secret data', 'strong-password');
+ * // Returns: base64-encoded string
+ * ```
+ */
+export declare function encrypt(plaintext: string, password: string): string;
+/**
+ * Decrypts data that was encrypted with the encrypt() function.
+ *
+ * The decryption process:
+ * 1. Decodes the base64 input
+ * 2. Extracts salt, IV, authentication tag, and ciphertext
+ * 3. Derives the decryption key using the same password and salt
+ * 4. Verifies the authentication tag and decrypts the data
+ *
+ * @param encryptedData - Base64-encoded encrypted data from encrypt()
+ * @param password - The same password used for encryption
+ * @returns The original plaintext string
+ * @throws Error if decryption fails (wrong password, corrupted data, or tampering)
+ *
+ * @example
+ * ```typescript
+ * const encrypted = encrypt('my secret data', 'strong-password');
+ * const decrypted = decrypt(encrypted, 'strong-password');
+ * // Returns: 'my secret data'
+ * ```
+ */
+export declare function decrypt(encryptedData: string, password: string): string;
+/**
+ * Generates a cryptographically secure random string.
+ *
+ * Uses crypto.randomBytes() which provides cryptographically strong
+ * pseudo-random data suitable for security-sensitive operations.
+ *
+ * @param length - Number of random bytes to generate (default: 32)
+ * @returns Hexadecimal string of the random bytes (2 * length characters)
+ *
+ * @example
+ * ```typescript
+ * const token = generateSecureRandom(16);
+ * // Returns: 32-character hex string like 'a1b2c3d4e5f6...'
+ *
+ * const sessionId = generateSecureRandom();
+ * // Returns: 64-character hex string (default 32 bytes)
+ * ```
+ */
+export declare function generateSecureRandom(length?: number): string;
+/**
+ * Generates a cryptographically secure random bytes buffer.
+ *
+ * @param length - Number of random bytes to generate
+ * @returns Buffer containing random bytes
+ *
+ * @example
+ * ```typescript
+ * const randomBytes = generateRandomBytes(16);
+ * // Returns: Buffer of 16 random bytes
+ * ```
+ */
+export declare function generateRandomBytes(length: number): Buffer;
+/**
+ * Generates a random UUID v4.
+ *
+ * @returns A random UUID string in the format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ *
+ * @example
+ * ```typescript
+ * const id = generateUUID();
+ * // Returns: 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
+ * ```
+ */
+export declare function generateUUID(): string;
+/**
+ * Creates a SHA-256 hash of the input string.
+ *
+ * SHA-256 is a cryptographic hash function that produces a 256-bit (32-byte)
+ * hash value. It's suitable for data integrity verification and generating
+ * unique identifiers from input data.
+ *
+ * @param input - The string to hash
+ * @returns Hexadecimal string of the SHA-256 hash (64 characters)
+ *
+ * @example
+ * ```typescript
+ * const hashedPassword = hash('user-password');
+ * // Returns: 64-character hex string
+ *
+ * const fileHash = hash(fileContents);
+ * // Can be used to verify file integrity
+ * ```
+ */
+export declare function hash(input: string): string;
+/**
+ * Creates a hash of the input using the specified algorithm.
+ *
+ * @param input - The string to hash
+ * @param algorithm - Hash algorithm to use (e.g., 'sha256', 'sha512', 'md5')
+ * @returns Hexadecimal string of the hash
+ *
+ * @example
+ * ```typescript
+ * const sha512Hash = hashWithAlgorithm('data', 'sha512');
+ * const md5Hash = hashWithAlgorithm('data', 'md5');
+ * ```
+ */
+export declare function hashWithAlgorithm(input: string, algorithm: string): string;
+/**
+ * Creates a hash of a buffer using SHA-256.
+ *
+ * @param input - The buffer to hash
+ * @returns Hexadecimal string of the SHA-256 hash
+ */
+export declare function hashBuffer(input: Buffer): string;
+/**
+ * Creates an HMAC-SHA256 signature of the data.
+ *
+ * HMAC (Hash-based Message Authentication Code) provides both data integrity
+ * and authentication. It's used to verify that a message hasn't been altered
+ * and was created by someone with the secret key.
+ *
+ * @param data - The data to sign
+ * @param secret - The secret key for HMAC
+ * @returns Hexadecimal string of the HMAC signature (64 characters)
+ *
+ * @example
+ * ```typescript
+ * const signature = hmac('message-to-sign', 'secret-key');
+ * // Returns: 64-character hex string
+ *
+ * // Verify by computing HMAC again and comparing
+ * const isValid = hmac('message-to-sign', 'secret-key') === signature;
+ * ```
+ */
+export declare function hmac(data: string, secret: string): string;
+/**
+ * Creates an HMAC signature using the specified algorithm.
+ *
+ * @param data - The data to sign
+ * @param secret - The secret key for HMAC
+ * @param algorithm - Hash algorithm to use (e.g., 'sha256', 'sha512')
+ * @returns Hexadecimal string of the HMAC signature
+ */
+export declare function hmacWithAlgorithm(data: string, secret: string, algorithm: string): string;
+/**
+ * Generates a machine-specific key for local encryption.
+ *
+ * This function creates a unique key based on machine identifiers,
+ * which can be used for encrypting data that should only be decryptable
+ * on the same machine. This is useful for storing credentials locally.
+ *
+ * Note: This key will change if the machine's hostname, username, or
+ * other identifying characteristics change.
+ *
+ * @returns SHA-256 hash of combined machine identifiers
+ *
+ * @example
+ * ```typescript
+ * const machineKey = getMachineKey();
+ * const encrypted = encrypt('sensitive-data', machineKey);
+ * // Data can only be decrypted on the same machine
+ * ```
+ */
+export declare function getMachineKey(): string;
+/**
+ * Generates a machine-specific key asynchronously.
+ * This is provided for consistency with async patterns in the codebase.
+ *
+ * @returns Promise resolving to SHA-256 hash of combined machine identifiers
+ */
+export declare function getMachineKeyAsync(): Promise<string>;
+/**
+ * Securely compares two strings in constant time.
+ *
+ * This function prevents timing attacks by ensuring the comparison
+ * takes the same amount of time regardless of where the strings differ.
+ * Regular string comparison (===) can leak information about the position
+ * of the first differing character through timing analysis.
+ *
+ * @param a - First string to compare
+ * @param b - Second string to compare
+ * @returns True if strings are equal, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Use for comparing sensitive values like tokens or signatures
+ * const isValid = secureCompare(providedToken, storedToken);
+ *
+ * // Don't use regular comparison for security-sensitive data
+ * // BAD: if (providedToken === storedToken) { ... }
+ * // GOOD: if (secureCompare(providedToken, storedToken)) { ... }
+ * ```
+ */
+export declare function secureCompare(a: string, b: string): boolean;
+/**
+ * Securely compares two buffers in constant time.
+ *
+ * @param a - First buffer to compare
+ * @param b - Second buffer to compare
+ * @returns True if buffers are equal, false otherwise
+ */
+export declare function secureCompareBuffers(a: Buffer, b: Buffer): boolean;
+/**
+ * Generates a secure token suitable for session IDs or API tokens.
+ *
+ * @param length - Length of the token in bytes (default: 32)
+ * @returns URL-safe base64-encoded token
+ *
+ * @example
+ * ```typescript
+ * const sessionToken = generateToken();
+ * // Returns: URL-safe base64 string
+ * ```
+ */
+export declare function generateToken(length?: number): string;
+/**
+ * Creates a salted hash of a password for storage.
+ *
+ * This is a simple implementation for non-critical use cases.
+ * For production password storage, consider using bcrypt or argon2.
+ *
+ * @param password - The password to hash
+ * @returns Object containing the salt and hash
+ *
+ * @example
+ * ```typescript
+ * const { salt, hash } = hashPassword('user-password');
+ * // Store both salt and hash in database
+ * ```
+ */
+export declare function hashPassword(password: string): {
+    salt: string;
+    hash: string;
+};
+/**
+ * Verifies a password against a stored salt and hash.
+ *
+ * @param password - The password to verify
+ * @param salt - The stored salt (hex string)
+ * @param storedHash - The stored hash (hex string)
+ * @returns True if the password matches
+ *
+ * @example
+ * ```typescript
+ * const isValid = verifyPassword('user-password', storedSalt, storedHash);
+ * ```
+ */
+export declare function verifyPassword(password: string, salt: string, storedHash: string): boolean;
+/**
+ * Encrypts an object by serializing it to JSON first.
+ *
+ * @param data - The object to encrypt
+ * @param password - The encryption password
+ * @returns Base64-encoded encrypted data
+ *
+ * @example
+ * ```typescript
+ * const encrypted = encryptObject({ apiKey: 'secret' }, 'password');
+ * ```
+ */
+export declare function encryptObject(data: unknown, password: string): string;
+/**
+ * Decrypts data and parses it as JSON.
+ *
+ * @param encryptedData - The encrypted data from encryptObject()
+ * @param password - The decryption password
+ * @returns The decrypted and parsed object
+ *
+ * @example
+ * ```typescript
+ * const data = decryptObject<{ apiKey: string }>(encrypted, 'password');
+ * console.log(data.apiKey);
+ * ```
+ */
+export declare function decryptObject<T>(encryptedData: string, password: string): T;
+/**
+ * Generates a checksum for data integrity verification.
+ *
+ * @param data - The data to checksum
+ * @returns Short hash suitable for display (first 8 characters of SHA-256)
+ *
+ * @example
+ * ```typescript
+ * const checksum = generateChecksum(fileContents);
+ * // Returns: '3a7bd3e2' (8 characters)
+ * ```
+ */
+export declare function generateChecksum(data: string): string;
+/**
+ * Verifies a checksum against data.
+ *
+ * @param data - The data to verify
+ * @param checksum - The expected checksum
+ * @returns True if the checksum matches
+ */
+export declare function verifyChecksum(data: string, checksum: string): boolean;
+/**
+ * Decrypts data encrypted with Python's cryptography.fernet.Fernet.
+ *
+ * Fernet format:
+ * - Version (1 byte): 0x80
+ * - Timestamp (8 bytes): big-endian timestamp
+ * - IV (16 bytes): initialization vector for AES-128-CBC
+ * - Ciphertext (variable): encrypted data
+ * - HMAC (32 bytes): HMAC-SHA256 for authentication
+ *
+ * @param encryptedData - Base64 URL-safe encoded Fernet token
+ * @param password - Password used for key derivation
+ * @returns Decrypted plaintext string
+ * @throws Error if decryption fails (wrong password, corrupted data, or invalid format)
+ *
+ * @example
+ * ```typescript
+ * // Decrypt data encrypted by Python's CliAuth.encrypt()
+ * const decrypted = decryptFernet(encryptedToken, 'anthropic');
+ * ```
+ */
+export declare function decryptFernet(encryptedData: string, password: string): string;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/utils/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/utils/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA0EH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8BnE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAiCvE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,GAAE,MAAW,GAAG,MAAM,CAEhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,CAER;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAYtC;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAE1D;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAU3D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAMlE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,MAAW,GAAG,MAAM,CAEzD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAO7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,OAAO,CAGT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAG3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEtE;AAsCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAiE7E"}