Module index_bundle 

Encrypted index bundles for the hosted Personal Index (GL #392).

Packs the locally built retrieval artifacts (bm25_index.bin.zst, embeddings.json from the project’s vector namespace) into one container, encrypts it client-side, and unpacks pulled bundles back into the namespace — so a fresh device gets working ctx_semantic_search without a local re-index.

Contract: docs/contracts/hosted-personal-index-v1.md.

Container format (LCIB1)

"LCIB1\n" | u32 LE manifest_len | manifest JSON | zstd(files payload)

Encryption

XChaCha20-Poly1305 with a 24-byte random nonce prepended to the ciphertext. The key is HKDF-SHA256-derived from the account API key — the backend stores that key only as a SHA-256 hash, so the server can never decrypt a bundle (true E2E for the operator threat model). Every logged-in device derives the same key with zero extra setup.

Structs

BundleFileEntry

BundleManifest

Enums

BundleError

Functions

decrypt

Decrypt nonce || ciphertext back into the plaintext container.

derive_key

Derive the per-account bundle key from the API key. The server only ever stores sha256(api_key), so this key is unknowable server-side.

encrypt

Encrypt a plaintext container. Output: nonce (24B) || ciphertext.

local_index_present

Whether this project has any bundleable index artifacts on disk — the cheap pre-check the background auto-push (GL #392) uses to skip silently instead of erroring through pack.

pack

Pack the project’s index artifacts into a plaintext LCIB1 container. Returns the container bytes and its manifest.

read_manifest

Parse a plaintext container without writing anything (manifest preview).

unpack

Unpack a plaintext container into the project’s vector namespace. Every file’s SHA-256 is verified before anything is written; writes are atomic (tmp + rename) so a torn pull can never corrupt a working local index.