Encrypted document store for TypeScript. Documents are encrypted end-to-end using XSalsa20-Poly1305 (TweetNaCl). Metadata is stored as plaintext so you can list, sort, and filter without decrypting every document. The encryption key never touches storage — only encrypted blobs and plaintext metadata do.
Works in Node.js, browsers, and React Native via swappable storage adapters.
Repository: github.com/devgeeks/smugrobot · Issues
npm install @smugrobot/echidnaimport { createEncryptedStore } from "@smugrobot/echidna";
import { memoryAdapter } from "@smugrobot/echidna/adapters/memory";
const store = await createEncryptedStore({
adapter: memoryAdapter(),
keySource: { type: "passphrase", passphrase: "my secret passphrase" },
});
// Write
await store.set("note-1", "This is stored encrypted.", {
title: "My first note",
tags: ["personal"],
});
// Read
const body = await store.get("note-1"); // decrypted string
const meta = await store.getMeta("note-1"); // plaintext metadata, no decryption
// List without decrypting
const all = await store.list();
const work = await store.list({ tags: ["work"] });Import only the adapter you need — each is a separate bundle entry so unused adapters are never included.
No dependencies. Works everywhere. Primarily useful for testing.
import { memoryAdapter } from "@smugrobot/echidna/adapters/memory";
const adapter = memoryAdapter();Stores each key as a file under a root directory. No extra dependencies.
import { nodeFsAdapter } from "@smugrobot/echidna/adapters/node-fs";
const adapter = nodeFsAdapter("./my-vault");import { localStorageAdapter } from "@smugrobot/echidna/adapters/localstorage";
const adapter = localStorageAdapter(); // prefix defaults to 'echidna:'
const adapter = localStorageAdapter("myapp:vault:"); // custom prefixLike the IndexedDB adapter below, this requests persistent storage on init — see that section for details.
Async, binary-native storage with much higher quotas than localStorage (typically up to ~60% of available disk). Requires no encoding overhead — Uint8Array values are stored directly.
import { indexedDbAdapter } from "@smugrobot/echidna/adapters/indexeddb";
const adapter = await indexedDbAdapter(); // db 'echidna', store 'vault'
const adapter = await indexedDbAdapter("myapp", "documents"); // custom db and store namesOn init, the adapter calls navigator.storage.persist() to request exemption from the browser's automatic "best-effort" storage eviction (which can otherwise clear IndexedDB data under disk pressure — Safari is particularly aggressive here). This is best-effort: the call is skipped where unsupported (e.g. Safari doesn't implement the API) and never throws if the browser declines the request. It does not protect against a user explicitly clearing site data or uninstalling the app.
Binary-native filesystem storage for Expo apps. No size constraints beyond device storage, and no base64 overhead — Uint8Array values are written directly to disk. Requires expo-file-system v17+ as a peer dependency.
import { expoFileSystemAdapter } from "@smugrobot/echidna/adapters/expo-file-system";
import * as FileSystem from "expo-file-system";
const adapter = expoFileSystemAdapter(FileSystem.documentDirectory + "vault/");Stores the encrypted vault as files in a Dropbox app folder, enabling multi-device access without exposing plaintext to Dropbox. The vault is encrypted before it leaves the device — Dropbox only ever sees opaque blobs.
Requires a Dropbox app configured with the files.content.write and files.content.read permissions and a redirect URI for your app.
Note: Dropbox is case-insensitive. Document IDs that differ only by case will collide.
Privacy warning: metadata (
title,tags, and any custom fields) is stored as plaintext, unauthenticated JSON. A compromised Dropbox account can read it and write arbitrary values into it. Treat every metadata field as untrusted input in your UI — never pass it toinnerHTMLor an equivalent unescaped-HTML sink.
import {
dropboxAdapter,
generatePkce,
getDropboxAuthUrl,
exchangeDropboxCode,
refreshDropboxToken,
} from "@smugrobot/echidna/adapters/dropbox";
import { createEncryptedStore } from "@smugrobot/echidna";
// Step 1 — redirect the user to Dropbox for authorization (run once)
const { verifier, challenge } = await generatePkce();
sessionStorage.setItem("pkce_verifier", verifier);
const authUrl = getDropboxAuthUrl({
clientId: "YOUR_APP_KEY",
redirectUri: "https://yourapp.example.com/callback",
codeChallenge: challenge,
state: crypto.randomUUID(), // optional CSRF token
});
window.location.href = authUrl;
// Step 2 — handle the redirect callback
const params = new URLSearchParams(window.location.search);
const tokens = await exchangeDropboxCode({
clientId: "YOUR_APP_KEY",
redirectUri: "https://yourapp.example.com/callback",
code: params.get("code")!,
codeVerifier: sessionStorage.getItem("pkce_verifier")!,
});
// Persist tokens.accessToken and tokens.refreshToken in your app
// Step 3 — open the vault
const store = await createEncryptedStore({
adapter: dropboxAdapter({
accessToken: tokens.accessToken,
rootPath: "/MyApp", // created inside the Dropbox app folder
}),
keySource: { type: "passphrase", passphrase: userPassphrase },
});To refresh an expired access token:
const fresh = await refreshDropboxToken({
clientId: "YOUR_APP_KEY",
refreshToken: tokens.refreshToken!,
});No SDK dependency — the adapter uses fetch and crypto.subtle directly.
Wraps a PouchDB instance you construct and own, so it can double as the local half of a .sync() against a remote CouchDB server. Values are stored as real CouchDB attachments (not inline base64 fields), so they replicate efficiently and stay interoperable with other CouchDB tooling inspecting the database.
pouchdb is a peer dependency — install it separately (pouchdb, pouchdb-browser, pouchdb-node, or a React Native build, whichever matches your environment).
In browsers, pouchdb-browser is typically backed by IndexedDB, so this adapter also requests persistent storage on init — see the IndexedDB section above for what that does and doesn't protect against.
Note: @smugrobot/echidna only implements local storage through this adapter. Remote sync — the CouchDB URL, auth, live replication, retry policy — is your app's responsibility, driven directly against the same PouchDB instance you pass in.
Privacy warning: syncing does not make document metadata private.
docs/{id}/meta(title, tags, timestamps, size, and any custom fields) is always stored as plaintext JSON — by design, so lists can be filtered without decrypting bodies — and it is unauthenticated, so a malicious or compromised CouchDB server can read and silently rewrite it. Onlydocs/{id}/bodyis encrypted and MAC-protected; tampering with a body fails loudly (WRONG_KEY), and moving one document's body onto another id is caught by the id binding (TAMPERED). What is not protected: a hostile server operator can see attachment sizes and write timing, can withhold documents, and can roll a body (and its metadata) back to an earlier version of the same document undetectably — there is no vault-level integrity check or version anchor across the whole sync. Don't put anything sensitive intitle,tags, or custom metadata fields if you don't trust the CouchDB server operator. The same server can also write arbitrary values into those fields, so any UI that renders them must treat them as untrusted input — never pass them toinnerHTMLor an equivalent unescaped-HTML sink.
import PouchDB from "pouchdb";
import { pouchDbAdapter } from "@smugrobot/echidna/adapters/pouchdb";
import { createEncryptedStore } from "@smugrobot/echidna";
const db = new PouchDB("my-vault");
const store = await createEncryptedStore({
adapter: pouchDbAdapter(db),
keySource: { type: "passphrase", passphrase: userPassphrase },
});
// Not part of @smugrobot/echidna — wire up sync yourself against the same `db`.
const remote = new PouchDB("https://couchdb.example.com/my-vault", {
auth: { username: "user", password: "pass" },
});
db.sync(remote, { live: true, retry: true });@react-native-async-storage/async-storage is a peer dependency — install it separately in your app.
import { asyncStorageAdapter } from "@smugrobot/echidna/adapters/async-storage";
const adapter = asyncStorageAdapter();A passphrase is derived into a key using scrypt (default) or PBKDF2. KDF parameters are stored in the vault so the same parameters are always used when reopening.
// scrypt (default, recommended)
{ type: 'passphrase', passphrase: 'my secret' }
// PBKDF2
{ type: 'passphrase', passphrase: 'my secret', kdf: 'pbkdf2' }Supply a 32-byte Uint8Array directly. You are responsible for key management.
import nacl from 'tweetnacl'
{ type: 'raw', key: nacl.randomBytes(32) }Creates or opens a vault. If the adapter already contains a vault, it is opened with the provided key source. If not, a new vault is initialised.
const store = await createEncryptedStore({
adapter: nodeFsAdapter("./vault"),
keySource: { type: "passphrase", passphrase: "hunter2" },
});Encrypts and writes a document. Generates a fresh nonce on every write. Returns the updated DocMeta.
On overwrite, createdAt is preserved and updatedAt is bumped.
The id becomes a segment in the adapter's key namespace, so it must be a
non-empty string that does not contain / or control characters and is not .
or ... Invalid ids throw EchidnaJsError('INVALID_ID') (from every id-taking
method). Use opaque ids such as UUIDs; keep any human-readable label in title.
const meta = await store.set("doc-id", "plaintext body", {
title: "My document",
tags: ["work", "draft"],
// any extra fields are stored in metadata
priority: "high",
});Decrypts and returns the document body, or null if the id does not exist.
Throws EchidnaJsError with code WRONG_KEY if decryption fails.
const body = await store.get("doc-id"); // string | nullReturns plaintext metadata without decrypting the body, or null if the id does not exist.
const meta = await store.getMeta("doc-id"); // DocMeta | nullUpdates metadata fields without re-encrypting the body. The body blob is untouched.
await store.updateMeta("doc-id", { title: "New title", tags: ["archived"] });Deletes both the encrypted body and the plaintext metadata.
await store.delete("doc-id");Returns all DocMeta records, optionally filtered. Never decrypts any body.
const all = await store.list();
const work = await store.list({ tags: ["work"] });
const today = await store.list({ since: Date.now() - 86_400_000 });
const range = await store.list({ since: startMs, until: endMs });Permanently deletes all documents and vault keys from the adapter. Irreversible.
await store.destroy();Returns true if the vault predates the current on-disk format and should be
upgraded with migrate(). Cheap — a single vault/version read.
if (await store.needsMigration()) await store.migrate();Upgrades legacy 0x01 document bodies to the current 0x02 format (see
Upgrading from 0.1.0). Idempotent and resumable; returns
counts of bodies scanned and upgraded.
const { scanned, upgraded } = await store.migrate();echidna 0.1.0 wrote body blobs in the 0x01 format, which did not bind the
document id into the ciphertext. The current format (0x02) does, so ordinary
reads reject 0x01 blobs with EchidnaJsError('NEEDS_MIGRATION') until they are
upgraded. The vault key is unchanged between the two formats, so migration is a
one-time re-encryption — no passphrase re-entry or key derivation.
Run it once, right after opening the vault:
const store = await createEncryptedStore({ adapter, keySource });
if (await store.needsMigration()) {
const { upgraded } = await store.migrate();
console.log(`Upgraded ${upgraded} document(s) to the 0x02 format`);
}migrate() rewrites only body blobs (metadata, including createdAt /
updatedAt, is untouched), skips already-0x02 bodies, and is safe to re-run if
interrupted — the vault/version marker is only advanced after a full pass.
Run migration on trusted storage. Migration binds the id going forward but cannot audit the past: it re-binds whatever plaintext currently sits at
docs/{id}/body. If a0x01vault was tampered with while its bodies were still unbound (e.g. two were swapped), that is laundered into an authenticated0x02blob. Migrate while the vault is local/trusted, before syncing to an untrusted backend, and run it single-flight before other writers touch the vault.
interface DocMeta {
id: string;
title: string;
createdAt: number; // Unix ms
updatedAt: number; // Unix ms
tags?: string[];
size?: number; // byte length of plaintext UTF-8
[key: string]: unknown; // caller-defined fields
}
interface ListOptions {
tags?: string[];
since?: number; // createdAt >= since
until?: number; // createdAt <= until
}All errors thrown by @smugrobot/echidna are instances of EchidnaJsError:
import { EchidnaJsError } from "@smugrobot/echidna";
try {
await store.get("doc-id");
} catch (e) {
if (e instanceof EchidnaJsError) {
console.error(e.code); // 'WRONG_KEY' | 'CORRUPT_BLOB' | 'NOT_FOUND' | ...
}
}| Code | When |
|---|---|
WRONG_KEY |
Decryption failed — wrong key or corrupted ciphertext |
CORRUPT_BLOB |
Encrypted blob is malformed or has an unknown version byte |
TAMPERED |
Blob decrypted cleanly but is bound to a different document id (body substituted from another document) |
NEEDS_MIGRATION |
Body is a legacy 0x01 blob — call store.migrate() to upgrade the vault |
INVALID_ID |
Document id is empty, contains / or a control character, or is ./.. |
NOT_FOUND |
Document id does not exist (only from updateMeta) |
KDF_FAILED |
Key derivation threw an unexpected error |
INVALID_KDF_PARAMS |
KDF params (read from vault/kdf) are malformed or out of bounds |
VAULT_NOT_FOUND |
Adapter has no vault initialised |
- Cipher: XSalsa20-Poly1305 via
nacl.secretbox - Key derivation: scrypt (
N=131072, r=8, p=1) or PBKDF2 (600,000 iterations, SHA-256) - Salt: 16 random bytes, generated once at vault creation, stored plaintext
- Nonce: 24 random bytes, generated fresh on every write, prepended to the ciphertext blob
- Document binding: each body is encrypted with its document id as additional authenticated data (see blob format). A body moved or relabelled to another document — e.g. by a compromised storage backend swapping two blobs — decrypts under the vault key but fails its id check, surfaced as
EchidnaJsError('TAMPERED'). This does not prevent rolling a body back to an earlier version of the same document (there is no trusted version anchor). - Version byte is unauthenticated: it sits outside the MAC, so a compromised backend can flip a
0x02body to0x01, denying reads (NEEDS_MIGRATION) until re-migrated;migrate()detects the flip and repairs the body in place instead of laundering it into a corrupted, MAC-valid0x02blob. - Wrong key detection:
nacl.secretbox.openreturnsnull— surfaced asEchidnaJsError('WRONG_KEY'). Garbage is never returned. - What is never stored: the key, the passphrase, or any derivative that would allow offline verification
- Metadata is untrusted input:
DocMetafields are plaintext and unauthenticated by design, so lists can be filtered without decrypting bodies. When a vault is synced through a backend you don't fully trust (see the Dropbox and CouchDB/PouchDB sections above), that backend can write arbitrary values intotitle,tags, or custom fields — consuming UIs must treat every metadata field as attacker-controllable, unescaped input.
[ 0x02 ][ nonce: 24 bytes ][ ciphertext: N bytes ]
The ciphertext is nacl.secretbox over the authenticated message
[ uint32BE(idLen) ][ id ][ plaintext ], so the document id is bound into the
MAC. The version byte distinguishes format revisions; 0x02 blobs are not
backward compatible with the original 0x01 format (which omitted the id
binding), and 0x01 blobs now surface as CORRUPT_BLOB.
vault/salt → 16 raw bytes (plaintext)
vault/kdf → JSON (plaintext): KDF algorithm and parameters
vault/version → JSON (plaintext): on-disk format version (for migration)
docs/{id}/meta → JSON (plaintext): title, tags, timestamps, size
docs/{id}/body → binary (encrypted blob)
Implement the StorageAdapter interface to use any backend:
import type { StorageAdapter } from '@smugrobot/echidna'
const myAdapter: StorageAdapter = {
async get(key: string): Promise<Uint8Array | null> { ... },
async set(key: string, value: Uint8Array): Promise<void> { ... },
async delete(key: string): Promise<void> { ... },
async list(prefix?: string): Promise<string[]> { ... },
}Keys use forward-slash namespacing (vault/salt, docs/abc/meta). The list method must return all keys that start with the given prefix, or all keys when prefix is omitted or empty.
Adapters that use text-only backends (like localStorage or AsyncStorage) should encode Uint8Array values as base64 internally.
MIT