@nervur-org/dock 0.4.1 → 0.6.0

package/dist/box/grants.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's grants: a bearer to an identity in a world, honoured on every
+// route alike. A route says the grammar a caller speaks and a grant says who
+// the caller is. A grant maps a token to an identity and nothing else; no
+// secret of Quo's is ever here.
+//
+// Her tokens are her cells. Issuing, refreshing and revoking are the routes'
+// to call on her in this process, and a token issued is a cell written
+// outside any ask, so she keeps her ward through her box. Her clock is the
+// box's. An access token lives an hour and a refresh token thirty days, and
+// refresh rotates.
+import { contract } from './contract.js';
+import { Faculty } from './faculty.js';
+// What a route needs from the box's grants. She lends nothing to beings, so
+// the contract has no ask; its title is what the box's own code finds her by.
+export const GRANTS = contract('grants', {});
+export const ACCESS_TTL = 60 * 60 * 1000;
+export const REFRESH_TTL = 30 * 24 * 60 * 60 * 1000;
+// Own keys only: a token is a string the far side offers.
+const own = (rec, key) => (Object.hasOwn(rec, key) ? rec[key] : undefined);
+// Thirty-two random bytes as base64url, from what every runtime has.
+const token = () => {
+    const bytes = globalThis.crypto.getRandomValues(new Uint8Array(32));
+    let binary = '';
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+};
+export class Grants extends Faculty {
+    static cells = { ...Faculty.cells, access: {}, refresh: {} };
+    static asks = {};
+    static fulfils = [GRANTS];
+    get kept() {
+        return this.cells;
+    }
+    // The box's moment, which is hers.
+    now() {
+        return this.box.now();
+    }
+    async issue(identity, ward, client) {
+        const access_token = token(), refresh_token = token();
+        this.kept.access[access_token] = { identity, ward, client, exp: this.now() + ACCESS_TTL };
+        this.kept.refresh[refresh_token] = { identity, ward, client, exp: this.now() + REFRESH_TTL };
+        this.sweep();
+        await this.box.save();
+        return { access_token, token_type: 'Bearer', expires_in: ACCESS_TTL / 1000, refresh_token, scope: 'nervur' };
+    }
+    async refresh(refresh_token) {
+        const r = own(this.kept.refresh, refresh_token);
+        if (!r || r.exp < this.now())
+            return null;
+        delete this.kept.refresh[refresh_token];
+        return this.issue(r.identity, r.ward, r.client);
+    }
+    bearer(req) {
+        const g = own(this.kept.access, offered(req));
+        return g && g.exp >= this.now() && typeof g.identity === 'string' ? { identity: g.identity, ward: g.ward } : null;
+    }
+    async revoke(identity, ward) {
+        for (const k of ['access', 'refresh'])
+            for (const [t, g] of Object.entries(this.kept[k]))
+                if (g.identity === identity && g.ward === ward)
+                    delete this.kept[k][t];
+        await this.box.save();
+    }
+    sweep() {
+        const now = this.now();
+        for (const k of ['access', 'refresh'])
+            for (const [t, g] of Object.entries(this.kept[k]))
+                if (!(g.exp >= now))
+                    delete this.kept[k][t];
+    }
+}
+// What a request offered as its bearer, or nothing.
+export const offered = (req) => {
+    const h = req.headers.get('authorization') ?? '';
+    return h.startsWith('Bearer ') ? h.slice(7) : '';
+};

package/dist/box/http.d.ts

@@ -0,0 +1,26 @@
+import type { Asker, JsonObject, OccupantRecord } from 'nervur';
+import { Faculty } from './faculty.ts';
+export declare const WIRE: import("nervur").Blueprint;
+declare const root: (_occ: OccupantRecord | undefined, asker: Asker) => boolean;
+export declare class Http extends Faculty {
+    static fulfils: import("nervur").Blueprint[];
+    static cells: JsonObject;
+    static asks: {
+        wired: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    claimed: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof root;
+        };
+    };
+    wired(args: JsonObject): JsonObject;
+    handle(req: Request): Promise<Response>;
+}
+export {};

package/dist/box/http.js

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+// The http faculty: the box's wire. A terrain that owns a wire hands her every
+// request no route of its own took, and she hands the bytes on a claimed
+// path to the faculty that claims it, through a standing the root placed at
+// unpacking, as the occupant `http:<path>`. Nobody asks with owner rights:
+// the faculty called in is asked by her, and answers in her own words.
+//
+// What crosses back is what every route here speaks: an object is 200, an
+// error object 400, and no object at all 503. A path nobody claims is 404, a
+// method but GET and POST is 405, and a body past a megabyte is 413. A GET
+// is where a redirect lands, the code in the query, and a GET from a browser
+// is a human sent back from somewhere: she is shown a page saying whether it
+// finished, and never what the faculty answered a machine.
+import { isSilence, isWord, OWNER } from 'nervur';
+import { landed, POLICY } from '../human/door.js';
+import { CSS } from '../human/style.js';
+import { contract } from './contract.js';
+import { Faculty } from './faculty.js';
+// The box's wire. She lends nothing to beings, so her contract has no ask;
+// its title is what unpacking finds her by.
+export const WIRE = contract('http', {});
+const LIMIT = 1 << 20;
+const json = (status, body) => Response.json(body, { status });
+// The one page this wire serves, wearing the one stylesheet every screen
+// wears, and allowed no script, since it runs none.
+const page = (status, body) => new Response(`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>nervur</title>\n<style>${CSS}</style>\n</head><body>${body}</body></html>`, {
+    status,
+    headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': POLICY, 'referrer-policy': 'no-referrer' },
+});
+const root = (_occ, asker) => asker.id === OWNER;
+export class Http extends Faculty {
+    static fulfils = [WIRE];
+    static cells = { watched: {}, minted: 0, claimed: {} };
+    static asks = {
+        wired: {
+            description: 'what this boot claims: each path to the faculty that claims it; a path held that this does not say goes',
+            input: { type: 'object', properties: { claimed: { type: 'object' } }, required: ['claimed'] },
+            for: root,
+        },
+    };
+    // The paths this run placed, held to: a standing under a path nobody
+    // claims now, or that another faculty claims now, goes here, and the
+    // root removes the far end. She answers what she holds and what went.
+    wired(args) {
+        const claimed = args.claimed;
+        if (claimed === null || typeof claimed !== 'object' || Array.isArray(claimed) || !Object.values(claimed).every((k) => typeof k === 'string'))
+            return { error: 'claimed is a path to a key' };
+        const was = (this.cells.claimed ?? {});
+        const pruned = [];
+        for (const p of Object.keys(this.cells.standings)) {
+            if (Object.hasOwn(claimed, p) && was[p] === claimed[p])
+                continue;
+            this.standings.remove(p);
+            pruned.push(p);
+        }
+        this.cells.claimed = claimed;
+        return { held: Object.keys(this.cells.standings), pruned };
+    }
+    // The terrain's own call, crossing no door: one request, one response.
+    // The longest claimed path the request's path begins with, at a segment
+    // boundary, is the faculty it goes to.
+    async handle(req) {
+        const url = new URL(req.url);
+        const claimed = Object.keys(this.cells.standings)
+            .filter((p) => url.pathname === p || url.pathname.startsWith(`${p}/`))
+            .sort((a, b) => b.length - a.length)[0];
+        const at = claimed === undefined ? undefined : this.standings[claimed];
+        if (!at)
+            return json(404, { error: 'nobody claims this path' });
+        if (req.method !== 'GET' && req.method !== 'POST')
+            return json(405, { error: 'POST, or GET for a redirect' });
+        const bytes = req.method === 'GET' ? new ArrayBuffer(0) : await req.arrayBuffer();
+        if (bytes.byteLength > LIMIT)
+            return json(413, { error: 'too big' });
+        const headers = {};
+        req.headers.forEach((v, k) => (headers[k] = v));
+        const out = await at.ask('inbound', { body: new TextDecoder().decode(bytes), headers, query: url.search.slice(1), method: req.method });
+        const object = out !== undefined && !isSilence(out) && !isWord(out) && out !== null && typeof out === 'object' && !Array.isArray(out) ? out : null;
+        if (req.method === 'GET' && (req.headers.get('accept') ?? '').includes('text/html')) {
+            const ok = object !== null && typeof object.error !== 'string';
+            // No host is printed: a Host header is the caller's to write, and a
+            // page that printed one would print whatever a caller wanted read.
+            return page(ok ? 200 : 400, landed({ host: '', ok }));
+        }
+        if (object === null)
+            return json(503, { error: 'silence' });
+        return json(typeof object.error === 'string' ? 400 : 200, object);
+    }
+}

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

@@ -1,4 +1,4 @@
-import type { Ring } from './push.ts';
+import type { Ring } from './ring.ts';
 import { HOSTS, type Apns } from './apns.ts';
 export declare function apnsOf(env: Record<string, string | undefined>): Apns | null;
 export declare function apnsHttp2(a: Apns, at?: typeof HOSTS, within?: number): Ring;

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

@@ -9,7 +9,7 @@
 // It is its own file for one reason, and the reason is the import. A worker
 // bundle that pulled `node:http2` in would not build, so nothing terrain
 // neutral may name this file: it is imported by the Node terrain and by
-// nothing else, and it is not exported from `dock/index.ts`.
+// nothing else, and it is not exported from `box/index.ts`.
 //
 // A session is one TCP connection carrying every ring to one of Apple's two
 // hosts, which is what HTTP/2 is for and what Apple asks of a provider that
@@ -54,12 +54,12 @@ export function apnsHttp2(a, at = HOSTS, within = WITHIN) {
             stream.setEncoding('utf8');
             stream.setTimeout(within, () => stream.destroy(new Error('apns did not answer')));
             const { status, text } = await new Promise((ok, no) => {
-                let status = 0;
-                let text = '';
-                stream.on('response', (h) => (status = Number(h[':status'] ?? 0)));
-                stream.on('data', (chunk) => (text += chunk));
+                let code = 0;
+                let body = '';
+                stream.on('response', (h) => (code = h[':status'] ?? 0));
+                stream.on('data', (chunk) => (body += chunk));
                 stream.on('error', no);
-                stream.on('end', () => ok({ status, text }));
+                stream.on('end', () => ok({ status: code, text: body }));
                 stream.end(req.body);
             });
             answered(status, text);

package/dist/box/index.d.ts

@@ -0,0 +1,46 @@
+import type { Harbor, WardPointers } from 'nervur/harbor';
+import type { BeingClass } from 'nervur';
+import { type BoxCells } from './dock.ts';
+import { type Contract } from './contract.ts';
+import { type Faculty } from './faculty.ts';
+import type { Harborage } from './box.ts';
+import { type Tree } from './tree.ts';
+export { ALONE, harborageOver, type Harborage } from './box.ts';
+export { Dock, BOX, DOMAIN, routesFor, type Routes, type Apps, type BoxCells } from './dock.ts';
+export { BOX_SEED } from 'nervur/harbor';
+export { Faculty, WATCH, INBOUND, HTTP, type Watched } from './faculty.ts';
+export { Http, WIRE } from './http.ts';
+export { Timer, TIMER } from './timer.ts';
+export { Local, LOCAL } from './local.ts';
+export { Grants, GRANTS, offered, ACCESS_TTL, REFRESH_TTL, type Grant, type Tokens, type Bearers } from './grants.ts';
+export { Push, PUSH } from './push.ts';
+export { Agents, AGENTS, isProcess, type Row as AgentRow, type Runner, type Side } from './agents.ts';
+export { Dialers, DIALERS } from './dialers.ts';
+export { EnvoyFaculty, WATCH_ACCOUNT, type Delivery } from './envoy.ts';
+export { contract, covers, nameOf, titleOf, type Contract } from './contract.ts';
+export { join, settled } from './join.ts';
+export { Location, LOCATION, type Where } from './location.ts';
+export { Notifications, NOTIFICATIONS } from './notifications.ts';
+export { keyed, type Tree } from './tree.ts';
+export { isToken, bellOf, banner, sealBanner, SEAL, type Token, type Ring, type Line } from './ring.ts';
+export { webPush, mintVapid, publicOf, type Vapid } from './webpush.ts';
+export { apnsPush, pkcs8, HOSTS, type Apns } from './apns.ts';
+export { fcmPush, isAccount, DOORS, type Account, type Doors } from './fcm.ts';
+export { handedTo, ringing, routed } from './service.ts';
+export declare const OWN: Tree;
+export declare function classes(tree: Tree, box: Harborage): Record<string, BeingClass>;
+type Boxed = {
+    wards: ReadonlyMap<string, {
+        ask: WardPointers['ask'];
+        being(key: string): unknown;
+    }>;
+};
+export declare function keyLent(harbor: Boxed, needs: Contract): Promise<string | undefined>;
+export declare function lent<F extends Faculty>(harbor: Boxed, needs: Contract): Promise<F | undefined>;
+export declare function boxOf(harbor: Boxed): Promise<BoxCells>;
+export declare function standHarbor(harbor: Harbor, tree: Tree, box: Harborage): Promise<void>;
+export type Rooted = {
+    ask(method?: string, args?: Record<string, unknown>): Promise<unknown>;
+    save?(): Promise<void>;
+};
+export declare function stand(ward: Rooted, tree?: Tree): Promise<void>;

package/dist/box/index.js

@@ -0,0 +1,179 @@
+import { BOX, hold, offerTo, BOX_SEED } from 'nervur/harbor';
+import { isInvitation } from 'nervur';
+import { Dock } from './dock.js';
+import { nameOf, titleOf } from './contract.js';
+import { HTTP } from './faculty.js';
+import { WIRE } from './http.js';
+import { keyed } from './tree.js';
+export { ALONE, harborageOver } from './box.js';
+export { Dock, BOX, DOMAIN, routesFor } from './dock.js';
+export { BOX_SEED } from 'nervur/harbor';
+export { Faculty, WATCH, INBOUND, HTTP } from './faculty.js';
+export { Http, WIRE } from './http.js';
+export { Timer, TIMER } from './timer.js';
+export { Local, LOCAL } from './local.js';
+export { Grants, GRANTS, offered, ACCESS_TTL, REFRESH_TTL } from './grants.js';
+export { Push, PUSH } from './push.js';
+export { Agents, AGENTS, isProcess } from './agents.js';
+export { Dialers, DIALERS } from './dialers.js';
+export { EnvoyFaculty, WATCH_ACCOUNT } from './envoy.js';
+export { contract, covers, nameOf, titleOf } from './contract.js';
+export { join, settled } from './join.js';
+export { Location, LOCATION } from './location.js';
+export { Notifications, NOTIFICATIONS } from './notifications.js';
+export { keyed } from './tree.js';
+// What waking a device rings through: the push parts every terrain shares,
+// the three grounds, and the bell service that holds a publisher's keys.
+export { isToken, bellOf, banner, sealBanner, SEAL } from './ring.js';
+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 classes this folder brings to every box ward, as a tree.
+export const OWN = { box: { Dock } };
+const isFaculty = (v) => typeof v === 'function' && Array.isArray(v.fulfils) && typeof v.stands === 'function';
+// The classes a box ward is handed, keyed where they live, every faculty
+// among them born holding this box. The kit makes a being with her stance
+// alone, so the class found under a faculty's key is her own class with the
+// harborage handed on.
+export function classes(tree, box) {
+    const out = keyed(OWN);
+    for (const [key, C] of Object.entries(keyed(tree))) {
+        if (!isFaculty(C))
+            continue;
+        const F = C;
+        out[key] = class extends F {
+            constructor(stance) {
+                super(stance, box);
+            }
+        };
+    }
+    return out;
+}
+export async function keyLent(harbor, needs) {
+    const ward = harbor.wards.get(BOX_SEED);
+    if (!ward)
+        return undefined;
+    const out = (await ward.ask('ask', { being: BOX, method: 'lends' }));
+    return out.lends?.[await nameOf(needs)];
+}
+export async function lent(harbor, needs) {
+    const key = await keyLent(harbor, needs);
+    return key === undefined ? undefined : harbor.wards.get(BOX_SEED)?.being(key);
+}
+// What the box is, asked of the Dock: its routes, its apps and its default
+// ward, each null until the root said it. A harbor with no box ward is a
+// box that is nothing yet.
+export async function boxOf(harbor) {
+    const ward = harbor.wards.get(BOX_SEED);
+    const out = ward ? (await ward.ask('ask', { being: BOX, method: 'box' })) : {};
+    return { routes: out.routes ?? null, apps: out.apps ?? null, default: out.default ?? null };
+}
+// Act one on a harbor: its classes handed to it, each faculty born holding
+// this box, the box's ward woken from what the store keeps or made, and
+// stood. From here the harbor hands every other ward one invitation on the
+// Dock, which is act two, the kit's.
+export async function standHarbor(harbor, tree, box) {
+    Object.assign(harbor.classes, classes(tree, box));
+    const kept = await harbor.store.load(BOX_SEED);
+    const ward = harbor.wards.get(BOX_SEED) ?? (kept ? await harbor.host(BOX_SEED, kept) : await harbor.create(BOX_SEED, BOX));
+    await stand(ward, tree);
+    harbor.offering = (name) => offerTo(ward, name);
+}
+// Stand a box ward already made, in the order a harbor stands: her own
+// being first, then every faculty of the tree whose class stands, each held
+// by her under its key, then the index of which faculty fulfils which
+// contract written into her cells, then every claimed path placed on the
+// wire. A key already booted is refused and costs nothing, so standing a
+// ward that woke from its partition finds every being as it was; and a run
+// says only itself, so a title or a path an earlier run placed that this
+// one does not is removed at both ends before anything is placed.
+export async function stand(ward, tree = {}) {
+    const own = keyed(OWN);
+    await ward.ask('boot', { key: BOX, class: Object.keys(own).find((k) => own[k] === Dock) });
+    const standing = Object.entries(keyed(tree)).filter((e) => isFaculty(e[1]) && e[1].stands());
+    // The index. Under each contract, the classes that fulfil it, and of
+    // those the ones no other extends, so a subclass wins over its base when
+    // both stand. One left is lent under it. Two left, with neither extending
+    // the other, are a clash: the contract is lent to neither, the Dock keeps
+    // the clash by name in her cells for the root to read and a terrain to
+    // print, and the box stays up, so one bad contract costs that contract
+    // and nothing else.
+    const under = new Map();
+    const names = new Map();
+    for (const [key, C] of standing) {
+        for (const c of C.fulfils) {
+            const name = await nameOf(c);
+            names.set(key, [...(names.get(key) ?? []), name]);
+            const u = under.get(name) ?? { title: titleOf(c), keys: [] };
+            u.keys.push([key, C]);
+            under.set(name, u);
+        }
+    }
+    const lends = {};
+    const clashes = {};
+    for (const [name, u] of under) {
+        const leaves = u.keys.filter(([, C]) => !u.keys.some(([, D]) => D !== C && D.prototype instanceof C));
+        if (leaves.length === 1)
+            lends[name] = leaves[0][0];
+        else
+            clashes[u.title || name] = leaves.map(([k]) => k);
+    }
+    // The word a screen shows a faculty under: what the first contract she is
+    // lent under calls itself. A key carries a slash and a title never does.
+    const titles = {};
+    for (const [key] of standing) {
+        const first = (names.get(key) ?? []).find((n) => lends[n] === key);
+        const title = first === undefined ? '' : (under.get(first)?.title ?? '');
+        if (title && title !== key)
+            titles[title] = key;
+    }
+    const claims = new Map();
+    for (const [key, C] of standing) {
+        const made = (await ward.ask('boot', { key, class: key }));
+        if (made.booted === key)
+            await hold(ward, key);
+        for (const p of C.claims ?? [])
+            claims.set(p, [...(claims.get(p) ?? []), key]);
+    }
+    // The index written whole, and the Dock's title standings held to this
+    // run: she removes her end of one this run does not place, and the root
+    // removes the far end from every faculty she holds, before placing what
+    // she does not hold yet.
+    const stood = (await ward.ask('ask', { being: BOX, method: 'stood', args: { lends, titles, clashes } }));
+    const keys = (stood.held ?? []).filter((id) => id.includes('/'));
+    for (const t of stood.pruned ?? [])
+        for (const key of keys)
+            await ward.ask('remove', { being: key, id: `${BOX}:${t}` });
+    for (const [title, key] of Object.entries(titles)) {
+        if (stood.held?.includes(title))
+            continue;
+        const inv = await ward.ask('invite', { being: key, id: `${BOX}:${title}` });
+        if (isInvitation(inv))
+            await ward.ask('knock', { being: BOX, id: title, invitation: inv });
+    }
+    // Every claimed path, placed on the box's wire: the root invites on the
+    // faculty that claims it for the http faculty, who holds it under the
+    // path. A path two faculties claim is neither's, and the box stays up. A
+    // path she holds that this run does not claim, or that another faculty
+    // claims now, goes at both ends the same way a title does.
+    const wire = lends[await nameOf(WIRE)];
+    if (wire) {
+        const claimed = {};
+        for (const [p, ks] of claims)
+            if (ks.length === 1)
+                claimed[p] = ks[0];
+        const wired = (await ward.ask('ask', { being: wire, method: 'wired', args: { claimed } }));
+        for (const p of wired.pruned ?? [])
+            for (const key of keys)
+                await ward.ask('remove', { being: key, id: `${HTTP}${p}` });
+        for (const [p, key] of Object.entries(claimed)) {
+            if (wired.held?.includes(p))
+                continue;
+            const inv = await ward.ask('invite', { being: key, id: `${HTTP}${p}` });
+            if (isInvitation(inv))
+                await ward.ask('knock', { being: wire, id: p, invitation: inv });
+        }
+    }
+    await ward.save?.();
+}

package/dist/box/join.d.ts

@@ -0,0 +1,19 @@
+import type { Being, JsonObject } from 'nervur';
+import { type Contract } from './contract.ts';
+export type Hosting = {
+    keys(): string[];
+    being(key: string): unknown;
+};
+type Memory = {
+    partitions: ReadonlyMap<string, Record<string, unknown>>;
+    objects: WeakMap<object, unknown>;
+};
+export declare function settled(of: {
+    wards: ReadonlyMap<string, Hosting>;
+} | Hosting | Memory): Promise<void>;
+export declare function join(b: Being, needs: Contract, id: string, watch?: {
+    method: string;
+    args?: JsonObject;
+    with?: JsonObject;
+}): Promise<string | null>;
+export {};

package/dist/box/join.js

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: Apache-2.0
+// How a being takes what her box lends. She names the contract she needs and
+// the id she holds it under; the box lends under the contract's digest; she
+// reads the describe she was handed and keeps it only if it covers what she
+// asked for. With `watch` she also asks to be woken, as the occupant she
+// names `<id>:wake`, handing whatever the faculty needs to know her by; a
+// watch refused puts the whole relation down.
+//
+// A being takes what her box lends at her birth, again at every birth, since
+// a restart and a move are one event to her. Birth is synchronous and taking
+// a standing is not, so every join in flight is kept on the being who made
+// it, and a terrain waits on `settled` over its own wards once they are
+// hosted: a box is up when its beings have landed, and another box's beings
+// are no business of this one.
+import { isBlueprint } from 'nervur';
+import { covers, nameOf } from './contract.js';
+const flight = new WeakMap();
+const beingsOf = (of) => {
+    if ('partitions' in of)
+        return [...of.partitions.values()].flatMap((rows) => Object.values((rows.beings ?? {})).map((cells) => of.objects.get(cells)));
+    const wards = 'wards' in of ? [...of.wards.values()] : [of];
+    return wards.flatMap((w) => w.keys().map((k) => w.being(k)));
+};
+// Every join in flight on one box's wards, or on one ward, landed. Walked
+// again until nothing is in flight, since a being landing may boot another.
+export async function settled(of) {
+    for (;;) {
+        const now = beingsOf(of).flatMap((b) => [...(flight.get(b) ?? [])]);
+        if (now.length === 0)
+            return;
+        await Promise.allSettled(now);
+    }
+}
+export function join(b, needs, id, watch) {
+    const p = joining(b, needs, id, watch);
+    const mine = flight.get(b) ?? new Set();
+    mine.add(p);
+    flight.set(b, mine);
+    const done = () => void mine.delete(p);
+    void p.then(done, done);
+    return p;
+}
+async function joining(b, needs, id, watch) {
+    // One turn first: her ward sets her door after her constructor returns, so
+    // a stance call made inside it would reach a being her ward does not hold
+    // yet.
+    await Promise.resolve();
+    b.standings.remove(id);
+    b.occupants.remove(`${id}:wake`);
+    if ((await b.lend(await nameOf(needs), id)) === null)
+        return null;
+    const held = await b.standings[id]?.ask();
+    if (!isBlueprint(held) || !covers(held, needs)) {
+        b.standings.remove(id);
+        return null;
+    }
+    if (watch) {
+        const back = await b.invite(`${id}:wake`);
+        const said = back ? await b.standings[id]?.ask('watch', { ...watch.with, invitation: back, method: watch.method, ...(watch.args ? { args: watch.args } : {}) }) : undefined;
+        if (!said || typeof said !== 'object' || 'error' in said) {
+            b.standings.remove(id);
+            b.occupants.remove(`${id}:wake`);
+            return null;
+        }
+    }
+    return id;
+}

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

@@ -1,12 +1,13 @@
-import { Faculty } from './faculty.ts';
 import type { JsonObject } from 'nervur';
 import { type Verified } from '../beings/way.ts';
-export declare const LOCAL = "local";
+import { Faculty } from './faculty.ts';
+export declare const LOCAL: import("nervur").Blueprint;
 export declare class Local extends Faculty {
     #private;
     static asks: {
         verify: import("nervur").AskSpec;
     };
+    static fulfils: import("nervur").Blueprint[];
     mint(nonce: string, who: Verified): void;
     drop(nonce: string): void;
     verify(args: JsonObject): Verified | null;

package/dist/box/local.js

@@ -0,0 +1,27 @@
+import { VERIFY } from '../beings/way.js';
+import { contract } from './contract.js';
+import { Faculty } from './faculty.js';
+// What a desk needs from a box that saw a process on its own socket.
+export const LOCAL = contract('local', { verify: VERIFY });
+export class Local extends Faculty {
+    static asks = { verify: VERIFY };
+    static fulfils = [LOCAL];
+    #nonces = new Map();
+    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 → box}/location.d.ts

@@ -6,6 +6,7 @@ export type Where = {
     accuracy?: number;
     at: number;
 };
+export declare const LOCATION: import("nervur").Blueprint;
 export declare class Location extends Faculty {
     static asks: {
         where: {
@@ -15,5 +16,7 @@ export declare class Location extends Faculty {
             };
         };
     };
+    static fulfils: import("nervur").Blueprint[];
+    static stands(): boolean;
     where(): Promise<JsonObject>;
 }

package/dist/box/location.js

@@ -0,0 +1,21 @@
+import { Faculty } from './faculty.js';
+import { contract } from './contract.js';
+const ASKS = {
+    where: { description: 'where this box is', input: { type: 'object' } },
+};
+// What a being needs from a box that can say where it is.
+export const LOCATION = contract('location', ASKS);
+export class Location extends Faculty {
+    static asks = ASKS;
+    static fulfils = [LOCATION];
+    // This body says where nothing is, so it stands nowhere: a terrain whose
+    // platform can answer subclasses her and says so.
+    static stands() {
+        return false;
+    }
+    // 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 → box}/notifications.d.ts

@@ -1,5 +1,6 @@
 import type { JsonObject } from 'nervur';
 import { Faculty } from './faculty.ts';
+export declare const NOTIFICATIONS: import("nervur").Blueprint;
 export declare class Notifications extends Faculty {
     static cells: JsonObject;
     static asks: {
@@ -25,6 +26,8 @@ export declare class Notifications extends Faculty {
             };
         };
     };
+    static fulfils: import("nervur").Blueprint[];
+    static stands(): boolean;
     notify(_args: JsonObject): Promise<JsonObject>;
     key(): Promise<{
         secret: Uint8Array;