nervur 0.22.0 → 0.22.2-3

package/dist/browser/browser-ground.d.ts

@@ -0,0 +1,69 @@
+import type { Json } from '../being/being.ts';
+import type { Memory } from '../foundation.ts';
+import { Ground, type Bodies, type Custody, type Faculty } from '../ground/ground.ts';
+import type { Answer } from '../house/rows-shape.ts';
+import { type Load } from './origin-classes.ts';
+/** What a page hands its ground: the faculties it makes, by name, and any custom body. */
+export interface BrowserRecipe {
+    readonly faculties?: () => Readonly<Record<string, Faculty | Promise<Faculty>>>;
+    readonly bodies?: Partial<Bodies>;
+}
+/** What the ground takes of its engine. Each is the page's own where omitted. */
+export interface BrowserPlatform {
+    readonly locks: Pick<LockManager, 'request'>;
+    readonly channel: (name: string) => Pick<BroadcastChannel, 'postMessage' | 'close'> & {
+        onmessage: ((event: MessageEvent) => void) | null;
+    };
+    readonly custody: (name: string) => Promise<Custody>;
+    readonly memory: (name: string) => Promise<Memory>;
+    /** Where its code stands; its classes load from under it alone. */
+    readonly origin: string;
+    /** Asks the browser to keep its storage, and answers whether it will. */
+    readonly persist: () => Promise<boolean>;
+    /** Loads a module of classes by URL: `import()`, or in a service worker a map of the worker's own imports. */
+    readonly load: Load;
+}
+export interface BrowserGroundOptions {
+    /** The ground's name on its origin, which names its lock, its channel and its storage. `nervur` where omitted. */
+    readonly name?: string;
+    readonly recipe?: BrowserRecipe;
+    readonly platform?: Partial<BrowserPlatform>;
+    /** The ground's bound on every ask, in milliseconds. */
+    readonly wait?: number;
+    /** Whether it dials private and loopback addresses, as a page on localhost does. */
+    readonly allowPrivate?: boolean;
+}
+/** One request of the hand, as every terrain serves it. */
+export interface BrowserHandRequest {
+    readonly describe?: true;
+    readonly faculty?: string;
+    readonly house?: string;
+    readonly id?: string;
+    readonly method?: string;
+    readonly args?: Json;
+    readonly after?: Answer;
+}
+export declare class BrowserGround {
+    #private;
+    private constructor();
+    /**
+     * The origin's ground, joined: this page runs it where it takes the lock,
+     * and reaches the page that runs it where another holds the lock.
+     */
+    static open(options?: BrowserGroundOptions): Promise<BrowserGround>;
+    /** Whether this page runs the ground now. */
+    get leading(): boolean;
+    /** The ground, where this page runs it. */
+    get ground(): Ground | undefined;
+    /** Resolves once this page runs the ground, and rejects where its boot failed. */
+    led(): Promise<void>;
+    /**
+     * The hand: `describe`, a faculty's method, or an ask of a being in a
+     * named house, answered by whichever page runs the ground.
+     */
+    hand(request: BrowserHandRequest): Promise<Answer | {
+        readonly describe: Json;
+    }>;
+    /** This page leaves: its ground closes where it ran one, and the lock passes to the next page. */
+    close(): Promise<void>;
+}

package/dist/browser/browser-ground.js

@@ -0,0 +1,219 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { JoinedCarry } from '../bodies/joined-carry.js';
+import { WebCarry } from '../bodies/web-carry.js';
+import { Ground } from '../ground/ground.js';
+import { IndexedDbMemory } from './indexeddb-memory.js';
+import { LockedCustody } from './locked-custody.js';
+import { OriginClasses } from './origin-classes.js';
+const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const random = () => Array.from(crypto.getRandomValues(new Uint8Array(8)), (byte) => byte.toString(16).padStart(2, '0')).join('');
+// Bodies a recipe adds beside the ground's own, never in their place.
+const joined = (own, added = {}) => {
+    for (const name of Object.keys(added))
+        if (name in own)
+            throw new TypeError(`the recipe names a body ${name}, which is the ground's own`);
+    return { ...own, ...added };
+};
+const defaults = (name) => ({
+    locks: navigator.locks,
+    channel: (channel) => new BroadcastChannel(channel),
+    custody: (custody) => LockedCustody.open(custody),
+    memory: (memory) => IndexedDbMemory.open(memory),
+    origin: globalThis.location?.origin ?? `nervur:${name}`,
+    persist: async () => (await navigator.storage?.persist?.()) ?? false,
+    load: (href) => import(__rewriteRelativeImportExtension(href)),
+});
+export class BrowserGround {
+    #name;
+    #platform;
+    #options;
+    #self = random();
+    #channel;
+    #abort = new AbortController();
+    // Asks sent to another page's ground, by id, with the page they went to.
+    #pending = new Map();
+    #ground;
+    #persisted = false;
+    #leader;
+    #waiting = [];
+    #release;
+    #leading;
+    #led;
+    #failed;
+    #closed = false;
+    constructor(name, platform, options) {
+        this.#name = name;
+        this.#platform = platform;
+        this.#options = options;
+        this.#channel = platform.channel(`${name}-hand`);
+        this.#leading = new Promise((resolve, reject) => {
+            this.#led = resolve;
+            this.#failed = reject;
+        });
+        this.#leading.catch(() => undefined);
+    }
+    /**
+     * The origin's ground, joined: this page runs it where it takes the lock,
+     * and reaches the page that runs it where another holds the lock.
+     */
+    static async open(options = {}) {
+        const name = options.name ?? 'nervur';
+        if (!NAME.test(name))
+            throw new TypeError(`no ground is named ${name}`);
+        const platform = { ...defaults(name), ...options.platform };
+        const joining = new BrowserGround(name, platform, options);
+        joining.#listen();
+        joining.#queue();
+        joining.#say({ kind: 'who' });
+        return joining;
+    }
+    /** Whether this page runs the ground now. */
+    get leading() {
+        return this.#ground !== undefined;
+    }
+    /** The ground, where this page runs it. */
+    get ground() {
+        return this.#ground;
+    }
+    /** Resolves once this page runs the ground, and rejects where its boot failed. */
+    led() {
+        return this.#leading;
+    }
+    /**
+     * The hand: `describe`, a faculty's method, or an ask of a being in a
+     * named house, answered by whichever page runs the ground.
+     */
+    async hand(request) {
+        if (this.#closed)
+            return { error: { message: 'the ground is closed here' } };
+        if (this.#ground !== undefined)
+            return this.#local(request);
+        if (this.#leader === undefined)
+            await new Promise((resolve) => this.#waiting.push(resolve));
+        if (this.#ground !== undefined)
+            return this.#local(request);
+        const id = random();
+        const to = this.#leader;
+        return new Promise((settle) => {
+            this.#pending.set(id, { to, settle });
+            this.#say({ kind: 'ask', id, to, request });
+        });
+    }
+    async #local(request) {
+        const answer = await this.#ground.hand(request);
+        if (request.describe === true && 'result' in answer)
+            return { result: { ...answer.result, persisted: this.#persisted } };
+        return answer;
+    }
+    #say(said) {
+        this.#channel.postMessage(said);
+    }
+    #listen() {
+        this.#channel.onmessage = (event) => {
+            const said = event.data;
+            if (said.kind === 'who' && this.#ground !== undefined)
+                this.#say({ kind: 'up', leader: this.#self });
+            else if (said.kind === 'up')
+                this.#heard(said.leader);
+            else if (said.kind === 'ask' && said.to === this.#self)
+                void this.#answer(said.id, said.request);
+            else if (said.kind === 'answer') {
+                const pending = this.#pending.get(said.id);
+                this.#pending.delete(said.id);
+                pending?.settle(said.answer);
+            }
+        };
+    }
+    async #answer(id, request) {
+        const answer = this.#ground === undefined ? { error: { message: 'the ground moved to another page; ask again' } } : await this.#local(request);
+        this.#say({ kind: 'answer', id, answer });
+    }
+    // A new page runs the ground: asks sent to the one before may never be answered, so they fail, and whoever waited goes on.
+    #heard(leader) {
+        if (leader !== this.#leader)
+            this.#orphan((to) => to !== leader);
+        this.#leader = leader;
+        const waiting = this.#waiting;
+        this.#waiting = [];
+        for (const resolve of waiting)
+            resolve();
+    }
+    #orphan(lost) {
+        for (const [id, pending] of this.#pending) {
+            if (!lost(pending.to))
+                continue;
+            this.#pending.delete(id);
+            pending.settle({ error: { message: 'the page that ran the ground closed; ask again' } });
+        }
+    }
+    // The lock, asked once and held until this page closes.
+    #queue() {
+        this.#platform.locks
+            .request(`${this.#name}-ground`, { signal: this.#abort.signal }, async () => {
+            try {
+                this.#ground = await this.#boot();
+            }
+            catch (error) {
+                this.#failed(error);
+                return;
+            }
+            this.#heard(this.#self);
+            this.#say({ kind: 'up', leader: this.#self });
+            this.#led();
+            await new Promise((resolve) => {
+                this.#release = resolve;
+            });
+        })
+            .catch(() => undefined);
+    }
+    // The boot: its own custody and memory, the recipe's faculties, and the record's houses.
+    async #boot() {
+        const name = this.#name;
+        const platform = this.#platform;
+        const recipe = this.#options.recipe ?? {};
+        const custody = await platform.custody(`${name}-custody`);
+        const memory = await platform.memory(`${name}-ground`);
+        this.#persisted = await platform.persist().catch(() => false);
+        // It only dials, so it writes no address into an invitation.
+        const web = new WebCarry({ allowPrivate: this.#options.allowPrivate === true });
+        const carry = new JoinedCarry({ https: web, http: web });
+        const faculties = {};
+        for (const [faculty, made] of Object.entries(recipe.faculties?.() ?? {}))
+            faculties[faculty] = await made;
+        const bodies = {
+            memory: joined({ indexeddb: ({ house }) => platform.memory(`${name}-house-${house}`) }, recipe.bodies?.memory),
+            classes: joined({
+                origin: ({ args }) => {
+                    if (typeof args.at !== 'string')
+                        throw new Error('the origin body names its module in at');
+                    return OriginClasses.open(args.at, platform.origin, platform.load);
+                },
+            }, recipe.bodies?.classes),
+        };
+        const wait = this.#options.wait;
+        return Ground.open({ custody, memory, carry, bodies, faculties, ...(wait === undefined ? {} : { wait }) });
+    }
+    /** This page leaves: its ground closes where it ran one, and the lock passes to the next page. */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#abort.abort();
+        const ground = this.#ground;
+        this.#ground = undefined;
+        await ground?.close();
+        this.#release?.();
+        this.#orphan(() => true);
+        for (const resolve of this.#waiting)
+            resolve();
+        this.#waiting = [];
+        this.#channel.close();
+    }
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,4 @@
+export { BrowserGround, type BrowserGroundOptions, type BrowserHandRequest, type BrowserPlatform, type BrowserRecipe } from './browser-ground.ts';
+export { IndexedDbMemory } from './indexeddb-memory.ts';
+export { IndexedDbShelf, LockedCustody, type Shelf } from './locked-custody.ts';
+export { OriginClasses, type Load } from './origin-classes.ts';

package/dist/browser/index.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur/browser`: the ground of a page and its service worker, and the
+// bodies it passes, for whoever writes a ground of their own.
+export { BrowserGround } from './browser-ground.js';
+export { IndexedDbMemory } from './indexeddb-memory.js';
+export { IndexedDbShelf, LockedCustody } from './locked-custody.js';
+export { OriginClasses } from './origin-classes.js';

package/dist/browser/indexeddb-memory.d.ts

@@ -0,0 +1,17 @@
+import type { Memory, PlaceRead } from '../foundation.ts';
+export declare class IndexedDbMemory implements Memory {
+    #private;
+    private constructor();
+    /** The memory named `name`, its database made on first use. `factory` is the engine's `indexedDB` where omitted. */
+    static open(name: string, factory?: IDBFactory): Promise<IndexedDbMemory>;
+    read({ place }: {
+        place: string;
+    }): Promise<PlaceRead>;
+    list(): Promise<readonly string[]>;
+    write({ writes, expect, }: {
+        writes: Readonly<Record<string, Readonly<Record<string, Uint8Array | null>>>>;
+        expect: Readonly<Record<string, string | null>>;
+    }): Promise<Readonly<Record<string, string | null>> | null>;
+    /** The database let go. */
+    close(): void;
+}

package/dist/browser/indexeddb-memory.js

@@ -0,0 +1,97 @@
+const PLACES = 'places';
+const COUNT = 'count';
+const done = (request) => new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('IndexedDB refused the request'));
+});
+const copied = (entries) => Object.fromEntries(Object.entries(entries).map(([name, bytes]) => [name, bytes.slice()]));
+export class IndexedDbMemory {
+    #db;
+    constructor(db) {
+        this.#db = db;
+    }
+    /** The memory named `name`, its database made on first use. `factory` is the engine's `indexedDB` where omitted. */
+    static async open(name, factory = indexedDB) {
+        const opening = factory.open(name, 1);
+        opening.onupgradeneeded = () => {
+            opening.result.createObjectStore(PLACES);
+            opening.result.createObjectStore(COUNT);
+        };
+        return new IndexedDbMemory(await done(opening));
+    }
+    async read({ place }) {
+        const held = (await done(this.#db.transaction(PLACES, 'readonly').objectStore(PLACES).get(place)));
+        if (held === undefined)
+            return { entries: {}, version: null };
+        return { entries: copied(held.entries), version: String(held.version) };
+    }
+    async list() {
+        const keys = await done(this.#db.transaction(PLACES, 'readonly').objectStore(PLACES).getAllKeys());
+        return keys.map(String);
+    }
+    write({ writes, expect, }) {
+        const places = [...new Set([...Object.keys(writes), ...Object.keys(expect)])];
+        return new Promise((resolve, reject) => {
+            const transaction = this.#db.transaction([PLACES, COUNT], 'readwrite');
+            const store = transaction.objectStore(PLACES);
+            const count = transaction.objectStore(COUNT);
+            const held = new Map();
+            let versions = null;
+            let refused = false;
+            transaction.oncomplete = () => resolve(versions);
+            transaction.onabort = () => (refused ? resolve(null) : reject(transaction.error ?? new Error('IndexedDB aborted the write')));
+            // Every place and the counter are read inside the transaction, and the writes follow in the same one.
+            const counted = count.get(COUNT);
+            const land = () => {
+                if (held.size < places.length || counted.readyState !== 'done')
+                    return;
+                for (const name of places) {
+                    const version = held.get(name) === undefined ? null : String(held.get(name).version);
+                    if (!(name in expect) || expect[name] !== version) {
+                        refused = true;
+                        transaction.abort();
+                        return;
+                    }
+                }
+                let next = counted.result ?? 0;
+                const landed = {};
+                for (const [name, entries] of Object.entries(writes)) {
+                    const kept = { ...(held.get(name)?.entries ?? {}) };
+                    for (const [entry, bytes] of Object.entries(entries)) {
+                        if (bytes === null)
+                            delete kept[entry];
+                        else
+                            kept[entry] = bytes.slice();
+                    }
+                    next += 1;
+                    if (Object.keys(kept).length === 0) {
+                        store.delete(name);
+                        landed[name] = null;
+                    }
+                    else {
+                        store.put({ entries: kept, version: next }, name);
+                        landed[name] = String(next);
+                    }
+                }
+                count.put(next, COUNT);
+                versions = landed;
+            };
+            counted.onsuccess = land;
+            for (const place of places) {
+                const request = store.get(place);
+                request.onsuccess = () => {
+                    held.set(place, request.result);
+                    land();
+                };
+            }
+            if (places.length === 0)
+                counted.onsuccess = () => {
+                    versions = {};
+                };
+        });
+    }
+    /** The database let go. */
+    close() {
+        this.#db.close();
+    }
+}

package/dist/browser/locked-custody.d.ts

@@ -0,0 +1,25 @@
+import type { Keys } from '../foundation.ts';
+import type { Custody } from '../ground/ground.ts';
+/** Where custody keeps its key and its sealed seeds: values kept as they are. */
+export interface Shelf {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+}
+/** A shelf in IndexedDB, which keeps a `CryptoKey` whole. */
+export declare class IndexedDbShelf implements Shelf {
+    #private;
+    private constructor();
+    static open(name: string, factory?: IDBFactory): Promise<IndexedDbShelf>;
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+    close(): void;
+}
+export declare class LockedCustody implements Custody {
+    #private;
+    constructor(shelf: Shelf, subtle?: SubtleCrypto);
+    /** The custody of the origin, on a shelf in IndexedDB named `name`. */
+    static open(name?: string, factory?: IDBFactory): Promise<LockedCustody>;
+    keys({ house }: {
+        house: string;
+    }): Promise<Keys>;
+}

package/dist/browser/locked-custody.js

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+// A BrowserGround's custody: one seed for each house, sealed with AES-GCM
+// under a key the browser keeps and never hands out. The key is made once,
+// unextractable, and kept on a shelf beside the sealed seeds, since
+// IndexedDB keeps a key as it is and never as bytes. A script on the
+// origin may use the key and can never copy it: a lock, not a wall.
+import { SeedKeys } from '../bodies/seed-keys.js';
+const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const KEY = 'key';
+const STORE = 'shelf';
+const done = (request) => new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('IndexedDB refused the request'));
+});
+/** A shelf in IndexedDB, which keeps a `CryptoKey` whole. */
+export class IndexedDbShelf {
+    #db;
+    constructor(db) {
+        this.#db = db;
+    }
+    static async open(name, factory = indexedDB) {
+        const opening = factory.open(name, 1);
+        opening.onupgradeneeded = () => {
+            opening.result.createObjectStore(STORE);
+        };
+        return new IndexedDbShelf(await done(opening));
+    }
+    get(key) {
+        return done(this.#db.transaction(STORE, 'readonly').objectStore(STORE).get(key));
+    }
+    async set(key, value) {
+        const transaction = this.#db.transaction(STORE, 'readwrite');
+        transaction.objectStore(STORE).put(value, key);
+        await new Promise((resolve, reject) => {
+            transaction.oncomplete = () => resolve();
+            transaction.onabort = () => reject(transaction.error ?? new Error('IndexedDB aborted the write'));
+        });
+    }
+    close() {
+        this.#db.close();
+    }
+}
+const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+export class LockedCustody {
+    #shelf;
+    #subtle;
+    // One seed is drawn at a time, so two first uses of a house never draw two.
+    #turn = Promise.resolve();
+    constructor(shelf, subtle = crypto.subtle) {
+        this.#shelf = shelf;
+        this.#subtle = subtle;
+    }
+    /** The custody of the origin, on a shelf in IndexedDB named `name`. */
+    static async open(name = 'nervur-custody', factory = indexedDB) {
+        return new LockedCustody(await IndexedDbShelf.open(name, factory));
+    }
+    keys({ house }) {
+        if (!NAME.test(house))
+            return Promise.reject(new TypeError(`no house is named ${house}`));
+        const turn = this.#turn.then(() => this.#keys(house));
+        this.#turn = turn.catch(() => undefined);
+        return turn;
+    }
+    async #keys(house) {
+        const key = await this.#key();
+        // The house's name is sealed in, so one house's seed never opens as another's.
+        const additionalData = new TextEncoder().encode(house);
+        let sealed = (await this.#shelf.get(`seed:${house}`));
+        if (sealed === undefined) {
+            const seed = crypto.getRandomValues(new Uint8Array(32));
+            const iv = crypto.getRandomValues(new Uint8Array(12));
+            sealed = { iv, data: new Uint8Array(await this.#subtle.encrypt({ name: 'AES-GCM', iv, additionalData }, key, seed)) };
+            seed.fill(0);
+            await this.#shelf.set(`seed:${house}`, sealed);
+        }
+        const seed = new Uint8Array(await this.#subtle.decrypt({ name: 'AES-GCM', iv: sealed.iv, additionalData }, key, sealed.data));
+        const keys = new SeedKeys(hex(seed));
+        seed.fill(0);
+        return keys;
+    }
+    async #key() {
+        const kept = (await this.#shelf.get(KEY));
+        if (kept !== undefined)
+            return kept;
+        const made = await this.#subtle.generateKey({ name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+        await this.#shelf.set(KEY, made);
+        return made;
+    }
+}

package/dist/browser/origin-classes.d.ts

@@ -0,0 +1,7 @@
+import type { Classes } from '../foundation.ts';
+/** What loads a module by its URL: the engine's `import()` where none is handed. */
+export type Load = (href: string) => Promise<unknown>;
+export declare const OriginClasses: Readonly<{
+    /** The classes of the module at `at`, resolved against `origin`, loaded once. */
+    open(at: string, origin: string, load?: Load): Promise<Classes>;
+}>;

package/dist/browser/origin-classes.js

@@ -0,0 +1,31 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// SPDX-License-Identifier: Apache-2.0
+// Classes from the ground's own origin. A module at a path under the
+// origin exports `steward`, and `public` and `beings` where it has them, as
+// `ClassList` takes them. A path that resolves off the origin is refused,
+// as a folder of code on a NodeGround stays inside its folder. A service
+// worker may not `import()`, so there the worker's own build hands a
+// loader that answers the same paths from modules it imported itself.
+import { ClassList } from '../bodies/class-list.js';
+export const OriginClasses = Object.freeze({
+    /** The classes of the module at `at`, resolved against `origin`, loaded once. */
+    async open(at, origin, load = (href) => import(__rewriteRelativeImportExtension(href))) {
+        const base = new URL(origin.endsWith('/') ? origin : `${origin}/`);
+        const url = new URL(at, base);
+        if (url.origin !== base.origin || !url.href.startsWith(base.href))
+            throw new Error(`the code at ${at} stands off ${base.href}`);
+        const module = (await load(url.href));
+        if (module.steward === undefined)
+            throw new Error(`${url.href} exports no steward`);
+        if (module.beings !== undefined && !Array.isArray(module.beings))
+            throw new Error(`${url.href} exports beings that are not a list`);
+        return new ClassList({ steward: module.steward, ...(module.public === undefined ? {} : { public: module.public }), ...(module.beings === undefined ? {} : { beings: module.beings }) });
+    },
+});