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

DynamoDBOperation<Decrypted<T>[]>

Type Parameters

T

T extends Record<string, unknown>

Constructors

Constructor

new BulkDecryptModelsOperation&lt;T&gt;(
   encryptionClient, 
   items, 
   table, 
   readOptions?, 
   options?): BulkDecryptModelsOperation&lt;T&gt;;

Defined in: dynamodb/operations/bulk-decrypt-models.ts:32

Overrides

DynamoDBOperation&lt;Decrypted&lt;T&gt;[]>.constructor

Methods

audit()

audit(config): this;

Defined in: dynamodb/operations/base-operation.ts:32

Attach audit metadata to this operation. Can be chained.

Inherited from

DynamoDBOperation.audit

then()

then&lt;TResult1, TResult2&gt;(onfulfilled?, onrejected?): Promise&lt;TResult1 | TResult2&gt;;

Defined in: dynamodb/operations/base-operation.ts:54

Make the operation thenable

TResult1

TResult1 = Result<Decrypted<T>[], EncryptedDynamoDBError>

onfulfilled?

(value) => TResult1 | PromiseLike<TResult1> | null

onrejected?

(reason) => TResult2 | PromiseLike<TResult2> | null

Inherited from

DynamoDBOperation.then

execute()

execute(): Promise&lt;Result&lt;Decrypted&lt;T&gt;[], EncryptedDynamoDBError>>;

Defined in: dynamodb/operations/bulk-decrypt-models.ts:46

Execute the operation and return a Result

Returns

Promise<Result<Decrypted<T>[], EncryptedDynamoDBError>>

Overrides

DynamoDBOperation.execute

BulkEncryptModelsOperation

Defined in: dynamodb/operations/bulk-encrypt-models.ts:22

Type Parameters

T

T extends Record<string, unknown>

Constructors

Constructor

new BulkEncryptModelsOperation&lt;T&gt;(
   encryptionClient, 
   items, 
   table, 
   options?): BulkEncryptModelsOperation&lt;T&gt;;

Defined in: dynamodb/operations/bulk-encrypt-models.ts:29

Overrides

DynamoDBOperation&lt;T[]&gt;.constructor

Methods

audit()

audit(config): this;

Defined in: dynamodb/operations/base-operation.ts:32

Attach audit metadata to this operation. Can be chained.

Inherited from

DynamoDBOperation.audit

then()

then&lt;TResult1, TResult2&gt;(onfulfilled?, onrejected?): Promise&lt;TResult1 | TResult2&gt;;

Defined in: dynamodb/operations/base-operation.ts:54

Make the operation thenable

TResult1

TResult1 = Result<T[], EncryptedDynamoDBError>

onfulfilled?

(value) => TResult1 | PromiseLike<TResult1> | null

onrejected?

(reason) => TResult2 | PromiseLike<TResult2> | null

Inherited from

DynamoDBOperation.then

execute()

execute(): Promise&lt;Result&lt;T[], EncryptedDynamoDBError&gt;>;

Defined in: dynamodb/operations/bulk-encrypt-models.ts:41

Execute the operation and return a Result

Returns

Promise<Result<T[], EncryptedDynamoDBError>>

Overrides

DynamoDBOperation.execute

DecryptModelOperation

Defined in: dynamodb/operations/decrypt-model.ts:24

Type Parameters

T

T extends Record<string, unknown>

Constructors

Constructor

new DecryptModelOperation&lt;T&gt;(
   encryptionClient, 
   item, 
   table, 
   readOptions?, 
   options?): DecryptModelOperation&lt;T&gt;;

Defined in: dynamodb/operations/decrypt-model.ts:32

item

Record<string, | EncryptedValue | unknown>

Overrides

DynamoDBOperation&lt;Decrypted&lt;T&gt;>.constructor

Methods

audit()

audit(config): this;

Defined in: dynamodb/operations/base-operation.ts:32

Attach audit metadata to this operation. Can be chained.

Inherited from

DynamoDBOperation.audit

then()

then&lt;TResult1, TResult2&gt;(onfulfilled?, onrejected?): Promise&lt;TResult1 | TResult2&gt;;

Defined in: dynamodb/operations/base-operation.ts:54

Make the operation thenable

TResult1

TResult1 = Result<Decrypted<T>, EncryptedDynamoDBError>

onfulfilled?

(value) => TResult1 | PromiseLike<TResult1> | null

onrejected?

(reason) => TResult2 | PromiseLike<TResult2> | null

Inherited from

DynamoDBOperation.then

execute()

execute(): Promise&lt;Result&lt;Decrypted&lt;T&gt;, EncryptedDynamoDBError>>;

Defined in: dynamodb/operations/decrypt-model.ts:46

Execute the operation and return a Result

Returns

Promise<Result<Decrypted<T>, EncryptedDynamoDBError>>

Overrides

DynamoDBOperation.execute

EncryptModelOperation

Defined in: dynamodb/operations/encrypt-model.ts:22

Type Parameters

T

T extends Record<string, unknown>

Constructors

Constructor

new EncryptModelOperation&lt;T&gt;(
   encryptionClient, 
   item, 
   table, 
   options?): EncryptModelOperation&lt;T&gt;;

Defined in: dynamodb/operations/encrypt-model.ts:29

Overrides

DynamoDBOperation&lt;T&gt;.constructor

Methods

audit()

audit(config): this;

Defined in: dynamodb/operations/base-operation.ts:32

Attach audit metadata to this operation. Can be chained.

Inherited from

DynamoDBOperation.audit

then()

then&lt;TResult1, TResult2&gt;(onfulfilled?, onrejected?): Promise&lt;TResult1 | TResult2&gt;;

Defined in: dynamodb/operations/base-operation.ts:54

Make the operation thenable

TResult1

TResult1 = Result<T, EncryptedDynamoDBError>

onfulfilled?

(value) => TResult1 | PromiseLike<TResult1> | null

onrejected?

(reason) => TResult2 | PromiseLike<TResult2> | null

Inherited from

DynamoDBOperation.then

execute()

execute(): Promise&lt;Result&lt;T, EncryptedDynamoDBError&gt;>;

Defined in: dynamodb/operations/encrypt-model.ts:41

Execute the operation and return a Result

Returns

Promise<Result<T, EncryptedDynamoDBError>>

Overrides

DynamoDBOperation.execute

Interfaces

EncryptedDynamoDBError

Defined in: dynamodb/types.ts:113

Properties

cause?

optional cause: unknown;

Defined in: ../../../../node_modules/typescript/lib/lib.es2022.error.d.ts:26

Inherited from

Error.cause

name

name: string;

Defined in: ../../../../node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

Error.name

message

message: string;

Defined in: ../../../../node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

Error.message

stack?

optional stack: string;

Defined in: ../../../../node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

Error.stack

EncryptedDynamoDBInstance

Defined in: dynamodb/types.ts:236

Methods

encryptModel()

encryptModel&lt;Table, T&gt;(item, table): EncryptModelOperation&lt;Simplify&lt;{ [K in string | number | symbol as K extends keyof V3Columns&lt;Table&gt; & string ? `${K}__source` : K]: K extends keyof V3Columns&lt;Table&gt; ? SourceAttribute&lt;V3Columns&lt;Table&gt;[K]> : T[K] } & { [K in string | number | symbol as K extends keyof V3Columns&lt;Table&gt; & string ? HasSearchTerm&lt;V3Columns&lt;Table&gt;[K]> extends true ? `${K}__hmac` : never : never]?: string }>>;

Defined in: dynamodb/types.ts:241

EQL v3: the input model is checked against the table's column types, and the result is the EncryptedAttributes storage split.

T

T extends Record<string, unknown>

EncryptModelOperation<Simplify<{ [K in string | number | symbol as K extends keyof V3Columns<Table> & string ? `${K}__source` : K]: K extends keyof V3Columns<Table> ? SourceAttribute<V3Columns<Table>[K]> : T[K] } & { [K in string | number | symbol as K extends keyof V3Columns<Table> & string ? HasSearchTerm<V3Columns<Table>[K]> extends true ? `${K}__hmac` : never : never]?: string }>>

bulkEncryptModels()

bulkEncryptModels&lt;Table, T&gt;(items, table): BulkEncryptModelsOperation&lt;Simplify&lt;{ [K in string | number | symbol as K extends keyof V3Columns&lt;Table&gt; & string ? `${K}__source` : K]: K extends keyof V3Columns&lt;Table&gt; ? SourceAttribute&lt;V3Columns&lt;Table&gt;[K]> : T[K] } & { [K in string | number | symbol as K extends keyof V3Columns&lt;Table&gt; & string ? HasSearchTerm&lt;V3Columns&lt;Table&gt;[K]> extends true ? `${K}__hmac` : never : never]?: string }>>;

Defined in: dynamodb/types.ts:247

EQL v3. See EncryptedDynamoDBInstance.encryptModel.

Type Parameters

Table

Table extends AnyV3Table

T

T extends Record<string, unknown>

Parameters

items

V3ModelInput<Table, T>[]

table

Table

Returns

BulkEncryptModelsOperation<Simplify<{ [K in string | number | symbol as K extends keyof V3Columns<Table> & string ? `${K}__source` : K]: K extends keyof V3Columns<Table> ? SourceAttribute<V3Columns<Table>[K]> : T[K] } & { [K in string | number | symbol as K extends keyof V3Columns<Table> & string ? HasSearchTerm<V3Columns<Table>[K]> extends true ? `${K}__hmac` : never : never]?: string }>>

decryptModel()

decryptModel&lt;Table, T&gt;(
   item, 
   table, 
   options?): DecryptModelOperation&lt;Simplify&lt;{ [K in string | number | symbol as K extends `${Base}__hmac` ? Base extends keyof V3Columns&lt;Table&gt; ? never : K : K extends `${Base}__source` ? Base extends keyof V3Columns&lt;Table&gt; ? Base : K : K]: K extends `${Base}__source` ? Base extends keyof InferPlaintext&lt;Table&gt; ? InferPlaintext&lt;Table&gt;[Base] : T[K] : T[K] }>>;

Defined in: dynamodb/types.ts:260

EQL v3: item is the stored attribute map (<col>__source / <col>__hmac), and the result is the DecryptedAttributes plaintext model it folds back to.

Type Parameters

Table

Table extends AnyV3Table

T

T extends Record<string, unknown>

Parameters

item

T

table

Table

options?

DynamoDBReadOptions

Returns

DecryptModelOperation<Simplify<{ [K in string | number | symbol as K extends `${Base}__hmac` ? Base extends keyof V3Columns<Table> ? never : K : K extends `${Base}__source` ? Base extends keyof V3Columns<Table> ? Base : K : K]: K extends `${Base}__source` ? Base extends keyof InferPlaintext<Table> ? InferPlaintext<Table>[Base] : T[K] : T[K] }>>

bulkDecryptModels()

bulkDecryptModels&lt;Table, T&gt;(
   items, 
   table, 
   options?): BulkDecryptModelsOperation&lt;Simplify&lt;{ [K in string | number | symbol as K extends `${Base}__hmac` ? Base extends keyof V3Columns&lt;Table&gt; ? never : K : K extends `${Base}__source` ? Base extends keyof V3Columns&lt;Table&gt; ? Base : K : K]: K extends `${Base}__source` ? Base extends keyof InferPlaintext&lt;Table&gt; ? InferPlaintext&lt;Table&gt;[Base] : T[K] : T[K] }>>;

Defined in: dynamodb/types.ts:267

EQL v3. See EncryptedDynamoDBInstance.decryptModel.

Type Parameters

Table

Table extends AnyV3Table

T

T extends Record<string, unknown>

Parameters

items

T[]

table

Table

options?

DynamoDBReadOptions

Returns

BulkDecryptModelsOperation<Simplify<{ [K in string | number | symbol as K extends `${Base}__hmac` ? Base extends keyof V3Columns<Table> ? never : K : K extends `${Base}__source` ? Base extends keyof V3Columns<Table> ? Base : K : K]: K extends `${Base}__source` ? Base extends keyof InferPlaintext<Table> ? InferPlaintext<Table>[Base] : T[K] : T[K] }>>

Type Aliases

AuditConfig

type AuditConfig = {
  metadata?: Record&lt;string, unknown&gt;;
};

Defined in: dynamodb/operations/base-operation.ts:4

Properties

metadata?

optional metadata: Record&lt;string, unknown&gt;;

Defined in: dynamodb/operations/base-operation.ts:5

AnyEncryptedTable

type AnyEncryptedTable = AnyV3Table;

Defined in: dynamodb/types.ts:18

An EQL v3 table accepted by every adapter operation.

DynamoDBReadOptions

type DynamoDBReadOptions = {
  storedEqlVersion?: 2 | 3;
};

Defined in: dynamodb/types.ts:20

Properties

storedEqlVersion?

optional storedEqlVersion: 2 | 3;

Defined in: dynamodb/types.ts:22

Wire generation of the payload before DynamoDB stripped its envelope.

DynamoDBEncryptionClient

type DynamoDBEncryptionClient = {
  encryptModel: unknown;
  bulkEncryptModels: unknown;
  decryptModel: unknown;
  bulkDecryptModels: unknown;
};

Defined in: dynamodb/types.ts:50

The client capability this adapter consumes, declared structurally so it is satisfied by EncryptionClient and by the WASM client. Mirrors the approach the Drizzle v3 operators take for the same reason: a nominal EncryptionClient<S> parameter would reject a client built for a narrower schema tuple.

The NATIVE client returns a chainable operation on every path: its decrypt-model methods hand back a MappedDecryptOperation wrapping the underlying DecryptModelOperation, and both of those carry .audit(). The operation classes handle either shape; see DecryptModelOperation and resolveDecryptResult.

The wasm-inline client does not, on EITHER path: its encrypt and decrypt are plain async methods returning a bare Promise<WasmResult>, so audit metadata is dropped (observably — resolveDecryptResult and resolveEncryptResult log it). Chaining .audit() unconditionally is therefore a bug, not just a lost audit record; the encrypt path made exactly that mistake and failed every v3 write on this entry (#788 review follow-up).

Its EQL v2 READ path is supported, however. The legacy read reconstructs the v2 envelope around the current v3 table and forwards that table like any other read, so nothing on this entry needs a v2 schema — which is just as well, since its Encryption() rejects one.

Methods

encryptModel()

encryptModel(input, table): unknown;

Defined in: dynamodb/types.ts:51

Parameters

input

never

table

never

Returns

unknown

bulkEncryptModels()

bulkEncryptModels(input, table): unknown;

Defined in: dynamodb/types.ts:52

Parameters

input

never

table

never

Returns

unknown

decryptModel()

decryptModel(input, table): unknown;

Defined in: dynamodb/types.ts:53

Parameters

input

never

table

never

Returns

unknown

bulkDecryptModels()

bulkDecryptModels(input, table): unknown;

Defined in: dynamodb/types.ts:54

Parameters

input

never

table

never

Returns

unknown

EncryptedAttributes

type EncryptedAttributes&lt;Table, T&gt; = Simplify&lt;{ [K in keyof T as K extends keyof V3Columns&lt;Table&gt; & string ? `${K}${CiphertextSuffix}` : K]: K extends keyof V3Columns&lt;Table&gt; ? SourceAttribute&lt;V3Columns&lt;Table&gt;[K]> : T[K] } & { [K in keyof T as K extends keyof V3Columns&lt;Table&gt; & string ? HasSearchTerm&lt;V3Columns&lt;Table&gt;[K]> extends true ? `${K}${SearchTermSuffix}` : never : never]?: string }>;

Defined in: dynamodb/types.ts:192

The DynamoDB attribute map encryptModel actually returns for a v3 table.

A declared column email does NOT survive as email: the adapter deletes it and writes email__source (plus email__hmac for equality domains). Typing the result as the input model is a lie that type-checks result.data.email (always undefined at runtime) and rejects result.data.email__source (the value you actually want).

Keys that name no column pass through untouched — partition/sort keys, GSI attributes, anything else on the item.

LIMITATION: a v3 column declared under a dotted path ('profile.ssn') is split inside the nested profile map at runtime. The model key is profile, not profile.ssn, so it passes through here unchanged and the nested split is not modelled.

LIMITATION: values inside an ARRAY are not descended into — the write path skips arrays, so a payload in a list is stored whole rather than split into <attr>__source/__hmac. It still decrypts on read, but this mapped type describes it as its plaintext input shape, not a split. Documented in the DynamoDB skill's limitations.

Type Parameters

Table

Table extends AnyV3Table

T

T

DecryptedAttributes

type DecryptedAttributes&lt;Table, T&gt; = Simplify&lt;{ [K in keyof T as K extends `${infer Base}${SearchTermSuffix}` ? Base extends keyof V3Columns&lt;Table&gt; ? never : K : K extends `${infer Base}${CiphertextSuffix}` ? Base extends keyof V3Columns&lt;Table&gt; ? Base : K : K]: K extends `${infer Base}${CiphertextSuffix}` ? Base extends keyof InferPlaintext&lt;Table&gt; ? InferPlaintext&lt;Table&gt;[Base] : T[K] : T[K] }>;

Defined in: dynamodb/types.ts:220

The inverse of EncryptedAttributes: the plaintext model decryptModel returns for an item read back out of DynamoDB.

<col>__source folds back to col with the column's plaintext type, <col>__hmac is dropped (it is a query term, not data), and every other attribute passes through. Declared this way — rather than taking the plaintext model as the input parameter — so T is inferred from the argument a caller actually has: the stored attribute map.

Type Parameters

Table

Table extends AnyV3Table

T

T

Functions

encryptedDynamoDB()

function encryptedDynamoDB(config): EncryptedDynamoDBInstance;

Defined in: dynamodb/index.ts:140

Create an encrypted DynamoDB helper bound to an EncryptionClient.

Returns an object with encryptModel, decryptModel, bulkEncryptModels, and bulkDecryptModels methods that transparently encrypt/decrypt DynamoDB items according to the provided table schema.

Every operation uses an EQL v3 table. To read attributes stored as EQL v2, pass { storedEqlVersion: 2 } to a decrypt method; the table still supplies current column identity and type reconstruction.

Only equality is meaningful on DynamoDB: an hm term is stored alongside the ciphertext as <attr>__hmac and can back a key condition. Ordering and free-text terms have no DynamoDB query surface and are not stored, so values in those domains remain decryptable but not searchable within DynamoDB.

import { Encryption } from "@cipherstash/stack"
import { encryptedTable, types } from "@cipherstash/stack/v3"
import { encryptedDynamoDB } from "@cipherstash/stack/dynamodb"

const users = encryptedTable("users", {
  email: types.TextEq("email"),  // equality → queryable via email__hmac
  name: types.Text("name"),      // storage only
})

const client = await Encryption({ schemas: [users] })
const dynamo = encryptedDynamoDB({ encryptionClient: client })

const encrypted = await dynamo.encryptModel({ email: "[email protected]" }, users)

import { Encryption } from "@cipherstash/stack"
import { encryptedTable, types } from "@cipherstash/stack/v3"
import { encryptedDynamoDB } from "@cipherstash/stack/dynamodb"

// The CURRENT v3 table — there is no v2 builder and no v2-mode client. It
// supplies column identity and type reconstruction for the legacy read, so
// keep it declared for as long as v2 items remain in the table.
const users = encryptedTable("users", {
  email: types.TextEq("email"),
})

const client = await Encryption({ schemas: [users] })
const dynamo = encryptedDynamoDB({ encryptionClient: client })

// `storedItem` is an item written before the v3 cutover.
const decrypted = await dynamo.decryptModel(storedItem, users, {
  storedEqlVersion: 2,
})