Guide

Getting started

Install the package, pass in the libsodium your runtime has, and every function takes and returns Uint8Array.

Install

npm install @ezpriv/crypto

Runtimes

The package doesn't import libsodium. You pass in the one your runtime has:

Runtimelibsodium
React Native (iOS, Android)react-native-libsodium, imported as import * as sodium: its default export leaves out crypto_box_seal on native
React Native Web, browsers, service workerslibsodium-wrappers-sumo (or react-native-libsodium after loadSumoVersion())
Nodelibsodium-wrappers-sumo

The sumo build is needed for passwordKeys (Argon2id). In browsers, WebAssembly needs 'wasm-unsafe-eval' in the page's script-src.

Quick start

import sodium from "libsodium-wrappers-sumo";
import { createCrypto } from "@ezpriv/crypto";

await sodium.ready;
const ez = createCrypto(sodium);

// Sign-up: a key pair, and two ways to unlock it.
const user = ez.createUserKeys();
const salt = ez.newSalt();
const { keyP, authKey } = ez.passwordKeys({ password, salt });
const passwordWrap = ez.wrapKey({ key: user.privateKey, wrappingKey: keyP, userId, kind: "password" });
const words = ez.newRecoveryWords(); // show once
const recoveryWrap = ez.wrapKey({ key: user.privateKey, wrappingKey: ez.keyFromWords(words), userId, kind: "recovery" });
// Store user.publicKey, salt, passwordWrap and recoveryWrap on the server. Send authKey at sign-in, never the password.

// A group and its rows.
const groupKey = ez.newGroupKey();
const forMember = ez.sealGroupKey({ groupKey, groupId, publicKey: memberPublicKey });
const encrypted = ez.encryptRow({ value: bytes, groupKey, table: "expense", rowId });

// On the server: seal something only the user can read.
const sealed = ez.sealForUser({ value: bytes, context: "notification", publicKey: user.publicKey });

Encoding (base64, JSON) is up to the app. The examples show each of these in a full flow.

Concepts

The user's key pair

Each user has an X25519 key pair. The private key, called key_A, is what everything else depends on: it opens the user's group keys and every value sealed to them. The server stores the public key and never key_A.

Ways to unlock key_A

key_A is stored on the server only as wraps: encrypted copies under keys the server can't derive. Each wrap is bound to the user id and to its kind, so one can't pass for another.

KindWrapping keyExample
passwordkeyP, from Argon2id over the password01, 02
recoverykey_R, from 12 BIP-39 words03
passkey:<credentialId>key_F, from a passkey's PRF output04
another deviceplatform storage, or a QR link05, 11

Group keys and rows

A group (a trip, a flat) has a random 32-byte key, sealed to each member's public key. Rows are encrypted under it, each bound to its table and row id. Removing a member means a new key version for the members who stay.

Sealed values

Anyone with a user's public key can seal a value to it, and only the user opens it. The server uses this for incoming data and the sender's app for push notifications. A context such as movement or notification keeps one kind from passing for another.

Linking a browser

A new browser shows a QR code with a one-time public key and a secret. The phone seals the user's key pair for it. The secret goes from screen to camera, never to the server.

Errors

Every error is a plain Error whose message starts with ezpriv:, the same on every runtime, for example ezpriv: cannot decrypt or ezpriv: wrong context. See the API reference.

The format

Every ciphertext starts with the version byte 0x01. There are two kinds plus one composite:

KindBytesUsed by
Encrypted0x01 ‖ nonce (24) ‖ XChaCha20-Poly1305 ciphertext and tagwrapKey, encryptRow
Sealed0x01 ‖ crypto_box_seal(header ‖ payload)sealGroupKey, sealForUser
Linkedan Encrypted value under the QR secret, inside a Sealed boxsealForLink

The labels and fields bound into each kind, the derived keys and the Argon2id bounds are in SPEC.md, the source of truth for every port, checked by test vectors.

Other languages

The iOS Notification Service Extension and the Android notification service can't run JavaScript, so the repo has a small openSealed for each:

Development

pnpm install
pnpm test          # Vitest, including vectors/vectors.json
pnpm check-types
pnpm build         # dist/
pnpm examples      # every example, in order