@nervur-org/dock 0.4.1 → 0.6.0

package/dist/{dock → box}/notifications.js

@@ -23,6 +23,13 @@
 // it would cost her a line of text rather than her world.
 import { arithmetic } from 'nervur/ward';
 import { Faculty } from './faculty.js';
+import { contract } from './contract.js';
+const ASKS = {
+    notify: { description: 'show the human a line', input: { type: 'object', properties: { title: { type: 'string' }, body: { type: 'string' } }, required: ['title'] } },
+    banner: { description: "this device's banner key, the public half, which a world seals a notification to", input: { type: 'object' } },
+};
+// What a being needs from a box that can show the human a line.
+export const NOTIFICATIONS = contract('notifications', ASKS);
 // A key is thirty two bytes of the platform's own randomness, as every seed
 // in this kit is.
 const seed = () => globalThis.crypto.getRandomValues(new Uint8Array(32));
@@ -30,10 +37,13 @@ export class Notifications extends Faculty {
     // The banner key, as hex: the seed it was made from, kept so the pair can
     // be made again, and the public half a device hands out.
     static cells = { watched: {}, minted: 0, banner: null };
-    static asks = {
-        notify: { description: 'show the human a line', input: { type: 'object', properties: { title: { type: 'string' }, body: { type: 'string' } }, required: ['title'] } },
-        banner: { description: "this device's banner key, the public half, which a world seals a notification to", input: { type: 'object' } },
-    };
+    static asks = ASKS;
+    static fulfils = [NOTIFICATIONS];
+    // This body shows nothing, so it stands nowhere: a terrain with a
+    // notification center subclasses her and says so.
+    static stands() {
+        return false;
+    }
     notify(_args) {
         return Promise.resolve({ error: 'this box shows no notifications' });
     }

package/dist/{dock → box}/push.d.ts

@@ -1,23 +1,8 @@
 import type { Asker, JsonObject, OccupantRecord } from 'nervur';
+import { type Ring } from './ring.ts';
 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 const PUSH: import("nervur").Blueprint;
 export declare class Push extends Faculty {
     static cells: JsonObject;
     static asks: {
@@ -54,6 +39,13 @@ export declare class Push extends Faculty {
                 type: string;
             };
         };
+        bell: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: typeof root;
+        };
         keep: {
             description: string;
             input: {
@@ -68,7 +60,9 @@ export declare class Push extends Faculty {
             for: typeof root;
         };
     };
-    mint(): Promise<JsonWebKey>;
+    static fulfils: import("nervur").Blueprint[];
+    static stands(): boolean;
+    bell(): Promise<JsonObject>;
     get key(): JsonWebKey | null;
     get service(): string | undefined;
     keep(args: JsonObject): JsonObject;

package/dist/box/push.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+// Waking a device that is not reachable, the one way its platform allows: a
+// ring carrying the device's token and a banner sealed to its key. A token
+// names its kind and a kind is one ring. The rings are live objects and not
+// values, so a terrain that can ring brings a class that builds its own; this
+// body rings nothing and stands nowhere.
+//
+// What she keeps: the world's doorbell key, a P-256 JWK she mints herself the
+// first time a terrain asks, and the bell service a phone's ring is handed
+// to when its token names none, a row the root keeps.
+import { OWNER } from 'nervur';
+import { SEAL, isToken } from './ring.js';
+import { mintVapid, publicOf } from './webpush.js';
+import { contract } from './contract.js';
+import { Faculty } from './faculty.js';
+const root = (_occ, asker) => asker.id === OWNER;
+// What a holder is owed: a ring, and which kinds this box can ring.
+const OWED = {
+    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' } },
+};
+// What a being needs from a box that can wake a device.
+export const PUSH = contract('push', OWED);
+export class Push extends Faculty {
+    static cells = { watched: {}, minted: 0, key: null, service: null };
+    static asks = { ...OWED, bell: { description: 'the public half of this box’s doorbell key, minted at the first ask and kept in her cells', input: { type: 'object' }, for: root }, 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 } };
+    static fulfils = [PUSH];
+    static stands() {
+        return false;
+    }
+    // The doorbell key, minted at the root's first ask and kept; nobody mints
+    // it from outside. What crosses is the public half, which every page's
+    // config carries.
+    async bell() {
+        if (this.cells.key === null)
+            this.cells.key = (await mintVapid()).key;
+        return { bell: publicOf(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. 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/box/ring.d.ts

@@ -0,0 +1,18 @@
+import type { JsonObject } from 'nervur';
+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>;

package/dist/box/ring.js

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: Apache-2.0
+// What waking a device is made of, beside the push faculty: the token a
+// device hands a world, the ring a platform rings through, the banner a
+// device shows, and the seal only the device can open. 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.
+import { arithmetic } from 'nervur/ward';
+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;
+    }
+}

package/dist/{dock → box}/service.d.ts

@@ -1,4 +1,4 @@
-import { type Ring } from './push.ts';
+import { type Ring } from './ring.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 → box}/service.js

@@ -26,7 +26,7 @@
 // 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';
+import { bellOf } from './ring.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

package/dist/{dock → box}/timer.d.ts

@@ -1,5 +1,6 @@
 import type { JsonObject } from 'nervur';
 import { Faculty, type Woke } from './faculty.ts';
+export declare const TIMER: import("nervur").Blueprint;
 export declare class Timer extends Faculty {
     #private;
     static asks: {
@@ -40,6 +41,7 @@ export declare class Timer extends Faculty {
             };
         };
     };
+    static fulfils: import("nervur").Blueprint[];
     get armed(): number | null;
     due(args: JsonObject): JsonObject;
     protected welcomed(id: string): Promise<void>;

package/dist/box/timer.js

@@ -0,0 +1,127 @@
+import { contract } from './contract.js';
+import { Faculty, WATCH } from './faculty.js';
+const ASKS = {
+    watch: WATCH,
+    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' } },
+};
+// What a being needs from a box that can wake her at a moment.
+export const TIMER = contract('timer', ASKS);
+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.
+const DAY = 86_400_000;
+export class Timer extends Faculty {
+    static asks = ASKS;
+    static fulfils = [TIMER];
+    #timeout;
+    #stopped = false;
+    #armed = null;
+    #round = null;
+    // The moment she is armed for, or null while she is asleep.
+    get armed() {
+        return this.#armed;
+    }
+    // A watcher says she is due sooner than the box knew. It only ever brings
+    // the round forward.
+    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, so she is never waiting for a round nobody scheduled.
+    async welcomed(id) {
+        await this.round(this.box.now(), id);
+    }
+    // The arming went off. A moment still well ahead is the day's cap, so it is
+    // armed again rather than fired.
+    async rang() {
+        if (this.#stopped)
+            return [];
+        if (this.#armed !== null && this.#armed - this.box.now() > 1_000) {
+            this.arm(this.#armed);
+            return [];
+        }
+        return this.fire(this.box.now());
+    }
+    // The device's own call at a moment it names: 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 at once.
+    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);
+        const woke = await this.woke((w) => ({ ...w.args, now }), only);
+        if (woke === null) {
+            this.stop();
+            return [];
+        }
+        // A moment already gone is no arming.
+        const named = soonest(woke);
+        const said = named !== null && named > this.box.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. Here a timeout, capped at a day, unreferenced so the box
+    // stays up for its work and never for this.
+    arm(when) {
+        clearTimeout(this.#timeout);
+        this.#timeout = undefined;
+        if (when === null)
+            return;
+        this.#timeout = setTimeout(() => void this.rang(), Math.min(Math.max(when - this.box.now(), 0), DAY));
+        this.#timeout.unref?.();
+    }
+    // The device puts the box down.
+    stop() {
+        this.#stopped = true;
+        this.#armed = null;
+        this.arm(null);
+    }
+    now() {
+        return { now: this.box.now() };
+    }
+}
+const moment = (at) => Math.max(at, Math.floor(at / MINUTE) * MINUTE + 500);
+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/box/tree.d.ts

@@ -0,0 +1,5 @@
+import type { BeingClass } from 'nervur';
+export type Tree = {
+    readonly [name: string]: unknown;
+};
+export declare function keyed(tree: Tree, at?: string): Record<string, BeingClass>;

package/dist/box/tree.js

@@ -0,0 +1,14 @@
+// Every class in a tree, keyed by where it lives: the folders down to it and
+// its export name, `box/Dock`. The key is the class's identity in a ward,
+// as a being's key is hers, and it moves only when the class moves.
+export function keyed(tree, at = '') {
+    const out = {};
+    for (const [name, v] of Object.entries(tree)) {
+        const key = at ? `${at}/${name}` : name;
+        if (typeof v === 'function' && 'prototype' in v)
+            out[key] = v;
+        else if (v !== null && typeof v === 'object' && !Array.isArray(v))
+            Object.assign(out, keyed(v, key));
+    }
+    return out;
+}

package/dist/{dock → box}/webpush.d.ts

@@ -1,4 +1,4 @@
-import type { Line, Ring } from './push.ts';
+import type { Line, Ring } from './ring.ts';
 export type Vapid = {
     key: JsonWebKey;
     subject: string;

package/dist/cli/client.d.ts

@@ -1,5 +1,6 @@
 export type Answer = {
     result: unknown;
+    ward?: string;
 } | {
     error: string;
 };

package/dist/cli/daemon.d.ts

@@ -2,9 +2,8 @@ import { DiskHarbor, type Hosted } from '../harbor/disk.ts';
 import type { Harbor } from 'nervur/harbor';
 import type { Avatar } from '../beings/index.ts';
 export { avatarOf, letIn, find } from '../beings/join.ts';
-import { type Ring } from '../dock/index.ts';
-import { Grants } from '../dock/grants.ts';
-import { Agents } from '../dock/agents.ts';
+import { type Ring } from '../box/index.ts';
+import { Agents, Grants } from '../box/index.ts';
 import type { OAuth } from '../mcp/oauth.ts';
 import { Exchange } from '../mcp/allow.ts';
 import { McpHttp } from '../mcp/http.ts';
@@ -43,8 +42,3 @@ export declare function admit(harbor: Harbor, hosted: Hosted, identity: string,
     error?: string;
 }>;
 export declare function serve(dir: string, options?: Options): Promise<Serving>;
-export declare const DOMAIN: RegExp;
-export declare function routesFor(domain: string): Required<Routes>;
-export declare function writeRoutes(dir: string, domain: string): Promise<Required<Routes>>;
-export declare function readRoutes(dir: string): Promise<Routes | null>;
-export declare function readApps(dir: string): Promise<Apps | null>;