@nervur-org/dock 0.4.1 → 0.6.0

package/dist/box/dock.d.ts

@@ -0,0 +1,182 @@
+import { Box } from 'nervur/harbor';
+import type { Asker, JsonObject, OccupantRecord, Reply } from 'nervur';
+export { BOX } from 'nervur/harbor';
+declare const root: (_occ: OccupantRecord | undefined, asker: Asker) => boolean;
+export type Routes = {
+    mcp: string;
+    web: string;
+    quo?: string;
+    api?: string;
+};
+export declare const DOMAIN: RegExp;
+export declare function routesFor(domain: string): Required<Routes>;
+export type Apps = {
+    apple: string[];
+    android: {
+        package: string;
+        fingerprints: string[];
+    }[];
+};
+export type BoxCells = {
+    routes: Routes | null;
+    apps: Apps | null;
+    default: string | null;
+};
+export declare class Dock extends Box {
+    #private;
+    static carries(occupant: OccupantRecord | undefined): boolean;
+    static skips(id: string): boolean;
+    static cells: JsonObject;
+    static asks: {
+        offer: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    name: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: (occ: OccupantRecord | undefined) => boolean;
+        };
+        retract: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    name: {
+                        type: string;
+                    };
+                    heir: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: (occ: OccupantRecord | undefined) => boolean;
+        };
+        host: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    seed: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: (_occ: OccupantRecord | undefined, asker: Asker) => boolean;
+        };
+        roll: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: (_occ: OccupantRecord | undefined, asker: Asker) => boolean;
+        };
+        box: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: typeof root;
+        };
+        domain: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    domain: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof root;
+        };
+        apps: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    apple: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                    };
+                    android: {
+                        type: string;
+                        items: {
+                            type: string;
+                            properties: {
+                                package: {
+                                    type: string;
+                                };
+                                fingerprints: {
+                                    type: string;
+                                    items: {
+                                        type: string;
+                                    };
+                                };
+                            };
+                            required: string[];
+                        };
+                    };
+                };
+            };
+            for: typeof root;
+        };
+        default: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    ward: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof root;
+        };
+        lends: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: typeof root;
+        };
+        stood: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    lends: {
+                        type: string;
+                    };
+                    titles: {
+                        type: string;
+                    };
+                    clashes: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof root;
+        };
+    };
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
+    offer(args: JsonObject): Promise<JsonObject>;
+    retract(args: JsonObject): Promise<JsonObject>;
+    lends(): JsonObject;
+    box(): JsonObject;
+    domain(args: JsonObject): JsonObject;
+    apps(args: JsonObject): JsonObject;
+    default(args: JsonObject): JsonObject;
+    stood(args: JsonObject): JsonObject;
+}

package/dist/box/dock.js

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box ward's own being, and so the harbor's. She is the kit's Box, the
+// box as one standing that every hosted ward holds, and two things more.
+//
+// She lends by contract: a being asks her for a contract's digest, and she
+// holds each faculty under its key, so her cells keep the index from digest
+// to key, written whole by the root at every boot from what this run's
+// classes say. A name she is asked to offer is a digest first and a key
+// second, and then it is the kit's offer.
+//
+// And she carries: she holds a standing at every faculty her harbor stood
+// and shows their asks as her own to whoever the root let in, so the one
+// screen a device has with no world joined draws her the way it draws any
+// being.
+import { OWNER } from 'nervur';
+import { Box, BOX_SEED } from 'nervur/harbor';
+import { carry } from '../beings/carry.js';
+export { BOX } from 'nervur/harbor';
+const root = (_occ, asker) => asker.id === OWNER;
+export const DOMAIN = /^[a-z0-9.-]+\.[a-z]{2,}$/i;
+export function routesFor(domain) {
+    if (!DOMAIN.test(domain))
+        throw new Error(`${domain} is not a domain`);
+    return { mcp: `https://mcp.${domain}`, web: `https://web.${domain}`, quo: `https://quo.${domain}`, api: `https://api.${domain}` };
+}
+const APPS = { type: 'object', properties: { apple: { type: 'array', items: { type: 'string' } }, android: { type: 'array', items: { type: 'object', properties: { package: { type: 'string' }, fingerprints: { type: 'array', items: { type: 'string' } } }, required: ['package', 'fingerprints'] } } } };
+export class Dock extends Box {
+    static carries(occupant) {
+        return occupant !== undefined;
+    }
+    // She holds every faculty twice: under its key, which is the lend seam
+    // and plumbing, and under the word the first contract it is lent under
+    // calls itself, which is the section a screen shows. A key is a path
+    // through the class tree and always carries a slash; a title never does.
+    // Both are this run's: `stood` writes the index whole and puts down any
+    // title standing this run does not say.
+    static skips(id) {
+        return id.includes('/');
+    }
+    static cells = { lends: {}, titles: {}, clashes: {}, hosted: [], routes: null, apps: null, default: null };
+    static asks = {
+        ...Box.asks,
+        box: { description: 'what this box is: its routes, its apps and its default ward, each null until said', input: { type: 'object' }, for: root },
+        domain: { description: 'the four routes by the convention, mcp., web., quo. and api. under this domain over https, kept until said again', input: { type: 'object', properties: { domain: { type: 'string' } }, required: ['domain'] }, for: root },
+        apps: { description: 'the apps this box’s links open, apple app ids and android packages with their fingerprints; neither named forgets them', input: APPS, for: root },
+        default: { description: 'the ward a caller means when naming none; the harbor holds it to the wards it hosts at boot', input: { type: 'object', properties: { ward: { type: 'string' } }, required: ['ward'] }, for: root },
+        lends: { description: 'which faculty is lent under each contract, by digest to key, and which contracts are lent to nobody because two classes clashed under them', input: { type: 'object' }, for: root },
+        stood: {
+            description: 'what this boot stood: each contract, by digest, to the faculty that fulfils it, each title to the faculty shown under it, and each clash to the keys that clashed; a title held that this does not say goes',
+            input: { type: 'object', properties: { lends: { type: 'object' }, titles: { type: 'object' }, clashes: { type: 'object' } }, required: ['lends', 'titles', 'clashes'] },
+            for: root,
+        },
+    };
+    answer(asker, method, args = {}) {
+        return carry(this, asker, method, args, (a, m, g) => super.answer(a, m, g));
+    }
+    #key(name) {
+        const index = this.cells.lends;
+        return Object.hasOwn(index, name) ? index[name] : name;
+    }
+    offer(args) {
+        return super.offer({ name: this.#key(args.name) });
+    }
+    retract(args) {
+        return super.retract({ ...args, name: this.#key(args.name) });
+    }
+    lends() {
+        return { lends: this.cells.lends, clashes: this.cells.clashes ?? {} };
+    }
+    // What the box is, placed by the root and read by the harbor: nothing here
+    // comes from a file.
+    box() {
+        return { routes: this.cells.routes ?? null, apps: this.cells.apps ?? null, default: this.cells.default ?? null };
+    }
+    domain(args) {
+        if (typeof args.domain !== 'string' || !DOMAIN.test(args.domain))
+            return { error: `${JSON.stringify(args.domain)} is not a domain` };
+        this.cells.routes = routesFor(args.domain);
+        return { routes: this.cells.routes };
+    }
+    apps(args) {
+        const apple = Array.isArray(args.apple) ? args.apple.filter((x) => typeof x === 'string') : [];
+        const android = Array.isArray(args.android)
+            ? args.android
+                .filter((a) => typeof a?.package === 'string' && Array.isArray(a.fingerprints))
+                .map((a) => ({ package: a.package, fingerprints: a.fingerprints.filter((f) => typeof f === 'string') }))
+            : [];
+        this.cells.apps = apple.length === 0 && android.length === 0 ? null : { apple, android };
+        return { apps: this.cells.apps };
+    }
+    default(args) {
+        if (typeof args.ward !== 'string' || args.ward === '' || args.ward === BOX_SEED)
+            return { error: 'a ward is a name, and the box ward is never the default' };
+        this.cells.default = args.ward;
+        return { default: args.ward };
+    }
+    // The index, written whole at every boot: what stands is what this run's
+    // classes say, and nothing an earlier run said, the clashes with it, by
+    // the word the contract calls itself to the keys that clashed. Her title
+    // standings are held to it: one under a title this run shows nobody
+    // under, or that now names another faculty, goes here, and the root
+    // removes the far end. She answers what she holds and what went, so the
+    // root places only what is not there.
+    stood(args) {
+        const { lends, titles, clashes } = args;
+        if (!isIndex(lends))
+            return { error: 'lends is a digest to a key' };
+        if (!isIndex(titles))
+            return { error: 'titles is a title to a key' };
+        if (clashes === null || typeof clashes !== 'object' || Array.isArray(clashes) || !Object.values(clashes).every((ks) => Array.isArray(ks) && ks.every((k) => typeof k === 'string')))
+            return { error: 'clashes is a word to keys' };
+        this.cells.clashes = clashes;
+        const was = (this.cells.titles ?? {});
+        const pruned = [];
+        for (const id of Object.keys(this.cells.standings)) {
+            if (id.includes('/'))
+                continue;
+            if (Object.hasOwn(titles, id) && was[id] === titles[id])
+                continue;
+            this.standings.remove(id);
+            pruned.push(id);
+        }
+        this.cells.lends = lends;
+        this.cells.titles = titles;
+        return { lends, held: Object.keys(this.cells.standings), pruned };
+    }
+}
+const isIndex = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && Object.values(v).every((k) => typeof k === 'string');

package/dist/box/envoy.d.ts

@@ -0,0 +1,44 @@
+import type { Asker, JsonObject } from 'nervur';
+import { Faculty } from './faculty.ts';
+export declare const WATCH_ACCOUNT: {
+    description: string;
+    input: {
+        type: string;
+        properties: {
+            invitation: {
+                type: string;
+            };
+            method: {
+                type: string;
+            };
+            args: {
+                type: string;
+            };
+            account: {
+                type: string;
+            };
+            secret: {
+                type: string;
+            };
+        };
+        required: string[];
+    };
+};
+export type Delivery = {
+    id: string;
+    method: string;
+    args: JsonObject;
+};
+export declare class EnvoyFaculty extends Faculty {
+    #private;
+    static cells: JsonObject;
+    watch(args: JsonObject, asker: Asker): Promise<JsonObject>;
+    get waking(): Promise<void>;
+    inbound(args: JsonObject): Promise<JsonObject>;
+    protected account(_body: string, _headers: Record<string, string>): string | null;
+    protected verify(_body: string, _headers: Record<string, string>, _secret: string): Promise<boolean> | boolean;
+    protected decode(_body: string, _headers: Record<string, string>): Delivery | {
+        error: string;
+    };
+    protected hmac(secret: string, text: string): Promise<string>;
+}

package/dist/box/envoy.js

@@ -0,0 +1,75 @@
+import { Faculty, WATCH } from './faculty.js';
+// A watch for an account: the invitation back, the ask to wake her with,
+// her account at the vendor and the secret the vendor signs with.
+export const WATCH_ACCOUNT = {
+    description: 'wake me for my account: an invitation back, the ask to wake me with, the account id and its signing secret',
+    input: { type: 'object', properties: { ...WATCH.input.properties, account: { type: 'string' }, secret: { type: 'string' } }, required: ['invitation', 'method', 'account', 'secret'] },
+};
+const SEEN = 200;
+export class EnvoyFaculty extends Faculty {
+    static cells = { watched: {}, minted: 0, seen: [] };
+    async watch(args, asker) {
+        if (typeof args.account !== 'string' || !args.account || typeof args.secret !== 'string' || !args.secret)
+            return { error: 'an account and its secret' };
+        const out = await super.watch(args, asker);
+        const id = out.watching;
+        if (typeof id === 'string')
+            Object.assign(this.cells.watched[id], { account: args.account, secret: args.secret });
+        return out;
+    }
+    #waking = Promise.resolve();
+    // The wake that went out after the last `{ ok }`, for the device's own
+    // code and a suite.
+    get waking() {
+        return this.#waking;
+    }
+    // The vendor's bytes, as they arrived on a path she claims, handed by the
+    // http faculty; nothing in them is trusted before `verify`.
+    async inbound(args) {
+        const body = typeof args.body === 'string' ? args.body : '';
+        const headers = (args.headers !== null && typeof args.headers === 'object' && !Array.isArray(args.headers) ? args.headers : {});
+        const account = this.account(body, headers);
+        const watched = this.cells.watched;
+        const mine = account === null ? [] : Object.entries(watched).filter(([, w]) => w.account === account);
+        if (mine.length === 0)
+            return { error: 'nobody watches that account' };
+        // every watcher of the account whose secret the bytes were signed with
+        const at = [];
+        for (const [id, w] of mine)
+            if (await this.verify(body, headers, w.secret))
+                at.push(id);
+        if (at.length === 0)
+            return { error: 'bad signature' };
+        const d = this.decode(body, headers);
+        if ('error' in d)
+            return d;
+        const seen = this.cells.seen;
+        if (seen.includes(d.id))
+            return { ok: true };
+        seen.push(d.id);
+        while (seen.length > SEEN)
+            seen.shift();
+        this.#waking = (async () => {
+            for (const id of at)
+                await this.standings[id]?.ask(d.method, d.args);
+        })();
+        return { ok: true };
+    }
+    // Which account the bytes are for: the one thing read before they are
+    // verified, since it names whose secret verifies them.
+    account(_body, _headers) {
+        return null;
+    }
+    verify(_body, _headers, _secret) {
+        return false;
+    }
+    decode(_body, _headers) {
+        return { error: 'this faculty is not called in' };
+    }
+    // A signature over text with a shared secret, hex: the shape most vendors
+    // sign in, here once so a leaf writes only the vendor's framing.
+    async hmac(secret, text) {
+        const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+        return [...new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(text)))].map((x) => x.toString(16).padStart(2, '0')).join('');
+    }
+}

package/dist/box/faculty.d.ts

@@ -0,0 +1,68 @@
+import { Lent } from 'nervur';
+import type { Asker, JsonObject, OccupantRecord, Stance } from 'nervur';
+import type { Contract } from './contract.ts';
+import { type Harborage } from './box.ts';
+export type Watched = {
+    by: string;
+    method: string;
+    args: JsonObject;
+};
+export type Woke = {
+    id: string;
+    by: string;
+    out: unknown;
+};
+export declare const HTTP = "http:";
+export declare const INBOUND: {
+    description: string;
+    input: {
+        type: string;
+        properties: {
+            body: {
+                type: string;
+            };
+            headers: {
+                type: string;
+            };
+            query: {
+                type: string;
+            };
+            method: {
+                type: string;
+            };
+        };
+        required: string[];
+    };
+    for: (occ: OccupantRecord | undefined) => boolean;
+};
+export declare const WATCH: {
+    description: string;
+    input: {
+        type: string;
+        properties: {
+            invitation: {
+                type: string;
+            };
+            method: {
+                type: string;
+            };
+            args: {
+                type: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare class Faculty extends Lent {
+    static cells: JsonObject;
+    static fulfils: Contract[];
+    static stands(): boolean;
+    static claims: string[];
+    readonly box: Harborage;
+    constructor(stance: Stance, box?: Harborage);
+    inbound(_args: JsonObject): Promise<JsonObject> | JsonObject;
+    watch(args: JsonObject, asker: Asker): Promise<JsonObject>;
+    protected welcomed(_id: string): Promise<void>;
+    protected woke(round?: (w: Watched) => JsonObject, only?: string): Promise<Woke[] | null>;
+    get watching(): Record<string, Watched>;
+}

package/dist/box/faculty.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: Apache-2.0
+// A faculty: a being of the box ward standing for one thing outside every
+// being. She says everything about herself on her class: the contracts she
+// fulfils, whether she can work on this runtime, and the paths she claims on
+// the box's wire. She is born holding her harbor's box. What every faculty
+// shares is here: `watch`, the one way a being asks to be woken, and
+// `woke`, one round of waking whoever asked.
+import { Lent, isInvitation, isSilence, isWord, wordOf } from 'nervur';
+import { ALONE } from './box.js';
+// The ask the http faculty makes of a faculty that claims a path, and only
+// the http faculty: the root places her one occupant per claimed path,
+// `http:<path>`.
+export const HTTP = 'http:';
+export const INBOUND = {
+    description: 'bytes that arrived on a path this faculty claims',
+    input: { type: 'object', properties: { body: { type: 'string' }, headers: { type: 'object' }, query: { type: 'string' }, method: { type: 'string' } }, required: ['body', 'headers'] },
+    for: (occ) => occ?.id.startsWith(HTTP) === true,
+};
+export const WATCH = {
+    description: 'wake me: an invitation back, the ask to wake me with, and what to add to it',
+    input: { type: 'object', properties: { invitation: { type: 'object' }, method: { type: 'string' }, args: { type: 'object' } }, required: ['invitation', 'method'] },
+};
+export class Faculty extends Lent {
+    static cells = { watched: {}, minted: 0 };
+    // The contracts she fulfils; the box lends her under each one's digest.
+    static fulfils = [];
+    // Whether she can work on the runtime reading this, answered honestly.
+    // One that cannot is never booted and never lent.
+    static stands() {
+        return true;
+    }
+    // The paths on the box's wire she answers. The http faculty hands her the
+    // bytes that arrive on one as `inbound`, and nobody else may ask it.
+    static claims = [];
+    // What her harbor is to her, handed at birth.
+    box;
+    constructor(stance, box = ALONE) {
+        super(stance);
+        this.box = box;
+    }
+    // Bytes on a path she claims: the body as text, the headers, the query and
+    // the method. This body is called in by nobody; a faculty that claims a
+    // path says what the bytes mean.
+    inbound(_args) {
+        return { error: 'this faculty is not called in' };
+    }
+    // Someone wants waking. She hands an invitation back and says what to ask
+    // her; this knocks it, takes it under an id of this being's own, and files
+    // it. The empty ask is the knock, because every being answers one.
+    async watch(args, asker) {
+        const inv = args.invitation;
+        if (!isInvitation(inv) || typeof args.method !== 'string')
+            return { error: 'an invitation and a method' };
+        const extra = args.args;
+        if (extra !== undefined && (extra === null || typeof extra !== 'object' || Array.isArray(extra)))
+            return { error: 'args is one object' };
+        const out = await this.knock(inv);
+        if (isSilence(out) || isWord(out))
+            return { error: 'no way back' };
+        const cells = this.cells;
+        const id = await this.take(`wake:${(cells.minted += 1)}`, inv);
+        if (id === null)
+            return { error: 'not taken' };
+        cells.watched[id] = { by: asker.id ?? '', method: args.method, args: extra ?? {} };
+        await this.welcomed(id);
+        return { watching: id };
+    }
+    // Somebody new is filed, and the answer to her `watch` waits for this. A
+    // faculty that owes a new subscriber something at once says it here.
+    async welcomed(_id) { }
+    // One round. Each subscriber is asked what she asked to be asked, with
+    // whatever this round adds; `only` is one of them. A subscriber who removed
+    // the occupant says `removed` once and her row goes. Null is this being
+    // herself taken out of her ward, so whoever holds an interval puts it down.
+    async woke(round = (w) => w.args, only) {
+        const watched = this.cells.watched;
+        const out = [];
+        for (const [id, w] of Object.entries(watched)) {
+            if (only !== undefined && id !== only)
+                continue;
+            const said = await this.standings[id]?.ask(w.method, round(w));
+            if (said === undefined || (isWord(said) && wordOf(said) === 'dropped'))
+                return null;
+            if (isWord(said) && wordOf(said) === 'removed') {
+                this.standings.remove(id);
+                delete watched[id];
+                continue;
+            }
+            out.push({ id, by: w.by, out: said });
+        }
+        return out;
+    }
+    // Who is waiting, by this being's own id for the relation.
+    get watching() {
+        return this.cells.watched;
+    }
+}

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

@@ -1,4 +1,4 @@
-import type { Ring } from './push.ts';
+import type { Ring } from './ring.ts';
 export type Account = {
     project_id: string;
     client_email: string;

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

@@ -1,5 +1,5 @@
 import { Faculty } from './faculty.ts';
-export declare const GRANTS = "grants";
+export declare const GRANTS: import("nervur").Blueprint;
 export declare const ACCESS_TTL: number;
 export declare const REFRESH_TTL: number;
 export type Grant = {
@@ -25,9 +25,9 @@ export declare class Grants extends Faculty {
         refresh: {};
     };
     static asks: {};
-    persist: () => Promise<void>;
-    now: () => number;
+    static fulfils: import("nervur").Blueprint[];
     get kept(): Kept;
+    now(): number;
     issue(identity: string, ward: string, client: string): Promise<Tokens>;
     refresh(refresh_token: string): Promise<Tokens | null>;
     bearer(req: Request): {
@@ -37,5 +37,6 @@ export declare class Grants extends Faculty {
     revoke(identity: string, ward: string): Promise<void>;
     sweep(): void;
 }
+export type Bearers = Pick<Grants, 'issue' | 'refresh' | 'bearer' | 'revoke' | 'now'>;
 export declare const offered: (req: Request) => string;
 export {};