nervur 0.20.1 → 0.20.2

package/src/http/websocket.ts

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+// The server side of RFC 6455, as far as a held line needs it: the accept
+// key, frames written plain, and a reader of masked frames that joins
+// fragments into messages and stops at the first byte that breaks the RFC
+// or a message longer than it takes.
+import { createHash } from 'node:crypto';
+
+const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+export const OP = { continuation: 0x0, text: 0x1, binary: 0x2, close: 0x8, ping: 0x9, pong: 0xa } as const;
+
+export const acceptKey = (key: string): string =>
+  createHash('sha1')
+    .update(key + GUID)
+    .digest('base64');
+
+export const isClientKey = (key: unknown): key is string => typeof key === 'string' && /^[A-Za-z0-9+/]{22}==$/.test(key);
+
+// One frame as a server writes it: final, unmasked.
+export const frameOf = (opcode: number, payload: Uint8Array = new Uint8Array(0)): Uint8Array => {
+  const length = payload.length;
+  const extended = length < 126 ? 0 : length < 65_536 ? 2 : 8;
+  const out = new Uint8Array(2 + extended + length);
+  const view = new DataView(out.buffer);
+  out[0] = 0x80 | opcode;
+  out[1] = extended === 0 ? length : extended === 2 ? 126 : 127;
+  if (extended === 2) view.setUint16(2, length);
+  if (extended === 8) view.setBigUint64(2, BigInt(length));
+  out.set(payload, 2 + extended);
+  return out;
+};
+
+export type WsEvent = { type: 'binary'; data: Uint8Array } | { type: 'text' } | { type: 'ping'; data: Uint8Array } | { type: 'close' } | { type: 'bad' };
+
+// Frames a client wrote, masked, read as they come.
+export class WsReader {
+  readonly #max: number;
+  #buffer = new Uint8Array(0);
+  #parts: Uint8Array[] | null = null;
+  #partsLength = 0;
+  #partsText = false;
+  #done = false;
+
+  constructor(max: number) {
+    this.#max = max;
+  }
+
+  push(chunk: Uint8Array): WsEvent[] {
+    if (this.#done) return [];
+    const joined = new Uint8Array(this.#buffer.length + chunk.length);
+    joined.set(this.#buffer);
+    joined.set(chunk, this.#buffer.length);
+    this.#buffer = joined;
+    const out: WsEvent[] = [];
+    while (this.#buffer.length >= 2) {
+      const b0 = this.#buffer[0]!;
+      const b1 = this.#buffer[1]!;
+      const fin = (b0 & 0x80) !== 0;
+      const opcode = b0 & 0x0f;
+      const masked = (b1 & 0x80) !== 0;
+      if ((b0 & 0x70) !== 0 || !masked) return this.#bad(out);
+      let length = b1 & 0x7f;
+      let at = 2;
+      const view = new DataView(this.#buffer.buffer, this.#buffer.byteOffset, this.#buffer.length);
+      if (length === 126) {
+        if (this.#buffer.length < 4) break;
+        length = view.getUint16(2);
+        at = 4;
+      } else if (length === 127) {
+        if (this.#buffer.length < 10) break;
+        const long = view.getBigUint64(2);
+        if (long > BigInt(this.#max)) return this.#bad(out);
+        length = Number(long);
+        at = 10;
+      }
+      const control = opcode >= 0x8;
+      if (control && (length > 125 || !fin)) return this.#bad(out);
+      if (!control && this.#partsLength + length > this.#max) return this.#bad(out);
+      if (this.#buffer.length < at + 4 + length) break;
+      const mask = this.#buffer.subarray(at, at + 4);
+      const payload = this.#buffer.slice(at + 4, at + 4 + length);
+      for (let i = 0; i < payload.length; i += 1) payload[i]! ^= mask[i & 3]!;
+      this.#buffer = this.#buffer.slice(at + 4 + length);
+      if (opcode === OP.close) {
+        this.#done = true;
+        out.push({ type: 'close' });
+        return out;
+      }
+      if (opcode === OP.ping) out.push({ type: 'ping', data: payload });
+      else if (opcode === OP.pong) continue;
+      else if (opcode === OP.text || opcode === OP.binary) {
+        if (this.#parts !== null) return this.#bad(out);
+        if (fin) out.push(opcode === OP.text ? { type: 'text' } : { type: 'binary', data: payload });
+        else {
+          this.#parts = [payload];
+          this.#partsLength = payload.length;
+          this.#partsText = opcode === OP.text;
+        }
+      } else if (opcode === OP.continuation) {
+        if (this.#parts === null) return this.#bad(out);
+        this.#parts.push(payload);
+        this.#partsLength += payload.length;
+        if (fin) {
+          const whole = new Uint8Array(this.#partsLength);
+          let o = 0;
+          for (const part of this.#parts) {
+            whole.set(part, o);
+            o += part.length;
+          }
+          out.push(this.#partsText ? { type: 'text' } : { type: 'binary', data: whole });
+          this.#parts = null;
+          this.#partsLength = 0;
+        }
+      } else return this.#bad(out);
+    }
+    return out;
+  }
+
+  #bad(out: WsEvent[]): WsEvent[] {
+    this.#done = true;
+    this.#buffer = new Uint8Array(0);
+    out.push({ type: 'bad' });
+    return out;
+  }
+}

package/src/index.ts

@@ -1,6 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // `nervur`: what a stranger writes a world with. It imports no platform, so
-// it runs wherever JavaScript runs. A disk is `nervur/folder`.
+// it runs wherever JavaScript runs. A disk is `nervur/folder`. Node reads
+// `node.ts` under this name instead, which adds the Node ground.
+import { addGround } from './harbor/index.ts';
+import { neutralGround } from './line/index.ts';
 
 // Beings, faculties, and what they are told.
 export { Being, canonical, digest, Faculty, isSilence, isWord, OWNER, silence, told, WARD, word } from './being/index.ts';
@@ -14,7 +17,37 @@ export { Carrier, Clock, Custody, Entropy, Loader, Memory, type Loaded, type Mod
 export { CEILING, DEFAULT, DEPTH, ownerAsk, Pilot, pilots, WardBeing, type Steward, type WardBeingStance } from './ward/index.ts';
 
 // The onion, and the one line its root's asks cross from any front.
-export { BOX, Catalogue, Dock, Harbor, readRootRequest, Registry, rootLine, Terrain, type RootRequest } from './harbor/index.ts';
+export {
+  BOX,
+  CarrierFaculty,
+  Catalogue,
+  copyPackage,
+  Dock,
+  Harbor,
+  addGround,
+  grounds,
+  readRootRequest,
+  Registry,
+  Push,
+  PUSH,
+  RELAY,
+  RELAY_CLIENT,
+  rootLine,
+  Terrain,
+  UNDIALED,
+  type Dialed,
+  type Failures,
+  type Ground,
+  type GroundFaculty,
+  type GroundProbe,
+  type Opening,
+  type Probing,
+  type RootRequest,
+} from './harbor/index.ts';
 
 // The pointer dock: a whole world in one process.
 export { CryptoEntropy, HeldCustody, HeldLoader, NoCarrier, PointerCarrier, PointerTerrain, SystemClock, VolatileMemory, World, type PointerParts } from './pointer/index.ts';
+export { NEUTRAL, WEB, WEB_OPENING, WEB_PUSH, WebDialer, webFaculty, webPush, type WebListen, type WebListener, type WebServe } from './line/index.ts';
+
+// The ground that fits everywhere, tried after any a platform entry adds.
+addGround(neutralGround);

package/src/line/answer.ts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+// The web carrier's inbound side on the standard Request and Response,
+// for a ground whose engine hands its code a request: a post answered, and
+// a held line's messages, whatever socket the engine gives.
+//
+// A post is one ask: 200 with the reply's box, or 204 for nothing. A post
+// to another path is 404, another method 405, a body that is no ask 400.
+// A page of an origin the listen names, or of any under `*`, is answered
+// as the CORS protocol says, its preflight included.
+import { hex } from '../crypto/index.ts';
+import type { Ground } from '../harbor/index.ts';
+import { nothingBody, readBody, replyBody } from './frame.ts';
+import { MAX_POST, readPost, type WebListen } from './web.ts';
+
+const allowedOrigin = (origins: readonly string[], origin: string | null): string | null => {
+  if (origin === null) return null;
+  if (origins.includes('*')) return '*';
+  return origins.includes(origin) ? origin : null;
+};
+
+export const answerPost = async (ground: Ground, listen: WebListen, request: Request): Promise<Response> => {
+  const headers = new Headers();
+  const allowed = allowedOrigin(listen.origins, request.headers.get('origin'));
+  if (allowed !== null) headers.set('access-control-allow-origin', allowed);
+  if (new URL(request.url).pathname !== listen.path) return new Response(null, { status: 404, headers });
+  if (request.method === 'OPTIONS') {
+    if (allowed !== null) {
+      headers.set('access-control-allow-methods', 'POST');
+      headers.set('access-control-allow-headers', 'content-type');
+    }
+    return new Response(null, { status: 204, headers });
+  }
+  if (request.method !== 'POST') {
+    headers.set('allow', 'POST, OPTIONS');
+    return new Response(null, { status: 405, headers });
+  }
+  const body = new Uint8Array(await request.arrayBuffer());
+  const ask = body.length > MAX_POST ? null : readPost(body);
+  if (ask === null) return new Response(null, { status: 400, headers });
+  const reply = await ground.arrive(ask.pk, ask.box).catch(() => null);
+  if (reply === null || reply.length === 0) return new Response(null, { status: 204, headers });
+  headers.set('content-type', 'application/octet-stream');
+  return new Response(new Uint8Array(reply), { status: 200, headers });
+};
+
+// What a held line answers with: a binary message back, or the line closed.
+export type HeldSide = { send(body: Uint8Array): void; close(): void };
+
+// One message on a held line: an ask answered on the same line, a text
+// message or a body that is no frame closing it, and anything else let be.
+export const answerHeld = (ground: Ground, side: HeldSide, message: Uint8Array | string): void => {
+  const frame = typeof message === 'string' ? null : readBody(message);
+  if (frame === null) return side.close();
+  if (frame.kind !== 'ask') return;
+  void ground
+    .arrive(hex(frame.pk), frame.box)
+    .catch(() => null)
+    .then((reply) => side.send(reply === null ? nothingBody(frame.id) : replyBody(frame.id, reply)));
+};

package/src/line/frame.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+// The frames of `quo/CARRIER-TCP.md`, which the held line of
+// `quo/CARRIER-WEB.md` carries too, one body to a message:
+//
+//   frame = length (4, big-endian) || body
+//   body  = kind (1) || id (4, big-endian) || rest
+//   00 ask      rest = ward pk (64) || box
+//   01 reply    rest = box
+//   02 nothing  rest = empty
+//
+// A reader says bytes are not a frame as soon as they say so, and reads
+// nothing after them.
+import { concat } from '../crypto/index.ts';
+
+// The kind of a TCP carrier faculty, whichever ground's body it is, and
+// the faculty a ground that speaks TCP opens at genesis under `tcp`.
+export const TCP = 'org.nervur.tcp';
+export const TCP_OPENING = { key: 'tcp', kind: TCP } as const;
+
+export const ASK = 0;
+export const REPLY = 1;
+export const NOTHING = 2;
+export const MAX_BODY = 1_048_645;
+const PK = 64;
+
+export type Frame = { kind: 'ask'; id: number; pk: Uint8Array; box: Uint8Array } | { kind: 'reply'; id: number; box: Uint8Array } | { kind: 'nothing'; id: number };
+
+const body = (kind: number, id: number, ...rest: Uint8Array[]): Uint8Array => {
+  const head = new Uint8Array(5);
+  head[0] = kind;
+  new DataView(head.buffer).setUint32(1, id >>> 0);
+  return concat(head, ...rest);
+};
+const framed = (b: Uint8Array): Uint8Array => {
+  const length = new Uint8Array(4);
+  new DataView(length.buffer).setUint32(0, b.length);
+  return concat(length, b);
+};
+
+export const askBody = (id: number, pk: Uint8Array, box: Uint8Array): Uint8Array => body(ASK, id, pk, box);
+export const replyBody = (id: number, box: Uint8Array): Uint8Array => body(REPLY, id, box);
+export const nothingBody = (id: number): Uint8Array => body(NOTHING, id);
+export const askFrame = (id: number, pk: Uint8Array, box: Uint8Array): Uint8Array => framed(askBody(id, pk, box));
+export const replyFrame = (id: number, box: Uint8Array): Uint8Array => framed(replyBody(id, box));
+export const nothingFrame = (id: number): Uint8Array => framed(nothingBody(id));
+
+// Whether a body of this length, and this first byte when known, is no frame.
+const notAFrame = (length: number, kind: number | undefined): boolean =>
+  length > MAX_BODY || length < 5 || (kind !== undefined && (kind > NOTHING || (kind === ASK && length < 5 + PK) || (kind === NOTHING && length !== 5)));
+
+// One whole body, read, or null for bytes that are no frame.
+export const readBody = (b: Uint8Array): Frame | null => {
+  if (notAFrame(b.length, b[0])) return null;
+  const id = new DataView(b.buffer, b.byteOffset).getUint32(1);
+  if (b[0] === ASK) return { kind: 'ask', id, pk: b.slice(5, 5 + PK), box: b.slice(5 + PK) };
+  if (b[0] === REPLY) return { kind: 'reply', id, box: b.slice(5) };
+  return { kind: 'nothing', id };
+};
+
+// Frames out of a stream, each with its length in front.
+export class FrameReader {
+  #buffer: Uint8Array = new Uint8Array(0);
+  #bad = false;
+
+  // True once bytes that are not a frame arrived; nothing is read after.
+  get bad(): boolean {
+    return this.#bad;
+  }
+
+  push(chunk: Uint8Array): Frame[] {
+    if (this.#bad) return [];
+    this.#buffer = this.#buffer.length === 0 ? chunk.slice() : concat(this.#buffer, chunk);
+    const out: Frame[] = [];
+    while (this.#buffer.length >= 4) {
+      const length = new DataView(this.#buffer.buffer, this.#buffer.byteOffset).getUint32(0);
+      if (notAFrame(length, this.#buffer.length > 4 ? this.#buffer[4] : undefined)) {
+        this.#bad = true;
+        this.#buffer = new Uint8Array(0);
+        return out;
+      }
+      if (this.#buffer.length < 4 + length) break;
+      const frame = readBody(this.#buffer.subarray(4, 4 + length))!;
+      this.#buffer = this.#buffer.slice(4 + length);
+      out.push(frame);
+    }
+    return out;
+  }
+}

package/src/line/ground.ts

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+// The ground that fits wherever JavaScript runs, and the one the main
+// entry adds: the pointer bodies, so the harbor lives as long as its
+// process, the modules it is handed, and the web as its one carrier,
+// opened at genesis to ask, with Web Push beside it. A ground whose
+// bodies keep a harbor, a browser's or an edge's, is added by its own
+// entry and tried before this one.
+import type { GroundProbe } from '../harbor/index.ts';
+import { HeldLoader, PointerTerrain } from '../pointer/index.ts';
+import { webPush } from './push.ts';
+import { WEB_OPENING, webFaculty } from './web.ts';
+
+export const NEUTRAL = 'neutral';
+
+export const neutralGround: GroundProbe = {
+  name: NEUTRAL,
+  fits: () => true,
+  terrain: ({ modules = [] }) => new PointerTerrain({ loader: new HeldLoader(modules), faculties: [webFaculty(), webPush], opens: [WEB_OPENING] }),
+};

package/src/line/index.ts

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
+// The lines Quo is carried on, with no platform under them: the frames
+// both published carriers share, the web carrier on fetch and the
+// WebSocket client, and a ring with no content as Web Push sends it.
+export { ASK, askBody, askFrame, FrameReader, MAX_BODY, NOTHING, nothingBody, nothingFrame, readBody, REPLY, replyBody, replyFrame, TCP, TCP_OPENING, type Frame } from './frame.ts';
+export { answerHeld, answerPost, type HeldSide } from './answer.ts';
+export { NEUTRAL, neutralGround } from './ground.ts';
+export { base64url, PUSH_TTL, pushEndpoint, VAPID_LIFE, WEB_PUSH, webPush } from './push.ts';
+export { MAX_POST, MIN_POST, readPost, WEB, WEB_OPENING, WebDialer, webFaculty, type WebListen, type WebListener, type WebServe } from './web.ts';

package/src/line/push.ts

@@ -0,0 +1,112 @@
+// 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;
+    }
+  };