nervur 0.19.2 → 0.20.0

package/src/quo/standing.ts

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: Apache-2.0
+// The standing's side of a relation: it seals asks and reads replies, and
+// moves to its announced key and the following edge key when an object
+// comes back to an ask above every ask it has moved on, and on nothing else.
+//
+// Its state is a value, so a ward keeps it in its partition.
+import { encapsulate, hex, unhex } from '../crypto/index.ts';
+import type { Invitation } from './invitation.ts';
+import { Ephemeral, SigningKey, wardHalves, type Draw } from './keys.ts';
+import { writePayload } from './payload.ts';
+import { readReply, type Reply } from './reply.ts';
+import { checkBody, follow, knockEdge, openReply, sealAsk, signBody, splitBody } from './seal.ts';
+
+export type Read = Reply | { readonly nothing: true };
+
+// A knock that brought no object back: its bytes, sent again as they are,
+// and what the standing moves to if it bound.
+type Knock = { readonly bytes: string; readonly lid: string; readonly next: string; readonly edge: string; readonly seq: number };
+
+export type StandingState = {
+  readonly key: string | null;
+  readonly edge: string | null;
+  readonly sent: number;
+  readonly moved: number;
+  readonly knock: Knock | null;
+  // Whether the last ask after an unanswered knock asked under its own key,
+  // so the next sends the knock again.
+  readonly probed: boolean;
+};
+
+export const freshStanding = (): StandingState => ({ key: null, edge: null, sent: 0, moved: 0, knock: null, probed: false });
+
+// One ask out: what `read` needs to read its reply and to move.
+export type Sent = { readonly bytes: Uint8Array; readonly lid: Ephemeral; readonly next: string; readonly edge: string; readonly seq: number };
+
+export class Standing {
+  readonly invitation: Invitation;
+  state: StandingState;
+  readonly draw: Draw;
+
+  constructor(invitation: Invitation, state: StandingState, draw: Draw) {
+    this.invitation = invitation;
+    this.state = state;
+    this.draw = draw;
+  }
+
+  async ask(method?: string, args?: string): Promise<Sent | null> {
+    const s = this.state;
+    if (s.key !== null) return this.#ask(unhex(s.key), unhex(s.edge!), method, args);
+    if (s.knock === null) return this.#knock(method, args);
+    if (!s.probed) {
+      this.state = { ...s, probed: true };
+      return this.#ask(unhex(s.knock.next), unhex(s.knock.edge), method, args);
+    }
+    this.state = { ...s, probed: false };
+    // The same bytes again: a new lid would be a new box.
+    return { bytes: unhex(s.knock.bytes), lid: await Ephemeral.from(unhex(s.knock.lid)), next: s.knock.next, edge: s.knock.edge, seq: s.knock.seq };
+  }
+
+  async read(sent: Sent, bytes: Uint8Array | null): Promise<Read> {
+    if (bytes === null) return { nothing: true };
+    const reply = await this.#open(sent, bytes);
+    if (reply === null) return { silence: true };
+    if ('object' in reply.text && sent.seq > this.state.moved) {
+      const edge = await follow(unhex(sent.edge), reply.agreement);
+      this.state = { ...this.state, key: sent.next, edge: hex(edge), moved: sent.seq, knock: null, probed: false };
+    }
+    return reply.text;
+  }
+
+  async #knock(method?: string, args?: string): Promise<Sent | null> {
+    const heir = await SigningKey.from(unhex(this.invitation.secret));
+    const next = await SigningKey.draw(this.draw);
+    const lid = await Ephemeral.draw(this.draw);
+    const sent = encapsulate(unhex(this.invitation.lock), this.draw(32));
+    if (sent === null) return null;
+    const edge = await knockEdge(sent.shared);
+    const seq = this.state.sent + 1;
+    const body = await this.#body(heir, next, seq, method, args);
+    const bytes = await sealAsk(lid, unhex(wardHalves(this.invitation.ward).padlock), unhex(this.invitation.heir), edge, body, sent.ciphertext);
+    if (bytes === null) return null;
+    this.state = { ...this.state, sent: seq, knock: { bytes: hex(bytes), lid: hex(lid.secret), next: hex(next.secret), edge: hex(edge), seq } };
+    return { bytes, lid, next: hex(next.secret), edge: hex(edge), seq };
+  }
+
+  async #ask(secret: Uint8Array, edge: Uint8Array, method?: string, args?: string): Promise<Sent | null> {
+    const by = await SigningKey.from(secret);
+    const next = await SigningKey.draw(this.draw);
+    const lid = await Ephemeral.draw(this.draw);
+    const seq = this.state.sent + 1;
+    const body = await this.#body(by, next, seq, method, args);
+    const bytes = await sealAsk(lid, unhex(wardHalves(this.invitation.ward).padlock), unhex(this.invitation.heir), edge, body);
+    if (bytes === null) return null;
+    this.state = { ...this.state, sent: seq };
+    return { bytes, lid, next: hex(next.secret), edge: hex(edge), seq };
+  }
+
+  #body(by: SigningKey, next: SigningKey, seq: number, method?: string, args?: string): Promise<Uint8Array> {
+    const text = writePayload({ to: this.invitation.heir, by: by.id, next: next.id, seq, ...(method === undefined ? {} : { method }), ...(args === undefined ? {} : { args }) });
+    return signBody(new TextEncoder().encode(text), by);
+  }
+
+  async #open(sent: Sent, bytes: Uint8Array): Promise<{ text: Reply; agreement: Uint8Array } | null> {
+    const opened = await openReply(bytes, sent.lid);
+    const body = opened && splitBody(opened.bytes);
+    if (!opened || !body) return null;
+    if (!(await checkBody(unhex(wardHalves(this.invitation.ward).signing), body))) return null;
+    const text = readReply(body.text);
+    return text && { text, agreement: opened.agreement };
+  }
+}

package/src/stand/main.ts

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+// The stand program: one JSON request a line on stdin, one answer a line on
+// stdout, until stdin closes.
+import { createInterface } from 'node:readline';
+import { Stand } from './stand.ts';
+
+const stand = new Stand((n) => globalThis.crypto.getRandomValues(new Uint8Array(n)));
+const pending: Promise<void>[] = [];
+
+for await (const line of createInterface({ input: process.stdin, crlfDelay: Infinity })) {
+  if (line === '') continue;
+  pending.push(
+    stand.handle(line).then(
+      (answer) => void process.stdout.write(`${JSON.stringify(answer)}\n`),
+      (error: unknown) => void process.stderr.write(`${String(error)}\n`),
+    ),
+  );
+}
+await Promise.all(pending);

package/src/stand/stand.ts

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: Apache-2.0
+// The stand of `quo/vectors/HARNESS.md`, part one, over `quo/` alone. Part
+// two carries bytes over TCP, which is the dock's, so its three requests
+// are `bad request`.
+import { hex, isHex, unhex } from '../crypto/index.ts';
+import { Door, freshStanding, MemoryRelations, readInvitation, Standing, WardKey, type Behind, type Choice, type Draw, type Invitation, type Payload, type Read, type Sent } from '../quo/index.ts';
+
+type Answer = Record<string, unknown>;
+const ERRORS = ['bad request', 'no such op', 'no such ward', 'not reached', 'ward stood', 'name held'] as const;
+type Error = (typeof ERRORS)[number];
+class Refused {
+  readonly error: Error;
+  constructor(error: Error) {
+    this.error = error;
+  }
+}
+const refuse = (error: Error): never => {
+  throw new Refused(error);
+};
+
+// What the verifier names behind a door.
+const REACHES: Record<string, (p: Payload) => Choice> = {
+  echo: (p) => ({ object: p.method === undefined ? '{}' : (p.args ?? '{}'), seen: null }),
+  marked: (p) => ({ object: p.method === undefined ? '{}' : (p.args ?? '{}'), seen: p.method === undefined ? null : '1' }),
+  null: () => ({ object: 'null', seen: null }),
+  silent: () => ({ silence: true }),
+};
+
+class StandWard implements Behind {
+  readonly door: Door;
+  readonly zero: boolean;
+  readonly #zero: string | undefined;
+  readonly names = new Map<string, string>();
+  readonly reaches = new Map<string, string>();
+  readonly standings = new Map<string, { standing: Standing; last?: Sent }>();
+
+  constructor(key: WardKey, zero: string | undefined, draw: Draw) {
+    this.#zero = zero;
+    this.zero = zero !== undefined;
+    this.door = new Door(key, new MemoryRelations(), this, draw);
+  }
+
+  answer(heir: string | null, p: Payload): Promise<Choice> {
+    const reach = heir === null ? this.#zero! : this.reaches.get(heir);
+    return Promise.resolve(reach === undefined ? { silence: true } : REACHES[reach]!(p));
+  }
+}
+
+const OPS = new Set(['ward', 'invite', 'release', 'arrive', 'ask', 'read', 'listen', 'route', 'send']);
+
+export class Stand {
+  readonly #wards = new Map<string, StandWard>();
+  readonly #draw: Draw;
+
+  constructor(draw: Draw) {
+    this.#draw = draw;
+  }
+
+  async handle(line: string): Promise<Answer> {
+    let request: unknown;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      return { id: null, error: 'bad request' };
+    }
+    if (typeof request !== 'object' || request === null || Array.isArray(request)) return { id: null, error: 'bad request' };
+    const r = request as Record<string, unknown>;
+    if (typeof r.id !== 'string') return { id: null, error: 'bad request' };
+    try {
+      return { id: r.id, ...(await this.#op(r)) };
+    } catch (e) {
+      if (e instanceof Refused) return { id: r.id, error: e.error };
+      throw e;
+    }
+  }
+
+  async #op(r: Record<string, unknown>): Promise<Answer> {
+    if (typeof r.op !== 'string') return refuse('bad request');
+    if (!OPS.has(r.op)) return refuse('no such op');
+    switch (r.op) {
+      case 'ward':
+        return this.#ward(text(r.seed), optional(r.reach));
+      case 'invite':
+        return this.#invite(r);
+      case 'release':
+        return this.#release(r);
+      case 'arrive':
+        return this.#arrive(r);
+      case 'ask':
+        return this.#ask(r);
+      case 'read':
+        return this.#read(r);
+      default:
+        return refuse('bad request');
+    }
+  }
+
+  async #ward(seed: string, reach: string | undefined): Promise<Answer> {
+    reached(reach);
+    const key = await WardKey.from(seed);
+    if (this.#wards.has(key.pk)) refuse('ward stood');
+    this.#wards.set(key.pk, new StandWard(key, reach, this.#draw));
+    return { ward: key.pk };
+  }
+
+  async #invite(r: Record<string, unknown>): Promise<Answer> {
+    const name = text(r.heir);
+    const reach = optional(r.reach) ?? 'echo';
+    const ward = this.#ward_(r.ward);
+    reached(reach);
+    if (ward.names.has(name)) refuse('name held');
+    const { heir, invitation } = await ward.door.invite();
+    ward.names.set(name, heir);
+    ward.reaches.set(heir, reach);
+    return { invitation };
+  }
+
+  #release(r: Record<string, unknown>): Answer {
+    const name = text(r.heir);
+    const ward = this.#ward_(r.ward);
+    const heir = ward.names.get(name);
+    if (heir === undefined) return { released: null };
+    ward.names.delete(name);
+    ward.door.remove(heir);
+    return { released: name };
+  }
+
+  async #arrive(r: Record<string, unknown>): Promise<Answer> {
+    const box = r.box;
+    if (!isHex(box)) return refuse('bad request');
+    const ward = this.#ward_(r.ward);
+    const judged = await ward.door.arrive(unhex(box));
+    return { reply: hex(judged.bytes) };
+  }
+
+  async #ask(r: Record<string, unknown>): Promise<Answer> {
+    const invitation = inviteOf(r.invitation);
+    const method = r.method === undefined ? undefined : text(r.method);
+    const args = r.args === undefined ? undefined : objectText(r.args);
+    const ward = this.#ward_(r.ward);
+    const held = this.#standing(ward, invitation);
+    const sent = await held.standing.ask(method, args);
+    if (sent === null) return refuse('bad request');
+    held.last = sent;
+    return { box: hex(sent.bytes) };
+  }
+
+  async #read(r: Record<string, unknown>): Promise<Answer> {
+    const invitation = inviteOf(r.invitation);
+    if (r.reply !== null && !isHex(r.reply)) return refuse('bad request');
+    const ward = this.#ward_(r.ward);
+    const held = this.#standing(ward, invitation);
+    if (held.last === undefined) return refuse('bad request');
+    const read = await held.standing.read(held.last, r.reply === null ? null : unhex(r.reply as string));
+    return { read: readOf(read) };
+  }
+
+  #standing(ward: StandWard, invitation: Invitation): { standing: Standing; last?: Sent } {
+    const key = `${invitation.ward}.${invitation.heir}`;
+    let held = ward.standings.get(key);
+    if (!held) ward.standings.set(key, (held = { standing: new Standing(invitation, freshStanding(), this.#draw) }));
+    return held;
+  }
+
+  #ward_(pk: unknown): StandWard {
+    if (!isHex(pk, 64)) return refuse('bad request');
+    return this.#wards.get(pk) ?? refuse('no such ward');
+  }
+}
+
+const text = (value: unknown): string => (typeof value === 'string' ? value : refuse('bad request'));
+const optional = (value: unknown): string | undefined => (value === undefined ? undefined : text(value));
+const reached = (reach: string | undefined): void => {
+  if (reach !== undefined && !Object.hasOwn(REACHES, reach)) refuse('not reached');
+};
+const inviteOf = (value: unknown): Invitation => readInvitation(value) ?? refuse('bad request');
+const objectText = (value: unknown): string => (typeof value === 'object' && value !== null && !Array.isArray(value) ? JSON.stringify(value) : refuse('bad request'));
+const readOf = (read: Read): unknown => ('object' in read ? { object: JSON.parse(read.object) as unknown, seen: read.seen } : read);

package/src/ward/allowance.ts

@@ -1,85 +1,47 @@
 // SPDX-License-Identifier: Apache-2.0
-// The allowance. Every ask carries, in its signed body, the time it may still
-// spend, in milliseconds. A being who says nothing gets her ward's default and
-// never thinks about it; one who wants to say so passes a third argument, and
-// is held to the ward's ceiling. The door reads it before anything is done
-// under it and refuses a budget already gone, as one silence like every other
-// refusal there. The sender bounds the whole of her ask to the same number,
-// and a wait that ran out is the word late, never silence and never unreached.
-//
-// Each ask is bounded on its own. The time an arriving call has left does not
-// bound the asks a being makes while answering it: attributing her onward ask
-// to the arrival that caused it needs a context the ward cannot get without
-// naming a runtime, and the ward names none. Every wait still ends.
+// The allowance: how long a being waits on one ask. It is on no wire. A
+// being who says nothing gets the default, and nobody gets past the
+// ceiling.
+import type { Clock } from '../contract/index.ts';
+import type { Wanted } from '../being/index.ts';
 
-// What a being may ask for is Wanted, and it belongs to the stance, where she
-// reads it. This file holds only what the ward does with it.
-import type { Wanted } from '../being/types.ts';
+export const DEFAULT = 30_000;
+export const CEILING = 300_000;
 
-// A budget, as it crosses a door. Time in milliseconds.
-export type Allowance = { time: number };
+export const allow = (wanted: Wanted | undefined): number => {
+  const whole = typeof wanted?.time === 'number' ? Math.floor(wanted.time) : NaN;
+  return Math.min(Number.isFinite(whole) && whole > 0 ? whole : DEFAULT, CEILING);
+};
 
-// How wide the default is, and how wide she may ask for, are the ward's own —
-// wider is more patient, and no peer can tell the difference except by being
-// refused. A being who never learns the third parameter exists writes correct
-// code forever under these. They are two numbers because the third argument
-// goes both ways: less for the ask she wants back quickly, more for the one
-// she knows is slow.
-export const DEFAULT: Allowance = { time: 30_000 };
-export const CEILING: Allowance = { time: 300_000 };
+export const LATE: unique symbol = Symbol('late');
+export type Late = typeof LATE;
 
-// What she asked for, held to what her ward allows. A being cannot mint budget
-// nobody granted her: asking for a minute where the ward gives thirty seconds
-// is thirty seconds, silently, because the ceiling is not hers to know.
-// Asking for nothing at all is the default, which is the whole point.
-export function allow(wanted: Wanted | undefined, ceiling: Allowance = CEILING, base: Allowance = DEFAULT): Allowance {
-  // Floored first, then tested: a fraction of a millisecond is not a budget,
-  // and falls to the default like every other number that is not a positive
-  // whole one.
-  const whole = (n: unknown, fallback: number) => {
-    const w = typeof n === 'number' ? Math.floor(n) : NaN;
-    return Number.isFinite(w) && w > 0 ? w : fallback;
-  };
-  return { time: Math.min(whole(wanted?.time, base.time), ceiling.time) };
-}
+// One ask's bell. It bounds the wait of the being who asked and the send
+// that holds the relation's line, so a far side that never answers holds
+// neither for longer than the allowance.
+export class Bell {
+  readonly #wait: { done: Promise<void>; cancel(): void };
+  readonly #late: Promise<Late>;
+  #rang = false;
 
-// Whether a budget has anything left to spend, and the one reader of it: the
-// door calls this on arrival and nothing else asks the question anywhere. A
-// time that is not a whole number above zero is not a budget that ran out, it
-// is no budget at all, and the door refuses both the same way, since a peer
-// learns nothing from the difference. `allow` never makes one, so only bytes
-// off the road ever carry one.
-export const spent = (a: Allowance): boolean => !(Number.isSafeInteger(a.time) && a.time > 0);
+  constructor(clock: Clock, ms: number) {
+    this.#wait = clock.wait(ms);
+    this.#late = this.#wait.done.then((): Late => {
+      this.#rang = true;
+      return LATE;
+    });
+  }
 
-// What a wait that ran out comes back as. Its own value, held by nobody
-// outside the ward, so no answer from any door can be mistaken for it.
-export const LATE = Symbol('late');
+  get rang(): boolean {
+    return this.#rang;
+  }
+
+  race<T>(work: Promise<T>): Promise<T | Late> {
+    work.catch(() => {});
+    return Promise.race([work, this.#late]);
+  }
 
-// A wait with an end. This is the one thing the ward times, and it covers the
-// whole of an ask, not only the wire: a relation that comes back round is
-// stopped at its own lane, before a single byte is sealed, and a bound that
-// only watched the wire would never see it. A timer is the only way to stop
-// waiting and every language that runs Quo has one; no runtime is named here.
-//
-// `rang` is called the moment the bell rings, before anyone waiting on the
-// wait is told: whoever holds work that has not started yet reads it and does
-// not start it. What comes back late is not read, and what has not left yet
-// does not leave.
-export async function within<T>(ms: number, work: Promise<T>, rang?: () => void): Promise<T | typeof LATE> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const bell = new Promise<typeof LATE>((ring) => {
-    timer = setTimeout(() => {
-      rang?.();
-      ring(LATE);
-    }, ms);
-  });
-  try {
-    return await Promise.race([work, bell]);
-  } finally {
-    clearTimeout(timer);
-    void work.then(
-      () => {},
-      () => {},
-    ); // whatever it was, it is nobody's answer now
+  cancel(): void {
+    this.#wait.cancel();
   }
 }