@cipherstash/protect-ffi 0.19.0 → 0.20.1

package/README.md

@@ -38,12 +38,27 @@ $ npm i
 $ npm run build
 $ node
 > const addon = require(".");
-> const client = await addon.newClient(JSON.stringify({v: 1, tables: {users: {email: {indexes: {ore: {}, match: {}, unique: {}}}}}}));
-> const ciphertext = await addon.encrypt(client, "plaintext", "email", "users");
-> const plaintext = await addon.decrypt(client, JSON.parse(ciphertext).c);
+> const client = await addon.newClient({ encryptConfig: {v: 1, tables: {users: {email: {indexes: {ore: {}, match: {}, unique: {}}}}}} });
+> const ciphertext = await addon.encrypt(client, { plaintext: "plaintext", column: "email", table: "users" });
+> const plaintext = await addon.decrypt(client, { ciphertext });
 > console.log({ciphertext, plaintext});
 ```
 
+## Errors
+
+Async API calls throw `ProtectError` with a stable `code` for programmatic handling.
+
+```typescript
+try {
+  await addon.encryptQuery(client, opts)
+} catch (err) {
+  if (err?.code === 'INVALID_JSON_PATH') {
+    // handle JSON path mistakes
+  }
+  throw err
+}
+```
+
 ## Available Scripts
 
 In the project directory, you can run:

package/lib/index.cjs

@@ -1,12 +1,146 @@
 "use strict";
 // This module is the CJS entry point for the library.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.decryptBulkFallible = exports.decryptBulk = exports.decrypt = exports.isEncrypted = exports.encryptBulk = exports.encrypt = exports.newClient = void 0;
-var load_cjs_1 = require("./load.cjs");
-Object.defineProperty(exports, "newClient", { enumerable: true, get: function () { return load_cjs_1.newClient; } });
-Object.defineProperty(exports, "encrypt", { enumerable: true, get: function () { return load_cjs_1.encrypt; } });
-Object.defineProperty(exports, "encryptBulk", { enumerable: true, get: function () { return load_cjs_1.encryptBulk; } });
-Object.defineProperty(exports, "isEncrypted", { enumerable: true, get: function () { return load_cjs_1.isEncrypted; } });
-Object.defineProperty(exports, "decrypt", { enumerable: true, get: function () { return load_cjs_1.decrypt; } });
-Object.defineProperty(exports, "decryptBulk", { enumerable: true, get: function () { return load_cjs_1.decryptBulk; } });
-Object.defineProperty(exports, "decryptBulkFallible", { enumerable: true, get: function () { return load_cjs_1.decryptBulkFallible; } });
+exports.ProtectError = void 0;
+exports.newClient = newClient;
+exports.encrypt = encrypt;
+exports.decrypt = decrypt;
+exports.isEncrypted = isEncrypted;
+exports.encryptBulk = encryptBulk;
+exports.decryptBulk = decryptBulk;
+exports.decryptBulkFallible = decryptBulkFallible;
+exports.encryptQuery = encryptQuery;
+exports.encryptQueryBulk = encryptQueryBulk;
+const native = __importStar(require("./load.cjs"));
+class ProtectError extends Error {
+    code;
+    details;
+    cause;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'ProtectError';
+        this.code = opts.code;
+        this.details = opts.details;
+        this.cause = opts.cause;
+    }
+}
+exports.ProtectError = ProtectError;
+function inferErrorCode(message) {
+    if (message.startsWith('protect-ffi invariant violation:')) {
+        return 'INVARIANT_VIOLATION';
+    }
+    if (message.startsWith('Unknown query operation:')) {
+        return 'UNKNOWN_QUERY_OP';
+    }
+    if (message.startsWith('Invalid query input for')) {
+        return 'INVALID_QUERY_INPUT';
+    }
+    if (message.startsWith('Invalid JSON path')) {
+        return 'INVALID_JSON_PATH';
+    }
+    if (message.includes(' not found in Encrypt config')) {
+        return 'UNKNOWN_COLUMN';
+    }
+    if (message.includes(' index configured')) {
+        return 'MISSING_INDEX';
+    }
+    if (message.includes("ste_vec index requires cast_as: 'json'")) {
+        return 'STE_VEC_REQUIRES_JSON_CAST_AS';
+    }
+    return 'UNKNOWN';
+}
+function normalizeError(err) {
+    if (err instanceof ProtectError) {
+        return err;
+    }
+    if (err && typeof err === 'object' && 'message' in err) {
+        const message = String(err.message ?? 'Unknown error');
+        const code = inferErrorCode(message);
+        if (code !== 'UNKNOWN') {
+            return new ProtectError({ code, message, cause: err });
+        }
+    }
+    return err;
+}
+async function wrapAsync(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        throw normalizeError(err);
+    }
+}
+function wrapSync(fn) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        throw normalizeError(err);
+    }
+}
+function newClient(opts) {
+    return wrapAsync(() => native.newClient(opts));
+}
+function encrypt(client, opts) {
+    return wrapAsync(() => native.encrypt(client, opts));
+}
+function decrypt(client, opts) {
+    return wrapAsync(() => native.decrypt(client, opts));
+}
+function isEncrypted(encrypted) {
+    return wrapSync(() => native.isEncrypted(encrypted));
+}
+function encryptBulk(client, opts) {
+    return wrapAsync(() => native.encryptBulk(client, opts));
+}
+function decryptBulk(client, opts) {
+    return wrapAsync(() => native.decryptBulk(client, opts));
+}
+async function decryptBulkFallible(client, opts) {
+    const results = await wrapAsync(() => native.decryptBulkFallible(client, opts));
+    return results.map((item) => {
+        if ('error' in item && typeof item.error === 'string') {
+            return { ...item, code: inferErrorCode(item.error) };
+        }
+        return item;
+    });
+}
+function encryptQuery(client, opts) {
+    return wrapAsync(() => native.encryptQuery(client, opts));
+}
+function encryptQueryBulk(client, opts) {
+    return wrapAsync(() => native.encryptQueryBulk(client, opts));
+}

package/lib/index.d.cts

@@ -1,4 +1,3 @@
-export { newClient, encrypt, encryptBulk, isEncrypted, decrypt, decryptBulk, decryptBulkFallible, } from './load.cjs';
 declare const sym: unique symbol;
 export type Client = {
     readonly [sym]: unknown;
@@ -11,12 +10,36 @@ declare module './load.cjs' {
     function encryptBulk(client: Client, opts: EncryptBulkOptions): Promise<Encrypted[]>;
     function decryptBulk(client: Client, opts: DecryptBulkOptions): Promise<JsPlaintext[]>;
     function decryptBulkFallible(client: Client, opts: DecryptBulkOptions): Promise<DecryptResult[]>;
+    function encryptQuery(client: Client, opts: EncryptQueryOptions): Promise<Encrypted>;
+    function encryptQueryBulk(client: Client, opts: EncryptQueryBulkOptions): Promise<Encrypted[]>;
+}
+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 {
+    code: ProtectErrorCode;
+    details?: unknown;
+    cause?: unknown;
+    constructor(opts: {
+        code: ProtectErrorCode;
+        message: string;
+        details?: unknown;
+        cause?: unknown;
+    });
 }
 export type DecryptResult = {
-    data: string;
+    data: JsPlaintext;
 } | {
     error: string;
-};
+    code?: ProtectErrorCode;
+};
+export declare function newClient(opts: NewClientOptions): Promise<Client>;
+export declare function encrypt(client: Client, opts: EncryptOptions): Promise<Encrypted>;
+export declare function decrypt(client: Client, opts: DecryptOptions): Promise<JsPlaintext>;
+export declare function isEncrypted(encrypted: Encrypted): boolean;
+export declare function encryptBulk(client: Client, opts: EncryptBulkOptions): Promise<Encrypted[]>;
+export declare function decryptBulk(client: Client, opts: DecryptBulkOptions): Promise<JsPlaintext[]>;
+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[]>;
 export type EncryptPayload = {
     plaintext: JsPlaintext;
     column: string;
@@ -135,6 +158,7 @@ export type MatchIndexOpts = {
 };
 export type SteVecIndexOpts = {
     prefix: string;
+    term_filters?: TokenFilter[];
 };
 export type Tokenizer = {
     kind: 'standard';
@@ -161,7 +185,7 @@ export type KeysetIdentifier = {
 } | {
     Name: string;
 };
-export type JsPlaintext = string | number | Record<string, unknown> | JsPlaintext[];
+export type JsPlaintext = string | number | boolean | Record<string, unknown> | JsPlaintext[];
 export type EncryptOptions = {
     plaintext: JsPlaintext;
     column: string;
@@ -186,3 +210,29 @@ export type DecryptBulkOptions = {
     serviceToken?: CtsToken;
     unverifiedContext?: Record<string, unknown>;
 };
+export type IndexTypeName = 'ste_vec' | 'match' | 'ore' | 'unique';
+export type QueryOpName = 'default' | 'ste_vec_selector' | 'ste_vec_term';
+export type EncryptQueryOptions = {
+    plaintext: JsPlaintext;
+    column: string;
+    table: string;
+    indexType: IndexTypeName;
+    queryOp?: QueryOpName;
+    lockContext?: Context;
+    serviceToken?: CtsToken;
+    unverifiedContext?: Record<string, unknown>;
+};
+export type QueryPayload = {
+    plaintext: JsPlaintext;
+    column: string;
+    table: string;
+    indexType: IndexTypeName;
+    queryOp?: QueryOpName;
+    lockContext?: Context;
+};
+export type EncryptQueryBulkOptions = {
+    queries: QueryPayload[];
+    serviceToken?: CtsToken;
+    unverifiedContext?: Record<string, unknown>;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cipherstash/protect-ffi",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "",
   "main": "./lib/index.cjs",
   "scripts": {
@@ -67,11 +67,11 @@
     "@neon-rs/load": "^0.1.82"
   },
   "optionalDependencies": {
-    "@cipherstash/protect-ffi-darwin-x64": "0.19.0",
-    "@cipherstash/protect-ffi-darwin-arm64": "0.19.0",
-    "@cipherstash/protect-ffi-win32-x64-msvc": "0.19.0",
-    "@cipherstash/protect-ffi-linux-x64-gnu": "0.19.0",
-    "@cipherstash/protect-ffi-linux-arm64-gnu": "0.19.0",
-    "@cipherstash/protect-ffi-linux-x64-musl": "0.19.0"
+    "@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"
   }
 }