@nervur-org/dock 0.3.0

package/dock/agents.ts

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's agents: `agents`, one faculty of the dock ward, standing for the
+// one thing a box does on an event as the timer does on a moment: run a
+// process. What she holds is the table of agents, in her cells and in no
+// file, placed by the root with `keep` the way a schedule is placed on the
+// clock, so a box has one place its state is and the daemon reads no recipe.
+//
+// A row names a client identity, the ward she is admitted into, and what
+// runs for her, one of two: a process, a command with its args in its
+// folder, or a model that speaks function calling, a base URL and a model
+// name, OpenRouter, LM Studio, anything with a tools array. At her birth
+// on a daemon she admits each identity into its ward as an avatar, through
+// the box's own way in, and stands the side her row says over that avatar.
+// A push from the user being is the event either way: the agent side runs
+// the command with it and reports what it printed; the runner side turns it
+// into a turn of the model's conversation with her describe as tools. The
+// queue is in the avatar's cells, so it survives a restart; the row is in
+// hers, so the agent comes back with the box.
+//
+// The daemon hands her how to run a row, as it hands the grants faculty how
+// to persist: running an agent is admitting through a socket only a daemon
+// has, and this file is not in the dock's index, since a tab has no process
+// to spawn. A box with no runner keeps the table and runs nobody.
+import { OWNER } from '@nervur-org/nervur';
+import type { Asker, JsonObject, OccupantRecord } from '@nervur-org/nervur';
+import { Faculty } from './faculty.ts';
+
+// The name the dock ward holds her under.
+export const AGENTS = 'agents';
+
+// One agent. `id` is the client identity the avatar is known by in her ward.
+// A process row and a model row, told apart by what they name.
+export type Process = { command: string; args: string[]; dir: string };
+export type Model = { url: string; model: string; key?: string; turns?: number };
+export type Row = { id: string; ward: string } & (Process | Model);
+export const isProcess = (r: Row): r is { id: string; ward: string } & Process => 'command' in r;
+
+// What a daemon stands for a row: a side over her avatar, closed when the
+// row is dropped or the box goes down.
+export type Side = { close(): Promise<void> };
+export type Runner = (row: Row) => Promise<Side>;
+
+// The root and nobody else, as the clock gates `keep`: an ask gated this way
+// is the device's own and cannot be reached through a door.
+const root = (_occ: OccupantRecord | undefined, asker: Asker) => asker.id === OWNER;
+
+const ROW = {
+  type: 'object',
+  properties: { id: { type: 'string' }, ward: { type: 'string' }, command: { type: 'string' }, args: { type: 'array', items: { type: 'string' } }, dir: { type: 'string' }, url: { type: 'string' }, model: { type: 'string' }, key: { type: 'string' }, turns: { type: 'number' } },
+  required: ['id', 'ward'],
+};
+
+export class Agents extends Faculty {
+  static override cells: JsonObject = { watched: {}, minted: 0, agents: {} };
+  static override asks = {
+    keep: { description: 'add an agent, or replace the one of that id: an identity, her ward, and what runs for her, a command with args in a folder, or a model at a url', input: ROW, for: root },
+    drop: { description: 'stop an agent and forget her row; the avatar in her ward stays until the root removes her', input: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] }, for: root },
+    list: { description: 'every agent she holds', input: { type: 'object' }, for: root },
+  };
+
+  runner: Runner | undefined;
+  readonly running = new Map<string, Side>();
+
+  private get rows(): Record<string, Row> {
+    return this.cells.agents as unknown as Record<string, Row>;
+  }
+
+  // Every row up, once the daemon has handed the runner. Called after the
+  // wards are hosted, since an avatar is admitted into one of them.
+  async start(runner: Runner): Promise<void> {
+    this.runner = runner;
+    for (const row of Object.values(this.rows)) await this.#run(row);
+  }
+
+  async #run(row: Row): Promise<void> {
+    if (!this.runner) return;
+    await this.running.get(row.id)?.close();
+    this.running.set(row.id, await this.runner(row));
+  }
+
+  async keep(args: JsonObject): Promise<JsonObject> {
+    const id = args.id,
+      ward = args.ward;
+    if (typeof id !== 'string' || !/^[\w.-]+$/.test(id)) return { error: 'id is a word' };
+    if (typeof ward !== 'string') return { error: 'ward names the ward she is admitted into' };
+    let row: Row;
+    if (typeof args.command === 'string' && typeof args.dir === 'string') {
+      row = { id, ward, command: args.command, args: Array.isArray(args.args) ? args.args.filter((a): a is string => typeof a === 'string') : [], dir: args.dir };
+    } else if (typeof args.url === 'string' && typeof args.model === 'string') {
+      row = { id, ward, url: args.url, model: args.model, ...(typeof args.key === 'string' ? { key: args.key } : {}), ...(typeof args.turns === 'number' ? { turns: args.turns } : {}) };
+    } else {
+      return { error: 'a row runs a process, { command, args?, dir }, or a model, { url, model, key?, turns? }' };
+    }
+    try {
+      await this.#run(row);
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) };
+    }
+    this.rows[id] = row;
+    return { kept: id };
+  }
+
+  async drop(args: JsonObject): Promise<JsonObject> {
+    const id = args.id;
+    if (typeof id !== 'string' || !this.rows[id]) return { error: 'no such agent' };
+    await this.running.get(id)?.close();
+    this.running.delete(id);
+    delete this.rows[id];
+    return { dropped: id };
+  }
+
+  list(): JsonObject {
+    return { agents: Object.values(this.rows) as unknown as JsonObject[] };
+  }
+
+  // The device puts the box down: every side closes, the rows stay.
+  async close(): Promise<void> {
+    for (const a of this.running.values()) await a.close();
+    this.running.clear();
+  }
+}

package/dock/apns.ts

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: Apache-2.0
+// APNs as a bell ground: Apple's way of waking an app, and the first of the
+// two the stores own. What makes a ring Apple's is a token signed with a
+// key the team minted at the portal, so unlike Web Push this ground cannot
+// be stood up by whoever wants one: it wants an account and a key file, and
+// that is the whole reason a bell service exists at all.
+//
+// A ring is one of two things, and the banner decides which. With no
+// banner it is a background push, `content-available`, priority 5, expiring
+// at once: the app wakes, dials, drains what it missed over Quo and
+// composes what the human reads from that. A background push is best effort
+// by Apple's own rules, throttled and never delivered to an app the human
+// force quit, so that path is best effort and says so.
+//
+// With a banner it is an alert, `mutable-content`, priority 10, and the
+// device's own notification service extension opens the seal and rewrites
+// the line before anything is drawn. Apple carries ciphertext and sees a
+// device woken, never a byte of why, on either path.
+//
+// One thing this asks of wherever it is put, and it is the reason a bell
+// service lives where it does. The APNs provider API is HTTP/2 only and
+// refuses HTTP/1.1, and not every `fetch` speaks HTTP/2: a worker's does
+// and Node's does not. So this file is the ring for a terrain whose
+// `fetch` speaks it, `http2.ts` beside it is the same ring over
+// `node:http2` for a terrain whose does not, and what they send is written
+// once here and used by both. Which terrains are which is
+// `quo-harbor.md`'s to say and not this file's. A stand-in in a test is an
+// ordinary HTTP/1.1 server, so what a test proves is the shape and the
+// signing rather than the transport, as the tab's push service did.
+import type { Ring, Token } from './push.ts';
+
+const subtle = () => globalThis.crypto.subtle;
+const ES256 = { name: 'ECDSA', namedCurve: 'P-256' } as const;
+
+const b64url = (bytes: Uint8Array): string => {
+  let binary = '';
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+};
+const utf8 = (v: string) => new TextEncoder().encode(v);
+
+// A `.p8` from the portal is PKCS#8 in a PEM wrapper. The wrapper is
+// stripped rather than parsed: the base64 between the two lines is the DER.
+export function pkcs8(pem: string): Uint8Array {
+  const body = pem.replace(/-----(BEGIN|END)[^-]*-----/g, '').replace(/\s+/g, '');
+  if (!body) throw new Error('an APNs 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;
+}
+
+// What a publisher holds. The key is per team and not per app, so one of
+// these rings every app id under that team; `topic` is which app is being
+// rung, and it is the bundle id.
+export type Apns = { key: string; keyId: string; teamId: string; topic: string };
+
+// Apple's two hosts. A token is minted by one of them and means nothing to
+// the other, and only the device knows which: a build signed for
+// development gets a sandbox token, a build from a store gets a production
+// one, and nothing in the token itself says so. So the device says it, in
+// the token it hands over.
+export const HOSTS = { production: 'https://api.push.apple.com', sandbox: 'https://api.sandbox.push.apple.com' };
+
+// Apple wants this refreshed no more often than every twenty minutes and no
+// less than every sixty, so it is minted once and kept for forty-five.
+const LIFE = 45 * 60 * 1000;
+
+// The provider token, and the request one ring makes. Both are here and
+// neither is a transport, because Apple is reached two ways in this kit and
+// what is sent must be the same both times: a `fetch` where a `fetch`
+// speaks HTTP/2, and `node:http2` in `http2.ts` where it does not.
+export async function provider(a: Apns, made: { at: number; jwt: string } | null): Promise<{ at: number; jwt: string }> {
+  const now = Date.now();
+  if (made && now - made.at < LIFE) return made;
+  const key = await subtle().importKey('pkcs8', pkcs8(a.key) as BufferSource, ES256, false, ['sign']);
+  const head = b64url(utf8(JSON.stringify({ alg: 'ES256', kid: a.keyId })));
+  const claims = b64url(utf8(JSON.stringify({ iss: a.teamId, iat: Math.floor(now / 1000) })));
+  const signed = await subtle().sign({ name: 'ECDSA', hash: 'SHA-256' }, key, utf8(`${head}.${claims}`));
+  return { at: now, jwt: `${head}.${claims}.${b64url(new Uint8Array(signed))}` };
+}
+
+// The device a token names, or nothing a ring may send. It is checked
+// where a human can read why rather than by Apple two hops later.
+export function device(token: Token): string {
+  const device = token.device;
+  if (typeof device !== 'string' || !/^[0-9a-fA-F]{8,200}$/.test(device)) throw new Error('an apns token is a device token');
+  return device;
+}
+
+// One ring, as Apple reads it: the path, the headers and the body. A ring
+// with a banner is an alert Apple must show, and `mutable-content` is what
+// sends it through the device's own extension first, which is the only
+// process that can open the seal. The title and body Apple carries are the
+// placeholder the extension replaces, and they say nothing: they are what a
+// person sees if her own phone cannot open its own banner. A ring with no
+// banner stays a background wake, where the device drains what it missed
+// over Quo and composes its own line.
+export function request(a: Apns, jwt: string, token: Token, sealed?: string): { path: string; headers: Record<string, string>; body: string } {
+  const said =
+    sealed === undefined
+      ? { aps: { 'content-available': 1 } }
+      : { aps: { alert: { 'loc-key': 'quo.ring' }, 'mutable-content': 1, sound: 'default' }, sealed };
+  return {
+    path: `/3/device/${device(token)}`,
+    headers: {
+      authorization: `bearer ${jwt}`,
+      'apns-topic': a.topic,
+      'apns-push-type': sealed === undefined ? 'background' : 'alert',
+      'apns-priority': sealed === undefined ? '5' : '10',
+      'apns-expiration': '0',
+    },
+    body: JSON.stringify(said),
+  };
+}
+
+// What Apple said. 410 is Apple saying this device token is gone. Nothing
+// here forgets it, as nothing forgets a spent Web Push endpoint: a device
+// sends a fresh token whenever it comes to the foreground, and a world that
+// dropped one would stop ringing a phone that is merely off.
+export function answered(status: number, text: string): void {
+  if (status < 200 || status > 299) throw new Error(`apns answered ${status} ${text.slice(0, 200)}`);
+}
+
+// The ground. An `apns` token is a device token and which of Apple's two
+// hosts minted it; `at` is what a test points somewhere else.
+export function apnsPush(a: Apns, at: typeof HOSTS = HOSTS): Ring {
+  let made: { at: number; jwt: string } | null = null;
+  return {
+    async ring(token: Token, sealed?: string) {
+      made = await provider(a, made);
+      const host = token.sandbox === true ? at.sandbox : at.production;
+      const req = request(a, made.jwt, token, sealed);
+      const res = await fetch(`${host}${req.path}`, { method: 'POST', headers: req.headers, body: req.body });
+      answered(res.status, await res.text());
+    },
+  };
+}

package/dock/console.ts

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box, as one being. A device has no surface of its own, so a box that
+// has joined no world has nothing to draw: the Console is that page and only
+// that. She carries the faculties her harbor stood, showing each one's asks
+// as her own, and the ordinary screen draws her exactly as it draws a
+// world's user being, through one avatar holding one standing.
+//
+// She exists because a fresh install otherwise asks for location and
+// notifications in its manifest and shows nothing that ever asks for them,
+// which is a store reviewer's first question and a human's second.
+//
+// She carries for whoever the harbor's root let in, and for nobody else: the
+// root is the box, and it invites the one avatar its own screen runs.
+import { Carrier } from '../beings/carry.ts';
+import type { Asker, OccupantRecord } from '@nervur-org/nervur';
+
+export const CONSOLE = 'console';
+
+export class Console extends Carrier {
+  static override carries(occupant: OccupantRecord | undefined, _asker: Asker): boolean {
+    return occupant !== undefined;
+  }
+}

package/dock/dialers.ts

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's dialers: `dialers`, one faculty of the dock ward, standing for
+// the sockets this box holds open to other harbors' `quo.` routes. A Mac
+// behind NAT, a phone on the mobile network, a droplet dialing home: each
+// is a dialer, and what it dials is a row in her cells, placed once by the
+// root with `keep` the way a schedule is placed on the clock and an agent
+// on the agents faculty, in no file.
+//
+// A row is one URL, the `quo.` route of the harbor dialed. She holds the
+// socket from her birth on, as every faculty holds what the box holds: one
+// line per row, announcing this harbor's wards on open, binding the far
+// side's pks, reconnecting with backoff when the line drops, and closed
+// when the row is dropped or the box goes down. The dialer itself is the
+// library's, written on the standard socket surface, so this faculty holds
+// on every terrain that has a socket; the daemon hands her the harbor to
+// dial for, as it hands the agents faculty how to run a row.
+import { OWNER } from '@nervur-org/nervur';
+import type { Asker, JsonObject, OccupantRecord } from '@nervur-org/nervur';
+import { dial, type Dialer, type Harbor } from '@nervur-org/nervur/harbor';
+import { Faculty } from './faculty.ts';
+
+// The name the dock ward holds her under.
+export const DIALERS = 'dialers';
+
+export type Row = { url: string };
+
+// The root and nobody else: a line held open is the device's own to place.
+const root = (_occ: OccupantRecord | undefined, asker: Asker) => asker.id === OWNER;
+
+const URL_ = { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] };
+
+export class Dialers extends Faculty {
+  static override cells: JsonObject = { watched: {}, minted: 0, dialers: {} };
+  static override asks = {
+    keep: { description: 'hold a socket to that quo. route, from now and from every boot, until it is dropped', input: URL_, for: root },
+    drop: { description: 'close the socket to that route and forget it', input: URL_, for: root },
+    list: { description: 'every route she dials, and whether the line is open now', input: { type: 'object' }, for: root },
+  };
+
+  harbor: Harbor | undefined;
+  readonly open = new Map<string, Dialer>();
+
+  private get rows(): Record<string, Row> {
+    return this.cells.dialers as unknown as Record<string, Row>;
+  }
+
+  // Every row dialed, once the daemon has handed the harbor to dial for.
+  start(harbor: Harbor): void {
+    this.harbor = harbor;
+    for (const row of Object.values(this.rows)) this.#dial(row.url);
+  }
+
+  #dial(url: string): void {
+    if (!this.harbor || this.open.has(url)) return;
+    this.open.set(url, dial(this.harbor, url));
+  }
+
+  keep(args: JsonObject): JsonObject {
+    const url = args.url;
+    if (typeof url !== 'string' || !/^https?:\/\/\S+$/.test(url)) return { error: 'url is the quo. route of the harbor dialed, over http or https' };
+    const clean = url.replace(/\/$/, '');
+    this.rows[clean] = { url: clean };
+    this.#dial(clean);
+    return { kept: clean };
+  }
+
+  drop(args: JsonObject): JsonObject {
+    const url = typeof args.url === 'string' ? args.url.replace(/\/$/, '') : '';
+    if (!this.rows[url]) return { error: 'no such route' };
+    this.open.get(url)?.close();
+    this.open.delete(url);
+    delete this.rows[url];
+    return { dropped: url };
+  }
+
+  list(): JsonObject {
+    return { dialers: Object.keys(this.rows).map((url) => ({ url, open: this.open.get(url)?.socket !== null && this.open.has(url) })) };
+  }
+
+  // The device puts the box down: every line closes, the rows stay.
+  close(): void {
+    for (const d of this.open.values()) d.close();
+    this.open.clear();
+  }
+}

package/dock/faculty.ts

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: Apache-2.0
+// A faculty: one being of the dock ward, standing for one thing the box can
+// do. She is a being and nothing else, so what is here is not a second kind
+// of object but the two moves every faculty shares.
+//
+// Out: whoever holds a standing at her asks her methods, and the occupant's
+// notes say what that caller is, a prefix on a store, an account at a
+// vendor. Her own cells say what the thing is.
+//
+// Back: `watch` is the one subscribe verb every faculty has. A being who
+// wants waking mints an invitation and hands it over, this takes it as a
+// standing, and from then on she is asked at her own door as the occupant
+// she named. `occupants.remove` on her side is the whole of unsubscribe: the
+// next wake hears `removed` and the row goes.
+//
+// She holds what the box holds and begins holding it at birth: the
+// connection, the interval, the worker, the route are opened in her
+// constructor, and she is born whether or not the thing is reachable,
+// answering an error object while it is not.
+import { Being, isInvitation, isSilence, isWord, wordOf } from '@nervur-org/nervur';
+import type { Asker, JsonObject } from '@nervur-org/nervur';
+
+// One subscription, as she files it: her own id for the relation, who asked
+// for it, and what to ask them.
+export type Watched = { by: string; method: string; args: JsonObject };
+
+// What one round of waking did, per subscription.
+export type Woke = { id: string; by: string; out: unknown };
+
+export class Faculty extends Being {
+  static override cells: JsonObject = { watched: {}, minted: 0 };
+
+  // Someone wants waking. She hands the invitation she minted and says what
+  // to ask her; this knocks it, takes it under an id of this being's own,
+  // and files it. The id never crosses: it is this side's name for the
+  // relation, and the caller's name for the same relation is her own.
+  //
+  // The empty ask is the knock, because every being answers one and asking
+  // for a named ask would make every subscriber owe a method she does not
+  // otherwise need.
+  async watch(args: JsonObject, asker: Asker): Promise<JsonObject> {
+    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 as unknown as { watched: Record<string, Watched>; minted: number };
+    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: the
+  // timer wakes her, learns when she is next due and arms the box for it, so
+  // a being born long after the box was up is not waiting for a round nobody
+  // scheduled. Most faculties owe nothing, and this is why they say nothing.
+  protected async welcomed(_id: string): Promise<void> {}
+
+  // One round of waking. Each subscriber is asked what she asked to be
+  // asked, with whatever this round adds. A subscriber who removed the
+  // occupant says `removed` once, and her row goes with the standing; there
+  // is nothing to retry and nothing to remember.
+  //
+  // `only` is one subscriber of the round's own choosing, named by this
+  // being's own id for the relation, and it is the same round down to one
+  // row: a faculty that wakes somebody just filed learns exactly what a full
+  // round would have learned about her.
+  //
+  // `dropped` is this being herself: her ward took her out, so the standings
+  // she holds reach nobody. Null says so, and whoever holds the interval puts
+  // it down rather than waking an empty room for as long as the box is up.
+  protected async woke(round: (w: Watched) => JsonObject = (w) => w.args, only?: string): Promise<Woke[] | null> {
+    const cells = this.cells as unknown as { watched: Record<string, Watched> };
+    const out: Woke[] = [];
+    for (const [id, w] of Object.entries(cells.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 cells.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. For a device's
+  // own code and for a suite; it crosses no door.
+  get watching(): Record<string, Watched> {
+    return this.cells.watched as unknown as Record<string, Watched>;
+  }
+}
+
+// The three moves a being makes at every birth to hold what her box lends.
+// A standing points at a being and not at a box, so one she wakes up holding
+// names a being on the box she was on when it was made; a restart and a
+// migration are the same silent event to her, so she does these again every
+// time she is constructed and is always pointed at the box she is on.
+//
+// `watch` says she wants waking too: her ward mints the occupant, the
+// faculty takes the standing it makes, and from then on the wake arrives at
+// her door under the id she chose.
+// Every join in flight on this box. A being takes what her box lends at her
+// birth, and birth is synchronous while taking a standing is not, so a
+// harbor that answered "up" before they landed would be a box whose first
+// tick woke nobody and whose first ring reached no platform. The terrain
+// waits on this once, after its wards are hosted; nothing else reads it, and
+// a join that fails leaves nothing behind but a being who asks again.
+const flight = new Set<Promise<unknown>>();
+export const settled = async (): Promise<void> => {
+  while (flight.size) {
+    const now = [...flight];
+    await Promise.allSettled(now);
+    for (const p of now) flight.delete(p);
+  }
+};
+
+export function join(b: Being, name: string, watch?: { method: string; args?: JsonObject }, id = name): Promise<string | null> {
+  const p = joining(b, name, watch, id);
+  flight.add(p);
+  void p.catch(() => {});
+  return p;
+}
+
+async function joining(b: Being, name: string, watch: { method: string; args?: JsonObject } | undefined, id: string): Promise<string | null> {
+  // One turn, before anything is asked. A being is called at her door and
+  // holds her stance from her first line, but her ward sets that door after
+  // her constructor returns, so a stance call made inside it reaches a being
+  // her ward does not hold yet and is answered as one taken out. Every
+  // faculty relation is made at birth, so the wait belongs here rather than
+  // in each of them.
+  await Promise.resolve();
+  b.standings.remove(id);
+  b.occupants.remove(`${id}:wake`);
+  const got = await b.lend(name, id);
+  if (got === null) return null;
+  if (!watch) return got;
+  const back = await b.invite(`${id}:wake`);
+  if (!back) return got;
+  await b.standings[id]?.ask('watch', { invitation: back, method: watch.method, ...(watch.args ? { args: watch.args } : {}) });
+  return got;
+}

package/dock/fcm.ts

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+// FCM as a bell ground: Google's way of waking an app, and the second of
+// the two the stores own. Like APNs it wants an account, a project and a
+// key, which is why it lives behind a bell service and not in a world.
+//
+// Two hops rather than one. Google does not take a signed token at the send
+// door the way Apple does: a service account's key signs a JWT, that JWT is
+// exchanged at Google's OAuth door for an access token, and the access
+// token sends. The exchange is what is cached, for an hour less a minute,
+// and one exchange serves every ring in that hour.
+//
+// The ring carries nothing, so the message is data only with an empty data
+// map and no `notification` key: a message carrying a notification would be
+// displayed by Android itself, out of the app's hands and out of the
+// human's, saying whatever the sender put in it. Data only wakes the app,
+// which dials, drains what it missed over Quo, sealed, and composes what
+// the human reads. High priority is what wakes a dozing device; it is the
+// same promise Apple's background push makes, which is best effort.
+import type { Ring, Token } from './push.ts';
+
+const subtle = () => globalThis.crypto.subtle;
+const RS256 = { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' } as const;
+
+const b64url = (bytes: Uint8Array): string => {
+  let binary = '';
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+};
+const utf8 = (v: string) => new TextEncoder().encode(v);
+
+const der = (pem: string): Uint8Array => {
+  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;
+};
+
+// The three fields of the JSON Google hands out when a service account is
+// given a key. The whole file has more in it and none of the rest is read
+// here, so what a publisher keeps as a secret is the file as it came.
+export type Account = { project_id: string; client_email: string; private_key: string };
+
+export function isAccount(v: unknown): v is Account {
+  const a = v as Partial<Account> | null;
+  return a !== null && typeof a === 'object' && typeof a.project_id === 'string' && typeof a.client_email === 'string' && typeof a.private_key === 'string';
+}
+
+// Where the two doors are, so a test may point them somewhere else.
+export type Doors = { oauth: string; fcm: string };
+export const DOORS: 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: Account, at: Doors, held: { at: number; token: string } | null): Promise<{ at: number; token: string }> {
+  const now = Date.now();
+  if (held && now - held.at < LIFE) return held;
+  const key = await subtle().importKey('pkcs8', der(a.private_key) as BufferSource, 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()) as { access_token?: unknown };
+  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: Account, at: Doors = DOORS): Ring {
+  let held: { at: number; token: string } | null = null;
+  return {
+    async ring(token: Token, sealed?: string) {
+      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)}`);
+    },
+  };
+}