@nervur-org/dock 0.3.0

package/harbor/quo.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+// The quo. route: the door sealed bytes arrive at, the same route on every
+// terrain. POST `/quo/<pk>` carries one ask to a pk this harbor holds or
+// holds a socket for; bytes from here go to an own door or a held socket,
+// never onward. A URL of this route is the base of every reach.
+//
+// It is `Request` in and `Response` out and names no runtime, so the daemon
+// mounts it under `/quo` behind the proxy that maps the quo. hostname and the
+// worker at the edge mounts it under its own prefix.
+//
+// The listener half of the socket reach is not here, because holding a socket
+// is the one thing no two runtimes do alike: `ws` on Node, at the daemon's
+// own door in `http.ts`, and a `WebSocketPair` at the edge, in the harbor
+// there. What a dialer's socket becomes once it is held is the library's
+// `Socket` on both.
+import { SUITE } from '@nervur-org/nervur/harbor';
+import { readAll, type Handler } from './http.ts';
+
+// What this route asks of the harbor it answers for: one ask delivered to a
+// pk, which is a door here or a socket held here. Nothing else.
+export type Deliver = { deliver(pk: string, bytes: Uint8Array): Promise<Uint8Array | undefined> };
+
+// The route is public and carries sealed bytes, so any origin may POST
+// to it: a tab on a world's web. reaching another world's quo. is the
+// ordinary case, and a binary POST needs the preflight answered.
+export const OPEN = { 'access-control-allow-origin': '*', 'access-control-allow-methods': 'POST, OPTIONS', 'access-control-allow-headers': 'content-type, quo-suite' };
+
+export function quoRoute(harbor: Deliver): Handler {
+  return async (req, rest) => {
+    if (req.method === 'OPTIONS') return new Response(null, { status: 204, headers: OPEN });
+    // The wire suite the caller speaks. Absent is this one, because a caller
+    // older than the header is this one. Anything else this door cannot open
+    // and says so as nothing delivered, rather than taking bytes that will
+    // never open and answering a silence that names no reason.
+    const suite = req.headers.get('quo-suite');
+    if (suite !== null && suite !== String(SUITE)) return Response.json({ error: `this door speaks wire suite ${SUITE}` }, { status: 404, headers: OPEN });
+    const pk = rest.replace(/^\//, '');
+    if (req.method !== 'POST' || !/^[0-9a-f]{128}$/.test(pk)) return Response.json({ error: 'POST /quo/<pk>' }, { status: 404, headers: OPEN });
+    const raw = await readAll(req);
+    const back = raw === undefined ? undefined : await harbor.deliver(pk, raw);
+    if (back === undefined) return Response.json({ error: 'no reach for that pk' }, { status: 404, headers: OPEN });
+    return new Response(new Uint8Array(back), { headers: { 'content-type': 'application/octet-stream', ...OPEN } });
+  };
+}

package/harbor/resolve.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+// How a class file the harbor folder holds finds its packages. The folder
+// is the device's, not a package: it has no node_modules, and a class in it
+// that imports `@nervur-org/nervur` would otherwise fail to resolve from where
+// it sits. This is a module resolution hook, registered once by the disk
+// harbor: a bare specifier that does not resolve from a file outside any
+// node_modules is resolved again from where the dock itself is installed,
+// so a class file sees exactly the packages the daemon sees, the library
+// and the dock's own, and one copy of each.
+type Context = { parentURL?: string; conditions: string[]; importAttributes: Record<string, string> };
+type Resolved = { url: string; format?: string | null; shortCircuit?: boolean };
+type Next = (specifier: string, context: Context) => Promise<Resolved>;
+
+let parent = '';
+
+export function initialize(data: { parent: string }): void {
+  parent = data.parent;
+}
+
+const bare = (s: string) => !s.startsWith('.') && !s.startsWith('/') && !/^[a-z]+:/i.test(s);
+
+export async function resolve(specifier: string, context: Context, next: Next): Promise<Resolved> {
+  try {
+    return await next(specifier, context);
+  } catch (e) {
+    const missing = (e as { code?: string }).code === 'ERR_MODULE_NOT_FOUND';
+    const from = context.parentURL ?? '';
+    if (missing && parent && bare(specifier) && from.startsWith('file:') && !from.includes('/node_modules/')) return next(specifier, { ...context, parentURL: parent });
+    throw e;
+  }
+}

package/harbor/seal.ts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+// The seal: what a store does to a ward's bytes before they rest on a data
+// store, under one key the secret store holds. One piece with three users,
+// the edge under the platform's secret, the daemon under a key from its
+// environment, the phone under a key from the Keychain. AES-GCM under a
+// 32-byte key, a fresh nonce each time, nonce and ciphertext together as
+// hex. WebCrypto only, so it runs wherever a store does.
+import { arithmetic } from '@nervur-org/nervur/ward';
+
+const { hex, unhex } = arithmetic;
+// Bytes as the platform's crypto wants them: over a plain ArrayBuffer.
+const plain = (b: Uint8Array): Uint8Array<ArrayBuffer> => new Uint8Array(b);
+
+export async function sealKey(secret: string): Promise<CryptoKey> {
+  if (!/^[0-9a-f]{64}$/.test(secret)) throw new Error('a seal key is 32 bytes as hex');
+  return crypto.subtle.importKey('raw', plain(unhex(secret)), 'AES-GCM', false, ['encrypt', 'decrypt']);
+}
+export async function seal(key: CryptoKey, bytes: Uint8Array): Promise<string> {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ct = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plain(bytes)));
+  return hex(iv) + hex(ct);
+}
+export async function open(key: CryptoKey, sealed: string): Promise<Uint8Array> {
+  const b = plain(unhex(sealed));
+  return new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: b.subarray(0, 12) }, key, b.subarray(12)));
+}

package/harbor/sealed.ts

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: Apache-2.0
+// The sealed store: the store an app holds on a device in a hand, the phone
+// and the desk alike. One key per harbor in the platform's secret store,
+// this device only, so it never travels in a backup; one sealed file per
+// ward, seed, partition and record as one blob, in a folder no backup
+// copies. The seal is `seal.ts`, the same piece the daemon and the edge use.
+//
+//   <files>/<harbor>/wards/<name>.sealed
+//   <files>/<harbor>/reach.json
+//   <secrets>: quo-<harbor>                32 bytes as hex
+//
+// Custody is the backup question, and opening the store answers it: a key
+// with no folder is a reinstall, and the stale key is deleted; a folder
+// with no key is a restore to another device, and the unreadable files are
+// deleted. Either way the harbor starts fresh and there is never a twin.
+//
+// What a platform gives is two small things, files and secrets, and the
+// rest is here once: the phone hands its plugins, the desk hands its core,
+// and the memory harbor hands a map, which is where the rule is proven.
+import { arithmetic } from '@nervur-org/nervur/ward';
+import type { Kept, Store, WardRecord } from '@nervur-org/nervur/harbor';
+import { sealKey, seal, open } from './seal.ts';
+
+// A folder the platform keeps for this app and no backup copies. Paths are
+// relative to it and forward-slashed; a platform maps them to its own.
+export type Files = {
+  exists(path: string): Promise<boolean>;
+  read(path: string): Promise<string>;
+  write(path: string, text: string): Promise<void>;
+  remove(path: string): Promise<void>;
+  mkdir(path: string): Promise<void>;
+  rmdir(path: string): Promise<void>;
+  list(path: string): Promise<string[]>;
+};
+
+// The platform's secret store, one string per item, this device only.
+export type Secrets = {
+  get(item: string): Promise<string | undefined>;
+  set(item: string, value: string): Promise<void>;
+  remove(item: string): Promise<void>;
+};
+
+const { hex, unhex } = arithmetic;
+type Blob = { seed: string; partition: Record<string, unknown>; record: WardRecord };
+
+export class Sealed implements Store {
+  readonly harbor: string;
+  readonly #files: Files;
+  readonly #key: CryptoKey;
+  readonly #queues = new Map<string, Promise<void>>();
+  private constructor(harbor: string, files: Files, key: CryptoKey) {
+    this.harbor = harbor;
+    this.#files = files;
+    this.#key = key;
+  }
+
+  // Open one harbor's store, applying the custody rule, minting the key and
+  // the folder when this is a fresh install.
+  static async open(harbor: string, files: Files, secrets: Secrets): Promise<Sealed> {
+    const item = `quo-${harbor}`;
+    const root = `quo/${harbor}`;
+    let secret = await secrets.get(item);
+    const folder = await files.exists(root);
+    if (secret && !folder) {
+      await secrets.remove(item);
+      secret = undefined;
+    }
+    if (!secret && folder) await files.rmdir(root);
+    if (!secret) {
+      secret = hex(crypto.getRandomValues(new Uint8Array(32)));
+      await secrets.set(item, secret);
+    }
+    if (!(await files.exists(`${root}/wards`))) await files.mkdir(`${root}/wards`);
+    return new Sealed(harbor, files, await sealKey(secret));
+  }
+
+  // Everything this harbor has, key and files: what a person does by hand
+  // to leave a device, and what a test does between two openings.
+  static async wipe(harbor: string, files: Files, secrets: Secrets): Promise<void> {
+    await secrets.remove(`quo-${harbor}`);
+    if (await files.exists(`quo/${harbor}`)) await files.rmdir(`quo/${harbor}`);
+  }
+
+  #path(name: string) {
+    return `quo/${this.harbor}/wards/${name}.sealed`;
+  }
+  async #read(name: string): Promise<Blob> {
+    const data = await this.#files.read(this.#path(name));
+    return JSON.parse(new TextDecoder().decode(await open(this.#key, data.trim()))) as Blob;
+  }
+  // A sealed ward is rewritten whole, so the read sits inside the queue
+  // with the write: two changes to one ward never lose each other's part.
+  #keep(name: string, change: (b: Blob | undefined) => Blob): Promise<void> {
+    const next = (this.#queues.get(name) ?? Promise.resolve()).then(async () => {
+      const blob = change((await this.#files.exists(this.#path(name))) ? await this.#read(name) : undefined);
+      const sealed = await seal(this.#key, new TextEncoder().encode(JSON.stringify(blob)));
+      await this.#files.write(this.#path(name), sealed + '\n');
+    });
+    this.#queues.set(name, next.catch(() => {}));
+    return next;
+  }
+
+  async list(): Promise<string[]> {
+    const files = await this.#files.list(`quo/${this.harbor}/wards`);
+    return files.filter((f) => f.endsWith('.sealed')).map((f) => f.slice(0, -'.sealed'.length));
+  }
+
+  async load(name: string): Promise<Kept | undefined> {
+    if (!(await this.#files.exists(this.#path(name)))) return undefined;
+    const b = await this.#read(name);
+    return { seed: unhex(b.seed), partition: b.partition, record: b.record };
+  }
+
+  async put(name: string, kept: Kept): Promise<void> {
+    if (await this.#files.exists(this.#path(name))) throw new Error(`ward ${name} already exists on this device`);
+    return this.#keep(name, () => ({ seed: hex(kept.seed), partition: kept.partition, record: kept.record }));
+  }
+
+  async save(name: string, partition: Record<string, unknown>): Promise<void> {
+    if (!(await this.#files.exists(this.#path(name)))) return; // a name not kept is nothing
+    return this.#keep(name, (b) => ({ ...b!, partition }));
+  }
+
+  async record(name: string, record: WardRecord): Promise<void> {
+    if (!(await this.#files.exists(this.#path(name)))) return;
+    return this.#keep(name, (b) => ({ ...b!, record }));
+  }
+
+  async take(name: string): Promise<Kept | undefined> {
+    const kept = await this.load(name);
+    if (!kept) return undefined;
+    await this.#queues.get(name);
+    await this.#files.remove(this.#path(name));
+    return kept;
+  }
+
+  async hints(): Promise<Record<string, string>> {
+    const p = `quo/${this.harbor}/reach.json`;
+    if (!(await this.#files.exists(p))) return {};
+    return JSON.parse(await this.#files.read(p)) as Record<string, string>;
+  }
+
+  async hint(pk: string, url: string): Promise<void> {
+    const all = await this.hints();
+    all[pk] = url;
+    await this.#files.write(`quo/${this.harbor}/reach.json`, JSON.stringify(all) + '\n');
+  }
+}
+
+// Files and secrets in memory, for a suite and for a box that keeps
+// nothing: the custody rule is proven here once and holds on every
+// platform that hands the two.
+export function inMemory(): { files: Files; secrets: Secrets; disk: Map<string, string> } {
+  const disk = new Map<string, string>();
+  const dirs = new Set<string>();
+  const vault = new Map<string, string>();
+  const under = (dir: string) => [...disk.keys()].filter((k) => k.startsWith(`${dir}/`));
+  const files: Files = {
+    exists: async (p) => disk.has(p) || dirs.has(p),
+    read: async (p) => {
+      const v = disk.get(p);
+      if (v === undefined) throw new Error(`no such file: ${p}`);
+      return v;
+    },
+    write: async (p, text) => void disk.set(p, text),
+    remove: async (p) => void disk.delete(p),
+    mkdir: async (p) => {
+      const parts = p.split('/');
+      for (let i = 1; i <= parts.length; i += 1) dirs.add(parts.slice(0, i).join('/'));
+    },
+    rmdir: async (p) => {
+      for (const k of under(p)) disk.delete(k);
+      for (const d of [...dirs]) if (d === p || d.startsWith(`${p}/`)) dirs.delete(d);
+    },
+    list: async (p) => under(p).map((k) => k.slice(p.length + 1)).filter((k) => !k.includes('/')),
+  };
+  const secrets: Secrets = {
+    get: async (i) => vault.get(i),
+    set: async (i, v) => void vault.set(i, v),
+    remove: async (i) => void vault.delete(i),
+  };
+  return { files, secrets, disk };
+}

package/harbor/tauri.ts

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+// The desk: the sealed store over the desk app's core, the browser harbor
+// over that store, and the desk's faculties as the platform gives them.
+// The core is Tauri's Rust side, reached by its commands, and it holds
+// three small things: the files under the app's own data folder, the key
+// in the OS keychain, and the notification center. The custody rule is the
+// sealed store's, `sealed.ts`, and this file hands it the two seams.
+//
+// The desk is a presence like the phone: a laptop sleeps and stands behind
+// a network nobody can address, so its harbor dials, holds no listener and
+// ships no daemon. It has no ear, since no store rings a desk; a desk is
+// reached while the app is open and drains what it missed when it opens.
+import type { BeingClass, JsonObject } from '@nervur-org/nervur';
+import { NOTIFICATIONS, Notifications } from '../dock/index.ts';
+import { BrowserHarbor } from './browser.ts';
+import { Sealed, type Files, type Secrets } from './sealed.ts';
+
+// The core, as the window sees it: one call in, one answer back.
+export type Core = { invoke(cmd: string, args?: Record<string, unknown>): Promise<unknown> };
+
+export class DeskNotifications extends Notifications {
+  readonly #core: Core;
+  constructor(stance: ConstructorParameters<typeof Notifications>[0], core: Core) {
+    super(stance);
+    this.#core = core;
+  }
+  override async notify(args: JsonObject): Promise<JsonObject> {
+    const title = typeof args.title === 'string' ? args.title : '';
+    const body = typeof args.body === 'string' ? args.body : '';
+    await this.#core.invoke('notify', { title, body });
+    return { shown: true };
+  }
+}
+
+// What a desk lends: its notification center, under the name every box
+// lends it under. Location is what the platform gives, which on a desk is
+// nothing, so it is not lent rather than lent and dumb. No timer either: a
+// desk holds presences and no home, so no Clock lives on it and a Timer
+// there would arm for nobody. A Timer stands only on a box that hosts a
+// home.
+export const deskLent: Record<string, string> = { [NOTIFICATIONS]: 'Notifications' };
+
+// The two seams over the core's commands. Paths are relative to the app's
+// data folder, and the core refuses one that climbs out of it.
+export function deskFiles(core: Core): Files {
+  return {
+    exists: (path) => core.invoke('file_exists', { path }) as Promise<boolean>,
+    read: (path) => core.invoke('file_read', { path }) as Promise<string>,
+    write: async (path, text) => void (await core.invoke('file_write', { path, text })),
+    remove: async (path) => void (await core.invoke('file_remove', { path })),
+    mkdir: async (path) => void (await core.invoke('dir_make', { path })),
+    rmdir: async (path) => void (await core.invoke('dir_remove', { path })),
+    list: (path) => core.invoke('dir_list', { path }) as Promise<string[]>,
+  };
+}
+export function deskSecrets(core: Core): Secrets {
+  return {
+    get: async (item) => (await core.invoke('secret_get', { item })) as string | undefined ?? undefined,
+    set: async (item, value) => void (await core.invoke('secret_set', { item, value })),
+    remove: async (item) => void (await core.invoke('secret_remove', { item })),
+  };
+}
+
+// The desk app's one harbor, booted, lending what the desk has to its
+// wards. The core hands the faculty its notification center by being in
+// the class body the harbor holds, which is the one place a terrain's
+// body may hold a live object.
+export async function deskHarbor(core: Core, name = 'quo', classes: Record<string, BeingClass> = {}): Promise<BrowserHarbor> {
+  class Center extends DeskNotifications {
+    constructor(stance: ConstructorParameters<typeof DeskNotifications>[0]) {
+      super(stance, core);
+    }
+  }
+  const store = await Sealed.open(name, deskFiles(core), deskSecrets(core));
+  const h = new BrowserHarbor(store, { Notifications: Center, ...classes });
+  await h.stand(deskLent);
+  await h.boot();
+  return h;
+}

package/harbor/ward.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// What a ward says about itself, read the one way anything is read from a
+// ward: by asking it. A harbor hands its device the beings it made and the
+// keys it has, and nothing else about a world; the partition is not on offer
+// and should not be, since it holds every seed the ward has. So a side that
+// wants to know which being is public, or what a key is a class of, asks
+// through the ask pointer and reads the describe, which is the same answer
+// the owner gets on every other surface. Terrain-free: a daemon and a tab
+// both hold a Hosted and both read it here.
+import type { Hosted } from '@nervur-org/nervur/harbor';
+
+// One being of a ward, as her own ward describes her.
+export type Row = { class: string | null; public: boolean; digest: string | null; absent?: boolean };
+
+// Every being of the ward, by key: the ones a door holds this run and the
+// ones whose class did not construct, which are hers all the same.
+export async function beingsOf(h: Hosted): Promise<Record<string, Row>> {
+  const bp = (await h.ask()) as { notes?: { beings?: Record<string, Row> } };
+  return bp.notes?.beings ?? {};
+}
+
+// The key of the one public being, or null. The ward marks her and the ward
+// is asked, because no harbor reads that mark and none should: which being
+// answers strangers is a decision, and a harbor decides nothing.
+export async function publicKey(h: Hosted): Promise<string | null> {
+  for (const [key, row] of Object.entries(await beingsOf(h))) if (row.public) return key;
+  return null;
+}