nervur 0.19.2 → 0.20.0

package/src/ward/heirs.ts

@@ -1,116 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Heirs. The door's view of every occupant of every being in the ward, by
-// the heir pk the invitation carried. One rule: the key I hold for you may
-// speak, and so may the key it announced last time. A knock is the first
-// use of the heir, which the inviter announced on your behalf, and the heir
-// dies as it speaks.
-import type { DoorWord } from '../being/types.ts';
-import { GONE, type Heir, type Partition } from './partition.ts';
-
-// How wide the span is, is the spec's and never a ward's. Wider is more
-// forgiving of a rough road, and that is exactly why it is not a ward's to
-// choose: a peer tells two doors apart by being refused at one and answered
-// at the other, which is one relation dying over one number.
-const SPAN = 64;
-
-export class Heirs {
-  #p: Partition;
-  #wrote: () => void;
-  constructor(p: Partition, wrote: () => void = () => {}) {
-    this.#p = p;
-    this.#wrote = wrote;
-  }
-  open(heir: string, being: string, id: string): void {
-    this.#p.heirs[heir] = { being, id, current: heir, announced: null, fresh: true, mark: 0, spent: [] };
-    this.#wrote();
-  }
-  // The id was removed. The heir is forgotten, and its last keys are kept
-  // apart, bounded, so that whoever still holds them hears `removed` at the
-  // door, once they have signed as themselves, and nobody else hears a thing.
-  close(heir: string): void {
-    const h = this.#p.heirs[heir];
-    if (!h) return;
-    delete this.#p.heirs[heir];
-    this.#p.gone[heir] = { current: h.current, announced: h.announced };
-    const keys = Object.keys(this.#p.gone);
-    for (const old of keys.slice(0, Math.max(0, keys.length - GONE))) delete this.#p.gone[old];
-    this.#wrote();
-  }
-  // May `by` speak for a relation she removed? True only for the keys the
-  // door held when the id went, which nobody but their holder has.
-  gone(heir: string, by: string): boolean {
-    const g = this.#p.gone[heir];
-    return !!g && (by === g.current || by === g.announced);
-  }
-  // May `by` speak for this heir? Returns the record if so, null if not.
-  // Does not write: the caller verifies the signature first, then settles.
-  admits(heir: string, by: string): Heir | null {
-    const h = this.#p.heirs[heir];
-    if (!h) return null;
-    if (h.fresh) return by === h.current ? h : null;
-    return by === h.current || by === h.announced ? h : null;
-  }
-  // Once only. A number above the mark is honoured and moves it; a number
-  // inside the span is honoured once and never again; a number at or below
-  // the span is refused, because a door that remembered every number ever
-  // seen would be a door with unbounded memory. Counting starts where
-  // strangers must agree: the first legal number is one.
-  //
-  // The number rides inside the signed body, so bytes caught on the road
-  // carry the number they were sent under and are refused as themselves. A
-  // caller who means to ask again asks again, under the next number, and is
-  // heard: retry and fire-and-forget stay hers to build. Only the accident
-  // and the interception are refused.
-  //
-  // Writes, so the caller settles it only once the signature has checked out.
-  // The same bytes twice are one honoured call and one silence.
-  spend(h: Heir, seq: number): boolean {
-    if (!Number.isSafeInteger(seq) || seq < 1) return false;
-    if (seq > h.mark) {
-      if (h.mark > 0) h.spent.push(h.mark);
-      h.mark = seq;
-      h.spent = h.spent.filter((past) => past > seq - SPAN);
-      return true;
-    }
-    if (seq === h.mark || seq <= h.mark - SPAN || h.spent.includes(seq)) return false;
-    h.spent.push(seq);
-    return true;
-  }
-
-  // The signature checked out. Spend the number and settle the keys, or do
-  // neither: a call that binds nothing must not burn a number on its way to
-  // being refused, or a stranger who cannot be heard would still leave a mark
-  // behind her. Every write below this line is one that is going to hold.
-  // This is where a knock is judged and where `unannounced` is said. settle
-  // below is the writing alone, and it judges nothing: one owner for the
-  // question, one for the answer.
-  honour(h: Heir, by: string, next: string | null, seq: number): true | DoorWord {
-    if (h.fresh && (next === null || next === h.current)) return 'unannounced'; // a knock without a key of her own binds nothing, and the heir is not a key of her own
-    if (!this.spend(h, seq)) return 'repeated';
-    this.settle(h, by, next);
-    this.#wrote(); // the number and the keys moved together
-    return true;
-  }
-
-  // The signature checked out and honour has judged. Settle the keys: a fresh
-  // heir rotates at once to what it announced, which honour has already held
-  // to being something other than itself, so that the heir dies as it speaks;
-  // a current key replaces its announcement; an announced key becomes current.
-  settle(h: Heir, by: string, next: string | null): void {
-    if (h.fresh) {
-      if (next === null) return; // honour judged this. the compiler has not read it, so the narrowing stays.
-      h.current = next;
-      h.announced = null;
-      h.fresh = false;
-      return;
-    }
-    if (by === h.announced) h.current = by;
-    // A send that announced nothing leaves the spare standing. This kit
-    // announces on every send but a public one, which holds no heir and
-    // reaches none of this; a kit that skips one is a kit whose own next is
-    // still the key it announced last time, and forgetting it here would meet
-    // that key with silence and kill a healthy relation. Nothing is dropped
-    // that was vouched for until something replaces it.
-    if (next !== null) h.announced = next;
-  }
-}

package/src/ward/json.ts

@@ -1,144 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The one reader of JSON that crossed an edge. A runtime's own parser is
-// where two kits stop agreeing: it keeps the last of two keys of one name,
-// rounds a whole number no double holds, reads a number past the doubles as
-// infinity, and mends bytes that are not UTF-8 into a replacement character.
-// Each of those is text two kits read two ways, so each is refused here, where
-// it is read, with a throw the caller already turns into what bytes that said
-// nothing are.
-//
-// What a value is beyond its text, a lone surrogate, a key named `__proto__`,
-// a nesting past the bound, is the value rule's, and `cellFault` in cells.ts
-// is its one reader. This file holds the rules that live only in the text.
-
-const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
-
-const fail = (at: number, why: string): never => {
-  throw new Error(`JSON at ${at}: ${why}`);
-};
-
-// A number text, held to the Values chapter. A text naming a whole number
-// stands only if that number is exactly a double, or if the text is how
-// ECMAScript writes the double it reads as. A text past the largest double,
-// or naming a value other than zero that rounds to zero, is refused, and so
-// is minus zero in any spelling.
-export function numberFault(literal: string): string | null {
-  const m = /^(-?)(0|[1-9]\d*)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(literal);
-  if (!m) return 'not a number';
-  const [, sign, whole, frac = '', exp = '0'] = m;
-  const v = Number(literal);
-  if (!Number.isFinite(v)) return 'past the largest double';
-  let digits = (whole + frac).replace(/^0+/, '');
-  if (v === 0) {
-    if (digits !== '') return 'a value other than zero that rounds to zero';
-    return sign ? 'minus zero' : null;
-  }
-  // The exact value is digits times ten to e. A finite double bounds e from
-  // above, so the power below is never larger than the double's own width.
-  let e = BigInt(exp) - BigInt(frac.length);
-  const trimmed = digits.replace(/0+$/, '');
-  e += BigInt(digits.length - trimmed.length);
-  digits = trimmed;
-  if (e < 0n) return null; // a fraction: the double nearest it, as every reader takes it
-  const exact = BigInt(digits) * 10n ** e;
-  if (exact === (v < 0 ? -BigInt(v) : BigInt(v))) return null;
-  return literal === String(v) ? null : 'a whole number that is not exactly a double';
-}
-
-// Bytes to a value, or a throw.
-export function readJson(input: Uint8Array | string): unknown {
-  const s = typeof input === 'string' ? input : utf8.decode(input);
-  let at = 0;
-  const space = () => {
-    for (;;) {
-      const c = s.charCodeAt(at);
-      if (c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d) at += 1;
-      else return;
-    }
-  };
-  const string = (): string => {
-    const start = at;
-    at += 1;
-    for (;;) {
-      const c = s.charCodeAt(at);
-      if (Number.isNaN(c)) fail(start, 'an unterminated string');
-      if (c === 0x22) break;
-      if (c < 0x20) fail(at, 'a control character in a string');
-      at += c === 0x5c ? 2 : 1;
-    }
-    at += 1;
-    // The escapes are JSON's own, and the runtime reads them the one way.
-    return JSON.parse(s.slice(start, at)) as string;
-  };
-  const value = (): unknown => {
-    space();
-    const c = s[at];
-    if (c === '{') {
-      at += 1;
-      const out: Record<string, unknown> = {};
-      const keys = new Set<string>();
-      space();
-      if (s[at] === '}') {
-        at += 1;
-        return out;
-      }
-      for (;;) {
-        space();
-        if (s[at] !== '"') fail(at, 'a key that is not a string');
-        const where = at;
-        const k = string();
-        if (keys.has(k)) fail(where, `two keys named ${JSON.stringify(k)}`);
-        keys.add(k);
-        space();
-        if (s[at] !== ':') fail(at, 'a key with no colon');
-        at += 1;
-        // Defined, never assigned: a key named `__proto__` is an own key here
-        // as it is in JSON.parse, and the value rule refuses it after.
-        Object.defineProperty(out, k, { value: value(), enumerable: true, writable: true, configurable: true });
-        space();
-        if (s[at] === ',') at += 1;
-        else if (s[at] === '}') {
-          at += 1;
-          return out;
-        } else fail(at, 'an object not closed');
-      }
-    }
-    if (c === '[') {
-      at += 1;
-      const out: unknown[] = [];
-      space();
-      if (s[at] === ']') {
-        at += 1;
-        return out;
-      }
-      for (;;) {
-        out.push(value());
-        space();
-        if (s[at] === ',') at += 1;
-        else if (s[at] === ']') {
-          at += 1;
-          return out;
-        } else fail(at, 'a list not closed');
-      }
-    }
-    if (c === '"') return string();
-    for (const [word, v] of [['true', true], ['false', false], ['null', null]] as const) {
-      if (s.startsWith(word, at)) {
-        at += word.length;
-        return v;
-      }
-    }
-    const m = /-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
-    m.lastIndex = at;
-    const hit = m.exec(s);
-    if (!hit) return fail(at, 'no value');
-    const why = numberFault(hit[0]);
-    if (why !== null) fail(at, `${hit[0]} is ${why}`);
-    at += hit[0].length;
-    return Number(hit[0]);
-  };
-  const out = value();
-  space();
-  if (at !== s.length) fail(at, 'text after the value');
-  return out;
-}

package/src/ward/owner.ts

@@ -1,214 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The owner's asks. The root owner holds the ask pointer; every other owner
-// is an occupant of the ward itself, invited by the root. The ward is a
-// being to her owner: the empty ask is her describe, and it carries her asks
-// with a description and an input each, so a side renders them as it
-// renders any being's. Seven asks: boot, public, invite, knock, remove and
-// unboot, which is boot's inverse and takes her relations with her, and ask,
-// which reaches into a being and asks her. The knock is a being's knock made
-// for her, and the standing is written into her cells under the id the owner
-// gave; remove takes a relation out of her by id, the mirror of it.
-import { isSilence, isWord, wordOf } from '../being/silence.ts';
-import { OWNER } from '../being/types.ts';
-import type { Ask, Asker, Invitation, Json, JsonObject, Wanted } from '../being/types.ts';
-import { put } from './partition.ts';
-import { seen, answered } from './door.ts';
-import { within, allow, DEFAULT, LATE } from './allowance.ts';
-import type { Resident } from './ward.ts';
-
-export type OwnerSide = {
-  pk: string;
-  doors: Map<string, Resident>;
-  absent(): Record<string, string | null>; // the rows no door holds this run: key to class
-  publicKey(): string | null;
-  // Class first, then key, as the ground and a being's own boot both say it.
-  instantiate(className: string, key: string): Resident | 'threw' | null;
-  unboot(key: string): string[] | null;
-  setPublic(key: string | null): void; // null takes the mark off, and the being stays
-};
-
-const str = { type: 'string' };
-export const OWNER_ASKS: Ask[] = [
-  { name: 'boot', description: 'boot a being by class name, under a key the owner chooses', input: { type: 'object', properties: { key: str, class: str }, required: ['key', 'class'] } },
-  { name: 'public', description: 'mark a booted being as the one public being of the ward, reached by anyone at the bare pk; null takes the mark off and leaves her booted', input: { type: 'object', properties: { key: str }, required: ['key'] } },
-  { name: 'invite', description: 'mint an invitation on a being of the ward, under the id she will know the occupant by, with the notes she will read on it; on the ward pk it mints an owner, and only the root may', input: { type: 'object', properties: { being: str, id: str, notes: { type: 'object' } }, required: ['being', 'id'] } },
-  {
-    name: 'knock',
-    description: 'knock for a being of the ward with an invitation, and take the standing under id if answered; being is a key booted, or { boot: class, key } to boot her first',
-    input: { type: 'object', properties: { being: { description: 'a key, or { boot, key }' }, id: str, invitation: { type: 'object' }, method: str, args: { type: 'object' }, wanted: { type: 'object', properties: { time: { type: 'number' } } } }, required: ['being', 'id', 'invitation'] },
-  },
-  { name: 'remove', description: 'take a relation out of a being of the ward by id, occupant or standing; on the ward pk it unseats an owner, and only the root may', input: { type: 'object', properties: { being: str, id: str }, required: ['being', 'id'] } },
-  { name: 'unboot', description: 'take a being out of the ward, with every relation she holds; her occupants hear removed, and the ward itself is refused', input: { type: 'object', properties: { being: str }, required: ['being'] } },
-  {
-    name: 'ask',
-    description: 'ask a being of the ward, as the owner; with no being it is the public being asked as nobody, which is what a stranger would hear',
-    input: { type: 'object', properties: { being: str, method: str, args: { type: 'object' }, wanted: { type: 'object', properties: { time: { type: 'number' } } } } },
-  },
-];
-
-export async function ownerAnswer(w: OwnerSide, asker: Asker, method: string | undefined, args: JsonObject): Promise<Json> {
-  // Every name the owner gives is a string, or it is nothing. Coerced instead
-  // of checked, an object passed where a name belongs becomes the string
-  // "[object Object]", and two owners who each got the shape wrong would be
-  // handed one being. Not `word`: a word in this tree is what a ward says when
-  // no object came back, and this file imports those.
-  const named = (v: unknown): string | null => (typeof v === 'string' ? v : null);
-
-  if (method === undefined) return describe(w);
-  if (method === 'boot') {
-    const key = named(args.key),
-      className = named(args.class);
-    if (key === null || className === null) return { error: 'no such class, or key taken' };
-    const door = w.instantiate(className, key);
-    if (door === 'threw') return { error: 'threw at birth' };
-    return door ? { booted: door.key } : { error: 'no such class, or key taken' };
-  }
-  if (method === 'public') {
-    // A ward may have one public being, and no more. Marking a second would
-    // leave the first holding every relation she had, reachable by nobody at
-    // the bare pk, and told by nobody that she had been replaced. One absent
-    // this run is reachable by nobody already, so the mark may move off her.
-    // Null takes the mark off: the being stays and keeps every relation she
-    // holds, and the ward answers arrivals for no heir with silence, as one
-    // that never had a public being does. Retiring her is not destroying her.
-    if (args.key === null) {
-      w.setPublic(null);
-      return { public: null };
-    }
-    const key = named(args.key);
-    if (key === null || key === w.pk || !w.doors.has(key)) return { error: 'no such being' };
-    const standing = w.publicKey();
-    if (standing !== null && standing !== key && w.doors.has(standing)) return { error: 'a ward has one public being' };
-    w.setPublic(key);
-    return { public: key };
-  }
-  if (method === 'invite') {
-    // On the ward itself, only the root may invite: an occupant of the ward
-    // is an owner, and ownership is minted by the ask pointer alone. An owner
-    // at the door asking to invite on the ward is refused, so that a carried
-    // key can pilot but never hand piloting on.
-    const being = named(args.being),
-      id = named(args.id);
-    if (being === null || id === null) return { error: 'no such being' };
-    if (being === w.pk && asker.id !== OWNER) return { error: 'no such being' };
-    // The notes are the terms the owner mints under, and the being reads them
-    // on her gate. Placing an occupant is the owner's, and saying what it may
-    // do is part of placing it; the work behind the gate is still hers alone.
-    const notes = args.notes;
-    const door = w.doors.get(being);
-    if (!door) return { error: 'no such being' };
-    return await door.stance.occupants.invite(id, notes !== null && typeof notes === 'object' && !Array.isArray(notes) ? (notes) : undefined);
-  }
-  if (method === 'knock') {
-    const b = args.being as string | { boot: unknown; key: unknown };
-    let door = typeof b === 'string' ? w.doors.get(b) : undefined;
-    if (!door && b && typeof b === 'object') {
-      // new or existing: the owner names a being of theirs, and a key already
-      // booted is a being of theirs, not a class that failed to instantiate.
-      const key = named(b.key),
-        className = named(b.boot);
-      if (key === null || className === null) return { error: 'no such being' };
-      const made = w.instantiate(className, key);
-      if (made === 'threw') return { error: 'threw at birth' };
-      // Made or already there, the door is the one under the key she named:
-      // instantiate boots under that key or refuses, and never another.
-      door = w.doors.get(key);
-    }
-    const id = named(args.id);
-    // Never for the ward itself, for the reason invite refuses it: the ward
-    // is a being to nobody outside, and holds no relation of its own. A
-    // standing written into its cells would be the owner's reach dressed as
-    // a being's, and no ask of the ward's could ever use it.
-    if (!door || id === null || door.key === w.pk) return { error: 'no such being' };
-    const inv = args.invitation as Invitation;
-    // The owner is a caller like any other and may say what this knock may
-    // spend. Saying nothing is the ward's default, as it is for a being.
-    const out = await door.stance.standings.knock(inv, args.method as string | undefined, (args.args as JsonObject) ?? {}, args.wanted as Wanted | undefined);
-    if (isSilence(out)) return { error: 'silence' };
-    if (isWord(out)) return { error: wordOf(out) }; // the owner hears objects: the word is the error's name
-    return { taken: await door.stance.standings.take(id, inv), answer: out };
-  }
-  if (method === 'remove') {
-    // The mirror of knock: a relation out of a being, by id, occupant or
-    // standing, since the two share one namespace. On the ward itself the
-    // id is an owner, and only the root may unseat one, for the reason only
-    // the root may invite one: ownership moves by the root alone.
-    const being = named(args.being),
-      id = named(args.id);
-    if (being === null || id === null) return { error: 'no such being' };
-    if (being === w.pk && asker.id !== OWNER) return { error: 'no such being' };
-    const door = w.doors.get(being);
-    if (!door) return { error: 'no such being' };
-    if (Object.hasOwn(door.cells.occupants, id)) door.stance.occupants.remove(id);
-    else if (Object.hasOwn(door.cells.standings, id)) door.stance.standings.remove(id);
-    else return { error: 'nothing to remove' };
-    return { removed: id };
-  }
-  if (method === 'unboot') {
-    // The inverse of boot, and the only way a being leaves a ward. Her
-    // relations go with her, so an occupant of hers hears `removed` from the
-    // keys the door kept, exactly as it would had the owner removed each id
-    // by hand; the owner hears which ids those were. The ward itself is
-    // refused, for the reason knock is: it is a being to nobody outside, and
-    // unbooting it would be a ward deleting itself from inside its own map,
-    // leaving its owners bound to a door that is gone.
-    const being = named(args.being);
-    if (being === null || being === w.pk) return { error: 'no such being' };
-    const removed = w.unboot(being);
-    return removed === null ? { error: 'no such being' } : { unbooted: being, removed };
-  }
-  if (method === 'ask') {
-    // The owner's other power: to reach into a being and ask her. It is
-    // strictly less than unboot, which takes her out with every relation she
-    // holds, and it is the third asker of the ward-to-being edge finally
-    // filled in by the ward rather than minted by whoever holds the pointer.
-    // Bounded, judged and named here, so no side outside the ward ever holds
-    // a being's answer and writes the door's discipline again beside it.
-    const being = args.being === undefined ? null : named(args.being);
-    if (args.being !== undefined && being === null) return { error: 'no such being' };
-    // A method is a name or it is the empty ask. Coerced instead of checked,
-    // a shape passed where a name belongs becomes a string she never declared,
-    // and she would answer `unknown ask` to something nobody asked.
-    if (args.method !== undefined && typeof args.method !== 'string') return { error: 'an ask is named by a word' };
-    // No being named is the in-process twin of bytes for nobody: the public
-    // being, asked as nobody, unbound, so a throw of hers is silence. Her
-    // insides are not a stranger's to read, and a device serving her to
-    // strangers must hear what a stranger hears and not one word more.
-    const key = being ?? w.publicKey();
-    const door = key === null ? undefined : w.doors.get(key);
-    if (!door || door.key === w.pk) return { error: 'no such being' };
-    const bound = being !== null;
-    // The owner is a caller like any other: wanted says what this ask may
-    // spend, and saying nothing is the ward's default. A wait that ran out is
-    // late, the same word a being would hear, said as the object an owner hears.
-    const out = await within(allow(args.wanted as Wanted | undefined).time, answered(door, bound ? { id: OWNER } : {}, args.method, (args.args as JsonObject) ?? {}, bound));
-    if (out === LATE) return { error: 'late' };
-    if ('quo' in out) return { error: out.quo };
-    if (!('object' in out)) return { error: 'silence' };
-    return out.object;
-  }
-  return { error: 'unknown ask' };
-}
-
-// The ward's describe for its owner: its beings, their classes, a digest each,
-// as she would describe herself to the owner. A being absent this run is
-// listed too, with a null digest and absent true, so the owner can see her
-// and take her out.
-async function describe(w: OwnerSide): Promise<Json> {
-  const beings: Record<string, Json> = {};
-  // Every being is asked at once and each is bounded on her own. One being
-  // whose describe never settles is one null digest, not a ward that never
-  // answers its owner: the harbor learns the pk by this very ask at boot, so
-  // an unbounded wait here is a ward no restart can bring back.
-  const asked = [...w.doors].filter(([key]) => key !== w.pk);
-  const digests = await Promise.all(asked.map(async ([, door]) => (await within(DEFAULT.time, seen(door, { id: OWNER })))));
-  for (const [i, [key, door]] of asked.entries()) {
-    const d = digests[i];
-    put(beings, key, { class: door.cells.class ?? null, public: w.publicKey() === key, digest: d === LATE ? null : d });
-  }
-  for (const [key, cls] of Object.entries(w.absent())) put(beings, key, { class: cls, public: w.publicKey() === key, digest: null, absent: true });
-  return {
-    asks: OWNER_ASKS,
-    notes: { pk: w.pk, beings },
-  };
-}

package/src/ward/seal.ts

@@ -1,178 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The seal. What a ward does to bytes on the way out and on the way in.
-//
-// A being's key is one 32-byte seed: an Ed25519 pair. It signs, it never
-// seals. The ward's key is one seed too, giving both an Ed25519 pair to sign
-// replies and an X25519 padlock every ask is sealed to. Beings never own a
-// padlock: asks are sealed to the ward, replies to the ephemeral key of the
-// ask they answer.
-//
-//   ask on the wire     box = eph X pk || AESGCM( payload || signature )     sealed to the ward padlock
-//                       payload = JSON { to, by, next, seq, time, hops?, method?, args }  signed by `by`
-//
-// Nothing rides outside the box. `to` names the heir this ask is for, and it
-// is inside with everything else: a heir is the one name in a relation that
-// never rotates, so on the outside it would be a handle an intermediary could
-// hold forever, and the same handle anyone who ever saw the invitation
-// already has. What a harbor needs to route is the ward pk, which it carries
-// itself. The door opens every ask with its own padlock and reads `to` after,
-// so nothing was ever gained by having it in the clear.
-//   reply on the wire   box = eph X pk || AESGCM( reply || signature )       sealed to the ask's eph pk
-//                       reply = JSON { object, seen } | { silence: true } | { quo: word }    signed by the ward key
-import type { DoorWord, Json, JsonObject } from '../being/types.ts';
-import { isDoorWord } from '../being/silence.ts';
-import { KEY, SIGNATURE, box, concat, derive, hex, sha256, sign, signingPair, sealingPair, unbox, unhex, verify } from './arithmetic.ts';
-import { cellFault } from './cells.ts';
-import { readJson } from './json.ts';
-
-const utf8 = new TextEncoder();
-
-export type WardKey = { sign: Uint8Array; padlock: Uint8Array; signPk: Uint8Array; padlockPk: Uint8Array; pk: string };
-
-// The two labels a ward's keys are derived under. They are here and not in
-// arithmetic.ts because a label is a decision and that file is arithmetic.
-// `quo-seal` is taken: it is the label the message cipher derives its key and
-// nonce under, from an agreement rather than from a seed, and two derivations
-// answering to one name is how a kit is read wrong.
-const WARD_SIGN = new TextEncoder().encode('quo-ward-sign');
-const WARD_SEAL = new TextEncoder().encode('quo-ward-seal');
-
-// The one size in Quo: one mebibyte of bytes each way. It is read before
-// anything is opened, so bytes above it are never decrypted, never parsed and
-// never allocated against. Refusing them is bytes that said nothing, which is
-// already silence, so there is no tenth word and no new door case. Breadth
-// costs bytes, so this one number bounds every other breadth on the wire, and
-// what a being holds is not the protocol's business. An ask is a message and
-// not a file; what is larger is asked for in pieces.
-export const SIZE = 1024 * 1024;
-
-// The ward's key from its seed. Its pk on the wire is the signing pk then the padlock, 128 hex.
-//
-// One seed, two curves, and each secret derived from it under its own label.
-// Fed the seed straight, the two scalars differ only because Ed25519 hashes
-// what it is given and X25519 clamps it raw, which is an accident of the two
-// designs and no separation at all: one secret would be doing two jobs with
-// nothing said about it, and a second kit would have to reproduce a
-// construction nobody named. HKDF-SHA-256 under a label is the separation
-// said out loud, and it is what `quo/vectors/framing.json` pins.
-//
-// Bytes are key material and text is not. A seed handed in as bytes of the
-// key length is taken as it stands, which is what a harbor mints; anything
-// else, of any length, is hashed to that length first. So a thirty-two
-// character name is a name like any other, and not a key because it happened
-// to be the right size.
-export async function wardKey(seed: string | Uint8Array): Promise<WardKey> {
-  const seed32 = typeof seed === 'string' ? await sha256(utf8.encode(seed)) : seed.length === KEY ? seed : await sha256(seed);
-  const s = await signingPair(await derive(seed32, WARD_SIGN, KEY));
-  const p = await sealingPair(await derive(seed32, WARD_SEAL, KEY));
-  return { sign: s.secret, padlock: p.secret, signPk: s.pk, padlockPk: p.pk, pk: hex(s.pk) + hex(p.pk) };
-}
-export const wardSignPk = (pk: string): Uint8Array => unhex(pk.slice(0, KEY * 2));
-export const wardPadlock = (pk: string): Uint8Array => unhex(pk.slice(KEY * 2));
-export const isWardPk = (pk: unknown): pk is string => typeof pk === 'string' && /^[0-9a-f]{128}$/.test(pk);
-// Thirty-two bytes as hex, which is how this kit writes every single key: a
-// heir pk, a heir secret, a being's own key, and a digest, which is the same
-// thirty-two bytes of SHA-256. A ward pk is two of these and has its own
-// shape above. The two are spelled here and nowhere else, so a door, a
-// stance, a harbor and a conformance suite all refuse the same string.
-export const isHex = (v: unknown): v is string => typeof v === 'string' && /^[0-9a-f]{64}$/.test(v);
-
-// A being's relation key: a seed, and the pk it signs as.
-export async function beingKey(seed: Uint8Array): Promise<{ seed: string; pk: string }> {
-  return { seed: hex(seed), pk: hex((await signingPair(seed)).pk) };
-}
-
-// time is the allowance: what this ask may still spend. It rides inside the
-// signed body, so a budget caught on the road cannot be widened by whoever
-// caught it.
-// hops is reserved and nothing sets it. An ask carries no count of doors
-// today, so a chain of relays is bounded by time alone. A relay chain that
-// ever wants a count needs every door on it to refuse at zero, and a door
-// written after the count was invented cannot make the doors before it
-// enforce anything. So the field is named and refused here now, while it
-// costs two lines: a door of this version already counts as a correct
-// participant in a chain nobody has designed yet.
-export type AskPayload = { by: string; next: string | null; seq: number; time: number; hops?: number; method?: string; args: JsonObject };
-// What is actually sealed: the payload with the heir it is for, or null for
-// the public being. `to` is signed with the rest, so it cannot be moved.
-type Sealed = AskPayload & { to: string | null };
-export type ReplyPayload = { object: Json; seen: string | null } | { silence: true } | { quo: DoorWord };
-
-// Seal an ask. Returns the bytes and the ephemeral secret the reply will be sealed to.
-export async function sealAsk(to: string | null, payload: AskPayload, signer: Uint8Array, padlock: Uint8Array, seed: Uint8Array): Promise<{ bytes: Uint8Array; ephemeral: Uint8Array }> {
-  const body = utf8.encode(JSON.stringify({ to, ...payload } satisfies Sealed));
-  const inside = concat([body, await sign(body, signer)]);
-  const { bytes, ephemeral } = await box(inside, padlock, seed);
-  return { bytes, ephemeral: ephemeral.secret };
-}
-
-// Open an ask at the door. Null when it does not open or does not parse.
-// Verification is the door's own step, because only the door knows which key may speak.
-export async function openAsk(bytes: Uint8Array, padlockSecret: Uint8Array): Promise<{ to: string | null; payload: AskPayload; body: Uint8Array; signature: Uint8Array; ephemeralPk: Uint8Array } | null> {
-  try {
-    if (!(bytes instanceof Uint8Array) || bytes.length < 1 || bytes.length > SIZE) return null;
-    const inside = await unbox(bytes, padlockSecret);
-    if (inside.length <= SIGNATURE) return null;
-    const body = inside.subarray(0, inside.length - SIGNATURE);
-    const signature = inside.subarray(inside.length - SIGNATURE);
-    const payload = readJson(body) as Sealed;
-    // The heir, or null for the public being. Absent is not null: a payload
-    // that never named one is malformed, like any other missing field.
-    const to = payload.to;
-    if (to !== null && !isHex(to)) return null;
-    if (!isHex(payload.by)) return null;
-    if (payload.next !== null && !isHex(payload.next)) return null;
-    if (payload.method !== undefined && typeof payload.method !== 'string') return null; // a name, or the empty ask. never a number, never an object.
-    if (payload.args !== undefined && (payload.args === null || typeof payload.args !== 'object' || Array.isArray(payload.args))) return null; // args are one object, or absent. a string or a list is not an ask.
-    if (payload.args !== undefined && cellFault(payload.args, 'args') !== null) return null; // and values all the way down: no key named __proto__, no nesting past the bound
-    if (!Number.isSafeInteger(payload.seq) || payload.seq < 1) return null; // her count for this relation. one and up, and a whole number.
-    // The allowance is not read here. It is the door's, D2, and the door is
-    // its one reader: `spent` in allowance.ts says what a budget is and what
-    // is left of it, in one sentence, for a payload that opened like any other.
-    // The hop count, if this ask carries one: a whole number, never below
-    // zero. Absent is the ordinary ask and always will be.
-    if (payload.hops !== undefined && (!Number.isSafeInteger(payload.hops) || payload.hops < 0)) return null;
-    return { to, payload, body, signature, ephemeralPk: bytes.subarray(0, KEY) };
-  } catch {
-    return null;
-  }
-}
-export const verifyAsk = (a: { body: Uint8Array; signature: Uint8Array }, pk: string): Promise<boolean> => verify(a.body, a.signature, unhex(pk));
-
-// Seal a reply to the ephemeral pk of the ask it answers, signed by the ward.
-export async function sealReply(reply: ReplyPayload, ephemeralPk: Uint8Array, wardSign: Uint8Array, seed: Uint8Array): Promise<Uint8Array> {
-  const body = utf8.encode(JSON.stringify(reply));
-  return (await box(concat([body, await sign(body, wardSign)]), ephemeralPk, seed)).bytes;
-}
-
-// Open a reply with the ephemeral secret kept from the ask, and verify it
-// came from the ward it was sent to. Null is silence: it did not open, it
-// lied, or it is not a reply. Every ward on the wire is somebody else's code,
-// so the shape is checked here and nowhere later: a reply is `{ silence }`,
-// `{ quo: word }` with a word the door may say, or `{ object, seen }` with an
-// object that is a value and seen a digest or null. A field beside a shape's
-// own makes it none of the three, since a kit that dropped the field would
-// hand her an answer where this one hands her silence.
-// Anything else is bytes that said nothing, and her ward never hands her a
-// throw or an absent value for what a stranger wrote.
-export async function openReply(bytes: unknown, ephemeralSecret: Uint8Array, signPk: Uint8Array): Promise<ReplyPayload | null> {
-  try {
-    if (!(bytes instanceof Uint8Array) || bytes.length > SIZE) return null;
-    const inside = await unbox(bytes, ephemeralSecret);
-    if (inside.length <= SIGNATURE) return null;
-    const body = inside.subarray(0, inside.length - SIGNATURE);
-    if (!(await verify(body, inside.subarray(inside.length - SIGNATURE), signPk))) return null;
-    const reply = readJson(body);
-    if (reply === null || typeof reply !== 'object' || Array.isArray(reply)) return null;
-    const r = reply as Record<string, unknown>;
-    const keys = Object.keys(r).sort().join(',');
-    if (keys === 'silence') return r.silence === true ? { silence: true } : null;
-    if (keys === 'quo') return isDoorWord(r.quo) ? { quo: r.quo } : null;
-    if (keys !== 'object,seen') return null;
-    if (r.seen !== null && !isHex(r.seen)) return null;
-    if (cellFault(r.object, 'object') !== null) return null; // values in both directions: nested past the bound is none of the shapes
-    return { object: r.object as Json, seen: r.seen };
-  } catch {
-    return null;
-  }
-}