@nervur-org/dock 0.3.0

package/beings/look.ts

@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: Apache-2.0
+// A look: what a being may say about how she is presented, as values and
+// no more. One optional ask, `look`, answers it, and every side reads the
+// part it understands: a screen reads the tokens and paints her section, a
+// model side reads the hints per ask and writes them as tool annotations.
+// Nothing here is capability, so nothing here is in a blueprint or a digest,
+// and Quo never sees it. The vocabulary is closed: a token that is not
+// listed does not exist, and one that fails its shape is dropped, not
+// fixed. A being cannot paint outside her section, and she cannot reach a
+// server through a look: no token carries a stylesheet or code, an image is
+// a data URI, and the one token that names places, `stands`, is inert. It
+// is a list of origins a side reads to decide whether to vouch for an
+// address the being's own page named, and nothing in the dock ever fetches
+// one.
+import type { Blueprint, Json } from '@nervur-org/nervur';
+
+// What a side may do with one ask. `title` is a human label instead of the
+// name; `readOnly` says the ask changes nothing, so a screen may run it on
+// its own and a model side marks it so; `destructive` asks for care;
+// `idempotent` says asking twice is asking once; `icon` is one short string
+// for a button. A being who marks an ask read-only and then writes has lied
+// to her own page, and nothing enforces it, the way nothing enforces that
+// her empty ask is safe to repeat.
+export type Hint = { title?: string; readOnly?: boolean; destructive?: boolean; idempotent?: boolean; icon?: string };
+export type Look = {
+  name?: string;
+  logo?: string; // an image as a data URI, never a URL
+  accent?: string; // hex colours
+  background?: string;
+  foreground?: string;
+  font?: string; // a font stack, plain characters
+  radius?: number; // 0 to 40, in px
+  order?: string[]; // her asks in the order she wants them shown
+  asks?: Record<string, Hint>;
+  // The origins this being stands in for. An envoy speaks for a vendor
+  // whose pages are that vendor's own, so a human she sends to a checkout
+  // or a consent screen is going somewhere the being's own world does not
+  // serve. She says here which places those are, once, in her look rather
+  // than in an answer: a look is asked once per digest and is the same for
+  // every answer she gives, so what she stands in for is a standing claim a
+  // human could be shown, and never a place that changes under one reply.
+  // A side vouches for an address on her page when its origin is in this
+  // list or is the world's own, and shows any other address as words.
+  stands?: string[];
+};
+
+const COLOUR = /^#[0-9a-fA-F]{3,8}$/;
+const FONT = /^[\w\s,'"-]{1,80}$/;
+const LOGO = /^data:image\/(svg\+xml|png|jpeg|webp);base64,[A-Za-z0-9+/=]{1,40000}$/;
+const NAME = /^[^<>&]{1,60}$/;
+const ICON = /^[^<>&"']{1,8}$/;
+const STANDS = 8; // origins a being may stand in for
+const ORIGIN = 200; // characters one of them may be
+
+const str = (v: Json | undefined, re: RegExp): string | undefined => (typeof v === 'string' && re.test(v) ? v : undefined);
+
+// The look as a side may use it: every token held to its shape, everything
+// else gone. A value that is not an object is no look at all.
+export function sanitise(v: Json | undefined): Look {
+  if (v === null || v === undefined || typeof v !== 'object' || Array.isArray(v)) return {};
+  const l: Look = {};
+  const name = str(v.name, NAME);
+  if (name !== undefined) l.name = name;
+  const logo = str(v.logo, LOGO);
+  if (logo !== undefined) l.logo = logo;
+  for (const k of ['accent', 'background', 'foreground'] as const) {
+    const c = str(v[k], COLOUR);
+    if (c !== undefined) l[k] = c;
+  }
+  const font = str(v.font, FONT);
+  if (font !== undefined) l.font = font;
+  if (typeof v.radius === 'number' && Number.isFinite(v.radius) && v.radius >= 0 && v.radius <= 40) l.radius = Math.round(v.radius);
+  if (Array.isArray(v.order)) l.order = v.order.filter((x): x is string => typeof x === 'string');
+  if (Array.isArray(v.stands)) {
+    // An origin and never a page: whatever she writes is parsed and reduced
+    // to its scheme, host and port, so a path, a query or a fragment she
+    // put there cannot narrow what a side vouches for into something a
+    // reader would misjudge. Bounded, because a list nobody could read is a
+    // list nobody can check.
+    const stands: string[] = [];
+    for (const x of v.stands.slice(0, STANDS)) {
+      if (typeof x !== 'string' || x.length > ORIGIN) continue;
+      try {
+        const u = new URL(x);
+        if ((u.protocol === 'https:' || u.protocol === 'http:') && !stands.includes(u.origin)) stands.push(u.origin);
+      } catch {
+        /* not an origin */
+      }
+    }
+    if (stands.length) l.stands = stands;
+  }
+  if (v.asks !== null && typeof v.asks === 'object' && !Array.isArray(v.asks)) {
+    const asks: Record<string, Hint> = {};
+    for (const [ask, h] of Object.entries(v.asks)) {
+      if (h === null || typeof h !== 'object' || Array.isArray(h)) continue;
+      const hint: Hint = {};
+      const title = str(h.title, NAME);
+      if (title !== undefined) hint.title = title;
+      const icon = str(h.icon, ICON);
+      if (icon !== undefined) hint.icon = icon;
+      for (const k of ['readOnly', 'destructive', 'idempotent'] as const) if (typeof h[k] === 'boolean') hint[k] = h[k];
+      if (Object.keys(hint).length) asks[ask] = hint;
+    }
+    if (Object.keys(asks).length) l.asks = asks;
+  }
+  return l;
+}
+
+// The one hint a side reads first: whether this ask is in the look at all.
+export const hint = (l: Look | undefined, name: string): Hint => l?.asks?.[name] ?? {};
+
+// A carrier's notes say which asks are a standing's, how she looks, and
+// which carried ask is her page: `standings: { id: { asks: [name], look?,
+// page? } }`. Every side reads them here.
+export type Group = { asks?: string[]; look?: Json; page?: string };
+export function groups(bp: Blueprint | null): Record<string, Group> {
+  const n = bp?.notes;
+  const g = n !== null && n !== undefined && typeof n === 'object' && !Array.isArray(n) ? n.standings : undefined;
+  return g !== null && g !== undefined && typeof g === 'object' && !Array.isArray(g) ? (g as Record<string, Group>) : {};
+}
+
+// The asks that are presentation and never a form nor a tool: her look, her
+// page, and the page of every standing she carries, named in her notes.
+export function presentation(bp: Blueprint | null): Set<string> {
+  const p = new Set(['look', 'page']);
+  for (const g of Object.values(groups(bp))) if (typeof g.page === 'string') p.add(g.page);
+  return p;
+}
+
+// The hint for one ask, hers or a standing's: a carried ask is looked up
+// under its bare name in that standing's look.
+export function hintFor(bp: Blueprint | null, mine: Look, name: string): Hint {
+  for (const [id, g] of Object.entries(groups(bp))) {
+    if (!g.asks?.includes(name)) continue;
+    const prefix = `${id}-`;
+    return hint(sanitise(g.look), name.startsWith(prefix) ? name.slice(prefix.length) : name);
+  }
+  return hint(mine, name);
+}

package/beings/porter.ts

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

package/beings/presence.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+// The presence being: the being of a world who lives on a device. She is
+// an avatar, one standing at the world's user being and a side for whoever
+// is at the screen, and she is the device's face to that world. At her
+// birth she lends every name the box lends and holds each as a standing
+// named for the faculty; a name the box does not lend is simply not held.
+// She carries those standings, so the user being who holds a way back to
+// her sees `location-where` and `notifications-notify` in her describe and
+// asks them in her name, and the phone is reached by asking her and never
+// by holding anything of the box.
+//
+// She asks again at every birth, since a restart and a move are one event
+// to her, and birth is synchronous while taking a standing is not, so what
+// she holds is settled after her constructor returns; the terrain waits on
+// `settled` before it says the box is up.
+import type { Asker, OccupantRecord, Stance } from '@nervur-org/nervur';
+import { Avatar, PUSHER, USER } from './avatar.ts';
+import { FACULTIES, join } from '../dock/index.ts';
+
+export class Presence extends Avatar {
+  // Her world's user being sees the box, and nobody else: the way back she
+  // handed over at the join is the one occupant who may ask through her.
+  static override carries(occupant: OccupantRecord | undefined, _asker: Asker): boolean {
+    return occupant?.id === PUSHER;
+  }
+  // Her standing at the user being is hers to speak through and never to
+  // carry: the user being carries her, so carrying it back would be a
+  // loop, and it is the one standing that is not a faculty.
+  static override skips(id: string): boolean {
+    return id === USER;
+  }
+
+  // Which names the box lent her, by name, settled after birth.
+  readonly lent: Promise<Record<string, string | null>>;
+  constructor(stance: Stance) {
+    super(stance);
+    this.lent = Promise.all(Object.keys(FACULTIES).map(async (name) => [name, await join(this, name)] as const)).then((all) => Object.fromEntries(all));
+  }
+}

package/beings/quo-app-bells.md

@@ -0,0 +1,280 @@
+# The bells of a Quo app
+
+A ward on a dialer is reachable only while it holds a line. A closed tab, a
+phone asleep, an app in the background: the world has something to say and
+nobody is listening. The bell is how such a device is reached, the one way
+its platform allows, by waking it.
+
+Everything here is four pieces, and none of them is any publisher's. An
+adopter who ships their own Quo app under their own name runs the same four
+with their own keys, changes nothing in the library and nothing in the dock,
+and is not asking anyone's permission.
+
+## Why a service exists at all
+
+Apple and Google accept a push only when it is signed with the key of the
+team that published the app. A world's box holds no such key and never
+will, because the key belongs to whoever publishes the app and to nobody
+else. So a world hands the ring on to a service that publisher runs.
+
+This is the one place in Quo where a world does not reach a person
+directly, and it is not a design choice. It is the platform's rule, and the
+whole of this paper is about making that hop carry as little as it possibly
+can.
+
+Web Push needs no service. A world mints its own keypair and speaks to the
+browser's push service itself, so tabs and desks are free of this entirely.
+
+## The porter
+
+A bell is a ward, and its public being is the porter. A phone nobody knows
+arrives at her as `{}`, which is the one place in Quo a stranger is
+answered by design.
+
+She does one thing. A device says hello, she brings a doorbell into being
+for it, and hands back the way in. The device knocks, and from then on it is
+a named occupant with a heir and a count, which is where anything that must
+happen once belongs. Her own answer is safe to repeat, as a public being's
+must be: saying hello twice is two doorbells and no harm.
+
+A stranger who keeps knocking is the harbor's, never hers and never the
+door's. A bell needs no attestation, no account and no door of its own
+invention, and it should have none.
+
+## The doorbell
+
+One being per device. Two things live in it.
+
+**The platform token**, in her cells, written by the device and read by
+nobody. It leaves for nowhere. No world ever sees it, so no world can copy
+it, hand it on, or keep ringing after it is told to stop. When the platform
+hands the phone a new token, the phone writes it here once and not one world
+is told anything.
+
+**One occupant per allowed world.** The device asks the doorbell for a way
+in, hands it to a world it has joined, and that world knocks and holds an
+ordinary standing. That row is the whole of the permission, and it is held
+at the bell, by neither the world that rings nor the publisher who holds the
+key.
+
+So the pair is recorded independently: this device, that world. A device
+with presence in many worlds has many rows here, and every one of them
+stands or falls on its own.
+
+## Allowing and disallowing
+
+**Allowing is an invitation the device mints.** A world can only ring a
+phone that chose it. There is no list of approved worlds anywhere, and there
+must not be: gating it would make the publisher the gatekeeper of every
+world's relation with its own member, which is the thing Quo exists to
+abolish, and it buys nothing, because the consent is already there in the
+act of handing over the invitation.
+
+**Disallowing is `remove`.** One occupant goes. The heir is forgotten and
+its last keys are kept apart, bounded, so that world hears `removed` once at
+the door and nobody else hears a thing. Her other worlds are untouched. It
+takes effect at the bell, so it does not depend on the removed world being
+honest about it, and there is nothing it could have kept that would still
+work.
+
+## What a ring carries
+
+A world rings its standing. It names no device, no token and no world,
+because the doorbell reads both ends from the standing the ask arrived on.
+There is nothing in a ring to forge.
+
+It carries one thing: a payload sealed to the device's own key. Not to the
+bell's, not to the world's, not to anyone else's. The bell passes ciphertext
+it could not read if it tried, the platform carries ciphertext, and on the
+device a notification service extension unseals it before the banner is
+drawn. What the person sees is an ordinary, immediate notification.
+
+So the claim is not that the doorbell carries nothing. It is that the
+doorbell carries nothing anyone but her device can read, which is the
+stronger promise, because the weaker one bought its purity with the banner
+itself: a notification composed after the app wakes is one the platform may
+delay at its own discretion and one a person who force quit the app never
+sees at all.
+
+The payload is bounded by what the platform will carry, four kilobytes on
+APNs, and the doorbell refuses a seal that will not fit rather than letting
+a platform nobody is reading refuse it two hops later.
+
+Web Push carries the same line and seals it once rather than twice. The
+standard encrypts a body to keys only that browser holds, so the only party
+a banner key would hide it from is the push service, which that encryption
+already excludes. A second seal would buy nothing and would make every tab
+keep a banner key for it. So a world encrypts the line itself, the browser
+opens it, and the worker shows what it was handed.
+
+## Where a bell runs
+
+Anywhere a harbor runs, and it is the same bell. A bell is a ward: the
+porter, a doorbell per device, and the push faculty of the ward it stands
+on. Nothing in it knows a platform.
+
+What differs is one thing, and it is the thing a faculty is for. The
+faculty's rings are built by the terrain out of what that terrain has: a
+worker's `fetch` speaks HTTP/2 and an edge bell rings APNs with it, a
+droplet speaks it with `node:http2` and rings the same service, and a
+terrain with neither holds no `apns` ring and says so. A publisher who
+starts on a worker and moves to a box moves the ward, keeps its pk, and
+neither a device's standing nor a world's is disturbed.
+
+So the edge is a convenience and never a requirement. It is a good first
+home because a bell keeps almost nothing and must answer whenever any world
+rings, and that is all it is.
+
+## Nothing is configured
+
+A bell has no configuration file and wants none. What it holds, it holds the
+way every being holds anything.
+
+- **Who may ring** is an occupant, invited by the device.
+- **What is rung** is a token in a doorbell's cells, written by the device.
+- **Which service a world hands a ring to** is a cell on the push faculty,
+  set by the root, because whose service it is belongs to an estate and not
+  to a world.
+- **The platform keys** are the terrain's secrets and reach the faculty as
+  its rings are built, never a file in a tree and never a cell.
+
+Rotation is the same answer twice. A heir rotates as it speaks, which is
+Quo's and needs nobody. A platform token rotates by the device writing it
+once, and because no world was ever given one, no world is told.
+
+## The banner key
+
+A world seals to a key that opens banners and nothing else.
+
+It is the device's, one pair, and it lives in the cells of the box's
+notifications faculty, which is the being that shows a human a line. That is
+the source of truth and the only place the pair is kept. The public half
+goes to a world when the device admits it, beside the invitation to the
+doorbell. The secret half never leaves the device.
+
+Where a platform's own notification process can read it is the faculty's
+business, and this is the whole reason the key sits there rather than in a
+being of the library's. On a phone the extension that draws the banner is a
+second process, so the faculty puts the secret in the keychain group it
+shares with it. On a desk and in a tab the terrain has its own answer. A
+faculty is the terrain's hand, and a key that must be reachable by the
+platform belongs in the hand and not in the library.
+
+A tab keeps none. Web Push is encrypted to the subscription's own keys and
+a browser draws its own banners in its own worker, so there is neither a
+second process to reach nor a second seal to open.
+
+Minting the key is where the person is asked. A device that has just minted
+one is a device about to be rung, and the ring that carries a banner is an
+alert the platform draws for nobody who has not allowed it. Registering for
+the doorbell asked for nothing, deliberately, because a doorbell displays
+nothing; so the phone asks in the same act as it plants the key, and a
+refusal costs the line and not the wake. The key stays where it is, the
+world is admitted, and what arrives is a push the person reads when she
+opens the app.
+
+It is not the ward's own key, and that is deliberate. The ward's seed opens
+everything the person sees and is kept so that it never leaves the device at
+all. A banner key opens banners. If the process that draws notifications
+were ever turned against her, the second loses her a line of text and the
+first would lose her the world.
+
+## What a bell knows, and what it cannot
+
+It knows which device, which world, and when. It cannot know what was said.
+
+That is the honest accounting, and the design holds it to the minimum: keep
+counters and no log of rings, name a doorbell by nothing that identifies a
+person, and hold occupants as keys with no world's name beside them. A bell
+that kept more would be a registry of worlds, and the app exists not to have
+one.
+
+The publisher cannot add a world to a device's doorbell. Only the device
+can, because only the device holds the standing that mints a way in. The
+list is held at the bell and it is not the bell's to write.
+
+## The three kinds
+
+**Web.** A world mints its own keypair and rings the browser's push service
+itself. The line rides in the ring, encrypted end to end by the standard to
+the two keys of that subscription, no bell is involved, and no banner key is
+wanted.
+
+**iOS.** APNs, signed under the publisher's key, spoken over HTTP/2. The
+service extension is what makes a sealed payload into a banner, and it needs
+the device's key reachable from a second process.
+
+**Android.** The same shape under FCM, with a data message the app composes
+from.
+
+A bell that holds no key for a kind says so to whoever rings that kind,
+which is what a publisher who rings no Android phones says to an Android
+phone. It does not pretend it rang.
+
+## What this refuses
+
+- **An account at the bell.** The standing is the identity. An account would
+  be the registry of worlds, and there is no third thing it would buy.
+- **Approving worlds.** The device approves. Nobody else is asked.
+- **A token that travels.** The moment a world holds one, disallowing is a
+  request rather than a fact.
+- **A payload the bell can read.** Including one it merely promises not to.
+- **A configuration file.** A bell is occupants, standings and cells. A
+  second place to say who may ring would be a second answer to a question
+  that already has one.
+- **A terrain in the design.** Edge or droplet is where the ward sleeps, and
+  a bell that worked one way on one and another way on the other would be
+  two bells.
+- **Anything publisher-specific in the packages.** Team ids, bundle ids, a
+  bell's address and a push key are an estate's, carried in by its
+  environment. What is published is the porter, the doorbell, the faculty
+  and the service, and they name nobody.
+
+## Where the tree stands
+
+The one place under this paper where a gap between it and the code is named.
+
+Each of the three grounds has drawn a line on a screen, and each in the
+shape this paper gives it. On an iPhone the app minted its banner key,
+planted the secret half where the extension reads it, took a device token
+from Apple, and a ring under the team's own key carried a hundred and
+thirty bytes of ciphertext that the extension opened. On Android the ring
+carried an empty data map and the device composed the line itself. In a
+real Chrome the world found the tab unreachable, rang its subscription, and
+the worker drew what it was handed.
+
+- **A simulator draws no sealed banner**, because it runs no notification
+  service extension at all. It proves everything on either side of that
+  move: the pair minted and kept across a reinstall, the secret half
+  planted, and the seal opened by the extension's own code against a
+  payload a world sealed to that device. The move itself is an iPhone's.
+- **A browser wants a real one.** The Chromium a bench drives answers
+  `showNotification` neither way, so the line that draws it is the one line
+  no test here runs. A browser also asks the human with a button and never
+  on load, so the permission is a click and no suite can spring it.
+- **Android is pointed at a Firebase project by a file a build carries**
+  and the tree ignores, since the file holds a key. The project is the
+  publisher's own and holds the one app it ships. Its id is minted once and
+  never moves, so a project opened for something else keeps that name for
+  as long as it lives, which is a thing to know before opening one.
+- **The ring on real hardware holds past the first.** A phone with the app
+  backgrounded draws the banner, and so does one locked with the screen
+  off. Five rings two seconds apart all arrived, in order, none coalesced
+  and none dropped, so the platform throttles nothing at that rate. And a
+  ring lands after a full power cycle on an app that has not run since the
+  device booted, which is custody at its strongest: the doorbell standing
+  and the banner key are both kept, and nothing has to be launched to
+  receive. A background push reaches no app the human force quit, by
+  Apple's rule, so a phone under test is backgrounded and not closed.
+- **An Android device reaches its bell over `wss` and never `ws`.** The
+  shell is served from `https://localhost` there, and that ground's WebView
+  refuses a cleartext socket from an HTTPS page as mixed content, so a bell
+  on a bare address on the same network cannot be dialled at all and the
+  device comes away with no doorbell. A phone's WebView on the other ground
+  allows it. So a bell under test wants a real name and a certificate,
+  where the other ground is content with an address on the wire.
+- **A ring costs about 290ms on the box side**, measured from the ask to
+  the answer that comes back only once the bell has handed it to Apple and
+  Apple has taken it. It is steady under a burst: five rings measured 291,
+  294, 291, 295 and 295. What the platform then does with it before a
+  screen lights is the platform's and is not ours to measure.