@weaveprotocol/core 0.1.0

package/dist/storage/directory-access.js

@@ -0,0 +1,164 @@
+/**
+ * @module directory-access
+ * Getting hold of the user's data folder, and getting it back on the next visit.
+ *
+ * A directory handle is the one capability a web page can hold that outlives the
+ * origin sandbox, so the browser guards it carefully: it can only be obtained
+ * from a user gesture, and permission has to be re-confirmed when a new session
+ * starts. The handle itself is structured-cloneable, which means it can be kept
+ * in IndexedDB — origin-local storage of a *pointer* to origin-independent data.
+ */
+import { protocolError } from '../utils/errors.js';
+const HANDLE_DB = 'weave-folder';
+const HANDLE_STORE = 'handles';
+const HANDLE_KEY = 'data-folder';
+/**
+ * Whether this browser can hand out a directory at all.
+ *
+ * Chrome, Edge and Opera on the desktop can. Firefox and Safari cannot, and
+ * neither can any mobile browser, so a caller has to have something else to
+ * offer — this returning false is a normal state, not a broken one.
+ *
+ * @returns Whether {@link pickDataFolder} will work here
+ */
+export function isFolderStorageAvailable() {
+    return typeof globalThis.showDirectoryPicker === 'function';
+}
+/**
+ * Asks the user to choose their data folder. Must be called from a click.
+ *
+ * @param options.id Groups the picker's memory of where it last opened. Keeping
+ *   this stable across apps means the second view of the same data opens the
+ *   picker already pointing at the right folder.
+ * @returns The chosen directory
+ */
+export async function pickDataFolder(options) {
+    const picker = globalThis.showDirectoryPicker;
+    if (!picker) {
+        throw protocolError('FOLDER_UNAVAILABLE', 'This browser cannot open a data folder.', 'The File System Access API is available in Chrome, Edge and Opera on the ' +
+            'desktop. Elsewhere, sign in with a recovery code and this device will ' +
+            'keep its own copy that syncs with your peers.');
+    }
+    return picker({ id: options?.id ?? 'weave-pod', mode: 'readwrite', startIn: 'documents' });
+}
+/**
+ * Asks what this origin is currently allowed to do with a folder.
+ * @param handle The directory in question
+ * @param mode The access being asked about
+ * @returns `granted`, `denied`, or `prompt` when the user has yet to be asked
+ */
+export async function queryFolderPermission(handle, mode = 'readwrite') {
+    const query = handle.queryPermission;
+    if (!query)
+        return 'granted'; // a handle from a runtime without the extension
+    return query.call(handle, { mode });
+}
+/**
+ * Makes sure this origin may use a folder, prompting if it has to.
+ *
+ * The prompt needs a user gesture, so `request` should only be true on a path
+ * that began with a click — call it with `false` on page load to find out
+ * whether a button needs showing at all.
+ *
+ * @param handle The directory to check
+ * @param options.request Whether to prompt when permission is not already given
+ * @param options.mode The access needed
+ * @returns Whether the folder is usable
+ */
+export async function ensureFolderPermission(handle, options) {
+    const mode = options?.mode ?? 'readwrite';
+    if ((await queryFolderPermission(handle, mode)) === 'granted')
+        return true;
+    if (!options?.request)
+        return false;
+    const request = handle.requestPermission;
+    if (!request)
+        return false;
+    return (await request.call(handle, { mode })) === 'granted';
+}
+/**
+ * Opens the tiny database that remembers which folder this origin was pointed at.
+ * @returns The database
+ */
+function openHandleDb() {
+    return new Promise((resolve, reject) => {
+        const request = globalThis.indexedDB.open(HANDLE_DB, 1);
+        request.onupgradeneeded = () => {
+            if (!request.result.objectStoreNames.contains(HANDLE_STORE)) {
+                request.result.createObjectStore(HANDLE_STORE);
+            }
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+/**
+ * Remembers a folder so the next visit can skip the picker.
+ *
+ * Only the handle is stored, never the contents — this origin keeps a pointer,
+ * and the data stays where the user put it.
+ *
+ * @param handle The directory to remember
+ */
+export async function rememberDataFolder(handle) {
+    const db = await openHandleDb();
+    try {
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction(HANDLE_STORE, 'readwrite');
+            tx.objectStore(HANDLE_STORE).put(handle, HANDLE_KEY);
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * The folder this origin used last, if the browser still has it.
+ *
+ * Says nothing about permission — a recalled handle usually needs
+ * {@link ensureFolderPermission} with a gesture before it can be read.
+ *
+ * @returns The remembered directory, or null
+ */
+export async function recallDataFolder() {
+    try {
+        const db = await openHandleDb();
+        try {
+            return await new Promise((resolve, reject) => {
+                const tx = db.transaction(HANDLE_STORE, 'readonly');
+                const request = tx.objectStore(HANDLE_STORE).get(HANDLE_KEY);
+                request.onsuccess = () => resolve(request.result ?? null);
+                request.onerror = () => reject(request.error);
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return null;
+    }
+}
+/** Forgets the remembered folder. The folder and everything in it stay put. */
+export async function forgetDataFolder() {
+    try {
+        const db = await openHandleDb();
+        try {
+            await new Promise((resolve, reject) => {
+                const tx = db.transaction(HANDLE_STORE, 'readwrite');
+                tx.objectStore(HANDLE_STORE).delete(HANDLE_KEY);
+                tx.oncomplete = () => resolve();
+                tx.onerror = () => reject(tx.error);
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        // Nothing to forget.
+    }
+}
+//# sourceMappingURL=directory-access.js.map

package/dist/storage/directory-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-access.js","sourceRoot":"","sources":["../../src/storage/directory-access.ts"],"names":[],"mappings":"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"}

package/dist/storage/encrypted-adapter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @module encrypted-adapter
+ * Encryption at rest for the parts of a store that would otherwise give the
+ * whole folder away.
+ *
+ * A private space encrypts every body before signing, which protects it from
+ * the relay and from peers who were never invited. It does not protect it from
+ * anyone holding the folder, because the AES key for that space is written into
+ * the same store as the ciphertext it opens. This closes that: the space key and
+ * the space record go in sealed under a key derived from the account seed, so
+ * they are readable only once the folder has actually been unlocked.
+ *
+ * Scoped deliberately narrowly. Expressions and MST nodes pass straight through:
+ * their bodies are already encrypted where it matters, they are content
+ * addressed, and sealing them would cost the property that makes a folder worth
+ * having — that you can open it and see what is in it. What stays legible is
+ * each record's author, timestamp and collection, plus anything in a space its
+ * owner made public.
+ */
+import type { StorageAdapter } from '../types.js';
+/**
+ * What gets sealed by default: the space registry — each space, its key, and
+ * the write secret of a shared one — and nothing else.
+ *
+ * A prefix match, so each must end in its colon: `space:` does not cover
+ * `spaceinvite:`, and an invite secret left out here is anyone-with-the-folder
+ * joining a space in your place.
+ */
+export declare const DEFAULT_ENCRYPTED_PREFIXES: ReadonlyArray<string>;
+export interface EncryptedAdapterOptions {
+    /** Key prefixes whose values are sealed. Defaults to {@link DEFAULT_ENCRYPTED_PREFIXES}. */
+    readonly prefixes?: ReadonlyArray<string>;
+}
+/**
+ * Wraps a storage adapter so that selected values are encrypted on the way in
+ * and decrypted on the way out.
+ *
+ * Each value is bound to its storage key (it is the AES-GCM additional data),
+ * so sealed values cannot be swapped between entries. A value under a sealed
+ * prefix that was not sealed is refused, not trusted: anyone who can write the
+ * folder could otherwise plant a space, or a key, in the clear.
+ *
+ * @param inner The adapter doing the actual storing
+ * @param key An AES-GCM key, from `deriveVaultKey`
+ * @param options Which keys to seal
+ * @returns An adapter with the same contract
+ */
+export declare function createEncryptedAdapter(inner: StorageAdapter, key: CryptoKey, options?: EncryptedAdapterOptions): StorageAdapter;
+//# sourceMappingURL=encrypted-adapter.d.ts.map

package/dist/storage/encrypted-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encrypted-adapter.d.ts","sourceRoot":"","sources":["../../src/storage/encrypted-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAW,MAAM,aAAa,CAAC;AAa3D;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,aAAa,CAAC,MAAM,CAAyD,CAAC;AAEvH,MAAM,WAAW,uBAAuB;IACtC,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC3C;AAQD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,SAAS,EACd,OAAO,CAAC,EAAE,uBAAuB,GAChC,cAAc,CAoEhB"}

package/dist/storage/encrypted-adapter.js

@@ -0,0 +1,106 @@
+/**
+ * @module encrypted-adapter
+ * Encryption at rest for the parts of a store that would otherwise give the
+ * whole folder away.
+ *
+ * A private space encrypts every body before signing, which protects it from
+ * the relay and from peers who were never invited. It does not protect it from
+ * anyone holding the folder, because the AES key for that space is written into
+ * the same store as the ciphertext it opens. This closes that: the space key and
+ * the space record go in sealed under a key derived from the account seed, so
+ * they are readable only once the folder has actually been unlocked.
+ *
+ * Scoped deliberately narrowly. Expressions and MST nodes pass straight through:
+ * their bodies are already encrypted where it matters, they are content
+ * addressed, and sealing them would cost the property that makes a folder worth
+ * having — that you can open it and see what is in it. What stays legible is
+ * each record's author, timestamp and collection, plus anything in a space its
+ * owner made public.
+ */
+import { concatBytes } from '../utils/encoding.js';
+/**
+ * Marks a value this module wrote.
+ *
+ * Without it there is no way to tell ciphertext from a value stored before the
+ * folder had a lock, and "try to decrypt, fall back to raw on failure" turns
+ * every genuine key mismatch into silently wrong data.
+ */
+const MAGIC = new Uint8Array([0x77, 0x65, 0x61, 0x76, 0x65, 0x65, 0x02, 0x00]); // "weavee\x02\x00" — Weave, encrypted, v2
+const IV_BYTES = 12;
+/**
+ * What gets sealed by default: the space registry — each space, its key, and
+ * the write secret of a shared one — and nothing else.
+ *
+ * A prefix match, so each must end in its colon: `space:` does not cover
+ * `spaceinvite:`, and an invite secret left out here is anyone-with-the-folder
+ * joining a space in your place.
+ */
+export const DEFAULT_ENCRYPTED_PREFIXES = ['space:', 'spacekey:', 'spaceinvite:', 'spacerole:'];
+/** Whether these bytes were written sealed. */
+function isSealed(bytes) {
+    if (bytes.length < MAGIC.length + IV_BYTES)
+        return false;
+    return MAGIC.every((byte, index) => bytes[index] === byte);
+}
+/**
+ * Wraps a storage adapter so that selected values are encrypted on the way in
+ * and decrypted on the way out.
+ *
+ * Each value is bound to its storage key (it is the AES-GCM additional data),
+ * so sealed values cannot be swapped between entries. A value under a sealed
+ * prefix that was not sealed is refused, not trusted: anyone who can write the
+ * folder could otherwise plant a space, or a key, in the clear.
+ *
+ * @param inner The adapter doing the actual storing
+ * @param key An AES-GCM key, from `deriveVaultKey`
+ * @param options Which keys to seal
+ * @returns An adapter with the same contract
+ */
+export function createEncryptedAdapter(inner, key, options) {
+    const prefixes = options?.prefixes ?? DEFAULT_ENCRYPTED_PREFIXES;
+    const shouldSeal = (storageKey) => prefixes.some((prefix) => storageKey.startsWith(prefix));
+    const bound = (storageKey) => new TextEncoder().encode(storageKey);
+    async function seal(storageKey, value) {
+        const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_BYTES));
+        const ciphertext = await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv: iv, additionalData: bound(storageKey) }, key, value);
+        return concatBytes(MAGIC, iv, new Uint8Array(ciphertext));
+    }
+    async function unseal(storageKey, bytes) {
+        if (!isSealed(bytes))
+            throw new Error(`${storageKey} should be sealed, and is not — refusing it`);
+        const iv = bytes.slice(MAGIC.length, MAGIC.length + IV_BYTES);
+        const ciphertext = bytes.slice(MAGIC.length + IV_BYTES);
+        const plain = await globalThis.crypto.subtle.decrypt({ name: 'AES-GCM', iv: iv, additionalData: bound(storageKey) }, key, ciphertext);
+        return new Uint8Array(plain);
+    }
+    return Object.freeze({
+        async get(storageKey) {
+            const bytes = await inner.get(storageKey);
+            if (!bytes || !shouldSeal(storageKey))
+                return bytes;
+            return unseal(storageKey, bytes);
+        },
+        async put(storageKey, value) {
+            return inner.put(storageKey, shouldSeal(storageKey) ? await seal(storageKey, value) : value);
+        },
+        async batch(ops) {
+            const prepared = await Promise.all(ops.map(async (op) => op.type === 'put' && shouldSeal(op.key)
+                ? { type: 'put', key: op.key, value: await seal(op.key, op.value) }
+                : op));
+            return inner.batch(prepared);
+        },
+        // Key names are not sealed, so listing, deleting and existence checks are
+        // unchanged. A space id is a content hash and gives nothing away; its name
+        // and its key live in the value, which is sealed.
+        delete: (storageKey) => inner.delete(storageKey),
+        has: (storageKey) => inner.has(storageKey),
+        list: (prefix) => inner.list(prefix),
+        // Expressions carry their own encryption where the space calls for it.
+        queryExpressions: (collection, limit, cursor) => inner.queryExpressions(collection, limit, cursor),
+        putExpression: inner.putExpression.bind(inner),
+        getExpression: (id) => inner.getExpression(id),
+        deleteExpression: (id) => inner.deleteExpression(id),
+        close: () => inner.close(),
+    });
+}
+//# sourceMappingURL=encrypted-adapter.js.map

package/dist/storage/encrypted-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encrypted-adapter.js","sourceRoot":"","sources":["../../src/storage/encrypted-adapter.ts"],"names":[],"mappings":"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"}

package/dist/storage/folder-adapter.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @module folder-adapter
+ * A StorageAdapter over a directory the user picked on their own disk.
+ *
+ * This is the store that escapes the origin sandbox. IndexedDB, localStorage and
+ * OPFS ("Origin Private File System" — the name is the specification) are all
+ * keyed by origin, so two deployments of the same app can never see each other's
+ * data. A directory handle is not: each origin asks the user for permission once
+ * and both end up reading the same files. That is what makes an app a *view* on
+ * the user's data rather than an owner of a private copy of it.
+ *
+ * The layout is meant to be legible, because the point is that the folder
+ * belongs to the user:
+ *
+ * ```
+ * <folder>/
+ *   accounts.json                    who has an account here
+ *   accounts/<id>/account.json       that account's keys, locked
+ *   accounts/<id>/stores/<name>/
+ *     kv/<key>                       MST nodes, the root pointer, space records
+ *     expressions/<cid>.json
+ * ```
+ *
+ * **Expressions are the truth; the MST is an index over them.** That inversion
+ * is what lets two origins share one folder with no locking. Every expression
+ * file is immutable and named by its own content hash, so concurrent writers can
+ * only ever add files that agree — the one genuinely mutable thing, the MST root
+ * pointer, is derived state that either side can rebuild. {@link reconcileFolder}
+ * is what rebuilds it.
+ */
+import type { StorageAdapter } from '../types.js';
+export interface WritableFileLike {
+    write(data: Uint8Array | string): Promise<void>;
+    close(): Promise<void>;
+}
+export interface FileHandleLike {
+    getFile(): Promise<{
+        arrayBuffer(): Promise<ArrayBuffer>;
+    }>;
+    createWritable(): Promise<WritableFileLike>;
+}
+export interface DirectoryHandleLike {
+    readonly name: string;
+    getFileHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<FileHandleLike>;
+    getDirectoryHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<DirectoryHandleLike>;
+    removeEntry(name: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    keys(): AsyncIterableIterator<string>;
+}
+/** What changed on disk since the last pass */
+export interface FolderReload {
+    /** Expression ids that appeared — written by another origin, or another device */
+    readonly added: ReadonlyArray<string>;
+    /** Expression ids whose files are gone */
+    readonly removed: ReadonlyArray<string>;
+}
+export interface FolderAdapter extends StorageAdapter {
+    /** Where inside the folder this adapter keeps its files */
+    readonly namespace: string;
+    /**
+     * Re-reads the directory, picking up writes made by another origin or device.
+     *
+     * There is no filesystem change notification on the web, so freshness is
+     * something the caller asks for — on an interval, on focus, or after a sync
+     * round. Pair it with {@link reconcileFolder} to fold what turns up into the
+     * local tree.
+     */
+    reload(): Promise<FolderReload>;
+    /** Every expression id currently on disk, whatever the MST believes */
+    listExpressionIds(): Promise<ReadonlyArray<string>>;
+}
+/**
+ * Reads a file, treating absence as null rather than as a failure.
+ * @param dir The directory holding it
+ * @param name The filename
+ * @returns Its bytes, or null when there is no such file
+ */
+export declare function readFolderFile(dir: DirectoryHandleLike, name: string): Promise<Uint8Array | null>;
+/**
+ * Writes a file, replacing whatever was there.
+ * @param dir The directory to write into
+ * @param name The filename
+ * @param bytes The contents
+ */
+export declare function writeFolderFile(dir: DirectoryHandleLike, name: string, bytes: Uint8Array): Promise<void>;
+/**
+ * Opens a storage adapter backed by a directory on the user's disk.
+ *
+ * Expressions are held in memory as well as on disk — a query would otherwise
+ * mean one file read per record, and the example app re-lists on every render.
+ * The cost is that the working set has to fit in memory.
+ *
+ * @param root The directory the user picked
+ * @param path Where to keep these files inside it, `/` separating
+ *   subdirectories. The full path from the folder root, so that several
+ *   accounts can each have a subtree of their own.
+ * @returns An adapter over that directory, already populated
+ */
+export declare function createFolderAdapter(root: DirectoryHandleLike, path: string): Promise<FolderAdapter>;
+//# sourceMappingURL=folder-adapter.d.ts.map

package/dist/storage/folder-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-adapter.d.ts","sourceRoot":"","sources":["../../src/storage/folder-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,aAAa,CAAC;AAUvE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,IAAI,OAAO,CAAC;QAAE,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;KAAE,CAAC,CAAC;IAC5D,cAAc,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACrF,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC/F,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,IAAI,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAAC;CACvC;AAED,+CAA+C;AAC/C,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAChC,uEAAuE;IACvE,iBAAiB,IAAI,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;CACrD;AAgED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CASvG;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAK9G;AAeD;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,aAAa,CAAC,CAuJxB"}