types-public is a module in @cipherstash/stack. TypeScript API reference with its signature, parameters, and usage.

types-public

Structural type representing an encrypted query term (search needle) returned by encryptQuery / encryptQueryBulk for scalar (unique / match / ore) lookups and SteVec JSON selector, value-selector, ordering, and eql_v3.query_json containment queries. Carries no ciphertext — matched against stored values, never decrypted.

KeysetIdentifier

type KeysetIdentifier = 
  | {
  name: string;
}
  | {
  id: string;
};

Defined in: types.ts:98

Public type re-exports for @cipherstash/stack/types.

This module exposes only the public types from the internal types module. Internal helpers (queryTypeToFfi, queryTypeToQueryOp, FfiIndexTypeName, QueryTermBase) are excluded.

ClientConfig

type ClientConfig = {
  workspaceCrn?: string;
  accessKey?: string;
  clientId?: string;
  clientKey?: string;
  keyset?: KeysetIdentifier;
  authStrategy?: AuthStrategy;
  strategy?: AuthStrategy;
  eqlVersion?: never;
};

Defined in: types.ts:100

Public type re-exports for @cipherstash/stack/types.

This module exposes only the public types from the internal types module. Internal helpers (queryTypeToFfi, queryTypeToQueryOp, FfiIndexTypeName, QueryTermBase) are excluded.

Properties

workspaceCrn?

optional workspaceCrn: string;

Defined in: types.ts:106

The CipherStash workspace CRN (Cloud Resource Name). Format: crn:<region>.aws:<workspace-id>. Can also be set via the CS_WORKSPACE_CRN environment variable.

accessKey?

optional accessKey: string;

Defined in: types.ts:113

The API access key used for authenticating with the CipherStash API. Can also be set via the CS_CLIENT_ACCESS_KEY environment variable. Obtain this from the CipherStash dashboard after creating a workspace.

clientId?

optional clientId: string;

Defined in: types.ts:120

The client identifier used to authenticate with CipherStash services. Can also be set via the CS_CLIENT_ID environment variable. Generated during workspace onboarding in the CipherStash dashboard.

clientKey?

optional clientKey: string;

Defined in: types.ts:127

The client key material used in combination with ZeroKMS for encryption operations. Can also be set via the CS_CLIENT_KEY environment variable. Generated during workspace onboarding in the CipherStash dashboard.

keyset?

optional keyset: KeysetIdentifier;

Defined in: types.ts:144

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 dashboard; omit to use the default keyset of the ZeroKMS client behind your credentials — the keyset it was created against, which is the workspace's default keyset if using the profile credentials in a dev environment. A client is bound to one keyset for its lifetime — encrypt and query always use it, while decrypt follows each payload's own keyset (subject to grants) — so use one client per tenant.

See

Encryption for the full keysets walkthrough.

authStrategy?

optional authStrategy: AuthStrategy;

Defined in: types.ts:168

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

AuthStrategy
Encryption for a full walkthrough of the authentication options.

strategy?

optional strategy: AuthStrategy;

Defined in: types.ts:175

Deprecated

Renamed to 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.

eqlVersion?

optional eqlVersion: never;

Defined in: types.ts:196

Removed: Stack always authors EQL v3. Declared as never rather than omitted so the type rejects it wherever it appears — every other property here is optional, so excess-property checking was the only thing catching a leftover eqlVersion, and that fires on FRESH object literals alone. A shared config const (const cfg = { …, eqlVersion: 2 }) — the shape a v2 → v3 migration most plausibly has — therefore type-checked clean and threw at Encryption().

Encryption keeps its runtime guard: JS and JSON callers bypass types entirely, so this is defence in depth, not a replacement for it.

One asymmetry the guard has to account for: without exactOptionalPropertyTypes — which this repo does not enable — ?: never has declared type undefined, so eqlVersion: undefined is accepted here and no declaration can reject it. The runtime therefore tolerates exactly that value (it names no version) while still rejecting every real one, eqlVersion: 3 included.

EncryptionClientConfig

type EncryptionClientConfig&lt;S&gt; = {
  schemas: S["length"] extends 0 ? never : S;
  config?: ClientConfig;
};

Defined in: types.ts:279

The Encryption({ schemas, config }) argument, as a named type.

The default MUST be a non-empty tuple, not readonly AnyV3Table[]: with the widened default, S['length'] resolves to number, number extends 0 is false, and the conditional hands back the widened array — so const cfg: EncryptionClientConfig = { schemas: [] } typechecked clean and threw at Encryption(). Excess-property checking only catches the FRESH literal Encryption({ schemas: [] }); a config object built once and passed around, which is exactly what this type exists to serve, slipped through.

The conditional stays for an explicit EncryptionClientConfig<[]>, and the type parameter stays so a caller can pin their own schema tuple. The factory keeps accepting widened arrays inline through its overloads — that is a separate concern from what this exported type can prove.

Mirrors WasmEncryptionConfig on the wasm-inline entry.

Type Parameters

S

S extends readonly AnyV3Table[] = readonly [AnyV3Table, ...AnyV3Table[]]

Properties

schemas

schemas: S["length"] extends 0 ? never : S;

Defined in: types.ts:282

config?

optional config: ClientConfig;

Defined in: types.ts:283

EncryptOptions

type EncryptOptions = {
  column: BuildableColumn;
  table: BuildableTable;
};

Defined in: types.ts:335

Options for single-value encrypt operations. Use a column from your table schema (from encryptedColumn) or a nested field (from encryptedField) as the target for encryption.

Properties

column

column: BuildableColumn;

Defined in: types.ts:337

The column or nested field to encrypt into. From EncryptedColumn or EncryptedField.

table

table: BuildableTable;

Defined in: types.ts:338

EncryptedReturnType

type EncryptedReturnType = "eql" | "composite-literal" | "escaped-composite-literal";

Defined in: types.ts:342

Format for encrypted query/search term return values

EncryptedSearchTerm

type EncryptedSearchTerm = 
  | Encrypted
  | EncryptedQuery
  | string;

Defined in: types.ts:357

Encrypted search term result. eql returns the query-only scalar or SteVec term; the composite-literal return types yield a string. The Encrypted arm remains for legacy v2 scalar query compatibility.

EncryptedQueryResult

type EncryptedQueryResult = 
  | Encrypted
  | EncryptedQuery
  | string
  | null;

Defined in: types.ts:365

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.

EncryptedFields

type EncryptedFields&lt;T&gt; = { [K in keyof T as NonNullable&lt;T[K]&gt; extends Encrypted ? K : never]: T[K] };

Defined in: types.ts:371

Public type re-exports for @cipherstash/stack/types.

This module exposes only the public types from the internal types module. Internal helpers (queryTypeToFfi, queryTypeToQueryOp, FfiIndexTypeName, QueryTermBase) are excluded.

Type Parameters

T

T

OtherFields

type OtherFields&lt;T&gt; = { [K in keyof T as NonNullable&lt;T[K]&gt; extends Encrypted ? never : K]: T[K] };

Defined in: types.ts:375

Public type re-exports for @cipherstash/stack/types.

This module exposes only the public types from the internal types module. Internal helpers (queryTypeToFfi, queryTypeToQueryOp, FfiIndexTypeName, QueryTermBase) are excluded.

Type Parameters

T

T

DecryptedFields

type DecryptedFields&lt;T&gt; = { [K in keyof T as NonNullable&lt;T[K]&gt; extends Encrypted ? K : never]: null extends T[K] ? string | null : string };

Defined in: types.ts:379

Public type re-exports for @cipherstash/stack/types.

This module exposes only the public types from the internal types module. Internal helpers (queryTypeToFfi, queryTypeToQueryOp, FfiIndexTypeName, QueryTermBase) are excluded.

Type Parameters

T

T

Decrypted

type Decrypted&lt;T&gt; = OtherFields&lt;T&gt; & DecryptedFields&lt;T&gt;;

Defined in: types.ts:386

Model with encrypted fields replaced by plaintext (decrypted) values

Type Parameters

T

T

BulkEncryptPayload

type BulkEncryptPayload = {
  id?: string;
  plaintext: Plaintext | null;
}[];

Defined in: types.ts:428

Public type re-exports for @cipherstash/stack/types.

This module exposes only the public types from the internal types module. Internal helpers (queryTypeToFfi, queryTypeToQueryOp, FfiIndexTypeName, QueryTermBase) are excluded.

Type Declaration

id?

optional id: string;

plaintext

plaintext: Plaintext | null;

BulkEncryptedData

type BulkEncryptedData = {
  id?: string;
  data:   | Encrypted
     | null;
}[];

Defined in: types.ts:433

Public type re-exports for @cipherstash/stack/types.

This module exposes only the public types from the internal types module. Internal helpers (queryTypeToFfi, queryTypeToQueryOp, FfiIndexTypeName, QueryTermBase) are excluded.

Type Declaration

id?

optional id: string;

data

data: 
  | Encrypted
  | null;

BulkDecryptPayload

type BulkDecryptPayload = {
  id?: string;
  data:   | Encrypted
     | null;
}[];

Defined in: types.ts:434

Public type re-exports for @cipherstash/stack/types.

This module exposes only the public types from the internal types module. Internal helpers (queryTypeToFfi, queryTypeToQueryOp, FfiIndexTypeName, QueryTermBase) are excluded.

Type Declaration

id?

optional id: string;

data

data: 
  | Encrypted
  | null;

BulkDecryptedData

type BulkDecryptedData = DecryptionResult&lt;JsPlaintext | null&gt;[];

Defined in: types.ts:435

Public type re-exports for @cipherstash/stack/types.

This module exposes only the public types from the internal types module. Internal helpers (queryTypeToFfi, queryTypeToQueryOp, FfiIndexTypeName, QueryTermBase) are excluded.

DecryptionResult

type DecryptionResult&lt;T&gt; = DecryptionSuccess&lt;T&gt; | DecryptionError&lt;T&gt;;

Defined in: types.ts:445

Result type for individual items in bulk decrypt operations. Uses error/data fields (not failure/data) since bulk operations can have per-item failures.

Type Parameters

T

T

QueryTypeName

type QueryTypeName = 
  | "orderAndRange"
  | "freeTextSearch"
  | "equality"
  | "steVecSelector"
  | "steVecValueSelector"
  | "steVecTerm"
  | "searchableJson";

Defined in: types.ts:462

User-facing query type names for encrypting query values.

'equality': Exact match. Exact Queries
'freeTextSearch': Text search. Match Queries
'orderAndRange': Comparison and range. Range Queries
'steVecSelector': JSONPath selector (e.g. '$.user.email')
'steVecValueSelector': Exact value at a JSONPath ({ path, value })
'steVecTerm': Ordering term for a scalar JSON value
'searchableJson': Auto-infers selector or containment from plaintext type (recommended)

EncryptQueryOptions

type EncryptQueryOptions = QueryTermBase;

Defined in: types.ts:512

Public type re-exports for @cipherstash/stack/types.

This module exposes only the public types from the internal types module. Internal helpers (queryTypeToFfi, queryTypeToQueryOp, FfiIndexTypeName, QueryTermBase) are excluded.

ScalarQueryTerm

type ScalarQueryTerm = QueryTermBase & {
  value: Plaintext;
};

Defined in: types.ts:514

Public type re-exports for @cipherstash/stack/types.

This module exposes only the public types from the internal types module. Internal helpers (queryTypeToFfi, queryTypeToQueryOp, FfiIndexTypeName, QueryTermBase) are excluded.

Type Declaration

value

value: Plaintext;

Variables

queryTypes

const queryTypes: {
  orderAndRange: "orderAndRange";
  freeTextSearch: "freeTextSearch";
  equality: "equality";
  steVecSelector: "steVecSelector";
  steVecValueSelector: "steVecValueSelector";
  steVecTerm: "steVecTerm";
  searchableJson: "searchableJson";
};

Defined in: types.ts:474

Type Declaration

orderAndRange

readonly orderAndRange: "orderAndRange" = 'orderAndRange';

freeTextSearch

readonly freeTextSearch: "freeTextSearch" = 'freeTextSearch';

equality

readonly equality: "equality" = 'equality';

steVecSelector

readonly steVecSelector: "steVecSelector" = 'steVecSelector';

steVecValueSelector

readonly steVecValueSelector: "steVecValueSelector" = 'steVecValueSelector';

steVecTerm

readonly steVecTerm: "steVecTerm" = 'steVecTerm';

searchableJson

readonly searchableJson: "searchableJson" = 'searchableJson';

References

Encrypted

Re-exports Encrypted

types-public

On this page