orm-blind-indexer 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,364 @@
+import * as _prisma_client from '@prisma/client';
+import * as _prisma_client_runtime_library from '@prisma/client/runtime/library';
+
+/**
+ * @file types/index.ts
+ * @description Core TypeScript interfaces and types for the orm-blind-indexer package.
+ */
+/**
+ * Configuration for a single encrypted field within a model.
+ *
+ * @example
+ * ```ts
+ * // For the "email" field on the User model:
+ * {
+ *   indexFieldName: "email_bidx",
+ *   caseSensitive: false
+ * }
+ * ```
+ */
+interface FieldConfig {
+    /**
+     * The name of the database column that stores the HMAC-SHA256 blind index.
+     * This column must exist in your Prisma schema (e.g., `email_bidx String @unique`).
+     */
+    indexFieldName: string;
+    /**
+     * When `false` (the default), the plaintext is lowercased before hashing.
+     * This ensures case-insensitive lookups: searching for "Test@Test.com"
+     * will match a record where "test@test.com" was stored.
+     *
+     * When `true`, the plaintext is hashed as-is, so the case must match exactly.
+     *
+     * @default false
+     */
+    caseSensitive?: boolean;
+    /**
+     * Optional byte length to truncate the HMAC-SHA256 digest to before encoding.
+     * Useful for frequency-analysis defense (k-anonymity / CipherSweet spec).
+     * Minimum: 8 bytes, Maximum: 32 bytes.
+     * Defaults to 32 (full SHA-256 digest length).
+     *
+     * @default undefined (full 32 bytes)
+     */
+    truncateBytes?: number;
+}
+/**
+ * Per-model field configuration map.
+ * Maps field names (as they appear in the Prisma schema) to their FieldConfig.
+ */
+type ModelFieldConfig = Record<string, FieldConfig>;
+/**
+ * Full field map across all models.
+ * Maps Prisma model names (PascalCase, e.g., "User") to their field configurations.
+ */
+type FieldsConfig = Record<string, ModelFieldConfig>;
+/**
+ * Root configuration object for the `withBlindIndexer` Prisma extension.
+ *
+ * @example
+ * ```ts
+ * const config: BlindIndexConfig = {
+ *   encryptionKey: process.env.ENCRYPTION_KEY!, // 32-byte base64 or hex string
+ *   indexKey: process.env.INDEX_KEY!,           // HMAC salt (any length, min 32 bytes recommended)
+ *   fields: {
+ *     User: {
+ *       email: {
+ *         indexFieldName: "email_bidx",
+ *         caseSensitive: false,
+ *       },
+ *     },
+ *   },
+ * };
+ * ```
+ */
+interface BlindIndexConfig {
+    /**
+     * The AES-256-GCM encryption key.
+     *
+     * Must decode to exactly **32 bytes** (256 bits).
+     * Accepted formats:
+     * - Base64-encoded 32-byte key (44 characters with padding)
+     * - Hex-encoded 32-byte key (64 hex characters)
+     *
+     * Generate with: `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`
+     */
+    encryptionKey: string;
+    /**
+     * The HMAC-SHA256 index key (salt).
+     *
+     * Used as the secret for the HMAC function. Should be a high-entropy
+     * random value, **different** from the encryptionKey.
+     * Recommended minimum: 32 bytes of entropy.
+     *
+     * Generate with: `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`
+     */
+    indexKey: string;
+    /**
+     * Map of model names to their encrypted fields configuration.
+     */
+    fields: FieldsConfig;
+}
+/**
+ * Represents the parsed components of an AES-256-GCM ciphertext string.
+ * The on-disk format is `base64(iv):base64(authTag):base64(ciphertext)`.
+ */
+interface ParsedCiphertext {
+    /** 12-byte Initialization Vector, stored as base64. */
+    iv: Buffer;
+    /** 16-byte GCM Authentication Tag, stored as base64. */
+    authTag: Buffer;
+    /** The actual encrypted bytes, stored as base64. */
+    ciphertext: Buffer;
+}
+/**
+ * Result of a successful encryption operation.
+ */
+interface EncryptionResult {
+    /**
+     * The serialized ciphertext string in the format:
+     * `base64(iv):base64(authTag):base64(ciphertext)`
+     */
+    encrypted: string;
+}
+
+/**
+ * Creates a Prisma Client Extension that transparently implements blind indexing
+ * for the configured fields.
+ *
+ * **Usage:**
+ * ```ts
+ * import { PrismaClient } from '@prisma/client';
+ * import { withBlindIndexer } from 'orm-blind-indexer';
+ *
+ * const prisma = new PrismaClient().$extends(
+ *   withBlindIndexer({
+ *     encryptionKey: process.env.ENCRYPTION_KEY!,
+ *     indexKey: process.env.INDEX_KEY!,
+ *     fields: {
+ *       User: {
+ *         email: {
+ *           indexFieldName: 'email_bidx',
+ *           caseSensitive: false,
+ *         },
+ *       },
+ *     },
+ *   })
+ * );
+ * ```
+ *
+ * @param config - The blind indexer configuration object.
+ * @returns A Prisma Client Extension object to pass to `.$extends()`.
+ * @throws {Error} At initialization time if the keys are invalid.
+ */
+declare function withBlindIndexer(config: BlindIndexConfig): (client: any) => _prisma_client.PrismaClientExtends<_prisma_client_runtime_library.InternalArgs<{}, {}, {}, {}>>;
+
+/**
+ * @file crypto/encryptor.ts
+ * @description AES-256-GCM authenticated encryption and decryption.
+ *
+ * ## Why AES-256-GCM?
+ *
+ * AES-256-GCM (Galois/Counter Mode) is an authenticated encryption with
+ * associated data (AEAD) cipher. It provides:
+ *
+ * 1. **Confidentiality**: The ciphertext reveals nothing about the plaintext.
+ * 2. **Integrity & Authenticity**: The 16-byte authentication tag (Auth Tag)
+ *    cryptographically proves the ciphertext has not been tampered with.
+ *    Decryption fails with an error if the tag doesn't verify.
+ * 3. **No padding oracle**: GCM is a stream-cipher mode — no PKCS#7 padding
+ *    means no padding oracle attacks.
+ *
+ * ## On-disk format
+ *
+ * We serialize the IV, Auth Tag, and ciphertext as three colon-separated
+ * base64 segments: `base64(iv):base64(authTag):base64(ciphertext)`
+ *
+ * This is a self-contained format: everything needed to decrypt the value
+ * lives in the value itself. The key is stored separately (environment variable).
+ *
+ * ## IV Randomness
+ *
+ * A fresh 12-byte random IV is generated for **every** encryption call using
+ * `crypto.randomBytes()`. This is critical: reusing an IV with the same key
+ * in GCM mode completely breaks confidentiality (two-time pad attack).
+ * With a 12-byte IV, the probability of a collision is negligible for
+ * reasonable database sizes (birthday bound: ~2^48 operations for 2^-32 risk).
+ *
+ * ## Auth Tag Length
+ *
+ * We use the full 16-byte (128-bit) authentication tag, which is the
+ * maximum and recommended length. Shorter tags reduce forgery resistance.
+ */
+/**
+ * Encrypts a UTF-8 plaintext string using AES-256-GCM.
+ *
+ * @param plaintext - The plaintext string to encrypt (e.g., an email address).
+ * @param key - A 32-byte Buffer containing the AES-256 encryption key.
+ * @returns A serialized ciphertext string: `base64(iv):base64(authTag):base64(ciphertext)`.
+ * @throws {Error} If encryption fails (e.g., invalid key length).
+ *
+ * @example
+ * ```ts
+ * const encrypted = encrypt('user@example.com', encryptionKeyBuffer);
+ * // => "ABC123...:XYZ789...:cipher..."
+ * ```
+ */
+declare function encrypt(plaintext: string, key: Buffer): string;
+/**
+ * Decrypts a serialized AES-256-GCM ciphertext string back to UTF-8 plaintext.
+ *
+ * The decryption process automatically verifies the GCM authentication tag.
+ * If the ciphertext or key has been tampered with, decryption will throw an error
+ * ("Unsupported state or unable to authenticate data") before any plaintext is returned.
+ *
+ * @param cipherText - The serialized ciphertext string from `encrypt()`.
+ * @param key - The same 32-byte Buffer used during encryption.
+ * @returns The original UTF-8 plaintext string.
+ * @throws {Error} If the ciphertext format is invalid, the key is wrong,
+ *   or the authentication tag verification fails (indicating tampering).
+ *
+ * @example
+ * ```ts
+ * const plaintext = decrypt(encryptedValue, encryptionKeyBuffer);
+ * // => "user@example.com"
+ * ```
+ */
+declare function decrypt(cipherText: string, key: Buffer): string;
+/**
+ * Checks if a string appears to be in the encrypted format produced by `encrypt()`.
+ * Used to avoid double-encrypting values that are already encrypted.
+ *
+ * This is a heuristic check based on format, not cryptographic verification.
+ *
+ * @param value - The string to check.
+ * @returns `true` if the string matches the `base64:base64:base64` pattern.
+ */
+declare function isEncryptedFormat(value: string): boolean;
+
+/**
+ * @file crypto/hasher.ts
+ * @description HMAC-SHA256 blind index generation.
+ *
+ * ## What is a Blind Index?
+ *
+ * A blind index solves the problem of querying encrypted data. Because AES-256-GCM
+ * uses a random IV on every encryption, the same plaintext produces a different
+ * ciphertext each time. This makes exact-match database queries impossible on
+ * the encrypted column.
+ *
+ * A blind index is a **deterministic** hash of the plaintext that:
+ * - Always produces the same output for the same input (queryable)
+ * - Reveals no information about the plaintext without the key (private)
+ * - Is stored in a separate `_bidx` column alongside the encrypted data
+ *
+ * ## Why HMAC-SHA256 (not plain SHA256)?
+ *
+ * Plain SHA256 is a one-way function, but it has no secret. An attacker who
+ * gains read access to your database could mount a **dictionary attack**:
+ * they hash every common email address and look for matches.
+ *
+ * HMAC-SHA256 incorporates a **secret key** (the `indexKey`). Without knowing
+ * the key, an attacker cannot compute the hash, so the blind index leaks no
+ * information about the plaintext even if the database is fully compromised.
+ *
+ * ## Case Sensitivity
+ *
+ * Email addresses and usernames are often compared case-insensitively.
+ * When `caseSensitive: false` (the default), we lowercase the input before
+ * hashing. This ensures that "Test@Test.com" and "test@test.com" produce the
+ * same blind index, enabling case-insensitive equality searches.
+ *
+ * **Important**: The case normalization must be applied consistently on both
+ * write (when storing) and read (when querying). The extension handles this.
+ */
+/**
+ * Generates a deterministic HMAC-SHA256 blind index for a given plaintext.
+ *
+ * The output is a base64-encoded 32-byte HMAC digest. Base64 is used (rather
+ * than hex) for compactness: 44 characters vs 64 characters for the same value.
+ *
+ * @param text - The plaintext value to hash (e.g., an email address).
+ * @param indexKey - A secret Buffer used as the HMAC key. Must be kept private.
+ * @param caseSensitive - When `false`, `text` is lowercased before hashing.
+ *   Defaults to `false` for case-insensitive equality searches.
+ * @param truncateBytes - Optional byte length (8 to 32) to truncate the HMAC
+ *   digest before base64 encoding. Useful for frequency-analysis defense.
+ * @returns A base64-encoded HMAC-SHA256 digest string.
+ *
+ * @example
+ * ```ts
+ * const indexKey = Buffer.from(process.env.INDEX_KEY!, 'base64');
+ *
+ * // Case-insensitive (default): both produce the same hash
+ * generateBlindIndex('Test@Test.com', indexKey, false);
+ * generateBlindIndex('test@test.com', indexKey, false);
+ *
+ * // Case-sensitive: these produce different hashes
+ * generateBlindIndex('Test@Test.com', indexKey, true);
+ * generateBlindIndex('test@test.com', indexKey, true);
+ *
+ * // Truncated blind index (e.g., 16 bytes for frequency defense)
+ * generateBlindIndex('user@example.com', indexKey, false, 16);
+ * ```
+ */
+declare function generateBlindIndex(text: string, indexKey: Buffer, caseSensitive?: boolean, truncateBytes?: number): string;
+/**
+ * Generates blind indexes for an array of plaintext values.
+ * Useful for `{ in: [...] }` and `{ notIn: [...] }` Prisma query operators.
+ *
+ * @param values - An array of plaintext strings to hash.
+ * @param indexKey - The secret HMAC key Buffer.
+ * @param caseSensitive - When `false`, each value is lowercased before hashing.
+ * @param truncateBytes - Optional byte length (8 to 32) to truncate each digest.
+ * @returns An array of base64-encoded HMAC-SHA256 digests, in the same order as `values`.
+ */
+declare function generateBlindIndexBatch(values: string[], indexKey: Buffer, caseSensitive?: boolean, truncateBytes?: number): string[];
+
+/**
+ * @file crypto/utils.ts
+ * @description Key validation and parsing utilities for cryptographic operations.
+ *
+ * Security Design Notes:
+ * - AES-256 requires a 256-bit (32-byte) key. Any deviation is a hard error.
+ * - Keys may be provided as base64 or hex strings for safe environment variable storage.
+ * - We validate at extension initialization time, not at query time, to fail fast.
+ */
+/**
+ * Parses a key string (base64 or hex) into a Buffer and validates its byte length.
+ *
+ * The function tries hex first (unambiguous format), then base64.
+ *
+ * @param keyString - The raw key string from environment variables or config.
+ * @param expectedBytes - The required byte length of the decoded key.
+ * @param keyName - A descriptive name for the key, used in error messages.
+ * @returns A `Buffer` of exactly `expectedBytes` bytes.
+ * @throws {Error} If the key cannot be parsed or has an incorrect length.
+ *
+ * @example
+ * ```ts
+ * const key = parseAndValidateKey(process.env.ENCRYPTION_KEY!, 32, 'encryptionKey');
+ * ```
+ */
+declare function parseAndValidateKey(keyString: string, expectedBytes: number, keyName: string): Buffer;
+/**
+ * Validates an encryption key for AES-256 (requires exactly 32 bytes / 256 bits).
+ *
+ * @param keyString - The raw encryption key string from config.
+ * @returns A `Buffer` of exactly 32 bytes suitable for AES-256-GCM.
+ * @throws {Error} If the key is invalid or not exactly 32 bytes.
+ */
+declare function validateEncryptionKey(keyString: string): Buffer;
+/**
+ * Parses the index key (HMAC salt) from a string.
+ * Unlike the encryption key, the HMAC key has no strict length requirement in the
+ * cryptographic spec (SHA-256 accepts any length), but we enforce a minimum of 16 bytes
+ * for security best-practice guidance.
+ *
+ * @param keyString - The raw index key string from config.
+ * @returns A `Buffer` usable as an HMAC key.
+ * @throws {Error} If the key cannot be parsed or is shorter than 16 bytes.
+ */
+declare function validateIndexKey(keyString: string): Buffer;
+
+export { type BlindIndexConfig, type EncryptionResult, type FieldConfig, type FieldsConfig, type ModelFieldConfig, type ParsedCiphertext, decrypt, encrypt, generateBlindIndex, generateBlindIndexBatch, isEncryptedFormat, parseAndValidateKey, validateEncryptionKey, validateIndexKey, withBlindIndexer };