@cipherstash/stack 0.16.0 → 0.19.0

package/dist/{types-public-Dv-r6Ik0.d.ts → types-public-CpS5KjwX.d.cts}

@@ -1,5 +1,5 @@
+import { JsPlaintext, EncryptedPayload, newClient, EncryptedQuery as EncryptedQuery$1, EncryptedV3Query, AuthStrategy, Encrypted as Encrypted$1 } from '@cipherstash/protect-ffi';
 import { z } from 'zod';
-import { Encrypted as Encrypted$1, newClient, JsPlaintext } from '@cipherstash/protect-ffi';
 
 /** Brand symbol for nominal typing */
 declare const __brand: unique symbol;
@@ -10,8 +10,44 @@ type Brand<T, B extends string> = T & {
 type Client = Awaited<ReturnType<typeof newClient>> | undefined;
 /** A branded type representing encrypted data. Cannot be accidentally used as plaintext. */
 type EncryptedValue = Brand<Encrypted$1, 'encrypted'>;
-/** Structural type representing encrypted data. See also `EncryptedValue` for branded nominal typing. */
-type Encrypted = Encrypted$1;
+/** Structural type representing encrypted data stored in the database. Always
+ * carries a ciphertext. Covers BOTH wire formats: the EQL v2.3 payloads
+ * (`k: "ct"` / `k: "sv"`) and the EQL v3 payloads (flat `{v: 3, i, c, …}`
+ * scalars and `{v: 3, k: "sv", i, sv}` SteVec documents). Which format
+ * `encrypt` produces is selected by the client's
+ * {@link ClientConfig.eqlVersion}; `decrypt` accepts both regardless.
+ * v3 scalars carry no `k` discriminator, so narrow with `'k' in payload`
+ * before reading it. See also `EncryptedValue` for branded nominal typing,
+ * and {@link EncryptedQuery} for the search-term shape returned by
+ * `encryptQuery`. */
+type Encrypted = EncryptedPayload;
+/** Structural type representing an encrypted query term (search needle)
+ * returned by `encryptQuery` / `encryptQueryBulk` for scalar
+ * (`unique` / `match` / `ore`) lookups and `ste_vec_selector` JSON path
+ * queries, plus — under `eqlVersion: 3` — the `eql_v3.jsonb_query`
+ * containment needle. Carries no ciphertext — matched against stored
+ * values, never decrypted. v2 JSON containment queries (`ste_vec_term`)
+ * return a storage-shaped {@link Encrypted} payload instead. */
+type EncryptedQuery = EncryptedQuery$1 | EncryptedV3Query;
+/**
+ * Plaintext values the SDK accepts for encryption.
+ *
+ * Widens the FFI's `JsPlaintext` (`string | number | boolean |
+ * Record<string, unknown> | JsPlaintext[]`) with `Date`. `Date` is a supported
+ * cast target that is omitted from the FFI's `JsPlaintext` INPUT union, but it
+ * serializes at the boundary via `toJSON` (ISO string), so it is accepted on the
+ * way in.
+ *
+ * `bigint` is intentionally NOT included: the native `@cipherstash/protect-ffi`
+ * build cannot marshal a JS `bigint` (V8 throws "Do not know how to serialize a
+ * BigInt") and rejects a `string` for a `big_int` column. The v3 int8 domains
+ * are therefore omitted from the SDK entirely (see `eql/v3`) until the FFI
+ * supports lossless bigint I/O; `bigint` returns here alongside them.
+ *
+ * When the upstream FFI `JsPlaintext` is corrected to include `Date`, the `Date`
+ * arm can collapse back into `JsPlaintext`.
+ */
+type Plaintext = JsPlaintext | Date;
 type KeysetIdentifier = {
     name: string;
 } | {
@@ -46,15 +82,146 @@ type ClientConfig = {
      * An optional keyset identifier for multi-tenant encryption.
      * Each keyset provides cryptographic isolation, giving each tenant its own keyspace.
      * Specify by name (`{ name: "tenant-a" }`) or UUID (`{ id: "..." }`).
-     * Keysets are created and managed in the CipherStash dashboard.
+     * Keysets are created and managed in the
+     * [dashboard](https://dashboard.cipherstash.com/workspaces/_/keysets); omit to
+     * use the workspace's default keyset. A client is bound to one keyset for its
+     * lifetime, so use one client per tenant.
+     *
+     * @see {@link Encryption} for the full keysets walkthrough.
      */
     keyset?: KeysetIdentifier;
+    /**
+     * An optional authentication strategy for ZeroKMS requests, from
+     * `@cipherstash/auth` (re-exported by `@cipherstash/stack`). When provided,
+     * its `getToken()` is invoked on every ZeroKMS request and takes precedence
+     * over the default `auto` strategy (the `clientKey` is still required for
+     * encryption). Use:
+     *
+     * - `OidcFederationStrategy` for per-user, identity-bound encryption —
+     *   federates an end user's OIDC JWT into a CTS service token, so requests
+     *   authenticate as that user. Pair with `.withLockContext({ identityClaim })`
+     *   to bind the data key to a claim. This replaces the older
+     *   `LockContext.identify()` ceremony.
+     * - `AccessKeyStrategy` for service-to-service / CI, or any custom
+     *   `{ getToken() }` object for bespoke token acquisition / caching.
+     *
+     * Leave unset to use the default `auto` strategy, which reads credentials
+     * from the `CS_*` environment variables and falls back to the local dev
+     * profile created by `npx stash auth login`.
+     *
+     * @see {@link AuthStrategy}
+     * @see {@link Encryption} for a full walkthrough of the authentication options.
+     */
+    authStrategy?: AuthStrategy;
+    /**
+     * @deprecated Renamed to {@link ClientConfig.authStrategy}. Still honoured for
+     * backwards compatibility — passing it logs a deprecation warning at runtime —
+     * but it will be removed in a future release. Set `authStrategy` instead.
+     */
+    strategy?: AuthStrategy;
+    /**
+     * The EQL wire version the client emits — one FFI client always emits
+     * exactly one wire format.
+     *
+     * - `2` (the protect-ffi default): payloads target the
+     *   `eql_v2_encrypted` column type.
+     * - `3`: payloads target the per-capability `eql_v3` domains
+     *   (`eql_v3.text_eq`, `eql_v3.integer_ord_ore`, `eql_v3.json`, …),
+     *   derived from each column's `cast_as` and indexes.
+     *
+     * When omitted, {@link Encryption} auto-detects from the schema set:
+     * EQL v3 tables (from `@cipherstash/stack/v3`, marked by
+     * `buildColumnKeyMap()`) select `3`; v2 tables leave the FFI default
+     * (`2`) untouched. Mixing v2 and v3 tables in one client is an error —
+     * split them across two clients instead.
+     *
+     * `decrypt` accepts BOTH formats regardless of this setting, so v2 and
+     * v3 data can coexist during a migration.
+     *
+     * v3 limitation (protect-ffi 0.27): `encryptQuery` supports only JSON
+     * containment queries — scalar-index and selector queries throw
+     * `EQL_V3_QUERY_UNSUPPORTED` until a v3 scalar query wire shape exists.
+     */
+    eqlVersion?: 2 | 3;
 };
 type AtLeastOneCsTable<T> = [T, ...T[]];
+/** Structural contract for a column builder the client can consume for STORAGE
+ *  (`encrypt`). Satisfied by v2 `EncryptedColumn` / `EncryptedField` AND v3
+ *  `EncryptedTextSearchColumn` — fields ARE encryptable, so this stays wide. */
+interface BuildableColumn {
+    getName(): string;
+    build(): ColumnSchema;
+}
+/** Structural contract for a column the client can consume for QUERIES
+ *  (`encryptQuery` / search terms). Narrower than `BuildableColumn`: it must
+ *  EXCLUDE non-queryable `EncryptedField` (a field has no indexes). A v2
+ *  `EncryptedColumn` qualifies via the nominal arm; a v3 queryable concrete
+ *  type qualifies via the `getEqlType()` structural arm; `EncryptedField` (no
+ *  `getEqlType`, not an `EncryptedColumn`) is rejected. */
+interface BuildableV3QueryableColumn extends BuildableColumn {
+    getEqlType(): string;
+    getQueryCapabilities(): {
+        equality: boolean;
+        orderAndRange: boolean;
+        freeTextSearch: boolean;
+    };
+    isQueryable(): true;
+}
+type BuildableQueryColumn = EncryptedColumn | BuildableV3QueryableColumn;
+/** Structural contract for a table builder the client can consume. Satisfied by
+ *  v2 and v3 `EncryptedTable` alike. */
+interface BuildableTable {
+    tableName: string;
+    build(): {
+        tableName: string;
+        columns: Record<string, ColumnSchema>;
+    };
+    /**
+     * Optional map from a model field's JS property name to its encrypt-config
+     * column name (the DB name). Present when the two can differ — v3 tables key
+     * their config by DB name (`column.getName()`) while models are written with
+     * JS property keys, so the model path must match by property but address the
+     * FFI/config by DB name.
+     *
+     * Absent on v2 tables, whose `build()` already keys columns by the JS property
+     * name; the model path then matches and addresses by that same key.
+     */
+    buildColumnKeyMap?(): Record<string, string>;
+}
 type EncryptionClientConfig = {
-    schemas: AtLeastOneCsTable<EncryptedTable<EncryptedTableColumn>>;
+    schemas: AtLeastOneCsTable<BuildableTable>;
     config?: ClientConfig;
 };
+/**
+ * The literal column map of a buildable table, read from its type-level
+ * `_columnType` brand. Both v2 and v3 `EncryptedTable` carry this brand, so this
+ * recovers the literal column keys structurally.
+ *
+ * This deliberately uses the `_columnType` brand rather than `build().columns`:
+ * `BuildableTable.build()` is typed to return `Record<string, ColumnSchema>`,
+ * which erases the literal keys and would mark EVERY model field as encrypted.
+ *
+ * The fallbacks resolve to `Record<never, never>` (a no-key type), NOT `never`:
+ * a value typed as the bare structural `BuildableTable` carries no `_columnType`
+ * brand, and `keyof never` is `string | number | symbol` — which would wrongly
+ * mark EVERY model field as encrypted. `keyof Record<never, never>` is `never`,
+ * so `EncryptedFromBuildableTable` degrades gracefully to the model unchanged.
+ */
+type BuildableTableColumns<T extends BuildableTable> = T extends {
+    readonly _columnType: infer C;
+} ? C extends Record<string, unknown> ? C : Record<never, never> : Record<never, never>;
+/**
+ * Maps a plaintext model type to its encrypted form using a buildable table.
+ *
+ * Fields whose keys match a column defined in `Table` (via its `_columnType`
+ * brand) become `Encrypted` (`Encrypted | null` when the source field is
+ * nullable); all other fields retain their original types from `T`. Works for
+ * both v2 and v3 tables. See {@link EncryptedFromSchema} for the v2-specific
+ * variant retained for backward compatibility.
+ */
+type EncryptedFromBuildableTable<T, Table extends BuildableTable> = {
+    [K in keyof T]: [K] extends [keyof BuildableTableColumns<Table>] ? null extends T[K] ? Encrypted | null : Encrypted : T[K];
+};
 /**
  * Options for single-value encrypt operations.
  * Use a column from your table schema (from {@link encryptedColumn}) or a nested
@@ -62,21 +229,26 @@ type EncryptionClientConfig = {
  */
 type EncryptOptions = {
     /** The column or nested field to encrypt into. From {@link EncryptedColumn} or {@link EncryptedField}. */
-    column: EncryptedColumn | EncryptedField;
-    table: EncryptedTable<EncryptedTableColumn>;
+    column: BuildableColumn;
+    table: BuildableTable;
 };
 /** Format for encrypted query/search term return values */
 type EncryptedReturnType = 'eql' | 'composite-literal' | 'escaped-composite-literal';
 type SearchTerm = {
-    value: JsPlaintext;
-    column: EncryptedColumn;
-    table: EncryptedTable<EncryptedTableColumn>;
+    value: Plaintext;
+    column: BuildableQueryColumn;
+    table: BuildableTable;
     returnType?: EncryptedReturnType;
 };
-/** Encrypted search term result: EQL object or composite literal string */
-type EncryptedSearchTerm = Encrypted | string;
-/** Result of encryptQuery (single or batch): EQL or composite literal string */
-type EncryptedQueryResult = Encrypted | string;
+/** Encrypted search term result. `eql` return type yields either a storage
+ * payload (`Encrypted`, for `ste_vec_term`) or a query-only term
+ * (`EncryptedQuery`, for scalar lookups and `ste_vec_selector`); the
+ * `composite-literal` return types yield a string. */
+type EncryptedSearchTerm = Encrypted | EncryptedQuery | string;
+/** Result of encryptQuery (single or batch). `eql` return type yields either a
+ * storage payload (`Encrypted`) or a query-only term (`EncryptedQuery`); the
+ * `composite-literal` return types yield a string. */
+type EncryptedQueryResult = Encrypted | EncryptedQuery | string | null;
 type EncryptedFields<T> = {
     [K in keyof T as NonNullable<T[K]> extends Encrypted ? K : never]: T[K];
 };
@@ -114,17 +286,17 @@ type EncryptedFromSchema<T, S extends EncryptedTableColumn> = {
 };
 type BulkEncryptPayload = Array<{
     id?: string;
-    plaintext: JsPlaintext;
+    plaintext: Plaintext | null;
 }>;
 type BulkEncryptedData = Array<{
     id?: string;
-    data: Encrypted;
+    data: Encrypted | null;
 }>;
 type BulkDecryptPayload = Array<{
     id?: string;
-    data: Encrypted;
+    data: Encrypted | null;
 }>;
-type BulkDecryptedData = Array<DecryptionResult<JsPlaintext>>;
+type BulkDecryptedData = Array<DecryptionResult<JsPlaintext | null>>;
 type DecryptionSuccess<T> = {
     error?: never;
     data: T;
@@ -162,14 +334,14 @@ declare const queryTypes: {
 };
 /** @internal */
 type QueryTermBase = {
-    column: EncryptedColumn;
-    table: EncryptedTable<EncryptedTableColumn>;
+    column: BuildableQueryColumn;
+    table: BuildableTable;
     queryType?: QueryTypeName;
     returnType?: EncryptedReturnType;
 };
 type EncryptQueryOptions = QueryTermBase;
 type ScalarQueryTerm = QueryTermBase & {
-    value: JsPlaintext;
+    value: Plaintext;
 };
 
 /**
@@ -179,6 +351,7 @@ type ScalarQueryTerm = QueryTermBase & {
  * - `"bigint"`
  * - `"boolean"`
  * - `"date"`
+ * - `"timestamp"`
  * - `"number"`
  * - `"string"`
  * - `"json"`
@@ -194,11 +367,11 @@ type ScalarQueryTerm = QueryTermBase & {
  * EQL cast types — the PostgreSQL-aligned types that EQL actually accepts.
  * These are stored in the `cast_as` field of the EncryptConfig.
  */
-declare const eqlCastAsEnum: z.ZodDefault<z.ZodEnum<["text", "int", "small_int", "big_int", "real", "double", "boolean", "date", "jsonb"]>>;
+declare const eqlCastAsEnum: z.ZodDefault<z.ZodEnum<["text", "int", "small_int", "big_int", "real", "double", "boolean", "date", "timestamp", "jsonb"]>>;
 /**
  * SDK-facing data types — developer-friendly aliases accepted by `dataType()`.
  */
-declare const castAsEnum: z.ZodDefault<z.ZodEnum<["bigint", "boolean", "date", "number", "string", "json", "text"]>>;
+declare const castAsEnum: z.ZodDefault<z.ZodEnum<["bigint", "boolean", "date", "timestamp", "number", "string", "json", "text"]>>;
 /**
  * Map SDK-facing data types to EQL `cast_as` values.
  *
@@ -316,7 +489,7 @@ declare const steVecIndexOptsSchema: z.ZodObject<{
     } | undefined;
 }>;
 declare const columnSchema: z.ZodDefault<z.ZodObject<{
-    cast_as: z.ZodDefault<z.ZodEnum<["bigint", "boolean", "date", "number", "string", "json", "text"]>>;
+    cast_as: z.ZodDefault<z.ZodEnum<["bigint", "boolean", "date", "timestamp", "number", "string", "json", "text"]>>;
     indexes: z.ZodDefault<z.ZodObject<{
         ore: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
         unique: z.ZodOptional<z.ZodObject<{
@@ -480,7 +653,7 @@ declare const columnSchema: z.ZodDefault<z.ZodObject<{
         } | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    cast_as: "string" | "number" | "bigint" | "boolean" | "text" | "date" | "json";
+    cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text";
     indexes: {
         match?: {
             token_filters?: {
@@ -512,7 +685,7 @@ declare const columnSchema: z.ZodDefault<z.ZodObject<{
         } | undefined;
     };
 }, {
-    cast_as?: "string" | "number" | "bigint" | "boolean" | "text" | "date" | "json" | undefined;
+    cast_as?: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text" | undefined;
     indexes?: {
         match?: {
             token_filters?: {
@@ -548,7 +721,7 @@ declare const columnSchema: z.ZodDefault<z.ZodObject<{
 declare const encryptConfigSchema: z.ZodObject<{
     v: z.ZodNumber;
     tables: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDefault<z.ZodObject<{
-        cast_as: z.ZodDefault<z.ZodEnum<["bigint", "boolean", "date", "number", "string", "json", "text"]>>;
+        cast_as: z.ZodDefault<z.ZodEnum<["bigint", "boolean", "date", "timestamp", "number", "string", "json", "text"]>>;
         indexes: z.ZodDefault<z.ZodObject<{
             ore: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
             unique: z.ZodOptional<z.ZodObject<{
@@ -712,7 +885,7 @@ declare const encryptConfigSchema: z.ZodObject<{
             } | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
-        cast_as: "string" | "number" | "bigint" | "boolean" | "text" | "date" | "json";
+        cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text";
         indexes: {
             match?: {
                 token_filters?: {
@@ -744,7 +917,7 @@ declare const encryptConfigSchema: z.ZodObject<{
             } | undefined;
         };
     }, {
-        cast_as?: "string" | "number" | "bigint" | "boolean" | "text" | "date" | "json" | undefined;
+        cast_as?: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text" | undefined;
         indexes?: {
             match?: {
                 token_filters?: {
@@ -779,7 +952,7 @@ declare const encryptConfigSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     v: number;
     tables: Record<string, Record<string, {
-        cast_as: "string" | "number" | "bigint" | "boolean" | "text" | "date" | "json";
+        cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text";
         indexes: {
             match?: {
                 token_filters?: {
@@ -814,7 +987,7 @@ declare const encryptConfigSchema: z.ZodObject<{
 }, {
     v: number;
     tables?: Record<string, Record<string, {
-        cast_as?: "string" | "number" | "bigint" | "boolean" | "text" | "date" | "json" | undefined;
+        cast_as?: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text" | undefined;
         indexes?: {
             match?: {
                 token_filters?: {
@@ -903,7 +1076,7 @@ declare class EncryptedField {
      */
     dataType(castAs: CastAs): this;
     build(): {
-        cast_as: "string" | "number" | "bigint" | "boolean" | "text" | "date" | "json";
+        cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text";
         indexes: {};
     };
     getName(): string;
@@ -1022,7 +1195,7 @@ declare class EncryptedColumn {
      */
     searchableJson(): this;
     build(): {
-        cast_as: "string" | "number" | "bigint" | "boolean" | "text" | "date" | "json";
+        cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text";
         indexes: {
             ore?: OreIndexOpts;
             unique?: UniqueIndexOpts;
@@ -1178,7 +1351,7 @@ declare function encryptedField(valueName: string): EncryptedField;
 /**
  * Build an encrypt config from a list of encrypted tables.
  *
- * @param ...tables - The list of encrypted tables to build the config from.
+ * @param protectTables - The list of encrypted tables to build the config from.
  * @returns An encrypt config object.
  *
  * @example
@@ -1197,6 +1370,6 @@ declare function encryptedField(valueName: string): EncryptedField;
  * console.log(config)
  * ```
  */
-declare function buildEncryptConfig(...protectTables: Array<EncryptedTable<EncryptedTableColumn>>): EncryptConfig;
+declare function buildEncryptConfig(...protectTables: Array<BuildableTable>): EncryptConfig;
 
-export { eqlCastAsEnum as A, type BulkDecryptedData as B, type CastAs as C, type Decrypted as D, type Encrypted as E, toEqlCastAs as F, type ClientConfig as G, type DecryptedFields as H, type InferEncrypted as I, type DecryptionResult as J, type KeysetIdentifier as K, type EncryptedFields as L, type MatchIndexOpts as M, type EncryptedSearchTerm as N, type OreIndexOpts as O, type OtherFields as P, type QueryTypeName as Q, type SearchTerm as R, type ScalarQueryTerm as S, type TokenFilter as T, type UniqueIndexOpts as U, queryTypes as V, encryptedField as a, encryptedTable as b, EncryptedTable as c, type EncryptedTableColumn as d, encryptedColumn as e, EncryptedColumn as f, type EncryptedValue as g, type EncryptedQueryResult as h, type Client as i, type BulkDecryptPayload as j, type BulkEncryptedData as k, type BulkEncryptPayload as l, type EncryptOptions as m, EncryptedField as n, type EncryptQueryOptions as o, type EncryptedReturnType as p, type EncryptConfig as q, type EncryptedFromSchema as r, type EncryptionClientConfig as s, type InferPlaintext as t, type ColumnSchema as u, type EqlCastAs as v, type SteVecIndexOpts as w, buildEncryptConfig as x, castAsEnum as y, encryptConfigSchema as z };
+export { type OtherFields as $, type SteVecIndexOpts as A, type BulkEncryptPayload as B, type ClientConfig as C, type Decrypted as D, type EncryptedReturnType as E, buildEncryptConfig as F, castAsEnum as G, encryptConfigSchema as H, type InferEncrypted as I, eqlCastAsEnum as J, type KeysetIdentifier as K, toEqlCastAs as L, type MatchIndexOpts as M, type BuildableTableColumns as N, type OreIndexOpts as O, type Plaintext as P, type QueryTypeName as Q, type BuildableV3QueryableColumn as R, type ScalarQueryTerm as S, type TokenFilter as T, type UniqueIndexOpts as U, type DecryptedFields as V, type DecryptionResult as W, type EncryptedFields as X, type EncryptedFromSchema as Y, type EncryptedQuery as Z, type EncryptedSearchTerm as _, type Encrypted as a, type SearchTerm as a0, queryTypes as a1, type EncryptOptions as b, type BulkDecryptPayload as c, encryptedField as d, encryptedColumn as e, encryptedTable as f, EncryptedTable as g, type EncryptedTableColumn as h, type ColumnSchema as i, type EncryptConfig as j, EncryptedColumn as k, type CastAs as l, type EncryptedValue as m, type EncryptedQueryResult as n, type Client as o, type BulkDecryptedData as p, type BulkEncryptedData as q, type BuildableColumn as r, type BuildableTable as s, type EncryptQueryOptions as t, type BuildableQueryColumn as u, type EncryptedFromBuildableTable as v, type EncryptionClientConfig as w, EncryptedField as x, type InferPlaintext as y, type EqlCastAs as z };