@nexys/zk-store
v0.1.13
Published
Browser client for zk-store: zero-knowledge encrypted file storage. Files are encrypted before they leave the device.
Maintainers
Readme
@nexys/zk-store
Browser client for ZK Store: zero-knowledge encrypted file storage. Files are encrypted in the browser before they leave it; the server only stores ciphertext and wrapped keys.
Use it to build a web app on zk.nexys.io with no backend of your own. API reference: https://zk.nexys.io/docs.
npm install @nexys/zk-storeQuick start
import {
configure,
ensureCryptoReady,
createVault,
unlockWithRecoveryPhrase,
} from "@nexys/zk-store";
configure({ baseUrl: "https://zk.nexys.io" }); // the default; optional
await ensureCryptoReady(); // loads the WASM crypto
// A new vault. Show the phrase to the user: it is the only way back in.
const { vault, recoveryPhrase } = await createVault();
const id = await vault.upload("notes.txt", new TextEncoder().encode("hello"));
console.log(await vault.listFiles()); // [{ uuid, name, size, uploaded }]
// Later, or on another device:
const again = await unlockWithRecoveryPhrase(recoveryPhrase);
const { name, data } = await again.download(id); // data: ArrayBuffer
await again.delete(id);
again.lock();upload takes an ArrayBuffer, a Uint8Array or a Blob (a File from an
<input type="file"> works as is).
Sign in with ZK Store
Let users sign in with the ZK Store account and passkey they already have, like an SSO redirect: no new passkey, no new key, every browser.
// On page load:
const vault = await handleSignInRedirect(); // Vault after the redirect back, else null
// On your "Sign in with ZK Store" button:
await signInWithZkStore({ appName: "Acme Notes" }); // goes to zk.nexys.io and backOn zk.nexys.io the user signs in and approves your site. They come back to
the same page, and handleSignInRedirect() returns their vault. The vault
key travels only in the URL fragment (never sent to a server), encrypted to
a one-time key that exists only in your tab.
Using it from your site
zk.nexys.io accepts calls from any website (CORS), so your app can be frontend-only. That is safe: no auth is in cookies, and every call needs a token that only a holder of the vault key can get.
Passkeys work from any HTTPS site: pass the options from
registerOptions() / authenticateOptions() to navigator.credentials
unchanged. zk.nexys.io names your own domain as the relying party, so your
site gets passkeys of its own, in every browser, that no other site can
use. The recovery-phrase flow above works from any site too.
Loading the WASM
ensureCryptoReady() with no argument fetches zk_store_crypto_bg.wasm
from next to @nexys/zk-store-crypto's JS. Vite and webpack 5 copy that file
for you. With other bundlers, serve the file yourself (it is in
node_modules/@nexys/zk-store-crypto/pkg/) and pass its URL:
await ensureCryptoReady("/zk_store_crypto_bg.wasm");On a server runtime (Bun, Node, Deno), pass the bytes instead.
Lower-level API
Everything the ZK Store web app uses is exported too:
- Crypto:
generateKey,wrapKey/unwrapKey,encrypt/decrypt,deriveKey,deriveRecoveryKey,generateRecoveryPhrase, … - API calls:
openVault,getBlob/putBlob/deleteBlob, invites, passkey ceremonies, subscriptions, andclient, the typed openapi-fetch client. - File list:
loadTree,updateTree(retries on conflicts with other devices),loadFileList. - Sharing:
createShare,joinShare,downloadSharedFile, … for file and folder links.
The server's API is documented at /docs on any ZK Store server.
License
MIT
