@cipherstash/stack 0.18.0 → 1.0.0-rc.0

package/dist/encryption/index.d.cts

@@ -1,7 +1,808 @@
-import '../errors/index.cjs';
-import '../types-public-BTxqjmtv.cjs';
-import '@byteslice/result';
-import '@cipherstash/protect-ffi';
-export { B as BatchEncryptQueryOperation, b as BulkDecryptModelsOperation, c as BulkDecryptOperation, d as BulkEncryptModelsOperation, e as BulkEncryptOperation, D as DecryptModelOperation, f as DecryptOperation, g as EncryptModelOperation, h as EncryptOperation, i as EncryptQueryOperation, E as Encryption, a as EncryptionClient, n as noClientError } from '../client-Dt98Rugc.cjs';
+import { Result } from '@byteslice/result';
+import { EncryptionError } from '../errors/index.cjs';
+import { w as EncryptedQueryResult, i as Client, S as ScalarQueryTerm, f as BulkDecryptedData, e as BulkDecryptPayload, D as Decrypted, h as BulkEncryptedData, g as BulkEncryptPayload, n as EncryptOptions, B as BuildableColumn, b as BuildableTable, p as Encrypted, P as Plaintext, o as EncryptQueryOptions, a as BuildableQueryColumn, Q as QueryTypeName, x as EncryptedReturnType, E as EncryptConfig, K as KeysetIdentifier, t as EncryptedFromBuildableTable, G as EncryptionClientConfig } from '../types-public-QMjYNfQO.cjs';
+import { LockContextInput } from '../identity/index.cjs';
+import { E as EncryptionOperation } from '../base-operation-AOAIvsSB.cjs';
+import { JsPlaintext, AuthStrategy } from '@cipherstash/protect-ffi';
 import 'zod';
-import '../identity/index.cjs';
+
+declare class BatchEncryptQueryOperation extends EncryptionOperation<EncryptedQueryResult[]> {
+    private client;
+    private terms;
+    constructor(client: Client, terms: readonly ScalarQueryTerm[]);
+    withLockContext(lockContext: LockContextInput): BatchEncryptQueryOperationWithLockContext;
+    execute(): Promise<Result<EncryptedQueryResult[], EncryptionError>>;
+}
+declare class BatchEncryptQueryOperationWithLockContext extends EncryptionOperation<EncryptedQueryResult[]> {
+    private client;
+    private terms;
+    private lockContext;
+    constructor(client: Client, terms: readonly ScalarQueryTerm[], lockContext: LockContextInput, auditMetadata?: Record<string, unknown>);
+    execute(): Promise<Result<EncryptedQueryResult[], EncryptionError>>;
+}
+
+declare class BulkDecryptOperation extends EncryptionOperation<BulkDecryptedData> {
+    private client;
+    private encryptedPayloads;
+    constructor(client: Client, encryptedPayloads: BulkDecryptPayload);
+    withLockContext(lockContext: LockContextInput): BulkDecryptOperationWithLockContext;
+    execute(): Promise<Result<BulkDecryptedData, EncryptionError>>;
+    getOperation(): {
+        client: Client;
+        encryptedPayloads: BulkDecryptPayload;
+    };
+}
+declare class BulkDecryptOperationWithLockContext extends EncryptionOperation<BulkDecryptedData> {
+    private operation;
+    private lockContext;
+    constructor(operation: BulkDecryptOperation, lockContext: LockContextInput);
+    execute(): Promise<Result<BulkDecryptedData, EncryptionError>>;
+}
+
+declare class BulkDecryptModelsOperation<T extends Record<string, unknown>> extends EncryptionOperation<Decrypted<T>[]> {
+    private client;
+    private models;
+    constructor(client: Client, models: T[]);
+    withLockContext(lockContext: LockContextInput): BulkDecryptModelsOperationWithLockContext<T>;
+    execute(): Promise<Result<Decrypted<T>[], EncryptionError>>;
+    getOperation(): {
+        client: Client;
+        models: T[];
+    };
+}
+declare class BulkDecryptModelsOperationWithLockContext<T extends Record<string, unknown>> extends EncryptionOperation<Decrypted<T>[]> {
+    private operation;
+    private lockContext;
+    constructor(operation: BulkDecryptModelsOperation<T>, lockContext: LockContextInput);
+    execute(): Promise<Result<Decrypted<T>[], EncryptionError>>;
+}
+
+declare class BulkEncryptOperation extends EncryptionOperation<BulkEncryptedData> {
+    private client;
+    private plaintexts;
+    private column;
+    private table;
+    constructor(client: Client, plaintexts: BulkEncryptPayload, opts: EncryptOptions);
+    withLockContext(lockContext: LockContextInput): BulkEncryptOperationWithLockContext;
+    execute(): Promise<Result<BulkEncryptedData, EncryptionError>>;
+    getOperation(): {
+        client: Client;
+        plaintexts: BulkEncryptPayload;
+        column: BuildableColumn;
+        table: BuildableTable;
+    };
+}
+declare class BulkEncryptOperationWithLockContext extends EncryptionOperation<BulkEncryptedData> {
+    private operation;
+    private lockContext;
+    constructor(operation: BulkEncryptOperation, lockContext: LockContextInput);
+    execute(): Promise<Result<BulkEncryptedData, EncryptionError>>;
+}
+
+declare class BulkEncryptModelsOperation<T extends Record<string, unknown>> extends EncryptionOperation<T[]> {
+    private client;
+    private models;
+    private table;
+    constructor(client: Client, models: Record<string, unknown>[], table: BuildableTable);
+    withLockContext(lockContext: LockContextInput): BulkEncryptModelsOperationWithLockContext<T>;
+    execute(): Promise<Result<T[], EncryptionError>>;
+    getOperation(): {
+        client: Client;
+        models: Record<string, unknown>[];
+        table: BuildableTable;
+    };
+}
+declare class BulkEncryptModelsOperationWithLockContext<T extends Record<string, unknown>> extends EncryptionOperation<T[]> {
+    private operation;
+    private lockContext;
+    constructor(operation: BulkEncryptModelsOperation<T>, lockContext: LockContextInput);
+    execute(): Promise<Result<T[], EncryptionError>>;
+}
+
+/**
+ * Decrypts an encrypted payload using the provided client.
+ * This is the type returned by the {@link EncryptionClient.decrypt | decrypt} method of the {@link EncryptionClient}.
+ */
+declare class DecryptOperation extends EncryptionOperation<JsPlaintext> {
+    private client;
+    private encryptedData;
+    constructor(client: Client, encryptedData: Encrypted | null);
+    withLockContext(lockContext: LockContextInput): DecryptOperationWithLockContext;
+    execute(): Promise<Result<JsPlaintext, EncryptionError>>;
+    getOperation(): {
+        client: Client;
+        encryptedData: Encrypted | null;
+        auditData?: Record<string, unknown>;
+    };
+}
+declare class DecryptOperationWithLockContext extends EncryptionOperation<JsPlaintext> {
+    private operation;
+    private lockContext;
+    constructor(operation: DecryptOperation, lockContext: LockContextInput);
+    execute(): Promise<Result<JsPlaintext, EncryptionError>>;
+}
+
+declare class DecryptModelOperation<T extends Record<string, unknown>> extends EncryptionOperation<Decrypted<T>> {
+    private client;
+    private model;
+    constructor(client: Client, model: T);
+    withLockContext(lockContext: LockContextInput): DecryptModelOperationWithLockContext<T>;
+    execute(): Promise<Result<Decrypted<T>, EncryptionError>>;
+    getOperation(): {
+        client: Client;
+        model: T;
+    };
+}
+declare class DecryptModelOperationWithLockContext<T extends Record<string, unknown>> extends EncryptionOperation<Decrypted<T>> {
+    private operation;
+    private lockContext;
+    constructor(operation: DecryptModelOperation<T>, lockContext: LockContextInput);
+    execute(): Promise<Result<Decrypted<T>, EncryptionError>>;
+}
+
+declare class EncryptOperation extends EncryptionOperation<Encrypted> {
+    private client;
+    private plaintext;
+    private column;
+    private table;
+    constructor(client: Client, plaintext: Plaintext | null, opts: EncryptOptions);
+    withLockContext(lockContext: LockContextInput): EncryptOperationWithLockContext;
+    execute(): Promise<Result<Encrypted, EncryptionError>>;
+    getOperation(): {
+        client: Client;
+        plaintext: Plaintext | null;
+        column: BuildableColumn;
+        table: BuildableTable;
+    };
+}
+declare class EncryptOperationWithLockContext extends EncryptionOperation<Encrypted> {
+    private operation;
+    private lockContext;
+    constructor(operation: EncryptOperation, lockContext: LockContextInput);
+    execute(): Promise<Result<Encrypted, EncryptionError>>;
+}
+
+declare class EncryptModelOperation<T extends Record<string, unknown>> extends EncryptionOperation<T> {
+    private client;
+    private model;
+    private table;
+    constructor(client: Client, model: Record<string, unknown>, table: BuildableTable);
+    withLockContext(lockContext: LockContextInput): EncryptModelOperationWithLockContext<T>;
+    execute(): Promise<Result<T, EncryptionError>>;
+    getOperation(): {
+        client: Client;
+        model: Record<string, unknown>;
+        table: BuildableTable;
+    };
+}
+declare class EncryptModelOperationWithLockContext<T extends Record<string, unknown>> extends EncryptionOperation<T> {
+    private operation;
+    private lockContext;
+    constructor(operation: EncryptModelOperation<T>, lockContext: LockContextInput);
+    execute(): Promise<Result<T, EncryptionError>>;
+}
+
+declare class EncryptQueryOperation extends EncryptionOperation<EncryptedQueryResult> {
+    private client;
+    private plaintext;
+    private opts;
+    constructor(client: Client, plaintext: Plaintext | null | undefined, opts: EncryptQueryOptions);
+    withLockContext(lockContext: LockContextInput): EncryptQueryOperationWithLockContext;
+    execute(): Promise<Result<EncryptedQueryResult, EncryptionError>>;
+    getOperation(): {
+        column: BuildableQueryColumn;
+        table: BuildableTable;
+        queryType?: QueryTypeName;
+        returnType?: EncryptedReturnType;
+        client: Client;
+        plaintext: Plaintext | null | undefined;
+    };
+}
+declare class EncryptQueryOperationWithLockContext extends EncryptionOperation<EncryptedQueryResult> {
+    private client;
+    private plaintext;
+    private opts;
+    private lockContext;
+    constructor(client: Client, plaintext: Plaintext | null | undefined, opts: EncryptQueryOptions, lockContext: LockContextInput, auditMetadata?: Record<string, unknown>);
+    execute(): Promise<Result<EncryptedQueryResult, EncryptionError>>;
+}
+
+declare const noClientError: () => Error;
+/**
+ * Resolve the EQL wire version for a client from its schema set.
+ *
+ * One FFI client emits exactly one wire format, so the whole schema set must
+ * agree. EQL v3 tables (from `@cipherstash/stack/v3`) are detected by their
+ * `buildColumnKeyMap()` marker — v2 tables don't have one:
+ *
+ * - every schema is v3 → `3`;
+ * - no schema is v3 → `undefined`, leaving the FFI's v2 default (and its
+ *   byte-identical v2 output) untouched;
+ * - a mix of the two → throws: the v2 tables target `eql_v2_encrypted`
+ *   columns and the v3 tables target `eql_v3` domains, so no single wire
+ *   format serves both. Split them across two clients.
+ *
+ * An explicit `config.eqlVersion` bypasses detection (the wire format is
+ * then unambiguous — e.g. writing v2-wire from a v3 schema set during a
+ * migration), but a mixed schema set still throws.
+ *
+ * @internal exported for unit-test coverage of the detection matrix.
+ */
+declare function resolveEqlVersion(schemas: readonly BuildableTable[], explicit?: 2 | 3): 2 | 3 | undefined;
+/** The EncryptionClient is the main entry point for interacting with the CipherStash Encryption library.
+ * It provides methods for encrypting and decrypting individual values, as well as models (objects) and bulk operations.
+ *
+ * The client must be initialized using the {@link Encryption} function before it can be used.
+ */
+declare class EncryptionClient {
+    private client;
+    private encryptConfig;
+    /**
+     * Initializes the EncryptionClient with the provided configuration.
+     * @internal
+     * @param config - The configuration object for initializing the client.
+     * @returns A promise that resolves to a {@link Result} containing the initialized EncryptionClient or an {@link EncryptionError}.
+     **/
+    init(config: {
+        encryptConfig: EncryptConfig;
+        workspaceCrn?: string;
+        accessKey?: string;
+        clientId?: string;
+        clientKey?: string;
+        keyset?: KeysetIdentifier;
+        authStrategy?: AuthStrategy;
+        eqlVersion?: 2 | 3;
+    }): Promise<Result<EncryptionClient, EncryptionError>>;
+    /**
+     * Encrypt a value - returns a promise which resolves to an encrypted value.
+     *
+     * @param plaintext - The plaintext value to be encrypted.
+     * @param opts - Options specifying the column (or nested field) and table for encryption. See {@link EncryptOptions}.
+     * @returns An EncryptOperation that can be awaited or chained with additional methods.
+     *
+     * @example
+     * The following example demonstrates how to encrypt a value using the Encryption client.
+     * It includes defining an encryption schema with {@link encryptedTable} and {@link encryptedColumn},
+     * initializing the client with {@link Encryption}, and performing the encryption.
+     *
+     * `encrypt` returns an {@link EncryptOperation} which can be awaited to get a {@link Result}
+     * which can either be the encrypted value or an {@link EncryptionError}.
+     *
+     * ```typescript
+     * // Define encryption schema
+     * import { Encryption } from "@cipherstash/stack"
+     * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+     * const userSchema = encryptedTable("users", {
+     *  email: encryptedColumn("email"),
+     * });
+     *
+     * // Initialize Encryption client
+     * const client = await Encryption({ schemas: [userSchema] })
+     *
+     * // Encrypt a value
+     * const encryptedResult = await client.encrypt(
+     *  "person@example.com",
+     *  { column: userSchema.email, table: userSchema }
+     * )
+     *
+     * // Handle encryption result
+     * if (encryptedResult.failure) {
+     *   throw new Error(`Encryption failed: ${encryptedResult.failure.message}`);
+     * }
+     *
+     * console.log("Encrypted data:", encryptedResult.data);
+     * ```
+     *
+     * @example
+     * When encrypting data, a {@link LockContext} can be provided to tie the encryption to a specific user or session.
+     * This ensures that the same lock context is required for decryption.
+     *
+     * The following example demonstrates how to create a lock context using a user's JWT token
+     * and use it during encryption.
+     *
+     * ```typescript
+     * // Define encryption schema and initialize client as above
+     *
+     * // Create a lock for the user's `sub` claim from their JWT
+     * const lc = new LockContext();
+     * const lockContext = await lc.identify(userJwt);
+     *
+     * if (lockContext.failure) {
+     *   // Handle the failure
+     * }
+     *
+     * // Encrypt a value with the lock context
+     * // Decryption will then require the same lock context
+     * const encryptedResult = await client.encrypt(
+     *  "person@example.com",
+     *  { column: userSchema.email, table: userSchema }
+     * )
+     *  .withLockContext(lockContext)
+     * ```
+     *
+     * @see {@link EncryptOptions}
+     * @see {@link Result}
+     * @see {@link encryptedTable}
+     * @see {@link encryptedColumn}
+     * @see {@link encryptedField}
+     * @see {@link LockContext}
+     * @see {@link EncryptOperation}
+     */
+    encrypt(plaintext: Plaintext, opts: EncryptOptions): EncryptOperation;
+    /**
+     * Encrypt a query value - returns a promise which resolves to an encrypted query value.
+     *
+     * @param plaintext - The plaintext value to be encrypted for querying.
+     * @param opts - Options specifying the column, table, and optional queryType for encryption.
+     * @returns An EncryptQueryOperation that can be awaited or chained with additional methods.
+     *
+     * @example
+     * The following example demonstrates how to encrypt a query value using the Encryption client.
+     *
+     * ```typescript
+     * // Define encryption schema
+     * import { Encryption } from "@cipherstash/stack"
+     * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+     * const userSchema = encryptedTable("users", {
+     *  email: encryptedColumn("email").equality(),
+     * });
+     *
+     * // Initialize Encryption client
+     * const client = await Encryption({ schemas: [userSchema] })
+     *
+     * // Encrypt a query value
+     * const encryptedResult = await client.encryptQuery(
+     *  "person@example.com",
+     *  { column: userSchema.email, table: userSchema, queryType: 'equality' }
+     * )
+     *
+     * // Handle encryption result
+     * if (encryptedResult.failure) {
+     *   throw new Error(`Encryption failed: ${encryptedResult.failure.message}`);
+     * }
+     *
+     * console.log("Encrypted query:", encryptedResult.data);
+     * ```
+     *
+     * @example
+     * The queryType can be auto-inferred from the column's configured indexes:
+     *
+     * ```typescript
+     * // When queryType is omitted, it will be inferred from the column's indexes
+     * const encryptedResult = await client.encryptQuery(
+     *  "person@example.com",
+     *  { column: userSchema.email, table: userSchema }
+     * )
+     * ```
+     *
+     * @see {@link EncryptQueryOperation}
+     *
+     * **JSONB columns (searchableJson):**
+     * When `queryType` is omitted on a `searchableJson()` column, the query operation is inferred:
+     * - String plaintext → `steVecSelector` (JSONPath queries like `'$.user.email'`)
+     * - Object/Array plaintext → `steVecTerm` (containment queries like `{ role: 'admin' }`)
+     */
+    encryptQuery(plaintext: Plaintext, opts: EncryptQueryOptions): EncryptQueryOperation;
+    /**
+     * Encrypt multiple values for use in queries (batch operation).
+     * @param terms - Array of query terms to encrypt
+     */
+    encryptQuery(terms: readonly ScalarQueryTerm[]): BatchEncryptQueryOperation;
+    /**
+     * Decryption - returns a promise which resolves to a decrypted value.
+     *
+     * @param encryptedData - The encrypted data to be decrypted.
+     * @returns A DecryptOperation that can be awaited or chained with additional methods.
+     *
+     * @example
+     * The following example demonstrates how to decrypt a value that was previously encrypted using the {@link encrypt} method.
+     * It includes encrypting a value first, then decrypting it, and handling the result.
+     *
+     * ```typescript
+     * const encryptedData = await client.encrypt(
+     *  "person@example.com",
+     *  { column: "email", table: "users" }
+     * )
+     * const decryptResult = await client.decrypt(encryptedData)
+     * if (decryptResult.failure) {
+     *   throw new Error(`Decryption failed: ${decryptResult.failure.message}`);
+     * }
+     * console.log("Decrypted data:", decryptResult.data);
+     * ```
+     *
+     * @example
+     * Provide a lock context when decrypting:
+     * ```typescript
+     *    await client.decrypt(encryptedData)
+     *      .withLockContext(lockContext)
+     * ```
+     *
+     * @remarks
+     * The public input type rejects null, but at runtime `decrypt` will
+     * short-circuit and return null when given a null ciphertext
+     * (defense in depth for legacy / manually-NULLed DB rows reached via
+     * casts or dynamic field walking). The narrow return type holds for
+     * any caller that respects the input contract.
+     *
+     * @see {@link LockContext}
+     * @see {@link DecryptOperation}
+     */
+    decrypt(encryptedData: Encrypted): DecryptOperation;
+    /**
+     * Encrypt a model (object) based on the table schema.
+     *
+     * Only fields whose keys match columns defined in the table schema are encrypted.
+     * All other fields are passed through unchanged. Returns a thenable operation
+     * that supports `.withLockContext()` for identity-aware encryption.
+     *
+     * The return type is **schema-aware**: fields matching the table schema are
+     * typed as `Encrypted`, while other fields retain their original types. For
+     * best results, let TypeScript infer the type parameters from the arguments
+     * rather than providing an explicit type argument.
+     *
+     * @param input - The model object with plaintext values to encrypt.
+     * @param table - The table schema defining which fields to encrypt.
+     * @returns An `EncryptModelOperation` that can be awaited to get a `Result`
+     *   containing the model with schema-defined fields typed as `Encrypted`,
+     *   or an `EncryptionError`.
+     *
+     * @example
+     * ```typescript
+     * import { Encryption } from "@cipherstash/stack"
+     * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+     *
+     * type User = { id: string; email: string; createdAt: Date }
+     *
+     * const usersSchema = encryptedTable("users", {
+     *   email: encryptedColumn("email").equality(),
+     * })
+     *
+     * const client = await Encryption({ schemas: [usersSchema] })
+     *
+     * // Let TypeScript infer the return type from the schema.
+     * // result.data.email is typed as `Encrypted`, result.data.id stays `string`.
+     * const result = await client.encryptModel(
+     *   { id: "user_123", email: "alice@example.com", createdAt: new Date() },
+     *   usersSchema,
+     * )
+     *
+     * if (result.failure) {
+     *   console.error(result.failure.message)
+     * } else {
+     *   console.log(result.data.id)    // string
+     *   console.log(result.data.email) // Encrypted
+     * }
+     * ```
+     */
+    encryptModel<T extends Record<string, unknown>, Table extends BuildableTable>(input: T, table: Table): EncryptModelOperation<EncryptedFromBuildableTable<T, Table>>;
+    /**
+     * Decrypt a model (object) whose fields contain encrypted values.
+     *
+     * Identifies encrypted fields automatically and decrypts them, returning the
+     * model with plaintext values. Returns a thenable operation that supports
+     * `.withLockContext()` for identity-aware decryption.
+     *
+     * @param input - The model object with encrypted field values.
+     * @returns A `DecryptModelOperation<T>` that can be awaited to get a `Result`
+     *   containing the model with decrypted plaintext fields, or an `EncryptionError`.
+     *
+     * @example
+     * ```typescript
+     * // Decrypt a previously encrypted model
+     * const decrypted = await client.decryptModel<User>(encryptedUser)
+     *
+     * if (decrypted.failure) {
+     *   console.error(decrypted.failure.message)
+     * } else {
+     *   console.log(decrypted.data.email) // "alice@example.com"
+     * }
+     *
+     * // With a lock context
+     * const decrypted = await client
+     *   .decryptModel<User>(encryptedUser)
+     *   .withLockContext(lockContext)
+     * ```
+     */
+    decryptModel<T extends Record<string, unknown>>(input: T): DecryptModelOperation<T>;
+    /**
+     * Encrypt multiple models (objects) in a single bulk operation.
+     *
+     * Performs a single call to ZeroKMS regardless of the number of models,
+     * while still using a unique key for each encrypted value. Only fields
+     * matching the table schema are encrypted; other fields pass through unchanged.
+     *
+     * The return type is **schema-aware**: fields matching the table schema are
+     * typed as `Encrypted`, while other fields retain their original types. For
+     * best results, let TypeScript infer the type parameters from the arguments.
+     *
+     * @param input - An array of model objects with plaintext values to encrypt.
+     * @param table - The table schema defining which fields to encrypt.
+     * @returns A `BulkEncryptModelsOperation` that can be awaited to get a `Result`
+     *   containing an array of models with schema-defined fields typed as `Encrypted`,
+     *   or an `EncryptionError`.
+     *
+     * @example
+     * ```typescript
+     * import { Encryption } from "@cipherstash/stack"
+     * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+     *
+     * type User = { id: string; email: string }
+     *
+     * const usersSchema = encryptedTable("users", {
+     *   email: encryptedColumn("email"),
+     * })
+     *
+     * const client = await Encryption({ schemas: [usersSchema] })
+     *
+     * // Let TypeScript infer the return type from the schema.
+     * // Each item's email is typed as `Encrypted`, id stays `string`.
+     * const result = await client.bulkEncryptModels(
+     *   [
+     *     { id: "1", email: "alice@example.com" },
+     *     { id: "2", email: "bob@example.com" },
+     *   ],
+     *   usersSchema,
+     * )
+     *
+     * if (!result.failure) {
+     *   console.log(result.data) // array of models with encrypted email fields
+     * }
+     * ```
+     */
+    bulkEncryptModels<T extends Record<string, unknown>, Table extends BuildableTable>(input: Array<T>, table: Table): BulkEncryptModelsOperation<EncryptedFromBuildableTable<T, Table>>;
+    /**
+     * Decrypt multiple models (objects) in a single bulk operation.
+     *
+     * Performs a single call to ZeroKMS regardless of the number of models,
+     * restoring all encrypted fields to their original plaintext values.
+     *
+     * @param input - An array of model objects with encrypted field values.
+     * @returns A `BulkDecryptModelsOperation<T>` that can be awaited to get a `Result`
+     *   containing an array of models with decrypted plaintext fields, or an `EncryptionError`.
+     *
+     * @example
+     * ```typescript
+     * const encryptedUsers = encryptedResult.data // from bulkEncryptModels
+     *
+     * const result = await client.bulkDecryptModels<User>(encryptedUsers)
+     *
+     * if (!result.failure) {
+     *   for (const user of result.data) {
+     *     console.log(user.email) // plaintext email
+     *   }
+     * }
+     *
+     * // With a lock context
+     * const result = await client
+     *   .bulkDecryptModels<User>(encryptedUsers)
+     *   .withLockContext(lockContext)
+     * ```
+     */
+    bulkDecryptModels<T extends Record<string, unknown>>(input: Array<T>): BulkDecryptModelsOperation<T>;
+    /**
+     * Encrypt multiple plaintext values in a single bulk operation.
+     *
+     * Each value is encrypted with its own unique key via a single call to ZeroKMS.
+     * Values can include optional `id` fields for correlating results back to
+     * your application data.
+     *
+     * @param plaintexts - An array of objects with `plaintext` (and optional `id`) fields.
+     * @param opts - Options specifying the target column (or nested {@link encryptedField}) and table. See {@link EncryptOptions}.
+     * @returns A `BulkEncryptOperation` that can be awaited to get a `Result`
+     *   containing an array of `{ id?, data: Encrypted }` objects, or an `EncryptionError`.
+     *
+     * @example
+     * ```typescript
+     * import { Encryption } from "@cipherstash/stack"
+     * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+     *
+     * const users = encryptedTable("users", {
+     *   email: encryptedColumn("email"),
+     * })
+     * const client = await Encryption({ schemas: [users] })
+     *
+     * const result = await client.bulkEncrypt(
+     *   [
+     *     { id: "u1", plaintext: "alice@example.com" },
+     *     { id: "u2", plaintext: "bob@example.com" },
+     *   ],
+     *   { column: users.email, table: users },
+     * )
+     *
+     * if (!result.failure) {
+     *   // result.data = [{ id: "u1", data: Encrypted }, { id: "u2", data: Encrypted }, ...]
+     *   console.log(result.data)
+     * }
+     * ```
+     */
+    bulkEncrypt(plaintexts: BulkEncryptPayload, opts: EncryptOptions): BulkEncryptOperation;
+    /**
+     * Decrypt multiple encrypted values in a single bulk operation.
+     *
+     * Performs a single call to ZeroKMS to decrypt all values. The result uses
+     * a multi-status pattern: each item in the returned array has either a `data`
+     * field (success) or an `error` field (failure), allowing graceful handling
+     * of partial failures.
+     *
+     * @param encryptedPayloads - An array of objects with `data` (encrypted payload) and optional `id` fields.
+     * @returns A `BulkDecryptOperation` that can be awaited to get a `Result`
+     *   containing an array of `{ id?, data: plaintext }` or `{ id?, error: string }` objects,
+     *   or an `EncryptionError` if the entire operation fails.
+     *
+     * @example
+     * ```typescript
+     * const encrypted = await client.bulkEncrypt(plaintexts, { column: users.email, table: users })
+     *
+     * const result = await client.bulkDecrypt(encrypted.data)
+     *
+     * if (!result.failure) {
+     *   for (const item of result.data) {
+     *     if ("data" in item) {
+     *       console.log(`${item.id}: ${item.data}`)
+     *     } else {
+     *       console.error(`${item.id} failed: ${item.error}`)
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    bulkDecrypt(encryptedPayloads: BulkDecryptPayload): BulkDecryptOperation;
+    /**
+     * Get the encrypt config object.
+     *
+     * @returns The encrypt config object.
+     */
+    getEncryptConfig(): EncryptConfig | undefined;
+}
+/**
+ * Reset the once-per-process deprecation-warning latch. Test-only hook so
+ * suites can assert the warning fires deterministically, independent of test
+ * ordering. Not re-exported from the package entry, so it stays off the public
+ * API surface.
+ * @internal
+ */
+declare function __resetStrategyDeprecationWarningForTests(): void;
+/**
+ * Creates and initializes an Encryption client for encrypting and decrypting data with CipherStash.
+ *
+ * Provide at least one schema (from {@link encryptedTable}) so the client knows which tables and
+ * columns to use:
+ *
+ * ```typescript
+ * import { Encryption, encryptedTable, encryptedColumn } from "@cipherstash/stack"
+ *
+ * const users = encryptedTable("users", { email: encryptedColumn("email") })
+ * const client = await Encryption({ schemas: [users] })
+ * const result = await client.encrypt("alice@example.com", { column: users.email, table: users })
+ * ```
+ *
+ * ## Authentication
+ *
+ * The snippets in this section reuse the `users` schema from the example above, and
+ * `workspaceCrn` / `accessKey` stand in for your own workspace credentials (from the
+ * [dashboard](https://dashboard.cipherstash.com) or the `CS_*` variables below).
+ *
+ * By default the client uses the `auto` auth strategy. `auto` first looks for the `CS_*`
+ * environment variables (see below) and, if they are not set, falls back to the local **dev
+ * profile** on your machine. The dev profile also supplies the client key, so during local
+ * development you generally don't need to set any environment variables at all.
+ *
+ * ### Local development — create a dev profile
+ *
+ * Log in once to create the dev profile that `auto` picks up automatically:
+ *
+ * ```bash
+ * npx stash auth login
+ * ```
+ *
+ * ### Production / CI — environment variables
+ *
+ * In production and CI you typically authenticate with the four `CS_*` environment variables
+ * instead of a dev profile. Developers can obtain these values from the
+ * [CipherStash dashboard](https://dashboard.cipherstash.com):
+ *
+ * | Environment variable   | Description                                                                    |
+ * | ---------------------- | ------------------------------------------------------------------------------ |
+ * | `CS_WORKSPACE_CRN`     | The workspace Cloud Resource Name (CRN) that identifies your workspace.         |
+ * | `CS_CLIENT_ID`         | The client identifier issued when you create an access key.                    |
+ * | `CS_CLIENT_KEY`        | The client key material combined with ZeroKMS to perform encryption.           |
+ * | `CS_CLIENT_ACCESS_KEY` | The API access key used to authenticate requests to CipherStash.               |
+ *
+ * When these are set, `auto` uses them in preference to the local dev profile.
+ *
+ * ### Custom auth strategies — `config.authStrategy`
+ *
+ * For finer control, pass an explicit strategy via `config.authStrategy` (from `@cipherstash/auth`,
+ * re-exported by `@cipherstash/stack`). See the `@cipherstash/auth` package for the full list. Two
+ * common choices:
+ *
+ * `AccessKeyStrategy` — like `auto`, but only ever uses an access key; it never falls back to the
+ * local dev profile. Ideal for services and CI:
+ *
+ * ```typescript
+ * import { Encryption, AccessKeyStrategy } from "@cipherstash/stack"
+ *
+ * const client = await Encryption({
+ *   schemas: [users],
+ *   config: {
+ *     authStrategy: AccessKeyStrategy.create(workspaceCrn, accessKey),
+ *   },
+ * })
+ * ```
+ *
+ * `OidcFederationStrategy` — authenticate end users through your own identity provider (Supabase,
+ * Clerk, Auth0 or Okta) by federating their OIDC JWT into a CipherStash token. Add the provider to
+ * your workspace first at
+ * [dashboard.cipherstash.com/workspaces/_/oidc-providers](https://dashboard.cipherstash.com/workspaces/_/oidc-providers)
+ * (the `_` in the URL resolves to whichever workspace you select):
+ *
+ * ```typescript
+ * import { Encryption, OidcFederationStrategy } from "@cipherstash/stack"
+ *
+ * // Authenticate every ZeroKMS request as the signed-in user.
+ * const client = await Encryption({
+ *   schemas: [users],
+ *   config: {
+ *     authStrategy: OidcFederationStrategy.create(workspaceCrn, () => getUserJwt()),
+ *   },
+ * })
+ * ```
+ *
+ * ### Lock context (identity-bound encryption)
+ *
+ * Lock context is an **additional** capability layered on top of `OidcFederationStrategy`: it
+ * requires that strategy, but `OidcFederationStrategy` does not require lock context. It binds a
+ * value to a claim from the user's JWT (typically `sub`) so that only the user who encrypted a
+ * value can decrypt it:
+ *
+ * ```typescript
+ * // Bind the data key to the user's `sub` claim.
+ * const result = await client
+ *   .encrypt("alice@example.com", { column: users.email, table: users })
+ *   .withLockContext({ identityClaim: ["sub"] })
+ * ```
+ *
+ * Because the lock is tied to a specific end user's identity, `AccessKeyStrategy` (which
+ * authenticates a service, not a user) is not valid for lock context — there is no user `sub`
+ * claim to bind to.
+ *
+ * ## Keysets (multi-tenant isolation)
+ *
+ * Pass `config.keyset` to encrypt under a specific **keyset** — a named or UUID-identified keyspace
+ * that gives each tenant its own cryptographic isolation, so data encrypted under one keyset cannot
+ * be decrypted under another. Create and manage keysets in the
+ * [dashboard](https://dashboard.cipherstash.com/workspaces/_/keysets) (the `_` in the URL resolves
+ * to whichever workspace you select); omit `config.keyset` to use the workspace's default keyset.
+ *
+ * ```typescript
+ * // `users` is the schema from the first example above.
+ * const client = await Encryption({
+ *   schemas: [users],
+ *   config: {
+ *     keyset: { name: "tenant-a" }, // or { id: "<uuid>" }
+ *   },
+ * })
+ * ```
+ *
+ * A client is bound to a single keyset for its lifetime, so multi-tenant applications use **one
+ * `Encryption()` client per tenant**. Keysets are orthogonal to `authStrategy` and lock context —
+ * they isolate a whole tenant's *keyspace* (coarse, fixed per client), whereas lock context binds
+ * an individual value to a user's identity claim (fine-grained, per operation) — and can be
+ * combined with both.
+ *
+ * @param config - Initialization options. Must include `schemas`; optionally include `config` for
+ *   credentials and authentication. Logging is configured via the `STASH_STACK_LOG` environment
+ *   variable (`debug | info | error`, default: `error`).
+ * @returns A Promise that resolves to an initialized {@link EncryptionClient} ready for
+ *   {@link EncryptionClient.encrypt}, {@link EncryptionClient.decrypt}, and related operations.
+ *
+ * @throws Throws if `schemas` is empty, or if a keyset `id` is supplied but is not a valid UUID.
+ *   Also throws if the client fails to initialize (e.g. invalid credentials or config).
+ *
+ * @see {@link EncryptionClientConfig} for full config options.
+ * @see {@link ClientConfig.authStrategy} for the auth strategy field.
+ * @see {@link EncryptionClient} for available methods after initialization.
+ */
+declare const Encryption: (config: EncryptionClientConfig) => Promise<EncryptionClient>;
+
+export { BatchEncryptQueryOperation, BulkDecryptModelsOperation, BulkDecryptOperation, BulkEncryptModelsOperation, BulkEncryptOperation, DecryptModelOperation, DecryptOperation, EncryptModelOperation, EncryptOperation, EncryptQueryOperation, Encryption, EncryptionClient, __resetStrategyDeprecationWarningForTests, noClientError, resolveEqlVersion };