Crypto engine reference

Reference for the production sodium engine, opaque key handles, algorithms, persisted formats, worker isolation, and deterministic test helpers.

@ownfold/crypto supplies the production CryptoEngine. It performs cryptographic operations but does not decide user identity, store vault state, make network requests, or render UI.

pnpm add @ownfold/core@beta @ownfold/crypto@beta

createSodiumCryptoEngine()

import { createSodiumCryptoEngine } from "@ownfold/crypto"

const cryptoEngine = createSodiumCryptoEngine()
const rootKey = await cryptoEngine.createRootKey()
if (rootKey.status === "error") return rootKey

The factory is synchronous; the returned engine initializes its crypto runtime lazily when an operation first needs it. Every fallible operation returns Result.

Key handles

RootKeyHandle and DeviceKeyHandle deliberately expose identity metadata, not private key bytes. The engine is the only component allowed to dereference their private material.

const created = await cryptoEngine.createRootKey()
if (created.status === "error") return created

try {
  // Pass the handle back to engine operations.
} finally {
  cryptoEngine.destroyRootKey(created.value)
}

After destroyRootKey, the handle reports destroyed: true and must not produce a successful operation. Destroying a handle reduces key lifetime; it does not erase ciphertext, Recovery Kits, or device envelopes.

Record encryption

encryptRecord:

1. generates a fresh record data key;
2. encrypts plaintext with XChaCha20-Poly1305;
3. authenticates vault ID, key version, encoding, namespace, record ID, and owner ID;
4. wraps the data key under the root key; and
5. returns a versioned envelope.

const encrypted = await cryptoEngine.encryptRecord({
  rootKey,
  vaultId: "vault_01",
  keyVersion: 1,
  context: {
    namespace: "documents",
    recordId: "doc_01",
    ownerId: "user_01",
  },
  encoding: "binary",
  plaintext: bytes,
})

decryptRecord requires the exact expected context and returns fresh Uint8Array plaintext only after format, context, and AEAD authentication succeed.

Data-key rewrapping

rewrapRecordDataKey opens only the wrapped record data key under the old root key and wraps it under the new root key. It returns a V2 envelope with the existing ciphertext and authenticated context. Application plaintext is never decrypted during rotation.

Recovery Kits

createRecoveryKit derives a wrapping key from the supplied secret using the parameters embedded in the kit and encrypts the root key locally. openRecoveryKit validates the structure, derives the same key, and returns an opaque root-key handle only after authentication succeeds.

Recovery failures intentionally do not reveal whether the secret, ciphertext, or authenticated metadata was wrong. Never upload the secret or file to diagnose them.

Device keys and envelopes

Device public keys and encrypted envelopes may cross the network. Device private keys and opened root handles must remain in local protected storage or memory.

Algorithms and format versions

The persisted value carries its own format, version, algorithm identifiers, nonce, salt, and authenticated context. Do not strip or replace those fields in database mappings.

Browser worker entry point

The worker entry point belongs to @ownfold/browser/worker, but it exposes the same production engine through a message boundary.

import { exposeOwnfoldCryptoWorker } from "@ownfold/browser/worker"

exposeOwnfoldCryptoWorker()

import { createVaultClient, createWorkerCryptoEngine } from "@ownfold/browser"

const worker = new Worker(
  new URL("../ownfold-crypto.worker.ts", import.meta.url),
  { type: "module" },
)

export const vault = createVaultClient({
  cryptoEngine: createWorkerCryptoEngine({ worker }),
  transport,
})

Worker isolation reduces accidental main-thread key exposure. Same-origin script compromise can still call an unlocked worker through the application, so keep CSP, dependency integrity, and automatic locking controls.

Testing entry point

Import deterministic helpers only from @ownfold/crypto/testing.

import {
  createDeterministicCryptoEngine,
  withEnvelopeVersionForTesting,
} from "@ownfold/crypto/testing"

Never ship the testing entry point in production. Exhausted or incorrectly sized deterministic input produces a typed crypto failure; it never falls back to insecure randomness.

Error surface

Operations return CryptoError, which includes invalid input, corrupted/authentication failures, unavailable key versions, Recovery Kit failures, and runtime failures. Handle them as values and destroy transient handles in cleanup paths. See Errors.