@nervur-org/dock 0.3.0

package/dist/dock/fcm.js

@@ -0,0 +1,77 @@
+const subtle = () => globalThis.crypto.subtle;
+const RS256 = { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' };
+const b64url = (bytes) => {
+    let binary = '';
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+};
+const utf8 = (v) => new TextEncoder().encode(v);
+const der = (pem) => {
+    const body = pem.replace(/-----(BEGIN|END)[^-]*-----/g, '').replace(/\s+/g, '');
+    if (!body)
+        throw new Error('a service account key is a PKCS#8 PEM');
+    const binary = atob(body);
+    const out = new Uint8Array(binary.length);
+    for (let at = 0; at < binary.length; at += 1)
+        out[at] = binary.charCodeAt(at);
+    return out;
+};
+export function isAccount(v) {
+    const a = v;
+    return a !== null && typeof a === 'object' && typeof a.project_id === 'string' && typeof a.client_email === 'string' && typeof a.private_key === 'string';
+}
+export const DOORS = { oauth: 'https://oauth2.googleapis.com/token', fcm: 'https://fcm.googleapis.com' };
+const SCOPE = 'https://www.googleapis.com/auth/firebase.messaging';
+const LIFE = 59 * 60 * 1000;
+async function access(a, at, held) {
+    const now = Date.now();
+    if (held && now - held.at < LIFE)
+        return held;
+    const key = await subtle().importKey('pkcs8', der(a.private_key), RS256, false, ['sign']);
+    const iat = Math.floor(now / 1000);
+    const head = b64url(utf8(JSON.stringify({ alg: 'RS256', typ: 'JWT' })));
+    const claims = b64url(utf8(JSON.stringify({ iss: a.client_email, scope: SCOPE, aud: at.oauth, iat, exp: iat + 3600 })));
+    const signed = await subtle().sign(RS256, key, utf8(`${head}.${claims}`));
+    const assertion = `${head}.${claims}.${b64url(new Uint8Array(signed))}`;
+    const res = await fetch(at.oauth, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer', assertion }).toString(),
+    });
+    if (!res.ok)
+        throw new Error(`google would not exchange the key: ${res.status} ${(await res.text()).slice(0, 200)}`);
+    const out = (await res.json());
+    if (typeof out.access_token !== 'string')
+        throw new Error('google answered no access token');
+    return { at: now, token: out.access_token };
+}
+// The ground. An `fcm` token is the registration token the device was
+// handed by Google's own sdk, which is opaque and is not inspected here
+// beyond being a string with something in it.
+export function fcmPush(a, at = DOORS) {
+    let held = null;
+    return {
+        async ring(token, sealed) {
+            const device = token.device;
+            if (typeof device !== 'string' || device.length < 8)
+                throw new Error('an fcm token is a registration token');
+            held = await access(a, at, held);
+            // The seal rides in the data map, as it rides in the payload on the
+            // other ground, so what Google carries is ciphertext and the line is
+            // drawn on the device by the service that opens it. A ring with no
+            // seal carries an empty map and is a wake and nothing more, which is
+            // what a device that draws no banner still needs.
+            const res = await fetch(`${at.fcm}/v1/projects/${a.project_id}/messages:send`, {
+                method: 'POST',
+                headers: { authorization: `Bearer ${held.token}`, 'content-type': 'application/json' },
+                body: JSON.stringify({ message: { token: device, android: { priority: 'HIGH' }, data: sealed === undefined ? {} : { sealed } } }),
+            });
+            // 404 is Google saying this registration token is gone. Nothing here
+            // forgets it, for the reason the other two grounds do not: a device
+            // sends a fresh one whenever it comes to the foreground.
+            if (!res.ok)
+                throw new Error(`fcm answered ${res.status} ${(await res.text()).slice(0, 200)}`);
+        },
+    };
+}

package/dist/dock/grants.d.ts

@@ -0,0 +1,41 @@
+import { Faculty } from './faculty.ts';
+export declare const GRANTS = "grants";
+export declare const ACCESS_TTL: number;
+export declare const REFRESH_TTL: number;
+export type Grant = {
+    identity: string;
+    ward: string;
+    client: string;
+    exp: number;
+};
+type Kept = {
+    access: Record<string, Grant>;
+    refresh: Record<string, Grant>;
+};
+export type Tokens = {
+    access_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+    refresh_token: string;
+    scope: 'quo';
+};
+export declare class Grants extends Faculty {
+    static cells: {
+        access: {};
+        refresh: {};
+    };
+    static asks: {};
+    persist: () => Promise<void>;
+    now: () => number;
+    get kept(): Kept;
+    issue(identity: string, ward: string, client: string): Promise<Tokens>;
+    refresh(refresh_token: string): Promise<Tokens | null>;
+    bearer(req: Request): {
+        identity: string;
+        ward: string;
+    } | null;
+    revoke(identity: string, ward: string): Promise<void>;
+    sweep(): void;
+}
+export declare const offered: (req: Request) => string;
+export {};

package/dist/dock/grants.js

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's grants: `grants`, one faculty of the dock ward. A bearer to an
+// identity in a world, honoured on every route alike. A route says the
+// grammar a caller speaks, forms, tools or JSON, and a grant says who the
+// caller is; no route holds a table of its own. She spans every world the
+// box hosts, and a grant maps a token to an identity and nothing else: the
+// credential is the invitation the avatar knocked with, spent once, and a
+// grant only remembers which avatar a client speaks through. No secret of
+// Quo's is ever here.
+//
+// Her tokens are her cells, kept by the dock ward's partition like every
+// faculty's and by no file of her own, so a box has one place its state is
+// and the harbor's one secret wraps them. Issuing, refreshing and revoking
+// are the routes' to call on her in this process, as the daemon mints a
+// nonce on `local`: none is an ask, none crosses a door, and she answers
+// nothing at hers.
+//
+// A grant is issued by whoever finished a way in: the OAuth exchange on the
+// model side, or the api route trading an invitation straight for tokens.
+// An access token lives an hour and a refresh token thirty days, and
+// refresh rotates. Revocation is the user being removing the occupant,
+// and the route that hears `removed` asks for the grants to go with it.
+import { Faculty } from './faculty.js';
+// The name the dock ward holds her under.
+export const GRANTS = 'grants';
+export const ACCESS_TTL = 60 * 60 * 1000; // an access token, one hour
+export const REFRESH_TTL = 30 * 24 * 60 * 60 * 1000; // a refresh token, thirty days
+// A token is a string the far side offers, and a bare lookup would find
+// `__proto__` and hand back an object with no identity. Own keys only.
+const own = (rec, key) => (Object.hasOwn(rec, key) ? rec[key] : undefined);
+// Thirty-two random bytes as base64url, from the web crypto and the base64
+// every runtime has, so nothing of node stands in a file a tab bundles or a
+// worker imports. `Buffer` is not among those: a worker has one only when a
+// deploy asks for node's shims, and the box's grants are the same code on
+// every terrain.
+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 = {};
+    // The ward's save, set by whoever holds her ward: a token issued is a
+    // cell written, and the routes answer with a token the partition keeps.
+    persist = async () => { };
+    // The clock, a suite's to move.
+    now = () => Date.now();
+    get kept() {
+        return this.cells;
+    }
+    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.persist();
+        return { access_token, token_type: 'Bearer', expires_in: ACCESS_TTL / 1000, refresh_token, scope: 'quo' };
+    }
+    // Rotated: the old one is gone with the new one's birth. Null is a token
+    // nobody issued, or one that died.
+    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);
+    }
+    // The bearer on a request, to an identity in a world. Null is a stranger,
+    // or a token that died; a route tells the two apart by whether the
+    // request offered one at all.
+    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;
+    }
+    // Every grant an identity holds in a world, gone: the box's half of
+    // revocation. The other half is the user being removing the occupant.
+    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.persist();
+    }
+    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/dock/http2.d.ts

@@ -0,0 +1,4 @@
+import type { Ring } from './push.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/http2.js

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// Apple, from a Node box. The APNs provider API is HTTP/2 only and refuses
+// HTTP/1.1, and Node's `fetch` speaks HTTP/1.1 alone, so a droplet cannot
+// ring Apple through `apns.ts` at all. This is the same ring over
+// `node:http2`: the same provider token, the same path, the same headers
+// and the same body, which all live in `apns.ts` and are written once,
+// because a phone that is rung two ways must be rung the same way twice.
+//
+// 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`.
+//
+// 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
+// rings more than once. It is kept while it lives, made again when it dies,
+// and unref'd, so an idle bell is not a process that will not exit.
+import { connect } from 'node:http2';
+import { HOSTS, answered, provider, request } from './apns.js';
+// What a Node box holds if it is a bell: the team's key from the portal and
+// which app is being rung. A box holding none is a box that rings no
+// iPhones, which is every box but a bell's.
+export function apnsOf(env) {
+    const { QUO_APNS_KEY: key, QUO_APNS_KEY_ID: keyId, QUO_APNS_TEAM: teamId, QUO_APNS_TOPIC: topic } = env;
+    return key && keyId && teamId && topic ? { key, keyId, teamId, topic } : null;
+}
+// How long a ring waits on Apple before it is a ring that did not leave. A
+// ring that hangs is worse than one that failed: the world behind it is
+// holding an ask open, and a push that is late is a push that is wrong.
+const WITHIN = 10_000;
+export function apnsHttp2(a, at = HOSTS, within = WITHIN) {
+    let made = null;
+    const held = new Map();
+    const session = (host) => {
+        const live = held.get(host);
+        if (live && !live.closed && !live.destroyed)
+            return live;
+        const s = connect(host);
+        const gone = () => {
+            if (held.get(host) === s)
+                held.delete(host);
+        };
+        s.on('error', gone);
+        s.on('close', gone);
+        s.unref();
+        held.set(host, s);
+        return s;
+    };
+    return {
+        async ring(token, sealed) {
+            made = await provider(a, made);
+            const req = request(a, made.jwt, token, sealed);
+            const stream = session(token.sandbox === true ? at.sandbox : at.production).request({ ':method': 'POST', ':path': req.path, ...req.headers });
+            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));
+                stream.on('error', no);
+                stream.on('end', () => ok({ status, text }));
+                stream.end(req.body);
+            });
+            answered(status, text);
+        },
+    };
+}

package/dist/dock/index.d.ts

@@ -0,0 +1,41 @@
+import type { Harbor, Lend } from '@nervur-org/nervur/harbor';
+import { Faculty } from './faculty.ts';
+import { Console } from './console.ts';
+import { Local } from './local.ts';
+import { Location } from './location.ts';
+import { Notifications } from './notifications.ts';
+import { Push } from './push.ts';
+import { Timer } from './timer.ts';
+export { Console, CONSOLE } from './console.ts';
+export { Faculty, join, settled, type Watched, type Woke } from './faculty.ts';
+export { Local, LOCAL } from './local.ts';
+export { Location, type Where } from './location.ts';
+export { Notifications } from './notifications.ts';
+export { Push, isToken, bellOf, banner, sealBanner, SEAL, type Token, type Ring, type Line } from './push.ts';
+export { Timer } from './timer.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 LOCATION = "location";
+export declare const NOTIFICATIONS = "notifications";
+export declare const PUSH = "push";
+export declare const TIMER = "timer";
+export declare const FACULTIES: Record<string, string>;
+export declare const FACULTY_CLASSES: {
+    Console: typeof Console;
+    Local: typeof Local;
+    Location: typeof Location;
+    Notifications: typeof Notifications;
+    Push: typeof Push;
+    Timer: typeof Timer;
+};
+export declare const DOCK = "dock";
+export declare function stand(harbor: Harbor, lent?: Record<string, string>): Promise<Lend>;
+export type Rooted = {
+    ask(method?: string, args?: Record<string, unknown>): Promise<unknown>;
+    save?(): Promise<void>;
+};
+export declare function standOn(ward: Rooted, lent?: Record<string, string>): Promise<Lend>;
+export declare function lending(ward: Rooted): Lend;
+export declare function facultyOf<F extends Faculty>(harbor: Harbor, name: string): F | undefined;

package/dist/dock/index.js

@@ -0,0 +1,113 @@
+import { isInvitation } from '@nervur-org/nervur';
+import { Faculty } from './faculty.js';
+import { Console, CONSOLE } from './console.js';
+import { Local } from './local.js';
+import { Location } from './location.js';
+import { Notifications } from './notifications.js';
+import { Push } from './push.js';
+import { Timer } from './timer.js';
+export { Console, CONSOLE } from './console.js';
+export { Faculty, join, settled } from './faculty.js';
+export { Local, LOCAL } from './local.js';
+export { Location } from './location.js';
+export { Notifications } from './notifications.js';
+export { Push, isToken, bellOf, banner, sealBanner, SEAL } from './push.js';
+export { Timer } from './timer.js';
+// The three grounds the push faculty rings through, and the bell service
+// that holds a publisher's keys: what the box can do, beside the faculty.
+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 names this package lends under. They are conventions of the dock and
+// nothing of Quo's: a name is the harbor's namespace, and a being holds each
+// one under an id of her own choosing.
+export const LOCATION = 'location';
+export const NOTIFICATIONS = 'notifications';
+export const PUSH = 'push';
+export const TIMER = 'timer';
+// The classes every dock ward may hold, by class name. A terrain hands its
+// own subclasses under the same names and the harbor holds those instead.
+// `local` and `grants` are not among them: the box's way in and the box's
+// grants stand only where a terrain serves routes, and that terrain adds
+// them to what it lends. `Grants` is not in this file at all, so that a tab
+// bundling this index carries no route's notion: the terrain that serves
+// routes hands her class to its harbor, as the daemon hands its own push.
+export const FACULTIES = { [LOCATION]: 'Location', [NOTIFICATIONS]: 'Notifications', [PUSH]: 'Push', [TIMER]: 'Timer' };
+export const FACULTY_CLASSES = { Console, Local, Location, Notifications, Push, Timer };
+// The name a harbor keeps its own ward under. It is a ward in every other
+// respect, and this one is never adopted or dropped as a migration: its
+// beings are the box's and die with it.
+export const DOCK = 'dock';
+// Put the dock ward up and answer the `lend` this harbor hands its wards.
+// `lent` says which names this box offers and which class stands for each;
+// a name it does not hold is null, and so is every other kind of no.
+//
+// The harbor keeps this ward's ask pointer rather than handing it out, so it
+// is the root here, and the root may invite on any being of its ward. That
+// is the whole of what `lend` does: it never mints, it asks its own root to.
+export async function stand(harbor, lent = FACULTIES) {
+    const kept = await harbor.store.load(DOCK);
+    const ward = harbor.wards.get(DOCK) ?? (kept ? await harbor.host(DOCK, kept) : await harbor.create(DOCK, CONSOLE));
+    return standOn(ward, lent);
+}
+// The faculties up in a ward already made, and the `lend` that reaches them.
+// Apart from `stand` so a suite can put its own stubs in its own ward and
+// get the same thing a box gets. It is run again at every boot and says the
+// same thing twice without harm: a key already booted is refused, and an
+// invitation on an id already held is null.
+export async function standOn(ward, lent = FACULTIES) {
+    for (const [name, className] of Object.entries(lent))
+        await ward.ask('boot', { key: name, class: className });
+    // The box as one being, carrying what it stood. She is the page a device
+    // that has joined no world shows, and she is placed by the root because
+    // the root is the box: a standing at every faculty, minted and knocked in
+    // one move, as an owner places any relation into a being of its ward.
+    await ward.ask('boot', { key: CONSOLE, class: 'Console' });
+    for (const name of Object.keys(lent)) {
+        const inv = await ward.ask('invite', { being: name, id: `${CONSOLE}:${name}` });
+        if (!isInvitation(inv))
+            continue;
+        await ward.ask('knock', { being: CONSOLE, id: name, invitation: inv });
+    }
+    await ward.save?.();
+    return lending(ward);
+}
+// The root's half alone: a name and a taker in, whether the ward took it out.
+// It never mints; it asks the root of the ward it holds to, which is what a
+// root may do on any being of its ward. And it unmints: a taker that would
+// not take leaves an occupant on that faculty which nobody holds, so the root
+// removes it before answering, and a refused lend costs the box nothing.
+//
+// Any being of the dock ward is lent by her key, not only the ones a terrain
+// stood: the faculties the dock ships are examples, and an estate boots its
+// own into the dock ward, of a class in its own `classes/`, and lends it the
+// same way. A name nobody there answers to is refused at the invite.
+//
+// The id is drawn and never counted. A faculty's occupants are in her cells
+// and outlive the process, so a count that started again at every boot would
+// name, on the first lend after a restart, an id she already holds, and the
+// invite would be refused for the rest of the box's life.
+export function lending(ward) {
+    return async (name, take) => {
+        const id = `lent:${fresh()}`;
+        const out = await ward.ask('invite', { being: name, id });
+        if (!isInvitation(out))
+            return false;
+        const took = await take(out);
+        if (!took)
+            await ward.ask('remove', { being: name, id });
+        await ward.save?.();
+        return took;
+    };
+}
+const fresh = () => Array.from(globalThis.crypto.getRandomValues(new Uint8Array(8)))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+// One faculty of this box, as the device's own code holds it: the object the
+// harbor made, in this process. Not a path around a door, and nothing of it
+// crosses an edge; it is how a device fires its own timer at a moment it
+// names and how a suite reads what a stub recorded.
+export function facultyOf(harbor, name) {
+    return harbor.wards.get(DOCK)?.being(name);
+}

package/dist/dock/local.d.ts

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

package/dist/dock/local.js

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's way in: `local`, one faculty of the dock ward. The daemon saw a
+// process reach a socket only the device's user can open, and that is the
+// whole of the vouch; file permissions are the device's rules, which is what
+// `quo/SPEC.md` allows a harbor to hand the root by.
+//
+// She holds the nonces this box minted, in this process and never in cells:
+// a vouch that outlived a restart would be a vouch for a process that is
+// gone. Each is honoured once, and a `local` proof arriving any other way
+// names no nonce and is refused.
+//
+// The device's own code mints on her directly, as a device fires its own
+// timer: `mint` is not an ask, it crosses no door, and nothing at a door
+// can reach it. The desk asks `verify` at her standing, as she asks any way
+// in.
+import { Faculty } from './faculty.js';
+import { VERIFY } from '../beings/way.js';
+// The name the dock ward lends her under. A box with no local side lends no
+// such name, and the desk there holds no such standing.
+export const LOCAL = 'local';
+export class Local extends Faculty {
+    static asks = { verify: VERIFY };
+    #nonces = new Map();
+    // A nonce for one client this box saw itself, spent by the first proof
+    // that names it. The caller drops it when the admit is over: a nonce that
+    // was never spent is not a way in that stays open.
+    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/location.d.ts

@@ -0,0 +1,19 @@
+import type { JsonObject } from '@nervur-org/nervur';
+import { Faculty } from './faculty.ts';
+export type Where = {
+    lat: number;
+    lng: number;
+    accuracy?: number;
+    at: number;
+};
+export declare class Location extends Faculty {
+    static asks: {
+        where: {
+            description: string;
+            input: {
+                type: string;
+            };
+        };
+    };
+    where(): Promise<JsonObject>;
+}

package/dist/dock/location.js

@@ -0,0 +1,11 @@
+import { Faculty } from './faculty.js';
+export class Location extends Faculty {
+    static asks = {
+        where: { description: 'where this box is', input: { type: 'object' } },
+    };
+    // 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/notifications.d.ts

@@ -0,0 +1,38 @@
+import type { JsonObject } from '@nervur-org/nervur';
+import { Faculty } from './faculty.ts';
+export declare class Notifications extends Faculty {
+    static cells: JsonObject;
+    static asks: {
+        notify: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    title: {
+                        type: string;
+                    };
+                    body: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+        banner: {
+            description: string;
+            input: {
+                type: string;
+            };
+        };
+    };
+    notify(_args: JsonObject): Promise<JsonObject>;
+    key(): Promise<{
+        secret: Uint8Array;
+        pk: Uint8Array;
+    }>;
+    banner(_args: JsonObject): Promise<JsonObject>;
+    protected plant(_pair: {
+        secret: Uint8Array;
+        pk: Uint8Array;
+    }): Promise<void>;
+}

package/dist/dock/notifications.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's notification center: show the human a line. One blueprint, and a
+// body per terrain. The platform's own permission prompt is the first ask's,
+// and a refusal is the error object every ask after it answers.
+//
+// She also keeps the banner key, which is the one key a world seals a
+// notification to. It is the device's, one pair, minted here the first time
+// it is asked for and kept in her cells; the public half is what a device
+// hands a world it admits, and the secret half never leaves the box.
+//
+// It sits here and not in a being of the library's for one reason. On a
+// phone the process that draws a banner is not the app: an extension runs
+// between the platform and the screen, and it must be able to open the seal
+// before anything is shown. So the secret has to reach wherever that
+// terrain's notification process can read it, and putting a key somewhere a
+// platform can find it is the terrain's business, which is what a faculty
+// is. A terrain overrides `plant` and does it its own way; a terrain that
+// has no second process does nothing and the key never leaves these cells.
+//
+// It is not the ward's seed. That one opens everything the person sees and
+// is kept so that it never leaves the device at all. This one opens
+// banners, and if the process that draws them were ever turned against her
+// it would cost her a line of text rather than her world.
+import { arithmetic } from '@nervur-org/nervur/ward';
+import { Faculty } from './faculty.js';
+// 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));
+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' } },
+    };
+    notify(_args) {
+        return Promise.resolve({ error: 'this box shows no notifications' });
+    }
+    // The pair, minted once and kept. Every call after the first is the same
+    // key, because a device that minted a new one on every ask would be a
+    // device whose worlds all seal to a key it has forgotten.
+    async key() {
+        if (typeof this.cells.banner !== 'string') {
+            this.cells.banner = arithmetic.hex(seed());
+            await this.plant(await arithmetic.sealingPair(arithmetic.unhex(this.cells.banner)));
+        }
+        return arithmetic.sealingPair(arithmetic.unhex(this.cells.banner));
+    }
+    async banner(_args) {
+        return { banner: arithmetic.hex((await this.key()).pk) };
+    }
+    // Where this terrain's notification process reads the secret half. The
+    // base plants nothing, which is right for a terrain that draws its own
+    // banners in the same process; a phone overrides it and writes into the
+    // keychain group its extension shares with the app.
+    plant(_pair) {
+        return Promise.resolve();
+    }
+}