@quo-systems/quo 0.2.14 → 0.2.16

package/dist/ward/seal.js

@@ -10,6 +10,14 @@ const text = new TextDecoder();
 // answering to one name is how a kit is read wrong.
 const WARD_SIGN = new TextEncoder().encode('quo-ward-sign');
 const WARD_SEAL = new TextEncoder().encode('quo-ward-seal');
+// The one size in Quo: one mebibyte of bytes each way. It is read before
+// anything is opened, so bytes above it are never decrypted, never parsed and
+// never allocated against. Refusing them is bytes that said nothing, which is
+// already silence, so there is no tenth word and no new door case. Breadth
+// costs bytes, so this one number bounds every other breadth on the wire, and
+// what a being holds is not the protocol's business. An ask is a message and
+// not a file; what is larger is asked for in pieces.
+export const SIZE = 1024 * 1024;
 // The ward's key from its seed. Its pk on the wire is the signing pk then the padlock, 128 hex.
 //
 // One seed, two curves, and each secret derived from it under its own label.
@@ -18,7 +26,7 @@ const WARD_SEAL = new TextEncoder().encode('quo-ward-seal');
 // 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.
+// said out loud, and it is what `protocol/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
@@ -55,7 +63,7 @@ export async function sealAsk(to, payload, signer, padlock, seed) {
 // 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)
+        if (!(bytes instanceof Uint8Array) || bytes.length < 1 || bytes.length > SIZE)
             return null;
         const inside = await unbox(bytes, padlockSecret);
         if (inside.length <= SIGNATURE)
@@ -109,7 +117,7 @@ export async function sealReply(reply, ephemeralPk, wardSign, seed) {
 // throw or an absent value for what a stranger wrote.
 export async function openReply(bytes, ephemeralSecret, signPk) {
     try {
-        if (!(bytes instanceof Uint8Array))
+        if (!(bytes instanceof Uint8Array) || bytes.length > SIZE)
             return null;
         const inside = await unbox(bytes, ephemeralSecret);
         if (inside.length <= SIGNATURE)

package/dist/ward/stance.d.ts

@@ -13,6 +13,7 @@ export type Inside = {
     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>;
+    lend(name: string, take: (invitation: Invitation) => Promise<boolean>): Promise<boolean>;
     unmake(key: string): void;
     wrote(): void;
 };

package/dist/ward/stance.js

@@ -1,20 +1,33 @@
 // SPDX-License-Identifier: Apache-2.0
 // The one stance builder. Used for every being the ward boots. Nothing
 // outer is in what she holds: ids in, values out, keys in the bind table.
-import { silence, isSilence, isWord, word, wordOf } from '../being/silence.js';
+import { silence, isSilence, isWord, unreached, word, wordOf } from '../being/silence.js';
 import { digest } from '../being/digest.js';
 import { RESERVED_IDS, isBlueprint } from '../being/types.js';
 import { at, put, drop, prune } from './partition.js';
 import { allow, within, LATE } from './allowance.js';
 import { isHex, isWardPk } from './seal.js';
-import { cellFault } from './cells.js';
+import { cellFault, unkeepable } from './cells.js';
 // The three calls on `standings` share the object with the ids she takes, so
 // a standing named after one of them would be unreachable: `standings.knock`
 // is the call, whatever record sits under that name. One namespace means one
 // list: these are refused at invite and at take, beside the ward's own words.
 const CALLS = ['knock', 'take', 'remove'];
-const reserved = (id) => RESERVED_IDS.includes(id) || CALLS.includes(id);
 export function buildStance(inside, key, cells, bind) {
+    // A word the ward refuses at every mint and every take. The two the
+    // protocol names, and the ones this kit adds because its own spelling took
+    // them: the calls a standing already answers to, and a name no partition
+    // can hold. That last one is refused here rather than by the cells guard,
+    // because the guard throws and this table promises a null.
+    // A method is a word or it is nothing at all. The seal writes a payload as
+    // JSON, which drops a key whose value it cannot write, so a symbol or a
+    // function here would leave as an ask with no method: the empty ask. She
+    // would have asked for work, been handed a blueprint, and spent a number on
+    // it. Nothing that cannot be sent is sent, and what never left is unreached,
+    // which is the one answer that says asking again is safe. This is the same
+    // rule args are already held to.
+    const named = (method) => method === undefined || typeof method === 'string';
+    const reserved = (id) => RESERVED_IDS.includes(id) || CALLS.includes(id) || unkeepable(id);
     // The name of one relation, as her side files it. A relation is a ward and
     // a heir, never a heir alone: the heir pk is outer, it rides in the clear on
     // every lid, and anyone who reads one can quote it back inside an invitation
@@ -189,6 +202,8 @@ export function buildStance(inside, key, cells, bind) {
         knock: async (inv, method, args = {}, wanted) => {
             if (gone())
                 return word('dropped');
+            if (!named(method))
+                return unreached();
             if (!valid(inv))
                 return word('invitation'); // S1. nothing is sent
             // She may knock again, and after take that knock is an ask: the relation
@@ -254,6 +269,8 @@ export function buildStance(inside, key, cells, bind) {
         ask: (method, args = {}, wanted) => {
             if (gone())
                 return Promise.resolve(word('dropped'));
+            if (!named(method))
+                return Promise.resolve(unreached());
             const keys = at(bind.standings, id);
             if (!keys)
                 return Promise.resolve(word('dropped')); // S2. she dropped it between one line and the next
@@ -324,6 +341,13 @@ export function buildStance(inside, key, cells, bind) {
             invite: async (id, notes) => {
                 if (gone() || reserved(id) || at(cells.occupants, id) || at(cells.standings, id))
                     return null;
+                // Notes are values, like everything else the partition keeps, and a
+                // spread copies one level: an object inside them would stay the
+                // caller's, a handle into her cells that writes past the guard and
+                // never says `wrote`, so what a restart brought back would not be
+                // what she read. Held to the rule and copied whole, or no invitation.
+                if (notes !== undefined && cellFault(notes, 'notes') !== null)
+                    return null;
                 // The key first, and nothing written until it exists: a record put
                 // before the mint would be a record a remove in the meantime drops
                 // with no heir to close, and the heir opened after it would name an
@@ -333,7 +357,7 @@ export function buildStance(inside, key, cells, bind) {
                     return null; // taken while the key was minted
                 // The notes are the terms the inviter minted under, hers to read on her
                 // gate. She may write more later; nobody outside ever writes them.
-                put(cells.occupants, id, { id, notes: notes ? { ...notes } : {} });
+                put(cells.occupants, id, { id, notes: notes ? JSON.parse(JSON.stringify(notes)) : {} });
                 inside.openHeir(k.pk, key, id);
                 put(bind.occupants, id, k.pk);
                 inside.wrote();
@@ -351,5 +375,39 @@ export function buildStance(inside, key, cells, bind) {
             },
         },
         standings,
+        // A standing at one of the things this device can do. The same three
+        // moves her boot makes, with the harbor's root doing the inviting instead
+        // of a being of this ward: ask the ground for the name, knock with what
+        // comes back, take it under the id she gave. She is handed the id.
+        //
+        // The invitation never reaches her, and that is the difference between
+        // this relation and every other she holds. Her own invitations are hers
+        // to give away, because giving one away is giving away her own relation.
+        // This one is the device's, minted for this ward alone, and a value she
+        // could copy is a capability she could hand to anyone. A being who wants
+        // to lend her device access to another does it in the open, by an ask of
+        // her own that forwards to this standing, where her gate reads who is
+        // asking and she can stop.
+        lend: async (name, id) => {
+            if (gone() || typeof name !== 'string' || typeof id !== 'string')
+                return null;
+            if (reserved(id) || at(cells.standings, id) || at(cells.occupants, id))
+                return null;
+            // Her half runs inside the harbor's call, so a knock that was refused
+            // and a take that lost the id both end with the harbor removing what it
+            // minted. Nothing half-lives here either.
+            const took = await inside.lend(name, async (inv) => {
+                // Read again: the ground was awaited, and a line of hers in between
+                // may have taken the id. Nothing is written for a relation she cannot
+                // hold, and the invitation goes back unspent.
+                if (gone() || reserved(id) || at(cells.standings, id) || at(cells.occupants, id))
+                    return false;
+                const out = await calls.knock(inv);
+                if (isSilence(out) || isWord(out))
+                    return false;
+                return (await calls.take(id, inv)) === id;
+            });
+            return took ? id : null;
+        },
     };
 }

package/dist/ward/ward.js

@@ -210,6 +210,11 @@ class Self {
             // never came about takes her out again.
             relate: async (k, id) => (await this.doors.get(k)?.stance.occupants.invite(id)) ?? null,
             unmake: (k) => void this.#unboot(k),
+            // What this device lends this ward's beings. The ward knocks and takes
+            // inside the harbor's own call and reads nothing in the value: which
+            // names there are, which ward may ask for one, and what becomes of one
+            // she did not take, is the harbor's and no word of the ward.
+            lend: async (name, take) => (await this.g.lend?.(name, take)) ?? false,
             wrote: () => this.#wrote(),
         }, key, cells, bind);
         const being = make(stance);
@@ -274,10 +279,14 @@ class Self {
             return unreached();
         }
         const { bytes, ephemeral } = sealed;
-        // The wait is bounded, and this is the one thing the ward times. A being
-        // holds three answers and a wait that does not end is none of them: a
-        // relation that comes back round holds a lane the answer needs, and only a
-        // bound on the wait can break that. What comes back late is not read.
+        // The wait is bounded here, and again around the lane in the stance. Two
+        // bounds and not one, because they end two different things: the stance's
+        // ends the wait a being is held in, and this one ends the occupancy of the
+        // relation's lane. A being holds three answers and a wait that does not
+        // end is none of them, and a lane nobody ever leaves is a relation the
+        // next ask never reaches. Only a bound on the wire breaks the second, and
+        // taking it out would leave one quiet far side holding the lane for good.
+        // What comes back late is not read.
         //
         // A wait that ran out is `late`, never unreached. Unreached promises
         // nothing was delivered and is safe to retry; a bound that expired knows

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quo-systems/quo",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Quo: an object asks another object and gets an answer, without knowing where it is. Being, Ward, Harbor.",
   "keywords": [
     "quo",
@@ -13,6 +13,7 @@
   ],
   "author": "Razvan Gherghina",
   "license": "Apache-2.0",
+  "homepage": "https://quo.systems",
   "type": "module",
   "engines": {
     "node": ">=22.18"
@@ -34,14 +35,14 @@
       "types": "./dist/conformance/index.d.ts",
       "default": "./dist/conformance/index.js"
     },
-    "./vectors/*": "./vectors/*",
+    "./protocol/*": "./protocol/*",
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp ../../papers/SPEC.md SPEC.md",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp ../../papers/SPEC.md protocol/SPEC.md && cp ../../papers/quo-kit.md quo-kit.md",
     "test": "node --test \"test/*.test.ts\"",
     "check:terrain": "node --test \"test/terrain/*.test.ts\"",
-    "prepublishOnly": "test \"$QUO_GATED\" = 1 || { echo 'publish from the root, gated once: npm run release' >&2; exit 1; }"
+    "prepublishOnly": "test \"$QUO_GATED\" = 1 || { echo 'publish from the root, gated once: npm run release:quo' >&2; exit 1; }"
   },
   "publishConfig": {
     "access": "public"
@@ -49,8 +50,8 @@
   "files": [
     "dist",
     "src",
-    "vectors",
-    "SPEC.md",
+    "protocol",
+    "quo-kit.md",
     "README.md",
     "LICENSE",
     "NOTICE"