@quo-systems/quo 0.2.9 → 0.2.11

package/dist/ward/owner.js

@@ -9,13 +9,15 @@
 // 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';
+import { within, DEFAULT, LATE } from './allowance.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: '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',
@@ -25,27 +27,40 @@ export const OWNER_ASKS = [
     { 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'] } },
 ];
 export async function ownerAnswer(w, asker, method, args) {
-    // Every name the owner gives is a word. 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.
-    const word = (v) => (typeof v === 'string' ? v : null);
+    // 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) => (typeof v === 'string' ? v : null);
     if (method === undefined)
         return describe(w);
     if (method === 'boot') {
-        const key = word(args.key), className = word(args.class);
+        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(key, className);
+        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.
-        const key = word(args.key);
+        // 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' };
-        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 };
@@ -55,13 +70,19 @@ export async function ownerAnswer(w, asker, method, args) {
         // 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 = word(args.being), id = word(args.id);
+        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);
-        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;
@@ -69,13 +90,17 @@ export async function ownerAnswer(w, asker, method, args) {
         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 = word(b.key), className = word(b.boot);
+            const key = named(b.key), className = named(b.boot);
             if (key === null || className === null)
                 return { error: 'no such being' };
-            const made = w.instantiate(key, className);
-            door = made ? w.doors.get(made.key) : w.doors.get(key);
+            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 = word(args.id);
+        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
@@ -97,7 +122,7 @@ export async function ownerAnswer(w, asker, method, args) {
         // 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 = word(args.being), id = word(args.id);
+        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)
@@ -121,7 +146,7 @@ export async function ownerAnswer(w, asker, method, args) {
         // 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 = word(args.being);
+        const being = named(args.being);
         if (being === null || being === w.pk)
             return { error: 'no such being' };
         const removed = w.unboot(being);
@@ -130,22 +155,23 @@ 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 };
+    // 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/dist/ward/partition.d.ts

@@ -39,6 +39,9 @@ export type Gone = {
     announced: string | null;
 };
 export declare const GONE = 256;
+export declare const MINTED = 8;
+export declare const KNOCKS = 64;
+export declare const prune: (knocks: Record<string, unknown>, answered: Record<string, true>) => void;
 export type Partition = {
     version: string;
     beings: Record<string, Cells & {

package/dist/ward/partition.js

@@ -26,11 +26,116 @@ function upgrade(p) {
     return p;
 }
 export const GONE = 256;
+// The last few pks a relation minted, and no more. A relation rotates on
+// every ask, so a list of all of them is a partition that grows for as long
+// as she keeps talking and can never be written down. It lives here, beside
+// the other bound on the durable shape, because it is a fact about what a
+// partition may hold and not about how a ward mints.
+export const MINTED = 8;
+// A knock record is a key she minted for one invitation, kept until she takes
+// it. Only take deletes one, so a being who knocks and never takes would grow
+// her bind table for the life of the ward, one secret seed at a time. The
+// list is bounded like `gone`: past the count the oldest go, and a relation
+// that answered outlives one that never did, since an answered knock is one
+// she may still take.
+export const KNOCKS = 64;
+export const prune = (knocks, answered) => {
+    const names = Object.keys(knocks);
+    if (names.length <= KNOCKS)
+        return;
+    const order = [...names.filter((n) => !answered[n]), ...names.filter((n) => answered[n])];
+    for (const old of order.slice(0, names.length - KNOCKS)) {
+        delete knocks[old];
+        delete answered[old];
+    }
+};
+// The shape, read before anything acts on it. A partition this ward wrote is
+// this shape by construction; one it adopted was written by a hand, another
+// kit, or a file that was cut short, and every field below is one the ward,
+// the door or the heirs then act on without looking again. A `spent` that is
+// not an array rejects the door's promise on the first bound ask, a `mark`
+// that is not a number honours every number ever sent and grows without
+// bound, a being row that is null refuses the whole ward at birth by
+// accident and says nothing about why. So the shape is read once, here, and
+// what is not it throws with the path that failed, which names the trouble
+// to whoever is holding the file.
+//
+// The rule, so the reader does not grow into a schema: read every field the
+// ward acts on, and refuse only what would make it act wrongly. So `minted`
+// must be a list, because she pushes to it, and the truth in `answered` is
+// not read, because anything there says answered and nothing else follows.
+// `last` is reserved and nobody reads it, so nobody reads its shape either;
+// the run that gives it a reader gives it a line here. A being's own cells
+// are hers, of any shape JSON carries, and only the two records the ward
+// keeps inside them are read.
+const fault = (path, want) => {
+    throw new Error(`partition ${path} is not ${want}`);
+};
+const table = (v, path) => (typeof v === 'object' && v !== null && !Array.isArray(v) ? v : fault(path, 'an object'));
+const list = (v, path) => (Array.isArray(v) ? v : fault(path, 'an array'));
+const text = (v, path) => void (typeof v === 'string' || fault(path, 'a string'));
+const orNull = (v, path) => void (v === null || typeof v === 'string' || fault(path, 'a string or null'));
+const whole = (v, path) => void (Number.isSafeInteger(v) || fault(path, 'a whole number'));
+const flag = (v, path) => void (typeof v === 'boolean' || fault(path, 'true or false'));
+function read(p) {
+    for (const [key, cells] of Object.entries(table(p.beings, 'beings'))) {
+        const c = table(cells, `beings.${key}`);
+        table(c.standings, `beings.${key}.standings`);
+        table(c.occupants, `beings.${key}.occupants`);
+        if (c.class !== undefined)
+            text(c.class, `beings.${key}.class`);
+    }
+    for (const [key, bind] of Object.entries(table(p.bind, 'bind'))) {
+        const b = table(bind, `bind.${key}`);
+        for (const [id, keys] of Object.entries(table(b.standings, `bind.${key}.standings`))) {
+            const w = `bind.${key}.standings.${id}`;
+            const s = table(keys, w);
+            text(s.ward, `${w}.ward`);
+            orNull(s.heir, `${w}.heir`);
+            text(s.current, `${w}.current`);
+            orNull(s.next, `${w}.next`);
+            whole(s.seq, `${w}.seq`);
+        }
+        for (const [id, pk] of Object.entries(table(b.occupants, `bind.${key}.occupants`)))
+            text(pk, `bind.${key}.occupants.${id}`);
+        for (const [name, keys] of Object.entries(table(b.knocks, `bind.${key}.knocks`))) {
+            const w = `bind.${key}.knocks.${name}`;
+            const k = table(keys, w);
+            text(k.current, `${w}.current`);
+            orNull(k.next, `${w}.next`);
+            flag(k.spoke, `${w}.spoke`);
+            flag(k.sent, `${w}.sent`);
+            whole(k.seq, `${w}.seq`);
+        }
+        table(b.answered, `bind.${key}.answered`);
+        for (const [i, pk] of list(b.minted, `bind.${key}.minted`).entries())
+            text(pk, `bind.${key}.minted[${i}]`);
+    }
+    for (const [pk, heir] of Object.entries(table(p.heirs, 'heirs'))) {
+        const h = table(heir, `heirs.${pk}`);
+        text(h.being, `heirs.${pk}.being`);
+        text(h.id, `heirs.${pk}.id`);
+        text(h.current, `heirs.${pk}.current`);
+        orNull(h.announced, `heirs.${pk}.announced`);
+        flag(h.fresh, `heirs.${pk}.fresh`);
+        whole(h.mark, `heirs.${pk}.mark`);
+        for (const [i, n] of list(h.spent, `heirs.${pk}.spent`).entries())
+            whole(n, `heirs.${pk}.spent[${i}]`);
+    }
+    for (const [pk, gone] of Object.entries(table(p.gone, 'gone'))) {
+        const g = table(gone, `gone.${pk}`);
+        text(g.current, `gone.${pk}.current`);
+        orNull(g.announced, `gone.${pk}.announced`);
+    }
+    orNull(p.public, 'public');
+    return p;
+}
 // The one place a ward reads state that another ward wrote. A fresh
 // memory becomes a partition of this version; anything already written must
-// say it is this version, and a ward that cannot read it does not boot. Birth is
-// where a ward is allowed to be loud: silence is the door's word, for asks
-// that were made, and no ask has been made yet.
+// say it is this version and be the shape this version names, and a ward that
+// cannot read it does not boot. Birth is where a ward is allowed to be loud:
+// silence is the door's word, for asks that were made, and no ask has been
+// made yet.
 export function open(memory) {
     const p = memory;
     if (Object.keys(memory).length > 0 && p.version !== VERSION) {
@@ -44,7 +149,7 @@ export function open(memory) {
     p.heirs ??= {};
     p.gone ??= {};
     p.public ??= null;
-    return p;
+    return read(p);
 }
 // One record, reached by a key a being or an owner chose. A bare lookup finds
 // every name on Object's prototype, so `__proto__` answers with the prototype

package/dist/ward/seal.d.ts

@@ -10,6 +10,7 @@ export declare function wardKey(seed: string | Uint8Array): Promise<WardKey>;
 export declare const wardSignPk: (pk: string) => Uint8Array;
 export declare const wardPadlock: (pk: string) => Uint8Array;
 export declare const isWardPk: (pk: unknown) => pk is string;
+export declare const isHex: (v: unknown) => v is string;
 export declare function beingKey(seed: Uint8Array): Promise<{
     seed: string;
     pk: string;

package/dist/ward/seal.js

@@ -1,18 +1,45 @@
 import { isDoorWord } from '../being/silence.js';
-import { KEY, SIGNATURE, box, concat, hex, sha256, sign, signingPair, sealingPair, unbox, unhex, verify } from './arithmetic.js';
+import { KEY, SIGNATURE, box, concat, derive, 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 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 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 `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) {
-    const raw = typeof seed === 'string' ? utf8.encode(seed) : seed;
-    const seed32 = raw.length === KEY ? raw : await sha256(raw);
-    const s = await signingPair(seed32);
-    const p = await sealingPair(seed32);
+    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) => unhex(pk.slice(0, KEY * 2));
 export const wardPadlock = (pk) => unhex(pk.slice(KEY * 2));
 export const isWardPk = (pk) => 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) => 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) {
     return { seed: hex(seed), pk: hex((await signingPair(seed)).pk) };
@@ -39,22 +66,23 @@ export async function openAsk(bytes, padlockSecret) {
         // 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 && !(typeof to === 'string' && /^[0-9a-f]{64}$/.test(to)))
+        if (to !== null && !isHex(to))
             return null;
-        if (typeof payload.by !== 'string' || !/^[0-9a-f]{64}$/.test(payload.by))
+        if (!isHex(payload.by))
             return null;
-        if (payload.next !== null && !(typeof payload.next === 'string' && /^[0-9a-f]{64}$/.test(payload.next)))
+        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. 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.
-        if (!Number.isSafeInteger(payload.time) || payload.time <= 0)
-            return null;
+        // 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))
@@ -99,7 +127,7 @@ export async function openReply(bytes, ephemeralSecret, signPk) {
             return isDoorWord(r.quo) ? { quo: r.quo } : null;
         if (!Object.hasOwn(r, 'object') || r.object === undefined)
             return null;
-        if (r.seen !== null && !(typeof r.seen === 'string' && /^[0-9a-f]{64}$/.test(r.seen)))
+        if (r.seen !== null && !isHex(r.seen))
             return null;
         return { object: r.object, seen: r.seen };
     }

package/dist/ward/stance.d.ts

@@ -1,16 +1,20 @@
-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 = {
     pk: string;
+    live(): boolean;
     mintKey(bind: Bind): Promise<{
         seed: string;
         pk: string;
     }>;
     openHeir(heir: string, being: string, id: string): void;
     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;
+    send(bind: Bind, keys: StandingKeys, method: string | undefined, args: JsonObject, wanted: Wanted | undefined): Promise<ReplyPayload | Silence | Word>;
+    instantiate(className: string, key: string): string | null;
+    relate(key: string, id: string): Promise<Invitation | null>;
+    unmake(key: string): void;
+    wrote(): void;
 };
 export type SealedInvitation = {
     ward: string;