chrome-tools 1.1.18 → 1.2.2

package/dist/core/crypto.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Decrypts a password/value buffer encrypted by Chrome on macOS or Linux.
+ * Chrome v10+ prefixes the encrypted blob with "v10" or "v11", followed by
+ * AES-128-CBC ciphertext. (Windows uses AES-256-GCM — see decryptValueBufferGcm.)
+ *
+ * @param encryptedBlob - The encrypted blob from the database.
+ * @param derivedKey - The derived 16-byte key.
+ * @returns The decrypted plaintext, or an error placeholder.
+ */
+export declare function decryptValue(encryptedBlob: Buffer | Uint8Array | null | undefined, derivedKey: Buffer): string;
+/**
+ * Decrypts a Chrome encrypted blob and returns the raw plaintext bytes.
+ *
+ * @param encryptedBlob - The encrypted blob from the database.
+ * @param derivedKey - The derived 16-byte key.
+ * @returns The decrypted plaintext bytes, or an error placeholder.
+ */
+export declare function decryptValueBuffer(encryptedBlob: Buffer | Uint8Array | null | undefined, derivedKey: Buffer): Buffer | string;
+/**
+ * Decrypts a Windows Chrome `v10` blob using AES-256-GCM.
+ *
+ * Unlike the macOS/Linux CBC scheme, Windows blobs carry their own 12-byte
+ * nonce after the version prefix and a 16-byte GCM auth tag at the end. The
+ * `key` is the 32-byte AES key recovered from `Local State` via DPAPI.
+ *
+ * @param encryptedBlob - The encrypted blob from the database.
+ * @param key - The 32-byte AES-256 key.
+ * @returns The decrypted plaintext bytes, or a placeholder string.
+ */
+export declare function decryptValueBufferGcm(encryptedBlob: Buffer | Uint8Array | null | undefined, key: Buffer): Buffer | string;
+/**
+ * Decrypts a Windows Chrome 127+ `v20` blob using AES-256-GCM.
+ *
+ * App-Bound Encryption uses the same AES-256-GCM layout as `v10`/`v11` but
+ * with a `"v20"` prefix and a key obtained from Chrome's Elevation Service
+ * (IElevator COM) instead of plain DPAPI.
+ *
+ * Layout: "v20" (3 bytes) + 12-byte nonce + ciphertext + 16-byte GCM tag
+ *
+ * @param encryptedBlob - The encrypted blob from the database.
+ * @param key - The 32-byte AES-256 key from ABE decryption.
+ * @returns The decrypted plaintext bytes, or a placeholder string.
+ */
+export declare function decryptValueBufferGcmV20(encryptedBlob: Buffer | Uint8Array | null | undefined, key: Buffer): Buffer | string;
+/**
+ * Converts a Chrome/Webkit timestamp (microseconds since 1601-01-01)
+ * to a readable local Date string.
+ *
+ * @param chromeTimestamp - Timestamp in microseconds.
+ * @returns Human-readable date-time string, or "N/A".
+ */
+export declare function chromeTimeToDate(chromeTimestamp: bigint | number | string | null | undefined): string;

package/dist/core/keychain.d.ts

@@ -0,0 +1,57 @@
+/** How a Keychain read failed, so callers (and the CLI) can react specifically. */
+export type KeychainErrorKind = "access-denied" | "not-found" | "empty" | "unknown";
+/**
+ * Error thrown when a browser's Safe Storage key cannot be read from the
+ * Keychain. Carries the failing `service` and a `kind` so the CLI can show a
+ * clear "No keychain access" message instead of a generic failure.
+ */
+export declare class KeychainAccessError extends Error {
+    readonly service: string;
+    readonly kind: KeychainErrorKind;
+    constructor(message: string, service: string, kind: KeychainErrorKind);
+    /** True when the failure means we couldn't get permission to read the key. */
+    get isAccessDenied(): boolean;
+}
+/**
+ * Narrows an unknown error to a {@link KeychainAccessError} caused by missing
+ * Keychain permission (denied/dismissed prompt, locked, or non-interactive).
+ */
+export declare function isKeychainAccessDenied(err: unknown): err is KeychainAccessError;
+export type KeychainPasswordProvider = (service: string) => string;
+/**
+ * Returns the current global keychain password provider hook.
+ */
+export declare function getKeychainPasswordProvider(): KeychainPasswordProvider | null;
+/**
+ * Sets the global keychain password provider hook, allowing downstream apps (like Electron)
+ * to intercept keychain password lookups and resolve them (e.g. via native node-keytar).
+ */
+export declare function setKeychainPasswordProvider(provider: KeychainPasswordProvider | null): void;
+/**
+ * Retrieves a browser's "Safe Storage" password from the macOS Keychain.
+ * Caches the result per service for subsequent calls within the same process.
+ *
+ * @param service - Keychain service name, e.g. "Chrome Safe Storage".
+ * @returns The raw keychain password.
+ * @throws If the password could not be retrieved.
+ */
+export declare function getKeychainPassword(service?: string): string;
+/**
+ * Backward-compatible alias for {@link getKeychainPassword} using Chrome's item.
+ * @deprecated Prefer {@link getKeychainPassword} with an explicit service name.
+ */
+export declare function getChromeKeychainPassword(): string;
+/**
+ * Derives the AES-128-CBC key from a browser's Keychain password using PBKDF2.
+ * Caches the result per service.
+ *
+ * @param service - Keychain service name. Defaults to Chrome's.
+ * @param keychainPassword - The raw password. If omitted, fetched from Keychain.
+ * @returns The derived 16-byte key.
+ */
+export declare function deriveEncryptionKey(service?: string, keychainPassword?: string): Buffer;
+/**
+ * Clears cached keychain data for all browsers. Useful for testing or
+ * re-authentication.
+ */
+export declare function clearKeychainCache(): void;

package/dist/core/limit.d.ts

@@ -0,0 +1,4 @@
+/** Normalizes the public limit option. Zero, negatives, and non-finite values mean unlimited. */
+export declare function normalizeLimit(limit: number | undefined): number | undefined;
+/** Applies a limit to the final combined result set across every profile. */
+export declare function limitResults<T>(results: T[], limit: number | undefined): T[];

package/dist/core/sql.d.ts

@@ -0,0 +1,2 @@
+/** Builds a SQL LIKE pattern with wildcard characters escaped for literal matching. */
+export declare function sqlLikePattern(term: string): string;