@cipherstash/stack 0.16.0 → 0.19.0

package/dist/chunk-U66S7VIF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/eql/v3/columns.ts"],"sourcesContent":["import type { ColumnSchema, MatchIndexOpts } from '@/schema'\nimport {\n  type BuiltMatchIndexOpts,\n  cloneMatchOpts,\n  defaultMatchOpts,\n} from '@/schema/match-defaults'\n\n/**\n * The query capabilities a v3 concrete domain exposes. These are SDK-facing\n * semantic flags describing what kinds of query terms a column can produce —\n * NOT the raw EQL index keys. They are metadata only and never emitted by\n * `build()`.\n *\n * - `equality`: exact-match lookups (EQL `hm`, or comparison via `ob`).\n * - `orderAndRange`: comparison / range lookups (EQL `ob`).\n * - `freeTextSearch`: tokenised substring match (EQL `bf`).\n */\nexport type QueryCapabilities = Readonly<{\n  equality: boolean\n  orderAndRange: boolean\n  freeTextSearch: boolean\n}>\n\n/** The plaintext (TypeScript) kind a v3 domain decrypts to. A subset of the\n * SDK `CastAs` enum, restricted to the scalar kinds v3 domains actually use. */\ntype PlaintextKind = 'string' | 'number' | 'boolean' | 'date' | 'timestamp'\n\n/**\n * The full, literal definition of a v3 domain. This is the LOAD-BEARING type:\n * the base column class carries a private field of this type so that every\n * concrete (otherwise-empty) subclass is discriminated by its literal\n * `eqlType`/`castAs`/`capabilities` — TypeScript empty subclasses are NOT\n * nominal, so without this a storage-only `boolean` column would be assignable to\n * a storage-only `date` column and plaintext inference would collapse.\n */\ntype V3DomainDefinition = Readonly<{\n  eqlType: `eql_v3.${string}`\n  castAs: PlaintextKind\n  capabilities: QueryCapabilities\n}>\n\n/** Type-level mirror of {@link isQueryableCapabilities}: `false` for a\n * storage-only domain (all capability flags `false`), `true` otherwise. */\ntype QueryableFlag<D extends V3DomainDefinition> = D['capabilities'] extends {\n  equality: false\n  orderAndRange: false\n  freeTextSearch: false\n}\n  ? false\n  : true\n\nconst STORAGE_ONLY = {\n  equality: false,\n  orderAndRange: false,\n  freeTextSearch: false,\n} as const\n\nconst EQUALITY_ONLY = {\n  equality: true,\n  orderAndRange: false,\n  freeTextSearch: false,\n} as const\n\nconst ORDER_AND_RANGE = {\n  equality: true,\n  orderAndRange: true,\n  freeTextSearch: false,\n} as const\n\nconst MATCH_ONLY = {\n  equality: false,\n  orderAndRange: false,\n  freeTextSearch: true,\n} as const\n\nconst TEXT_SEARCH = {\n  equality: true,\n  orderAndRange: true,\n  freeTextSearch: true,\n} as const\n\n/**\n * The concrete EQL v3 domain name for a full-capability text column.\n * Recorded as metadata for future DDL / query-dialect increments; it is\n * intentionally absent from the emitted encrypt config.\n */\nexport const TEXT_SEARCH_EQL_TYPE = 'eql_v3.text_search'\n\n// Per-domain literal definitions. Each concrete column subclass is parameterised\n// by `typeof <CONST>`; the literal `eqlType`/`castAs`/`capabilities` on each is\n// what makes the otherwise-empty subclasses nominally distinct (see\n// V3DomainDefinition). Order mirrors eql-bindings `CATALOG` order.\n//\n// Exported for the `types` namespace factory (see ./types); they are internal\n// building blocks and are intentionally NOT re-exported from the public barrel.\nexport const INTEGER = {\n  eqlType: 'eql_v3.integer',\n  castAs: 'number',\n  capabilities: STORAGE_ONLY,\n} as const\nexport const INTEGER_EQ = {\n  eqlType: 'eql_v3.integer_eq',\n  castAs: 'number',\n  capabilities: EQUALITY_ONLY,\n} as const\nexport const INTEGER_ORD_ORE = {\n  eqlType: 'eql_v3.integer_ord_ore',\n  castAs: 'number',\n  capabilities: ORDER_AND_RANGE,\n} as const\nexport const INTEGER_ORD = {\n  eqlType: 'eql_v3.integer_ord',\n  castAs: 'number',\n  capabilities: ORDER_AND_RANGE,\n} as const\n\nexport const SMALLINT = {\n  eqlType: 'eql_v3.smallint',\n  castAs: 'number',\n  capabilities: STORAGE_ONLY,\n} as const\nexport const SMALLINT_EQ = {\n  eqlType: 'eql_v3.smallint_eq',\n  castAs: 'number',\n  capabilities: EQUALITY_ONLY,\n} as const\nexport const SMALLINT_ORD_ORE = {\n  eqlType: 'eql_v3.smallint_ord_ore',\n  castAs: 'number',\n  capabilities: ORDER_AND_RANGE,\n} as const\nexport const SMALLINT_ORD = {\n  eqlType: 'eql_v3.smallint_ord',\n  castAs: 'number',\n  capabilities: ORDER_AND_RANGE,\n} as const\n\n// NOTE: bigint (int8) domains are intentionally NOT defined yet. The native\n// protect-ffi build cannot round-trip a 64-bit int losslessly: a JS `bigint`\n// fails JSON serialization, and a `string` is rejected for a `big_int` column\n// (\"Cannot convert String to BigInt\"), while `number` loses precision above\n// 2^53. Re-add BIGINT/BIGINT_EQ/BIGINT_ORD_ORE/BIGINT_ORD and their builders once the\n// FFI accepts a lossless bigint on input and returns it on decrypt.\n\nexport const DATE = {\n  eqlType: 'eql_v3.date',\n  castAs: 'date',\n  capabilities: STORAGE_ONLY,\n} as const\nexport const DATE_EQ = {\n  eqlType: 'eql_v3.date_eq',\n  castAs: 'date',\n  capabilities: EQUALITY_ONLY,\n} as const\nexport const DATE_ORD_ORE = {\n  eqlType: 'eql_v3.date_ord_ore',\n  castAs: 'date',\n  capabilities: ORDER_AND_RANGE,\n} as const\nexport const DATE_ORD = {\n  eqlType: 'eql_v3.date_ord',\n  castAs: 'date',\n  capabilities: ORDER_AND_RANGE,\n} as const\n\n// Timestamp domains cast as 'timestamp' (not 'date') so decrypt preserves the\n// time-of-day component — the FFI's 'date' variant truncates to midnight.\n// Both kinds decrypt to a JS `Date`.\nexport const TIMESTAMP = {\n  eqlType: 'eql_v3.timestamp',\n  castAs: 'timestamp',\n  capabilities: STORAGE_ONLY,\n} as const\nexport const TIMESTAMP_EQ = {\n  eqlType: 'eql_v3.timestamp_eq',\n  castAs: 'timestamp',\n  capabilities: EQUALITY_ONLY,\n} as const\nexport const TIMESTAMP_ORD_ORE = {\n  eqlType: 'eql_v3.timestamp_ord_ore',\n  castAs: 'timestamp',\n  capabilities: ORDER_AND_RANGE,\n} as const\nexport const TIMESTAMP_ORD = {\n  eqlType: 'eql_v3.timestamp_ord',\n  castAs: 'timestamp',\n  capabilities: ORDER_AND_RANGE,\n} as const\n\nexport const NUMERIC = {\n  eqlType: 'eql_v3.numeric',\n  castAs: 'number',\n  capabilities: STORAGE_ONLY,\n} as const\nexport const NUMERIC_EQ = {\n  eqlType: 'eql_v3.numeric_eq',\n  castAs: 'number',\n  capabilities: EQUALITY_ONLY,\n} as const\nexport const NUMERIC_ORD_ORE = {\n  eqlType: 'eql_v3.numeric_ord_ore',\n  castAs: 'number',\n  capabilities: ORDER_AND_RANGE,\n} as const\nexport const NUMERIC_ORD = {\n  eqlType: 'eql_v3.numeric_ord',\n  castAs: 'number',\n  capabilities: ORDER_AND_RANGE,\n} as const\n\nexport const TEXT = {\n  eqlType: 'eql_v3.text',\n  castAs: 'string',\n  capabilities: STORAGE_ONLY,\n} as const\nexport const TEXT_EQ = {\n  eqlType: 'eql_v3.text_eq',\n  castAs: 'string',\n  capabilities: EQUALITY_ONLY,\n} as const\nexport const TEXT_MATCH = {\n  eqlType: 'eql_v3.text_match',\n  castAs: 'string',\n  capabilities: MATCH_ONLY,\n} as const\nexport const TEXT_ORD_ORE = {\n  eqlType: 'eql_v3.text_ord_ore',\n  castAs: 'string',\n  capabilities: ORDER_AND_RANGE,\n} as const\nexport const TEXT_ORD = {\n  eqlType: 'eql_v3.text_ord',\n  castAs: 'string',\n  capabilities: ORDER_AND_RANGE,\n} as const\n\nexport const BOOLEAN = {\n  eqlType: 'eql_v3.boolean',\n  castAs: 'boolean',\n  capabilities: STORAGE_ONLY,\n} as const\n\nexport const REAL = {\n  eqlType: 'eql_v3.real',\n  castAs: 'number',\n  capabilities: STORAGE_ONLY,\n} as const\nexport const REAL_EQ = {\n  eqlType: 'eql_v3.real_eq',\n  castAs: 'number',\n  capabilities: EQUALITY_ONLY,\n} as const\nexport const REAL_ORD_ORE = {\n  eqlType: 'eql_v3.real_ord_ore',\n  castAs: 'number',\n  capabilities: ORDER_AND_RANGE,\n} as const\nexport const REAL_ORD = {\n  eqlType: 'eql_v3.real_ord',\n  castAs: 'number',\n  capabilities: ORDER_AND_RANGE,\n} as const\n\nexport const DOUBLE = {\n  eqlType: 'eql_v3.double',\n  castAs: 'number',\n  capabilities: STORAGE_ONLY,\n} as const\nexport const DOUBLE_EQ = {\n  eqlType: 'eql_v3.double_eq',\n  castAs: 'number',\n  capabilities: EQUALITY_ONLY,\n} as const\nexport const DOUBLE_ORD_ORE = {\n  eqlType: 'eql_v3.double_ord_ore',\n  castAs: 'number',\n  capabilities: ORDER_AND_RANGE,\n} as const\nexport const DOUBLE_ORD = {\n  eqlType: 'eql_v3.double_ord',\n  castAs: 'number',\n  capabilities: ORDER_AND_RANGE,\n} as const\n\n/**\n * Translate a domain's semantic {@link QueryCapabilities} (plus its plaintext\n * `castAs`, which decides how equality is answered) into the concrete EQL index\n * block emitted by `build()`.\n *\n * - `unique` (the `hm` HMAC index) whenever equality is answered via HMAC:\n *   equality-only domains of ANY type, AND text order domains. Text equality is\n *   HMAC-based — the `eql_v3.text_ord` / `eql_v3.text_ord_ore` SQL domains\n *   REQUIRE `hm` in the stored ciphertext (their `eql_v3.eq_term` extracts it).\n * - `ore` for any order/range domain (the `ob` term). For numeric/date order\n *   domains `ob` also answers equality (via the SQL `=` operator), so those emit\n *   `ore` ONLY — no `hm`. Text order domains emit BOTH `unique` and `ore`.\n * - `match` (the `bf` bloom-filter index) for free-text search, deep-cloned from\n *   the per-call defaults so no nested object is ever shared across columns.\n */\nfunction indexesForCapabilities(\n  capabilities: QueryCapabilities,\n  castAs: PlaintextKind,\n): ColumnSchema['indexes'] {\n  const indexes: ColumnSchema['indexes'] = {}\n\n  // Text equality is always HMAC-based, so a text order domain (`string` +\n  // order/range) still needs `unique`; numeric/date order domains answer\n  // equality via `ob` and must NOT emit `unique`.\n  if (\n    capabilities.equality &&\n    (!capabilities.orderAndRange || castAs === 'string')\n  ) {\n    indexes.unique = { token_filters: [] }\n  }\n\n  if (capabilities.orderAndRange) {\n    indexes.ore = {}\n  }\n\n  if (capabilities.freeTextSearch) {\n    // The factory returns fresh, unaliased nested objects per call, so no\n    // column's emitted match block ever shares state with another's.\n    indexes.match = defaultMatchOpts()\n  }\n\n  return indexes\n}\n\n/** Whether a domain's capabilities make it queryable at all (any flag set). */\nfunction isQueryableCapabilities(capabilities: QueryCapabilities): boolean {\n  return (\n    capabilities.equality ||\n    capabilities.orderAndRange ||\n    capabilities.freeTextSearch\n  )\n}\n\n/**\n * Shared base for every v3 concrete domain column. Parameterised by the FULL\n * literal {@link V3DomainDefinition} (not by capabilities alone): the private\n * `definition` field carries the literal `eqlType`/`castAs`/`capabilities`, so\n * two otherwise-empty subclasses (e.g. `EncryptedBooleanColumn` and\n * `EncryptedDateColumn`, both storage-only) are NOT mutually assignable. This\n * nominality is what keeps plaintext inference precise.\n */\nexport class EncryptedV3Column<D extends V3DomainDefinition> {\n  constructor(\n    private readonly columnName: string,\n    private readonly definition: D,\n  ) {}\n\n  getName(): string {\n    return this.columnName\n  }\n\n  /** The concrete EQL v3 domain name. Metadata only; not emitted by `build()`. */\n  getEqlType(): D['eqlType'] {\n    return this.definition.eqlType\n  }\n\n  /** The semantic query capabilities this domain exposes. Metadata only. */\n  getQueryCapabilities(): D['capabilities'] {\n    return this.definition.capabilities\n  }\n\n  /** `true` when this domain can produce at least one kind of query term. */\n  isQueryable(): QueryableFlag<D> {\n    return isQueryableCapabilities(\n      this.definition.capabilities,\n    ) as QueryableFlag<D>\n  }\n\n  /** Emit the encrypt-config column: `cast_as` plus capability-derived indexes. */\n  build(): ColumnSchema {\n    return {\n      cast_as: this.definition.castAs,\n      indexes: indexesForCapabilities(\n        this.definition.capabilities,\n        this.definition.castAs,\n      ),\n    }\n  }\n}\n\nconst TEXT_SEARCH_DOMAIN = {\n  eqlType: TEXT_SEARCH_EQL_TYPE,\n  castAs: 'string',\n  capabilities: TEXT_SEARCH,\n} as const\n\n/**\n * Builder for an `eql_v3.text_search` column.\n *\n * The concrete type inherently enables equality + order/range + free-text\n * match — there are no capability-enabling methods. `.freeTextSearch(opts?)`\n * tunes the match index only.\n *\n * NOTE — querying: a `text_search` column emits all three indexes (`unique`,\n * `ore`, `match`), and the shared index-inference picks them by fixed priority\n * `unique > match > ore`. So `encryptQuery(value, { column, table })` with NO\n * explicit `queryType` builds an EQUALITY term (via `unique`), NOT a free-text\n * match — a substring like `'joh'` then matches nothing. To run a free-text\n * match query you MUST pass `queryType: 'freeTextSearch'`:\n *\n * ```typescript\n * // equality (default): exact value only\n * client.encryptQuery('john@example.com', { column: users.email, table: users })\n * // free-text match: substring/token search\n * client.encryptQuery('joh', { column: users.email, table: users, queryType: 'freeTextSearch' })\n * ```\n */\nexport class EncryptedTextSearchColumn extends EncryptedV3Column<\n  typeof TEXT_SEARCH_DOMAIN\n> {\n  private matchOpts: BuiltMatchIndexOpts\n\n  constructor(columnName: string) {\n    super(columnName, TEXT_SEARCH_DOMAIN)\n    this.matchOpts = defaultMatchOpts()\n  }\n\n  /**\n   * Tune the match index. Each provided key replaces its default; omitted\n   * keys keep the default. This NEVER enables a capability — match is always\n   * on for this type. Merge semantics mirror v2's `opts?.x ?? default`.\n   */\n  freeTextSearch(opts?: MatchIndexOpts): this {\n    // A fresh defaults object per call supplies the `?? ` fallbacks, so no\n    // nested default object is ever shared into `this.matchOpts` by reference.\n    const defaults = defaultMatchOpts()\n    // Clone-on-write: deep-copy the nested tokenizer / token_filters when\n    // storing them so a caller mutating their own opts object between\n    // freeTextSearch(opts) and build() cannot leak into the emitted config.\n    this.matchOpts = cloneMatchOpts({\n      tokenizer: opts?.tokenizer ?? defaults.tokenizer,\n      token_filters: opts?.token_filters ?? defaults.token_filters,\n      k: opts?.k ?? defaults.k,\n      m: opts?.m ?? defaults.m,\n      include_original: opts?.include_original ?? defaults.include_original,\n    })\n    return this\n  }\n\n  /** Emit the encrypt-config column. Byte-identical to a v2 equality+order+match column. */\n  override build(): ColumnSchema {\n    // Deep-clone the match block so the returned config NEVER aliases this\n    // builder's internal `matchOpts` (or any caller-supplied opts merged into\n    // it). A caller mutating the returned object cannot corrupt this builder's\n    // state or another column's defaults.\n    return {\n      cast_as: 'string',\n      indexes: {\n        unique: { token_filters: [] },\n        ore: {},\n        match: cloneMatchOpts(this.matchOpts),\n      },\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Concrete domain columns\n//\n// Every concrete class is an empty subclass parameterised by its literal domain\n// definition (see EncryptedV3Column). The `types` namespace (see ./types)\n// constructs these with the SAME literal constant so the instance's private\n// `definition` field carries full literal type data — that is what keeps\n// distinct domains nominally incompatible.\n// ---------------------------------------------------------------------------\n\n// integer\nexport class EncryptedIntegerColumn extends EncryptedV3Column<typeof INTEGER> {}\nexport class EncryptedIntegerEqColumn extends EncryptedV3Column<\n  typeof INTEGER_EQ\n> {}\nexport class EncryptedIntegerOrdOreColumn extends EncryptedV3Column<\n  typeof INTEGER_ORD_ORE\n> {}\nexport class EncryptedIntegerOrdColumn extends EncryptedV3Column<\n  typeof INTEGER_ORD\n> {}\n\n// smallint\nexport class EncryptedSmallintColumn extends EncryptedV3Column<\n  typeof SMALLINT\n> {}\nexport class EncryptedSmallintEqColumn extends EncryptedV3Column<\n  typeof SMALLINT_EQ\n> {}\nexport class EncryptedSmallintOrdOreColumn extends EncryptedV3Column<\n  typeof SMALLINT_ORD_ORE\n> {}\nexport class EncryptedSmallintOrdColumn extends EncryptedV3Column<\n  typeof SMALLINT_ORD\n> {}\n\n// bigint (int8) domain builders are intentionally omitted pending FFI support\n// for lossless bigint round-tripping — see the note by the INTEGER/DATE domain\n// definitions above.\n\n// date\nexport class EncryptedDateColumn extends EncryptedV3Column<typeof DATE> {}\nexport class EncryptedDateEqColumn extends EncryptedV3Column<typeof DATE_EQ> {}\nexport class EncryptedDateOrdOreColumn extends EncryptedV3Column<\n  typeof DATE_ORD_ORE\n> {}\nexport class EncryptedDateOrdColumn extends EncryptedV3Column<\n  typeof DATE_ORD\n> {}\n\n// timestamp\nexport class EncryptedTimestampColumn extends EncryptedV3Column<\n  typeof TIMESTAMP\n> {}\nexport class EncryptedTimestampEqColumn extends EncryptedV3Column<\n  typeof TIMESTAMP_EQ\n> {}\nexport class EncryptedTimestampOrdOreColumn extends EncryptedV3Column<\n  typeof TIMESTAMP_ORD_ORE\n> {}\nexport class EncryptedTimestampOrdColumn extends EncryptedV3Column<\n  typeof TIMESTAMP_ORD\n> {}\n\n// numeric\nexport class EncryptedNumericColumn extends EncryptedV3Column<typeof NUMERIC> {}\nexport class EncryptedNumericEqColumn extends EncryptedV3Column<\n  typeof NUMERIC_EQ\n> {}\nexport class EncryptedNumericOrdOreColumn extends EncryptedV3Column<\n  typeof NUMERIC_ORD_ORE\n> {}\nexport class EncryptedNumericOrdColumn extends EncryptedV3Column<\n  typeof NUMERIC_ORD\n> {}\n\n// text (text_search is defined above with its match-tuning override)\nexport class EncryptedTextColumn extends EncryptedV3Column<typeof TEXT> {}\nexport class EncryptedTextEqColumn extends EncryptedV3Column<typeof TEXT_EQ> {}\nexport class EncryptedTextMatchColumn extends EncryptedV3Column<\n  typeof TEXT_MATCH\n> {}\nexport class EncryptedTextOrdOreColumn extends EncryptedV3Column<\n  typeof TEXT_ORD_ORE\n> {}\nexport class EncryptedTextOrdColumn extends EncryptedV3Column<\n  typeof TEXT_ORD\n> {}\n\n// boolean\nexport class EncryptedBooleanColumn extends EncryptedV3Column<typeof BOOLEAN> {}\n\n// real\nexport class EncryptedRealColumn extends EncryptedV3Column<typeof REAL> {}\nexport class EncryptedRealEqColumn extends EncryptedV3Column<typeof REAL_EQ> {}\nexport class EncryptedRealOrdOreColumn extends EncryptedV3Column<\n  typeof REAL_ORD_ORE\n> {}\nexport class EncryptedRealOrdColumn extends EncryptedV3Column<\n  typeof REAL_ORD\n> {}\n\n// double\nexport class EncryptedDoubleColumn extends EncryptedV3Column<typeof DOUBLE> {}\nexport class EncryptedDoubleEqColumn extends EncryptedV3Column<\n  typeof DOUBLE_EQ\n> {}\nexport class EncryptedDoubleOrdOreColumn extends EncryptedV3Column<\n  typeof DOUBLE_ORD_ORE\n> {}\nexport class EncryptedDoubleOrdColumn extends EncryptedV3Column<\n  typeof DOUBLE_ORD\n> {}\n\n/**\n * Union of every v3 concrete column type. Used as the value type for v3 table\n * columns so a table may mix any generated domains.\n */\nexport type AnyEncryptedV3Column =\n  | EncryptedIntegerColumn\n  | EncryptedIntegerEqColumn\n  | EncryptedIntegerOrdOreColumn\n  | EncryptedIntegerOrdColumn\n  | EncryptedSmallintColumn\n  | EncryptedSmallintEqColumn\n  | EncryptedSmallintOrdOreColumn\n  | EncryptedSmallintOrdColumn\n  | EncryptedDateColumn\n  | EncryptedDateEqColumn\n  | EncryptedDateOrdOreColumn\n  | EncryptedDateOrdColumn\n  | EncryptedTimestampColumn\n  | EncryptedTimestampEqColumn\n  | EncryptedTimestampOrdOreColumn\n  | EncryptedTimestampOrdColumn\n  | EncryptedNumericColumn\n  | EncryptedNumericEqColumn\n  | EncryptedNumericOrdOreColumn\n  | EncryptedNumericOrdColumn\n  | EncryptedTextColumn\n  | EncryptedTextEqColumn\n  | EncryptedTextMatchColumn\n  | EncryptedTextOrdOreColumn\n  | EncryptedTextOrdColumn\n  | EncryptedTextSearchColumn\n  | EncryptedBooleanColumn\n  | EncryptedRealColumn\n  | EncryptedRealEqColumn\n  | EncryptedRealOrdOreColumn\n  | EncryptedRealOrdColumn\n  | EncryptedDoubleColumn\n  | EncryptedDoubleEqColumn\n  | EncryptedDoubleOrdOreColumn\n  | EncryptedDoubleOrdColumn\n\n/**\n * Shape of v3 table columns: every value is a v3 concrete column builder.\n * (Nested fields are deferred to later increments.)\n */\nexport type EncryptedV3TableColumn = {\n  [key: string]: AnyEncryptedV3Column\n}\n\n/** Map a domain's {@link PlaintextKind} to its TypeScript plaintext type. */\ntype PlaintextFromKind<K extends PlaintextKind> = K extends 'string'\n  ? string\n  : K extends 'number'\n    ? number\n    : K extends 'boolean'\n      ? boolean\n      : K extends 'date' | 'timestamp'\n        ? Date\n        : never\n\n/**\n * The plaintext type for a single v3 column, read from the literal domain\n * definition carried on the base class's private field. This is stable across\n * empty subclasses that share the same base generic — a subclass-name\n * conditional would collapse because those subclasses are structurally\n * assignable to one another.\n */\nexport type PlaintextForColumn<C> =\n  C extends EncryptedV3Column<infer D> ? PlaintextFromKind<D['castAs']> : never\n\n/**\n * The user-facing `queryType` names a v3 column supports, derived 1:1 from its\n * capability flags. Resolves to `never` for a storage-only column (all flags\n * `false`) and for any non-v3 value. The names mirror the {@link QueryCapabilities}\n * keys and the first three {@link import('@/types').QueryTypeName} members.\n */\nexport type QueryTypesForColumn<C> =\n  C extends EncryptedV3Column<infer D>\n    ?\n        | (D['capabilities']['equality'] extends true ? 'equality' : never)\n        | (D['capabilities']['orderAndRange'] extends true\n            ? 'orderAndRange'\n            : never)\n        | (D['capabilities']['freeTextSearch'] extends true\n            ? 'freeTextSearch'\n            : never)\n    : never\n\n/**\n * The concrete EQL v3 type string for a single column, read from the literal\n * domain definition carried on the base class's private field (mirrors\n * {@link PlaintextForColumn}). Distributes over a union of columns, so\n * `EqlTypeForColumn<AnyEncryptedV3Column>` yields the union of every domain's\n * `eqlType` — the canonical, source-of-truth key set for a type-driven test\n * matrix keyed by domain.\n */\nexport type EqlTypeForColumn<C> =\n  C extends EncryptedV3Column<infer D> ? D['eqlType'] : never\n"],"mappings":"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","names":[]}

package/dist/{client-C_7TF8EL.d.cts → client-DSGHBN-g.d.cts}

@@ -1,8 +1,8 @@
-import { h as EncryptedQueryResult, i as Client, S as ScalarQueryTerm, B as BulkDecryptedData, j as BulkDecryptPayload, D as Decrypted, k as BulkEncryptedData, l as BulkEncryptPayload, m as EncryptOptions, f as EncryptedColumn, n as EncryptedField, c as EncryptedTable, d as EncryptedTableColumn, E as Encrypted, o as EncryptQueryOptions, Q as QueryTypeName, p as EncryptedReturnType, q as EncryptConfig, K as KeysetIdentifier, r as EncryptedFromSchema, s as EncryptionClientConfig } from './types-public-Dv-r6Ik0.cjs';
-import { EncryptionError } from './errors/index.cjs';
 import { Result } from '@byteslice/result';
-import { JsPlaintext } from '@cipherstash/protect-ffi';
-import { LockContext } from './identity/index.cjs';
+import { EncryptionError } from './errors/index.cjs';
+import { n as EncryptedQueryResult, o as Client, S as ScalarQueryTerm, p as BulkDecryptedData, c as BulkDecryptPayload, D as Decrypted, q as BulkEncryptedData, B as BulkEncryptPayload, b as EncryptOptions, r as BuildableColumn, s as BuildableTable, a as Encrypted, P as Plaintext, t as EncryptQueryOptions, u as BuildableQueryColumn, Q as QueryTypeName, E as EncryptedReturnType, j as EncryptConfig, K as KeysetIdentifier, v as EncryptedFromBuildableTable, w as EncryptionClientConfig } from './types-public-CpS5KjwX.cjs';
+import { LockContextInput } from './identity/index.cjs';
+import { JsPlaintext, AuthStrategy } from '@cipherstash/protect-ffi';
 
 type AuditConfig = {
     metadata?: Record<string, unknown>;
@@ -32,24 +32,18 @@ declare abstract class EncryptionOperation<T> {
     then<TResult1 = Result<T, EncryptionError>, TResult2 = never>(onfulfilled?: ((value: Result<T, EncryptionError>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
 }
 
-/**
- * @internal Use {@link EncryptionClient.encryptQuery} with array input instead.
- */
 declare class BatchEncryptQueryOperation extends EncryptionOperation<EncryptedQueryResult[]> {
     private client;
     private terms;
     constructor(client: Client, terms: readonly ScalarQueryTerm[]);
-    withLockContext(lockContext: LockContext): BatchEncryptQueryOperationWithLockContext;
+    withLockContext(lockContext: LockContextInput): BatchEncryptQueryOperationWithLockContext;
     execute(): Promise<Result<EncryptedQueryResult[], EncryptionError>>;
 }
-/**
- * @internal Use {@link EncryptionClient.encryptQuery} with array input and `.withLockContext()` instead.
- */
 declare class BatchEncryptQueryOperationWithLockContext extends EncryptionOperation<EncryptedQueryResult[]> {
     private client;
     private terms;
     private lockContext;
-    constructor(client: Client, terms: readonly ScalarQueryTerm[], lockContext: LockContext, auditMetadata?: Record<string, unknown>);
+    constructor(client: Client, terms: readonly ScalarQueryTerm[], lockContext: LockContextInput, auditMetadata?: Record<string, unknown>);
     execute(): Promise<Result<EncryptedQueryResult[], EncryptionError>>;
 }
 
@@ -57,7 +51,7 @@ declare class BulkDecryptOperation extends EncryptionOperation<BulkDecryptedData
     private client;
     private encryptedPayloads;
     constructor(client: Client, encryptedPayloads: BulkDecryptPayload);
-    withLockContext(lockContext: LockContext): BulkDecryptOperationWithLockContext;
+    withLockContext(lockContext: LockContextInput): BulkDecryptOperationWithLockContext;
     execute(): Promise<Result<BulkDecryptedData, EncryptionError>>;
     getOperation(): {
         client: Client;
@@ -67,7 +61,7 @@ declare class BulkDecryptOperation extends EncryptionOperation<BulkDecryptedData
 declare class BulkDecryptOperationWithLockContext extends EncryptionOperation<BulkDecryptedData> {
     private operation;
     private lockContext;
-    constructor(operation: BulkDecryptOperation, lockContext: LockContext);
+    constructor(operation: BulkDecryptOperation, lockContext: LockContextInput);
     execute(): Promise<Result<BulkDecryptedData, EncryptionError>>;
 }
 
@@ -75,7 +69,7 @@ declare class BulkDecryptModelsOperation<T extends Record<string, unknown>> exte
     private client;
     private models;
     constructor(client: Client, models: T[]);
-    withLockContext(lockContext: LockContext): BulkDecryptModelsOperationWithLockContext<T>;
+    withLockContext(lockContext: LockContextInput): BulkDecryptModelsOperationWithLockContext<T>;
     execute(): Promise<Result<Decrypted<T>[], EncryptionError>>;
     getOperation(): {
         client: Client;
@@ -85,7 +79,7 @@ declare class BulkDecryptModelsOperation<T extends Record<string, unknown>> exte
 declare class BulkDecryptModelsOperationWithLockContext<T extends Record<string, unknown>> extends EncryptionOperation<Decrypted<T>[]> {
     private operation;
     private lockContext;
-    constructor(operation: BulkDecryptModelsOperation<T>, lockContext: LockContext);
+    constructor(operation: BulkDecryptModelsOperation<T>, lockContext: LockContextInput);
     execute(): Promise<Result<Decrypted<T>[], EncryptionError>>;
 }
 
@@ -95,19 +89,19 @@ declare class BulkEncryptOperation extends EncryptionOperation<BulkEncryptedData
     private column;
     private table;
     constructor(client: Client, plaintexts: BulkEncryptPayload, opts: EncryptOptions);
-    withLockContext(lockContext: LockContext): BulkEncryptOperationWithLockContext;
+    withLockContext(lockContext: LockContextInput): BulkEncryptOperationWithLockContext;
     execute(): Promise<Result<BulkEncryptedData, EncryptionError>>;
     getOperation(): {
         client: Client;
         plaintexts: BulkEncryptPayload;
-        column: EncryptedColumn | EncryptedField;
-        table: EncryptedTable<EncryptedTableColumn>;
+        column: BuildableColumn;
+        table: BuildableTable;
     };
 }
 declare class BulkEncryptOperationWithLockContext extends EncryptionOperation<BulkEncryptedData> {
     private operation;
     private lockContext;
-    constructor(operation: BulkEncryptOperation, lockContext: LockContext);
+    constructor(operation: BulkEncryptOperation, lockContext: LockContextInput);
     execute(): Promise<Result<BulkEncryptedData, EncryptionError>>;
 }
 
@@ -115,19 +109,19 @@ declare class BulkEncryptModelsOperation<T extends Record<string, unknown>> exte
     private client;
     private models;
     private table;
-    constructor(client: Client, models: Record<string, unknown>[], table: EncryptedTable<EncryptedTableColumn>);
-    withLockContext(lockContext: LockContext): BulkEncryptModelsOperationWithLockContext<T>;
+    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: EncryptedTable<EncryptedTableColumn>;
+        table: BuildableTable;
     };
 }
 declare class BulkEncryptModelsOperationWithLockContext<T extends Record<string, unknown>> extends EncryptionOperation<T[]> {
     private operation;
     private lockContext;
-    constructor(operation: BulkEncryptModelsOperation<T>, lockContext: LockContext);
+    constructor(operation: BulkEncryptModelsOperation<T>, lockContext: LockContextInput);
     execute(): Promise<Result<T[], EncryptionError>>;
 }
 
@@ -138,19 +132,19 @@ declare class BulkEncryptModelsOperationWithLockContext<T extends Record<string,
 declare class DecryptOperation extends EncryptionOperation<JsPlaintext> {
     private client;
     private encryptedData;
-    constructor(client: Client, encryptedData: Encrypted);
-    withLockContext(lockContext: LockContext): DecryptOperationWithLockContext;
+    constructor(client: Client, encryptedData: Encrypted | null);
+    withLockContext(lockContext: LockContextInput): DecryptOperationWithLockContext;
     execute(): Promise<Result<JsPlaintext, EncryptionError>>;
     getOperation(): {
         client: Client;
-        encryptedData: Encrypted;
+        encryptedData: Encrypted | null;
         auditData?: Record<string, unknown>;
     };
 }
 declare class DecryptOperationWithLockContext extends EncryptionOperation<JsPlaintext> {
     private operation;
     private lockContext;
-    constructor(operation: DecryptOperation, lockContext: LockContext);
+    constructor(operation: DecryptOperation, lockContext: LockContextInput);
     execute(): Promise<Result<JsPlaintext, EncryptionError>>;
 }
 
@@ -158,7 +152,7 @@ declare class DecryptModelOperation<T extends Record<string, unknown>> extends E
     private client;
     private model;
     constructor(client: Client, model: T);
-    withLockContext(lockContext: LockContext): DecryptModelOperationWithLockContext<T>;
+    withLockContext(lockContext: LockContextInput): DecryptModelOperationWithLockContext<T>;
     execute(): Promise<Result<Decrypted<T>, EncryptionError>>;
     getOperation(): {
         client: Client;
@@ -168,7 +162,7 @@ declare class DecryptModelOperation<T extends Record<string, unknown>> extends E
 declare class DecryptModelOperationWithLockContext<T extends Record<string, unknown>> extends EncryptionOperation<Decrypted<T>> {
     private operation;
     private lockContext;
-    constructor(operation: DecryptModelOperation<T>, lockContext: LockContext);
+    constructor(operation: DecryptModelOperation<T>, lockContext: LockContextInput);
     execute(): Promise<Result<Decrypted<T>, EncryptionError>>;
 }
 
@@ -177,20 +171,20 @@ declare class EncryptOperation extends EncryptionOperation<Encrypted> {
     private plaintext;
     private column;
     private table;
-    constructor(client: Client, plaintext: JsPlaintext, opts: EncryptOptions);
-    withLockContext(lockContext: LockContext): EncryptOperationWithLockContext;
+    constructor(client: Client, plaintext: Plaintext | null, opts: EncryptOptions);
+    withLockContext(lockContext: LockContextInput): EncryptOperationWithLockContext;
     execute(): Promise<Result<Encrypted, EncryptionError>>;
     getOperation(): {
         client: Client;
-        plaintext: JsPlaintext;
-        column: EncryptedColumn | EncryptedField;
-        table: EncryptedTable<EncryptedTableColumn>;
+        plaintext: Plaintext | null;
+        column: BuildableColumn;
+        table: BuildableTable;
     };
 }
 declare class EncryptOperationWithLockContext extends EncryptionOperation<Encrypted> {
     private operation;
     private lockContext;
-    constructor(operation: EncryptOperation, lockContext: LockContext);
+    constructor(operation: EncryptOperation, lockContext: LockContextInput);
     execute(): Promise<Result<Encrypted, EncryptionError>>;
 }
 
@@ -198,54 +192,69 @@ declare class EncryptModelOperation<T extends Record<string, unknown>> extends E
     private client;
     private model;
     private table;
-    constructor(client: Client, model: Record<string, unknown>, table: EncryptedTable<EncryptedTableColumn>);
-    withLockContext(lockContext: LockContext): EncryptModelOperationWithLockContext<T>;
+    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: EncryptedTable<EncryptedTableColumn>;
+        table: BuildableTable;
     };
 }
 declare class EncryptModelOperationWithLockContext<T extends Record<string, unknown>> extends EncryptionOperation<T> {
     private operation;
     private lockContext;
-    constructor(operation: EncryptModelOperation<T>, lockContext: LockContext);
+    constructor(operation: EncryptModelOperation<T>, lockContext: LockContextInput);
     execute(): Promise<Result<T, EncryptionError>>;
 }
 
-/**
- * @internal Use {@link EncryptionClient.encryptQuery} instead.
- */
 declare class EncryptQueryOperation extends EncryptionOperation<EncryptedQueryResult> {
     private client;
     private plaintext;
     private opts;
-    constructor(client: Client, plaintext: JsPlaintext, opts: EncryptQueryOptions);
-    withLockContext(lockContext: LockContext): EncryptQueryOperationWithLockContext;
+    constructor(client: Client, plaintext: Plaintext | null | undefined, opts: EncryptQueryOptions);
+    withLockContext(lockContext: LockContextInput): EncryptQueryOperationWithLockContext;
     execute(): Promise<Result<EncryptedQueryResult, EncryptionError>>;
     getOperation(): {
-        column: EncryptedColumn;
-        table: EncryptedTable<EncryptedTableColumn>;
+        column: BuildableQueryColumn;
+        table: BuildableTable;
         queryType?: QueryTypeName;
         returnType?: EncryptedReturnType;
         client: Client;
-        plaintext: JsPlaintext;
+        plaintext: Plaintext | null | undefined;
     };
 }
-/**
- * @internal Use {@link EncryptionClient.encryptQuery} with `.withLockContext()` instead.
- */
 declare class EncryptQueryOperationWithLockContext extends EncryptionOperation<EncryptedQueryResult> {
     private client;
     private plaintext;
     private opts;
     private lockContext;
-    constructor(client: Client, plaintext: JsPlaintext, opts: EncryptQueryOptions, lockContext: LockContext, auditMetadata?: Record<string, unknown>);
+    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.
  *
@@ -267,6 +276,8 @@ declare class EncryptionClient {
         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.
@@ -343,7 +354,7 @@ declare class EncryptionClient {
      * @see {@link LockContext}
      * @see {@link EncryptOperation}
      */
-    encrypt(plaintext: JsPlaintext, opts: EncryptOptions): EncryptOperation;
+    encrypt(plaintext: Plaintext, opts: EncryptOptions): EncryptOperation;
     /**
      * Encrypt a query value - returns a promise which resolves to an encrypted query value.
      *
@@ -397,7 +408,7 @@ declare class EncryptionClient {
      * - String plaintext → `steVecSelector` (JSONPath queries like `'$.user.email'`)
      * - Object/Array plaintext → `steVecTerm` (containment queries like `{ role: 'admin' }`)
      */
-    encryptQuery(plaintext: JsPlaintext, opts: EncryptQueryOptions): EncryptQueryOperation;
+    encryptQuery(plaintext: Plaintext, opts: EncryptQueryOptions): EncryptQueryOperation;
     /**
      * Encrypt multiple values for use in queries (batch operation).
      * @param terms - Array of query terms to encrypt
@@ -432,6 +443,13 @@ declare class EncryptionClient {
      *      .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}
      */
@@ -482,7 +500,7 @@ declare class EncryptionClient {
      * }
      * ```
      */
-    encryptModel<T extends Record<string, unknown>, S extends EncryptedTableColumn = EncryptedTableColumn>(input: T, table: EncryptedTable<S>): EncryptModelOperation<EncryptedFromSchema<T, S>>;
+    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.
      *
@@ -557,7 +575,7 @@ declare class EncryptionClient {
      * }
      * ```
      */
-    bulkEncryptModels<T extends Record<string, unknown>, S extends EncryptedTableColumn = EncryptedTableColumn>(input: Array<T>, table: EncryptedTable<S>): BulkEncryptModelsOperation<EncryptedFromSchema<T, S>>;
+    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.
      *
@@ -662,36 +680,155 @@ declare class EncryptionClient {
      */
     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. Credentials are read from the optional `config` or from the environment
- * (`CS_WORKSPACE_CRN`, `CS_CLIENT_ID`, `CS_CLIENT_KEY`, `CS_CLIENT_ACCESS_KEY`).
- *
- * @param config - Initialization options. Must include `schemas`; optionally include `config` for
- *   workspace/keys. 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.
+ * columns to use:
  *
- * @throws Throws if `schemas` is empty, or if a keyset `id` is supplied but is not a valid UUID.
- *   Also throws if {@link EncryptionClient.init} fails (e.g. invalid credentials or config).
- *
- * @example
  * ```typescript
  * import { Encryption, encryptedTable, encryptedColumn } from "@cipherstash/stack"
  *
- * const users = encryptedTable("users", {
- *   email: encryptedColumn("email"),
- * })
+ * 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 { type AuditConfig as A, Encryption as E, EncryptionClient as a, noClientError as n };
+export { type AuditConfig as A, BulkEncryptModelsOperation as B, DecryptOperation as D, EncryptOperation as E, __resetStrategyDeprecationWarningForTests as _, EncryptQueryOperation as a, EncryptModelOperation as b, BulkEncryptOperation as c, BulkDecryptOperation as d, EncryptionClient as e, Encryption as f, BatchEncryptQueryOperation as g, BulkDecryptModelsOperation as h, DecryptModelOperation as i, noClientError as n, resolveEqlVersion as r };