@nervur-org/dock 0.5.0 → 0.6.0

package/dist/dock/index.js

@@ -1,113 +0,0 @@
-import { isInvitation } from 'nervur';
-import { Faculty } from './faculty.js';
-import { Console, CONSOLE } from './console.js';
-import { Local } from './local.js';
-import { Location } from './location.js';
-import { Notifications } from './notifications.js';
-import { Push } from './push.js';
-import { Timer } from './timer.js';
-export { Console, CONSOLE } from './console.js';
-export { Faculty, join, settled } from './faculty.js';
-export { Local, LOCAL } from './local.js';
-export { Location } from './location.js';
-export { Notifications } from './notifications.js';
-export { Push, isToken, bellOf, banner, sealBanner, SEAL } from './push.js';
-export { Timer } from './timer.js';
-// The three grounds the push faculty rings through, and the bell service
-// that holds a publisher's keys: what the box can do, beside the faculty.
-export { webPush, mintVapid, publicOf } from './webpush.js';
-export { apnsPush, pkcs8, HOSTS } from './apns.js';
-export { fcmPush, isAccount, DOORS } from './fcm.js';
-export { handedTo, ringing, routed } from './service.js';
-// The names this package lends under. They are conventions of the dock and
-// nothing of Quo's: a name is the harbor's namespace, and a being holds each
-// one under an id of her own choosing.
-export const LOCATION = 'location';
-export const NOTIFICATIONS = 'notifications';
-export const PUSH = 'push';
-export const TIMER = 'timer';
-// The classes every dock ward may hold, by class name. A terrain hands its
-// own subclasses under the same names and the harbor holds those instead.
-// `local` and `grants` are not among them: the box's way in and the box's
-// grants stand only where a terrain serves routes, and that terrain adds
-// them to what it lends. `Grants` is not in this file at all, so that a tab
-// bundling this index carries no route's notion: the terrain that serves
-// routes hands her class to its harbor, as the daemon hands its own push.
-export const FACULTIES = { [LOCATION]: 'Location', [NOTIFICATIONS]: 'Notifications', [PUSH]: 'Push', [TIMER]: 'Timer' };
-export const FACULTY_CLASSES = { Console, Local, Location, Notifications, Push, Timer };
-// The name a harbor keeps its own ward under. It is a ward in every other
-// respect, and this one is never adopted or dropped as a migration: its
-// beings are the box's and die with it.
-export const DOCK = 'dock';
-// Put the dock ward up and answer the `lend` this harbor hands its wards.
-// `lent` says which names this box offers and which class stands for each;
-// a name it does not hold is null, and so is every other kind of no.
-//
-// The harbor keeps this ward's ask pointer rather than handing it out, so it
-// is the root here, and the root may invite on any being of its ward. That
-// is the whole of what `lend` does: it never mints, it asks its own root to.
-export async function stand(harbor, lent = FACULTIES) {
-    const kept = await harbor.store.load(DOCK);
-    const ward = harbor.wards.get(DOCK) ?? (kept ? await harbor.host(DOCK, kept) : await harbor.create(DOCK, CONSOLE));
-    return standOn(ward, lent);
-}
-// The faculties up in a ward already made, and the `lend` that reaches them.
-// Apart from `stand` so a suite can put its own stubs in its own ward and
-// get the same thing a box gets. It is run again at every boot and says the
-// same thing twice without harm: a key already booted is refused, and an
-// invitation on an id already held is null.
-export async function standOn(ward, lent = FACULTIES) {
-    for (const [name, className] of Object.entries(lent))
-        await ward.ask('boot', { key: name, class: className });
-    // The box as one being, carrying what it stood. She is the page a device
-    // that has joined no world shows, and she is placed by the root because
-    // the root is the box: a standing at every faculty, minted and knocked in
-    // one move, as an owner places any relation into a being of its ward.
-    await ward.ask('boot', { key: CONSOLE, class: 'Console' });
-    for (const name of Object.keys(lent)) {
-        const inv = await ward.ask('invite', { being: name, id: `${CONSOLE}:${name}` });
-        if (!isInvitation(inv))
-            continue;
-        await ward.ask('knock', { being: CONSOLE, id: name, invitation: inv });
-    }
-    await ward.save?.();
-    return lending(ward);
-}
-// The root's half alone: a name and a taker in, whether the ward took it out.
-// It never mints; it asks the root of the ward it holds to, which is what a
-// root may do on any being of its ward. And it unmints: a taker that would
-// not take leaves an occupant on that faculty which nobody holds, so the root
-// removes it before answering, and a refused lend costs the box nothing.
-//
-// Any being of the dock ward is lent by her key, not only the ones a terrain
-// stood: the faculties the dock ships are examples, and an estate boots its
-// own into the dock ward, of a class in its own `classes/`, and lends it the
-// same way. A name nobody there answers to is refused at the invite.
-//
-// The id is drawn and never counted. A faculty's occupants are in her cells
-// and outlive the process, so a count that started again at every boot would
-// name, on the first lend after a restart, an id she already holds, and the
-// invite would be refused for the rest of the box's life.
-export function lending(ward) {
-    return async (name, take) => {
-        const id = `lent:${fresh()}`;
-        const out = await ward.ask('invite', { being: name, id });
-        if (!isInvitation(out))
-            return false;
-        const took = await take(out);
-        if (!took)
-            await ward.ask('remove', { being: name, id });
-        await ward.save?.();
-        return took;
-    };
-}
-const fresh = () => Array.from(globalThis.crypto.getRandomValues(new Uint8Array(8)))
-    .map((b) => b.toString(16).padStart(2, '0'))
-    .join('');
-// One faculty of this box, as the device's own code holds it: the object the
-// harbor made, in this process. Not a path around a door, and nothing of it
-// crosses an edge; it is how a device fires its own timer at a moment it
-// names and how a suite reads what a stub recorded.
-export function facultyOf(harbor, name) {
-    return harbor.wards.get(DOCK)?.being(name);
-}

package/dist/dock/local.js

@@ -1,44 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The box's way in: `local`, one faculty of the dock ward. The daemon saw a
-// process reach a socket only the device's user can open, and that is the
-// whole of the vouch; file permissions are the device's rules, which is what
-// `quo/SPEC.md` allows a harbor to hand the root by.
-//
-// She holds the nonces this box minted, in this process and never in cells:
-// a vouch that outlived a restart would be a vouch for a process that is
-// gone. Each is honoured once, and a `local` proof arriving any other way
-// names no nonce and is refused.
-//
-// The device's own code mints on her directly, as a device fires its own
-// timer: `mint` is not an ask, it crosses no door, and nothing at a door
-// can reach it. The desk asks `verify` at her standing, as she asks any way
-// in.
-import { Faculty } from './faculty.js';
-import { VERIFY } from '../beings/way.js';
-// The name the dock ward lends her under. A box with no local side lends no
-// such name, and the desk there holds no such standing.
-export const LOCAL = 'local';
-export class Local extends Faculty {
-    static asks = { verify: VERIFY };
-    #nonces = new Map();
-    // A nonce for one client this box saw itself, spent by the first proof
-    // that names it. The caller drops it when the admit is over: a nonce that
-    // was never spent is not a way in that stays open.
-    mint(nonce, who) {
-        this.#nonces.set(nonce, who);
-    }
-    drop(nonce) {
-        this.#nonces.delete(nonce);
-    }
-    verify(args) {
-        const proof = args.proof;
-        if (!proof || typeof proof !== 'object' || Array.isArray(proof))
-            return null;
-        const nonce = proof.nonce;
-        const who = typeof nonce === 'string' ? this.#nonces.get(nonce) : undefined;
-        if (!who)
-            return null;
-        this.#nonces.delete(nonce);
-        return who;
-    }
-}

package/dist/dock/location.js

@@ -1,11 +0,0 @@
-import { Faculty } from './faculty.js';
-export class Location extends Faculty {
-    static asks = {
-        where: { description: 'where this box is', input: { type: 'object' } },
-    };
-    // The platform's own permission prompt is the first ask's, and a refusal is
-    // the error object every ask after it answers.
-    where() {
-        return Promise.resolve({ error: 'this box cannot say where it is' });
-    }
-}

package/dist/dock/push.js

@@ -1,132 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Waking a device that is not reachable, the one way its platform allows: a
-// push that carries the device's token and the banner sealed to that
-// device's own key, which nothing between the world and the phone can
-// read. A token names its
-// kind, and a kind is one ring: `web` is Web Push under a keypair a world
-// mints itself, `apns` and `fcm` are the two stores' own, handed on to the
-// publisher's bell service by a world that holds no platform key. A box that
-// was given no ring for a kind says so, which is what a world that rings no
-// iPhones says to one.
-//
-// The rings are live objects and not values, so they are not cells: a
-// terrain subclasses and builds its own in `rings`, out of what its
-// environment and this being's cells give it.
-import { OWNER } from 'nervur';
-import { arithmetic } from 'nervur/ward';
-import { Faculty } from './faculty.js';
-import { mintVapid } from './webpush.js';
-export const isToken = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && typeof v.kind === 'string';
-// The bell a token names, when it names one a ring can reach.
-export function bellOf(token) {
-    if (typeof token.bell !== 'string')
-        return undefined;
-    try {
-        const u = new URL(token.bell);
-        return u.protocol === 'https:' || u.protocol === 'http:' ? token.bell : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-// What a platform will carry, so a seal too big is refused where a human
-// can still read why rather than two hops later by a service nobody reads.
-export const SEAL = 4096;
-// The line a device shows when it was woken while nobody was looking,
-// composed from one object. A pushed object is whatever the far being sent,
-// so the two names a notification has are taken when they are there and the
-// object is shown as it is when they are not.
-export function banner(o) {
-    const text = (v) => (typeof v === 'string' && v.trim() ? v.trim() : '');
-    const title = text(o.title) || text(o.from) || 'Nervur';
-    const body = text(o.body) ||
-        text(o.said) ||
-        Object.entries(o)
-            .filter(([k]) => k !== 'title' && k !== 'from')
-            .map(([k, v]) => `${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`)
-            .join(', ');
-    return { title, body };
-}
-// A banner sealed to a device's banner key, as hex, or null when it will
-// not seal or will not fit. The world seals and the process that draws the
-// banner opens it; no doorbell, no bell service and no platform between
-// them holds either half, which is why a ring may carry a line at all.
-export async function sealBanner(line, key) {
-    if (!/^[0-9a-f]{64}$/.test(key))
-        return null;
-    try {
-        const boxed = await arithmetic.box(new TextEncoder().encode(JSON.stringify(line)), arithmetic.unhex(key), globalThis.crypto.getRandomValues(new Uint8Array(32)));
-        const wire = arithmetic.hex(boxed.bytes);
-        return wire.length > SEAL ? null : wire;
-    }
-    catch {
-        return null;
-    }
-}
-// The root and nobody else: where a box hands a phone's ring is the box's own.
-const root = (_occ, asker) => asker.id === OWNER;
-export class Push extends Faculty {
-    // What she keeps, beside every faculty's: the world's doorbell key, a P-256
-    // JWK she mints herself the first time a terrain asks for one, so a Web
-    // Push is signed under a key that lives with the wards and in no file; and
-    // the bell service a phone's ring is handed to when its token names none,
-    // a row the root keeps, since whose service it is belongs to an estate.
-    static cells = { watched: {}, minted: 0, key: null, service: null };
-    static asks = {
-        ring: { description: 'wake a device: its token, the banner sealed to it, or the line itself where the ground encrypts it', input: { type: 'object', properties: { token: { type: 'object' }, sealed: { type: 'string' }, line: { type: 'object', properties: { title: { type: 'string' }, body: { type: 'string' } }, required: ['title', 'body'] } }, required: ['token'] } },
-        kinds: { description: 'which kinds this box can ring', input: { type: 'object' } },
-        keep: { description: 'the bell service a phone is rung through when its token names none; null forgets it', input: { type: 'object', properties: { service: { type: ['string', 'null'] } }, required: ['service'] }, for: root },
-    };
-    // The doorbell key, minted once and kept. A terrain asks for it when it
-    // serves a web route; a box that never does holds none and rings no tabs.
-    async mint() {
-        if (this.cells.key === null)
-            this.cells.key = (await mintVapid()).key;
-        return this.cells.key;
-    }
-    get key() {
-        return this.cells.key;
-    }
-    get service() {
-        return typeof this.cells.service === 'string' ? this.cells.service : undefined;
-    }
-    keep(args) {
-        const service = args.service;
-        if (service !== null && (typeof service !== 'string' || !/^https?:\/\/\S+$/.test(service)))
-            return { error: 'a bell service is a URL over http or https, or null' };
-        this.cells.service = service === null ? null : service.replace(/\/$/, '');
-        return { service: this.cells.service };
-    }
-    // What this box can ring. A terrain overrides it and builds its rings from
-    // its environment and this being's cells; the base rings nothing.
-    get rings() {
-        return {};
-    }
-    kinds() {
-        return { kinds: Object.keys(this.rings) };
-    }
-    async ring(args) {
-        const token = args.token;
-        if (!isToken(token))
-            return { error: 'a token names its kind' };
-        const sealed = args.sealed;
-        if (sealed !== undefined && typeof sealed !== 'string')
-            return { error: 'a seal is text' };
-        if (typeof sealed === 'string' && sealed.length > SEAL)
-            return { error: `a seal is at most ${SEAL} bytes` };
-        const said = args.line;
-        if (said !== undefined && (said === null || typeof said !== 'object' || Array.isArray(said) || typeof said.title !== 'string' || typeof said.body !== 'string'))
-            return { error: 'a line is a title and a body' };
-        const line = said;
-        const r = Object.hasOwn(this.rings, token.kind) ? this.rings[token.kind] : undefined;
-        if (!r)
-            return { error: `this box cannot ring a ${token.kind}` };
-        try {
-            await r.ring(token, sealed, line);
-            return { rang: token.kind };
-        }
-        catch (e) {
-            return { error: e instanceof Error ? e.message : 'the ring threw' };
-        }
-    }
-}

package/dist/dock/timer.js

@@ -1,149 +0,0 @@
-import { Faculty } from './faculty.js';
-const MINUTE = 60_000;
-// A timeout further out than this is not trusted, so the arming is capped and
-// made again when it goes off. It is the base class's own bound and no rule
-// of the faculty: a terrain whose alarm holds a month arms for the month.
-const DAY = 86_400_000;
-export class Timer extends Faculty {
-    static asks = {
-        watch: { description: 'wake me when I say I am next due', input: { type: 'object', properties: { invitation: { type: 'object' }, method: { type: 'string' }, args: { type: 'object' } }, required: ['invitation', 'method'] } },
-        due: { description: 'bring my next round forward to this moment', input: { type: 'object', properties: { at: { type: 'number' } }, required: ['at'] } },
-        now: { description: 'this box’s moment', input: { type: 'object' } },
-    };
-    #timeout;
-    #stopped = false;
-    #armed = null;
-    #round = null;
-    // The moment she is armed for, or null while she is asleep. For the
-    // device's own code and for a suite; it crosses no door.
-    get armed() {
-        return this.#armed;
-    }
-    // A watcher says she is due sooner than the box knew. It only ever brings
-    // the round forward: what fires is decided at the tick, in the watcher's
-    // own cells, so an arming that moved later on somebody's word would be a
-    // schedule somebody else held silenced. The door is the whole gate here:
-    // a standing at a faculty comes from `lend` alone, and this adds no second
-    // one.
-    due(args) {
-        const at = args.at;
-        if (typeof at !== 'number' || !Number.isFinite(at))
-            return { error: 'a due carries the moment: { at }' };
-        const when = moment(at);
-        if (this.#armed === null || when < this.#armed)
-            this.#arm(when);
-        return { armed: this.#armed };
-    }
-    // Whoever was just filed is ticked at once, and what she answers is what
-    // the box arms for. One move covers a box booting, a home moving in and a
-    // watcher born long after the box was up: she is never waiting for a round
-    // nobody scheduled.
-    async welcomed(id) {
-        await this.round(Date.now(), id);
-    }
-    // The arming went off. A moment still well ahead is the day's cap this
-    // class put on its own timeout, so it is armed again rather than fired: a
-    // terrain calls this and never has to know how far out the arming was.
-    async rang() {
-        if (this.#stopped)
-            return [];
-        if (this.#armed !== null && this.#armed - Date.now() > 1_000) {
-            this.arm(this.#armed);
-            return [];
-        }
-        return this.fire(Date.now());
-    }
-    // The moment, read here and handed on. A device's own code may call it at a
-    // moment it names, which is how a suite proves a wake without waiting for
-    // one and how an operator makes a round happen now.
-    fire(now) {
-        return this.round(now);
-    }
-    // One round, and never two: a second while one is in flight is handed the
-    // one already running. What every watcher answered decides the next
-    // arming, and a `due` that landed while the round ran is not lost.
-    round(now, only) {
-        if (this.#round)
-            return this.#round;
-        const mine = this.#run(now, only);
-        this.#round = mine;
-        return mine.finally(() => {
-            if (this.#round === mine)
-                this.#round = null;
-        });
-    }
-    async #run(now, only) {
-        if (only === undefined)
-            this.#arm(null); // the arming is spent, whether it went off or the device called this by hand
-        const woke = await this.woke((w) => ({ ...w.args, now }), only);
-        if (woke === null) {
-            this.stop(); // her ward took her out; there is nobody left to wake
-            return [];
-        }
-        // A moment already gone is no arming. Every watcher works out when she is
-        // next due from the moment she was handed, so a round fired by hand at a
-        // moment that is not this box's answers one that is not this box's
-        // either, and a box that armed for it would run a round for a minute long
-        // past. A round at the box's own moment always names one still ahead.
-        const named = soonest(woke);
-        const said = named !== null && named > Date.now() ? named : null;
-        const held = this.#armed;
-        const at = said === null ? held : held === null ? moment(said) : Math.min(held, moment(said));
-        if (at !== null && at !== this.#armed)
-            this.#arm(at);
-        else if (at === null && this.#armed !== null)
-            this.#arm(null);
-        return woke;
-    }
-    #arm(when) {
-        if (this.#stopped)
-            return;
-        this.#armed = when;
-        this.arm(when);
-    }
-    // The one thing a terrain says about itself: be woken at this moment, or at
-    // no moment at all. A subclass replaces this and nothing else of her.
-    //
-    // Here it is a timeout, capped at a day and armed again when the cap goes
-    // off. The box stays up for its work and never for this, so the handle is
-    // unreferenced.
-    arm(when) {
-        clearTimeout(this.#timeout);
-        this.#timeout = undefined;
-        if (when === null)
-            return;
-        this.#timeout = setTimeout(() => void this.rang(), Math.min(Math.max(when - Date.now(), 0), DAY));
-        this.#timeout.unref?.();
-    }
-    // A being her ward took out reaches nobody, so nothing is left to wake. The
-    // device calls this when it puts the box down.
-    stop() {
-        this.#stopped = true;
-        this.#armed = null;
-        this.arm(null);
-    }
-    now() {
-        return { now: Date.now() };
-    }
-}
-// Half a second past the minute a moment falls in, and never before the
-// moment itself: a watcher floors what she is handed, so a round that fired a
-// hair early would floor to the minute before and fire nothing.
-const moment = (at) => Math.max(at, Math.floor(at / MINUTE) * MINUTE + 500);
-// What one round learned. Every watcher says when she is next due, and the
-// box arms for the earliest of them. A watcher who named no moment has
-// nothing to be woken for, and so has one who answered something that is no
-// tally at all.
-function soonest(woke) {
-    let at = null;
-    for (const w of woke) {
-        if (w.out === null || typeof w.out !== 'object')
-            continue;
-        const next = w.out.next;
-        if (typeof next !== 'number' || !Number.isFinite(next))
-            continue;
-        if (at === null || next < at)
-            at = next;
-    }
-    return at;
-}

package/dock/console.ts

@@ -1,23 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The box, as one being. A device has no surface of its own, so a box that
-// has joined no world has nothing to draw: the Console is that page and only
-// that. She carries the faculties her harbor stood, showing each one's asks
-// as her own, and the ordinary screen draws her exactly as it draws a
-// world's user being, through one avatar holding one standing.
-//
-// She exists because a fresh install otherwise asks for location and
-// notifications in its manifest and shows nothing that ever asks for them,
-// which is a store reviewer's first question and a human's second.
-//
-// She carries for whoever the harbor's root let in, and for nobody else: the
-// root is the box, and it invites the one avatar its own screen runs.
-import { Carrier } from '../beings/carry.ts';
-import type { Asker, OccupantRecord } from 'nervur';
-
-export const CONSOLE = 'console';
-
-export class Console extends Carrier {
-  static override carries(occupant: OccupantRecord | undefined, _asker: Asker): boolean {
-    return occupant !== undefined;
-  }
-}

package/dock/dialers.ts

@@ -1,85 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The box's dialers: `dialers`, one faculty of the dock ward, standing for
-// the sockets this box holds open to other harbors' `quo.` routes. A Mac
-// behind NAT, a phone on the mobile network, a droplet dialing home: each
-// is a dialer, and what it dials is a row in her cells, placed once by the
-// root with `keep` the way a schedule is placed on the clock and an agent
-// on the agents faculty, in no file.
-//
-// A row is one URL, the `quo.` route of the harbor dialed. She holds the
-// socket from her birth on, as every faculty holds what the box holds: one
-// line per row, announcing this harbor's wards on open, binding the far
-// side's pks, reconnecting with backoff when the line drops, and closed
-// when the row is dropped or the box goes down. The dialer itself is the
-// library's, written on the standard socket surface, so this faculty holds
-// on every terrain that has a socket; the daemon hands her the harbor to
-// dial for, as it hands the agents faculty how to run a row.
-import { OWNER } from 'nervur';
-import type { Asker, JsonObject, OccupantRecord } from 'nervur';
-import { dial, type Dialer, type Harbor } from 'nervur/harbor';
-import { Faculty } from './faculty.ts';
-
-// The name the dock ward holds her under.
-export const DIALERS = 'dialers';
-
-export type Row = { url: string };
-
-// The root and nobody else: a line held open is the device's own to place.
-const root = (_occ: OccupantRecord | undefined, asker: Asker) => asker.id === OWNER;
-
-const URL_ = { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] };
-
-export class Dialers extends Faculty {
-  static override cells: JsonObject = { watched: {}, minted: 0, dialers: {} };
-  static override asks = {
-    keep: { description: 'hold a socket to that quo. route, from now and from every boot, until it is dropped', input: URL_, for: root },
-    drop: { description: 'close the socket to that route and forget it', input: URL_, for: root },
-    list: { description: 'every route she dials, and whether the line is open now', input: { type: 'object' }, for: root },
-  };
-
-  harbor: Harbor | undefined;
-  readonly open = new Map<string, Dialer>();
-
-  private get rows(): Record<string, Row> {
-    return this.cells.dialers as unknown as Record<string, Row>;
-  }
-
-  // Every row dialed, once the daemon has handed the harbor to dial for.
-  start(harbor: Harbor): void {
-    this.harbor = harbor;
-    for (const row of Object.values(this.rows)) this.#dial(row.url);
-  }
-
-  #dial(url: string): void {
-    if (!this.harbor || this.open.has(url)) return;
-    this.open.set(url, dial(this.harbor, url));
-  }
-
-  keep(args: JsonObject): JsonObject {
-    const url = args.url;
-    if (typeof url !== 'string' || !/^https?:\/\/\S+$/.test(url)) return { error: 'url is the quo. route of the harbor dialed, over http or https' };
-    const clean = url.replace(/\/$/, '');
-    this.rows[clean] = { url: clean };
-    this.#dial(clean);
-    return { kept: clean };
-  }
-
-  drop(args: JsonObject): JsonObject {
-    const url = typeof args.url === 'string' ? args.url.replace(/\/$/, '') : '';
-    if (!this.rows[url]) return { error: 'no such route' };
-    this.open.get(url)?.close();
-    this.open.delete(url);
-    delete this.rows[url];
-    return { dropped: url };
-  }
-
-  list(): JsonObject {
-    return { dialers: Object.keys(this.rows).map((url) => ({ url, open: this.open.get(url)?.socket !== null && this.open.has(url) })) };
-  }
-
-  // The device puts the box down: every line closes, the rows stay.
-  close(): void {
-    for (const d of this.open.values()) d.close();
-    this.open.clear();
-  }
-}