@nervur-org/dock 0.3.0

package/dist/dock/push.d.ts

@@ -0,0 +1,79 @@
+import type { Asker, JsonObject, OccupantRecord } from '@nervur-org/nervur';
+import { Faculty } from './faculty.ts';
+export type Token = {
+    kind: string;
+    bell?: string;
+    app?: string;
+} & JsonObject;
+export declare const isToken: (v: unknown) => v is Token;
+export declare function bellOf(token: Token): string | undefined;
+export type Line = {
+    title: string;
+    body: string;
+};
+export type Ring = {
+    ring(token: Token, sealed?: string, line?: Line): Promise<void>;
+};
+export declare const SEAL = 4096;
+export declare function banner(o: JsonObject): Line;
+export declare function sealBanner(line: JsonObject, key: string): Promise<string | null>;
+declare const root: (_occ: OccupantRecord | undefined, asker: Asker) => boolean;
+export declare class Push extends Faculty {
+    static cells: JsonObject;
+    static asks: {
+        ring: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    token: {
+                        type: string;
+                    };
+                    sealed: {
+                        type: string;
+                    };
+                    line: {
+                        type: string;
+                        properties: {
+                            title: {
+                                type: string;
+                            };
+                            body: {
+                                type: string;
+                            };
+                        };
+                        required: string[];
+                    };
+                };
+                required: string[];
+            };
+        };
+        kinds: {
+            description: string;
+            input: {
+                type: string;
+            };
+        };
+        keep: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    service: {
+                        type: string[];
+                    };
+                };
+                required: string[];
+            };
+            for: typeof root;
+        };
+    };
+    mint(): Promise<JsonWebKey>;
+    get key(): JsonWebKey | null;
+    get service(): string | undefined;
+    keep(args: JsonObject): JsonObject;
+    protected get rings(): Readonly<Record<string, Ring>>;
+    kinds(): JsonObject;
+    ring(args: JsonObject): Promise<JsonObject>;
+}
+export {};

package/dist/dock/push.js

@@ -0,0 +1,132 @@
+// 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-org/nervur';
+import { arithmetic } from '@nervur-org/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) || 'quo';
+    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/service.d.ts

@@ -0,0 +1,4 @@
+import { type Ring } from './push.ts';
+export declare function routed(fallback?: string): Ring;
+export declare function handedTo(at: string): Ring;
+export declare function ringing(rings: Record<string, Ring>, apps?: readonly string[]): (request: Request) => Promise<Response>;

package/dist/dock/service.js

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: Apache-2.0
+// The bell service, from both ends: the ground a world rings through when
+// it does not hold the platform's key, and the door that holds the key and
+// rings.
+//
+// Why there is one at all. Apple and Google accept a push only when it is
+// signed with the key of the team that published the app, so a world's
+// droplet cannot ring the Quo app however much its human wants it to: the
+// key belongs to whoever publishes the app and to nobody else. So a world's
+// world hands the ring on, a token and a sealed banner, to a service the
+// publisher runs. It is the one server the app has. An estate that ships
+// its own app under its own name holds its own keys and runs its own, or
+// puts these two rings straight into its push faculty and runs none.
+//
+// What it sees is a token, a ring, and ciphertext. Not a world, not an
+// occupant, not a pk, and not a word of what was pushed: the banner is
+// sealed to the device's banner key by the world that rang, and this
+// service holds no key that opens it and never will. It keeps nothing
+// either: no log of who rang, no list of tokens, no state at all, which is
+// the only honest way to run a server every world's traffic passes through.
+//
+// Who may ring it is the token itself, and that is deliberate. A device
+// token exists only because a device installed this app and handed it to a
+// world it joined; it is per app and per device; a ring wakes a phone and
+// says nothing to it; and the platforms throttle a background push on their
+// own. An account here would be a registry of worlds, which is the one
+// thing the app is built not to have. The day this is abused it wants a
+// rate limit at the edge, which is the terrain's and not a word of Quo.
+import { bellOf } from './push.js';
+// The ring a world holds for a store's kind: the token names its bell and
+// the ring goes there, so a phone running an app this world never shipped
+// is rung through that app's own service; a token naming none goes to the
+// service the world was told of, and a world told of none rings nothing.
+export function routed(fallback) {
+    return {
+        async ring(token, sealed) {
+            const at = bellOf(token) ?? fallback;
+            if (!at)
+                throw new Error(`no bell service rings a ${token.kind} from this box`);
+            return handedTo(at).ring(token, sealed);
+        },
+    };
+}
+// The ring a world holds: hand the token to the service and take its word
+// for it. A ring either left or threw, as every ring does.
+export function handedTo(at) {
+    return {
+        async ring(token, sealed) {
+            const res = await fetch(`${at.replace(/\/$/, '')}/ring`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(sealed === undefined ? { token } : { token, sealed }),
+            });
+            const said = (await res.text()).slice(0, 200);
+            if (!res.ok)
+                throw new Error(`the bell service answered ${res.status} ${said}`);
+        },
+    };
+}
+// The other end, as a plain request in and a response out, so that the
+// terrain it runs on is the terrain's business and this is the whole of the
+// service. `rings` is one per kind, exactly as the push faculty's map is: a
+// service with no key for a kind answers that it has none, which is what a
+// publisher who rings no Android phones says to one. `apps` is which apps
+// this service holds keys for, and a token naming another is refused,
+// since a key signs for one app and a ring for another would be a lie the
+// platform catches later and nobody reads.
+export function ringing(rings, apps) {
+    const answer = (status, body) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' } });
+    return async (request) => {
+        if (new URL(request.url).pathname !== '/ring')
+            return answer(404, { error: 'the bell service has one door, /ring' });
+        if (request.method !== 'POST')
+            return answer(405, { error: 'a ring is a POST' });
+        let token;
+        let sealed;
+        try {
+            const body = (await request.json());
+            token = body.token;
+            sealed = body.sealed;
+        }
+        catch {
+            return answer(400, { error: 'a ring is one JSON object naming a token' });
+        }
+        if (sealed !== undefined && typeof sealed !== 'string')
+            return answer(400, { error: 'a seal is text' });
+        const kind = token?.kind;
+        if (typeof kind !== 'string')
+            return answer(400, { error: 'a token names its kind' });
+        const g = rings[kind];
+        if (!g)
+            return answer(400, { error: `this service holds no key to ring a ${kind}` });
+        const app = token.app;
+        if (apps && (typeof app !== 'string' || !apps.includes(app)))
+            return answer(400, { error: `this service holds no key for ${typeof app === 'string' ? app : 'an app the token does not name'}` });
+        try {
+            await g.ring(token, sealed);
+            return answer(200, { rang: kind });
+        }
+        catch (e) {
+            // The platform's own refusal, passed back as it came. A world reads
+            // it in the error object its Bell answers with, which is where a
+            // human eventually reads it too.
+            return answer(502, { error: e instanceof Error ? e.message : String(e) });
+        }
+    };
+}

package/dist/dock/timer.d.ts

@@ -0,0 +1,52 @@
+import type { JsonObject } from '@nervur-org/nervur';
+import { Faculty, type Woke } from './faculty.ts';
+export declare class Timer extends Faculty {
+    #private;
+    static asks: {
+        watch: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    invitation: {
+                        type: string;
+                    };
+                    method: {
+                        type: string;
+                    };
+                    args: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+        due: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    at: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+        now: {
+            description: string;
+            input: {
+                type: string;
+            };
+        };
+    };
+    get armed(): number | null;
+    due(args: JsonObject): JsonObject;
+    protected welcomed(id: string): Promise<void>;
+    rang(): Promise<Woke[]>;
+    fire(now: number): Promise<Woke[]>;
+    protected round(now: number, only?: string): Promise<Woke[]>;
+    protected arm(when: number | null): void;
+    stop(): void;
+    now(): JsonObject;
+}

package/dist/dock/timer.js

@@ -0,0 +1,149 @@
+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/dist/dock/webpush.d.ts

@@ -0,0 +1,12 @@
+import type { Line, Ring } from './push.ts';
+export type Vapid = {
+    key: JsonWebKey;
+    subject: string;
+};
+export declare function publicOf(key: JsonWebKey): string;
+export declare function mintVapid(): Promise<{
+    key: JsonWebKey;
+    publicKey: string;
+}>;
+export declare function encrypt(line: Line, ua: Uint8Array, auth: Uint8Array): Promise<Uint8Array>;
+export declare function webPush(v: Vapid): Ring;