nervur 0.22.0 → 0.22.2-3

package/dist/bodies/seed-keys.js

@@ -0,0 +1,42 @@
+import { NobleCrypto } from './noble-crypto.js';
+const SEED = /^[0-9a-f]{64}$/;
+export class SeedKeys {
+    #seed;
+    #crypto;
+    #held;
+    constructor(seed, crypto = new NobleCrypto()) {
+        if (typeof seed !== 'string' || !SEED.test(seed))
+            throw new TypeError('a seed is sixty-four lowercase hex digits');
+        this.#seed = Uint8Array.from(seed.match(/../g), (pair) => Number.parseInt(pair, 16));
+        this.#crypto = crypto;
+    }
+    #keys() {
+        this.#held ??= (async () => {
+            const crypto = this.#crypto;
+            const signing = await crypto.hkdf(this.#seed, 'quo-ward-sign', 32);
+            const scalar = await crypto.hkdf(this.#seed, 'quo-ward-seal', 32);
+            // The lock is the kit's: one per ward, drawn from the seed under a label of Nervur's.
+            const lock = await crypto.lockPair(await crypto.hkdf(this.#seed, 'nervur-lock', 64));
+            const ward = Object.freeze({ signing: await crypto.signingPublic(signing), padlock: await crypto.agreePublic(scalar), lock: lock.encapsulation });
+            return { signing, scalar, decapsulation: lock.decapsulation, ward };
+        })();
+        return this.#held;
+    }
+    async ward() {
+        return (await this.#keys()).ward;
+    }
+    async sign(message) {
+        return this.#crypto.sign((await this.#keys()).signing, message);
+    }
+    async agree(pk) {
+        return this.#crypto.agree((await this.#keys()).scalar, pk);
+    }
+    async decapsulate(ciphertext) {
+        return this.#crypto.decapsulate((await this.#keys()).decapsulation, ciphertext);
+    }
+    async derive(label, length) {
+        if (label.startsWith('quo-'))
+            throw new TypeError('a label beginning quo- is Quo\'s');
+        return this.#crypto.hkdf(this.#seed, `nervur-derive:${label}`, length);
+    }
+}

package/dist/bodies/strict-tools.d.ts

@@ -0,0 +1,10 @@
+import type { Parsed, Tools } from '../foundation.ts';
+export declare class StrictTools implements Tools {
+    utf8(text: string): Uint8Array;
+    text(bytes: Uint8Array): string | null;
+    hex(bytes: Uint8Array): string;
+    bytes(hex: string): Uint8Array | null;
+    parse(text: string): Parsed | null;
+    canonical(value: unknown): string;
+    check(schema: unknown, value: unknown): string | null;
+}

package/dist/bodies/strict-tools.js

@@ -0,0 +1,306 @@
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const HEX = /^(?:[0-9a-f]{2})*$/;
+const NUMBER = /-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/y;
+const ESCAPES = { '"': '"', '\\': '\\', '/': '/', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t' };
+const define = (target, key, value) => Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+// An iterative reader, so no nesting a sender writes can exhaust the stack.
+const read = (text) => {
+    const length = text.length;
+    let at = 0;
+    let duplicate = false;
+    let nestedDuplicate = false;
+    let fields = null;
+    const stack = [];
+    const space = () => {
+        while (at < length) {
+            const code = text.charCodeAt(at);
+            if (code !== 0x20 && code !== 0x09 && code !== 0x0a && code !== 0x0d)
+                return;
+            at++;
+        }
+    };
+    const string = () => {
+        if (text[at] !== '"')
+            return null;
+        at++;
+        let out = '';
+        let from = at;
+        while (at < length) {
+            const code = text.charCodeAt(at);
+            if (code === 0x22) {
+                out += text.slice(from, at);
+                at++;
+                return out;
+            }
+            if (code < 0x20)
+                return null;
+            if (code === 0x5c) {
+                out += text.slice(from, at);
+                const escape = text[at + 1];
+                if (escape === 'u') {
+                    const digits = text.slice(at + 2, at + 6);
+                    if (!/^[0-9a-fA-F]{4}$/.test(digits))
+                        return null;
+                    out += String.fromCharCode(Number.parseInt(digits, 16));
+                    at += 6;
+                }
+                else {
+                    const plain = escape === undefined ? undefined : ESCAPES[escape];
+                    if (plain === undefined)
+                        return null;
+                    out += plain;
+                    at += 2;
+                }
+                from = at;
+                continue;
+            }
+            at++;
+        }
+        return null;
+    };
+    const key = (frame) => {
+        const name = string();
+        if (name === null)
+            return false;
+        space();
+        if (text[at] !== ':')
+            return false;
+        at++;
+        space();
+        if (frame.keys.has(name)) {
+            if (stack[0] === frame)
+                duplicate = true;
+            else
+                nestedDuplicate = true;
+        }
+        frame.keys.add(name);
+        frame.key = name;
+        frame.start = at;
+        return true;
+    };
+    for (;;) {
+        space();
+        let value;
+        const char = text[at];
+        if (char === '{') {
+            at++;
+            space();
+            const frame = { object: true, value: {}, keys: new Set(), key: '', start: 0 };
+            if (text[at] === '}') {
+                at++;
+                value = frame.value;
+            }
+            else {
+                stack.push(frame);
+                if (stack.length === 1)
+                    fields = Object.create(null);
+                if (!key(frame))
+                    return null;
+                continue;
+            }
+        }
+        else if (char === '[') {
+            at++;
+            space();
+            if (text[at] === ']') {
+                at++;
+                value = [];
+            }
+            else {
+                stack.push({ object: false, value: [] });
+                continue;
+            }
+        }
+        else if (char === '"') {
+            value = string();
+            if (value === null)
+                return null;
+        }
+        else if (text.startsWith('true', at)) {
+            at += 4;
+            value = true;
+        }
+        else if (text.startsWith('false', at)) {
+            at += 5;
+            value = false;
+        }
+        else if (text.startsWith('null', at)) {
+            at += 4;
+            value = null;
+        }
+        else {
+            NUMBER.lastIndex = at;
+            const number = NUMBER.exec(text);
+            if (number === null)
+                return null;
+            at += number[0].length;
+            value = Number(number[0]);
+        }
+        // The value is whole: set it in its container, and close what it ends.
+        for (;;) {
+            const top = stack.at(-1);
+            if (top === undefined) {
+                space();
+                if (at !== length)
+                    return null;
+                if (!(typeof value === 'object' && value !== null && !Array.isArray(value)))
+                    fields = null;
+                return { value, fields, duplicate, nestedDuplicate };
+            }
+            if (top.object) {
+                if (stack.length === 1 && fields !== null)
+                    fields[top.key] = text.slice(top.start, at);
+                define(top.value, top.key, value);
+                space();
+                if (text[at] === ',') {
+                    at++;
+                    space();
+                    if (!key(top))
+                        return null;
+                    break;
+                }
+                if (text[at] !== '}')
+                    return null;
+            }
+            else {
+                top.value.push(value);
+                space();
+                if (text[at] === ',') {
+                    at++;
+                    break;
+                }
+                if (text[at] !== ']')
+                    return null;
+            }
+            at++;
+            stack.pop();
+            value = top.value;
+        }
+    }
+};
+const canonical = (value) => {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new TypeError('a number that is not finite has no JSON');
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+        const keys = Object.keys(value).sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+    }
+    throw new TypeError('the value is not JSON');
+};
+export class StrictTools {
+    utf8(text) {
+        return encoder.encode(text);
+    }
+    text(bytes) {
+        try {
+            return decoder.decode(bytes);
+        }
+        catch {
+            return null;
+        }
+    }
+    hex(bytes) {
+        let out = '';
+        for (const byte of bytes)
+            out += byte.toString(16).padStart(2, '0');
+        return out;
+    }
+    bytes(hex) {
+        if (typeof hex !== 'string' || !HEX.test(hex))
+            return null;
+        const out = new Uint8Array(hex.length / 2);
+        for (let at = 0; at < out.length; at++)
+            out[at] = Number.parseInt(hex.slice(at * 2, at * 2 + 2), 16);
+        return out;
+    }
+    parse(text) {
+        return read(text);
+    }
+    canonical(value) {
+        return canonical(value);
+    }
+    check(schema, value) {
+        return check(schema, value, 'the value');
+    }
+}
+const typeOf = (value) => {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'number')
+        return Number.isInteger(value) ? 'integer' : 'number';
+    return typeof value;
+};
+// The closed subset, read as JSON Schema 2020-12 reads it.
+const check = (schema, value, at) => {
+    if (typeof schema !== 'object' || schema === null)
+        return `${at} meets no schema`;
+    const type = schema.type;
+    if (type !== undefined) {
+        const actual = typeOf(value);
+        const fits = actual === type || (type === 'number' && actual === 'integer');
+        if (!fits)
+            return `${at} is not ${type === 'integer' || type === 'array' || type === 'object' ? 'an' : 'a'} ${type}`;
+    }
+    if ('const' in schema && schema.const !== value)
+        return `${at} is not ${JSON.stringify(schema.const)}`;
+    if (Array.isArray(schema.enum) && !schema.enum.includes(value))
+        return `${at} is none of ${JSON.stringify(schema.enum)}`;
+    if (typeof value === 'string') {
+        const length = [...value].length;
+        if (typeof schema.minLength === 'number' && length < schema.minLength)
+            return `${at} is shorter than ${schema.minLength}`;
+        if (typeof schema.maxLength === 'number' && length > schema.maxLength)
+            return `${at} is longer than ${schema.maxLength}`;
+        if (typeof schema.pattern === 'string' && !new RegExp(schema.pattern, 'u').test(value))
+            return `${at} does not match ${schema.pattern}`;
+        if (schema.contentEncoding === 'base16' && !HEX.test(value))
+            return `${at} is not lowercase hex`;
+    }
+    if (typeof value === 'number') {
+        if (typeof schema.minimum === 'number' && value < schema.minimum)
+            return `${at} is below ${schema.minimum}`;
+        if (typeof schema.maximum === 'number' && value > schema.maximum)
+            return `${at} is above ${schema.maximum}`;
+    }
+    if (Array.isArray(value) && schema.items !== undefined) {
+        for (let index = 0; index < value.length; index++) {
+            const found = check(schema.items, value[index], `${at}[${index}]`);
+            if (found !== null)
+                return found;
+        }
+    }
+    if (typeOf(value) === 'object') {
+        const object = value;
+        const properties = (schema.properties ?? {});
+        for (const key of (schema.required ?? []))
+            if (!Object.hasOwn(object, key))
+                return `${at}.${key} is missing`;
+        for (const [key, field] of Object.entries(object)) {
+            const inner = Object.hasOwn(properties, key) ? properties[key] : undefined;
+            if (inner === undefined) {
+                if (schema.additionalProperties === false)
+                    return `${at}.${key} is not allowed`;
+                continue;
+            }
+            const found = check(inner, field, `${at}.${key}`);
+            if (found !== null)
+                return found;
+        }
+    }
+    if (Array.isArray(schema.anyOf)) {
+        const reasons = schema.anyOf.map((branch) => check(branch, value, at));
+        if (!reasons.includes(null))
+            return reasons[0] ?? `${at} meets no branch`;
+    }
+    return null;
+};

package/dist/bodies/web-carry.d.ts

@@ -0,0 +1,65 @@
+import type { Carry, Sent } from '../foundation.ts';
+/** A WebSocket the ground's listener opened: bytes out, and closing. */
+export interface HeldSocket {
+    send(data: Uint8Array): void;
+    close(): void;
+}
+/** What a handler does with a WebSocket once it is open. */
+export interface Held {
+    message(data: Uint8Array | string): void;
+    close(): void;
+}
+/**
+ * Whatever speaks HTTP on a ground. `fetch` answers a request, or `null`
+ * where it is not this handler's. `upgrade` takes a WebSocket: the
+ * subprotocol it selects, and what it does once the socket is open.
+ */
+export interface Handler {
+    fetch(request: Request): Promise<Response | null>;
+    upgrade?(request: Request): {
+        protocol: string;
+        open(socket: HeldSocket): Held;
+    } | null;
+}
+type Door = (box: Uint8Array) => Promise<Uint8Array | null>;
+export declare class WebCarry implements Carry, Handler {
+    #private;
+    /**
+     * `path` is where it listens under the ground's listener, `/quo` where
+     * omitted. `addresses` are written into invitations, or read each time
+     * where the listener's port is known only once it listens. `origins` are
+     * the pages of other origins it answers, by the CORS protocol.
+     */
+    constructor({ path, addresses, origins, allowPrivate, wait, }?: {
+        path?: string;
+        addresses?: readonly string[] | (() => readonly string[]);
+        origins?: readonly string[];
+        allowPrivate?: boolean;
+        wait?: number;
+    });
+    /** A ward's door, answered on the post and on held lines alike. */
+    listen({ ward, door }: {
+        ward: string;
+        door: Door;
+    }): void;
+    /** A ward this handler answers no more. */
+    unlisten({ ward }: {
+        ward: string;
+    }): void;
+    at(_options?: {
+        toward?: string;
+    }): readonly string[];
+    fetch(request: Request): Promise<Response | null>;
+    upgrade(request: Request): {
+        protocol: string;
+        open(socket: HeldSocket): Held;
+    } | null;
+    send({ ward, at, box }: {
+        ward: string;
+        at: readonly string[];
+        box: Uint8Array;
+    }): Promise<Sent>;
+    /** Closes every held line it dialled. */
+    close(): Promise<void>;
+}
+export {};

package/dist/bodies/web-carry.js

@@ -0,0 +1,224 @@
+import { ASK, NOTHING, PK, REPLY, body, privateHost, read } from '../quo/frame.js';
+/** The longest post: a ward pk and the longest box. */
+const LONGEST_POST = 1_048_640;
+const PROTOCOL = 'quo';
+// Errors of a connection never made: the box went nowhere.
+const UNREACHED = new Set(['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'EHOSTUNREACH', 'ENETUNREACH', 'UND_ERR_CONNECT_TIMEOUT']);
+const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+const unhex = (text) => Uint8Array.from(text.match(/../g) ?? [], (pair) => Number.parseInt(pair, 16));
+const joined = (a, b) => {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a);
+    out.set(b, a.length);
+    return out;
+};
+export class WebCarry {
+    #doors = new Map();
+    #lines = new Map();
+    #path;
+    #addresses;
+    #origins;
+    #allowPrivate;
+    #wait;
+    /**
+     * `path` is where it listens under the ground's listener, `/quo` where
+     * omitted. `addresses` are written into invitations, or read each time
+     * where the listener's port is known only once it listens. `origins` are
+     * the pages of other origins it answers, by the CORS protocol.
+     */
+    constructor({ path = '/quo', addresses = [], origins = [], allowPrivate = false, wait = 30_000, } = {}) {
+        this.#path = path;
+        this.#addresses = addresses;
+        this.#origins = new Set(origins);
+        this.#allowPrivate = allowPrivate;
+        this.#wait = wait;
+    }
+    /** A ward's door, answered on the post and on held lines alike. */
+    listen({ ward, door }) {
+        this.#doors.set(ward, door);
+    }
+    /** A ward this handler answers no more. */
+    unlisten({ ward }) {
+        this.#doors.delete(ward);
+    }
+    at(_options = {}) {
+        return typeof this.#addresses === 'function' ? this.#addresses() : this.#addresses;
+    }
+    // ---- the listener ----
+    #cors(request) {
+        const origin = request.headers.get('origin');
+        return origin !== null && (this.#origins.has(origin) || this.#origins.has('*')) ? { 'access-control-allow-origin': origin, vary: 'origin' } : {};
+    }
+    async fetch(request) {
+        if (new URL(request.url).pathname !== this.#path)
+            return null;
+        const cors = this.#cors(request);
+        if (request.method === 'OPTIONS' && 'access-control-allow-origin' in cors) {
+            return new Response(null, { status: 204, headers: { ...cors, 'access-control-allow-methods': 'POST', 'access-control-allow-headers': 'content-type' } });
+        }
+        if (request.method !== 'POST')
+            return new Response(null, { status: 405, headers: cors });
+        const bytes = new Uint8Array(await request.arrayBuffer());
+        if (bytes.length <= PK || bytes.length > LONGEST_POST)
+            return new Response(null, { status: 400, headers: cors });
+        const door = this.#doors.get(hex(bytes.subarray(0, PK)));
+        if (door === undefined)
+            return new Response(null, { status: 404, headers: cors });
+        const reply = await door(bytes.slice(PK)).catch(() => null);
+        if (reply === null)
+            return new Response(null, { status: 204, headers: cors });
+        return new Response(new Uint8Array(reply), { status: 200, headers: { ...cors, 'content-type': 'application/octet-stream' } });
+    }
+    upgrade(request) {
+        if (new URL(request.url).pathname !== this.#path)
+            return null;
+        const offered = (request.headers.get('sec-websocket-protocol') ?? '').split(',').map((protocol) => protocol.trim());
+        if (!offered.includes(PROTOCOL))
+            return null;
+        return {
+            protocol: PROTOCOL,
+            open: (socket) => ({
+                message: (data) => {
+                    const frame = typeof data === 'string' ? null : read(data);
+                    if (frame === null)
+                        return socket.close();
+                    // A reply or a nothing frame is not a listener's to read.
+                    if (frame.kind !== ASK)
+                        return;
+                    const door = this.#doors.get(hex(frame.rest.subarray(0, PK)));
+                    void (door === undefined ? Promise.resolve(null) : door(frame.rest.slice(PK)).catch(() => null)).then((reply) => {
+                        try {
+                            socket.send(reply === null ? body(NOTHING, frame.id, new Uint8Array()) : body(REPLY, frame.id, reply));
+                        }
+                        catch {
+                            // The line went while the door answered.
+                        }
+                    });
+                },
+                close: () => undefined,
+            }),
+        };
+    }
+    // ---- the dialer ----
+    async send({ ward, at, box }) {
+        // A ward this carry listens for is on this ground: its door takes the box by pointer.
+        const door = this.#doors.get(ward);
+        if (door !== undefined) {
+            const reply = await door(box).catch(() => null);
+            if (reply !== null)
+                return { reply };
+        }
+        for (const address of at) {
+            let url;
+            try {
+                url = new URL(address);
+            }
+            catch {
+                continue;
+            }
+            if (!this.#allowPrivate && privateHost(url.hostname))
+                continue;
+            const scheme = url.protocol.slice(0, -1);
+            const answer = scheme === 'http' || scheme === 'https' ? await this.#post(address, ward, box) : scheme === 'ws' || scheme === 'wss' ? await this.#held(address, ward, box) : 'unheard';
+            // A reply ends it; an ask that may have been heard is not carried again.
+            if (answer === 'heard')
+                return { reply: null, heard: true };
+            if (answer !== 'unheard')
+                return { reply: answer, via: address };
+        }
+        return { reply: null, heard: false };
+    }
+    async #post(address, ward, box) {
+        const abort = new AbortController();
+        const timer = setTimeout(() => abort.abort(), this.#wait);
+        try {
+            const response = await fetch(address, { method: 'POST', body: joined(unhex(ward), box), signal: abort.signal });
+            if (response.status !== 200) {
+                await response.body?.cancel();
+                return 'unheard';
+            }
+            const reply = new Uint8Array(await response.arrayBuffer());
+            return reply.length > 0 ? reply : 'unheard';
+        }
+        catch (error) {
+            // A connection never made, or a port the fetch standard blocks, sent nothing.
+            const cause = error.cause;
+            const unsent = (typeof cause?.code === 'string' && UNREACHED.has(cause.code)) || cause?.message === 'bad port';
+            return !abort.signal.aborted && unsent ? 'unheard' : 'heard';
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async #held(address, ward, box) {
+        let line;
+        try {
+            line = await this.#line(address);
+        }
+        catch {
+            return 'unheard';
+        }
+        const id = line.next;
+        line.next = (line.next + 1) >>> 0;
+        const answered = new Promise((resolve) => line.pending.set(id, resolve));
+        try {
+            line.socket.send(body(ASK, id, joined(unhex(ward), box)));
+        }
+        catch {
+            line.pending.delete(id);
+            return 'unheard';
+        }
+        let timer;
+        const late = new Promise((resolve) => (timer = setTimeout(() => resolve(null), this.#wait)));
+        const frame = await Promise.race([answered, late]);
+        clearTimeout(timer);
+        line.pending.delete(id);
+        if (frame === null)
+            return 'heard';
+        return frame.kind === REPLY ? frame.rest : 'unheard';
+    }
+    #line(address) {
+        let held = this.#lines.get(address);
+        if (held === undefined) {
+            held = new Promise((resolve, reject) => {
+                const socket = new WebSocket(address, [PROTOCOL]);
+                socket.binaryType = 'arraybuffer';
+                const line = { socket, pending: new Map(), next: 1 };
+                let open = false;
+                socket.onopen = () => {
+                    if (socket.protocol !== PROTOCOL)
+                        return socket.close();
+                    open = true;
+                    resolve(line);
+                };
+                socket.onmessage = (event) => {
+                    const frame = typeof event.data === 'string' ? null : read(new Uint8Array(event.data));
+                    if (frame === null)
+                        return socket.close();
+                    // An ask is not a dialer's to read: nothing is said to it, and the line stands.
+                    if (frame.kind === ASK)
+                        return;
+                    line.pending.get(frame.id)?.(frame);
+                };
+                socket.onclose = () => {
+                    this.#lines.delete(address);
+                    for (const settle of line.pending.values())
+                        settle(null);
+                    line.pending.clear();
+                    if (!open)
+                        reject(new Error(`no held line to ${address}`));
+                };
+                socket.onerror = () => undefined;
+            });
+            this.#lines.set(address, held);
+            held.catch(() => this.#lines.delete(address));
+        }
+        return held;
+    }
+    /** Closes every held line it dialled. */
+    async close() {
+        for (const line of this.#lines.values())
+            void line.then((held) => held.socket.close(), () => undefined);
+        this.#lines.clear();
+    }
+}

package/dist/bodies/web-clock.d.ts

@@ -0,0 +1,12 @@
+import type { Clock } from '../foundation.ts';
+export declare class WebClock implements Clock {
+    #private;
+    now(): number;
+    wait({ id, ms }: {
+        id: string;
+        ms: number;
+    }): Promise<boolean>;
+    cancel({ id }: {
+        id: string;
+    }): void;
+}

package/dist/bodies/web-clock.js

@@ -0,0 +1,33 @@
+// A timer holds at most this long; a longer wait is a chain of them.
+const LONGEST = 2 ** 31 - 1;
+export class WebClock {
+    #waits = new Map();
+    now() {
+        return Date.now();
+    }
+    wait({ id, ms }) {
+        this.cancel({ id });
+        const at = Date.now() + Math.max(0, ms);
+        return new Promise((resolve) => {
+            const arm = () => {
+                const left = at - Date.now();
+                const timer = setTimeout(() => {
+                    if (at > Date.now())
+                        return arm();
+                    this.#waits.delete(id);
+                    resolve(true);
+                }, Math.min(Math.max(0, left), LONGEST));
+                this.#waits.set(id, { timer, resolve });
+            };
+            arm();
+        });
+    }
+    cancel({ id }) {
+        const held = this.#waits.get(id);
+        if (held === undefined)
+            return;
+        clearTimeout(held.timer);
+        this.#waits.delete(id);
+        held.resolve(false);
+    }
+}