@nervur-org/dock 0.3.0

package/dist/human/wake.js

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: Apache-2.0
+// The device's half of the doorbell, worn by every shell: the tab's, the
+// worker's behind a closed tab, and the app's. A ring carries nothing but a
+// sealed line, so waking is three moves and the first two are the harbor's
+// own. The device tells its dialers it is back, since a socket that died
+// while it slept died silently; it asks each relation in each world what it
+// missed, which is an ordinary ask on an ordinary standing, sealed like
+// every other; and it composes what the human sees from the objects that
+// came back, here, on the device, from bytes no push service ever held.
+//
+// Each object lands on the avatar exactly where a push would have landed,
+// so a page that is open shows what it missed in its own notices as well.
+//
+// A phone and a desk hold a doorbell of their own at a bell, and hand the
+// platform's token to that doorbell and to nobody else; what a world is
+// given is a standing at that doorbell and the banner key it seals to. A
+// tab hands its browser endpoint instead and keeps no doorbell, because a
+// browser endpoint is rung only by whoever holds the VAPID secret the
+// subscription was made under, and that secret is the world's own.
+import { isInvitation, isSilence, isWord } from '@nervur-org/nervur';
+import { DOCK, CONSOLE, NOTIFICATIONS, facultyOf } from '../dock/index.js';
+import { banner } from '../dock/push.js';
+import { localName, relations } from './worlds.js';
+// The token a browser's push service hands a page: the endpoint, and the
+// two keys of the subscription made at it. RFC 8291 encrypts a body to
+// those keys, which is how a ring carries the world's own line, so a token
+// without them is a device that is woken and told nothing.
+export const webToken = (endpoint, p256dh, auth) => ({ kind: 'web', endpoint, ...(p256dh && auth ? { p256dh, auth } : {}) });
+// The id this device holds its doorbell under, on the box's own being.
+export const DOORBELL = 'doorbell';
+const said = (out) => (out === undefined || isSilence(out) || isWord(out) || out === null || typeof out !== 'object' || Array.isArray(out) ? null : out);
+// The box's own being, as the device's own code reaches its own object in
+// its own process. Nothing of this crosses an edge.
+const box = (harbor) => harbor.wards.get(DOCK)?.being(CONSOLE);
+// The doorbell this device holds, taken the first time and kept after that.
+// A stranger phone knocks the bell's public being, is booted a doorbell of
+// its own and comes away with the one way in; the standing lives on the
+// box's own being, because a doorbell is the device's and not any world's.
+//
+// Null is a device with no bell behind it, which is what a build that names
+// none looks like and what a bell that will not answer looks like. Each of
+// them works in every other way.
+export async function doorbell(harbor, bell) {
+    if (!bell)
+        return null;
+    const ward = harbor.wards.get(DOCK);
+    const me = box(harbor);
+    if (!ward || !me)
+        return null;
+    if (!me.standings[DOORBELL]) {
+        const hello = said(await me.standings.knock({ ward: bell.pk }, 'hello', {}));
+        const inv = hello?.invitation;
+        if (!isInvitation(inv))
+            return null;
+        // The ward's own knock, which knocks and takes in one act: an
+        // invitation is taken only where it was answered, so the two halves are
+        // never split.
+        const took = said(await ward.ask('knock', { being: CONSOLE, id: DOORBELL, invitation: inv }));
+        await ward.save();
+        if (took?.taken !== DOORBELL)
+            return null;
+    }
+    const mine = me.standings[DOORBELL];
+    if (!mine)
+        return null;
+    return {
+        keep: async (token) => {
+            const out = said(await mine.ask('keep', { token }));
+            await ward.save();
+            return typeof out?.kept === 'string';
+        },
+        admit: async () => {
+            // The banner key is minted on the first ask and kept, and a terrain
+            // whose banners are drawn by a second process plants the secret half
+            // where that process reads it while this is happening.
+            const keys = facultyOf(harbor, NOTIFICATIONS);
+            const key = keys ? said(await keys.banner({}))?.banner : undefined;
+            if (typeof key !== 'string')
+                return null;
+            const out = said(await mine.ask('admit', {}));
+            await ward.save();
+            const inv = out?.invitation;
+            return isInvitation(inv) ? { invitation: inv, banner: key } : null;
+        },
+    };
+}
+// One world told how to wake this device. What a world is given is a
+// standing at this device's doorbell and the banner key it seals to, never
+// the platform's token: the same token at every world is a bearer
+// credential, and a standing is not one.
+//
+// A standing does not rotate, so it is handed over once. The world is asked
+// what it already holds and told nothing when it holds a doorbell, which is
+// what keeps the doorbell's list of the worlds it allows a list a human can
+// read and cut, rather than one row per time a page was opened. A browser
+// endpoint is said every time, because a push service may hand out a new
+// one at any moment and a stale one rings an empty house.
+//
+// A device with no bell behind it and no browser endpoint says nothing, and
+// works in every other way.
+export async function told(rel, at, token) {
+    const has = said(await rel.call('bell', {}));
+    const kept = typeof has?.kept === 'string' ? has.kept : null;
+    if (at) {
+        if (kept === 'doorbell')
+            return kept;
+        const got = await at.admit();
+        if (!got)
+            return null;
+        const out = said(await rel.call('bell', { invitation: got.invitation, banner: got.banner }));
+        return typeof out?.kept === 'string' ? out.kept : null;
+    }
+    if (token?.kind !== 'web')
+        return null;
+    const out = said(await rel.call('bell', { token }));
+    return typeof out?.kept === 'string' ? out.kept : null;
+}
+// The tab's doorbell: the worker registered on this world's origin, whose
+// scope is the folder it is served from and so covers every world page
+// there, and a subscription at whatever push service this browser keeps.
+// The world's key goes over as the base64url string it already is. Null is
+// a device with no doorbell, which is a browser with no push service, a
+// human who was asked and said no, or a human who has not been asked; each
+// of them works in every other way, and the last is why `ask` exists.
+export async function subscribe(web, key, ask = false) {
+    const workers = globalThis.navigator?.serviceWorker;
+    if (!workers || !('PushManager' in globalThis) || !('Notification' in globalThis))
+        return null;
+    try {
+        const registration = await workers.register(`${web}/sw.js`, { type: 'module' });
+        await workers.ready;
+        if (Notification.permission === 'default' && ask)
+            await Notification.requestPermission();
+        if (Notification.permission !== 'granted')
+            return null;
+        const held = await registration.pushManager.getSubscription();
+        const sub = held ?? (await registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: key }));
+        // The keys are read off the subscription as it writes them itself,
+        // base64url, which is the form a world encrypts to.
+        const keys = sub.toJSON().keys;
+        return webToken(sub.endpoint, keys?.p256dh, keys?.auth);
+    }
+    catch {
+        return null; // a browser with no push service behind it: no doorbell, and everything else stands
+    }
+}
+// What every relation in every world here missed, in the order it was
+// pushed, drained and gone. A world this device is not in has no relation
+// and answers nothing.
+export async function drained(harbor, pks) {
+    const out = [];
+    for (const pk of pks) {
+        const ward = harbor.wards.get(localName(pk));
+        if (!ward)
+            continue;
+        for (const rel of relations(ward)) {
+            const got = await rel.avatar.call('missed');
+            const objects = got.missed;
+            if (!Array.isArray(objects))
+                continue;
+            for (const o of objects) {
+                if (o === null || typeof o !== 'object' || Array.isArray(o))
+                    continue;
+                rel.avatar.notify(o); // where the push would have arrived
+                out.push(o);
+            }
+        }
+        await ward.save(); // her keys rotated on that ask, whatever it answered
+    }
+    return out;
+}
+// What the human reads on the lock screen, composed from the objects and
+// from nothing else. It is the same line a world seals into a ring, made
+// here from what actually crossed, and the human is told how many are
+// behind the last one.
+export function notice(objects) {
+    const line = banner(objects[objects.length - 1] ?? {});
+    return { ...line, body: objects.length > 1 ? `${line.body} (and ${objects.length - 1} more)` : line.body };
+}

package/dist/human/web.d.ts

@@ -0,0 +1,33 @@
+import type { Handler } from '../harbor/http.ts';
+import type { Hosted } from '@nervur-org/nervur/harbor';
+import { type Apps } from './apps.ts';
+export type { Apps };
+export type Folder = {
+    wearing(): Promise<{
+        tokens: boolean;
+        fonts: boolean;
+    }>;
+    design(file: string): Promise<Uint8Array<ArrayBuffer> | string | null>;
+    serving(): Promise<boolean>;
+    beings(): Promise<string | null>;
+};
+export declare const BARE_FOLDER: Folder;
+export type WebOptions = {
+    at: {
+        quo: string;
+        web: string;
+    };
+    code: {
+        tab: string;
+        worker: string;
+    };
+    folder?: Folder;
+    apps?: Apps | null;
+    bell?: string | null;
+    shown?: (ward: string) => boolean;
+};
+export declare const TAB_CODE = "tab/index.js";
+export declare const TAB_SOURCE = "tab/index.ts";
+export declare function webRoute(harbor: {
+    wards: ReadonlyMap<string, Hosted>;
+}, o: WebOptions): Handler;

package/dist/human/web.js

@@ -0,0 +1,184 @@
+import { DOCK } from '../dock/index.js';
+import { publicKey } from '../harbor/ward.js';
+import { ANDROID, APPLE, association } from './apps.js';
+import { door } from './door.js';
+import { BARE, CSS } from './style.js';
+// A world with nothing beside its wards: no design, no code of its own. It
+// is what a terrain hands the route when it holds no folder at all.
+export const BARE_FOLDER = {
+    wearing: () => Promise.resolve({ tokens: false, fonts: false }),
+    design: () => Promise.resolve(null),
+    serving: () => Promise.resolve(false),
+    beings: () => Promise.resolve(null),
+};
+// The paths under `/web` that are the exchange's, never a ward's name.
+const RESERVED_PATHS = new Set(['allow', 'tab.js', 'beings.js', 'sw.js', 'design', '.well-known']);
+// The design a world wears: `design/` in the harbor folder, the compiled
+// face of one design and the fonts it speaks in, served under this route
+// and linked by every page after the kit. A harbor with none wears the
+// kit's own face. Only these files, by these names, and nothing else in
+// the folder is reachable.
+const DESIGN = 'design';
+const DESIGN_FILES = { 'tokens.css': 'text/css; charset=utf-8', 'fonts.css': 'text/css; charset=utf-8' };
+const FONT = /^fonts\/[\w.-]+\.woff2$/;
+// The origins a Quo app's webview speaks from: Tauri's on the desk,
+// Capacitor's on iOS, and the plain loopback Android's webview uses. They
+// are the only origins a world tells its config to, and the fetch is a
+// plain GET asking for JSON, which no browser preflights.
+const APP_ORIGINS = new Set(['tauri://localhost', 'capacitor://localhost', 'http://localhost', 'https://localhost']);
+const appAsking = (req) => {
+    const origin = req.headers.get('origin');
+    if (origin === null || !APP_ORIGINS.has(origin))
+        return null;
+    return (req.headers.get('accept') ?? '').includes('application/json') ? origin : null;
+};
+// The world's code for the tab: a module in the harbor folder, the twin of
+// `classes/index.ts`, exporting by name the classes the tab boots into its
+// local ward for a world of this harbor. Served bundled as `beings.js` on
+// this origin, and one origin is one world's code. It is a built file: the
+// estate that deploys this harbor bundles its own tab source and puts the
+// result in the folder, because nothing here runs a compiler.
+export const TAB_CODE = 'tab/index.js';
+// The source that built file comes from. It is named here for one reason:
+// a folder holding it and no built file has a build that did not run, and
+// that is said at the path rather than passed over in silence.
+export const TAB_SOURCE = 'tab/index.ts';
+export function webRoute(harbor, o) {
+    const folder = o.folder ?? BARE_FOLDER;
+    const quoOrigin = (() => {
+        try {
+            const u = new URL(o.at.quo);
+            return `${u.origin} ${u.origin.replace(/^http/, 'ws')}`;
+        }
+        catch {
+            return '';
+        }
+    })();
+    const host = (() => {
+        try {
+            return new URL(o.at.web).host;
+        }
+        catch {
+            return o.at.web;
+        }
+    })();
+    // `worker-src` is named because it falls back to `default-src`, which is
+    // none: without it the page's own service worker, the ear that hears the
+    // doorbell while the tab is closed, is refused by the policy.
+    const policy = `default-src 'none'; script-src 'self'; worker-src 'self'; style-src 'self' 'unsafe-inline'; font-src 'self'; img-src 'self' data:; connect-src 'self' ${quoOrigin}; form-action 'self'; base-uri 'none'; frame-ancestors 'none'`;
+    const design = async () => {
+        const worn = await folder.wearing();
+        if (!worn.tokens)
+            return `<style>${CSS}</style>`;
+        const fonts = worn.fonts ? `<link rel="stylesheet" href="${o.at.web}/${DESIGN}/fonts.css">` : '';
+        return `<style>${BARE}</style>${fonts}<link rel="stylesheet" href="${o.at.web}/${DESIGN}/tokens.css">`;
+    };
+    const shell = async (body) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>quo</title>
+${await design()}
+</head><body>${body}</body></html>`;
+    const esc = (v) => v.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
+    const html = async (status, body) => new Response(await shell(body), { status, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': policy, 'referrer-policy': 'no-referrer' } });
+    // Each ward is asked which being it marks public: the harbor reads no
+    // partition and the mark is the ward's, so the config a page is handed is
+    // built from describes, one per world on this harbor.
+    // The box's own ward is not a world and is never offered as one: its
+    // beings are the harbor's, reached by `lend` from this box alone, and a
+    // page that listed it would be offering a stranger a device's own things.
+    // A ward is at its door for a stranger's page only when it is shown: the
+    // public being still answers a proof and a link still knocks, but a hidden
+    // ward's page is the plain door page and its root line is not written.
+    const shown = o.shown ?? (() => true);
+    const wards = async () => Object.fromEntries(await Promise.all([...harbor.wards].filter(([n]) => n !== DOCK).map(async ([n, h]) => [n, { pk: h.pk, public: shown(n) && (await publicKey(h)) !== null }])));
+    const config = async (ward, being) => ({ quo: o.at.quo, web: o.at.web, wards: await wards(), beings: await folder.serving(), ...(o.bell ? { bell: o.bell } : {}), ...(ward ? { ward } : {}), ...(being ? { being } : {}) });
+    const tab = async (ward, being) => {
+        return `<script id="quo" type="application/json">${JSON.stringify(await config(ward, being)).replace(/</g, '\\u003c')}</script><script type="module" src="${o.at.web}/tab.js"></script>`;
+    };
+    // The same config the tab is handed in its page, for an app that is not a
+    // tab: it learns a world by this one fetch and never loads the bundle,
+    // because its code is its own bundle and a world's code never runs on a
+    // phone. Only the app origins are answered, and only this; a browser on
+    // any other origin is told nothing, and gets the page instead.
+    const asJson = async (origin, ward) => new Response(JSON.stringify(await config(ward)), { headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'access-control-allow-origin': origin, vary: 'origin' } });
+    return async (req, rest) => {
+        const parts = rest.split('/').filter(Boolean);
+        if (req.method === 'GET' && (rest === '' || rest === '/')) {
+            // the harbor's own config, every ward on it: an app that was sent a
+            // link into a ward it does not know learns the whole harbor at once
+            const app = appAsking(req);
+            if (app !== null)
+                return asJson(app);
+            const open = [];
+            for (const [n, h] of harbor.wards) {
+                const key = shown(n) ? await publicKey(h) : null;
+                if (key !== null)
+                    open.push(`<li class="nv-item nv-person"><span class="nv-avatar">${esc(n.charAt(0).toUpperCase())}</span><div class="nv-stack"><p class="nv-t-body"><a href="${o.at.web}/${encodeURIComponent(n)}">${esc(n)}</a></p><p class="nv-t-quiet">${esc(key)} at the door · <span class="nv-key">${h.pk.slice(0, 16)}…</span></p></div></li>`);
+            }
+            const list = open.join('');
+            return html(200, `${list ? `<main data-door><div class="nv-hero"><h1 class="nv-t-title">worlds</h1><p class="nv-t-lead">The worlds on this box that show a face. Each is entered by a link someone sends you.</p><ul class="nv-list" role="list">${list}</ul></div></main>` : door({ host })}${await tab()}`);
+        }
+        // Where the two platforms look before they let an app claim this
+        // hostname's links. The estate names its apps and nothing else is
+        // decided here: the file is the claim, the platform verifies it over
+        // TLS, and a hostname that names no app is a hostname whose links open
+        // the tab. The exchange page is not the app's on purpose: a credential
+        // exchange belongs in the browser that started it.
+        if (req.method === 'GET' && (rest === APPLE || rest === ANDROID)) {
+            const body = association(o.apps, rest, ['/allow*']);
+            if (body === null)
+                return undefined;
+            return new Response(body, { headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' } });
+        }
+        if (rest === '/tab.js' && req.method === 'GET')
+            return new Response(o.code.tab, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' } });
+        // The service worker: the page's ear while the page is closed. It is
+        // served from the root of this route so that its scope covers every
+        // world's page, and its config is written above the bundle, since a
+        // worker has no page to be handed a JSON script in. A world with no
+        // doorbell serves no worker, and its pages register none.
+        if (rest === '/sw.js' && req.method === 'GET') {
+            if (!o.bell)
+                return undefined;
+            const said = `self.quo=${JSON.stringify(await config()).replace(/</g, '\\u003c')};\n${o.code.worker}`;
+            return new Response(said, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store', 'service-worker-allowed': '/' } });
+        }
+        // the design this world wears, when the harbor folder holds one: its
+        // stylesheet, its font faces, and the font files those name
+        if (rest.startsWith(`/${DESIGN}/`) && req.method === 'GET') {
+            const file = rest.slice(DESIGN.length + 2);
+            const type = DESIGN_FILES[file] ?? (FONT.test(file) ? 'font/woff2' : null);
+            if (type === null)
+                return undefined;
+            const bytes = await folder.design(file);
+            if (bytes === null)
+                return undefined;
+            return new Response(bytes, { headers: { 'content-type': type, 'cache-control': 'public, max-age=86400' } });
+        }
+        // the world's code for the tab, when the harbor folder holds any; a
+        // harbor with none has no such path. A folder holding the source and no
+        // built file is a build that did not run, and the page is told so here
+        // rather than quietly booting a world with no classes in it.
+        if (rest === '/beings.js' && req.method === 'GET') {
+            if (!(await folder.serving()))
+                return undefined;
+            const own = await folder.beings();
+            if (own === null)
+                return new Response(`this world holds ${TAB_SOURCE} and no built ${TAB_CODE}; whoever deploys it emits that file`, { status: 500, headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' } });
+            return new Response(own, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' } });
+        }
+        const wardName = parts[0] ?? '';
+        if (!wardName || RESERVED_PATHS.has(wardName))
+            return undefined;
+        const hosted = harbor.wards.get(wardName);
+        if (!hosted)
+            return html(404, `<h1>no such world</h1><p>no ward named ${esc(wardName)} on this harbor.</p>`);
+        if (parts.length === 1 && req.method === 'GET') {
+            const app = appAsking(req);
+            return app === null ? html(200, await tab(wardName)) : asJson(app, wardName);
+        }
+        // a being's page: one standing the user being carries, by its id, as the whole page. No router:
+        // the path is a key, and the tab paints nothing for a key her describe does not carry
+        if (parts.length === 2 && req.method === 'GET' && /^[\w.-]{1,80}$/.test(parts[1]))
+            return html(200, await tab(wardName, parts[1]));
+        return undefined;
+    };
+}