@cipherstash/stack 0.18.0 → 1.0.0-rc.0

package/dist/encryption/v3.d.cts

@@ -0,0 +1,103 @@
+import { Result } from '@byteslice/result';
+import { V as PlaintextForColumn, X as QueryTypesForColumn } from '../columns-D2_YzrCX.cjs';
+export { A as AnyEncryptedV3Column, E as EncryptedBigintColumn, a as EncryptedBigintEqColumn, b as EncryptedBigintOrdColumn, c as EncryptedBigintOrdOreColumn, d as EncryptedBooleanColumn, e as EncryptedDateColumn, f as EncryptedDateEqColumn, g as EncryptedDateOrdColumn, h as EncryptedDateOrdOreColumn, i as EncryptedDoubleColumn, j as EncryptedDoubleEqColumn, k as EncryptedDoubleOrdColumn, l as EncryptedDoubleOrdOreColumn, m as EncryptedIntegerColumn, n as EncryptedIntegerEqColumn, o as EncryptedIntegerOrdColumn, p as EncryptedIntegerOrdOreColumn, q as EncryptedJsonColumn, r as EncryptedNumericColumn, s as EncryptedNumericEqColumn, t as EncryptedNumericOrdColumn, u as EncryptedNumericOrdOreColumn, v as EncryptedRealColumn, w as EncryptedRealEqColumn, x as EncryptedRealOrdColumn, y as EncryptedRealOrdOreColumn, z as EncryptedSmallintColumn, B as EncryptedSmallintEqColumn, C as EncryptedSmallintOrdColumn, F as EncryptedSmallintOrdOreColumn, G as EncryptedTextColumn, H as EncryptedTextEqColumn, I as EncryptedTextMatchColumn, J as EncryptedTextOrdColumn, K as EncryptedTextOrdOreColumn, L as EncryptedTextSearchColumn, M as EncryptedTimestampColumn, N as EncryptedTimestampEqColumn, O as EncryptedTimestampOrdColumn, P as EncryptedTimestampOrdOreColumn, R as EncryptedV3TableColumn, S as EqlTypeForColumn, T as JsonDocument, U as JsonValue, W as QueryCapabilities, Y as TEXT_SEARCH_EQL_TYPE } from '../columns-D2_YzrCX.cjs';
+import { AnyV3Table, ColumnsOf, QueryableColumnsOf, V3ModelInput, V3EncryptedModel, V3DecryptedModel } from '../eql/v3/index.cjs';
+export { EncryptedTable, InferEncrypted, InferPlaintext, buildEncryptConfig, encryptedTable, types } from '../eql/v3/index.cjs';
+import { EncryptionError } from '../errors/index.cjs';
+import { LockContextInput } from '../identity/index.cjs';
+import { j as ClientConfig, x as EncryptedReturnType, S as ScalarQueryTerm, p as Encrypted, g as BulkEncryptPayload, n as EncryptOptions, e as BulkDecryptPayload } from '../types-public-QMjYNfQO.cjs';
+import { EncryptOperation, EncryptQueryOperation, BatchEncryptQueryOperation, EncryptModelOperation, BulkEncryptModelsOperation, DecryptOperation, BulkEncryptOperation, BulkDecryptOperation, EncryptionClient } from './index.cjs';
+import '@cipherstash/protect-ffi';
+import 'zod';
+import '../base-operation-AOAIvsSB.cjs';
+
+/**
+ * A strongly-typed view over an {@link EncryptionClient} for EQL v3 schemas.
+ *
+ * Every method derives its types from the concrete `table` / `column` builder
+ * arguments (which carry their branded types at the call site), so:
+ * - `encrypt` / `encryptQuery` pin the plaintext to the column's domain type
+ *   (`text → string`, `timestamp → Date`, …);
+ * - `encryptQuery` additionally constrains `queryType` to the column's
+ *   capabilities and rejects storage-only columns outright;
+ * - `encryptModel` / `bulkEncryptModels` validate schema-column fields against
+ *   their inferred plaintext type (passthrough fields are untouched) and return
+ *   a precise encrypted model;
+ * - `decryptModel` / `bulkDecryptModels` return the precise plaintext model,
+ *   reconstructing `Date` values from the encrypt-config `cast_as`.
+ *
+ * @typeParam S - the tuple of registered v3 tables; `table` arguments must be a
+ *   member of this tuple.
+ */
+interface TypedEncryptionClient<S extends readonly AnyV3Table[]> {
+    encrypt<Table extends S[number], Col extends ColumnsOf<Table>>(plaintext: PlaintextForColumn<Col>, opts: {
+        table: Table;
+        column: Col;
+    }): EncryptOperation;
+    encryptQuery<Table extends S[number], Col extends QueryableColumnsOf<Table>, QT extends QueryTypesForColumn<Col> = QueryTypesForColumn<Col>>(plaintext: PlaintextForColumn<Col>, opts: {
+        table: Table;
+        column: Col;
+        queryType?: QT;
+        returnType?: EncryptedReturnType;
+    }): EncryptQueryOperation;
+    /**
+     * Batch form: encrypt many query terms in one crossing. Mirrors the nominal
+     * {@link EncryptionClient} overload — the per-term columns are heterogeneous,
+     * so the terms are the base {@link ScalarQueryTerm} rather than a per-column
+     * narrowed type. Consumed by the Drizzle `inArray`/`notInArray` operators.
+     */
+    encryptQuery(terms: readonly ScalarQueryTerm[]): BatchEncryptQueryOperation;
+    encryptModel<Table extends S[number], T extends Record<string, unknown>>(input: V3ModelInput<Table, T>, table: Table): EncryptModelOperation<V3EncryptedModel<Table, T>>;
+    bulkEncryptModels<Table extends S[number], T extends Record<string, unknown>>(input: Array<V3ModelInput<Table, T>>, table: Table): BulkEncryptModelsOperation<V3EncryptedModel<Table, T>>;
+    /**
+     * Decrypt a single value. Cannot be strongly typed — a lone ciphertext carries
+     * no column identity — so it resolves to the FFI plaintext union unchanged.
+     */
+    decrypt(encrypted: Encrypted): DecryptOperation;
+    /**
+     * Decrypt a model, returning the precise plaintext shape for `table`. `Date`
+     * columns are reconstructed from the encrypt-config `cast_as`.
+     *
+     * Pass `lockContext` to decrypt identity-bound data — the same context that
+     * was supplied at encrypt time must be provided here.
+     *
+     * Unlike the encrypt operations this returns a plain `Promise<Result<…>>`
+     * rather than a chainable operation, because it maps the resolved value.
+     */
+    decryptModel<Table extends S[number], T extends Record<string, unknown>>(input: T, table: Table, lockContext?: LockContextInput): Promise<Result<V3DecryptedModel<Table, T>, EncryptionError>>;
+    bulkDecryptModels<Table extends S[number], T extends Record<string, unknown>>(input: Array<T>, table: Table, lockContext?: LockContextInput): Promise<Result<Array<V3DecryptedModel<Table, T>>, EncryptionError>>;
+    bulkEncrypt(plaintexts: BulkEncryptPayload, opts: EncryptOptions): BulkEncryptOperation;
+    bulkDecrypt(payloads: BulkDecryptPayload): BulkDecryptOperation;
+    getEncryptConfig(): ReturnType<EncryptionClient['getEncryptConfig']>;
+}
+/**
+ * Wrap an already-built {@link EncryptionClient} in a {@link TypedEncryptionClient}
+ * for the given v3 schemas. Zero runtime cost for the encrypt/query paths (the
+ * underlying operations are returned unchanged); the decrypt-model paths add a
+ * per-column `Date` reconstruction step.
+ *
+ * The `schemas` are captured with a `const` type parameter so array-literal
+ * widening does not collapse per-table inference.
+ */
+declare function typedClient<const S extends readonly AnyV3Table[]>(client: EncryptionClient, ...schemas: S): TypedEncryptionClient<S>;
+/**
+ * Build a {@link TypedEncryptionClient} for EQL v3 schemas — the strongly-typed
+ * counterpart to {@link Encryption}. Mirrors its config, then retypes the client
+ * against the provided v3 `schemas`.
+ *
+ * @example
+ * ```typescript
+ * import { EncryptionV3, encryptedTable, types } from "@cipherstash/stack/v3"
+ *
+ * const users = encryptedTable("users", { email: types.TextSearch("email") })
+ * const client = await EncryptionV3({ schemas: [users] })
+ *
+ * await client.encrypt("a@b.com", { table: users, column: users.email })
+ * ```
+ */
+declare function EncryptionV3<const S extends readonly AnyV3Table[]>(config: {
+    schemas: S;
+    config?: ClientConfig;
+}): Promise<TypedEncryptionClient<S>>;
+
+export { AnyV3Table, ColumnsOf, EncryptionV3, PlaintextForColumn, QueryTypesForColumn, QueryableColumnsOf, type TypedEncryptionClient, V3DecryptedModel, V3EncryptedModel, V3ModelInput, typedClient };

package/dist/encryption/v3.d.ts

@@ -0,0 +1,103 @@
+import { Result } from '@byteslice/result';
+import { V as PlaintextForColumn, X as QueryTypesForColumn } from '../columns-rZc7fQHI.js';
+export { A as AnyEncryptedV3Column, E as EncryptedBigintColumn, a as EncryptedBigintEqColumn, b as EncryptedBigintOrdColumn, c as EncryptedBigintOrdOreColumn, d as EncryptedBooleanColumn, e as EncryptedDateColumn, f as EncryptedDateEqColumn, g as EncryptedDateOrdColumn, h as EncryptedDateOrdOreColumn, i as EncryptedDoubleColumn, j as EncryptedDoubleEqColumn, k as EncryptedDoubleOrdColumn, l as EncryptedDoubleOrdOreColumn, m as EncryptedIntegerColumn, n as EncryptedIntegerEqColumn, o as EncryptedIntegerOrdColumn, p as EncryptedIntegerOrdOreColumn, q as EncryptedJsonColumn, r as EncryptedNumericColumn, s as EncryptedNumericEqColumn, t as EncryptedNumericOrdColumn, u as EncryptedNumericOrdOreColumn, v as EncryptedRealColumn, w as EncryptedRealEqColumn, x as EncryptedRealOrdColumn, y as EncryptedRealOrdOreColumn, z as EncryptedSmallintColumn, B as EncryptedSmallintEqColumn, C as EncryptedSmallintOrdColumn, F as EncryptedSmallintOrdOreColumn, G as EncryptedTextColumn, H as EncryptedTextEqColumn, I as EncryptedTextMatchColumn, J as EncryptedTextOrdColumn, K as EncryptedTextOrdOreColumn, L as EncryptedTextSearchColumn, M as EncryptedTimestampColumn, N as EncryptedTimestampEqColumn, O as EncryptedTimestampOrdColumn, P as EncryptedTimestampOrdOreColumn, R as EncryptedV3TableColumn, S as EqlTypeForColumn, T as JsonDocument, U as JsonValue, W as QueryCapabilities, Y as TEXT_SEARCH_EQL_TYPE } from '../columns-rZc7fQHI.js';
+import { AnyV3Table, ColumnsOf, QueryableColumnsOf, V3ModelInput, V3EncryptedModel, V3DecryptedModel } from '../eql/v3/index.js';
+export { EncryptedTable, InferEncrypted, InferPlaintext, buildEncryptConfig, encryptedTable, types } from '../eql/v3/index.js';
+import { EncryptionError } from '../errors/index.js';
+import { LockContextInput } from '../identity/index.js';
+import { j as ClientConfig, x as EncryptedReturnType, S as ScalarQueryTerm, p as Encrypted, g as BulkEncryptPayload, n as EncryptOptions, e as BulkDecryptPayload } from '../types-public-QMjYNfQO.js';
+import { EncryptOperation, EncryptQueryOperation, BatchEncryptQueryOperation, EncryptModelOperation, BulkEncryptModelsOperation, DecryptOperation, BulkEncryptOperation, BulkDecryptOperation, EncryptionClient } from './index.js';
+import '@cipherstash/protect-ffi';
+import 'zod';
+import '../base-operation-FXEzUXIq.js';
+
+/**
+ * A strongly-typed view over an {@link EncryptionClient} for EQL v3 schemas.
+ *
+ * Every method derives its types from the concrete `table` / `column` builder
+ * arguments (which carry their branded types at the call site), so:
+ * - `encrypt` / `encryptQuery` pin the plaintext to the column's domain type
+ *   (`text → string`, `timestamp → Date`, …);
+ * - `encryptQuery` additionally constrains `queryType` to the column's
+ *   capabilities and rejects storage-only columns outright;
+ * - `encryptModel` / `bulkEncryptModels` validate schema-column fields against
+ *   their inferred plaintext type (passthrough fields are untouched) and return
+ *   a precise encrypted model;
+ * - `decryptModel` / `bulkDecryptModels` return the precise plaintext model,
+ *   reconstructing `Date` values from the encrypt-config `cast_as`.
+ *
+ * @typeParam S - the tuple of registered v3 tables; `table` arguments must be a
+ *   member of this tuple.
+ */
+interface TypedEncryptionClient<S extends readonly AnyV3Table[]> {
+    encrypt<Table extends S[number], Col extends ColumnsOf<Table>>(plaintext: PlaintextForColumn<Col>, opts: {
+        table: Table;
+        column: Col;
+    }): EncryptOperation;
+    encryptQuery<Table extends S[number], Col extends QueryableColumnsOf<Table>, QT extends QueryTypesForColumn<Col> = QueryTypesForColumn<Col>>(plaintext: PlaintextForColumn<Col>, opts: {
+        table: Table;
+        column: Col;
+        queryType?: QT;
+        returnType?: EncryptedReturnType;
+    }): EncryptQueryOperation;
+    /**
+     * Batch form: encrypt many query terms in one crossing. Mirrors the nominal
+     * {@link EncryptionClient} overload — the per-term columns are heterogeneous,
+     * so the terms are the base {@link ScalarQueryTerm} rather than a per-column
+     * narrowed type. Consumed by the Drizzle `inArray`/`notInArray` operators.
+     */
+    encryptQuery(terms: readonly ScalarQueryTerm[]): BatchEncryptQueryOperation;
+    encryptModel<Table extends S[number], T extends Record<string, unknown>>(input: V3ModelInput<Table, T>, table: Table): EncryptModelOperation<V3EncryptedModel<Table, T>>;
+    bulkEncryptModels<Table extends S[number], T extends Record<string, unknown>>(input: Array<V3ModelInput<Table, T>>, table: Table): BulkEncryptModelsOperation<V3EncryptedModel<Table, T>>;
+    /**
+     * Decrypt a single value. Cannot be strongly typed — a lone ciphertext carries
+     * no column identity — so it resolves to the FFI plaintext union unchanged.
+     */
+    decrypt(encrypted: Encrypted): DecryptOperation;
+    /**
+     * Decrypt a model, returning the precise plaintext shape for `table`. `Date`
+     * columns are reconstructed from the encrypt-config `cast_as`.
+     *
+     * Pass `lockContext` to decrypt identity-bound data — the same context that
+     * was supplied at encrypt time must be provided here.
+     *
+     * Unlike the encrypt operations this returns a plain `Promise<Result<…>>`
+     * rather than a chainable operation, because it maps the resolved value.
+     */
+    decryptModel<Table extends S[number], T extends Record<string, unknown>>(input: T, table: Table, lockContext?: LockContextInput): Promise<Result<V3DecryptedModel<Table, T>, EncryptionError>>;
+    bulkDecryptModels<Table extends S[number], T extends Record<string, unknown>>(input: Array<T>, table: Table, lockContext?: LockContextInput): Promise<Result<Array<V3DecryptedModel<Table, T>>, EncryptionError>>;
+    bulkEncrypt(plaintexts: BulkEncryptPayload, opts: EncryptOptions): BulkEncryptOperation;
+    bulkDecrypt(payloads: BulkDecryptPayload): BulkDecryptOperation;
+    getEncryptConfig(): ReturnType<EncryptionClient['getEncryptConfig']>;
+}
+/**
+ * Wrap an already-built {@link EncryptionClient} in a {@link TypedEncryptionClient}
+ * for the given v3 schemas. Zero runtime cost for the encrypt/query paths (the
+ * underlying operations are returned unchanged); the decrypt-model paths add a
+ * per-column `Date` reconstruction step.
+ *
+ * The `schemas` are captured with a `const` type parameter so array-literal
+ * widening does not collapse per-table inference.
+ */
+declare function typedClient<const S extends readonly AnyV3Table[]>(client: EncryptionClient, ...schemas: S): TypedEncryptionClient<S>;
+/**
+ * Build a {@link TypedEncryptionClient} for EQL v3 schemas — the strongly-typed
+ * counterpart to {@link Encryption}. Mirrors its config, then retypes the client
+ * against the provided v3 `schemas`.
+ *
+ * @example
+ * ```typescript
+ * import { EncryptionV3, encryptedTable, types } from "@cipherstash/stack/v3"
+ *
+ * const users = encryptedTable("users", { email: types.TextSearch("email") })
+ * const client = await EncryptionV3({ schemas: [users] })
+ *
+ * await client.encrypt("a@b.com", { table: users, column: users.email })
+ * ```
+ */
+declare function EncryptionV3<const S extends readonly AnyV3Table[]>(config: {
+    schemas: S;
+    config?: ClientConfig;
+}): Promise<TypedEncryptionClient<S>>;
+
+export { AnyV3Table, ColumnsOf, EncryptionV3, PlaintextForColumn, QueryTypesForColumn, QueryableColumnsOf, type TypedEncryptionClient, V3DecryptedModel, V3EncryptedModel, V3ModelInput, typedClient };

package/dist/encryption/v3.js

@@ -0,0 +1,189 @@
+import {
+  EncryptedTable,
+  buildEncryptConfig,
+  encryptedTable
+} from "../chunk-X3JRXEIB.js";
+import {
+  DATE_LIKE_CASTS,
+  EncryptedBigintColumn,
+  EncryptedBigintEqColumn,
+  EncryptedBigintOrdColumn,
+  EncryptedBigintOrdOreColumn,
+  EncryptedBooleanColumn,
+  EncryptedDateColumn,
+  EncryptedDateEqColumn,
+  EncryptedDateOrdColumn,
+  EncryptedDateOrdOreColumn,
+  EncryptedDoubleColumn,
+  EncryptedDoubleEqColumn,
+  EncryptedDoubleOrdColumn,
+  EncryptedDoubleOrdOreColumn,
+  EncryptedIntegerColumn,
+  EncryptedIntegerEqColumn,
+  EncryptedIntegerOrdColumn,
+  EncryptedIntegerOrdOreColumn,
+  EncryptedJsonColumn,
+  EncryptedNumericColumn,
+  EncryptedNumericEqColumn,
+  EncryptedNumericOrdColumn,
+  EncryptedNumericOrdOreColumn,
+  EncryptedRealColumn,
+  EncryptedRealEqColumn,
+  EncryptedRealOrdColumn,
+  EncryptedRealOrdOreColumn,
+  EncryptedSmallintColumn,
+  EncryptedSmallintEqColumn,
+  EncryptedSmallintOrdColumn,
+  EncryptedSmallintOrdOreColumn,
+  EncryptedTextColumn,
+  EncryptedTextEqColumn,
+  EncryptedTextMatchColumn,
+  EncryptedTextOrdColumn,
+  EncryptedTextOrdOreColumn,
+  EncryptedTextSearchColumn,
+  EncryptedTimestampColumn,
+  EncryptedTimestampEqColumn,
+  EncryptedTimestampOrdColumn,
+  EncryptedTimestampOrdOreColumn,
+  TEXT_SEARCH_EQL_TYPE,
+  types
+} from "../chunk-V2Q3NYIH.js";
+import {
+  Encryption
+} from "../chunk-ZTP5QJ27.js";
+import "../chunk-OFQ555AX.js";
+import "../chunk-BNO32ZMV.js";
+import "../chunk-CLM7E4I6.js";
+import "../chunk-7333ZC6L.js";
+import "../chunk-3B5ZX3IS.js";
+import "../chunk-JSG2AMDI.js";
+import "../chunk-HQANMV7R.js";
+import {
+  EncryptionErrorTypes
+} from "../chunk-LBMC4D6D.js";
+import "../chunk-PZ5AY32C.js";
+
+// src/encryption/v3.ts
+function rowReconstructor(table) {
+  const { columns } = table.build();
+  const propToDb = table.buildColumnKeyMap();
+  const dateProperties = Object.entries(propToDb).filter(([, dbName]) => {
+    const castAs = columns[dbName]?.cast_as;
+    return DATE_LIKE_CASTS.includes(castAs);
+  }).map(([property]) => property);
+  return (row) => {
+    const out = { ...row };
+    for (const property of dateProperties) {
+      const value = out[property];
+      if (value == null) continue;
+      out[property] = new Date(value);
+    }
+    return out;
+  };
+}
+function typedClient(client, ...schemas) {
+  const reconstructors = /* @__PURE__ */ new Map();
+  for (const table of schemas) {
+    reconstructors.set(table.tableName, rowReconstructor(table));
+  }
+  const unknownTableFailure = {
+    failure: {
+      type: EncryptionErrorTypes.DecryptionError,
+      message: "[eql/v3]: decryptModel received a table this client was not initialized with \u2014 pass a table given to EncryptionV3/typedClient"
+    }
+  };
+  function encryptQuery(plaintextOrTerms, opts) {
+    return client.encryptQuery(plaintextOrTerms, opts);
+  }
+  return {
+    encrypt: (plaintext, opts) => client.encrypt(plaintext, opts),
+    encryptQuery,
+    encryptModel: (input, table) => client.encryptModel(input, table),
+    bulkEncryptModels: (input, table) => client.bulkEncryptModels(input, table),
+    decrypt: (encrypted) => client.decrypt(encrypted),
+    decryptModel: async (input, table, lockContext) => {
+      const reconstruct = reconstructors.get(table.tableName);
+      if (!reconstruct) return unknownTableFailure;
+      const op = client.decryptModel(input);
+      const result = await (lockContext ? op.withLockContext(lockContext) : op);
+      if (result.failure) return result;
+      return { data: reconstruct(result.data) };
+    },
+    bulkDecryptModels: async (input, table, lockContext) => {
+      const reconstruct = reconstructors.get(table.tableName);
+      if (!reconstruct) return unknownTableFailure;
+      const op = client.bulkDecryptModels(input);
+      const result = await (lockContext ? op.withLockContext(lockContext) : op);
+      if (result.failure) return result;
+      return {
+        data: result.data.map(
+          (row) => reconstruct(row)
+        )
+      };
+    },
+    bulkEncrypt: (plaintexts, opts) => client.bulkEncrypt(plaintexts, opts),
+    bulkDecrypt: (payloads) => client.bulkDecrypt(payloads),
+    getEncryptConfig: () => client.getEncryptConfig()
+  };
+}
+async function EncryptionV3(config) {
+  const client = await Encryption({
+    schemas: config.schemas,
+    // Force the v3 EQL wire format. protect-ffi's newClient defaults to
+    // eqlVersion 2; a v2-mode client cannot resolve v3 concrete-type columns
+    // and fails every encrypt with "Cannot convert undefined or null to
+    // object". This is a v3-only invariant, so it overrides any user value.
+    config: { ...config.config, eqlVersion: 3 }
+  });
+  return typedClient(client, ...config.schemas);
+}
+export {
+  EncryptedBigintColumn,
+  EncryptedBigintEqColumn,
+  EncryptedBigintOrdColumn,
+  EncryptedBigintOrdOreColumn,
+  EncryptedBooleanColumn,
+  EncryptedDateColumn,
+  EncryptedDateEqColumn,
+  EncryptedDateOrdColumn,
+  EncryptedDateOrdOreColumn,
+  EncryptedDoubleColumn,
+  EncryptedDoubleEqColumn,
+  EncryptedDoubleOrdColumn,
+  EncryptedDoubleOrdOreColumn,
+  EncryptedIntegerColumn,
+  EncryptedIntegerEqColumn,
+  EncryptedIntegerOrdColumn,
+  EncryptedIntegerOrdOreColumn,
+  EncryptedJsonColumn,
+  EncryptedNumericColumn,
+  EncryptedNumericEqColumn,
+  EncryptedNumericOrdColumn,
+  EncryptedNumericOrdOreColumn,
+  EncryptedRealColumn,
+  EncryptedRealEqColumn,
+  EncryptedRealOrdColumn,
+  EncryptedRealOrdOreColumn,
+  EncryptedSmallintColumn,
+  EncryptedSmallintEqColumn,
+  EncryptedSmallintOrdColumn,
+  EncryptedSmallintOrdOreColumn,
+  EncryptedTable,
+  EncryptedTextColumn,
+  EncryptedTextEqColumn,
+  EncryptedTextMatchColumn,
+  EncryptedTextOrdColumn,
+  EncryptedTextOrdOreColumn,
+  EncryptedTextSearchColumn,
+  EncryptedTimestampColumn,
+  EncryptedTimestampEqColumn,
+  EncryptedTimestampOrdColumn,
+  EncryptedTimestampOrdOreColumn,
+  EncryptionV3,
+  TEXT_SEARCH_EQL_TYPE,
+  buildEncryptConfig,
+  encryptedTable,
+  typedClient,
+  types
+};
+//# sourceMappingURL=v3.js.map

package/dist/encryption/v3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/encryption/v3.ts"],"sourcesContent":["import type { Result } from '@byteslice/result'\nimport type {\n  AnyV3Table,\n  ColumnsOf,\n  PlaintextForColumn,\n  QueryableColumnsOf,\n  QueryTypesForColumn,\n  V3DecryptedModel,\n  V3EncryptedModel,\n  V3ModelInput,\n} from '@/eql/v3'\nimport { DATE_LIKE_CASTS } from '@/eql/v3/columns'\nimport { type EncryptionError, EncryptionErrorTypes } from '@/errors'\nimport type { LockContextInput } from '@/identity'\nimport type {\n  BulkDecryptPayload,\n  BulkEncryptPayload,\n  ClientConfig,\n  Encrypted,\n  EncryptedReturnType,\n  EncryptOptions,\n  ScalarQueryTerm,\n} from '@/types'\nimport {\n  type BatchEncryptQueryOperation,\n  type BulkDecryptOperation,\n  type BulkEncryptModelsOperation,\n  type BulkEncryptOperation,\n  type DecryptOperation,\n  Encryption,\n  type EncryptionClient,\n  type EncryptModelOperation,\n  type EncryptOperation,\n  type EncryptQueryOperation,\n} from './index'\n\n/**\n * A strongly-typed view over an {@link EncryptionClient} for EQL v3 schemas.\n *\n * Every method derives its types from the concrete `table` / `column` builder\n * arguments (which carry their branded types at the call site), so:\n * - `encrypt` / `encryptQuery` pin the plaintext to the column's domain type\n *   (`text → string`, `timestamp → Date`, …);\n * - `encryptQuery` additionally constrains `queryType` to the column's\n *   capabilities and rejects storage-only columns outright;\n * - `encryptModel` / `bulkEncryptModels` validate schema-column fields against\n *   their inferred plaintext type (passthrough fields are untouched) and return\n *   a precise encrypted model;\n * - `decryptModel` / `bulkDecryptModels` return the precise plaintext model,\n *   reconstructing `Date` values from the encrypt-config `cast_as`.\n *\n * @typeParam S - the tuple of registered v3 tables; `table` arguments must be a\n *   member of this tuple.\n */\nexport interface TypedEncryptionClient<S extends readonly AnyV3Table[]> {\n  encrypt<Table extends S[number], Col extends ColumnsOf<Table>>(\n    plaintext: PlaintextForColumn<Col>,\n    opts: { table: Table; column: Col },\n  ): EncryptOperation\n\n  encryptQuery<\n    Table extends S[number],\n    Col extends QueryableColumnsOf<Table>,\n    QT extends QueryTypesForColumn<Col> = QueryTypesForColumn<Col>,\n  >(\n    plaintext: PlaintextForColumn<Col>,\n    opts: {\n      table: Table\n      column: Col\n      queryType?: QT\n      returnType?: EncryptedReturnType\n    },\n  ): EncryptQueryOperation\n\n  /**\n   * Batch form: encrypt many query terms in one crossing. Mirrors the nominal\n   * {@link EncryptionClient} overload — the per-term columns are heterogeneous,\n   * so the terms are the base {@link ScalarQueryTerm} rather than a per-column\n   * narrowed type. Consumed by the Drizzle `inArray`/`notInArray` operators.\n   */\n  encryptQuery(terms: readonly ScalarQueryTerm[]): BatchEncryptQueryOperation\n\n  encryptModel<Table extends S[number], T extends Record<string, unknown>>(\n    input: V3ModelInput<Table, T>,\n    table: Table,\n  ): EncryptModelOperation<V3EncryptedModel<Table, T>>\n\n  bulkEncryptModels<Table extends S[number], T extends Record<string, unknown>>(\n    input: Array<V3ModelInput<Table, T>>,\n    table: Table,\n  ): BulkEncryptModelsOperation<V3EncryptedModel<Table, T>>\n\n  /**\n   * Decrypt a single value. Cannot be strongly typed — a lone ciphertext carries\n   * no column identity — so it resolves to the FFI plaintext union unchanged.\n   */\n  decrypt(encrypted: Encrypted): DecryptOperation\n\n  /**\n   * Decrypt a model, returning the precise plaintext shape for `table`. `Date`\n   * columns are reconstructed from the encrypt-config `cast_as`.\n   *\n   * Pass `lockContext` to decrypt identity-bound data — the same context that\n   * was supplied at encrypt time must be provided here.\n   *\n   * Unlike the encrypt operations this returns a plain `Promise<Result<…>>`\n   * rather than a chainable operation, because it maps the resolved value.\n   */\n  decryptModel<Table extends S[number], T extends Record<string, unknown>>(\n    input: T,\n    table: Table,\n    lockContext?: LockContextInput,\n  ): Promise<Result<V3DecryptedModel<Table, T>, EncryptionError>>\n\n  bulkDecryptModels<Table extends S[number], T extends Record<string, unknown>>(\n    input: Array<T>,\n    table: Table,\n    lockContext?: LockContextInput,\n  ): Promise<Result<Array<V3DecryptedModel<Table, T>>, EncryptionError>>\n\n  // Parity passthroughs — not v3-strengthened, delegated as-is.\n  bulkEncrypt(\n    plaintexts: BulkEncryptPayload,\n    opts: EncryptOptions,\n  ): BulkEncryptOperation\n  bulkDecrypt(payloads: BulkDecryptPayload): BulkDecryptOperation\n  getEncryptConfig(): ReturnType<EncryptionClient['getEncryptConfig']>\n}\n\n/**\n * Build a per-row reconstructor of `Date` values from the table's\n * encrypt-config `cast_as`. The FFI returns `JsPlaintext`\n * (string/number/boolean/…) with no `Date`, so those columns arrive as their\n * serialized form and are rebuilt here. Safe (idempotent) if the FFI ever\n * returns `Date` directly: `new Date(date)` is a no-op.\n *\n * A factory rather than a `(row, table)` function so the table config —\n * row-invariant, but non-trivial to build — is derived once per call site,\n * not once per row on the bulk path.\n *\n * NOTE: only date-like casts need per-row reconstruction. `bigint` (int8)\n * needs none — protect-ffi 0.28 returns a native JS `bigint` on decrypt\n * (and bounds-checks/encodes it on encrypt), so those columns pass through\n * unchanged, exactly like `string`/`number`/`boolean`.\n */\nfunction rowReconstructor(\n  table: AnyV3Table,\n): (row: Record<string, unknown>) => Record<string, unknown> {\n  // The decrypted row is keyed by JS property name, but `cast_as` lives on the\n  // config keyed by DB name — bridge the two via the table's property→DB map.\n  const { columns } = table.build()\n  const propToDb = table.buildColumnKeyMap()\n  // Only date-like columns need per-row work; resolve them up front.\n  const dateProperties = Object.entries(propToDb)\n    .filter(([, dbName]) => {\n      const castAs = columns[dbName]?.cast_as\n      // Date-like casts share one source of truth with the type-level\n      // reconstruction (`PlaintextFromKind`) — see `DATE_LIKE_CASTS`.\n      return (DATE_LIKE_CASTS as readonly string[]).includes(castAs as string)\n    })\n    .map(([property]) => property)\n\n  return (row) => {\n    const out: Record<string, unknown> = { ...row }\n    for (const property of dateProperties) {\n      const value = out[property]\n      if (value == null) continue\n      out[property] = new Date(value as string | number | Date)\n    }\n    return out\n  }\n}\n\n/**\n * Wrap an already-built {@link EncryptionClient} in a {@link TypedEncryptionClient}\n * for the given v3 schemas. Zero runtime cost for the encrypt/query paths (the\n * underlying operations are returned unchanged); the decrypt-model paths add a\n * per-column `Date` reconstruction step.\n *\n * The `schemas` are captured with a `const` type parameter so array-literal\n * widening does not collapse per-table inference.\n */\nexport function typedClient<const S extends readonly AnyV3Table[]>(\n  client: EncryptionClient,\n  ...schemas: S\n): TypedEncryptionClient<S> {\n  // Precompute one row reconstructor per schema table at construction. This runs\n  // each table's `build()` — which throws on duplicate DB column names — ONCE,\n  // here, off the Result-returning decrypt path. `decryptModel`/\n  // `bulkDecryptModels` therefore never call `build()` (whose throw would surface\n  // as a promise rejection and break their `Promise<Result<…>>` contract) and no\n  // longer rebuild the row-invariant config on every call.\n  // Keyed by `tableName`, not table object identity: `AnyV3Table` is\n  // structurally typed, so a table re-imported from another module (or rebuilt\n  // after an HMR reload) satisfies `Table extends S[number]` yet is a different\n  // object. Identity keying would fail those valid calls. `tableName` is the\n  // semantic identity the FFI encrypt config and `build()` already key on.\n  const reconstructors = new Map<\n    string,\n    (row: Record<string, unknown>) => Record<string, unknown>\n  >()\n  for (const table of schemas) {\n    reconstructors.set(table.tableName, rowReconstructor(table))\n  }\n\n  // A table not among the schemas this client was initialized with has no\n  // precomputed reconstructor. Return a Result failure rather than building one\n  // inline, which could throw and reject the Result-shaped decrypt promise.\n  const unknownTableFailure: { failure: EncryptionError } = {\n    failure: {\n      type: EncryptionErrorTypes.DecryptionError,\n      message:\n        '[eql/v3]: decryptModel received a table this client was not initialized with — pass a table given to EncryptionV3/typedClient',\n    },\n  }\n\n  // Overloaded so the implementation is checked against BOTH forms directly —\n  // no whole-value cast. The two public signatures mirror the interface member;\n  // the hidden implementation signature is broad and forwards to the nominal\n  // client (which routes to the batch operation when no `opts` are supplied).\n  // Only the forwarded args are `as never`, exactly as the sibling wrappers\n  // below: one forwarding body cannot re-derive the nominal client's per-column\n  // signatures.\n  function encryptQuery<\n    Table extends S[number],\n    Col extends QueryableColumnsOf<Table>,\n    QT extends QueryTypesForColumn<Col> = QueryTypesForColumn<Col>,\n  >(\n    plaintext: PlaintextForColumn<Col>,\n    opts: {\n      table: Table\n      column: Col\n      queryType?: QT\n      returnType?: EncryptedReturnType\n    },\n  ): EncryptQueryOperation\n  function encryptQuery(\n    terms: readonly ScalarQueryTerm[],\n  ): BatchEncryptQueryOperation\n  function encryptQuery(\n    plaintextOrTerms: unknown,\n    opts?: unknown,\n  ): EncryptQueryOperation | BatchEncryptQueryOperation {\n    return client.encryptQuery(plaintextOrTerms as never, opts as never)\n  }\n\n  return {\n    encrypt: (plaintext, opts) =>\n      client.encrypt(plaintext as never, opts as never),\n    encryptQuery,\n    encryptModel: (input, table) =>\n      client.encryptModel(input as never, table as never) as never,\n    bulkEncryptModels: (input, table) =>\n      client.bulkEncryptModels(input as never, table as never) as never,\n    decrypt: (encrypted) => client.decrypt(encrypted),\n    decryptModel: async (input, table, lockContext) => {\n      const reconstruct = reconstructors.get(table.tableName)\n      if (!reconstruct) return unknownTableFailure as never\n      const op = client.decryptModel(input as never)\n      const result = await (lockContext ? op.withLockContext(lockContext) : op)\n      if (result.failure) return result as never\n      return { data: reconstruct(result.data) } as never\n    },\n    bulkDecryptModels: async (input, table, lockContext) => {\n      const reconstruct = reconstructors.get(table.tableName)\n      if (!reconstruct) return unknownTableFailure as never\n      const op = client.bulkDecryptModels(input as never)\n      const result = await (lockContext ? op.withLockContext(lockContext) : op)\n      if (result.failure) return result as never\n      return {\n        data: result.data.map((row) =>\n          reconstruct(row as Record<string, unknown>),\n        ),\n      } as never\n    },\n    bulkEncrypt: (plaintexts, opts) => client.bulkEncrypt(plaintexts, opts),\n    bulkDecrypt: (payloads) => client.bulkDecrypt(payloads),\n    getEncryptConfig: () => client.getEncryptConfig(),\n  } satisfies TypedEncryptionClient<S>\n}\n\n/**\n * Build a {@link TypedEncryptionClient} for EQL v3 schemas — the strongly-typed\n * counterpart to {@link Encryption}. Mirrors its config, then retypes the client\n * against the provided v3 `schemas`.\n *\n * @example\n * ```typescript\n * import { EncryptionV3, encryptedTable, types } from \"@cipherstash/stack/v3\"\n *\n * const users = encryptedTable(\"users\", { email: types.TextSearch(\"email\") })\n * const client = await EncryptionV3({ schemas: [users] })\n *\n * await client.encrypt(\"a@b.com\", { table: users, column: users.email })\n * ```\n */\nexport async function EncryptionV3<\n  const S extends readonly AnyV3Table[],\n>(config: {\n  schemas: S\n  config?: ClientConfig\n}): Promise<TypedEncryptionClient<S>> {\n  const client = await Encryption({\n    schemas: config.schemas as unknown as Parameters<\n      typeof Encryption\n    >[0]['schemas'],\n    // Force the v3 EQL wire format. protect-ffi's newClient defaults to\n    // eqlVersion 2; a v2-mode client cannot resolve v3 concrete-type columns\n    // and fails every encrypt with \"Cannot convert undefined or null to\n    // object\". This is a v3-only invariant, so it overrides any user value.\n    config: { ...config.config, eqlVersion: 3 },\n  })\n  return typedClient(client, ...config.schemas)\n}\n\n// Single import surface: re-export the v3 `types` namespace + table API + type\n// helpers so `@cipherstash/stack/v3` provides everything needed to author and\n// use a schema.\nexport * from '@/eql/v3'\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiJA,SAAS,iBACP,OAC2D;AAG3D,QAAM,EAAE,QAAQ,IAAI,MAAM,MAAM;AAChC,QAAM,WAAW,MAAM,kBAAkB;AAEzC,QAAM,iBAAiB,OAAO,QAAQ,QAAQ,EAC3C,OAAO,CAAC,CAAC,EAAE,MAAM,MAAM;AACtB,UAAM,SAAS,QAAQ,MAAM,GAAG;AAGhC,WAAQ,gBAAsC,SAAS,MAAgB;AAAA,EACzE,CAAC,EACA,IAAI,CAAC,CAAC,QAAQ,MAAM,QAAQ;AAE/B,SAAO,CAAC,QAAQ;AACd,UAAM,MAA+B,EAAE,GAAG,IAAI;AAC9C,eAAW,YAAY,gBAAgB;AACrC,YAAM,QAAQ,IAAI,QAAQ;AAC1B,UAAI,SAAS,KAAM;AACnB,UAAI,QAAQ,IAAI,IAAI,KAAK,KAA+B;AAAA,IAC1D;AACA,WAAO;AAAA,EACT;AACF;AAWO,SAAS,YACd,WACG,SACuB;AAY1B,QAAM,iBAAiB,oBAAI,IAGzB;AACF,aAAW,SAAS,SAAS;AAC3B,mBAAe,IAAI,MAAM,WAAW,iBAAiB,KAAK,CAAC;AAAA,EAC7D;AAKA,QAAM,sBAAoD;AAAA,IACxD,SAAS;AAAA,MACP,MAAM,qBAAqB;AAAA,MAC3B,SACE;AAAA,IACJ;AAAA,EACF;AAyBA,WAAS,aACP,kBACA,MACoD;AACpD,WAAO,OAAO,aAAa,kBAA2B,IAAa;AAAA,EACrE;AAEA,SAAO;AAAA,IACL,SAAS,CAAC,WAAW,SACnB,OAAO,QAAQ,WAAoB,IAAa;AAAA,IAClD;AAAA,IACA,cAAc,CAAC,OAAO,UACpB,OAAO,aAAa,OAAgB,KAAc;AAAA,IACpD,mBAAmB,CAAC,OAAO,UACzB,OAAO,kBAAkB,OAAgB,KAAc;AAAA,IACzD,SAAS,CAAC,cAAc,OAAO,QAAQ,SAAS;AAAA,IAChD,cAAc,OAAO,OAAO,OAAO,gBAAgB;AACjD,YAAM,cAAc,eAAe,IAAI,MAAM,SAAS;AACtD,UAAI,CAAC,YAAa,QAAO;AACzB,YAAM,KAAK,OAAO,aAAa,KAAc;AAC7C,YAAM,SAAS,OAAO,cAAc,GAAG,gBAAgB,WAAW,IAAI;AACtE,UAAI,OAAO,QAAS,QAAO;AAC3B,aAAO,EAAE,MAAM,YAAY,OAAO,IAAI,EAAE;AAAA,IAC1C;AAAA,IACA,mBAAmB,OAAO,OAAO,OAAO,gBAAgB;AACtD,YAAM,cAAc,eAAe,IAAI,MAAM,SAAS;AACtD,UAAI,CAAC,YAAa,QAAO;AACzB,YAAM,KAAK,OAAO,kBAAkB,KAAc;AAClD,YAAM,SAAS,OAAO,cAAc,GAAG,gBAAgB,WAAW,IAAI;AACtE,UAAI,OAAO,QAAS,QAAO;AAC3B,aAAO;AAAA,QACL,MAAM,OAAO,KAAK;AAAA,UAAI,CAAC,QACrB,YAAY,GAA8B;AAAA,QAC5C;AAAA,MACF;AAAA,IACF;AAAA,IACA,aAAa,CAAC,YAAY,SAAS,OAAO,YAAY,YAAY,IAAI;AAAA,IACtE,aAAa,CAAC,aAAa,OAAO,YAAY,QAAQ;AAAA,IACtD,kBAAkB,MAAM,OAAO,iBAAiB;AAAA,EAClD;AACF;AAiBA,eAAsB,aAEpB,QAGoC;AACpC,QAAM,SAAS,MAAM,WAAW;AAAA,IAC9B,SAAS,OAAO;AAAA;AAAA;AAAA;AAAA;AAAA,IAOhB,QAAQ,EAAE,GAAG,OAAO,QAAQ,YAAY,EAAE;AAAA,EAC5C,CAAC;AACD,SAAO,YAAY,QAAQ,GAAG,OAAO,OAAO;AAC9C;","names":[]}