quiver-client 0.22.0

package/dist/vector.js

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+//! Client-side opaque vector encryption (ADR-0032) for the Quiver TypeScript SDK.
+//
+// Mirrors `quiver_crypto::vector` byte-for-byte: seals a vector's raw
+// little-endian f32 bytes with XChaCha20-Poly1305 (the audited
+// `@stablelib/xchacha20poly1305`, interoperating with the Rust and Python
+// implementations) under the reserved `__quiver_vec__` key. The server stores the
+// blob (in the payload) plus a zero placeholder vector, does no distance math, and
+// never sees the key; the client fetches the entitled set, decrypts, and ranks
+// locally. It is the semantically secure end of Quiver's encrypted-search
+// spectrum: unlike DCPE it leaks nothing about the vectors. Because the sealed
+// message is raw bytes, interop with the Rust/Python impls is bit-exact.
+//
+// This module lives at the `quiver-client/vector` subpath so the core client
+// stays dependency-free; `@stablelib/xchacha20poly1305` is an optional peer
+// dependency you install only to use these helpers:
+//
+//     pnpm add @stablelib/xchacha20poly1305
+//
+//     import { VectorCipher } from "quiver-client/vector";
+//     const cipher = VectorCipher.fromHex("…64 hex chars…");
+//     const payload = { tier: "gold", ...cipher.seal([0.1, -0.2, 0.3, 0.4]) };
+//     // ... upsert with a zero placeholder vector + this payload; later:
+//     const vector = cipher.open(payload); // -> [0.1, -0.2, 0.3, 0.4] (bit-exact)
+//
+// Use a dedicated key for vector encryption; never reuse your at-rest
+// `QUIVER_ENCRYPTION_KEY`. The client owns the key — losing it means the vectors
+// are unrecoverable.
+import { XChaCha20Poly1305 } from "@stablelib/xchacha20poly1305";
+/** The reserved payload key under which a sealed vector envelope is stored. */
+export const VECTOR_ENVELOPE_KEY = "__quiver_vec__";
+const VERSION = 1;
+const ALG = "xchacha20poly1305";
+const NONCE_LEN = 24;
+const TAG_LEN = 16;
+const AAD = new TextEncoder().encode("quiver/vector/v1");
+/** An error sealing or opening a client-side vector envelope. */
+export class VectorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VectorError";
+    }
+}
+/** A client-held key for sealing and opening vector envelopes (ADR-0032). */
+export class VectorCipher {
+    #key;
+    constructor(key) {
+        this.#key = key;
+    }
+    /** Build a cipher from a raw 256-bit (32-byte) key. */
+    static fromBytes(key) {
+        if (key.length !== 32) {
+            throw new VectorError(`vector key must be 32 bytes, got ${key.length}`);
+        }
+        return new VectorCipher(Uint8Array.from(key));
+    }
+    /** Build a cipher from a 64-character hex-encoded 256-bit key. */
+    static fromHex(hex) {
+        const clean = hex.trim();
+        if (!/^[0-9a-fA-F]{64}$/.test(clean)) {
+            throw new VectorError(`vector key must be 64 hex characters, got ${clean.length}`);
+        }
+        const key = new Uint8Array(32);
+        for (let i = 0; i < 32; i++) {
+            key[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+        }
+        return new VectorCipher(key);
+    }
+    /** Seal `vector` into a one-key envelope `{ [VECTOR_ENVELOPE_KEY]: { … } }`. Each
+     * call uses a fresh random nonce, so the same vector seals to different
+     * ciphertext. The vector's f32 components are written little-endian to match the
+     * Rust reference regardless of host endianness. */
+    seal(vector) {
+        const dim = vector.length;
+        const buffer = new ArrayBuffer(dim * 4);
+        const view = new DataView(buffer);
+        for (let i = 0; i < dim; i++) {
+            view.setFloat32(i * 4, Number(vector[i]), true);
+        }
+        const nonce = randomBytes(NONCE_LEN);
+        const ciphertext = new XChaCha20Poly1305(this.#key).seal(nonce, new Uint8Array(buffer), AAD);
+        return {
+            [VECTOR_ENVELOPE_KEY]: {
+                v: VERSION,
+                alg: ALG,
+                dim,
+                n: toBase64(nonce),
+                ct: toBase64(ciphertext),
+            },
+        };
+    }
+    /** Open an envelope sealed by {@link seal}, returning the vector. `sealed` may
+     * carry cleartext sibling fields; only the reserved key is read. A wrong key or
+     * any tampering throws {@link VectorError}. */
+    open(sealed) {
+        if (!isSealedVector(sealed)) {
+            throw new VectorError("value is not a quiver-encrypted vector envelope");
+        }
+        const envelope = sealed[VECTOR_ENVELOPE_KEY];
+        if (typeof envelope !== "object" || envelope === null) {
+            throw new VectorError("envelope is not an object");
+        }
+        const env = envelope;
+        if (env.v !== VERSION) {
+            throw new VectorError(`unsupported envelope version: ${String(env.v)}`);
+        }
+        if (env.alg !== ALG) {
+            throw new VectorError(`unsupported envelope algorithm: ${String(env.alg)}`);
+        }
+        const dim = env.dim;
+        if (typeof dim !== "number" || !Number.isInteger(dim) || dim < 0) {
+            throw new VectorError(`missing or invalid dim: ${String(dim)}`);
+        }
+        const nonce = decodeField(env, "n");
+        if (nonce.length !== NONCE_LEN) {
+            throw new VectorError(`nonce is ${nonce.length} bytes, expected ${NONCE_LEN}`);
+        }
+        const ciphertext = decodeField(env, "ct");
+        if (ciphertext.length < TAG_LEN) {
+            throw new VectorError(`ciphertext is ${ciphertext.length} bytes, shorter than the ${TAG_LEN}-byte tag`);
+        }
+        const message = new XChaCha20Poly1305(this.#key).open(nonce, ciphertext, AAD);
+        if (message === null) {
+            throw new VectorError("wrong key or tampered ciphertext");
+        }
+        if (message.length !== dim * 4) {
+            throw new VectorError(`decrypted ${message.length} bytes, expected ${dim * 4} for dim ${dim}`);
+        }
+        const view = new DataView(message.buffer, message.byteOffset, message.byteLength);
+        const out = [];
+        for (let i = 0; i < dim; i++) {
+            out.push(view.getFloat32(i * 4, true));
+        }
+        return out;
+    }
+}
+/** Whether `value` carries a Quiver vector envelope. */
+export function isSealedVector(value) {
+    return typeof value === "object" && value !== null && VECTOR_ENVELOPE_KEY in value;
+}
+function decodeField(envelope, field) {
+    const raw = envelope[field];
+    if (typeof raw !== "string") {
+        throw new VectorError(`missing envelope field '${field}'`);
+    }
+    return fromBase64(raw);
+}
+function randomBytes(length) {
+    const webcrypto = globalThis.crypto;
+    if (!webcrypto?.getRandomValues) {
+        throw new VectorError("a Web Crypto getRandomValues implementation is required");
+    }
+    return webcrypto.getRandomValues(new Uint8Array(length));
+}
+function toBase64(bytes) {
+    let binary = "";
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+function fromBase64(text) {
+    const binary = atob(text);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "quiver-client",
+  "version": "0.22.0",
+  "description": "TypeScript client for Quiver — a security-first, memory-frugal vector database.",
+  "license": "AGPL-3.0-only",
+  "packageManager": "pnpm@11.6.0",
+  "author": "Achref Soua <achref.soua@outlook.com>",
+  "homepage": "https://github.com/achref-soua/quiver",
+  "keywords": [
+    "vector-database",
+    "embeddings",
+    "search",
+    "ann",
+    "quiver"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./encryption": {
+      "types": "./dist/encryption.d.ts",
+      "import": "./dist/encryption.js"
+    },
+    "./vector": {
+      "types": "./dist/vector.d.ts",
+      "import": "./dist/vector.js"
+    },
+    "./dcpe": {
+      "types": "./dist/dcpe.d.ts",
+      "import": "./dist/dcpe.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@stablelib/chacha": "^2.0.0",
+    "@stablelib/hkdf": "^2.0.0",
+    "@stablelib/hmac": "^2.0.0",
+    "@stablelib/sha256": "^2.0.0",
+    "@stablelib/xchacha20poly1305": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@stablelib/chacha": {
+      "optional": true
+    },
+    "@stablelib/hkdf": {
+      "optional": true
+    },
+    "@stablelib/hmac": {
+      "optional": true
+    },
+    "@stablelib/sha256": {
+      "optional": true
+    },
+    "@stablelib/xchacha20poly1305": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@stablelib/chacha": "^2.0.1",
+    "@stablelib/hkdf": "^2.0.1",
+    "@stablelib/hmac": "^2.0.1",
+    "@stablelib/sha256": "^2.0.1",
+    "@stablelib/xchacha20poly1305": "^2.0.1",
+    "@types/node": "^25.0.0",
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/achref-soua/quiver"
+  }
+}