nervur 0.21.4 → 0.22.0

package/src/line/push.ts

@@ -1,112 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// A ring with no content, as Web Push sends it: RFC 8030 with no payload,
-// so nothing is encrypted and nothing is said, and RFC 8292's VAPID, so
-// the push service knows who rings. It runs on fetch and Web Crypto, in
-// every engine. The device a ring wakes asks its relay client to `ring`.
-//
-//   subject  { subject }   the contact a push service reaches, a mailto:
-//                          or https: URI, the owner's to set
-//   key                    the key a device subscribes with, as
-//                          PushManager takes it
-//   ring     { endpoint }  a ring to that endpoint: `rung`, `gone` where
-//                          the push service has let it go, or an error
-//
-// The signing key is drawn at the first `key` or `ring` and kept in the
-// faculty's cells, sealed with the rest of the harbor.
-import type { AskSpec, JsonObject } from '../being/index.ts';
-import { concat, utf8 } from '../crypto/index.ts';
-import { Push, type GroundFaculty } from '../harbor/index.ts';
-import { ownerAsk } from '../ward/index.ts';
-
-export const WEB_PUSH = 'org.nervur.web-push';
-// How long a push service holds a ring for a device, in seconds.
-export const PUSH_TTL = 60;
-// How long a VAPID token stands, in seconds, inside RFC 8292's day.
-export const VAPID_LIFE = 43_200;
-
-type Vapid = { d: string; x: string; y: string };
-const EC = { name: 'ECDSA', namedCurve: 'P-256' } as const;
-
-export const base64url = (bytes: Uint8Array): string => {
-  let s = '';
-  for (const b of bytes) s += String.fromCharCode(b);
-  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-};
-const unbase64url = (text: string): Uint8Array => Uint8Array.from(atob(text.replace(/-/g, '+').replace(/_/g, '/')), (c) => c.charCodeAt(0));
-const local = (host: string): boolean => host === '127.0.0.1' || host === 'localhost' || host === '[::1]';
-
-// A push endpoint: an https URL, or plain http to this machine alone.
-export const pushEndpoint = (value: unknown): URL | null => {
-  if (typeof value !== 'string') return null;
-  try {
-    const url = new URL(value);
-    return url.protocol === 'https:' || (url.protocol === 'http:' && local(url.hostname)) ? url : null;
-  } catch {
-    return null;
-  }
-};
-const isSubject = (value: unknown): value is string => typeof value === 'string' && /^(mailto:.+|https:\/\/.+)$/.test(value);
-
-export const webPush: GroundFaculty = () =>
-  class WebPush extends Push {
-    static override readonly kind: string = WEB_PUSH;
-    static override asks: Record<string, AskSpec> = {
-      subject: ownerAsk('the contact a push service reaches, a mailto: or https: URI', { required: ['subject'] }),
-      key: { description: 'the key a device subscribes to pushes with', input: { type: 'object' } },
-      ring: { description: 'a ring with no content to a push endpoint', input: { type: 'object', required: ['endpoint'] } },
-    };
-
-    #drawing: Promise<Vapid> | undefined;
-
-    subject(args: JsonObject): JsonObject {
-      if (!isSubject(args.subject)) return { error: 'subject is a mailto: or https: URI' };
-      this.cells.subject = args.subject;
-      return { subject: args.subject };
-    }
-
-    async key(): Promise<JsonObject> {
-      return { key: WebPush.#public(await this.#vapid()) };
-    }
-
-    async ring(args: JsonObject): Promise<JsonObject> {
-      const endpoint = pushEndpoint(args.endpoint);
-      if (endpoint === null) return { error: 'endpoint is an https URL' };
-      const sub = this.cells.subject;
-      if (!isSubject(sub)) return { error: 'no subject is set' };
-      const vapid = await this.#vapid();
-      const signing = await crypto.subtle.importKey('jwk', { kty: 'EC', crv: 'P-256', ...vapid }, EC, false, ['sign']);
-      const part = (value: JsonObject) => base64url(utf8(JSON.stringify(value)));
-      const unsigned = `${part({ typ: 'JWT', alg: 'ES256' })}.${part({ aud: endpoint.origin, exp: Math.floor(Date.now() / 1000) + VAPID_LIFE, sub })}`;
-      const signature = new Uint8Array(await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, signing, new Uint8Array(utf8(unsigned))));
-      let status: number;
-      try {
-        const response = await fetch(endpoint, {
-          method: 'POST',
-          headers: { TTL: String(PUSH_TTL), Urgency: 'high', 'Content-Length': '0', Authorization: `vapid t=${unsigned}.${base64url(signature)}, k=${WebPush.#public(vapid)}` },
-        });
-        status = response.status;
-        await response.body?.cancel();
-      } catch {
-        return { error: 'the push service was not reached' };
-      }
-      if (status === 404 || status === 410) return { gone: true };
-      return status >= 200 && status < 300 ? { rung: true } : { error: `the push service answered ${String(status)}` };
-    }
-
-    static #public({ x, y }: Vapid): string {
-      return base64url(concat(Uint8Array.of(4), unbase64url(x), unbase64url(y)));
-    }
-
-    #vapid(): Promise<Vapid> {
-      const kept = this.cells.vapid as Vapid | undefined;
-      if (kept) return Promise.resolve(kept);
-      this.#drawing ??= (async () => {
-        const pair = await crypto.subtle.generateKey(EC, true, ['sign']);
-        const { d, x, y } = await crypto.subtle.exportKey('jwk', pair.privateKey);
-        const vapid = { d: d!, x: x!, y: y! };
-        this.cells.vapid = vapid;
-        return vapid;
-      })();
-      return this.#drawing;
-    }
-  };

package/src/node/index.ts

@@ -1,241 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// `nervur/node`: the Node ground. A harbor keeps its seed and sealed
-// memory in a folder, finds its code among the modules it is handed and
-// then in files, speaks TCP from genesis and the web and Web Push where
-// the root opens them, and serves the root line on a local socket, so the
-// `nervur` command reaches it while it stands.
-//
-//   <dir>/seed        the harbor's seed
-//   <dir>/<place>/    its sealed memory
-//   <dir>/root.sock   the root line while the harbor is served, open to
-//                     this user alone, or in the temporary folder for a
-//                     folder too deep for a socket path
-//
-// One run holds a folder: a terrain refuses a folder another run serves.
-import { createHash } from 'node:crypto';
-import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import { createRequire } from 'node:module';
-import { connect, createServer, type Server } from 'node:net';
-import { homedir, tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import type { JsonObject } from '../being/index.ts';
-import { Loader, type Loaded, type Module } from '../contract/index.ts';
-import { FolderCustody, FolderMemory } from '../folder/index.ts';
-import { rootLine, type GroundProbe, type Harbor, type RootRequest } from '../harbor/index.ts';
-import { webGround } from '../http/index.ts';
-import { webPush } from '../line/index.ts';
-import { CryptoEntropy, HeldLoader, PointerTerrain } from '../pointer/index.ts';
-import { TCP_OPENING, tcpFaculty } from '../tcp/index.ts';
-
-export const NODE = 'node';
-
-// Where a harbor of this user lives unless named: $NERVUR_DIR, then
-// ~/.nervur.
-export const harborDir = (env: Record<string, string | undefined> = process.env): string => env.NERVUR_DIR ?? join(homedir(), '.nervur');
-
-// A socket path has a hundred bytes or so on every system, so a folder too
-// deep for one puts its socket in this user's temporary folder, under a
-// name drawn from the folder's own path.
-const SOCKET_PATH = 100;
-export const socketOf = (dir: string): string => {
-  const beside = join(resolve(dir), 'root.sock');
-  if (Buffer.byteLength(beside) <= SOCKET_PATH) return beside;
-  return join(tmpdir(), `nervur-${createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 32)}.sock`);
-};
-
-// A specifier that names a file rather than a package.
-export const isFile = (from: string): boolean => /^(\.{1,2}[\\/]|[\\/]|[A-Za-z]:[\\/])/.test(from) || /\.(m?[jt]s|c[jt]s)$/.test(from);
-
-// Code from a file or an installed package: a module that exports
-// `module`, `version` and `classes`, found again by where it was found, a
-// file by its absolute path and a package by its name, resolved from each
-// folder of `bases` in order. What is not there, or exports no module, is
-// none. Code that is there and does not import throws Node's reason, so
-// whoever added it learns why; an ES module read as CommonJS says which
-// field its package.json lacks.
-export class ImportLoader extends Loader {
-  readonly #bases: readonly string[];
-  constructor(bases: readonly string[] = [process.cwd()]) {
-    super();
-    this.#bases = bases;
-  }
-
-  async load(from: string): Promise<Loaded | null> {
-    const found = isFile(from) ? resolve(from) : this.#package(from);
-    if (found === null) return null;
-    let exported: { module?: unknown; version?: unknown; classes?: unknown };
-    try {
-      exported = (await import(pathToFileURL(found).href)) as typeof exported;
-    } catch (e) {
-      const said = (e as Error).message;
-      // The name itself is nowhere, as against code there that needs
-      // something that is not.
-      if ((e as { code?: string }).code === 'ERR_MODULE_NOT_FOUND' && said.includes(`'${found}'`)) return null;
-      const commonjs = e instanceof SyntaxError && /\b(export|import)\b/.test(said);
-      throw new Error(`${found} did not load: ${said}${commonjs ? '; it is an ES module read as CommonJS, so set "type": "module" in its package.json' : ''}`, { cause: e });
-    }
-    const { module, version, classes } = exported;
-    if (typeof module !== 'string' || typeof version !== 'string' || !Array.isArray(classes)) return null;
-    return { module, version, classes, from: isFile(from) ? found : from };
-  }
-
-  #package(name: string): string | null {
-    for (const base of this.#bases) {
-      try {
-        return createRequire(join(resolve(base), 'noop.js')).resolve(name);
-      } catch {
-        // Not installed from here; the next base may hold it.
-      }
-    }
-    return null;
-  }
-}
-
-// A module by its id, the name it declares, so the catalogue's cells name
-// code the same way on every ground. `add` may name a module by its id, a
-// file, or an installed package, and the ground works out which. The
-// modules a harbor is handed are found by their id first. Where else an id
-// is found, a file's path or a package's name, is this ground's own
-// knowledge, kept beside the harbor in `<dir>/modules.json` and never in
-// the sealed package, since another ground finds the same id in its own
-// bundle. Packages resolve from where the command runs, then from the
-// harbor's folder.
-export class NodeLoader extends ImportLoader {
-  readonly #held: HeldLoader;
-  readonly #map: string | undefined;
-  constructor(modules: readonly Module[] = [], dir?: string) {
-    super(dir === undefined ? [process.cwd()] : [process.cwd(), dir]);
-    this.#held = new HeldLoader(modules);
-    this.#map = dir === undefined ? undefined : join(dir, MODULES);
-  }
-
-  override async load(from: string): Promise<Loaded | null> {
-    const held = await this.#held.load(from);
-    if (held) return held;
-    const known = await this.#known();
-    const where = known[from];
-    if (where !== undefined) {
-      const loaded = await super.load(where);
-      return loaded?.module === from ? { ...loaded, from } : null;
-    }
-    const loaded = await super.load(from);
-    if (!loaded) return null;
-    if (this.#map && known[loaded.module] !== loaded.from) await this.#keep({ ...known, [loaded.module]: loaded.from });
-    return { ...loaded, from: loaded.module };
-  }
-
-  async #known(): Promise<Record<string, string>> {
-    if (!this.#map) return {};
-    try {
-      return JSON.parse(await readFile(this.#map, 'utf8')) as Record<string, string>;
-    } catch {
-      return {};
-    }
-  }
-
-  async #keep(files: Record<string, string>): Promise<void> {
-    await mkdir(dirname(this.#map!), { recursive: true, mode: 0o700 });
-    await writeFile(`${this.#map!}.new`, `${JSON.stringify(files, null, 2)}\n`, { mode: 0o600 });
-    await rename(`${this.#map!}.new`, this.#map!);
-  }
-}
-
-// Where a Node harbor's module ids find their files.
-export const MODULES = 'modules.json';
-
-// One root request over a served harbor's socket, or undefined where none
-// is served.
-export const askServed = (dir: string, request: RootRequest): Promise<JsonObject | undefined> =>
-  new Promise((done, fail) => {
-    const socket = connect(socketOf(dir));
-    let text = '';
-    socket.once('connect', () => socket.write(`${JSON.stringify(request)}\n`));
-    socket.on('data', (chunk: Buffer) => {
-      text += chunk.toString('utf8');
-      const end = text.indexOf('\n');
-      if (end < 0) return;
-      socket.end();
-      done(JSON.parse(text.slice(0, end)) as JsonObject);
-    });
-    socket.once('error', (e: NodeJS.ErrnoException) => (e.code === 'ENOENT' || e.code === 'ECONNREFUSED' ? done(undefined) : fail(e)));
-  });
-
-export type NodeParts = {
-  readonly dir: string;
-  readonly modules?: readonly Module[];
-  // Whether its carriers wake, and whether it serves the root line.
-  readonly wakes?: boolean;
-  readonly serves?: boolean;
-};
-
-export class NodeTerrain extends PointerTerrain {
-  readonly dir: string;
-  readonly serves: boolean;
-  #server: Server | undefined;
-
-  constructor(parts: NodeParts) {
-    const entropy = new CryptoEntropy();
-    super({
-      entropy,
-      loader: new NodeLoader(parts.modules, parts.dir),
-      custody: new FolderCustody(parts.dir, entropy),
-      memory: new FolderMemory(parts.dir),
-      faculties: [tcpFaculty, webGround, webPush],
-      opens: [TCP_OPENING],
-      wakes: parts.wakes ?? true,
-    });
-    this.dir = parts.dir;
-    this.serves = parts.serves ?? true;
-  }
-
-  override async claim(): Promise<void> {
-    if ((await askServed(this.dir, {})) !== undefined) throw new Error(`a harbor is already served from ${this.dir}`);
-  }
-
-  // The root line on the socket. A socket file nobody answers on is a
-  // stale one, and is replaced.
-  override async stand(harbor: Harbor): Promise<void> {
-    if (!this.serves) return;
-    const root = socketOf(this.dir);
-    await rm(root, { force: true });
-    const server = createServer((socket) => {
-      let text = '';
-      socket.on('data', (chunk: Buffer) => {
-        text += chunk.toString('utf8');
-        for (let end = text.indexOf('\n'); end >= 0; end = text.indexOf('\n')) {
-          const line = text.slice(0, end);
-          text = text.slice(end + 1);
-          let value: unknown;
-          try {
-            value = JSON.parse(line);
-          } catch {
-            value = undefined;
-          }
-          void rootLine(harbor, value)
-            .catch(() => ({ error: 'the harbor threw' }))
-            .then((answer) => socket.write(`${JSON.stringify(answer)}\n`));
-        }
-      });
-      socket.on('error', () => socket.destroy());
-    });
-    await new Promise<void>((done) => server.listen(root, done));
-    await chmod(root, 0o600);
-    this.#server = server;
-  }
-
-  override async release(): Promise<void> {
-    const server = this.#server;
-    if (!server) return;
-    this.#server = undefined;
-    await new Promise((done) => server.close(done));
-    await rm(socketOf(this.dir), { force: true });
-  }
-}
-
-// Node, and the engines that answer as Node does.
-export const nodeGround: GroundProbe = {
-  name: NODE,
-  fits: () => typeof process !== 'undefined' && typeof process.versions?.node === 'string',
-  terrain: ({ modules, where }) => new NodeTerrain({ dir: where ?? harborDir(), ...(modules ? { modules } : {}) }),
-};

package/src/pointer/bodies.ts

@@ -1,82 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The pointer terrain's bodies: each contract fulfilled in one process,
-// with nothing beyond JavaScript.
-import { Clock, Custody, Entropy, Loader, Memory, type Loaded, type Module } from '../contract/index.ts';
-
-export class CryptoEntropy extends Entropy {
-  draw(length: number): Uint8Array {
-    return globalThis.crypto.getRandomValues(new Uint8Array(length));
-  }
-}
-
-export class SystemClock extends Clock {
-  now(): number {
-    return Date.now();
-  }
-  wait(ms: number): { done: Promise<void>; cancel(): void } {
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const done = new Promise<void>((resolve) => (timer = setTimeout(resolve, ms)));
-    return { done, cancel: () => clearTimeout(timer) };
-  }
-}
-
-// The harbor's seed, drawn once and held by this object.
-export class HeldCustody extends Custody {
-  readonly #seed: Uint8Array;
-  constructor(entropy: Entropy) {
-    super();
-    this.#seed = entropy.draw(32);
-  }
-  seed(): Promise<Uint8Array> {
-    return Promise.resolve(this.#seed.slice());
-  }
-}
-
-// Modules handed to this object, found by the name each declares: the
-// bundle a ground with no disk to load from carries, an edge's or a
-// browser's. A path, a package or any other name is no module of it.
-export class HeldLoader extends Loader {
-  readonly #modules = new Map<string, Module>();
-  constructor(modules: readonly Module[] = []) {
-    super();
-    for (const m of modules) this.#modules.set(m.module, m);
-  }
-  load(from: string): Promise<Loaded | null> {
-    const m = this.#modules.get(from);
-    return Promise.resolve(m ? { module: m.module, version: m.version, classes: m.classes, from } : null);
-  }
-  override missing(from: string): string {
-    const carried = [...this.#modules.keys()];
-    return `${from} is no module this bundle carries${carried.length === 0 ? ', and it carries none' : `: it carries ${carried.join(', ')}`}`;
-  }
-}
-
-// Entries that live as long as this object, copied in and out, which is
-// what a restart in one process finds.
-export class VolatileMemory extends Memory {
-  readonly #places = new Map<string, Map<string, Uint8Array>>();
-  read(place: string): Promise<Map<string, Uint8Array>> {
-    const entries = this.#places.get(place) ?? new Map<string, Uint8Array>();
-    return Promise.resolve(new Map([...entries].map(([name, bytes]) => [name, bytes.slice()])));
-  }
-  // One object holds it, so a keep is whole by the run of one turn.
-  write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void> {
-    let kept = this.#places.get(place);
-    if (!kept) this.#places.set(place, (kept = new Map()));
-    for (const [name, bytes] of entries) {
-      if (bytes === null) kept.delete(name);
-      else kept.set(name, bytes.slice());
-    }
-    if (kept.size === 0) this.#places.delete(place);
-    return Promise.resolve();
-  }
-
-  places(): Promise<string[]> {
-    return Promise.resolve([...this.#places.keys()]);
-  }
-
-  forget(place: string): Promise<void> {
-    this.#places.delete(place);
-    return Promise.resolve();
-  }
-}

package/src/pointer/index.ts

@@ -1,4 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The pointer dock: a whole world with `nervur` alone.
-export { CryptoEntropy, HeldCustody, HeldLoader, SystemClock, VolatileMemory } from './bodies.ts';
-export { NoCarrier, PointerCarrier, PointerTerrain, World, type PointerParts } from './world.ts';