nervur 0.23.0 → 0.24.0

package/dist/quo/room.js

@@ -1,362 +0,0 @@
-const SIZE = 1_048_576;
-const PK = 32;
-const TAG = 16;
-const SIG = 64;
-const CIPHERTEXT = 1088;
-const MAX_COUNT = 2 ** 53 - 1;
-const COUNT = /^[1-9][0-9]*$/;
-const PK_HEX = /^[0-9a-f]{64}$/;
-const DIGEST = /^[0-9a-f]{16}$/;
-const ZERO_PK = '0'.repeat(64);
-const WORDS = new Set(['removed', 'unannounced', 'repeated']);
-const concat = (...parts) => {
-    const out = new Uint8Array(parts.reduce((sum, part) => sum + part.length, 0));
-    let at = 0;
-    for (const part of parts) {
-        out.set(part, at);
-        at += part.length;
-    }
-    return out;
-};
-export class Room {
-    #keys;
-    #crypto;
-    #tools;
-    constructor(keys, crypto, tools) {
-        this.#keys = keys;
-        this.#crypto = crypto;
-        this.#tools = tools;
-    }
-    #hex(bytes) {
-        return this.#tools.hex(bytes);
-    }
-    #bytes(hex) {
-        const bytes = this.#tools.bytes(hex);
-        if (bytes === null)
-            throw new TypeError('a record holds hex that is not hex');
-        return bytes;
-    }
-    async #cipher(ikm, label) {
-        const out = await this.#crypto.hkdf(ikm, label, 44);
-        return { key: out.subarray(0, 32), nonce: out.subarray(32) };
-    }
-    async #follow(edge, agreement) {
-        return this.#crypto.hkdf(concat(edge, agreement), 'quo-edge', 32);
-    }
-    /** The ward's name: its signing pk, then its padlock, as 128 hex. */
-    async ward() {
-        const ward = await this.#keys.ward();
-        return this.#hex(concat(ward.signing, ward.padlock));
-    }
-    /** A new heir: the invitation to give away, and the occupant to keep. */
-    async invite(at) {
-        const ward = await this.#keys.ward();
-        const secret = this.#crypto.random(32);
-        const heir = this.#hex(await this.#crypto.signingPublic(secret));
-        const invitation = {
-            ward: this.#hex(concat(ward.signing, ward.padlock)),
-            heir,
-            secret: this.#hex(secret),
-            lock: this.#hex(ward.lock),
-            ...(at === undefined ? {} : { at: [...at] }),
-        };
-        return { invitation, occupant: { heir, spent: false, removed: false, held: null, vouched: null, open: null, offered: null, highest: 0 } };
-    }
-    /** The occupant after the door stops holding it: gone while fresh, its keys kept while spent. */
-    release(occupant) {
-        return occupant.spent ? { ...occupant, removed: true } : null;
-    }
-    /** A value read as an invitation, or `null` where it is none. */
-    async invitation(value) {
-        if (typeof value !== 'object' || value === null || Array.isArray(value))
-            return null;
-        const { ward, heir, secret, lock, at } = value;
-        const hex = (field, length) => typeof field === 'string' && field.length === length && this.#tools.bytes(field) !== null;
-        if (!hex(ward, 128) || !hex(heir, 64) || !hex(secret, 64) || !hex(lock, 2368))
-            return null;
-        if ((await this.#crypto.encapsulate(this.#bytes(lock))) === null)
-            return null;
-        const addresses = Array.isArray(at) ? at.filter((entry) => typeof entry === 'string') : undefined;
-        return { ward: ward, heir: heir, secret: secret, lock: lock, ...(addresses === undefined ? {} : { at: addresses }) };
-    }
-    /** A standing on an invitation, before its knock. */
-    standing(invitation) {
-        return { invitation, key: invitation.secret, edge: null, knock: null, bound: false, heard: false, knockedLast: false, sent: 0, moved: 0 };
-    }
-    // ---- the door ----
-    /** A box at the door: refused with its reply, or admitted and waiting for a choice. */
-    async arrive(box, lookup) {
-        const refuse = async (why, lid) => ({ refused: true, reply: (await this.#reply(lid, '{"silence":true}')).box, why });
-        const word = async (why, lid, name) => ({ refused: true, reply: (await this.#reply(lid, `{"quo":"${name}"}`)).box, why });
-        const lid = box.length >= PK ? box.subarray(0, PK) : null;
-        if (box.length > SIZE || lid === null)
-            return refuse(1, lid);
-        const agreement = await this.#keys.agree(lid);
-        if (agreement === null)
-            return refuse(1, lid);
-        const headSeal = await this.#cipher(agreement, 'quo-seal');
-        const head = await this.#crypto.open(headSeal.key, headSeal.nonce, box.subarray(PK, PK + PK + TAG), lid);
-        if (head === null || head.length !== PK)
-            return refuse(1, lid);
-        const zero = head.every((byte) => byte === 0);
-        const heir = zero ? null : this.#hex(head);
-        const occupant = heir === null ? undefined : await lookup.occupant(heir);
-        const fresh = occupant !== undefined && !occupant.spent;
-        // The body, under each edge key the door takes for this head, in order.
-        let rest = box.subarray(PK + PK + TAG);
-        let edges;
-        if (fresh) {
-            if (rest.length < CIPHERTEXT)
-                return refuse(1, lid);
-            const shared = await this.#keys.decapsulate(rest.subarray(0, CIPHERTEXT));
-            edges = [await this.#crypto.hkdf(shared, 'quo-lock', 32)];
-            rest = rest.subarray(CIPHERTEXT);
-        }
-        else if (occupant === undefined)
-            edges = [new Uint8Array(32)];
-        else
-            edges = [occupant.open, occupant.offered].filter((edge) => edge !== null).map((edge) => this.#bytes(edge));
-        let body = null;
-        let under = null;
-        for (const edge of edges) {
-            const seal = await this.#cipher(concat(agreement, edge), 'quo-edge-seal');
-            body = await this.#crypto.open(seal.key, seal.nonce, rest, lid);
-            if (body !== null) {
-                under = edge;
-                break;
-            }
-        }
-        if (body === null || under === null || body.length <= SIG)
-            return refuse(1, lid);
-        const payloadBytes = body.subarray(0, body.length - SIG);
-        const signature = body.subarray(body.length - SIG);
-        const text = this.#tools.text(payloadBytes);
-        const parsed = text === null ? null : this.#tools.parse(text);
-        if (parsed === null || parsed.fields === null || parsed.duplicate)
-            return refuse(2, lid);
-        const payload = parsed.value;
-        const fields = parsed.fields;
-        const pk = (value) => typeof value === 'string' && PK_HEX.test(value) && value !== ZERO_PK;
-        const seqText = fields.seq;
-        const wellFormed = 'to' in fields &&
-            'by' in fields &&
-            'next' in fields &&
-            seqText !== undefined &&
-            (zero ? payload.to === null : payload.to === heir) &&
-            pk(payload.by) &&
-            (payload.next === null || pk(payload.next)) &&
-            COUNT.test(seqText) &&
-            Number(seqText) <= MAX_COUNT &&
-            (!('method' in fields) || typeof payload.method === 'string') &&
-            (!('args' in fields) || (typeof payload.args === 'object' && payload.args !== null && !Array.isArray(payload.args)));
-        if (!wellFormed)
-            return refuse(3, lid);
-        const by = payload.by;
-        const next = payload.next;
-        const seq = Number(seqText);
-        const signedBy = this.#bytes(by);
-        const admitted = {
-            refused: false,
-            heir,
-            by,
-            seq,
-            method: payload.method,
-            args: fields.args ?? '{}',
-            strange: parsed.nestedDuplicate,
-            call: typeof payload.call === 'string' ? payload.call : undefined,
-            within: Number.isSafeInteger(payload.within) && payload.within >= 0 ? payload.within : undefined,
-            after: typeof payload.after === 'string' && DIGEST.test(payload.after) ? payload.after : undefined,
-            signature: this.#hex(signature),
-        };
-        if (zero) {
-            if (!lookup.zero)
-                return refuse(4, lid);
-            if (!(await this.#crypto.verify(signedBy, payloadBytes, signature)))
-                return refuse(5, lid);
-            return { ...admitted, choose: async (choice) => ({ reply: (await this.#reply(lid, this.#write(choice))).box, occupant: null }) };
-        }
-        if (occupant === undefined || (occupant.removed && occupant.held === null))
-            return refuse(6, lid);
-        const keys = fresh ? [occupant.heir] : [occupant.held, occupant.vouched].filter((key) => key !== null);
-        if (!keys.includes(by))
-            return refuse(7, lid);
-        if (!(await this.#crypto.verify(signedBy, payloadBytes, signature)))
-            return refuse(8, lid);
-        if (occupant.removed)
-            return word(9, lid, 'removed');
-        const announced = next === null || next === occupant.heir || next === by ? null : next;
-        if (fresh && announced === null)
-            return word(10, lid, 'unannounced');
-        if (!fresh && seq <= occupant.highest)
-            return word(11, lid, 'repeated');
-        return {
-            ...admitted,
-            choose: async (choice) => {
-                const { box: reply, agreement: replied } = await this.#reply(lid, this.#write(choice));
-                const offered = this.#hex(await this.#follow(under, replied));
-                const open = this.#hex(under);
-                const moved = fresh
-                    ? { ...occupant, spent: true, held: announced, vouched: null, open, offered, highest: seq }
-                    : { ...occupant, held: by, vouched: announced ?? (by === occupant.held ? occupant.vouched : null), open, offered, highest: seq };
-                return { reply, occupant: moved };
-            },
-        };
-    }
-    #write(choice) {
-        if ('silence' in choice)
-            return '{"silence":true}';
-        const at = choice.at === undefined ? '' : `,"at":${JSON.stringify(choice.at)}`;
-        return `{"object":${choice.object},"seen":${JSON.stringify(choice.seen)}${at}}`;
-    }
-    // A reply sealed to a lid, or to a lid nobody holds where the lid takes no seal.
-    async #reply(lid, text) {
-        const secret = this.#crypto.random(32);
-        const pk = await this.#crypto.agreePublic(secret);
-        let to = lid;
-        let agreement = to === null ? null : await this.#crypto.agree(secret, to);
-        if (agreement === null) {
-            to = this.#crypto.random(32);
-            agreement = await this.#crypto.agree(secret, to);
-            if (agreement === null) {
-                to = await this.#crypto.agreePublic(this.#crypto.random(32));
-                agreement = (await this.#crypto.agree(secret, to));
-            }
-        }
-        const textBytes = this.#tools.utf8(text);
-        const signature = await this.#keys.sign(concat(to, textBytes));
-        const seal = await this.#cipher(agreement, 'quo-seal');
-        const sealed = await this.#crypto.seal(seal.key, seal.nonce, concat(textBytes, signature), pk);
-        return { box: concat(pk, sealed), agreement };
-    }
-    // ---- the standing ----
-    /** The next box on a relation: its knock, its knock again, or an ask. */
-    async seal(standing, ask) {
-        const invitation = standing.invitation;
-        const ward = this.#bytes(invitation.ward);
-        const padlock = ward.subarray(32);
-        // A knock no door heard binds nothing, so it goes again alone. After one
-        // that may have been heard and brought no object back, the knock again
-        // and an ask under its own key take turns, until the door is known to
-        // have bound it.
-        if (standing.knock !== null && !standing.bound && (!standing.heard || (!standing.knockedLast && standing.sent > 1))) {
-            const kept = JSON.parse(standing.knock);
-            return { box: this.#bytes(kept.box), pending: kept.pending, standing: { ...standing, knockedLast: true } };
-        }
-        const knock = standing.edge === null;
-        const seq = standing.sent + 1;
-        const nextSecret = this.#crypto.random(32);
-        const next = this.#hex(await this.#crypto.signingPublic(nextSecret));
-        const signing = this.#bytes(standing.key);
-        const by = this.#hex(await this.#crypto.signingPublic(signing));
-        const payload = `{"to":"${invitation.heir}","by":"${by}","next":"${next}","seq":${seq}${ask.method === undefined ? '' : `,"method":${JSON.stringify(ask.method)}`}${ask.args === undefined ? '' : `,"args":${ask.args}`}${ask.call === undefined ? '' : `,"call":${JSON.stringify(ask.call)}`}${ask.within === undefined ? '' : `,"within":${ask.within}`}${ask.after === undefined ? '' : `,"after":"${ask.after}"`}}`;
-        const payloadBytes = this.#tools.utf8(payload);
-        const signature = await this.#crypto.sign(signing, payloadBytes);
-        const lidSecret = this.#crypto.random(32);
-        const lid = await this.#crypto.agreePublic(lidSecret);
-        const agreement = await this.#crypto.agree(lidSecret, padlock);
-        if (agreement === null)
-            throw new TypeError('the ward’s padlock takes no seal');
-        const headSeal = await this.#cipher(agreement, 'quo-seal');
-        const head = await this.#crypto.seal(headSeal.key, headSeal.nonce, this.#bytes(invitation.heir), lid);
-        let edge;
-        let ciphertext = new Uint8Array(0);
-        if (knock) {
-            const encapsulated = await this.#crypto.encapsulate(this.#bytes(invitation.lock));
-            if (encapsulated === null)
-                throw new TypeError('the invitation’s lock is refused');
-            ciphertext = encapsulated.ciphertext;
-            edge = await this.#crypto.hkdf(encapsulated.shared, 'quo-lock', 32);
-        }
-        else
-            edge = this.#bytes(standing.edge);
-        const bodySeal = await this.#cipher(concat(agreement, edge), 'quo-edge-seal');
-        const body = await this.#crypto.seal(bodySeal.key, bodySeal.nonce, concat(payloadBytes, signature), lid);
-        const box = concat(lid, head, ciphertext, body);
-        const pending = { seq, lid: this.#hex(lidSecret), announced: this.#hex(nextSecret), under: this.#hex(edge), knock };
-        // A knock is the one ask after which the door admits one key: the one it
-        // announces, under the knock's edge key. The standing asks under both.
-        const moved = knock
-            ? { ...standing, key: this.#hex(nextSecret), edge: this.#hex(edge), knock: JSON.stringify({ box: this.#hex(box), pending }), sent: seq, knockedLast: false }
-            : { ...standing, sent: seq, knockedLast: false };
-        return { box, pending, standing: moved };
-    }
-    /** A reply read, and the standing moved where an object came back above every ask it moved on. */
-    /** `heard` says whether a box that brought nothing may have reached the door; a reply was heard. */
-    async read(given, pending, reply, heard = true) {
-        const standing = pending.knock && (reply !== null || heard) ? { ...given, heard: true } : given;
-        const { read, agreement } = await this.#reading(standing.invitation.ward, pending.lid, reply);
-        if ('quo' in read) {
-            // A word is said only to an admitted key, so the door holds the relation.
-            return { read, standing: { ...standing, bound: pending.knock ? standing.bound : true } };
-        }
-        if (!('object' in read))
-            return { read, standing };
-        if (pending.seq <= standing.moved)
-            return { read, standing: { ...standing, bound: true } };
-        const edge = this.#hex(await this.#follow(this.#bytes(pending.under), agreement));
-        return { read, standing: { ...standing, key: pending.announced ?? standing.key, edge, moved: pending.seq, bound: true, knock: null } };
-    }
-    // A reply opened under the lid's secret and held to the ward's signature.
-    async #reading(ward, lidHex, reply) {
-        if (reply === null)
-            return { read: { nothing: true }, agreement: null };
-        const silence = { read: { silence: true }, agreement: null };
-        if (reply.length > SIZE || reply.length < PK + TAG + SIG)
-            return silence;
-        const pk = reply.subarray(0, PK);
-        const lidSecret = this.#bytes(lidHex);
-        const agreement = await this.#crypto.agree(lidSecret, pk);
-        if (agreement === null)
-            return silence;
-        const seal = await this.#cipher(agreement, 'quo-seal');
-        const body = await this.#crypto.open(seal.key, seal.nonce, reply.subarray(PK), pk);
-        if (body === null || body.length < SIG)
-            return silence;
-        const textBytes = body.subarray(0, body.length - SIG);
-        const lid = await this.#crypto.agreePublic(lidSecret);
-        const signing = this.#bytes(ward).subarray(0, 32);
-        if (!(await this.#crypto.verify(signing, concat(lid, textBytes), body.subarray(body.length - SIG))))
-            return silence;
-        const text = this.#tools.text(textBytes);
-        const parsed = text === null ? null : this.#tools.parse(text);
-        if (parsed === null || parsed.fields === null || parsed.duplicate)
-            return silence;
-        const value = parsed.value;
-        const keys = Object.keys(parsed.fields);
-        const only = (...names) => keys.length === names.length && names.every((name) => keys.includes(name));
-        if (only('silence') && value.silence === true)
-            return silence;
-        if (only('quo') && typeof value.quo === 'string' && WORDS.has(value.quo))
-            return { read: { quo: value.quo }, agreement };
-        if ((only('object', 'seen') || only('object', 'seen', 'at')) && (value.seen === null || typeof value.seen === 'string')) {
-            // An `at` is read as an invitation's is: no array reads as absent, and an entry that is no string is skipped.
-            const at = Array.isArray(value.at) ? value.at.filter((entry) => typeof entry === 'string') : undefined;
-            return { read: { object: value.object, text: parsed.fields.object, seen: value.seen, ...(at === undefined ? {} : { at }) }, agreement };
-        }
-        return silence;
-    }
-    // ---- a stranger ----
-    /** An ask on the zero head of a ward, signed by `secret`, which the door keeps nothing of. */
-    async stranger(ward, secret, ask) {
-        const padlock = this.#bytes(ward).subarray(32);
-        const signing = this.#bytes(secret);
-        const by = this.#hex(await this.#crypto.signingPublic(signing));
-        const payload = `{"to":null,"by":"${by}","next":null,"seq":1${ask.method === undefined ? '' : `,"method":${JSON.stringify(ask.method)}`}${ask.args === undefined ? '' : `,"args":${ask.args}`}}`;
-        const payloadBytes = this.#tools.utf8(payload);
-        const signature = await this.#crypto.sign(signing, payloadBytes);
-        const lidSecret = this.#crypto.random(32);
-        const lid = await this.#crypto.agreePublic(lidSecret);
-        const agreement = await this.#crypto.agree(lidSecret, padlock);
-        if (agreement === null)
-            throw new TypeError('the ward’s padlock takes no seal');
-        const headSeal = await this.#cipher(agreement, 'quo-seal');
-        const head = await this.#crypto.seal(headSeal.key, headSeal.nonce, new Uint8Array(32), lid);
-        const bodySeal = await this.#cipher(concat(agreement, new Uint8Array(32)), 'quo-edge-seal');
-        const body = await this.#crypto.seal(bodySeal.key, bodySeal.nonce, concat(payloadBytes, signature), lid);
-        return { box: concat(lid, head, body), lid: this.#hex(lidSecret) };
-    }
-    /** A stranger's reply read. */
-    async strangerRead(ward, lid, reply) {
-        return (await this.#reading(ward, lid, reply)).read;
-    }
-}

package/dist/serve/index.d.ts

@@ -1,45 +0,0 @@
-import type { Json } from '../being/being.ts';
-type Answered = {
-    result: Json;
-} | {
-    error: {
-        message: string;
-    };
-};
-/** The faculty's memory, as its lines reach it: every entry's bytes in lowercase hex. */
-interface ServedMemory {
-    read(place: string): Promise<{
-        entries: Record<string, string>;
-        version: string | null;
-    }>;
-    list(): Promise<string[]>;
-    /** Each written place's new version, or `null` where the versions moved and nothing landed. */
-    write(writes: Record<string, Record<string, string | null>>, expect: Record<string, string | null>): Promise<Record<string, string | null> | null>;
-}
-/** What a served method receives beside its args. */
-interface ServeContext {
-    /** The call id: the same on every attempt of one call, so a repeat acts once. */
-    readonly id: string;
-    /**
-     * A handle the program was handed, called; its answer, or its error. Its
-     * call id is `id` where given, and otherwise this call's own id and the
-     * count of handles it has called, so the same on every attempt of this
-     * call, in any life of the program.
-     */
-    call(token: string, args?: Json, id?: string): Promise<Answered>;
-    /** The faculty's own memory, sealed by the ground; a line the ground refuses throws. */
-    readonly memory: ServedMemory;
-}
-type Method = (args: {
-    readonly [key: string]: Json;
-}, context: ServeContext) => Json | Promise<Json>;
-/**
- * Serves `methods` on the standard streams under `need`'s blueprint, and
- * `window`, how long the program remembers a call id. A method that
- * throws answers an error, which is final; a program that must be asked
- * again exits instead, and the ground starts it again.
- */
-export declare const serve: (need: unknown, methods: Readonly<Record<string, Method>>, { window }?: {
-    window?: number;
-}) => void;
-export {};

package/dist/serve/index.js

@@ -1,71 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// `nervur/serve`: the program's side of the bridge, for a faculty written
-// in JavaScript and run beside a ground. It answers `describe` with the
-// blueprint, and every other line with the method it names. A method
-// receives its args and a context: the call id, a way to call a handle it
-// was handed, and the faculty's memory.
-import { createInterface } from 'node:readline';
-import { blueprintOf } from '../being/need.js';
-/**
- * Serves `methods` on the standard streams under `need`'s blueprint, and
- * `window`, how long the program remembers a call id. A method that
- * throws answers an error, which is final; a program that must be asked
- * again exits instead, and the ground starts it again.
- */
-export const serve = (need, methods, { window } = {}) => {
-    const blueprint = blueprintOf(need);
-    if (blueprint === undefined)
-        throw new TypeError('serve takes a need');
-    const write = (message) => process.stdout.write(`${JSON.stringify(message)}\n`);
-    const waiting = new Map();
-    let next = 0;
-    // One line of the program's own, and the ground's answer to it.
-    const asked = (line) => new Promise((resolve) => {
-        const sent = `p${++next}`;
-        waiting.set(sent, resolve);
-        write({ id: sent, ...line });
-    });
-    const remembered = async (op, args) => {
-        const answer = await asked({ memory: op, args });
-        if ('error' in answer)
-            throw new Error(answer.error.message);
-        return answer.result;
-    };
-    const memory = {
-        read: async (place) => (await remembered('read', { place })),
-        list: async () => (await remembered('list', {})),
-        write: async (writes, expect) => (await remembered('write', { writes, expect })),
-    };
-    createInterface({ input: process.stdin, crlfDelay: Infinity }).on('line', (line) => {
-        const message = JSON.parse(line);
-        // The house's answer to a handle this program called.
-        if (message.method === undefined) {
-            const answered = waiting.get(String(message.id));
-            waiting.delete(String(message.id));
-            answered?.('error' in message && message.error !== undefined ? { error: message.error } : { result: message.result ?? null });
-            return;
-        }
-        if (message.method === 'describe') {
-            write({ id: message.id, result: { blueprint: JSON.parse(JSON.stringify(blueprint)), ...(window === undefined ? {} : { window }) } });
-            return;
-        }
-        const method = methods[message.method];
-        const served = message.call ?? '';
-        let called = 0;
-        const context = {
-            id: served,
-            call: (token, args = {}, id = served === '' ? '' : `${served}:${++called}`) => id === '' ? Promise.resolve({ error: { message: 'a handle is called with a call id of the program’s own' } }) : asked({ token, args, call: id }),
-            memory,
-        };
-        void (async () => {
-            if (method === undefined)
-                return write({ id: message.id, error: { message: `no method ${message.method}` } });
-            try {
-                write({ id: message.id, result: await method(message.args ?? {}, context) });
-            }
-            catch (error) {
-                write({ id: message.id, error: { message: error instanceof Error ? error.message : String(error) } });
-            }
-        })();
-    });
-};