@quo-systems/quo 0.2.9 → 0.2.10

package/src/ward/cells.ts

@@ -3,12 +3,12 @@
 // persist a being's cells as it likes: as this process's objects, as a row, as
 // a line of JSON on a disk. That promise is only worth what the cells honour.
 //
-// Nothing checked it. A being could write a Map, a Date, an undefined, a NaN.
-// In a memory harbor the object survives, because there is nowhere for it to
-// go and come back from. Through any harbor that keeps values it silently
-// becomes {}, or a string, or absent, or null — and she is never told which
-// harbor she is standing in. That is the memory harbor lying to her, which is
-// the one thing it must never do.
+// Unchecked, a being could write a Map, a Date, an undefined, a NaN. In a
+// memory harbor the object would survive, because there is nowhere for it to
+// go and come back from. Through any harbor that keeps values it would
+// silently become {}, or a string, or absent, or null, and she is never told
+// which harbor she is standing in. That would be the memory harbor lying to
+// her, which is the one thing it must never do.
 //
 // So the cells refuse the write. Loud, where she wrote it, in her own frame:
 // a being holds three answers and a throw is not one of them, so this throw
@@ -17,18 +17,27 @@
 // that a harbor would have to lie about later.
 import type { Cells, Json } from '../being/types.ts';
 
+// How deep a value may nest. Every walk over a value in the kit recurses,
+// and a peer chooses the depth of what she answers; a bound keeps a hostile
+// reply from ending a walk in a stack overflow instead of a refusal.
+export const DEPTH = 64;
+
 // I-JSON, all the way down. A number that JSON cannot write is not a number
-// a harbor can keep, and a key on the prototype is not a key she wrote.
-function fault(v: unknown, path: string, seen: Set<object>): string | null {
+// a harbor can keep, a key on the prototype is not a key she wrote, and a
+// hole in a list, or a key named `__proto__`, is a thing JSON writes one way
+// and a runtime reads another.
+function fault(v: unknown, path: string, seen: Set<object>, depth: number): string | null {
   if (v === null || typeof v === 'boolean' || typeof v === 'string') return null;
   if (typeof v === 'number') return Number.isFinite(v) ? null : `${path} is ${String(v)}, which no harbor can write down`;
   if (typeof v !== 'object') return `${path} is a ${typeof v}, which is not a value`;
   if (seen.has(v)) return `${path} refers back to itself`;
+  if (depth >= DEPTH) return `${path} is nested past ${DEPTH} levels, which no harbor can keep`;
   seen.add(v);
   try {
     if (Array.isArray(v)) {
       for (let i = 0; i < v.length; i += 1) {
-        const f = fault(v[i], `${path}[${i}]`, seen);
+        if (!(i in v)) return `${path}[${i}] is a hole, which no harbor can write down`;
+        const f = fault(v[i], `${path}[${i}]`, seen, depth + 1);
         if (f) return f;
       }
       return null;
@@ -36,7 +45,8 @@ function fault(v: unknown, path: string, seen: Set<object>): string | null {
     const proto = Object.getPrototypeOf(v);
     if (proto !== Object.prototype && proto !== null) return `${path} is a ${(v).constructor?.name ?? 'object'}, which is not a value`;
     for (const k of Object.keys(v)) {
-      const f = fault((v as Record<string, unknown>)[k], `${path}.${k}`, seen);
+      if (k === '__proto__') return `${path}.__proto__ is a key no harbor can keep`;
+      const f = fault((v as Record<string, unknown>)[k], `${path}.${k}`, seen, depth + 1);
       if (f) return f;
     }
     return null;
@@ -45,16 +55,43 @@ function fault(v: unknown, path: string, seen: Set<object>): string | null {
   }
 }
 
-export const cellFault = (v: unknown, path: string): string | null => fault(v, path, new Set());
+export const cellFault = (v: unknown, path: string): string | null => fault(v, path, new Set(), 0);
+
+// The three keys at the root of her cells that are the ward's: it writes
+// them, she reads them, and a write of hers there is refused like a non-value.
+const WARDS = new Set(['standings', 'occupants', 'class']);
 
 // The guard is one proxy at the root and one for every container read through
 // it, so a write nested three deep is refused the same way a write at the top
 // is. Wrappers are remembered, so reading the same array twice is the same
 // object twice and a being may still compare what she holds.
 const wrapped = new WeakMap<object, object>();
+const targets = new WeakMap<object, object>();
 const guards = new WeakSet();
 
-function guard<T extends object>(target: T, path: string): T {
+// A key a write may land on: a string that is not `__proto__`, and not one
+// of the ward's at the root. A symbol key is a thing JSON never writes.
+const refuse: (why: string) => never = (why) => {
+  throw new TypeError(`cells hold values: ${why}`);
+};
+function keyFault(t: object, k: string | symbol, v: unknown, path: string, root: boolean): void {
+  if (typeof k !== 'string') refuse(`${path} takes no symbol key`);
+  if (k === '__proto__') refuse(`${path}.__proto__ is a key no harbor can keep`);
+  if (root && WARDS.has(k)) refuse(`${path}.${k} is the ward's to write`);
+  // A list grows by one at its end, or it has holes JSON cannot write. A
+  // push sets the slot at its length and then the length: both pass. A
+  // length set past what she wrote, or a slot beyond it, would leave holes.
+  if (Array.isArray(t)) {
+    if (k === 'length') {
+      if (typeof v !== 'number' || v > t.length) refuse(`${path}.length set past what she wrote would leave holes`);
+      return;
+    }
+    const i = Number(k);
+    if (Number.isInteger(i) && i > t.length) refuse(`${path}[${i}] would leave a hole`);
+  }
+}
+
+function guard<T extends object>(target: T, path: string, wrote: () => void, root = false): T {
   if (guards.has(target)) return target;
   const had = wrapped.get(target);
   if (had) return had as T;
@@ -62,29 +99,43 @@ function guard<T extends object>(target: T, path: string): T {
     get(t, k, r) {
       const v = Reflect.get(t, k, r);
       // A container reached through her cells is part of her cells.
-      return v !== null && typeof v === 'object' && !ArrayBuffer.isView(v) ? guard(v as object, `${path}.${String(k)}`) : v;
+      return v !== null && typeof v === 'object' && !ArrayBuffer.isView(v) ? guard(v as object, `${path}.${String(k)}`, wrote) : v;
     },
     set(t, k, v, r) {
-      if (typeof k === 'string') {
-        const f = cellFault(v, `${path}.${k}`);
-        if (f) throw new TypeError(`cells hold values: ${f}`);
-      }
-      return Reflect.set(t, k, v, r);
+      keyFault(t, k, v, path, root);
+      const f = cellFault(v, `${path}.${String(k)}`);
+      if (f) refuse(f);
+      const ok = Reflect.set(t, k, v, r);
+      wrote();
+      return ok;
     },
     defineProperty(t, k, d) {
-      if (typeof k === 'string' && 'value' in d) {
-        const f = cellFault(d.value, `${path}.${k}`);
-        if (f) throw new TypeError(`cells hold values: ${f}`);
-      }
-      return Reflect.defineProperty(t, k, d);
+      if (!('value' in d)) refuse(`${path}.${String(k)} is an accessor, which no harbor can keep`);
+      keyFault(t, k, d.value, path, root);
+      const f = cellFault(d.value, `${path}.${String(k)}`);
+      if (f) refuse(f);
+      const ok = Reflect.defineProperty(t, k, d);
+      wrote();
+      return ok;
+    },
+    deleteProperty(t, k) {
+      if (root && typeof k === 'string' && WARDS.has(k)) refuse(`${path}.${k} is the ward's to keep`);
+      const ok = Reflect.deleteProperty(t, k);
+      wrote();
+      return ok;
     },
   });
   wrapped.set(target, p);
+  targets.set(p, target);
   guards.add(p);
   return p;
 }
 
 // Her cells, guarded. Called once per being at boot; the guarded object is
 // what goes into the partition and what the stance hands her, so there is no
-// second door onto the same cells.
-export const guardCells = (cells: Cells): Cells => guard(cells as unknown as Record<string, Json>, 'cells') as unknown as Cells;
+// second door onto the same cells. Every write that passes says so to the
+// ward, which says so to its harbor.
+export const guardCells = (cells: Cells, wrote: () => void = () => {}): Cells => guard(cells as unknown as Record<string, Json>, 'cells', wrote, true) as unknown as Cells;
+// The cells behind the guard, for the ward alone: the one writer of the
+// three keys that are its own.
+export const unguarded = (cells: Cells): Cells => (targets.get(cells as unknown as object) ?? cells) as Cells;

package/src/ward/door.ts

@@ -15,6 +15,7 @@ import type { Heirs } from './heirs.ts';
 import { openAsk, sealReply, verifyAsk, type ReplyPayload, type WardKey } from './seal.ts';
 import { spent } from './allowance.ts';
 import { KEY, sealingPair } from './arithmetic.ts';
+import { cellFault } from './cells.ts';
 
 export type Door = { key: string; being: BeingLike; cells: { occupants: Record<string, unknown> } };
 export type Judged = { bytes: Uint8Array; heard: boolean };
@@ -37,13 +38,21 @@ export async function arrive(door: Door, asker: Asker, method: string | undefine
   // on the way out and the far side reads back as a fourth word.
   if (out === undefined || isSilence(out)) return SILENCE;
   if (isWord(out)) return threw; // a word is the ward's to say, never hers
+  // Her answer is held to the rule her args and her cells are held to. A
+  // shape JSON would drop or rewrite on the way out, a Date, a Map, a NaN, a
+  // cycle, is not hers to make: the far side would read something she never
+  // said, or the door itself would fail to write her reply after the number
+  // was spent. It is threw, like a word out of her.
+  if (cellFault(out, 'answer') !== null) return threw;
   if (method === undefined) return { object: out, seen: null };
   // The digest rides along, it is not the answer. She has already answered:
   // a describe that will not run costs the digest, and nothing else.
   return { object: out, seen: await seen(door, asker) };
 }
 
-async function seen(door: Door, asker: Asker): Promise<string | null> {
+// Her digest for this asker, or null when her describe threw or fell silent.
+// The owner's describe reads it the same way for every being of the ward.
+export async function seen(door: Door, asker: Asker): Promise<string | null> {
   try {
     const bp = await door.being.answer(asker);
     return isSilence(bp) || isWord(bp) ? null : await digest(bp);
@@ -83,6 +92,12 @@ export function makeDoor(key: WardKey, heirs: Heirs, doors: Map<string, Door>, p
       return { reply: said('removed'), ephemeralPk, heard: true };
     }
     if (!(await verifyAsk(a, payload.by))) return refuse(); // D7, under an admitted key
+    // The signature took time, and another arrival on this heir may have been
+    // honoured meanwhile: a knock that raced this one and won spent the heir,
+    // and the key this ask speaks under may not be admitted any more. The
+    // door judges concurrently, so admission is read again now that writing
+    // is next, and what changed under the await is judged as it stands.
+    if (!heirs.admits(to, payload.by)) return heirs.gone(to, payload.by) ? { reply: said('removed'), ephemeralPk, heard: true } : refuse();
     // From here the door has heard a key it holds. Every answer below is
     // sealed to that key's lid; nothing below is a stranger's.
     const door = doors.get(h.being);
@@ -100,9 +115,11 @@ export function makeDoor(key: WardKey, heirs: Heirs, doors: Map<string, Door>, p
   // reply is sealed to the ephemeral pk on its lid, which is all a stranger
   // holds, and says silence.
   //
-  // A lid that is not a key -- a small-order point, of which the two curves
-  // have several each -- makes a dead agreement, and the seal refuses it. The
-  // door never throws: that reply is noise, sealed to a key nobody holds.
+  // A lid that is not a key, a small-order point, of which the two curves
+  // have several each, makes a dead agreement, and the seal refuses it. The
+  // door never throws: that reply is noise, a plain silence sealed to a key
+  // nobody holds, and the same is written for anything else the seal will
+  // not take.
   return async function door(bytes: Uint8Array): Promise<Judged> {
     const out = await judge(bytes);
     const reply = out?.reply ?? SILENCE;
@@ -110,7 +127,7 @@ export function makeDoor(key: WardKey, heirs: Heirs, doors: Map<string, Door>, p
     try {
       return { bytes: await sealReply(reply, out?.ephemeralPk ?? lid(bytes, random), key.sign, random(32)), heard };
     } catch {
-      return { bytes: await sealReply(reply, (await sealingPair(random(32))).pk, key.sign, random(32)), heard };
+      return { bytes: await sealReply(SILENCE, (await sealingPair(random(32))).pk, key.sign, random(32)), heard };
     }
   };
 }

package/src/ward/ground.ts

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
-// The ground. The one object a harbor passes a ward at birth. Five things,
-// never a sixth. Everything a runtime differs on arrives here, which is
+// The ground. The one object a harbor passes a ward at birth. Six things,
+// never a seventh. Everything a runtime differs on arrives here, which is
 // why the ward itself knows no runtime.
 import type { Stance, BeingLike } from '../being/types.ts';
 
@@ -8,6 +8,13 @@ export type Ground = {
   seed: string | Uint8Array; // the ward derives its pk from it and nothing else
   memory: Record<string, unknown>; // the partition. the ward's files. opaque to the harbor
   instantiate(className: string, stance: Stance): BeingLike | null; // the code half
+  // The ward wrote its partition. It says so after every write, a key
+  // rotated, a relation taken, a cell she set, and says nothing else: it
+  // never learns whether anything was kept. A harbor that keeps the
+  // partition saves after this, when it likes and in the order it was told,
+  // so a being driven in process is kept the way one reached through a door
+  // is. A harbor that keeps nothing leaves it out.
+  wrote?: () => void;
   // Sealed bytes to a ward pk. What comes back, or undefined.
   //
   // undefined is a promise, not a shrug: no door was reached, and nothing was

package/src/ward/heirs.ts

@@ -13,11 +13,14 @@ const SPAN = 64;
 
 export class Heirs {
   #p: Partition;
-  constructor(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
@@ -29,6 +32,7 @@ export class Heirs {
     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.
@@ -79,17 +83,20 @@ export class Heirs {
   // 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.
   honour(h: Heir, by: string, next: string | null, seq: number): true | DoorWord {
-    if (h.fresh && next === null) return 'unannounced'; // a knock without a key of her own binds nothing
+    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';
-    return this.settle(h, by, next) ? true : 'unannounced';
+    const settled = this.settle(h, by, next);
+    this.#wrote(); // the number is spent whether or not the keys settled
+    return settled ? true : 'unannounced';
   }
 
   // The signature checked out. Settle the keys: a fresh heir rotates at once
-  // to what it announced and must announce something; a current key replaces
-  // its announcement; an announced key becomes current.
+  // to what it announced and must announce something that is not 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): boolean {
     if (h.fresh) {
-      if (next === null) return false; // a knock without a key of her own binds nothing
+      if (next === null || next === h.current) return false;
       h.current = next;
       h.announced = null;
       h.fresh = false;

package/src/ward/owner.ts

@@ -9,23 +9,18 @@
 // 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 { digest } from '../being/digest.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 } from './door.ts';
+import type { Booted } from './ward.ts';
 
 export type OwnerSide = {
   pk: string;
-  doors: Map<
-    string,
-    {
-      key: string;
-      being: { answer: (...a: never[]) => unknown };
-      cells: { class?: string; occupants: Record<string, unknown>; standings: Record<string, unknown> };
-      stance: { occupants: { invite(id: string): Promise<Invitation | null>; remove(id: string): void }; standings: { knock(inv: Invitation, m?: string, a?: JsonObject, w?: Wanted): Promise<unknown>; take(id: string, inv: Invitation): Promise<string | null>; remove(id: string): void } };
-    }
-  >;
+  doors: Map<string, Booted>;
+  absent(): Record<string, string | null>; // the rows no door holds this run: key to class
   publicKey(): string | null;
-  instantiate(key: string, className: string): { key: string } | null;
+  instantiate(key: string, className: string): Booted | 'threw' | null;
   unboot(key: string): string[] | null;
   setPublic(key: string): void;
 };
@@ -34,7 +29,7 @@ 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', 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; on the ward pk it mints an owner, and only the root may', input: { type: 'object', properties: { being: str, id: str }, required: ['being', 'id'] } },
+  { 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',
@@ -56,15 +51,18 @@ export async function ownerAnswer(w: OwnerSide, asker: Asker, method: string | u
       className = word(args.class);
     if (key === null || className === null) return { error: 'no such class, or key taken' };
     const door = w.instantiate(key, className);
+    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.
+    // 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.
     const key = word(args.key);
     if (key === null || key === w.pk || !w.doors.has(key)) return { error: 'no such being' };
-    if (w.publicKey() !== null && w.publicKey() !== key) return { error: 'a ward has one public 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 };
   }
@@ -77,8 +75,13 @@ export async function ownerAnswer(w: OwnerSide, asker: Asker, method: string | u
       id = word(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);
-    return door ? await door.stance.occupants.invite(id) : { error: 'no such being' };
+    if (!door) return { error: 'no such being' };
+    return await door.stance.occupants.invite(id, notes !== null && typeof notes === 'object' && !Array.isArray(notes) ? (notes as JsonObject) : undefined);
   }
   if (method === 'knock') {
     const b = args.being as string | { boot: unknown; key: unknown };
@@ -90,6 +93,7 @@ export async function ownerAnswer(w: OwnerSide, asker: Asker, method: string | u
         className = word(b.boot);
       if (key === null || className === null) return { error: 'no such being' };
       const made = w.instantiate(key, className);
+      if (made === 'threw') return { error: 'threw at birth' };
       door = made ? w.doors.get(made.key) : w.doors.get(key);
     }
     const id = word(args.id);
@@ -139,20 +143,16 @@ export async function ownerAnswer(w: OwnerSide, asker: Asker, method: string | u
 }
 
 // The ward's describe for its owner: its beings, their classes, a digest each,
-// as she would describe herself to the owner.
+// 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> = {};
   for (const [key, door] of w.doors) {
     if (key === w.pk) continue;
-    let d: string | null = null;
-    try {
-      const bp = await (door.being.answer as (a: unknown) => unknown)({ id: OWNER });
-      d = isSilence(bp) || isWord(bp) ? null : await digest(bp as Json);
-    } catch {
-      // she threw where she was asked. there is no blueprint, and d stays null.
-    }
-    beings[key] = { class: door.cells.class ?? null, public: w.publicKey() === key, digest: d };
+    put(beings, key, { class: door.cells.class ?? null, public: w.publicKey() === key, digest: await seen(door, { id: OWNER }) });
   }
+  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

@@ -22,6 +22,7 @@
 import type { DoorWord, Json, JsonObject } from '../being/types.ts';
 import { isDoorWord } from '../being/silence.ts';
 import { KEY, SIGNATURE, box, concat, hex, sha256, sign, signingPair, sealingPair, unbox, unhex, verify } from './arithmetic.ts';
+import { cellFault } from './cells.ts';
 
 const utf8 = new TextEncoder();
 const text = new TextDecoder();
@@ -87,6 +88,7 @@ export async function openAsk(bytes: Uint8Array, padlockSecret: Uint8Array): Pro
     if (payload.next !== null && !(typeof payload.next === 'string' && /^[0-9a-f]{64}$/.test(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. A whole number, and one that has already run out is not an
     // ask this door will open: it is refused as the bytes it is, above.