Choose a surface

Browser in sixty seconds

import { VoidedE2EEClient } from "@voideddev/e2ee-client";

const client = new VoidedE2EEClient();
const artifact = await client.protect("Private browser data", {
  preset: "balanced",
});

const info = await client.inspectProtected(artifact);
const restored = await client.open(artifact);

console.log(info.preset, restored);

The stateful client creates or loads its key from IndexedDB. Inspection is structural only; treat every returned field as attacker-controlled until open succeeds.

Node.js in sixty seconds

import { generateKey, inspectArtifact, open, protect } from "@voideddev/enc-server";

const key = generateKey();
const { artifact } = protect(Buffer.from("Private server data"), key, {
  preset: "balanced",
  compressionAlgorithm: "brotli",
  encryptionAlgorithm: "xchacha20-poly1305",
});

console.log(inspectArtifact(artifact).preset);
console.log(open(artifact, key).toString("utf8"));
key.fill(0);

Release status

The source tree and docs are at 1.0.0 release-candidate state. macOS arm64 and Linux x64 native packages, browser WASM, CJS, and ESM paths have passed their release gates. The Windows x64 prebuild has verified provenance and hashes; real Windows execution is the final native gate before publication.

Choose the API

Answer three questions. The result updates to the smallest safe surface for your system.

Trace the artifact

Move through one payload. The owner, byte shape, and trust rule change at every boundary.

Compare Fuse presets

Presets change shell overhead and variation. They do not replace or strengthen the authenticated-encryption primitive.

const { artifact } = protect(data, key, {
  preset: "balanced",
});

Rotate recovery

Press rotate to see what changes. A recovery credential is a wrapper path to the stable root—not the root itself.

Real implementations

Layers

Utilities

Runtime matrix

Open a deep guide

When to use it

• Your plaintext is created or consumed in the browser.
• You want local IndexedDB-backed key persistence.
• You need the VOF3 monolith path through verified WASM.
• You want a neutral, customizable Recovery Deck setup component.

Do not move plaintext to a server merely to encrypt it there. Do not use browser storage as a substitute for account recovery, device custody, or cross-tab transaction coordination.

Stateful client

import { VoidedE2EEClient } from "@voideddev/e2ee-client";

const client = new VoidedE2EEClient();

const protectedBlob = await client.protect("Private data", {
  preset: "balanced",
});

// Metadata is not authenticated yet.
const preview = await client.inspectProtected(protectedBlob);

// Successful open authenticates the artifact.
const plaintext = await client.open(protectedBlob);

Top-level helpers

protect, open, inspectProtected, exportKey, importKey, and rotateKey operate through a default singleton client. Use them for small integrations; hold your own client instance when lifecycle ownership matters.

WASM behavior

Fuse, full-flow artifacts, bounded decompression, and Recovery Deck require the verified Rust/WASM runtime. The browser package does not silently replace those protocols with a TypeScript interpretation.

Use configureWasmLoader before initialization when your bundler or CDN needs an explicit artifact URL. A configured URL is locked to that initialization attempt; a failed configured load does not silently hunt for another binary.

Storage and lifecycle

Only a confirmed null read creates a first-use key. Storage errors fail closed and remain retryable. Each key-dependent operation revalidates persisted authority before taking a stable-key lease.

Fully compromised same-origin JavaScript can observe plaintext and usable keys. CSP, XSS prevention, dependency hygiene, and origin design are part of your security boundary.

Compression

High-level browser encryption defaults to compressionAlgorithm: "none". Compression can reveal secrets through ciphertext length when secret and attacker-controlled inputs share a context.

// Only when the whole plaintext has one trust boundary.
const blob = await client.encrypt(data, {
  compressionAlgorithm: "gzip",
});

Browser support

Voided 1.0 targets current Safari/WebKit and Chromium-based browsers. Firefox is best-effort and is not a release gate.

When to use it

• Plaintext already exists in a trusted Node.js process.
• You need native protected artifacts, hashing, compression, or recovery.
• You want CJS and ESM entry points over the same verified binary.

Protect and open

import { generateKey, inspectArtifact, open, protect } from "@voideddev/enc-server";

const key = generateKey();
try {
  const result = protect(Buffer.from("Private server data"), key, {
    preset: "balanced",
    compressionAlgorithm: "brotli",
    encryptionAlgorithm: "xchacha20-poly1305",
  });

  const structuralInfo = inspectArtifact(result.artifact);
  const restored = open(result.artifact, key);
} finally {
  key.fill(0);
}

The normal path returns a complete artifact. Raw encrypt/decrypt returns primitive AEAD fields and leaves outer serialization to you.

Native runtime

Supported release prebuilds are macOS arm64, Linux x64 GNU with glibc 2.34 or newer, and Windows x64 MSVC. The postinstall and runtime loaders verify the selected artifact against the release manifest before loading it.

npm --prefix packages/enc-server run verify:release:current
npm --prefix packages/enc-server run smoke:package:current
npm --prefix packages/enc-server run test:integration

Another architecture, C library, or older Linux distribution must build from the tagged source and run the native verification suite.

API layers

Add the crate

[dependencies]
voided-core = "1.0"

Use the exact tagged source until the crate is published.

Standard artifact

use voided_core::encryption::generate_key;
use voided_core::shell::{
    inspect_artifact, open, protect, FusedPreset, ProtectOptions,
};

let key = generate_key();
let protected = protect(
    b"hello monolith world",
    &key,
    Some(ProtectOptions {
        preset: FusedPreset::Balanced,
        ..ProtectOptions::default()
    }),
)?;

let info = inspect_artifact(&protected.artifact)?;
let restored = open(&protected.artifact, &key)?;

Feature flags

The mental model

1. Optionally compress under an explicit policy.
2. Encrypt with authenticated encryption.
3. Shape the complete plan into the VOF3 artifact.
4. On open, validate structure and bounds before expensive work.
5. Authenticate before releasing plaintext.

Choose the API layer

Inspection

inspectFused and inspectArtifact parse structural metadata without a key. This is useful for routing, size display, and format introspection—but it is not proof.

Presets

• compact — lowest shell overhead.
• balanced — general-purpose default.
• concealed — heavier shape variation.

Presets do not upgrade the entropy of weak key material. Measure size and performance on your corpus before moving away from balanced.

Version stability

Package version 1.0 and wire-format version 3 are deliberately independent. VOF3 is the frozen authenticated byte format used by the first stable package release. Legacy readers exist for explicit migration; current writers produce VOF3.

The recovery flow

1. Validate exactly 52 canonical cards, each exactly once.
2. Rank the permutation into exactly 29 big-endian bytes.
3. Derive 32 bytes with domain-separated HKDF-SHA256.
4. Use that key to unwrap the stable 32-byte root.
5. Clear deck and derived-key copies as soon as the flow ends.

What to persist

Node.js setup and rotation

import {
  createRecoveryDeck,
  deriveRecoveryKey,
  rotateRecoveryDeck,
  unwrapRootWithRecoveryKey,
} from "@voideddev/enc-server";

const setup = createRecoveryDeck(stableRoot);
await displayForPhysicalBackup(setup.deck);
await saveOpaqueWrapper(setup.rootWrapper);

// Later: reconstruct the same root.
const recoveryKey = deriveRecoveryKey(enteredDeck);
const root = unwrapRootWithRecoveryKey(savedWrapper, recoveryKey);

// Secure rotation creates a wholly new random deck.
const next = rotateRecoveryDeck(savedWrapper, enteredDeck);

Browser UI

The optional framework-free component opens as a modal with show() or mounts inline with mount(container). It supports card movement and a fresh secure shuffle; it does not impose a manual 52-card construction flow.

import { createRecoveryDeckUI } from "@voideddev/e2ee-client";

const deckUI = createRecoveryDeckUI({
  rootClassName: "my-recovery-theme",
  injectDefaultStyles: false,
  onConfirm: async (deck) => {
    await wrapAndSaveStableRoot(deck);
  },
});

await deckUI.show();       // modal
// await deckUI.mount(main); // inline or full-page composition

Use classNames, labels, renderCardContent, stable data attributes, or a fully application-owned stylesheet. Voided owns behavior; your product owns the experience.

Threats that matter

Brute force is not the practical concern. Screenshots, recording, photographs, clipboard exposure, malware, telemetry, crash reports, browser persistence, accidental sync, weak RNG, and memory copies are.

An attacker holding both an old deck and an offline copy of its old wrapper can still recover that old root. Rotation invalidates the active wrapper; it cannot revoke every copied historical wrapper in the world.

Do this

• Prefer XChaCha20-Poly1305 unless interoperability requires AES-256-GCM.
• Treat keyless inspection as attacker-controlled metadata.
• Use protect/open for normal application artifacts.
• Zeroize mutable secret buffers after use.
• Keep one browser lifecycle writer per key ID.
• Keep Recovery Deck material out of logs, storage, analytics, and crash reports.
• Run package integrity and current-platform smoke checks in release automation.

Do not do this

• Do not authorize based on inspectArtifact output.
• Do not reuse an AES-GCM nonce with the same key.
• Do not assume a 256-bit KDF output adds entropy to weak input.
• Do not enable compression across mixed attacker-controlled and secret values.
• Do not interpret grouped fingerprints as an identity-binding safety-number protocol.
• Do not treat browser IndexedDB as account recovery.

Failure behavior

Wrong keys, malformed structure, non-canonical inputs, oversized work, tampered tags, invalid algorithms, and unavailable required backends throw. Authenticated decryption does not stream plaintext before the tag verifies.

Report a vulnerability

Use a private GitHub Security Advisory for suspected vulnerabilities. Include the affected package and version, platform, minimal reproduction, security impact, and whether any secret material was exposed. Do not post exploitable details in a public issue.

Run focused checks

Choose the failing runtime and boundary. This produces commands, not a fake issue report. You decide what evidence is relevant after you see the output.

Compatibility

Safe support boundary

Public integration failures belong in a minimal issue. Suspected vulnerabilities belong in a private security advisory.