@cipherstash/stack 0.1.0

package/dist/index-9-Ya3fDK.d.cts

@@ -0,0 +1,169 @@
+import { ProtectErrorCode } from '@cipherstash/protect-ffi';
+import { Result } from '@byteslice/result';
+
+declare const EncryptionErrorTypes: {
+    ClientInitError: string;
+    EncryptionError: string;
+    DecryptionError: string;
+    LockContextError: string;
+    CtsTokenError: string;
+};
+/**
+ * Base error interface returned by all encryption operations.
+ *
+ * Every operation that can fail returns `Result<T, EncryptionError>`.
+ * Use the `type` field to narrow to a specific error kind, or use
+ * {@link StackError} for an exhaustive discriminated union.
+ *
+ * @example
+ * ```typescript
+ * const result = await client.encrypt(value, opts)
+ * if (result.failure) {
+ *   switch (result.failure.type) {
+ *     case 'EncryptionError':
+ *       console.error('Encryption failed:', result.failure.message)
+ *       break
+ *     case 'LockContextError':
+ *       console.error('Lock context issue:', result.failure.message)
+ *       break
+ *   }
+ * }
+ * ```
+ */
+interface EncryptionError {
+    type: (typeof EncryptionErrorTypes)[keyof typeof EncryptionErrorTypes];
+    message: string;
+    code?: ProtectErrorCode;
+}
+interface ClientInitError {
+    type: typeof EncryptionErrorTypes.ClientInitError;
+    message: string;
+}
+interface EncryptionOperationError {
+    type: typeof EncryptionErrorTypes.EncryptionError;
+    message: string;
+    code?: ProtectErrorCode;
+}
+interface DecryptionOperationError {
+    type: typeof EncryptionErrorTypes.DecryptionError;
+    message: string;
+    code?: ProtectErrorCode;
+}
+interface LockContextError {
+    type: typeof EncryptionErrorTypes.LockContextError;
+    message: string;
+}
+interface CtsTokenError {
+    type: typeof EncryptionErrorTypes.CtsTokenError;
+    message: string;
+}
+/**
+ * Discriminated union of all specific error types.
+ *
+ * Use `StackError` when you need exhaustive error handling via `switch` on the `type` field.
+ *
+ * @example
+ * ```typescript
+ * function handleError(error: StackError) {
+ *   switch (error.type) {
+ *     case 'ClientInitError':
+ *       // re-initialize client
+ *       break
+ *     case 'EncryptionError':
+ *     case 'DecryptionError':
+ *       // log and retry
+ *       break
+ *     case 'LockContextError':
+ *       // re-authenticate
+ *       break
+ *     case 'CtsTokenError':
+ *       // refresh token
+ *       break
+ *     default:
+ *       error satisfies never
+ *   }
+ * }
+ * ```
+ */
+type StackError = ClientInitError | EncryptionOperationError | DecryptionOperationError | LockContextError | CtsTokenError;
+/**
+ * Safely extract an error message from an unknown thrown value.
+ * Unlike `(error as Error).message`, this handles non-Error values gracefully.
+ */
+declare function getErrorMessage(error: unknown): string;
+
+type CtsRegions = 'ap-southeast-2';
+type IdentifyOptions = {
+    fetchFromCts?: boolean;
+};
+type CtsToken = {
+    accessToken: string;
+    expiry: number;
+};
+type Context = {
+    identityClaim: string[];
+};
+type LockContextOptions = {
+    context?: Context;
+    ctsToken?: CtsToken;
+};
+type GetLockContextResponse = {
+    ctsToken: CtsToken;
+    context: Context;
+};
+/**
+ * Manages CipherStash lock contexts for row-level access control.
+ *
+ * A `LockContext` ties encryption/decryption operations to an authenticated
+ * user identity via CTS (CipherStash Token Service). Call {@link identify}
+ * with a user's JWT to obtain a CTS token, then pass the `LockContext`
+ * to `.withLockContext()` on any encrypt/decrypt operation.
+ *
+ * @example
+ * ```typescript
+ * import { LockContext } from "@cipherstash/stack/identity"
+ *
+ * const lc = new LockContext()
+ * const identified = await lc.identify(userJwt)
+ *
+ * if (identified.failure) throw new Error(identified.failure.message)
+ *
+ * const result = await client
+ *   .encrypt(value, { column: users.email, table: users })
+ *   .withLockContext(identified.data)
+ * ```
+ */
+declare class LockContext {
+    private ctsToken;
+    private workspaceId;
+    private context;
+    constructor({ context, ctsToken, }?: LockContextOptions);
+    /**
+     * Exchange a user's JWT for a CTS token and bind it to this lock context.
+     *
+     * @param jwtToken - A valid OIDC / JWT token for the current user.
+     * @returns A `Result` containing this `LockContext` (now authenticated) or an error.
+     *
+     * @example
+     * ```typescript
+     * const lc = new LockContext()
+     * const result = await lc.identify(userJwt)
+     * if (result.failure) {
+     *   console.error("Auth failed:", result.failure.message)
+     * }
+     * ```
+     */
+    identify(jwtToken: string): Promise<Result<LockContext, EncryptionError>>;
+    /**
+     * Retrieve the current CTS token and context for use with encryption operations.
+     *
+     * Must be called after {@link identify}. Returns the token/context pair that
+     * `.withLockContext()` expects.
+     *
+     * @returns A `Result` containing the CTS token and identity context, or an error
+     *   if {@link identify} has not been called.
+     */
+    getLockContext(): Promise<Result<GetLockContextResponse, EncryptionError>>;
+}
+
+export { type ClientInitError as C, type DecryptionOperationError as D, EncryptionErrorTypes as E, type GetLockContextResponse as G, type IdentifyOptions as I, type LockContextError as L, type StackError as S, type EncryptionError as a, type EncryptionOperationError as b, type CtsTokenError as c, LockContext as d, type CtsRegions as e, type CtsToken as f, getErrorMessage as g, type Context as h, type LockContextOptions as i };

package/dist/index-9-Ya3fDK.d.ts

@@ -0,0 +1,169 @@
+import { ProtectErrorCode } from '@cipherstash/protect-ffi';
+import { Result } from '@byteslice/result';
+
+declare const EncryptionErrorTypes: {
+    ClientInitError: string;
+    EncryptionError: string;
+    DecryptionError: string;
+    LockContextError: string;
+    CtsTokenError: string;
+};
+/**
+ * Base error interface returned by all encryption operations.
+ *
+ * Every operation that can fail returns `Result<T, EncryptionError>`.
+ * Use the `type` field to narrow to a specific error kind, or use
+ * {@link StackError} for an exhaustive discriminated union.
+ *
+ * @example
+ * ```typescript
+ * const result = await client.encrypt(value, opts)
+ * if (result.failure) {
+ *   switch (result.failure.type) {
+ *     case 'EncryptionError':
+ *       console.error('Encryption failed:', result.failure.message)
+ *       break
+ *     case 'LockContextError':
+ *       console.error('Lock context issue:', result.failure.message)
+ *       break
+ *   }
+ * }
+ * ```
+ */
+interface EncryptionError {
+    type: (typeof EncryptionErrorTypes)[keyof typeof EncryptionErrorTypes];
+    message: string;
+    code?: ProtectErrorCode;
+}
+interface ClientInitError {
+    type: typeof EncryptionErrorTypes.ClientInitError;
+    message: string;
+}
+interface EncryptionOperationError {
+    type: typeof EncryptionErrorTypes.EncryptionError;
+    message: string;
+    code?: ProtectErrorCode;
+}
+interface DecryptionOperationError {
+    type: typeof EncryptionErrorTypes.DecryptionError;
+    message: string;
+    code?: ProtectErrorCode;
+}
+interface LockContextError {
+    type: typeof EncryptionErrorTypes.LockContextError;
+    message: string;
+}
+interface CtsTokenError {
+    type: typeof EncryptionErrorTypes.CtsTokenError;
+    message: string;
+}
+/**
+ * Discriminated union of all specific error types.
+ *
+ * Use `StackError` when you need exhaustive error handling via `switch` on the `type` field.
+ *
+ * @example
+ * ```typescript
+ * function handleError(error: StackError) {
+ *   switch (error.type) {
+ *     case 'ClientInitError':
+ *       // re-initialize client
+ *       break
+ *     case 'EncryptionError':
+ *     case 'DecryptionError':
+ *       // log and retry
+ *       break
+ *     case 'LockContextError':
+ *       // re-authenticate
+ *       break
+ *     case 'CtsTokenError':
+ *       // refresh token
+ *       break
+ *     default:
+ *       error satisfies never
+ *   }
+ * }
+ * ```
+ */
+type StackError = ClientInitError | EncryptionOperationError | DecryptionOperationError | LockContextError | CtsTokenError;
+/**
+ * Safely extract an error message from an unknown thrown value.
+ * Unlike `(error as Error).message`, this handles non-Error values gracefully.
+ */
+declare function getErrorMessage(error: unknown): string;
+
+type CtsRegions = 'ap-southeast-2';
+type IdentifyOptions = {
+    fetchFromCts?: boolean;
+};
+type CtsToken = {
+    accessToken: string;
+    expiry: number;
+};
+type Context = {
+    identityClaim: string[];
+};
+type LockContextOptions = {
+    context?: Context;
+    ctsToken?: CtsToken;
+};
+type GetLockContextResponse = {
+    ctsToken: CtsToken;
+    context: Context;
+};
+/**
+ * Manages CipherStash lock contexts for row-level access control.
+ *
+ * A `LockContext` ties encryption/decryption operations to an authenticated
+ * user identity via CTS (CipherStash Token Service). Call {@link identify}
+ * with a user's JWT to obtain a CTS token, then pass the `LockContext`
+ * to `.withLockContext()` on any encrypt/decrypt operation.
+ *
+ * @example
+ * ```typescript
+ * import { LockContext } from "@cipherstash/stack/identity"
+ *
+ * const lc = new LockContext()
+ * const identified = await lc.identify(userJwt)
+ *
+ * if (identified.failure) throw new Error(identified.failure.message)
+ *
+ * const result = await client
+ *   .encrypt(value, { column: users.email, table: users })
+ *   .withLockContext(identified.data)
+ * ```
+ */
+declare class LockContext {
+    private ctsToken;
+    private workspaceId;
+    private context;
+    constructor({ context, ctsToken, }?: LockContextOptions);
+    /**
+     * Exchange a user's JWT for a CTS token and bind it to this lock context.
+     *
+     * @param jwtToken - A valid OIDC / JWT token for the current user.
+     * @returns A `Result` containing this `LockContext` (now authenticated) or an error.
+     *
+     * @example
+     * ```typescript
+     * const lc = new LockContext()
+     * const result = await lc.identify(userJwt)
+     * if (result.failure) {
+     *   console.error("Auth failed:", result.failure.message)
+     * }
+     * ```
+     */
+    identify(jwtToken: string): Promise<Result<LockContext, EncryptionError>>;
+    /**
+     * Retrieve the current CTS token and context for use with encryption operations.
+     *
+     * Must be called after {@link identify}. Returns the token/context pair that
+     * `.withLockContext()` expects.
+     *
+     * @returns A `Result` containing the CTS token and identity context, or an error
+     *   if {@link identify} has not been called.
+     */
+    getLockContext(): Promise<Result<GetLockContextResponse, EncryptionError>>;
+}
+
+export { type ClientInitError as C, type DecryptionOperationError as D, EncryptionErrorTypes as E, type GetLockContextResponse as G, type IdentifyOptions as I, type LockContextError as L, type StackError as S, type EncryptionError as a, type EncryptionOperationError as b, type CtsTokenError as c, LockContext as d, type CtsRegions as e, type CtsToken as f, getErrorMessage as g, type Context as h, type LockContextOptions as i };