nervur 0.19.2 → 0.20.1

package/dist/harbor/package.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: Apache-2.0
+// The package: a harbor's memory, sealed under the harbor's seed. The
+// terrain keeps its bytes and reads neither a ward's name, nor a being's
+// key, nor anything a row holds.
+//
+//   key            HKDF-SHA-256 of the seed under `nervur-package`
+//   place          16 bytes under ["place", ward], as hex
+//   entry          16 bytes under ["entry", ward, row], as hex
+//   seal           32 bytes under ["seal", ward]
+//   entry bytes    nonce (12) || AES-256-GCM( JSON { row, value } ),
+//                  the entry's name as additional data
+//
+// A row is the head, under the empty name, or one being, under her key. An
+// entry that does not open refuses the whole ward, so nothing unpacks from
+// bytes the package did not seal.
+import { concat, decrypt, encrypt, hex, hkdf, utf8 } from '../crypto/index.js';
+import { HEAD_ROW } from '../ward/index.js';
+const NONCE = 12;
+const LABEL = utf8('nervur-package');
+class PackageRows {
+    rows;
+    #ward;
+    #told = new Set();
+    #line = Promise.resolve(true);
+    constructor(ward, rows) {
+        this.#ward = ward;
+        this.rows = rows;
+    }
+    told(row) {
+        this.#told.add(row);
+    }
+    // Every row told since the last keep, sealed and written as one keep, one
+    // keep at a time.
+    kept() {
+        const rows = [...this.#told];
+        this.#told.clear();
+        this.#line = this.#line.then(() => this.#write(rows)).catch(() => false);
+        return this.#line;
+    }
+    async #write(told) {
+        const beings = (this.rows.beings ?? {});
+        const entries = new Map();
+        for (const row of told) {
+            const value = row === HEAD_ROW ? (this.rows.ward ?? null) : Object.hasOwn(beings, row) ? beings[row] : undefined;
+            entries.set(await this.#ward.entry(row), value === undefined ? null : await this.#ward.seal(row, value));
+        }
+        await this.#ward.write(entries);
+        return true;
+    }
+}
+class Ward {
+    #pack;
+    #name;
+    #seal;
+    place;
+    constructor(pack, name, seal, place) {
+        this.#pack = pack;
+        this.#name = name;
+        this.#seal = seal;
+        this.place = place;
+    }
+    entry(row) {
+        return this.#pack.derive(['entry', this.#name, row], 16).then(hex);
+    }
+    async seal(row, value) {
+        const nonce = this.#pack.entropy.draw(NONCE);
+        const text = utf8(JSON.stringify({ row, value }));
+        return concat(nonce, await encrypt(this.#seal, nonce, utf8(await this.entry(row)), text));
+    }
+    // The name is the additional data, so an entry moved under another name
+    // does not open either.
+    async open(name, bytes) {
+        const text = bytes.length > NONCE ? await decrypt(this.#seal, bytes.subarray(0, NONCE), utf8(name), bytes.subarray(NONCE)) : null;
+        if (text === null)
+            throw new Error('an entry the package did not seal');
+        return JSON.parse(new TextDecoder().decode(text));
+    }
+    write(entries) {
+        return this.#pack.memory.write(this.place, entries);
+    }
+}
+export class Package {
+    memory;
+    entropy;
+    #key;
+    constructor(memory, entropy, key) {
+        this.memory = memory;
+        this.entropy = entropy;
+        this.#key = key;
+    }
+    static async open(memory, entropy, seed) {
+        return new Package(memory, entropy, await hkdf(seed, LABEL, 32));
+    }
+    derive(info, length) {
+        return hkdf(this.#key, utf8(JSON.stringify(info)), length);
+    }
+    // One ward's rows, as the package kept them.
+    async rows(name) {
+        const ward = new Ward(this, name, await this.derive(['seal', name], 32), hex(await this.derive(['place', name], 16)));
+        const rows = {};
+        const beings = {};
+        let any = false;
+        for (const [entry, bytes] of await this.memory.read(ward.place)) {
+            const { row, value } = await ward.open(entry, bytes);
+            any = true;
+            if (row === HEAD_ROW)
+                rows.ward = value;
+            else
+                beings[row] = value;
+        }
+        if (any)
+            rows.beings = beings;
+        return new PackageRows(ward, rows);
+    }
+}

package/dist/harbor/registry.d.ts

@@ -0,0 +1,9 @@
+import { type BeingClass } from '../being/index.ts';
+import type { Module } from '../contract/index.ts';
+import type { Catalogue } from '../ward/index.ts';
+export declare class Registry implements Catalogue {
+    #private;
+    constructor(kit: readonly BeingClass[], modules: readonly Module[]);
+    classOf(kind: string): BeingClass | undefined;
+    kindsOf(module: string): string[];
+}

package/dist/harbor/registry.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// The catalogue's index: every kind the harbor runs, from the kit's own
+// classes and the modules the catalogue loaded. It resolves a kind a row
+// keeps, and decides nothing about what stands. It refuses any set of
+// modules two readings could split:
+//
+//   a module whose name is no kind, or is the kit's, or two of one name
+//   a class with no kind of its own, or one outside its module's domain
+//   two classes of one kind, or one kind in two modules
+//   a contract with no kind of its own, or one kind for two contracts
+//   a kind that is a class and a contract
+//
+// A module's domain is its name's first two segments: `com.acme.shop`
+// stands classes under `com.acme.` alone. A contract may be any domain's,
+// so a faculty fulfils a contract another module declares. Two harbors hold
+// two registries, and nothing between them names a class.
+import { Faculty, isKind, KIT, kindOf } from '../being/index.js';
+const domainOf = (name) => `${name.split('.').slice(0, 2).join('.')}.`;
+export class Registry {
+    #classes = new Map();
+    #modules = new Map();
+    // `kit` holds the kit's own classes, which alone may be of its kinds.
+    constructor(kit, modules) {
+        const contracts = new Map();
+        const owners = new Map();
+        const add = (C, kind) => {
+            if (this.#classes.has(kind) && this.#classes.get(kind) !== C)
+                throw new Error(`two classes are of kind ${kind}`);
+            this.#classes.set(kind, C);
+        };
+        for (const C of kit)
+            add(C, kindOf(C));
+        for (const m of modules) {
+            if (!isKind(m.module) || m.module.startsWith(KIT))
+                throw new Error(`module ${String(m.module)} is no name a module may take`);
+            if (this.#modules.has(m.module))
+                throw new Error(`two modules are named ${m.module}`);
+            if (typeof m.version !== 'string' || m.version === '')
+                throw new Error(`module ${m.module} declares no version`);
+            const kinds = [];
+            for (const C of m.classes) {
+                if (typeof C !== 'function')
+                    throw new Error(`module ${m.module} holds something that is no class`);
+                const kind = kindOf(C);
+                if (!kind.startsWith(domainOf(m.module)))
+                    throw new Error(`kind ${kind} is outside module ${m.module}`);
+                const owner = owners.get(kind);
+                if (owner !== undefined && owner !== m.module)
+                    throw new Error(`kind ${kind} is in modules ${owner} and ${m.module}`);
+                owners.set(kind, m.module);
+                add(C, kind);
+                kinds.push(kind);
+                if (!Faculty.fulfils(C))
+                    continue;
+                for (let c = Object.getPrototypeOf(C); c !== Faculty; c = Object.getPrototypeOf(c)) {
+                    const contract = kindOf(c);
+                    if (contract.startsWith(KIT))
+                        throw new Error(`kind ${contract} is the kit's`);
+                    if (contracts.has(contract) && contracts.get(contract) !== c)
+                        throw new Error(`two contracts are of kind ${contract}`);
+                    contracts.set(contract, c);
+                }
+            }
+            this.#modules.set(m.module, kinds);
+        }
+        for (const kind of contracts.keys()) {
+            if (this.#classes.has(kind))
+                throw new Error(`kind ${kind} is a class and a contract`);
+        }
+    }
+    classOf(kind) {
+        return this.#classes.get(kind);
+    }
+    // The kinds a module stands, or none.
+    kindsOf(module) {
+        return [...(this.#modules.get(module) ?? [])];
+    }
+}

package/dist/harbor/root-line.d.ts

@@ -0,0 +1,9 @@
+import { type JsonObject } from '../being/index.ts';
+import type { Harbor } from './harbor.ts';
+export type RootRequest = {
+    ward?: string;
+    method?: string;
+    args?: JsonObject;
+};
+export declare const readRootRequest: (value: unknown) => RootRequest | null;
+export declare const rootLine: (harbor: Harbor, value: unknown) => Promise<JsonObject>;

package/dist/harbor/root-line.js

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: Apache-2.0
+// The root line: one request, one answer, both plain JSON, for whatever
+// carries the root's asks to a harbor in its own process. The command line
+// carries it over a local socket, and an edge route carries it the same way.
+//
+//   request  { ward?, method?, args? }    no ward is the box ward, no
+//                                         method the census
+//   answer   { answer }                   what the ward-being said
+//            { silence: true }            she said nothing
+//            { word }                     a kit word: unreached, late, ...
+//            { error }                    the request was not one, or the
+//                                         ward is none this harbor holds
+import { isSilence, isWord, told } from '../being/index.js';
+const object = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export const readRootRequest = (value) => {
+    if (!object(value))
+        return null;
+    const { ward, method, args } = value;
+    if ((ward !== undefined && typeof ward !== 'string') || (method !== undefined && typeof method !== 'string') || (args !== undefined && !object(args)))
+        return null;
+    return { ...(ward === undefined ? {} : { ward }), ...(method === undefined ? {} : { method }), ...(args === undefined ? {} : { args }) };
+};
+export const rootLine = async (harbor, value) => {
+    const request = readRootRequest(value);
+    if (request === null)
+        return { error: 'not a root request' };
+    const ward = request.ward === undefined ? harbor.box : harbor.ward(request.ward);
+    if (ward === undefined)
+        return { error: 'no such ward' };
+    const out = await ward.root(request.method, request.args);
+    if (isSilence(out))
+        return { silence: true };
+    if (isWord(out))
+        return { word: told(out) };
+    return { answer: out };
+};

package/dist/harbor/terrain.d.ts

@@ -0,0 +1,9 @@
+import type { Carrier, Clock, Custody, Entropy, Loader, Memory } from '../contract/index.ts';
+export declare abstract class Terrain {
+    abstract readonly entropy: Entropy;
+    abstract readonly clock: Clock;
+    abstract readonly custody: Custody;
+    abstract readonly memory: Memory;
+    abstract readonly loader: Loader;
+    abstract readonly carrier: Carrier;
+}

package/dist/harbor/terrain.js

@@ -0,0 +1,2 @@
+export class Terrain {
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { Being, canonical, digest, Faculty, isSilence, isWord, OWNER, silence, told, WARD, word } from './being/index.ts';
+export type { Answer, Ask, Asker, AskSpec, BeingClass, BeingLike, Blueprint, Invitation, Json, JsonObject, Occupants, Reply, Schema, Silence, Stance, Standing, Standings, Wanted, Word, WordName } from './being/index.ts';
+export { readInvitation } from './quo/index.ts';
+export { Carrier, Clock, Custody, Entropy, Loader, Memory, type Loaded, type Module, type Rows } from './contract/index.ts';
+export { CEILING, DEFAULT, DEPTH, ownerAsk, Pilot, pilots, WardBeing, type Steward, type WardBeingStance } from './ward/index.ts';
+export { BOX, Catalogue, Dock, Harbor, readRootRequest, Registry, rootLine, Terrain, type RootRequest } from './harbor/index.ts';
+export { CryptoEntropy, HeldCustody, HeldLoader, NoCarrier, PointerCarrier, PointerTerrain, SystemClock, VolatileMemory, World, type PointerParts } from './pointer/index.ts';

package/dist/index.js

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur`: what a stranger writes a world with. It imports no platform, so
+// it runs wherever JavaScript runs. A disk is `nervur/folder`.
+// Beings, faculties, and what they are told.
+export { Being, canonical, digest, Faculty, isSilence, isWord, OWNER, silence, told, WARD, word } from './being/index.js';
+export { readInvitation } from './quo/index.js';
+// What a terrain gives a harbor.
+export { Carrier, Clock, Custody, Entropy, Loader, Memory } from './contract/index.js';
+// Wards and the ward-being.
+export { CEILING, DEFAULT, DEPTH, ownerAsk, Pilot, pilots, WardBeing } from './ward/index.js';
+// The onion, and the one line its root's asks cross from any front.
+export { BOX, Catalogue, Dock, Harbor, readRootRequest, Registry, rootLine, Terrain } from './harbor/index.js';
+// The pointer dock: a whole world in one process.
+export { CryptoEntropy, HeldCustody, HeldLoader, NoCarrier, PointerCarrier, PointerTerrain, SystemClock, VolatileMemory, World } from './pointer/index.js';

package/dist/pointer/bodies.d.ts

@@ -0,0 +1,26 @@
+import { Clock, Custody, Entropy, Loader, Memory, type Loaded, type Module } from '../contract/index.ts';
+export declare class CryptoEntropy extends Entropy {
+    draw(length: number): Uint8Array;
+}
+export declare class SystemClock extends Clock {
+    now(): number;
+    wait(ms: number): {
+        done: Promise<void>;
+        cancel(): void;
+    };
+}
+export declare class HeldCustody extends Custody {
+    #private;
+    constructor(entropy: Entropy);
+    seed(): Promise<Uint8Array>;
+}
+export declare class HeldLoader extends Loader {
+    #private;
+    constructor(modules?: readonly Module[]);
+    load(from: string): Promise<Loaded | null>;
+}
+export declare class VolatileMemory extends Memory {
+    #private;
+    read(place: string): Promise<Map<string, Uint8Array>>;
+    write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void>;
+}

package/dist/pointer/bodies.js

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: Apache-2.0
+// The pointer terrain's bodies: each contract fulfilled in one process,
+// with nothing beyond JavaScript.
+import { Clock, Custody, Entropy, Loader, Memory } from '../contract/index.js';
+export class CryptoEntropy extends Entropy {
+    draw(length) {
+        return globalThis.crypto.getRandomValues(new Uint8Array(length));
+    }
+}
+export class SystemClock extends Clock {
+    now() {
+        return Date.now();
+    }
+    wait(ms) {
+        let timer;
+        const done = new Promise((resolve) => (timer = setTimeout(resolve, ms)));
+        return { done, cancel: () => clearTimeout(timer) };
+    }
+}
+// The harbor's seed, drawn once and held by this object.
+export class HeldCustody extends Custody {
+    #seed;
+    constructor(entropy) {
+        super();
+        this.#seed = entropy.draw(32);
+    }
+    seed() {
+        return Promise.resolve(this.#seed.slice());
+    }
+}
+// Modules handed to this object, found by the name each declares.
+export class HeldLoader extends Loader {
+    #modules = new Map();
+    constructor(modules = []) {
+        super();
+        for (const m of modules)
+            this.#modules.set(m.module, m);
+    }
+    load(from) {
+        const m = this.#modules.get(from);
+        return Promise.resolve(m ? { module: m.module, version: m.version, classes: m.classes, from } : null);
+    }
+}
+// Entries that live as long as this object, copied in and out, which is
+// what a restart in one process finds.
+export class VolatileMemory extends Memory {
+    #places = new Map();
+    read(place) {
+        const entries = this.#places.get(place) ?? new Map();
+        return Promise.resolve(new Map([...entries].map(([name, bytes]) => [name, bytes.slice()])));
+    }
+    write(place, entries) {
+        let kept = this.#places.get(place);
+        if (!kept)
+            this.#places.set(place, (kept = new Map()));
+        for (const [name, bytes] of entries) {
+            if (bytes === null)
+                kept.delete(name);
+            else
+                kept.set(name, bytes.slice());
+        }
+        return Promise.resolve();
+    }
+}

package/dist/pointer/index.d.ts

@@ -0,0 +1,2 @@
+export { CryptoEntropy, HeldCustody, HeldLoader, SystemClock, VolatileMemory } from './bodies.ts';
+export { NoCarrier, PointerCarrier, PointerTerrain, World, type PointerParts } from './world.ts';

package/dist/pointer/index.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// The pointer dock: a whole world with `nervur` alone.
+export { CryptoEntropy, HeldCustody, HeldLoader, SystemClock, VolatileMemory } from './bodies.js';
+export { NoCarrier, PointerCarrier, PointerTerrain, World } from './world.js';

package/dist/pointer/world.d.ts

@@ -0,0 +1,35 @@
+import { Carrier, type Clock, type Custody, type Entropy, type Loader, type Memory, type Module } from '../contract/index.ts';
+import { Harbor, Terrain } from '../harbor/index.ts';
+export declare class NoCarrier extends Carrier {
+    carry(): Promise<Uint8Array | null>;
+}
+export declare class PointerCarrier extends Carrier {
+    #private;
+    constructor(world: World);
+    carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+}
+export type PointerParts = {
+    entropy?: Entropy;
+    clock?: Clock;
+    custody?: Custody;
+    memory?: Memory;
+    carrier?: Carrier;
+    loader?: Loader;
+};
+export declare class PointerTerrain extends Terrain {
+    readonly entropy: Entropy;
+    readonly clock: Clock;
+    readonly custody: Custody;
+    readonly memory: Memory;
+    readonly carrier: Carrier;
+    readonly loader: Loader;
+    constructor(parts?: PointerParts);
+}
+export declare class World {
+    #private;
+    readonly cut: Set<string>;
+    harbor(name: string, modules?: readonly Module[], parts?: Omit<PointerParts, 'carrier'>): Promise<Harbor>;
+    get(name: string): Harbor;
+    restart(name: string, parts?: Omit<PointerParts, 'carrier'>): Promise<Harbor>;
+    carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+}

package/dist/pointer/world.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+// The pointer world: harbors in one process, an address book from ward pk
+// to harbor that stands in for the internet, and weather between them. A
+// restart drops a harbor and opens a new one on the terrain the world
+// keeps for it, so only what its memory kept comes back.
+import { Carrier } from '../contract/index.js';
+import { Harbor, Terrain } from '../harbor/index.js';
+import { CryptoEntropy, HeldCustody, HeldLoader, SystemClock, VolatileMemory } from './bodies.js';
+// A carrier that reaches no one: a harbor alone.
+export class NoCarrier extends Carrier {
+    carry() {
+        return Promise.resolve(null);
+    }
+}
+// Bytes to whichever harbor of a world holds the ward pk.
+export class PointerCarrier extends Carrier {
+    #world;
+    constructor(world) {
+        super();
+        this.#world = world;
+    }
+    carry(pk, bytes) {
+        return this.#world.carry(pk, bytes);
+    }
+}
+export class PointerTerrain extends Terrain {
+    entropy;
+    clock;
+    custody;
+    memory;
+    carrier;
+    loader;
+    constructor(parts = {}) {
+        super();
+        this.entropy = parts.entropy ?? new CryptoEntropy();
+        this.clock = parts.clock ?? new SystemClock();
+        this.custody = parts.custody ?? new HeldCustody(this.entropy);
+        this.memory = parts.memory ?? new VolatileMemory();
+        this.carrier = parts.carrier ?? new NoCarrier();
+        this.loader = parts.loader ?? new HeldLoader();
+    }
+}
+export class World {
+    #places = new Map();
+    // Harbors the world reaches no one in, nor anyone out of.
+    cut = new Set();
+    // A harbor of this world, whose loader holds `modules` unless `parts`
+    // names a loader. `parts` replaces the pointer bodies, a folder's memory
+    // and custody among them. The harbor runs only the modules its catalogue
+    // was told to add.
+    async harbor(name, modules = [], parts = {}) {
+        if (this.#places.has(name))
+            throw new Error(`a harbor named ${name} stands`);
+        const terrain = new PointerTerrain({ loader: new HeldLoader(modules), ...parts, carrier: new PointerCarrier(this) });
+        const harbor = await Harbor.open(terrain);
+        this.#places.set(name, { harbor, terrain });
+        return harbor;
+    }
+    get(name) {
+        const place = this.#places.get(name);
+        if (!place)
+            throw new Error(`no harbor named ${name}`);
+        return place.harbor;
+    }
+    // The harbor opened again on its own terrain. `parts` replaces bodies of
+    // the terrain, as a new process would build them over the same disk, or
+    // with other code.
+    async restart(name, parts) {
+        const place = this.#places.get(name);
+        if (!place)
+            throw new Error(`no harbor named ${name}`);
+        const t = place.terrain;
+        const terrain = parts ? new PointerTerrain({ entropy: t.entropy, clock: t.clock, custody: t.custody, memory: t.memory, loader: t.loader, ...parts, carrier: t.carrier }) : t;
+        const harbor = await Harbor.open(terrain);
+        this.#places.set(name, { harbor, terrain });
+        return harbor;
+    }
+    carry(pk, bytes) {
+        for (const [name, { harbor }] of this.#places) {
+            if (harbor.holds(pk))
+                return this.cut.has(name) ? Promise.resolve(null) : harbor.arrive(pk, bytes);
+        }
+        return Promise.resolve(null);
+    }
+}

package/dist/quo/door.d.ts

@@ -0,0 +1,34 @@
+import { type Draw, type WardKey } from './keys.ts';
+import type { Invitation } from './invitation.ts';
+import { type Payload } from './payload.ts';
+import type { Relations } from './relations.ts';
+export declare const SPAN = 64;
+export type Choice = {
+    readonly object: string;
+    readonly seen: string | null;
+} | {
+    readonly silence: true;
+};
+export interface Behind {
+    readonly zero: boolean;
+    answer(heir: string | null, payload: Payload): Promise<Choice>;
+}
+export type Judged = {
+    bytes: Uint8Array;
+    case: number;
+    heard: boolean;
+};
+export declare class Door {
+    #private;
+    readonly key: WardKey;
+    readonly relations: Relations;
+    readonly behind: Behind;
+    readonly draw: Draw;
+    constructor(key: WardKey, relations: Relations, behind: Behind, draw: Draw);
+    invite(): Promise<{
+        heir: string;
+        invitation: Invitation;
+    }>;
+    remove(heir: string): boolean;
+    arrive(bytes: Uint8Array): Promise<Judged>;
+}