> ## Documentation Index
> Fetch the complete documentation index at: https://docs.everabyte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zero-Knowledge SDK

> Encrypt files and file names on your own infrastructure before they reach Everabyte — one protocol (evb-e2ee-v1), eight languages, validated against the official RFC and NIST test vectors.

The Everabyte Zero-Knowledge SDK is the client-side encryption library for
Everabyte integrations. It encrypts file contents and file names **on your
machine**, before any network call. For files processed through this SDK,
Everabyte's servers store opaque ciphertext and never receive the keys that
open it — there is no server-side decryption path and no key escrow.

This is the same protocol (`evb-e2ee-v1`) executed by the Everabyte web,
desktop and mobile apps. The SDK is a byte-exact, cross-language
implementation of that wire format: a file encrypted with one binding
decrypts with every other, and compatibility is enforced in CI through a
shared frozen test-vector grid plus the official test vectors of the
underlying standards.

## Which language, which mechanism

| Language | Install | Mechanism | Quickstart |
| - | - | - | - |
| **Node.js** | `npm install everabyte/crypto-sdk#path:bindings/wasm/pkg-node` (npm ≥ 9.4) | Prebuilt WASM — no toolchain | [Node.js](https://docs.everabyte.com/sdk/quickstart-nodejs.md) |
| **TypeScript / browser crypto** | `npm install everabyte/crypto-sdk#path:bindings/wasm/pkg` | Prebuilt WASM (ESM); browser code must call your backend for authenticated API operations | [TypeScript](https://docs.everabyte.com/sdk/quickstart-typescript.md) |
| **Rust** | `evb-e2ee-core = { git = "…/crypto-sdk.git", tag }` | Native crate | [Rust](https://docs.everabyte.com/sdk/quickstart-rust.md) |
| **Dart / Flutter** | pub git dependency `bindings/dart` + native library | FFI | [Dart](https://docs.everabyte.com/sdk/quickstart-dart.md) |
| **PHP 8+** | C ABI via the PHP FFI extension | FFI (`evb_e2ee.h`) | [PHP](https://docs.everabyte.com/sdk/quickstart-php.md) |
| **Java 22+** | C ABI via the Foreign Function & Memory API | FFI | [Java](https://docs.everabyte.com/sdk/quickstart-java.md) |
| **C# / .NET** | C ABI via P/Invoke | FFI | [C#](https://docs.everabyte.com/sdk/quickstart-csharp.md) |
| **Go** | C ABI via cgo | FFI | [Go](https://docs.everabyte.com/sdk/quickstart-golang.md) |

Repository: [everabyte/crypto-sdk](https://github.com/everabyte/crypto-sdk).
PHP, Java, C# and Go all speak the same stable **C ABI**
([reference](https://docs.everabyte.com/sdk/c-abi-reference.md)) — any other language with a C FFI can
integrate identically.

## How a zero-knowledge file flows

Every step below runs client-side except the two network calls, which only
carry ciphertext, opaque aliases and wrapped keys:

1. **Enroll once.** Generate the account key (UMK: X25519 secret 32 B +
   ML-KEM-768 seed 64 B) and a 12-word BIP-39 recovery phrase. Register the
   **public** keys and the **wrapped** copies: `POST /e2ee/keys/register`.
2. **Per file, generate a data key** (DEK, 32 random bytes) — it is never
   persisted anywhere.
3. **Encrypt the content** locally: AES-256-GCM in authenticated 64 KiB
   chunks (`EVB1` wire format).
4. **Name substitution**: the upload filename becomes a deterministic opaque
   alias (`evb-<hex64>`); the real name travels only as an AES-256-GCM blob
   under the DEK.
5. **Wrap the DEK** to the account key with HPKE (RFC 9180, mode PSK carrying
   the ML-KEM-768 shared secret), upload the ciphertext, and attach the
   envelope: `POST /e2ee/files/by-path/envelope`.
6. **Download** = fetch envelope + ciphertext, unwrap the DEK, decrypt
   locally. The restored file is byte-identical to the original.

If attaching the envelope fails, the file is not usable as a zero-knowledge file. On a timeout, reconcile the result using the returned file identifier and `GET /e2ee/files/{fileId}/envelope` before taking action. After a confirmed attach failure, the E2EE upload contract requires deleting the orphaned ciphertext row. Resolve its identifier from the bucket listing if necessary, confirm no envelope is attached, then hard-delete it through the file API; retention policy may prevent deletion and must be handled explicitly.

## Mandatory for new accounts

Accounts created on or after **2026-11-13** are zero-knowledge by default
(`zkRequired`). For these accounts:

* uploads **must** be client-encrypted — files that arrive unencrypted are
  **refused on download (403)** and swept after a grace window;
* the Everabyte apps enforce this natively; custom integrations enforce it by
  following the quickstarts above;
* legacy accounts keep the opt-in path — client-side encryption is optional
  and existing files migrate through the in-app controls
  ([migration](https://docs.everabyte.com/sdk/migration.md)).

## Standards conformance

| Purpose | Algorithm | Standard | Validated against |
| - | - | - | - |
| File content | AES-256-GCM, 64 KiB chunks, per-chunk AAD | NIST SP 800-38D | NIST GCM test vectors |
| File-key envelopes | HPKE mode PSK, DHKEM(X25519, HKDF-SHA256) + ML-KEM-768 | RFC 9180, FIPS 203 | Official RFC 9180 §A.1 vectors |
| Key derivation | HKDF-SHA256 (salt-less extract) | RFC 5869 | RFC test case 1 |
| Recovery-phrase KDF | Argon2id v1.3 (m = 64 MiB, t = 2, p = 1) | RFC 9106 | Cross-language grid |
| Recovery phrase | BIP-39 English, normalized before derivation | BIP-39 | SDK compatibility vectors; generate a fresh phrase for each user |

The HPKE key schedule is byte-exact against RFC 9180 §A.1.1/A.1.2 (both
sender and receiver side); the GCM/HKDF constructions match the official
published vectors. Compliance tests run in the SDK repository and fail the
build on any drift.

## What the SDK does — and what stays in your application

| In the SDK | In your application |
| - | - |
| Rust `EVB1` streaming encryption (AES-256-GCM, ≤ 1 chunk buffered); whole-buffer helpers are also available | HTTP calls, retries, authentication |
| DEK envelopes: HPKE v2 (RFC 9180 PSK) with legacy v1 dispatch | Key storage — keychain, KMS, HSM, encrypted vault |
| Recovery-phrase and device wraps; link/invite sharing wraps | Enrollment and upload orchestration |
| Opaque aliases + encrypted display names | UI, sharing policy decisions |
| Buffer zeroization; error messages contain no secrets | — |

The split is deliberate: your key custody model stays yours. The SDK never
opens a network connection and never logs key material. Browser code must not
contain an Everabyte secret API key; route authenticated REST calls through
your own backend. That backend can relay ciphertext and wrapped envelope data
without receiving the UMK, DEK or recovery phrase.

## What the model protects — and what it does not

**Protected:** the content and the names of zero-knowledge files, against
Everabyte's services, operators and infrastructure providers. No operator
console, maintenance job or database read can produce their plaintext. No
escrow: with every enrolled device **and** the recovery phrase lost, the data
is unreadable by anyone — including Everabyte.

**Not protected:**

* **Technical metadata** the product requires: file/folder sizes, timestamps,
  the folder tree, the sharing graph, quotas and access logs. Visible to the
  service in both encryption models.
* **Deliberate sharing.** A share recipient — or anyone holding a public
  link — holds the decryption key material for that file, by design.
* **A compromised device**, or a tampered client on it. Encryption happens
  where the SDK runs; protect the host.
* **The web app delivering its own code** — native bindings (this SDK)
  remove that dependency for custom integrations.
* **Recovery failure.** No enrolled device + no recovery phrase = no
  recovery. There is nothing for support to reset.

## Where to go next

> [card] [Node.js quickstart](https://docs.everabyte.com/sdk/quickstart-nodejs.md)
>
> Prebuilt WASM — no toolchain. Full upload/download round trip.

> [card] [TypeScript quickstart](https://docs.everabyte.com/sdk/quickstart-typescript.md)
>
> Browser-side encryption only. Use your backend for authenticated Everabyte API calls.

> [card] [Rust quickstart](https://docs.everabyte.com/sdk/quickstart-rust.md)
>
> Services and CLI tools, streaming included.

> [card] [Dart quickstart](https://docs.everabyte.com/sdk/quickstart-dart.md)
>
> Flutter and Dart via the native FFI binding.

> [card] [PHP / Java / C# / Go](https://docs.everabyte.com/sdk/c-abi-reference.md)
>
> One C ABI, four FFI paths — quickstarts for each.

> [card] [Wire protocol](https://docs.everabyte.com/sdk/protocol-reference.md)
>
> The `evb-e2ee-v1` format, envelopes, wraps and versioning policy.

> [card] [SDK API reference](https://docs.everabyte.com/sdk/api-reference.md)
>
> Every exported function of every binding.

> [card] [Migrating legacy files](https://docs.everabyte.com/sdk/migration.md)
>
> Moving existing server-encrypted files to zero-knowledge.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.