@cipherstash/stack 0.19.0 → 1.0.0-rc.1

package/dist/types-public.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types-public.ts","../src/types.ts"],"sourcesContent":["/**\n * Public type re-exports for `@cipherstash/stack/types`.\n *\n * This module exposes only the public types from the internal types module.\n * Internal helpers (`queryTypeToFfi`, `queryTypeToQueryOp`, `FfiIndexTypeName`,\n * `QueryTermBase`) are excluded.\n */\n\n// Core types\n// Client configuration\n// Encrypt / decrypt operation options and results\n// Model field types\n// Bulk operations\n// Query types (public only)\nexport type {\n  AuthStrategy,\n  BuildableColumn,\n  BuildableQueryColumn,\n  BuildableTable,\n  BuildableTableColumns,\n  BuildableV3QueryableColumn,\n  BulkDecryptedData,\n  BulkDecryptPayload,\n  BulkEncryptedData,\n  BulkEncryptPayload,\n  Client,\n  ClientConfig,\n  Decrypted,\n  DecryptedFields,\n  DecryptionResult,\n  Encrypted,\n  EncryptedFields,\n  EncryptedFromBuildableTable,\n  EncryptedFromSchema,\n  EncryptedQuery,\n  EncryptedQueryResult,\n  EncryptedReturnType,\n  EncryptedSearchTerm,\n  EncryptedValue,\n  EncryptionClientConfig,\n  EncryptOptions,\n  EncryptQueryOptions,\n  KeysetIdentifier,\n  OtherFields,\n  QueryTypeName,\n  ScalarQueryTerm,\n  SearchTerm,\n} from '@/types'\n\n// Runtime values\nexport { queryTypes } from '@/types'\n","import type {\n  AuthStrategy,\n  Encrypted as CipherStashEncrypted,\n  EncryptedPayload as CipherStashEncryptedPayload,\n  EncryptedQuery as CipherStashEncryptedQuery,\n  EncryptedV3Query as CipherStashEncryptedV3Query,\n  JsPlaintext,\n  newClient,\n  QueryOpName,\n} from '@cipherstash/protect-ffi'\nimport type {\n  ColumnSchema,\n  EncryptedColumn,\n  EncryptedField,\n  EncryptedTableColumn,\n  // Imported type-only for the TSDoc {@link} references in the comments below.\n  encryptedColumn,\n  encryptedField,\n} from '@/schema'\n\n/**\n * A pluggable authentication strategy for ZeroKMS requests. Any object\n * with a `getToken(): Promise<{ token: string }>` method satisfies it —\n * notably the strategies from `@cipherstash/auth`: `OidcFederationStrategy`\n * (per-user, identity-bound encryption) and `AccessKeyStrategy`\n * (service-to-service / CI). When supplied to {@link ClientConfig.authStrategy},\n * `getToken()` is invoked on every ZeroKMS request, taking precedence over\n * the default `auto` strategy.\n *\n * @see ClientConfig.authStrategy\n */\nexport type { AuthStrategy }\n\n// ---------------------------------------------------------------------------\n// Branded type utilities\n// ---------------------------------------------------------------------------\n\n/** Brand symbol for nominal typing */\ndeclare const __brand: unique symbol\n\n/** Creates a branded type that is structurally incompatible with the base type */\ntype Brand<T, B extends string> = T & { readonly [__brand]: B }\n\n// ---------------------------------------------------------------------------\n// Core types\n// ---------------------------------------------------------------------------\n\nexport type Client = Awaited<ReturnType<typeof newClient>> | undefined\n\n/** A branded type representing encrypted data. Cannot be accidentally used as plaintext. */\nexport type EncryptedValue = Brand<CipherStashEncrypted, 'encrypted'>\n\n/** Structural type representing encrypted data stored in the database. Always\n * carries a ciphertext. Covers BOTH wire formats: the EQL v2.3 payloads\n * (`k: \"ct\"` / `k: \"sv\"`) and the EQL v3 payloads (flat `{v: 3, i, c, …}`\n * scalars and `{v: 3, k: \"sv\", i, sv}` SteVec documents). Which format\n * `encrypt` produces is selected by the client's\n * {@link ClientConfig.eqlVersion}; `decrypt` accepts both regardless.\n * v3 scalars carry no `k` discriminator, so narrow with `'k' in payload`\n * before reading it. See also `EncryptedValue` for branded nominal typing,\n * and {@link EncryptedQuery} for the search-term shape returned by\n * `encryptQuery`. */\nexport type Encrypted = CipherStashEncryptedPayload\n\n/** Structural type representing an encrypted query term (search needle)\n * returned by `encryptQuery` / `encryptQueryBulk` for scalar\n * (`unique` / `match` / `ore`) lookups and `ste_vec_selector` JSON path\n * queries, plus — under `eqlVersion: 3` — the `eql_v3.jsonb_query`\n * containment needle. Carries no ciphertext — matched against stored\n * values, never decrypted. v2 JSON containment queries (`ste_vec_term`)\n * return a storage-shaped {@link Encrypted} payload instead. */\nexport type EncryptedQuery =\n  | CipherStashEncryptedQuery\n  | CipherStashEncryptedV3Query\n\n/**\n * Plaintext values the SDK accepts for encryption.\n *\n * Widens the FFI's `JsPlaintext` (`string | number | boolean |\n * Record<string, unknown> | JsPlaintext[]`) with `Date`. `Date` is a supported\n * cast target that is omitted from the FFI's `JsPlaintext` INPUT union, but it\n * serializes at the boundary via `toJSON` (ISO string), so it is accepted on the\n * way in.\n *\n * `bigint` is intentionally NOT included: the native `@cipherstash/protect-ffi`\n * build cannot marshal a JS `bigint` (V8 throws \"Do not know how to serialize a\n * BigInt\") and rejects a `string` for a `big_int` column. The v3 int8 domains\n * are therefore omitted from the SDK entirely (see `eql/v3`) until the FFI\n * supports lossless bigint I/O; `bigint` returns here alongside them.\n *\n * When the upstream FFI `JsPlaintext` is corrected to include `Date`, the `Date`\n * arm can collapse back into `JsPlaintext`.\n */\nexport type Plaintext = JsPlaintext | Date\n\n// ---------------------------------------------------------------------------\n// Client configuration\n// ---------------------------------------------------------------------------\n\nexport type KeysetIdentifier = { name: string } | { id: string }\n\nexport type ClientConfig = {\n  /**\n   * The CipherStash workspace CRN (Cloud Resource Name).\n   * Format: `crn:<region>.aws:<workspace-id>`.\n   * Can also be set via the `CS_WORKSPACE_CRN` environment variable.\n   */\n  workspaceCrn?: string\n\n  /**\n   * The API access key used for authenticating with the CipherStash API.\n   * Can also be set via the `CS_CLIENT_ACCESS_KEY` environment variable.\n   * Obtain this from the CipherStash dashboard after creating a workspace.\n   */\n  accessKey?: string\n\n  /**\n   * The client identifier used to authenticate with CipherStash services.\n   * Can also be set via the `CS_CLIENT_ID` environment variable.\n   * Generated during workspace onboarding in the CipherStash dashboard.\n   */\n  clientId?: string\n\n  /**\n   * The client key material used in combination with ZeroKMS for encryption operations.\n   * Can also be set via the `CS_CLIENT_KEY` environment variable.\n   * Generated during workspace onboarding in the CipherStash dashboard.\n   */\n  clientKey?: string\n\n  /**\n   * An optional keyset identifier for multi-tenant encryption.\n   * Each keyset provides cryptographic isolation, giving each tenant its own keyspace.\n   * Specify by name (`{ name: \"tenant-a\" }`) or UUID (`{ id: \"...\" }`).\n   * Keysets are created and managed in the\n   * [dashboard](https://dashboard.cipherstash.com/workspaces/_/keysets); omit to\n   * use the workspace's default keyset. A client is bound to one keyset for its\n   * lifetime, so use one client per tenant.\n   *\n   * @see {@link Encryption} for the full keysets walkthrough.\n   */\n  keyset?: KeysetIdentifier\n\n  /**\n   * An optional authentication strategy for ZeroKMS requests, from\n   * `@cipherstash/auth` (re-exported by `@cipherstash/stack`). When provided,\n   * its `getToken()` is invoked on every ZeroKMS request and takes precedence\n   * over the default `auto` strategy (the `clientKey` is still required for\n   * encryption). Use:\n   *\n   * - `OidcFederationStrategy` for per-user, identity-bound encryption —\n   *   federates an end user's OIDC JWT into a CTS service token, so requests\n   *   authenticate as that user. Pair with `.withLockContext({ identityClaim })`\n   *   to bind the data key to a claim. This replaces the older\n   *   `LockContext.identify()` ceremony.\n   * - `AccessKeyStrategy` for service-to-service / CI, or any custom\n   *   `{ getToken() }` object for bespoke token acquisition / caching.\n   *\n   * Leave unset to use the default `auto` strategy, which reads credentials\n   * from the `CS_*` environment variables and falls back to the local dev\n   * profile created by `npx stash auth login`.\n   *\n   * @see {@link AuthStrategy}\n   * @see {@link Encryption} for a full walkthrough of the authentication options.\n   */\n  authStrategy?: AuthStrategy\n\n  /**\n   * @deprecated Renamed to {@link ClientConfig.authStrategy}. Still honoured for\n   * backwards compatibility — passing it logs a deprecation warning at runtime —\n   * but it will be removed in a future release. Set `authStrategy` instead.\n   */\n  strategy?: AuthStrategy\n\n  /**\n   * The EQL wire version the client emits — one FFI client always emits\n   * exactly one wire format.\n   *\n   * - `2` (the protect-ffi default): payloads target the\n   *   `eql_v2_encrypted` column type.\n   * - `3`: payloads target the per-capability `eql_v3` domains\n   *   (`eql_v3.text_eq`, `eql_v3.integer_ord_ore`, `eql_v3.json`, …),\n   *   derived from each column's `cast_as` and indexes.\n   *\n   * When omitted, {@link Encryption} auto-detects from the schema set:\n   * EQL v3 tables (from `@cipherstash/stack/v3`, marked by\n   * `buildColumnKeyMap()`) select `3`; v2 tables leave the FFI default\n   * (`2`) untouched. Mixing v2 and v3 tables in one client is an error —\n   * split them across two clients instead.\n   *\n   * `decrypt` accepts BOTH formats regardless of this setting, so v2 and\n   * v3 data can coexist during a migration.\n   *\n   * v3 limitation (protect-ffi 0.27): `encryptQuery` supports only JSON\n   * containment queries — scalar-index and selector queries throw\n   * `EQL_V3_QUERY_UNSUPPORTED` until a v3 scalar query wire shape exists.\n   */\n  eqlVersion?: 2 | 3\n}\n\ntype AtLeastOneCsTable<T> = [T, ...T[]]\n\n/** Structural contract for a column builder the client can consume for STORAGE\n *  (`encrypt`). Satisfied by v2 `EncryptedColumn` / `EncryptedField` AND v3\n *  `EncryptedTextSearchColumn` — fields ARE encryptable, so this stays wide. */\nexport interface BuildableColumn {\n  getName(): string\n  build(): ColumnSchema\n}\n\n/** Structural contract for a column the client can consume for QUERIES\n *  (`encryptQuery` / search terms). Narrower than `BuildableColumn`: it must\n *  EXCLUDE non-queryable `EncryptedField` (a field has no indexes). A v2\n *  `EncryptedColumn` qualifies via the nominal arm; a v3 queryable concrete\n *  type qualifies via the `getEqlType()` structural arm; `EncryptedField` (no\n *  `getEqlType`, not an `EncryptedColumn`) is rejected. */\nexport interface BuildableV3QueryableColumn extends BuildableColumn {\n  getEqlType(): string\n  getQueryCapabilities(): {\n    equality: boolean\n    orderAndRange: boolean\n    freeTextSearch: boolean\n  }\n  isQueryable(): true\n}\n\nexport type BuildableQueryColumn = EncryptedColumn | BuildableV3QueryableColumn\n\n/** Structural contract for a table builder the client can consume. Satisfied by\n *  v2 and v3 `EncryptedTable` alike. */\nexport interface BuildableTable {\n  tableName: string\n  build(): { tableName: string; columns: Record<string, ColumnSchema> }\n  /**\n   * Optional map from a model field's JS property name to its encrypt-config\n   * column name (the DB name). Present when the two can differ — v3 tables key\n   * their config by DB name (`column.getName()`) while models are written with\n   * JS property keys, so the model path must match by property but address the\n   * FFI/config by DB name.\n   *\n   * Absent on v2 tables, whose `build()` already keys columns by the JS property\n   * name; the model path then matches and addresses by that same key.\n   */\n  buildColumnKeyMap?(): Record<string, string>\n}\n\nexport type EncryptionClientConfig = {\n  schemas: AtLeastOneCsTable<BuildableTable>\n  config?: ClientConfig\n}\n\n/**\n * The literal column map of a buildable table, read from its type-level\n * `_columnType` brand. Both v2 and v3 `EncryptedTable` carry this brand, so this\n * recovers the literal column keys structurally.\n *\n * This deliberately uses the `_columnType` brand rather than `build().columns`:\n * `BuildableTable.build()` is typed to return `Record<string, ColumnSchema>`,\n * which erases the literal keys and would mark EVERY model field as encrypted.\n *\n * The fallbacks resolve to `Record<never, never>` (a no-key type), NOT `never`:\n * a value typed as the bare structural `BuildableTable` carries no `_columnType`\n * brand, and `keyof never` is `string | number | symbol` — which would wrongly\n * mark EVERY model field as encrypted. `keyof Record<never, never>` is `never`,\n * so `EncryptedFromBuildableTable` degrades gracefully to the model unchanged.\n */\nexport type BuildableTableColumns<T extends BuildableTable> = T extends {\n  readonly _columnType: infer C\n}\n  ? C extends Record<string, unknown>\n    ? C\n    : Record<never, never>\n  : Record<never, never>\n\n/**\n * Maps a plaintext model type to its encrypted form using a buildable table.\n *\n * Fields whose keys match a column defined in `Table` (via its `_columnType`\n * brand) become `Encrypted` (`Encrypted | null` when the source field is\n * nullable); all other fields retain their original types from `T`. Works for\n * both v2 and v3 tables. See {@link EncryptedFromSchema} for the v2-specific\n * variant retained for backward compatibility.\n */\nexport type EncryptedFromBuildableTable<T, Table extends BuildableTable> = {\n  [K in keyof T]: [K] extends [keyof BuildableTableColumns<Table>]\n    ? null extends T[K]\n      ? Encrypted | null\n      : Encrypted\n    : T[K]\n}\n\n// ---------------------------------------------------------------------------\n// Encrypt / decrypt operation options and results\n// ---------------------------------------------------------------------------\n\n/**\n * Options for single-value encrypt operations.\n * Use a column from your table schema (from {@link encryptedColumn}) or a nested\n * field (from {@link encryptedField}) as the target for encryption.\n */\nexport type EncryptOptions = {\n  /** The column or nested field to encrypt into. From {@link EncryptedColumn} or {@link EncryptedField}. */\n  column: BuildableColumn // storage: fields are encryptable, so stays wide\n  table: BuildableTable\n}\n\n/** Format for encrypted query/search term return values */\nexport type EncryptedReturnType =\n  | 'eql'\n  | 'composite-literal'\n  | 'escaped-composite-literal'\n\nexport type SearchTerm = {\n  value: Plaintext\n  column: BuildableQueryColumn // query: excludes non-queryable EncryptedField\n  table: BuildableTable\n  returnType?: EncryptedReturnType\n}\n\n/** Encrypted search term result. `eql` return type yields either a storage\n * payload (`Encrypted`, for `ste_vec_term`) or a query-only term\n * (`EncryptedQuery`, for scalar lookups and `ste_vec_selector`); the\n * `composite-literal` return types yield a string. */\nexport type EncryptedSearchTerm = Encrypted | EncryptedQuery | string\n\n/** Result of encryptQuery (single or batch). `eql` return type yields either a\n * storage payload (`Encrypted`) or a query-only term (`EncryptedQuery`); the\n * `composite-literal` return types yield a string. */\n// null elements appear in the batch path when a term has a null/undefined\n// value — the operation preserves position so callers can correlate results\n// with their input array.\nexport type EncryptedQueryResult = Encrypted | EncryptedQuery | string | null\n\n// ---------------------------------------------------------------------------\n// Model field types (encrypted vs decrypted views)\n// ---------------------------------------------------------------------------\n\nexport type EncryptedFields<T> = {\n  [K in keyof T as NonNullable<T[K]> extends Encrypted ? K : never]: T[K]\n}\n\nexport type OtherFields<T> = {\n  [K in keyof T as NonNullable<T[K]> extends Encrypted ? never : K]: T[K]\n}\n\nexport type DecryptedFields<T> = {\n  [K in keyof T as NonNullable<T[K]> extends Encrypted\n    ? K\n    : never]: null extends T[K] ? string | null : string\n}\n\n/** Model with encrypted fields replaced by plaintext (decrypted) values */\nexport type Decrypted<T> = OtherFields<T> & DecryptedFields<T>\n\n/**\n * Maps a plaintext model type to its encrypted form using the table schema.\n *\n * Fields whose keys match columns defined in `S` become `Encrypted`;\n * all other fields retain their original types from `T`.\n *\n * When `S` is the widened `EncryptedTableColumn` (e.g. when a user passes an\n * explicit `<User>` type argument without specifying `S`), the type degrades\n * gracefully to `T` — preserving backward compatibility.\n *\n * @typeParam T - The plaintext model type (e.g. `{ id: string; email: string }`)\n * @typeParam S - The table schema column definition, inferred from the `table` argument\n *\n * @example\n * ```typescript\n * type User = { id: string; email: string }\n * // With a schema that defines `email`:\n * type Encrypted = EncryptedFromSchema<User, { email: EncryptedColumn }>\n * // => { id: string; email: Encrypted }\n * ```\n */\nexport type EncryptedFromSchema<T, S extends EncryptedTableColumn> = {\n  [K in keyof T]: [K] extends [keyof S]\n    ? [S[K & keyof S]] extends [EncryptedColumn | EncryptedField]\n      ? null extends T[K]\n        ? Encrypted | null\n        : Encrypted\n      : T[K]\n    : T[K]\n}\n\n// ---------------------------------------------------------------------------\n// Bulk operations\n// ---------------------------------------------------------------------------\n\n// Bulk payloads admit null elements — bulk operations pass them through\n// untouched (encrypt(null) -> null, decrypt(null) -> null) so callers can\n// process mixed nullable arrays without filtering ahead of time. The\n// runtime guards in the operation classes preserve the null in the\n// position-stable output.\nexport type BulkEncryptPayload = Array<{\n  id?: string\n  plaintext: Plaintext | null\n}>\n\nexport type BulkEncryptedData = Array<{ id?: string; data: Encrypted | null }>\nexport type BulkDecryptPayload = Array<{ id?: string; data: Encrypted | null }>\nexport type BulkDecryptedData = Array<DecryptionResult<JsPlaintext | null>>\n\ntype DecryptionSuccess<T> = { error?: never; data: T; id?: string }\ntype DecryptionError<T> = { error: T; id?: string; data?: never }\n\n/**\n * Result type for individual items in bulk decrypt operations.\n * Uses `error`/`data` fields (not `failure`/`data`) since bulk operations\n * can have per-item failures.\n */\nexport type DecryptionResult<T> = DecryptionSuccess<T> | DecryptionError<T>\n\n// ---------------------------------------------------------------------------\n// Query types (for searchable encryption / encryptQuery)\n// ---------------------------------------------------------------------------\n\n/**\n * User-facing query type names for encrypting query values.\n *\n * - `'equality'`: Exact match. [Exact Queries](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption)\n * - `'freeTextSearch'`: Text search. [Match Queries](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption)\n * - `'orderAndRange'`: Comparison and range. [Range Queries](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption)\n * - `'steVecSelector'`: JSONPath selector (e.g. `'$.user.email'`)\n * - `'steVecTerm'`: Containment (e.g. `{ role: 'admin' }`)\n * - `'searchableJson'`: Auto-infers selector or term from plaintext type (recommended)\n */\nexport type QueryTypeName =\n  | 'orderAndRange'\n  | 'freeTextSearch'\n  | 'equality'\n  | 'steVecSelector'\n  | 'steVecTerm'\n  | 'searchableJson'\n\n/** @internal */\nexport type FfiIndexTypeName = 'ore' | 'match' | 'unique' | 'ste_vec'\n\nexport const queryTypes = {\n  orderAndRange: 'orderAndRange',\n  freeTextSearch: 'freeTextSearch',\n  equality: 'equality',\n  steVecSelector: 'steVecSelector',\n  steVecTerm: 'steVecTerm',\n  searchableJson: 'searchableJson',\n} as const satisfies Record<string, QueryTypeName>\n\n/** @internal */\nexport const queryTypeToFfi: Record<QueryTypeName, FfiIndexTypeName> = {\n  orderAndRange: 'ore',\n  freeTextSearch: 'match',\n  equality: 'unique',\n  steVecSelector: 'ste_vec',\n  steVecTerm: 'ste_vec',\n  searchableJson: 'ste_vec',\n}\n\n/** @internal */\nexport const queryTypeToQueryOp: Partial<Record<QueryTypeName, QueryOpName>> = {\n  steVecSelector: 'ste_vec_selector',\n  steVecTerm: 'ste_vec_term',\n}\n\n/** @internal */\nexport type QueryTermBase = {\n  column: BuildableQueryColumn // query: excludes non-queryable EncryptedField\n  table: BuildableTable\n  queryType?: QueryTypeName\n  returnType?: EncryptedReturnType\n}\n\nexport type EncryptQueryOptions = QueryTermBase\n\nexport type ScalarQueryTerm = QueryTermBase & {\n  value: Plaintext\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACsbO,IAAM,aAAa;AAAA,EACxB,eAAe;AAAA,EACf,gBAAgB;AAAA,EAChB,UAAU;AAAA,EACV,gBAAgB;AAAA,EAChB,YAAY;AAAA,EACZ,gBAAgB;AAClB;","names":[]}
+{"version":3,"sources":["../src/types-public.ts","../src/types.ts"],"sourcesContent":["/**\n * Public type re-exports for `@cipherstash/stack/types`.\n *\n * This module exposes only the public types from the internal types module.\n * Internal helpers (`queryTypeToFfi`, `queryTypeToQueryOp`, `FfiIndexTypeName`,\n * `QueryTermBase`) are excluded.\n */\n\n// Core types\n// Client configuration\n// Encrypt / decrypt operation options and results\n// Model field types\n// Bulk operations\n// Query types (public only)\nexport type {\n  AuthStrategy,\n  BuildableColumn,\n  BuildableQueryColumn,\n  BuildableTable,\n  BuildableTableColumns,\n  BuildableV3QueryableColumn,\n  BulkDecryptedData,\n  BulkDecryptPayload,\n  BulkEncryptedData,\n  BulkEncryptPayload,\n  Client,\n  ClientConfig,\n  Decrypted,\n  DecryptedFields,\n  DecryptionResult,\n  Encrypted,\n  EncryptedFields,\n  EncryptedFromBuildableTable,\n  EncryptedFromSchema,\n  EncryptedQuery,\n  EncryptedQueryResult,\n  EncryptedReturnType,\n  EncryptedSearchTerm,\n  EncryptedValue,\n  EncryptionClientConfig,\n  EncryptOptions,\n  EncryptQueryOptions,\n  KeysetIdentifier,\n  OtherFields,\n  QueryTypeName,\n  ScalarQueryTerm,\n  SearchTerm,\n} from '@/types'\n\n// Runtime values\nexport { queryTypes } from '@/types'\n","import type {\n  AuthStrategy,\n  Encrypted as CipherStashEncrypted,\n  EncryptedPayload as CipherStashEncryptedPayload,\n  EncryptedQuery as CipherStashEncryptedQuery,\n  EncryptedV3Query as CipherStashEncryptedV3Query,\n  JsPlaintext,\n  newClient,\n  QueryOpName,\n} from '@cipherstash/protect-ffi'\nimport type {\n  ColumnSchema,\n  EncryptedColumn,\n  EncryptedField,\n  EncryptedTableColumn,\n  // Imported type-only for the TSDoc {@link} references in the comments below.\n  encryptedColumn,\n  encryptedField,\n} from '@/schema'\n\n/**\n * A pluggable authentication strategy for ZeroKMS requests. Any object\n * with a `getToken(): Promise<{ token: string }>` method satisfies it —\n * notably the strategies from `@cipherstash/auth`: `OidcFederationStrategy`\n * (per-user, identity-bound encryption) and `AccessKeyStrategy`\n * (service-to-service / CI). When supplied to {@link ClientConfig.authStrategy},\n * `getToken()` is invoked on every ZeroKMS request, taking precedence over\n * the default `auto` strategy.\n *\n * @see ClientConfig.authStrategy\n */\nexport type { AuthStrategy }\n\n// ---------------------------------------------------------------------------\n// Branded type utilities\n// ---------------------------------------------------------------------------\n\n/** Brand symbol for nominal typing */\ndeclare const __brand: unique symbol\n\n/** Creates a branded type that is structurally incompatible with the base type */\ntype Brand<T, B extends string> = T & { readonly [__brand]: B }\n\n// ---------------------------------------------------------------------------\n// Core types\n// ---------------------------------------------------------------------------\n\nexport type Client = Awaited<ReturnType<typeof newClient>> | undefined\n\n/** A branded type representing encrypted data. Cannot be accidentally used as plaintext. */\nexport type EncryptedValue = Brand<CipherStashEncrypted, 'encrypted'>\n\n/** Structural type representing encrypted data stored in the database. Always\n * carries a ciphertext. Covers BOTH wire formats: the EQL v2.3 payloads\n * (`k: \"ct\"` / `k: \"sv\"`) and the EQL v3 payloads (flat `{v: 3, i, c, …}`\n * scalars and `{v: 3, k: \"sv\", i, sv}` SteVec documents). Which format\n * `encrypt` produces is selected by the client's\n * {@link ClientConfig.eqlVersion}; `decrypt` accepts both regardless.\n * v3 scalars carry no `k` discriminator, so narrow with `'k' in payload`\n * before reading it. See also `EncryptedValue` for branded nominal typing,\n * and {@link EncryptedQuery} for the search-term shape returned by\n * `encryptQuery`. */\nexport type Encrypted = CipherStashEncryptedPayload\n\n/** Structural type representing an encrypted query term (search needle)\n * returned by `encryptQuery` / `encryptQueryBulk` for scalar\n * (`unique` / `match` / `ore`) lookups and `ste_vec_selector` JSON path\n * queries, plus — under `eqlVersion: 3` — the `eql_v3.jsonb_query`\n * containment needle. Carries no ciphertext — matched against stored\n * values, never decrypted. v2 JSON containment queries (`ste_vec_term`)\n * return a storage-shaped {@link Encrypted} payload instead. */\nexport type EncryptedQuery =\n  | CipherStashEncryptedQuery\n  | CipherStashEncryptedV3Query\n\n/**\n * Plaintext values the SDK accepts for encryption.\n *\n * Widens the FFI's `JsPlaintext` (`string | number | boolean |\n * Record<string, unknown> | JsPlaintext[]`) with `Date` and `bigint`. `Date`\n * is a supported cast target that is omitted from the FFI's `JsPlaintext` INPUT\n * union, but it serializes at the boundary via `toJSON` (ISO string), so it is\n * accepted on the way in.\n *\n * `bigint` is the plaintext for the v3 int8/bigint domains (see `eql/v3`),\n * which always decrypt to a JS `bigint`. protect-ffi 0.28 marshals a native\n * `bigint` across the Neon boundary losslessly. i64 bounds\n * (`-2^63 … 2^63 - 1`) are enforced at the protect-ffi boundary, not here —\n * out-of-range values surface as encryption errors from the FFI.\n *\n * When the upstream FFI `JsPlaintext` includes `Date` and `bigint`, both extra\n * arms can collapse back into `JsPlaintext`.\n */\nexport type Plaintext = JsPlaintext | Date | bigint\n\n// ---------------------------------------------------------------------------\n// Client configuration\n// ---------------------------------------------------------------------------\n\nexport type KeysetIdentifier = { name: string } | { id: string }\n\nexport type ClientConfig = {\n  /**\n   * The CipherStash workspace CRN (Cloud Resource Name).\n   * Format: `crn:<region>.aws:<workspace-id>`.\n   * Can also be set via the `CS_WORKSPACE_CRN` environment variable.\n   */\n  workspaceCrn?: string\n\n  /**\n   * The API access key used for authenticating with the CipherStash API.\n   * Can also be set via the `CS_CLIENT_ACCESS_KEY` environment variable.\n   * Obtain this from the CipherStash dashboard after creating a workspace.\n   */\n  accessKey?: string\n\n  /**\n   * The client identifier used to authenticate with CipherStash services.\n   * Can also be set via the `CS_CLIENT_ID` environment variable.\n   * Generated during workspace onboarding in the CipherStash dashboard.\n   */\n  clientId?: string\n\n  /**\n   * The client key material used in combination with ZeroKMS for encryption operations.\n   * Can also be set via the `CS_CLIENT_KEY` environment variable.\n   * Generated during workspace onboarding in the CipherStash dashboard.\n   */\n  clientKey?: string\n\n  /**\n   * An optional keyset identifier for multi-tenant encryption.\n   * Each keyset provides cryptographic isolation, giving each tenant its own keyspace.\n   * Specify by name (`{ name: \"tenant-a\" }`) or UUID (`{ id: \"...\" }`).\n   * Keysets are created and managed in the\n   * [dashboard](https://dashboard.cipherstash.com/workspaces/_/keysets); omit to\n   * use the workspace's default keyset. A client is bound to one keyset for its\n   * lifetime, so use one client per tenant.\n   *\n   * @see {@link Encryption} for the full keysets walkthrough.\n   */\n  keyset?: KeysetIdentifier\n\n  /**\n   * An optional authentication strategy for ZeroKMS requests, from\n   * `@cipherstash/auth` (re-exported by `@cipherstash/stack`). When provided,\n   * its `getToken()` is invoked on every ZeroKMS request and takes precedence\n   * over the default `auto` strategy (the `clientKey` is still required for\n   * encryption). Use:\n   *\n   * - `OidcFederationStrategy` for per-user, identity-bound encryption —\n   *   federates an end user's OIDC JWT into a CTS service token, so requests\n   *   authenticate as that user. Pair with `.withLockContext({ identityClaim })`\n   *   to bind the data key to a claim. This replaces the older\n   *   `LockContext.identify()` ceremony.\n   * - `AccessKeyStrategy` for service-to-service / CI, or any custom\n   *   `{ getToken() }` object for bespoke token acquisition / caching.\n   *\n   * Leave unset to use the default `auto` strategy, which reads credentials\n   * from the `CS_*` environment variables and falls back to the local dev\n   * profile created by `npx stash auth login`.\n   *\n   * @see {@link AuthStrategy}\n   * @see {@link Encryption} for a full walkthrough of the authentication options.\n   */\n  authStrategy?: AuthStrategy\n\n  /**\n   * @deprecated Renamed to {@link ClientConfig.authStrategy}. Still honoured for\n   * backwards compatibility — passing it logs a deprecation warning at runtime —\n   * but it will be removed in a future release. Set `authStrategy` instead.\n   */\n  strategy?: AuthStrategy\n\n  /**\n   * The EQL wire version the client emits — one FFI client always emits\n   * exactly one wire format.\n   *\n   * - `2` (the protect-ffi default): payloads target the\n   *   `eql_v2_encrypted` column type.\n   * - `3`: payloads target the per-capability `eql_v3` domains\n   *   (`eql_v3.text_eq`, `eql_v3.integer_ord_ore`, `eql_v3.json`, …),\n   *   derived from each column's `cast_as` and indexes.\n   *\n   * When omitted, {@link Encryption} auto-detects from the schema set:\n   * EQL v3 tables (from `@cipherstash/stack/v3`, marked by\n   * `buildColumnKeyMap()`) select `3`; v2 tables leave the FFI default\n   * (`2`) untouched. Mixing v2 and v3 tables in one client is an error —\n   * split them across two clients instead.\n   *\n   * `decrypt` accepts BOTH formats regardless of this setting, so v2 and\n   * v3 data can coexist during a migration.\n   *\n   * Under `3`, `encryptQuery` returns EQL v3 query operands (protect-ffi\n   * 0.29+): term-only scalar operands for the `eql_v3.query_<name>` twins,\n   * the `eql_v3.query_jsonb` containment needle, and bare selector-hash\n   * strings for JSON path queries.\n   */\n  eqlVersion?: 2 | 3\n}\n\ntype AtLeastOneCsTable<T> = [T, ...T[]]\n\n/** Structural contract for a column builder the client can consume for STORAGE\n *  (`encrypt`). Satisfied by v2 `EncryptedColumn` / `EncryptedField` AND v3\n *  `EncryptedTextSearchColumn` — fields ARE encryptable, so this stays wide. */\nexport interface BuildableColumn {\n  getName(): string\n  build(): ColumnSchema\n}\n\n/** Structural contract for a column the client can consume for QUERIES\n *  (`encryptQuery` / search terms). Narrower than `BuildableColumn`: it must\n *  EXCLUDE non-queryable `EncryptedField` (a field has no indexes). A v2\n *  `EncryptedColumn` qualifies via the nominal arm; a v3 queryable concrete\n *  type qualifies via the `getEqlType()` structural arm; `EncryptedField` (no\n *  `getEqlType`, not an `EncryptedColumn`) is rejected. */\nexport interface BuildableV3QueryableColumn extends BuildableColumn {\n  getEqlType(): string\n  getQueryCapabilities(): {\n    equality: boolean\n    orderAndRange: boolean\n    freeTextSearch: boolean\n  }\n  isQueryable(): true\n}\n\nexport type BuildableQueryColumn = EncryptedColumn | BuildableV3QueryableColumn\n\n/** Structural contract for a table builder the client can consume. Satisfied by\n *  v2 and v3 `EncryptedTable` alike. */\nexport interface BuildableTable {\n  tableName: string\n  build(): { tableName: string; columns: Record<string, ColumnSchema> }\n  /**\n   * Optional map from a model field's JS property name to its encrypt-config\n   * column name (the DB name). Present when the two can differ — v3 tables key\n   * their config by DB name (`column.getName()`) while models are written with\n   * JS property keys, so the model path must match by property but address the\n   * FFI/config by DB name.\n   *\n   * Absent on v2 tables, whose `build()` already keys columns by the JS property\n   * name; the model path then matches and addresses by that same key.\n   */\n  buildColumnKeyMap?(): Record<string, string>\n}\n\nexport type EncryptionClientConfig = {\n  schemas: AtLeastOneCsTable<BuildableTable>\n  config?: ClientConfig\n}\n\n/**\n * The literal column map of a buildable table, read from its type-level\n * `_columnType` brand. Both v2 and v3 `EncryptedTable` carry this brand, so this\n * recovers the literal column keys structurally.\n *\n * This deliberately uses the `_columnType` brand rather than `build().columns`:\n * `BuildableTable.build()` is typed to return `Record<string, ColumnSchema>`,\n * which erases the literal keys and would mark EVERY model field as encrypted.\n *\n * The fallbacks resolve to `Record<never, never>` (a no-key type), NOT `never`:\n * a value typed as the bare structural `BuildableTable` carries no `_columnType`\n * brand, and `keyof never` is `string | number | symbol` — which would wrongly\n * mark EVERY model field as encrypted. `keyof Record<never, never>` is `never`,\n * so `EncryptedFromBuildableTable` degrades gracefully to the model unchanged.\n */\nexport type BuildableTableColumns<T extends BuildableTable> = T extends {\n  readonly _columnType: infer C\n}\n  ? C extends Record<string, unknown>\n    ? C\n    : Record<never, never>\n  : Record<never, never>\n\n/**\n * Maps a plaintext model type to its encrypted form using a buildable table.\n *\n * Fields whose keys match a column defined in `Table` (via its `_columnType`\n * brand) become `Encrypted` (`Encrypted | null` when the source field is\n * nullable); all other fields retain their original types from `T`. Works for\n * both v2 and v3 tables. See {@link EncryptedFromSchema} for the v2-specific\n * variant retained for backward compatibility.\n */\nexport type EncryptedFromBuildableTable<T, Table extends BuildableTable> = {\n  [K in keyof T]: [K] extends [keyof BuildableTableColumns<Table>]\n    ? null extends T[K]\n      ? Encrypted | null\n      : Encrypted\n    : T[K]\n}\n\n// ---------------------------------------------------------------------------\n// Encrypt / decrypt operation options and results\n// ---------------------------------------------------------------------------\n\n/**\n * Options for single-value encrypt operations.\n * Use a column from your table schema (from {@link encryptedColumn}) or a nested\n * field (from {@link encryptedField}) as the target for encryption.\n */\nexport type EncryptOptions = {\n  /** The column or nested field to encrypt into. From {@link EncryptedColumn} or {@link EncryptedField}. */\n  column: BuildableColumn // storage: fields are encryptable, so stays wide\n  table: BuildableTable\n}\n\n/** Format for encrypted query/search term return values */\nexport type EncryptedReturnType =\n  | 'eql'\n  | 'composite-literal'\n  | 'escaped-composite-literal'\n\nexport type SearchTerm = {\n  value: Plaintext\n  column: BuildableQueryColumn // query: excludes non-queryable EncryptedField\n  table: BuildableTable\n  returnType?: EncryptedReturnType\n}\n\n/** Encrypted search term result. `eql` return type yields either a storage\n * payload (`Encrypted`, for `ste_vec_term`) or a query-only term\n * (`EncryptedQuery`, for scalar lookups and `ste_vec_selector`); the\n * `composite-literal` return types yield a string. */\nexport type EncryptedSearchTerm = Encrypted | EncryptedQuery | string\n\n/** Result of encryptQuery (single or batch). `eql` return type yields either a\n * storage payload (`Encrypted`) or a query-only term (`EncryptedQuery`); the\n * `composite-literal` return types yield a string. */\n// null elements appear in the batch path when a term has a null/undefined\n// value — the operation preserves position so callers can correlate results\n// with their input array.\nexport type EncryptedQueryResult = Encrypted | EncryptedQuery | string | null\n\n// ---------------------------------------------------------------------------\n// Model field types (encrypted vs decrypted views)\n// ---------------------------------------------------------------------------\n\nexport type EncryptedFields<T> = {\n  [K in keyof T as NonNullable<T[K]> extends Encrypted ? K : never]: T[K]\n}\n\nexport type OtherFields<T> = {\n  [K in keyof T as NonNullable<T[K]> extends Encrypted ? never : K]: T[K]\n}\n\nexport type DecryptedFields<T> = {\n  [K in keyof T as NonNullable<T[K]> extends Encrypted\n    ? K\n    : never]: null extends T[K] ? string | null : string\n}\n\n/** Model with encrypted fields replaced by plaintext (decrypted) values */\nexport type Decrypted<T> = OtherFields<T> & DecryptedFields<T>\n\n/**\n * Maps a plaintext model type to its encrypted form using the table schema.\n *\n * Fields whose keys match columns defined in `S` become `Encrypted`;\n * all other fields retain their original types from `T`.\n *\n * When `S` is the widened `EncryptedTableColumn` (e.g. when a user passes an\n * explicit `<User>` type argument without specifying `S`), the type degrades\n * gracefully to `T` — preserving backward compatibility.\n *\n * @typeParam T - The plaintext model type (e.g. `{ id: string; email: string }`)\n * @typeParam S - The table schema column definition, inferred from the `table` argument\n *\n * @example\n * ```typescript\n * type User = { id: string; email: string }\n * // With a schema that defines `email`:\n * type Encrypted = EncryptedFromSchema<User, { email: EncryptedColumn }>\n * // => { id: string; email: Encrypted }\n * ```\n */\nexport type EncryptedFromSchema<T, S extends EncryptedTableColumn> = {\n  [K in keyof T]: [K] extends [keyof S]\n    ? [S[K & keyof S]] extends [EncryptedColumn | EncryptedField]\n      ? null extends T[K]\n        ? Encrypted | null\n        : Encrypted\n      : T[K]\n    : T[K]\n}\n\n// ---------------------------------------------------------------------------\n// Bulk operations\n// ---------------------------------------------------------------------------\n\n// Bulk payloads admit null elements — bulk operations pass them through\n// untouched (encrypt(null) -> null, decrypt(null) -> null) so callers can\n// process mixed nullable arrays without filtering ahead of time. The\n// runtime guards in the operation classes preserve the null in the\n// position-stable output.\nexport type BulkEncryptPayload = Array<{\n  id?: string\n  plaintext: Plaintext | null\n}>\n\nexport type BulkEncryptedData = Array<{ id?: string; data: Encrypted | null }>\nexport type BulkDecryptPayload = Array<{ id?: string; data: Encrypted | null }>\nexport type BulkDecryptedData = Array<DecryptionResult<JsPlaintext | null>>\n\ntype DecryptionSuccess<T> = { error?: never; data: T; id?: string }\ntype DecryptionError<T> = { error: T; id?: string; data?: never }\n\n/**\n * Result type for individual items in bulk decrypt operations.\n * Uses `error`/`data` fields (not `failure`/`data`) since bulk operations\n * can have per-item failures.\n */\nexport type DecryptionResult<T> = DecryptionSuccess<T> | DecryptionError<T>\n\n// ---------------------------------------------------------------------------\n// Query types (for searchable encryption / encryptQuery)\n// ---------------------------------------------------------------------------\n\n/**\n * User-facing query type names for encrypting query values.\n *\n * - `'equality'`: Exact match. [Exact Queries](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption)\n * - `'freeTextSearch'`: Text search. [Match Queries](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption)\n * - `'orderAndRange'`: Comparison and range. [Range Queries](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption)\n * - `'steVecSelector'`: JSONPath selector (e.g. `'$.user.email'`)\n * - `'steVecTerm'`: Containment (e.g. `{ role: 'admin' }`)\n * - `'searchableJson'`: Auto-infers selector or term from plaintext type (recommended)\n */\nexport type QueryTypeName =\n  | 'orderAndRange'\n  | 'freeTextSearch'\n  | 'equality'\n  | 'steVecSelector'\n  | 'steVecTerm'\n  | 'searchableJson'\n\n/** @internal */\nexport type FfiIndexTypeName = 'ore' | 'ope' | 'match' | 'unique' | 'ste_vec'\n\nexport const queryTypes = {\n  orderAndRange: 'orderAndRange',\n  freeTextSearch: 'freeTextSearch',\n  equality: 'equality',\n  steVecSelector: 'steVecSelector',\n  steVecTerm: 'steVecTerm',\n  searchableJson: 'searchableJson',\n} as const satisfies Record<string, QueryTypeName>\n\n/** @internal */\nexport const queryTypeToFfi: Record<QueryTypeName, FfiIndexTypeName> = {\n  // v3 `_ord` domains carry `ope` instead — `resolveIndexType` swaps this\n  // static default for the ordering index the column actually configures.\n  orderAndRange: 'ore',\n  freeTextSearch: 'match',\n  equality: 'unique',\n  steVecSelector: 'ste_vec',\n  steVecTerm: 'ste_vec',\n  searchableJson: 'ste_vec',\n}\n\n/** @internal */\nexport const queryTypeToQueryOp: Partial<Record<QueryTypeName, QueryOpName>> = {\n  steVecSelector: 'ste_vec_selector',\n  steVecTerm: 'ste_vec_term',\n}\n\n/** @internal */\nexport type QueryTermBase = {\n  column: BuildableQueryColumn // query: excludes non-queryable EncryptedField\n  table: BuildableTable\n  queryType?: QueryTypeName\n  returnType?: EncryptedReturnType\n}\n\nexport type EncryptQueryOptions = QueryTermBase\n\nexport type ScalarQueryTerm = QueryTermBase & {\n  value: Plaintext\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACubO,IAAM,aAAa;AAAA,EACxB,eAAe;AAAA,EACf,gBAAgB;AAAA,EAChB,UAAU;AAAA,EACV,gBAAgB;AAAA,EAChB,YAAY;AAAA,EACZ,gBAAgB;AAClB;","names":[]}

package/dist/types-public.d.cts

@@ -1,3 +1,3 @@
-export { r as BuildableColumn, u as BuildableQueryColumn, s as BuildableTable, N as BuildableTableColumns, R as BuildableV3QueryableColumn, c as BulkDecryptPayload, p as BulkDecryptedData, B as BulkEncryptPayload, q as BulkEncryptedData, o as Client, C as ClientConfig, D as Decrypted, V as DecryptedFields, W as DecryptionResult, b as EncryptOptions, t as EncryptQueryOptions, a as Encrypted, X as EncryptedFields, v as EncryptedFromBuildableTable, Y as EncryptedFromSchema, Z as EncryptedQuery, n as EncryptedQueryResult, E as EncryptedReturnType, _ as EncryptedSearchTerm, m as EncryptedValue, w as EncryptionClientConfig, K as KeysetIdentifier, $ as OtherFields, Q as QueryTypeName, S as ScalarQueryTerm, a0 as SearchTerm, a1 as queryTypes } from './types-public-CpS5KjwX.cjs';
+export { B as BuildableColumn, a as BuildableQueryColumn, b as BuildableTable, c as BuildableTableColumns, d as BuildableV3QueryableColumn, e as BulkDecryptPayload, f as BulkDecryptedData, g as BulkEncryptPayload, h as BulkEncryptedData, i as Client, j as ClientConfig, D as Decrypted, l as DecryptedFields, m as DecryptionResult, n as EncryptOptions, o as EncryptQueryOptions, p as Encrypted, s as EncryptedFields, t as EncryptedFromBuildableTable, u as EncryptedFromSchema, v as EncryptedQuery, w as EncryptedQueryResult, x as EncryptedReturnType, y as EncryptedSearchTerm, F as EncryptedValue, G as EncryptionClientConfig, K as KeysetIdentifier, N as OtherFields, Q as QueryTypeName, S as ScalarQueryTerm, R as SearchTerm, a1 as queryTypes } from './types-public-QMjYNfQO.cjs';
 export { AuthStrategy } from '@cipherstash/protect-ffi';
 import 'zod';

package/dist/types-public.d.ts

@@ -1,3 +1,3 @@
-export { r as BuildableColumn, u as BuildableQueryColumn, s as BuildableTable, N as BuildableTableColumns, R as BuildableV3QueryableColumn, c as BulkDecryptPayload, p as BulkDecryptedData, B as BulkEncryptPayload, q as BulkEncryptedData, o as Client, C as ClientConfig, D as Decrypted, V as DecryptedFields, W as DecryptionResult, b as EncryptOptions, t as EncryptQueryOptions, a as Encrypted, X as EncryptedFields, v as EncryptedFromBuildableTable, Y as EncryptedFromSchema, Z as EncryptedQuery, n as EncryptedQueryResult, E as EncryptedReturnType, _ as EncryptedSearchTerm, m as EncryptedValue, w as EncryptionClientConfig, K as KeysetIdentifier, $ as OtherFields, Q as QueryTypeName, S as ScalarQueryTerm, a0 as SearchTerm, a1 as queryTypes } from './types-public-CpS5KjwX.js';
+export { B as BuildableColumn, a as BuildableQueryColumn, b as BuildableTable, c as BuildableTableColumns, d as BuildableV3QueryableColumn, e as BulkDecryptPayload, f as BulkDecryptedData, g as BulkEncryptPayload, h as BulkEncryptedData, i as Client, j as ClientConfig, D as Decrypted, l as DecryptedFields, m as DecryptionResult, n as EncryptOptions, o as EncryptQueryOptions, p as Encrypted, s as EncryptedFields, t as EncryptedFromBuildableTable, u as EncryptedFromSchema, v as EncryptedQuery, w as EncryptedQueryResult, x as EncryptedReturnType, y as EncryptedSearchTerm, F as EncryptedValue, G as EncryptionClientConfig, K as KeysetIdentifier, N as OtherFields, Q as QueryTypeName, S as ScalarQueryTerm, R as SearchTerm, a1 as queryTypes } from './types-public-QMjYNfQO.js';
 export { AuthStrategy } from '@cipherstash/protect-ffi';
 import 'zod';

package/dist/types-public.js

@@ -1,6 +1,6 @@
 import {
   queryTypes
-} from "./chunk-4AVL4VZD.js";
+} from "./chunk-3B5ZX3IS.js";
 import "./chunk-PZ5AY32C.js";
 export {
   queryTypes