@nervur-org/dock 0.3.0

package/dist/beings/index.d.ts

@@ -0,0 +1,14 @@
+export { User, DESK, HOME, BELL } from './user.ts';
+export { Desk } from './desk.ts';
+export { WAY, kindOf, verified, VERIFY, SEND, type Proof, type Verified } from './way.ts';
+export { Avatar, USER, PUSHER } from './avatar.ts';
+export { Carrier } from './carry.ts';
+export { Presence } from './presence.ts';
+export { Courier, MOVER, isMoving, type Moving } from './courier.ts';
+export { Porter } from './porter.ts';
+export { Doorbell } from './doorbell.ts';
+export { Envoy, owner, occupant, type Delivery, type Wake, type Heard } from './envoy.ts';
+export { DOCK, CONSOLE, LOCAL, LOCATION, NOTIFICATIONS, PUSH, TIMER, FACULTIES, FACULTY_CLASSES, Console, Faculty, Local, Location, Notifications, Push, Timer, isToken, join, settled, stand, standOn, lending, facultyOf, type Ring, type Token, type Where, type Watched, type Woke, type Rooted } from '../dock/index.ts';
+export { webPush, mintVapid, publicOf, apnsPush, pkcs8, HOSTS, fcmPush, isAccount, DOORS, handedTo, ringing, routed, type Vapid, type Apns, type Account, type Doors } from '../dock/index.ts';
+export { Clock, CLOCK, setupClock, placeClock, readSchedule, parseCron, nextFire, civil, fromCivil, type Schedule, type Fire, type Cron, type Civil } from './clock.ts';
+export { sanitise, hint, hintFor, groups, type Look, type Hint } from './look.ts';

package/dist/beings/index.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: Apache-2.0
+// The beings every side shares. See quo-dock.md, the trunk.
+export { User, DESK, HOME, BELL } from './user.js';
+export { Desk } from './desk.js';
+export { WAY, kindOf, verified, VERIFY, SEND } from './way.js';
+export { Avatar, USER, PUSHER } from './avatar.js';
+export { Carrier } from './carry.js';
+export { Presence } from './presence.js';
+export { Courier, MOVER, isMoving } from './courier.js';
+export { Porter } from './porter.js';
+export { Doorbell } from './doorbell.js';
+export { Envoy, owner, occupant } from './envoy.js';
+export { DOCK, CONSOLE, LOCAL, LOCATION, NOTIFICATIONS, PUSH, TIMER, FACULTIES, FACULTY_CLASSES, Console, Faculty, Local, Location, Notifications, Push, Timer, isToken, join, settled, stand, standOn, lending, facultyOf } from '../dock/index.js';
+export { webPush, mintVapid, publicOf, apnsPush, pkcs8, HOSTS, fcmPush, isAccount, DOORS, handedTo, ringing, routed } from '../dock/index.js';
+export { Clock, CLOCK, setupClock, placeClock, readSchedule, parseCron, nextFire, civil, fromCivil } from './clock.js';
+export { sanitise, hint, hintFor, groups } from './look.js';

package/dist/beings/join.d.ts

@@ -0,0 +1,15 @@
+import type { Hosted } from '@nervur-org/nervur/harbor';
+import type { Invitation } from '@nervur-org/nervur';
+import type { Avatar } from './avatar.ts';
+export declare function avatarOf(hosted: Hosted, identity: string): Promise<{
+    avatar?: Avatar;
+    error?: string;
+}>;
+export declare function letIn(hosted: Hosted, identity: string, invitation: Invitation): Promise<{
+    avatar?: Avatar;
+    error?: string;
+}>;
+export declare function find(hosted: Hosted, identity: string): Promise<{
+    avatar?: Avatar;
+    error?: string;
+}>;

package/dist/beings/join.js

@@ -0,0 +1,42 @@
+// Her avatar in a ward, found or booted under the identity's key. An
+// identity is a word, and never a being of the ward.
+export async function avatarOf(hosted, identity) {
+    if (!/^[\w.-]+$/.test(identity) || identity === hosted.record.user || identity === 'desk')
+        return { error: 'an identity is a word, and not a being of the ward' };
+    const key = `avatar:${identity}`;
+    let avatar = hosted.being(key);
+    if (!avatar) {
+        const out = (await hosted.ask('boot', { key, class: 'Avatar' }));
+        if (out.error)
+            return { error: out.error };
+        avatar = hosted.being(key);
+    }
+    return { avatar };
+}
+// Join a client identity to a ward with an invitation the root minted for
+// it: find or boot her avatar, and she knocks. The one path for an identity
+// from elsewhere, the exchange page. Nothing is typed to get in but the
+// invitation, and the knock spends it.
+export async function letIn(hosted, identity, invitation) {
+    const found = await avatarOf(hosted, identity);
+    if (!found.avatar)
+        return found;
+    const joined = await found.avatar.join(invitation);
+    await hosted.save();
+    if ('error' in joined && !('asks' in joined))
+        return { error: joined.error };
+    return { avatar: found.avatar };
+}
+// Her avatar as she stands, for a session opening under a grant: she is in
+// or she is not, and nothing is minted here. An identity the user being
+// removed hears `removed` on her describe, which the endpoint speaks as 401.
+export async function find(hosted, identity) {
+    const avatar = hosted.being(`avatar:${identity}`);
+    if (!avatar)
+        return { error: 'not joined' };
+    const bp = await avatar.tools();
+    await hosted.save();
+    if ('error' in bp && !('asks' in bp))
+        return { error: bp.error };
+    return { avatar };
+}

package/dist/beings/link.d.ts

@@ -0,0 +1,14 @@
+import type { Invitation } from '@nervur-org/nervur';
+export declare const KEY = "quo";
+export declare const PROOF = "proof";
+export declare function format(inv: Invitation): string;
+export declare function parse(hash: string): Invitation | null;
+export declare function parseProof(hash: string): {
+    kind: string;
+    token: string;
+} | null;
+export declare function strip(hash: string): string;
+export declare function link(page: string, inv: Invitation): string;
+export declare function proofLink(page: string, kind: string, token: string): string;
+export declare function invitationOf(text: string): Invitation | null;
+export declare function reachOf(text: string): string | null;

package/dist/beings/link.js

@@ -0,0 +1,91 @@
+export const KEY = 'quo';
+// The other reserved key: a proof, for a way in the world sent out itself.
+// A proof is not a capability into a ward, it is a word one door will trade
+// once for an invitation, and it rides in the fragment for the same reason:
+// a query string is in every log and every referer, and one read of it is
+// one way in taken. `<kind>.<token>`, the kind the desk knows it by and the
+// token that door minted.
+export const PROOF = 'proof';
+const HEX = (n) => `[0-9a-f]{${n}}`;
+const FULL = new RegExp(`^(${HEX(128)})\\.(${HEX(64)})\\.(${HEX(64)})$`);
+const PUBLIC = new RegExp(`^${HEX(128)}$`);
+export function format(inv) {
+    return inv.heir && inv.secret ? `${inv.ward}.${inv.heir}.${inv.secret}` : inv.ward;
+}
+// The invitation in a fragment, or null. Anything else in the fragment is
+// the page's own and is left alone.
+export function parse(hash) {
+    const m = /(?:^#|&)quo=([^&]+)/.exec(hash.startsWith('#') ? hash : `#${hash}`);
+    if (!m)
+        return null;
+    const v = decodeURIComponent(m[1]);
+    const full = FULL.exec(v);
+    if (full)
+        return { ward: full[1], heir: full[2], secret: full[3] };
+    return PUBLIC.test(v) ? { ward: v } : null;
+}
+// The proof in a fragment, or null. The kind is a word and the token is
+// whatever the door that minted it wrote, opaque here and never read.
+export function parseProof(hash) {
+    const m = new RegExp(`(?:^#|&)${PROOF}=([^&]+)`).exec(hash.startsWith('#') ? hash : `#${hash}`);
+    if (!m)
+        return null;
+    const v = decodeURIComponent(m[1]);
+    const at = v.indexOf('.');
+    if (at < 1 || at === v.length - 1)
+        return null;
+    const kind = v.slice(0, at);
+    return /^[\w-]{1,40}$/.test(kind) ? { kind, token: v.slice(at + 1) } : null;
+}
+// The fragment without what the dock reserves, so the page keeps whatever
+// else it put there and neither capability is left in the address bar.
+export function strip(hash) {
+    const rest = (hash.startsWith('#') ? hash.slice(1) : hash)
+        .split('&')
+        .filter((p) => !p.startsWith(`${KEY}=`) && !p.startsWith(`${PROOF}=`))
+        .join('&');
+    return rest ? `#${rest}` : '';
+}
+export function link(page, inv) {
+    return `${page}#${KEY}=${format(inv)}`;
+}
+// A world's own way in, as it goes out in a mail or a message: the page of
+// the world it is for, with the proof in the fragment.
+export function proofLink(page, kind, token) {
+    return `${page}#${PROOF}=${encodeURIComponent(`${kind}.${token}`)}`;
+}
+// The invitation as a human hands it over: the compact form, the whole link
+// it came in, or the JSON value `quo invite` printed. Wherever a person
+// types or pastes an invitation, this is what reads it, so the three forms
+// are one form everywhere.
+export function invitationOf(text) {
+    const t = text.trim();
+    const hash = t.indexOf('#');
+    const linked = parse(hash === -1 ? `#${KEY}=${t}` : t.slice(hash));
+    if (linked?.heir)
+        return linked;
+    try {
+        const v = JSON.parse(t);
+        if (v && typeof v === 'object' && typeof v.ward === 'string' && typeof v.heir === 'string' && typeof v.secret === 'string')
+            return { ward: v.ward, heir: v.heir, secret: v.secret };
+    }
+    catch {
+        /* not JSON either */
+    }
+    return null;
+}
+// The reach note in front of an invitation: the URL a link was written on,
+// which for a link between two devices is the rendezvous to dial to reach
+// the one that wrote it. A hint is not a capability, so it travels beside
+// the invitation in the open. Nothing that is not a URL is one.
+export function reachOf(text) {
+    const t = text.trim();
+    const hash = t.indexOf('#');
+    const before = hash === -1 ? '' : t.slice(0, hash);
+    try {
+        return /^https?:$/.test(new URL(before).protocol) ? before : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/beings/look.d.ts

@@ -0,0 +1,30 @@
+import type { Blueprint, Json } from '@nervur-org/nervur';
+export type Hint = {
+    title?: string;
+    readOnly?: boolean;
+    destructive?: boolean;
+    idempotent?: boolean;
+    icon?: string;
+};
+export type Look = {
+    name?: string;
+    logo?: string;
+    accent?: string;
+    background?: string;
+    foreground?: string;
+    font?: string;
+    radius?: number;
+    order?: string[];
+    asks?: Record<string, Hint>;
+    stands?: string[];
+};
+export declare function sanitise(v: Json | undefined): Look;
+export declare const hint: (l: Look | undefined, name: string) => Hint;
+export type Group = {
+    asks?: string[];
+    look?: Json;
+    page?: string;
+};
+export declare function groups(bp: Blueprint | null): Record<string, Group>;
+export declare function presentation(bp: Blueprint | null): Set<string>;
+export declare function hintFor(bp: Blueprint | null, mine: Look, name: string): Hint;

package/dist/beings/look.js

@@ -0,0 +1,104 @@
+const COLOUR = /^#[0-9a-fA-F]{3,8}$/;
+const FONT = /^[\w\s,'"-]{1,80}$/;
+const LOGO = /^data:image\/(svg\+xml|png|jpeg|webp);base64,[A-Za-z0-9+/=]{1,40000}$/;
+const NAME = /^[^<>&]{1,60}$/;
+const ICON = /^[^<>&"']{1,8}$/;
+const STANDS = 8; // origins a being may stand in for
+const ORIGIN = 200; // characters one of them may be
+const str = (v, re) => (typeof v === 'string' && re.test(v) ? v : undefined);
+// The look as a side may use it: every token held to its shape, everything
+// else gone. A value that is not an object is no look at all.
+export function sanitise(v) {
+    if (v === null || v === undefined || typeof v !== 'object' || Array.isArray(v))
+        return {};
+    const l = {};
+    const name = str(v.name, NAME);
+    if (name !== undefined)
+        l.name = name;
+    const logo = str(v.logo, LOGO);
+    if (logo !== undefined)
+        l.logo = logo;
+    for (const k of ['accent', 'background', 'foreground']) {
+        const c = str(v[k], COLOUR);
+        if (c !== undefined)
+            l[k] = c;
+    }
+    const font = str(v.font, FONT);
+    if (font !== undefined)
+        l.font = font;
+    if (typeof v.radius === 'number' && Number.isFinite(v.radius) && v.radius >= 0 && v.radius <= 40)
+        l.radius = Math.round(v.radius);
+    if (Array.isArray(v.order))
+        l.order = v.order.filter((x) => typeof x === 'string');
+    if (Array.isArray(v.stands)) {
+        // An origin and never a page: whatever she writes is parsed and reduced
+        // to its scheme, host and port, so a path, a query or a fragment she
+        // put there cannot narrow what a side vouches for into something a
+        // reader would misjudge. Bounded, because a list nobody could read is a
+        // list nobody can check.
+        const stands = [];
+        for (const x of v.stands.slice(0, STANDS)) {
+            if (typeof x !== 'string' || x.length > ORIGIN)
+                continue;
+            try {
+                const u = new URL(x);
+                if ((u.protocol === 'https:' || u.protocol === 'http:') && !stands.includes(u.origin))
+                    stands.push(u.origin);
+            }
+            catch {
+                /* not an origin */
+            }
+        }
+        if (stands.length)
+            l.stands = stands;
+    }
+    if (v.asks !== null && typeof v.asks === 'object' && !Array.isArray(v.asks)) {
+        const asks = {};
+        for (const [ask, h] of Object.entries(v.asks)) {
+            if (h === null || typeof h !== 'object' || Array.isArray(h))
+                continue;
+            const hint = {};
+            const title = str(h.title, NAME);
+            if (title !== undefined)
+                hint.title = title;
+            const icon = str(h.icon, ICON);
+            if (icon !== undefined)
+                hint.icon = icon;
+            for (const k of ['readOnly', 'destructive', 'idempotent'])
+                if (typeof h[k] === 'boolean')
+                    hint[k] = h[k];
+            if (Object.keys(hint).length)
+                asks[ask] = hint;
+        }
+        if (Object.keys(asks).length)
+            l.asks = asks;
+    }
+    return l;
+}
+// The one hint a side reads first: whether this ask is in the look at all.
+export const hint = (l, name) => l?.asks?.[name] ?? {};
+export function groups(bp) {
+    const n = bp?.notes;
+    const g = n !== null && n !== undefined && typeof n === 'object' && !Array.isArray(n) ? n.standings : undefined;
+    return g !== null && g !== undefined && typeof g === 'object' && !Array.isArray(g) ? g : {};
+}
+// The asks that are presentation and never a form nor a tool: her look, her
+// page, and the page of every standing she carries, named in her notes.
+export function presentation(bp) {
+    const p = new Set(['look', 'page']);
+    for (const g of Object.values(groups(bp)))
+        if (typeof g.page === 'string')
+            p.add(g.page);
+    return p;
+}
+// The hint for one ask, hers or a standing's: a carried ask is looked up
+// under its bare name in that standing's look.
+export function hintFor(bp, mine, name) {
+    for (const [id, g] of Object.entries(groups(bp))) {
+        if (!g.asks?.includes(name))
+            continue;
+        const prefix = `${id}-`;
+        return hint(sanitise(g.look), name.startsWith(prefix) ? name.slice(prefix.length) : name);
+    }
+    return hint(mine, name);
+}

package/dist/beings/porter.d.ts

@@ -0,0 +1,14 @@
+import { Being } from '@nervur-org/nervur';
+import type { JsonObject } from '@nervur-org/nervur';
+export declare class Porter extends Being {
+    static cells: JsonObject;
+    static asks: {
+        hello: {
+            description: string;
+            input: {
+                type: string;
+            };
+        };
+    };
+    hello(_args: JsonObject): Promise<JsonObject>;
+}

package/dist/beings/porter.js

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+// The bell's public being. She is the one door a phone nobody knows can
+// reach: her asker is `{}` and she can tell, which is what the spec puts a
+// public being there for. A stranger says hello, she boots that device a
+// doorbell of its own and hands back its one way in, and from then on the
+// phone is a named occupant with a heir and a count, which is where
+// anything that must happen once belongs.
+//
+// She needs no owner standing and no root. A being boots a being of her
+// ward and holds a standing to it, which is the whole of what she does.
+//
+// Her answer is safe to repeat, as a public being's must be: saying hello
+// twice is two doorbells and no harm. A stranger who keeps knocking is the
+// harbor's, never hers and never the door's, and the count below is only so
+// that a loop in this session stops somewhere a human can see.
+import { Being, isSilence, isWord, wordOf } from '@nervur-org/nervur';
+const ROOM = 64;
+export class Porter extends Being {
+    static cells = { minted: 0 };
+    static asks = {
+        hello: { description: 'a device asks for a doorbell of its own', input: { type: 'object' } },
+    };
+    async hello(_args) {
+        const minted = typeof this.cells.minted === 'number' ? this.cells.minted : 0;
+        if (minted >= ROOM)
+            return { error: 'this bell holds no more doorbells' };
+        const key = `doorbell:${minted + 1}`;
+        const held = await this.boot('Doorbell', key, key);
+        if (held === null)
+            return { error: 'this bell could not make a doorbell' };
+        this.cells.minted = minted + 1;
+        // The doorbell hands out its one way in, and only while it has no
+        // device. So the porter cannot keep a key to a phone she introduced.
+        const out = await this.standings[held]?.ask('claim', {});
+        if (out === undefined || isSilence(out))
+            return { error: 'the doorbell said nothing' };
+        if (isWord(out))
+            return { error: wordOf(out) };
+        return { doorbell: key, ...out };
+    }
+}

package/dist/beings/presence.d.ts

@@ -0,0 +1,8 @@
+import type { Asker, OccupantRecord, Stance } from '@nervur-org/nervur';
+import { Avatar } from './avatar.ts';
+export declare class Presence extends Avatar {
+    static carries(occupant: OccupantRecord | undefined, _asker: Asker): boolean;
+    static skips(id: string): boolean;
+    readonly lent: Promise<Record<string, string | null>>;
+    constructor(stance: Stance);
+}

package/dist/beings/presence.js

@@ -0,0 +1,21 @@
+import { Avatar, PUSHER, USER } from './avatar.js';
+import { FACULTIES, join } from '../dock/index.js';
+export class Presence extends Avatar {
+    // Her world's user being sees the box, and nobody else: the way back she
+    // handed over at the join is the one occupant who may ask through her.
+    static carries(occupant, _asker) {
+        return occupant?.id === PUSHER;
+    }
+    // Her standing at the user being is hers to speak through and never to
+    // carry: the user being carries her, so carrying it back would be a
+    // loop, and it is the one standing that is not a faculty.
+    static skips(id) {
+        return id === USER;
+    }
+    // Which names the box lent her, by name, settled after birth.
+    lent;
+    constructor(stance) {
+        super(stance);
+        this.lent = Promise.all(Object.keys(FACULTIES).map(async (name) => [name, await join(this, name)])).then((all) => Object.fromEntries(all));
+    }
+}

package/dist/beings/setup.d.ts

@@ -0,0 +1,3 @@
+import type { Hosted } from '@nervur-org/nervur/harbor';
+export declare function setupHome(hosted: Hosted, user: string): Promise<void>;
+export declare function setup(hosted: Hosted, user: string, cls?: string): Promise<void>;

package/dist/beings/setup.js

@@ -0,0 +1,39 @@
+import { DESK, HOME } from './user.js';
+// The root boots and steps back: it invites an owner on the ward's own pk
+// and the user being knocks for it, so from then on placing a being,
+// minting a way in or removing one is an ask on her, shown by her gate to a
+// device that may mint, and the box is not logged into for it. The same
+// standing a user being of another ward takes to own this one; here it is
+// her own.
+export async function setupHome(hosted, user) {
+    const inv = (await hosted.ask('invite', { being: hosted.pk, id: HOME }));
+    if ('error' in inv)
+        throw new Error(`home: ${inv.error}`);
+    const placed = (await hosted.ask('knock', { being: user, id: HOME, invitation: inv }));
+    if (placed.taken !== HOME)
+        throw new Error(`home: ${placed.error ?? 'she could not take her own door'}`);
+}
+// The ward's home being is a `User` unless the device says which class: an
+// organisation's ward has an org's home being, of the estate's own class,
+// and everything else of setup, the desk and the door, is placed on her the
+// same way.
+export async function setup(hosted, user, cls = 'User') {
+    if (!/^[\w.-]+$/.test(user) || user === 'desk')
+        throw new Error(`a user is a word, and not desk: ${user}`);
+    const boot = async (args) => {
+        const out = (await hosted.ask('boot', args));
+        if (out.error)
+            throw new Error(`init: ${out.error}`);
+    };
+    await boot({ key: 'desk', class: 'Desk' });
+    const pub = (await hosted.ask('public', { key: 'desk' }));
+    if (pub.error)
+        throw new Error(`init: ${pub.error}`);
+    await boot({ key: user, class: cls });
+    const inv = (await hosted.ask('invite', { being: user, id: DESK }));
+    // the desk's first hello names her, since a being does not know her own key
+    const placed = (await hosted.ask('knock', { being: 'desk', id: `user:${user}`, invitation: inv, method: 'hello', args: { name: user } }));
+    if (placed.taken !== `user:${user}`)
+        throw new Error('init: the desk could not reach the user being');
+    await setupHome(hosted, user);
+}

package/dist/beings/side.d.ts

@@ -0,0 +1,32 @@
+import type { Answer, Blueprint, Json, JsonObject, Wanted, WordName } from '@nervur-org/nervur';
+import type { Avatar } from './avatar.ts';
+export type Serving = {
+    close(): Promise<void>;
+};
+export type Side = (avatar: Avatar) => Promise<Serving>;
+export type Subject = {
+    tools(): Promise<Blueprint | {
+        error: string;
+    }>;
+    call(name: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+    ears: Set<(object: JsonObject) => void>;
+};
+export type Word = {
+    word: 'object';
+    value: Json;
+} | {
+    word: 'error';
+    value: JsonObject;
+} | {
+    word: 'silence';
+} | {
+    word: 'unreached';
+} | {
+    word: 'quo';
+    name: WordName;
+};
+export declare function word(answer: Answer): Word;
+export declare const SILENCE_TEXT = "silence: the work may have happened, and no answer came back";
+export declare const UNREACHED_TEXT = "unreached: nothing was delivered; asking again is safe";
+export declare const WORD_TEXT: Record<WordName, string>;
+export declare const wordText: (name: WordName) => string;

package/dist/beings/side.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+// The side: the one interface an avatar speaks through to someone outside
+// Quo. A side takes the avatar object, in-process, and renders three things
+// its own way: her describe as what that someone reads, a call as an ask on
+// her one standing, and a push as a notification. Sides in this repository:
+// a screen, an MCP server, a runner, an event-driven agent. None knows
+// another exists, and none of this file names a platform.
+import { isSilence, isUnreached, isWord, wordOf } from '@nervur-org/nervur';
+export function word(answer) {
+    if (isSilence(answer))
+        return { word: 'silence' };
+    if (isUnreached(answer))
+        return { word: 'unreached' };
+    if (isWord(answer))
+        return { word: 'quo', name: wordOf(answer) };
+    if (answer !== null && typeof answer === 'object' && !Array.isArray(answer) && 'error' in answer)
+        return { word: 'error', value: answer };
+    return { word: 'object', value: answer };
+}
+// What a side says about the two words that carry nothing, so that whoever
+// reads them can decide: silence promises nothing, unreached promises that
+// nothing was delivered.
+export const SILENCE_TEXT = 'silence: the work may have happened, and no answer came back';
+export const UNREACHED_TEXT = 'unreached: nothing was delivered; asking again is safe';
+// And the ward's other words, each with what a side says of it.
+export const WORD_TEXT = {
+    unreached: UNREACHED_TEXT,
+    late: 'late: the wait ran out; the work may have happened',
+    invitation: 'invitation: that is not an invitation',
+    dropped: 'dropped: the standing is gone',
+    removed: 'removed: the far being removed you',
+    absent: 'absent: the far being did not come back this run',
+    unannounced: 'unannounced: the knock announced no key of its own',
+    repeated: 'repeated: that number was already honoured',
+    threw: 'threw: the far being threw',
+};
+export const wordText = (name) => WORD_TEXT[name];