@quo-systems/quo 0.1.0 → 0.2.0

package/dist/ward/index.d.ts

@@ -0,0 +1,8 @@
+export { Ward } from './ward.ts';
+export type { Ground, WardPointers } from './ground.ts';
+export type { Partition, Heir, Bind, StandingKeys } from './partition.ts';
+export type { AskPayload, ReplyPayload } from './seal.ts';
+export * as seal from './seal.ts';
+export * as arithmetic from './arithmetic.ts';
+export { allow, spent, DEFAULT, CEILING } from './allowance.ts';
+export type { Allowance } from './allowance.ts';

package/dist/ward/index.js

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+// @quo-systems/quo/ward — one function. Every ward is the same ward.
+export { Ward } from './ward.js';
+// The seal and the arithmetic, for a kit in another language to check its
+// bytes against, and for tests that speak to a door directly.
+export * as seal from './seal.js';
+export * as arithmetic from './arithmetic.js';
+// The allowance every ask carries, for a kit in another language and for
+// tests that speak to a door directly.
+export { allow, spent, DEFAULT, CEILING } from './allowance.js';

package/dist/ward/owner.d.ts

@@ -0,0 +1,32 @@
+import type { Asker, Invitation, Json, JsonObject, Wanted } from '../being/types.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;
+            };
+        };
+    }>;
+    publicKey(): string | null;
+    instantiate(key: string, className: string, isPublic?: boolean): {
+        key: string;
+    } | null;
+};
+export declare const OWNER_ASKS: readonly ['boot', 'invite', 'knock', 'remove'];
+export declare function ownerAnswer(w: OwnerSide, asker: Asker, method: string | undefined, args: JsonObject): Promise<Json>;

package/dist/ward/owner.js

@@ -0,0 +1,116 @@
+// 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. Five asks:
+// describe, boot, invite, knock, remove. 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.js';
+import { digest } from '../being/digest.js';
+import { OWNER } from '../being/types.js';
+export const OWNER_ASKS = ['boot', 'invite', 'knock', 'remove'];
+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);
+    if (method === undefined)
+        return describe(w);
+    if (method === 'boot') {
+        // 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.
+        if (args.public === true && w.publicKey() !== null)
+            return { error: 'a ward has one public being' };
+        const key = word(args.key), className = word(args.class);
+        if (key === null || className === null)
+            return { error: 'no such class, or key taken' };
+        const door = w.instantiate(key, className, args.public === true);
+        return door ? { booted: door.key } : { error: 'no such class, or key taken' };
+    }
+    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 = word(args.being), 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' };
+        const door = w.doors.get(being);
+        return door ? await door.stance.occupants.invite(id) : { error: 'no such being' };
+    }
+    if (method === 'knock') {
+        const b = args.being;
+        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 = word(b.key), className = word(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 id = word(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;
+        // 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, args.args ?? {}, args.wanted);
+        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 = word(args.being), 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' };
+        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 };
+    }
+    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.
+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 };
+    }
+    return {
+        asks: OWNER_ASKS.map((name) => ({ name, input: { type: 'object' } })),
+        notes: { pk: w.pk, beings },
+    };
+}

package/dist/ward/partition.d.ts

@@ -0,0 +1,57 @@
+import type { Cells } from '../being/types.ts';
+export declare const VERSION = "pre-1.0.0";
+export declare const READS: readonly string[];
+export type Heir = {
+    being: string;
+    id: string;
+    current: string;
+    announced: string | null;
+    fresh: boolean;
+    mark: number;
+    spent: number[];
+    last?: {
+        seq: number;
+        reply: string;
+    };
+};
+export type StandingKeys = {
+    ward: string;
+    heir: string | null;
+    current: string;
+    next: string | null;
+    seq: number;
+};
+export type Bind = {
+    standings: Record<string, StandingKeys>;
+    occupants: Record<string, string>;
+    knocks: Record<string, {
+        current: string;
+        next: string | null;
+        spoke: boolean;
+        sent: boolean;
+        seq: number;
+    }>;
+    answered: Record<string, true>;
+    minted: string[];
+};
+export type Gone = {
+    current: string;
+    announced: string | null;
+};
+export declare const GONE = 256;
+export type Partition = {
+    version: string;
+    beings: Record<string, Cells & {
+        class?: string;
+    }>;
+    bind: Record<string, Bind>;
+    heirs: Record<string, Heir>;
+    gone: Record<string, Gone>;
+    public: string | null;
+};
+export declare function open(memory: Record<string, unknown>): Partition;
+export declare const at: <T>(rec: Record<string, T>, key: string) => T | undefined;
+export declare const put: <T>(rec: Record<string, T>, key: string, value: T) => T;
+export declare const drop: (rec: Record<string, unknown>, key: string) => void;
+export declare const emptyCells: () => Cells;
+export declare const emptyBind: () => Bind;

package/dist/ward/partition.js

@@ -0,0 +1,64 @@
+// The shape of everything below. A ward stamps what it writes and refuses
+// what it cannot read: the partition outlives the ward that wrote it, and a
+// ward that guessed at a shape it did not know would not fail, it would answer
+// wrongly on relations it had silently misread.
+//
+// One value, and it does not move until 1.0.0. Before a release there is
+// nobody holding a partition of another shape to tell apart: if the types
+// below change, the partition is thrown away, not migrated to and not counted.
+// A number that climbed with every change would be a changelog, and the only
+// question asked here is answered by equality — is this a partition this ward
+// can read. At 1.0.0 this changes once, and from then on it means something.
+export const VERSION = 'pre-1.0.0';
+// Every version this ward can read, newest last. Today it is one, and the
+// seam below is what makes it able to be more than one later: a partition
+// written under an older readable version is carried forward by `upgrade`
+// before the ward touches it. The seam is here before 1.0.0 because after
+// 1.0.0 there is nowhere to put it. A partition holds every secret and every
+// relation a world has, so the first shape change after the freeze cannot be
+// answered by throwing it away, and a ward that meets a shape it has no seam
+// for refuses to boot with everything still inside it.
+export const READS = [VERSION];
+// Carry a partition written under an older readable version forward to this
+// one. There is nothing to carry today, because READS has one member. Each
+// step added here is from one member of READS to the next.
+function upgrade(p) {
+    return p;
+}
+export const GONE = 256;
+// 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.
+export function open(memory) {
+    const p = memory;
+    if (Object.keys(memory).length > 0 && p.version !== VERSION) {
+        if (!READS.includes(p.version))
+            throw new Error(`partition is version ${p.version}, this ward reads ${READS.join(', ')}`);
+        upgrade(p).version = VERSION;
+    }
+    p.version ??= VERSION;
+    p.beings ??= {};
+    p.bind ??= {};
+    p.heirs ??= {};
+    p.gone ??= {};
+    p.public ??= null;
+    return 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
+// itself: read, it is there where nothing was put; written, it reaches every
+// object alive in the runtime. Own keys only, both ways, and a write that
+// names one of those lands on the record where it belongs.
+export const at = (rec, key) => (Object.hasOwn(rec, key) ? rec[key] : undefined);
+export const put = (rec, key, value) => {
+    Object.defineProperty(rec, key, { value, writable: true, enumerable: true, configurable: true });
+    return value;
+};
+export const drop = (rec, key) => {
+    if (Object.hasOwn(rec, key))
+        delete rec[key];
+};
+export const emptyCells = () => ({ standings: {}, occupants: {} });
+export const emptyBind = () => ({ standings: {}, occupants: {}, knocks: {}, answered: {}, minted: [] });

package/dist/ward/seal.d.ts

@@ -0,0 +1,50 @@
+import type { DoorWord, Json, JsonObject } from '../being/types.ts';
+export type WardKey = {
+    sign: Uint8Array;
+    padlock: Uint8Array;
+    signPk: Uint8Array;
+    padlockPk: Uint8Array;
+    pk: string;
+};
+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 function beingKey(seed: Uint8Array): Promise<{
+    seed: string;
+    pk: string;
+}>;
+export type AskPayload = {
+    by: string;
+    next: string | null;
+    seq: number;
+    time: number;
+    hops?: number;
+    method?: string;
+    args: JsonObject;
+};
+export type ReplyPayload = {
+    object: Json;
+    seen: string | null;
+} | {
+    silence: true;
+} | {
+    quo: DoorWord;
+};
+export declare function sealAsk(to: string | null, payload: AskPayload, signer: Uint8Array, padlock: Uint8Array, seed: Uint8Array): Promise<{
+    bytes: Uint8Array;
+    ephemeral: Uint8Array;
+}>;
+export declare function openAsk(bytes: Uint8Array, padlockSecret: Uint8Array): Promise<{
+    to: string | null;
+    payload: AskPayload;
+    body: Uint8Array;
+    signature: Uint8Array;
+    ephemeralPk: Uint8Array;
+} | null>;
+export declare const verifyAsk: (a: {
+    body: Uint8Array;
+    signature: Uint8Array;
+}, pk: string) => Promise<boolean>;
+export declare function sealReply(reply: ReplyPayload, ephemeralPk: Uint8Array, wardSign: Uint8Array, seed: Uint8Array): Promise<Uint8Array>;
+export declare function openReply(bytes: unknown, ephemeralSecret: Uint8Array, signPk: Uint8Array): Promise<ReplyPayload | null>;

package/dist/ward/seal.js

@@ -0,0 +1,109 @@
+import { isDoorWord } from '../being/silence.js';
+import { KEY, SIGNATURE, box, concat, hex, sha256, sign, signingPair, sealingPair, unbox, unhex, verify } from './arithmetic.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.
+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);
+    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);
+// 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) };
+}
+// Seal an ask. Returns the bytes and the ephemeral secret the reply will be sealed to.
+export async function sealAsk(to, payload, signer, padlock, seed) {
+    const body = utf8.encode(JSON.stringify({ to, ...payload }));
+    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, padlockSecret) {
+    try {
+        if (!(bytes instanceof Uint8Array) || bytes.length < 1)
+            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 = JSON.parse(text.decode(body));
+        // 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)))
+            return null;
+        if (typeof payload.by !== 'string' || !/^[0-9a-f]{64}$/.test(payload.by))
+            return null;
+        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 (!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 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, pk) => 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, ephemeralPk, wardSign, seed) {
+    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 present and seen a digest or null.
+// 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, ephemeralSecret, signPk) {
+    try {
+        if (!(bytes instanceof Uint8Array))
+            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 = JSON.parse(text.decode(body));
+        if (reply === null || typeof reply !== 'object' || Array.isArray(reply))
+            return null;
+        const r = reply;
+        if (r.silence === true)
+            return { silence: true };
+        if (Object.hasOwn(r, 'quo'))
+            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)))
+            return null;
+        return { object: r.object, seen: r.seen };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/ward/stance.d.ts

@@ -0,0 +1,19 @@
+import type { Cells, 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;
+    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>;
+};
+export type SealedInvitation = {
+    ward: string;
+    heir?: string;
+    secret?: string;
+};
+export declare function buildStance(inside: Inside, key: string, cells: Cells, bind: Bind): Stance;