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

Binds an encryption/decryption operation to a user's identity by selecting which JWT claim(s) ZeroKMS bakes into the data key's tag (the lock context).

The claim value is resolved by ZeroKMS from the token that authenticates the request — so to bind to a real end user, authenticate the client as that user with an OidcFederationStrategy (from @cipherstash/auth) and pass the claim to .withLockContext(). The same context must be supplied to decrypt.

You can pass a plain { identityClaim } directly — constructing a LockContext is optional.

Example

import { Encryption } from "@cipherstash/stack"
import { OidcFederationStrategy } from "@cipherstash/auth"

// Authenticate the client as the end user (replaces the old identify() flow).
const client = await Encryption({
  schemas,
  config: {
    authStrategy: OidcFederationStrategy.create(workspaceCrn, () => getJwt()),
  },
})

// Bind the key to the user's `sub` claim — no token, no identify().
const result = await client
  .encrypt(value, { column: users.email, table: users })
  .withLockContext({ identityClaim: ["sub"] })

Constructors

Constructor

new LockContext(__namedParameters?): LockContext;

Defined in: identity/index.ts:86

Parameters

__namedParameters?

LockContextOptions = {}

Returns

LockContext

Accessors

identityContext

Get Signature

get identityContext(): Context;

Defined in: identity/index.ts:112

The identity-claim context this lock context binds to, e.g. { identityClaim: ['sub'] }. Resolved synchronously — .withLockContext() uses this directly; no CTS token is required.

Returns

Context

Methods

identify()

identify(jwtToken): Promise&lt;Result&lt;LockContext, EncryptionError&gt;>;

Defined in: identity/index.ts:129

Exchange a user's JWT for a CTS token and bind it to this lock context.

Parameters

jwtToken

string

A valid OIDC / JWT token for the current user.

Returns

Promise<Result<LockContext, EncryptionError>>

A Result containing this LockContext or an error.

Deprecated

Per-operation CTS tokens were removed in protect-ffi 0.25. Authenticate the client as the user with an OidcFederationStrategy (config.authStrategy) instead, and pass the claim to .withLockContext(). The token fetched here is no longer used by encryption operations. This method is kept for backwards compatibility and will be removed in a future major release.

getLockContext()

getLockContext(): Promise&lt;Result&lt;GetLockContextResponse, EncryptionError&gt;>;

Defined in: identity/index.ts:192

Retrieve the identity context (and CTS token, if one was set).

Returns

Promise<Result<GetLockContextResponse, EncryptionError>>

Deprecated

Encryption operations no longer consume a CTS token — they read the identity claim directly via identityContext. Pass the claim to .withLockContext() and authenticate the client with an OidcFederationStrategy instead. Kept for backwards compatibility; the returned ctsToken is undefined unless one was supplied to the constructor or identify was called.

Type Aliases

CtsRegions

type CtsRegions = "ap-southeast-2";

Defined in: identity/index.ts:6

IdentifyOptions

type IdentifyOptions = {
  fetchFromCts?: boolean;
};

Defined in: identity/index.ts:8

Properties

fetchFromCts?

optional fetchFromCts: boolean;

Defined in: identity/index.ts:9

CtsToken

type CtsToken = {
  accessToken: string;
  expiry: number;
};

Defined in: identity/index.ts:12

Properties

accessToken

accessToken: string;

Defined in: identity/index.ts:13

expiry

expiry: number;

Defined in: identity/index.ts:14

Context

type Context = {
  identityClaim: string[];
};

Defined in: identity/index.ts:17

Properties

identityClaim

identityClaim: string[];

Defined in: identity/index.ts:18

LockContextOptions

type LockContextOptions = {
  context?: Context;
  ctsToken?: CtsToken;
};

Defined in: identity/index.ts:21

Properties

context?

optional context: Context;

Defined in: identity/index.ts:22

ctsToken?

optional ctsToken: CtsToken;

Defined in: identity/index.ts:23

GetLockContextResponse

type GetLockContextResponse = {
  ctsToken?: CtsToken;
  context: Context;
};

Defined in: identity/index.ts:26

Properties

ctsToken?

optional ctsToken: CtsToken;

Defined in: identity/index.ts:27

context

context: Context;

Defined in: identity/index.ts:28

LockContextInput

type LockContextInput = 
  | LockContext
  | Context;

Defined in: identity/index.ts:35

The accepted argument to .withLockContext() — either a LockContext or a plain identity-claim spec (e.g. { identityClaim: ['sub'] }).

Functions

resolveLockContext()

function resolveLockContext(input): Context;

Defined in: identity/index.ts:41

Resolve a LockContextInput to the Context (identity claim) that protect-ffi expects. Synchronous — no token round-trip.

identity

On this page