quiver-client 0.22.0

package/dist/dcpe.js

@@ -0,0 +1,336 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+//! Client-side DCPE vector encryption (ADR-0031, hardened in ADR-0035) for the
+//! Quiver TypeScript SDK.
+//
+// A faithful port of the reference cipher `quiver_crypto::dcpe` (and the Python
+// `quiver.dcpe`): the **Scale-And-Perturb (SAP)** distance-comparison-preserving
+// scheme of Fuchsbauer, Ghosal, Hauke & O'Neill (ePrint 2021/1666, SCN 2022). It
+// encrypts embedding vectors so a Quiver server can answer approximate
+// nearest-neighbour queries over the ciphertexts **without ever holding the
+// plaintext vectors or the key** — Euclidean distance comparison is preserved up
+// to a tunable margin.
+//
+// This is **cipher v2** (ADR-0035): it adds the paper's two hardening steps — a
+// key-derived component **shuffle** (an exact L2 isometry, so zero recall cost)
+// and an optional ordering-preserving global affine **normalisation**
+// (`Normalization`). v2 is a breaking change from v1 (v1 ciphertexts are not
+// v2-decryptable); the cipher is client-side, so there is no on-disk format change.
+//
+// This module lives at the `quiver-client/dcpe` subpath so the core client stays
+// dependency-free. The primitives come from audited `@stablelib` packages, installed
+// as optional peer dependencies only to use these helpers:
+//
+//     pnpm add @stablelib/chacha @stablelib/hkdf @stablelib/hmac @stablelib/sha256
+//
+//     import { DcpeCipher } from "quiver-client/dcpe";
+//     const cipher = DcpeCipher.fromHex("…64 hex chars…", 0.02);
+//     // encrypt vectors before upsert, and queries before search, with the same cipher:
+//     const sealed = cipher.encrypt([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]);
+//     // upsert sealed.ciphertext; later: cipher.encryptQuery(myQuery) for search.
+//
+// **DCPE is experimental and is _not_ semantically secure.** It leaks the
+// approximate distance-comparison relation by design (that is what makes encrypted
+// search work), is L2-only, and is broken by known-plaintext or strong-prior
+// adversaries. It complements — does not replace — encryption at rest. Use a
+// dedicated key, and encrypt and query from the same client. See ADR-0031, ADR-0035,
+// and docs/security/dcpe.md.
+//
+// Because the ciphertext is float-valued and uses transcendental functions,
+// bit-exact reproduction against the Rust reference is not guaranteed (libm ULP
+// differences); interop is validated within a tolerance. The Rust module is canonical.
+import { stream } from "@stablelib/chacha";
+import { HKDF } from "@stablelib/hkdf";
+import { hmac } from "@stablelib/hmac";
+import { SHA256 } from "@stablelib/sha256";
+/** DCPE initialisation-vector length in bytes (a 96-bit ChaCha20 nonce). */
+export const IV_LEN = 12;
+/** DCPE integrity-tag length in bytes (full HMAC-SHA256 output). */
+export const TAG_LEN = 32;
+const TE = new TextEncoder();
+// HKDF-SHA256 `info` strings: distinct sub-keys from one master secret. The
+// scale/prf/auth derivations are unchanged from v1; `shuffle` is new in v2, and
+// the tag domain is bumped to v2 so a v1 ciphertext fails a v2 integrity check.
+const INFO_SCALE = TE.encode("quiver/dcpe/v1/scale");
+const INFO_PRF = TE.encode("quiver/dcpe/v1/prf");
+const INFO_SHUFFLE = TE.encode("quiver/dcpe/v2/shuffle");
+const INFO_AUTH = TE.encode("quiver/dcpe/v1/auth");
+const AUTH_DOMAIN = TE.encode("quiver/dcpe/v2/tag");
+const TWO_POW_53 = 2 ** 53;
+/** An error from DCPE encryption, decryption, or construction. */
+export class DcpeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DcpeError";
+    }
+}
+/** A fixed, ordering-preserving global affine normalisation (ADR-0035).
+ *
+ * Maps a plaintext `m` to `(m - shift) * scale` before encryption, where `shift`
+ * is a per-dimension translation and `scale` is a **single** positive scalar. Both
+ * steps preserve the L2 distance-comparison ordering (a uniform shift cancels in
+ * any difference; a single positive scalar scales every distance by the same
+ * factor) and are invertible. Supply it once from a one-time measurement of your
+ * corpus and reuse it for the data *and* the queries.
+ *
+ * Per-axis variance whitening (a different scale per dimension) is anisotropic,
+ * re-weights the L2 distance, and so breaks the ordering — it is intentionally not
+ * expressible here. See ADR-0035. */
+export class Normalization {
+    shift;
+    scale;
+    constructor(shift, scale) {
+        this.shift = shift;
+        this.scale = scale;
+    }
+    /** Build a normalisation from a per-dimension shift and a single positive scale. */
+    static create(shift, scale) {
+        const shiftArr = Array.from(shift, Number);
+        if (!Number.isFinite(scale) || scale <= 0 || shiftArr.some((x) => !Number.isFinite(x))) {
+            throw new DcpeError("invalid normalisation: scale must be finite and > 0 and shifts finite");
+        }
+        return new Normalization(shiftArr, scale);
+    }
+}
+/** A client-held DCPE key bound to one approximation factor (ADR-0031/0035).
+ *
+ * Construct one cipher per `(key, approximationFactor[, normalization])` and reuse
+ * it; the same factor (and normalisation) must be used for the data and the queries
+ * searched against it. */
+export class DcpeCipher {
+    #scale;
+    #prfKey;
+    #shuffleKey;
+    #authKey;
+    #beta;
+    #normalization;
+    constructor(key, approximationFactor, normalization) {
+        if (!Number.isFinite(approximationFactor) || approximationFactor < 0) {
+            throw new DcpeError("approximation factor must be finite and >= 0");
+        }
+        // Match the Rust f32 approximation factor exactly (it is bound into the tag).
+        this.#beta = Math.fround(approximationFactor);
+        const salt = new Uint8Array(32);
+        const scaleBytes = new HKDF(SHA256, key, salt, INFO_SCALE).expand(8);
+        this.#scale = 1 + Number(leU64(scaleBytes, 0) >> 11n) / TWO_POW_53;
+        this.#prfKey = new HKDF(SHA256, key, salt, INFO_PRF).expand(32);
+        this.#shuffleKey = new HKDF(SHA256, key, salt, INFO_SHUFFLE).expand(32);
+        this.#authKey = new HKDF(SHA256, key, salt, INFO_AUTH).expand(32);
+        this.#normalization = normalization;
+    }
+    /** Build a cipher from a raw 256-bit (32-byte) key. */
+    static fromBytes(key, approximationFactor, normalization = null) {
+        if (key.length !== 32) {
+            throw new DcpeError(`DCPE key must be 32 bytes, got ${key.length}`);
+        }
+        return new DcpeCipher(Uint8Array.from(key), approximationFactor, normalization);
+    }
+    /** Build a cipher from a 64-character hex-encoded 256-bit key. */
+    static fromHex(hex, approximationFactor, normalization = null) {
+        const clean = hex.trim();
+        if (!/^[0-9a-fA-F]{64}$/.test(clean)) {
+            throw new DcpeError(`DCPE 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 DcpeCipher(key, approximationFactor, normalization);
+    }
+    /** The secret, key-derived scaling factor `s ∈ [1, 2)`. Part of the key. */
+    get scale() {
+        return this.#scale;
+    }
+    /** The approximation factor this cipher was built with. */
+    get approximationFactor() {
+        return this.#beta;
+    }
+    /** Encrypt a vector for storage with a fresh random IV. */
+    encrypt(vector) {
+        if (vector.length === 0) {
+            throw new DcpeError("empty vector: DCPE needs at least one dimension");
+        }
+        const pre = this.#pretransform(vector);
+        const iv = randomBytes(IV_LEN);
+        const ciphertext = this.#scaleAndPerturb(pre, iv);
+        return { ciphertext, iv, tag: this.#tag(iv, ciphertext) };
+    }
+    /** Encrypt a query vector for searching against DCPE-encrypted data. */
+    encryptQuery(vector) {
+        if (vector.length === 0) {
+            throw new DcpeError("empty vector: DCPE needs at least one dimension");
+        }
+        return this.#scaleAndPerturb(this.#pretransform(vector), randomBytes(IV_LEN));
+    }
+    /** Verify the integrity tag (constant-time) and recover the plaintext. */
+    decrypt(sealed) {
+        if (sealed.ciphertext.length === 0) {
+            throw new DcpeError("empty vector: DCPE needs at least one dimension");
+        }
+        const expected = this.#tag(sealed.iv, sealed.ciphertext);
+        if (!constantTimeEqual(expected, sealed.tag)) {
+            throw new DcpeError("integrity check failed: wrong key or tampered ciphertext");
+        }
+        const lambda = this.#perturbation(sealed.iv, sealed.ciphertext.length);
+        // Recover the shuffled, normalised vector (c - lambda)/s, then reverse the
+        // pipeline: un-shuffle, then un-normalise.
+        const shuffled = sealed.ciphertext.map((c, i) => (c - lambda[i]) / this.#scale);
+        return this.#denormalize(this.#unshuffle(shuffled));
+    }
+    // --- internals (match the Rust/Python references byte-for-byte) ---
+    #pretransform(vector) {
+        const normalized = this.#normalize(vector);
+        const perm = this.#permutation(vector.length);
+        return perm.map((p) => normalized[p]);
+    }
+    #normalize(vector) {
+        const n = this.#normalization;
+        if (n === null) {
+            return Array.from(vector, Number);
+        }
+        if (n.shift.length !== vector.length) {
+            throw new DcpeError(`dimension mismatch: vector has ${vector.length} dims, normalisation has ${n.shift.length}`);
+        }
+        return Array.from(vector, (m, i) => (Number(m) - n.shift[i]) * n.scale);
+    }
+    #unshuffle(shuffled) {
+        const perm = this.#permutation(shuffled.length);
+        const out = new Array(shuffled.length).fill(0);
+        for (let i = 0; i < perm.length; i++) {
+            out[perm[i]] = shuffled[i];
+        }
+        return out;
+    }
+    #denormalize(normalized) {
+        const n = this.#normalization;
+        if (n === null) {
+            return normalized.map((x) => Math.fround(x));
+        }
+        if (n.shift.length !== normalized.length) {
+            throw new DcpeError(`dimension mismatch: vector has ${normalized.length} dims, normalisation has ${n.shift.length}`);
+        }
+        return normalized.map((x, i) => Math.fround(x / n.scale + n.shift[i]));
+    }
+    // The key-derived permutation of [0, d) (Fisher-Yates from the top over the
+    // shuffle keystream with a fixed zero IV), identical for every vector and query
+    // so all pairwise L2 distances are preserved. The `% (i + 1)` reduction's modulo
+    // bias is cryptographically negligible and is fixed for cross-language parity.
+    #permutation(d) {
+        const perm = Array.from({ length: d }, (_, i) => i);
+        if (d <= 1) {
+            return perm;
+        }
+        const ks = new KeyStream(this.#shuffleKey, new Uint8Array(IV_LEN), d * 8);
+        for (let i = d - 1; i >= 1; i--) {
+            const j = Number(ks.nextU64() % BigInt(i + 1));
+            const tmp = perm[i];
+            perm[i] = perm[j];
+            perm[j] = tmp;
+        }
+        return perm;
+    }
+    // Compute c = s·x + λ (f64), stored as f32. `x` is the normalised+shuffled vector.
+    #scaleAndPerturb(x, iv) {
+        const lambda = this.#perturbation(iv, x.length);
+        return x.map((m, i) => Math.fround(this.#scale * m + lambda[i]));
+    }
+    // The perturbation λ: a uniform point in the d-ball of radius (s/4)·β. The CSPRNG
+    // draws the d normal components first, then one uniform for the radius.
+    #perturbation(iv, d) {
+        const ks = new KeyStream(this.#prfKey, iv, (d + 4) * 8);
+        const direction = Array.from({ length: d }, () => ks.nextNormal());
+        let norm = 0;
+        for (const v of direction) {
+            norm += v * v;
+        }
+        norm = Math.sqrt(norm);
+        const u = ks.nextUnit();
+        const radius = (this.#scale / 4) * this.#beta * Math.pow(u, 1 / d);
+        if (norm === 0) {
+            return new Array(d).fill(0);
+        }
+        return direction.map((v) => (v / norm) * radius);
+    }
+    // HMAC-SHA256 over (domain ‖ β as f32 LE ‖ iv ‖ ciphertext as f32 LE).
+    #tag(iv, ciphertext) {
+        const d = ciphertext.length;
+        const msg = new Uint8Array(AUTH_DOMAIN.length + 4 + IV_LEN + 4 * d);
+        const dv = new DataView(msg.buffer, msg.byteOffset, msg.byteLength);
+        let off = 0;
+        msg.set(AUTH_DOMAIN, off);
+        off += AUTH_DOMAIN.length;
+        dv.setFloat32(off, this.#beta, true);
+        off += 4;
+        msg.set(iv, off);
+        off += IV_LEN;
+        for (let i = 0; i < d; i++) {
+            dv.setFloat32(off, ciphertext[i], true);
+            off += 4;
+        }
+        return hmac(SHA256, this.#authKey, msg);
+    }
+}
+/** A deterministic CSPRNG: the raw ChaCha20 keystream from `(key, iv)`, read as
+ * little-endian u64s. Standard normals come from Box-Muller, caching the paired
+ * value. The layout matches the Rust/Python references byte-for-byte. The keystream
+ * is materialised up front to `capacity` bytes (sized to the caller's exact need). */
+class KeyStream {
+    #buf;
+    #pos = 0;
+    #spare = null;
+    constructor(key, iv, capacity) {
+        this.#buf = new Uint8Array(capacity);
+        stream(key, iv, this.#buf);
+    }
+    nextU64() {
+        if (this.#pos + 8 > this.#buf.length) {
+            throw new DcpeError("DCPE keystream exhausted");
+        }
+        const w = leU64(this.#buf, this.#pos);
+        this.#pos += 8;
+        return w;
+    }
+    // A uniform in [0, 1) with 53-bit resolution (the f64 mantissa width).
+    nextUnit() {
+        return Number(this.nextU64() >> 11n) / TWO_POW_53;
+    }
+    // A standard normal via Box-Muller; u1 ∈ (0, 1] so log is finite.
+    nextNormal() {
+        if (this.#spare !== null) {
+            const z = this.#spare;
+            this.#spare = null;
+            return z;
+        }
+        const u1 = 1 - this.nextUnit();
+        const u2 = this.nextUnit();
+        const r = Math.sqrt(-2 * Math.log(u1));
+        const theta = 2 * Math.PI * u2;
+        this.#spare = r * Math.sin(theta);
+        return r * Math.cos(theta);
+    }
+}
+/** Read 8 bytes of `buf` at `off` as a little-endian u64. */
+function leU64(buf, off) {
+    let w = 0n;
+    for (let i = 7; i >= 0; i--) {
+        w = (w << 8n) | BigInt(buf[off + i]);
+    }
+    return w;
+}
+/** A constant-time byte-string comparison (not a crypto primitive; a comparison). */
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a[i] ^ b[i];
+    }
+    return diff === 0;
+}
+function randomBytes(length) {
+    const webcrypto = globalThis.crypto;
+    if (!webcrypto?.getRandomValues) {
+        throw new DcpeError("a Web Crypto getRandomValues implementation is required");
+    }
+    return webcrypto.getRandomValues(new Uint8Array(length));
+}

package/dist/encryption.d.ts

@@ -0,0 +1,25 @@
+/** The reserved payload key under which a sealed envelope is stored. */
+export declare const ENVELOPE_KEY = "__quiver_enc__";
+/** An error sealing or opening a client-side payload envelope. */
+export declare class PayloadError extends Error {
+    constructor(message: string);
+}
+/** A client-held key for sealing and opening payload envelopes (ADR-0012). */
+export declare class PayloadCipher {
+    #private;
+    private constructor();
+    /** Build a cipher from a raw 256-bit (32-byte) key. */
+    static fromBytes(key: Uint8Array): PayloadCipher;
+    /** Build a cipher from a 64-character hex-encoded 256-bit key. */
+    static fromHex(hex: string): PayloadCipher;
+    /** Seal `plaintext` into a one-key envelope `{ [ENVELOPE_KEY]: { … } }`. Each
+     * call uses a fresh random nonce, so the same value seals to different
+     * ciphertext. */
+    seal(plaintext: unknown): Record<string, unknown>;
+    /** Open an envelope sealed by {@link seal}, returning the plaintext. `sealed`
+     * may carry cleartext sibling fields; only the reserved key is read. A wrong
+     * key or any tampering throws {@link PayloadError}. */
+    open(sealed: unknown): unknown;
+}
+/** Whether `value` carries a Quiver payload envelope. */
+export declare function isSealed(value: unknown): boolean;

package/dist/encryption.js

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+//! Client-side payload encryption (ADR-0012) for the Quiver TypeScript SDK.
+//
+// Mirrors the reference envelope in `quiver_crypto::payload` byte-for-byte: a
+// caller seals a JSON payload with a 256-bit key Quiver never sees, and the
+// server stores and returns it as an opaque blob it cannot read. Sealing uses
+// XChaCha20-Poly1305 (the audited `@stablelib/xchacha20poly1305`, which
+// interoperates with the Rust and Python implementations) with a fresh random
+// 192-bit nonce.
+//
+// This module lives at the `quiver-client/encryption` 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
+//
+// Keep fields server-filterable by leaving them in cleartext and merging the
+// sealed envelope alongside them — `open` reads only the reserved key:
+//
+//     import { PayloadCipher } from "quiver-client/encryption";
+//     const cipher = PayloadCipher.fromHex("…64 hex chars…");
+//     const payload = { tier: "gold", ...cipher.seal({ ssn: "078-05-1120" }) };
+//     // ... upsert `payload`; the server only ever sees ciphertext for `ssn`.
+//     const secret = cipher.open(payload); // -> { ssn: "078-05-1120" }
+//
+// Use a dedicated key for payload encryption; never reuse your at-rest
+// `QUIVER_ENCRYPTION_KEY`. The client owns the key — losing it means the data
+// is unrecoverable.
+import { XChaCha20Poly1305 } from "@stablelib/xchacha20poly1305";
+/** The reserved payload key under which a sealed envelope is stored. */
+export const ENVELOPE_KEY = "__quiver_enc__";
+const VERSION = 1;
+const ALG = "xchacha20poly1305";
+const NONCE_LEN = 24;
+const TAG_LEN = 16;
+const AAD = new TextEncoder().encode("quiver/payload/v1");
+/** An error sealing or opening a client-side payload envelope. */
+export class PayloadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PayloadError";
+    }
+}
+/** A client-held key for sealing and opening payload envelopes (ADR-0012). */
+export class PayloadCipher {
+    #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 PayloadError(`payload key must be 32 bytes, got ${key.length}`);
+        }
+        return new PayloadCipher(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 PayloadError(`payload 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 PayloadCipher(key);
+    }
+    /** Seal `plaintext` into a one-key envelope `{ [ENVELOPE_KEY]: { … } }`. Each
+     * call uses a fresh random nonce, so the same value seals to different
+     * ciphertext. */
+    seal(plaintext) {
+        const json = JSON.stringify(plaintext);
+        if (json === undefined) {
+            throw new PayloadError("cannot seal a value that is not JSON-serializable");
+        }
+        const nonce = randomBytes(NONCE_LEN);
+        const ciphertext = new XChaCha20Poly1305(this.#key).seal(nonce, new TextEncoder().encode(json), AAD);
+        return {
+            [ENVELOPE_KEY]: {
+                v: VERSION,
+                alg: ALG,
+                n: toBase64(nonce),
+                ct: toBase64(ciphertext),
+            },
+        };
+    }
+    /** Open an envelope sealed by {@link seal}, returning the plaintext. `sealed`
+     * may carry cleartext sibling fields; only the reserved key is read. A wrong
+     * key or any tampering throws {@link PayloadError}. */
+    open(sealed) {
+        if (!isSealed(sealed)) {
+            throw new PayloadError("payload is not a quiver-encrypted envelope");
+        }
+        const envelope = sealed[ENVELOPE_KEY];
+        if (typeof envelope !== "object" || envelope === null) {
+            throw new PayloadError("envelope is not an object");
+        }
+        const env = envelope;
+        if (env.v !== VERSION) {
+            throw new PayloadError(`unsupported envelope version: ${String(env.v)}`);
+        }
+        if (env.alg !== ALG) {
+            throw new PayloadError(`unsupported envelope algorithm: ${String(env.alg)}`);
+        }
+        const nonce = decodeField(env, "n");
+        if (nonce.length !== NONCE_LEN) {
+            throw new PayloadError(`nonce is ${nonce.length} bytes, expected ${NONCE_LEN}`);
+        }
+        const ciphertext = decodeField(env, "ct");
+        if (ciphertext.length < TAG_LEN) {
+            throw new PayloadError(`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 PayloadError("wrong key or tampered ciphertext");
+        }
+        return JSON.parse(new TextDecoder().decode(message));
+    }
+}
+/** Whether `value` carries a Quiver payload envelope. */
+export function isSealed(value) {
+    return typeof value === "object" && value !== null && ENVELOPE_KEY in value;
+}
+function decodeField(envelope, field) {
+    const raw = envelope[field];
+    if (typeof raw !== "string") {
+        throw new PayloadError(`missing envelope field '${field}'`);
+    }
+    return fromBase64(raw);
+}
+function randomBytes(length) {
+    const webcrypto = globalThis.crypto;
+    if (!webcrypto?.getRandomValues) {
+        throw new PayloadError("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/dist/index.d.ts

@@ -0,0 +1 @@
+export { Client, QuiverError, type Point, type Match, type Document, type DocumentMatch, type CollectionInfo, type IndexKind, type Metric, type ClientOptions, type CreateCollectionOptions, type SearchOptions, type SparseVector, type HybridSearchOptions, type TextPoint, type SearchTextOptions, type SnapshotInfo, } from "./client.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+export { Client, QuiverError, } from "./client.js";

package/dist/vector.d.ts

@@ -0,0 +1,26 @@
+/** The reserved payload key under which a sealed vector envelope is stored. */
+export declare const VECTOR_ENVELOPE_KEY = "__quiver_vec__";
+/** An error sealing or opening a client-side vector envelope. */
+export declare class VectorError extends Error {
+    constructor(message: string);
+}
+/** A client-held key for sealing and opening vector envelopes (ADR-0032). */
+export declare class VectorCipher {
+    #private;
+    private constructor();
+    /** Build a cipher from a raw 256-bit (32-byte) key. */
+    static fromBytes(key: Uint8Array): VectorCipher;
+    /** Build a cipher from a 64-character hex-encoded 256-bit key. */
+    static fromHex(hex: string): VectorCipher;
+    /** 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: ArrayLike<number>): Record<string, unknown>;
+    /** 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: unknown): number[];
+}
+/** Whether `value` carries a Quiver vector envelope. */
+export declare function isSealedVector(value: unknown): boolean;