@cipherstash/protect-ffi 0.20.1 → 0.21.0

package/lib/credentials.d.ts

@@ -0,0 +1,11 @@
+export type CredentialOpts = {
+    workspaceCrn?: string;
+    accessKey?: string;
+    clientId?: string;
+    clientKey?: string;
+};
+/** Reads an environment variable. Replaceable in tests. */
+export type EnvReader = (key: string) => string | undefined;
+/** Fill in credential fields from env vars when not explicitly set. */
+export declare function withEnvCredentials<T extends CredentialOpts>(opts: T, env?: EnvReader): T;
+export declare function withEnvCredentials(opts: CredentialOpts | undefined, env?: EnvReader): CredentialOpts;

package/lib/credentials.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withEnvCredentials = withEnvCredentials;
+const processEnv = (key) => process.env[key];
+function withEnvCredentials(opts, env = processEnv) {
+    // CS_CLIENT_ID and CS_CLIENT_KEY are a keypair — only use them when both are set
+    const envClientId = env('CS_CLIENT_ID');
+    const envClientKey = env('CS_CLIENT_KEY');
+    const hasEnvClientKey = envClientId !== undefined && envClientKey !== undefined;
+    const creds = {
+        clientId: opts?.clientId ?? (hasEnvClientKey ? envClientId : undefined),
+        clientKey: opts?.clientKey ?? (hasEnvClientKey ? envClientKey : undefined),
+        workspaceCrn: opts?.workspaceCrn ?? env('CS_WORKSPACE_CRN'),
+        accessKey: opts?.accessKey ?? env('CS_ACCESS_KEY'),
+    };
+    return opts ? { ...opts, ...creds } : creds;
+}

package/lib/index.cjs

@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProtectError = void 0;
+exports.ProtectError = exports.withEnvCredentials = void 0;
 exports.newClient = newClient;
 exports.encrypt = encrypt;
 exports.decrypt = decrypt;
@@ -44,7 +44,11 @@ exports.decryptBulk = decryptBulk;
 exports.decryptBulkFallible = decryptBulkFallible;
 exports.encryptQuery = encryptQuery;
 exports.encryptQueryBulk = encryptQueryBulk;
+exports.ensureKeyset = ensureKeyset;
+const credentials_js_1 = require("./credentials.js");
 const native = __importStar(require("./load.cjs"));
+var credentials_js_2 = require("./credentials.js");
+Object.defineProperty(exports, "withEnvCredentials", { enumerable: true, get: function () { return credentials_js_2.withEnvCredentials; } });
 class ProtectError extends Error {
     code;
     details;
@@ -112,7 +116,10 @@ function wrapSync(fn) {
     }
 }
 function newClient(opts) {
-    return wrapAsync(() => native.newClient(opts));
+    return wrapAsync(() => native.newClient({
+        ...opts,
+        clientOpts: (0, credentials_js_1.withEnvCredentials)(opts.clientOpts),
+    }));
 }
 function encrypt(client, opts) {
     return wrapAsync(() => native.encrypt(client, opts));
@@ -144,3 +151,11 @@ function encryptQuery(client, opts) {
 function encryptQueryBulk(client, opts) {
     return wrapAsync(() => native.encryptQueryBulk(client, opts));
 }
+/**
+ * Test-only helper: ensures a keyset with the given name exists, creating it if necessary,
+ * and grants the current client access. Not safe for concurrent use — intended for
+ * sequential test setup only.
+ */
+function ensureKeyset(opts) {
+    return wrapAsync(() => native.ensureKeyset((0, credentials_js_1.withEnvCredentials)(opts)));
+}

package/lib/index.d.cts

@@ -1,3 +1,5 @@
+import { type CredentialOpts } from './credentials.js';
+export { withEnvCredentials, type EnvReader, type CredentialOpts, } from './credentials.js';
 declare const sym: unique symbol;
 export type Client = {
     readonly [sym]: unknown;
@@ -12,6 +14,7 @@ declare module './load.cjs' {
     function decryptBulkFallible(client: Client, opts: DecryptBulkOptions): Promise<DecryptResult[]>;
     function encryptQuery(client: Client, opts: EncryptQueryOptions): Promise<Encrypted>;
     function encryptQueryBulk(client: Client, opts: EncryptQueryBulkOptions): Promise<Encrypted[]>;
+    function ensureKeyset(opts: EnsureKeysetOpts): Promise<EnsureKeysetResult>;
 }
 export type ProtectErrorCode = 'INVARIANT_VIOLATION' | 'UNKNOWN_QUERY_OP' | 'UNKNOWN_COLUMN' | 'MISSING_INDEX' | 'INVALID_QUERY_INPUT' | 'INVALID_JSON_PATH' | 'STE_VEC_REQUIRES_JSON_CAST_AS' | 'UNKNOWN';
 export declare class ProtectError extends Error {
@@ -40,6 +43,12 @@ export declare function decryptBulk(client: Client, opts: DecryptBulkOptions): P
 export declare function decryptBulkFallible(client: Client, opts: DecryptBulkOptions): Promise<DecryptResult[]>;
 export declare function encryptQuery(client: Client, opts: EncryptQueryOptions): Promise<Encrypted>;
 export declare function encryptQueryBulk(client: Client, opts: EncryptQueryBulkOptions): Promise<Encrypted[]>;
+/**
+ * Test-only helper: ensures a keyset with the given name exists, creating it if necessary,
+ * and grants the current client access. Not safe for concurrent use — intended for
+ * sequential test setup only.
+ */
+export declare function ensureKeyset(opts: EnsureKeysetOpts): Promise<EnsureKeysetResult>;
 export type EncryptPayload = {
     plaintext: JsPlaintext;
     column: string;
@@ -129,7 +138,7 @@ export type Column = {
     cast_as?: CastAs;
     indexes?: Indexes;
 };
-export type CastAs = 'bigint' | 'boolean' | 'date' | 'number' | 'string' | 'json';
+export type CastAs = 'bigint' | 'boolean' | 'date' | 'number' | 'string' | 'text' | 'json';
 type TablesOf<C extends EncryptConfig> = C['tables'];
 export type Identifier<C extends EncryptConfig> = {
     [T in keyof TablesOf<C>]: {
@@ -156,9 +165,15 @@ export type MatchIndexOpts = {
     m?: number;
     include_original?: boolean;
 };
+export type ArrayIndexMode = 'all' | 'none' | {
+    item?: boolean;
+    wildcard?: boolean;
+    position?: boolean;
+};
 export type SteVecIndexOpts = {
     prefix: string;
     term_filters?: TokenFilter[];
+    array_index_mode?: ArrayIndexMode;
 };
 export type Tokenizer = {
     kind: 'standard';
@@ -173,11 +188,7 @@ export type NewClientOptions = {
     encryptConfig: EncryptConfig;
     clientOpts?: ClientOpts;
 };
-export type ClientOpts = {
-    workspaceCrn?: string;
-    accessKey?: string;
-    clientId?: string;
-    clientKey?: string;
+export type ClientOpts = CredentialOpts & {
     keyset?: KeysetIdentifier;
 };
 export type KeysetIdentifier = {
@@ -185,6 +196,13 @@ export type KeysetIdentifier = {
 } | {
     Name: string;
 };
+export type EnsureKeysetOpts = CredentialOpts & {
+    name: string;
+};
+export type EnsureKeysetResult = {
+    id: string;
+    name: string;
+};
 export type JsPlaintext = string | number | boolean | Record<string, unknown> | JsPlaintext[];
 export type EncryptOptions = {
     plaintext: JsPlaintext;
@@ -235,4 +253,3 @@ export type EncryptQueryBulkOptions = {
     serviceToken?: CtsToken;
     unverifiedContext?: Record<string, unknown>;
 };
-export {};

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@cipherstash/protect-ffi",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "description": "",
   "main": "./lib/index.cjs",
   "scripts": {
-    "test": "npm run test:typecheck && npm run test:lint && npm run test:format && npm run test:rust",
+    "test": "npm run test:typecheck && npm run test:unit && npm run test:lint && npm run test:format && npm run test:rust",
     "test:typecheck": "tsc",
+    "test:unit": "vitest run",
     "test:rust": "cargo test",
     "test:lint": "npm run test:lint:ts",
     "test:lint:ts": "biome lint",
@@ -61,17 +62,18 @@
     "@neon-rs/cli": "^0.1.82",
     "@tsconfig/node20": "^20.1.4",
     "@types/node": "^20.11.16",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "vitest": "^4.1.0"
   },
   "dependencies": {
     "@neon-rs/load": "^0.1.82"
   },
   "optionalDependencies": {
-    "@cipherstash/protect-ffi-darwin-x64": "0.20.1",
-    "@cipherstash/protect-ffi-darwin-arm64": "0.20.1",
-    "@cipherstash/protect-ffi-win32-x64-msvc": "0.20.1",
-    "@cipherstash/protect-ffi-linux-x64-gnu": "0.20.1",
-    "@cipherstash/protect-ffi-linux-arm64-gnu": "0.20.1",
-    "@cipherstash/protect-ffi-linux-x64-musl": "0.20.1"
+    "@cipherstash/protect-ffi-darwin-x64": "0.21.0",
+    "@cipherstash/protect-ffi-darwin-arm64": "0.21.0",
+    "@cipherstash/protect-ffi-win32-x64-msvc": "0.21.0",
+    "@cipherstash/protect-ffi-linux-x64-gnu": "0.21.0",
+    "@cipherstash/protect-ffi-linux-arm64-gnu": "0.21.0",
+    "@cipherstash/protect-ffi-linux-x64-musl": "0.21.0"
   }
 }