@quo-systems/quo 0.2.8 → 0.2.10

package/dist/ward/cells.js

@@ -1,6 +1,12 @@
+// 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, path, seen) {
+// 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, path, seen, depth) {
     if (v === null || typeof v === 'boolean' || typeof v === 'string')
         return null;
     if (typeof v === 'number')
@@ -9,11 +15,15 @@ function fault(v, path, seen) {
         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;
             }
@@ -23,7 +33,9 @@ function fault(v, path, seen) {
         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[k], `${path}.${k}`, seen);
+            if (k === '__proto__')
+                return `${path}.__proto__ is a key no harbor can keep`;
+            const f = fault(v[k], `${path}.${k}`, seen, depth + 1);
             if (f)
                 return f;
         }
@@ -33,14 +45,44 @@ function fault(v, path, seen) {
         seen.delete(v);
     }
 }
-export const cellFault = (v, path) => fault(v, path, new Set());
+export const cellFault = (v, path) => 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();
+const targets = new WeakMap();
 const guards = new WeakSet();
-function guard(target, path) {
+// 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) => {
+    throw new TypeError(`cells hold values: ${why}`);
+};
+function keyFault(t, k, v, path, root) {
+    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(target, path, wrote, root = false) {
     if (guards.has(target))
         return target;
     const had = wrapped.get(target);
@@ -50,30 +92,46 @@ function guard(target, path) {
         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, `${path}.${String(k)}`) : v;
+            return v !== null && typeof v === 'object' && !ArrayBuffer.isView(v) ? guard(v, `${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) => guard(cells, '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, wrote = () => { }) => guard(cells, 'cells', wrote, true);
+// The cells behind the guard, for the ward alone: the one writer of the
+// three keys that are its own.
+export const unguarded = (cells) => (targets.get(cells) ?? cells);

package/dist/ward/door.d.ts

@@ -13,4 +13,5 @@ export type Judged = {
     heard: boolean;
 };
 export declare function arrive(door: Door, asker: Asker, method: string | undefined, args: JsonObject, bound: boolean): Promise<ReplyPayload>;
+export declare function seen(door: Door, asker: Asker): Promise<string | null>;
 export declare function makeDoor(key: WardKey, heirs: Heirs, doors: Map<string, Door>, publicKey: () => string | null, random: (n: number) => Uint8Array): (bytes: Uint8Array) => Promise<Judged>;

package/dist/ward/door.js

@@ -13,6 +13,7 @@ import { at } from './partition.js';
 import { openAsk, sealReply, verifyAsk } from './seal.js';
 import { spent } from './allowance.js';
 import { KEY, sealingPair } from './arithmetic.js';
+import { cellFault } from './cells.js';
 const SILENCE = { silence: true };
 const said = (quo) => ({ quo });
 // One arrival at one being, already named. Catches every throw. `bound` says
@@ -34,13 +35,22 @@ export async function arrive(door, asker, method, args, bound) {
         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, asker) {
+// 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, asker) {
     try {
         const bp = await door.being.answer(asker);
         return isSilence(bp) || isWord(bp) ? null : await digest(bp);
@@ -83,6 +93,13 @@ export function makeDoor(key, heirs, doors, publicKey, random) {
         }
         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);
@@ -102,9 +119,11 @@ export function makeDoor(key, heirs, doors, publicKey, random) {
     // 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) {
         const out = await judge(bytes);
         const reply = out?.reply ?? SILENCE;
@@ -113,7 +132,7 @@ export function makeDoor(key, heirs, doors, publicKey, random) {
             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/dist/ward/ground.d.ts

@@ -3,6 +3,7 @@ export type Ground = {
     seed: string | Uint8Array;
     memory: Record<string, unknown>;
     instantiate(className: string, stance: Stance): BeingLike | null;
+    wrote?: () => void;
     carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | undefined>;
     random(n: number): Uint8Array;
 };

package/dist/ward/heirs.d.ts

@@ -2,7 +2,7 @@ import type { DoorWord } from '../being/types.ts';
 import { type Heir, type Partition } from './partition.ts';
 export declare class Heirs {
     #private;
-    constructor(p: Partition);
+    constructor(p: Partition, wrote?: () => void);
     open(heir: string, being: string, id: string): void;
     close(heir: string): void;
     gone(heir: string, by: string): boolean;

package/dist/ward/heirs.js

@@ -4,11 +4,14 @@ import { GONE } from './partition.js';
 const SPAN = 64;
 export class Heirs {
     #p;
-    constructor(p) {
+    #wrote;
+    constructor(p, wrote = () => { }) {
         this.#p = p;
+        this.#wrote = wrote;
     }
     open(heir, being, id) {
         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
@@ -22,6 +25,7 @@ export class Heirs {
         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.
@@ -76,19 +80,22 @@ 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, by, next, seq) {
-        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, by, next) {
         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/dist/ward/owner.d.ts

@@ -1,32 +1,11 @@
-import type { Ask, Asker, Invitation, Json, JsonObject, Wanted } from '../being/types.ts';
+import type { Ask, Asker, Json, JsonObject } from '../being/types.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>;
     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;
 };

package/dist/ward/owner.js

@@ -9,13 +9,14 @@
 // 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.js';
-import { digest } from '../being/digest.js';
 import { OWNER } from '../being/types.js';
+import { put } from './partition.js';
+import { seen } from './door.js';
 const str = { type: 'string' };
 export const OWNER_ASKS = [
     { 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',
@@ -36,16 +37,20 @@ export async function ownerAnswer(w, asker, method, args) {
         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)
+        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 };
@@ -60,8 +65,14 @@ export async function ownerAnswer(w, asker, method, args) {
             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 : undefined);
     }
     if (method === 'knock') {
         const b = args.being;
@@ -73,6 +84,8 @@ export async function ownerAnswer(w, asker, method, args) {
             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);
@@ -130,22 +143,18 @@ export async function ownerAnswer(w, asker, method, args) {
     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.
+// 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) {
     const beings = {};
     for (const [key, door] of w.doors) {
         if (key === w.pk)
             continue;
-        let d = null;
-        try {
-            const bp = await door.being.answer({ id: OWNER });
-            d = isSilence(bp) || isWord(bp) ? null : await digest(bp);
-        }
-        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/dist/ward/seal.js

@@ -1,5 +1,6 @@
 import { isDoorWord } from '../being/silence.js';
 import { KEY, SIGNATURE, box, concat, hex, sha256, sign, signingPair, sealingPair, unbox, unhex, verify } from './arithmetic.js';
+import { cellFault } from './cells.js';
 const utf8 = new TextEncoder();
 const text = new TextDecoder();
 // The ward's key from its seed. Its pk on the wire is the signing pk then the padlock, 128 hex.
@@ -49,6 +50,8 @@ export async function openAsk(bytes, padlockSecret) {
             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

package/dist/ward/stance.d.ts

@@ -1,4 +1,4 @@
-import type { Cells, JsonObject, Silence, Stance, Wanted, Word } from '../being/types.ts';
+import type { Cells, Invitation, JsonObject, Silence, Stance, Wanted, Word } from '../being/types.ts';
 import { type Bind, type StandingKeys } from './partition.ts';
 import { type ReplyPayload } from './seal.ts';
 export type Inside = {
@@ -11,6 +11,9 @@ export type Inside = {
     closeHeir(heir: string): void;
     send(bind: Bind, keys: StandingKeys, announce: boolean, method: string | undefined, args: JsonObject, wanted: Wanted | undefined): Promise<ReplyPayload | Silence | Word>;
     instantiate(key: string, className: string): string | null;
+    relate(key: string, id: string): Promise<Invitation | null>;
+    unmake(key: string): void;
+    wrote(): void;
 };
 export type SealedInvitation = {
     ward: string;