@quo-systems/quo 0.1.0 → 0.1.1

package/dist/ward/stance.js

@@ -0,0 +1,250 @@
+// 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, isUnreached } from '../being/silence.js';
+import { digest } from '../being/digest.js';
+import { RESERVED_IDS } from '../being/types.js';
+import { at, put, drop } from './partition.js';
+import { allow, within, LATE } from './allowance.js';
+import { isWardPk } from './seal.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) {
+    // 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
+    // naming a ward of their own. Filed under the heir alone, that invitation
+    // would share her knock record with the relation the heir really belongs to:
+    // it would sign with that relation's key, and an answer to it would set the
+    // answered flag the other relation is taken on. Both halves, always.
+    const nameOf = (inv) => (inv.heir === undefined ? `public:${inv.ward}` : `${inv.ward}:${inv.heir}`);
+    const valid = (inv) => {
+        const i = inv;
+        if (!i || typeof i !== 'object' || !isWardPk(i.ward))
+            return false;
+        if (i.heir === undefined)
+            return i.secret === undefined;
+        return typeof i.heir === 'string' && typeof i.secret === 'string' && /^[0-9a-f]{64}$/.test(i.heir) && /^[0-9a-f]{64}$/.test(i.secret);
+    };
+    // One relation, one ask at a time. The rotation is a conversation: a send
+    // reads the key that speaks now, announces the next, and moves to it once
+    // the far door has answered. Two sends interleaving on one relation read
+    // each other's half-written keys and the two sides diverge, which no later
+    // ask can repair. So each relation has a lane, and a send waits for the one
+    // before it. Beings may still ask concurrently: the lanes are per relation,
+    // and a slow relation never holds up another.
+    const lanes = new Map();
+    const lane = (name, run) => {
+        const mine = (lanes.get(name) ?? Promise.resolve()).then(run, run);
+        const quiet = mine.then(() => { }, () => { });
+        lanes.set(name, quiet);
+        void quiet.then(() => {
+            if (lanes.get(name) === quiet)
+                lanes.delete(name); // the lane is idle. nothing to remember.
+        });
+        return mine;
+    };
+    // Every ask a being makes, bounded. The bound is outside the lane on
+    // purpose: an ask that waits its turn behind a relation that comes back
+    // round never reaches a send, and a bound that only watched the wire would
+    // never see it hang. A bound that ran out is silence, never unreached:
+    // unreached promises nothing was delivered and is safe to ask again, and a
+    // wait that gave up knows no such thing.
+    //
+    // The bell rings before the work is reached, too: an ask that was still
+    // waiting its turn when the wait ran out is never sent. Sent then, it would
+    // be a fresh ask nobody is waiting on, the far being would do the work, and
+    // what came back would be read into her cells behind a silence she was
+    // already handed. So the work is given the bell, and reads it at the lane.
+    const bounded = async (wanted, work) => {
+        let late = false;
+        const out = await within(allow(wanted).time, work(() => !late), () => {
+            late = true;
+        });
+        return out === LATE ? silence : out;
+    };
+    const send = async (keys, method, args, wanted, rec) => {
+        const r = await inside.send(bind, keys, true, method, args, wanted);
+        if (isSilence(r) || isUnreached(r))
+            return r;
+        if ('silence' in r)
+            return silence;
+        if (rec && method !== undefined && r.seen !== null)
+            rec.seen = r.seen; // the digest rode along
+        return r.object;
+    };
+    const knocking = async (inv, method, args, wanted) => {
+        const name = nameOf(inv);
+        // her own key for this relation, minted once: rotation two. reused if she knocks again.
+        const k = (bind.knocks[name] ??= { current: (await inside.mintKey(bind)).seed, next: null, spoke: false, sent: false, seq: 0 });
+        // the first knock on a heir speaks as the heir, the key the inviter handed out, and announces her own.
+        // once bytes have come back, the heir is spent whatever they said, and her own key speaks.
+        // She sent once as the heir and nothing came back. Either the door heard,
+        // spent the heir and rotated to the key she announced, or nothing arrived
+        // and the heir still stands. Only the far door knows, and it will not say.
+        //
+        // So she asks, and the asking tells her. Under her own key: if the door
+        // heard, that key is the one it admits, and she is answered. If it did
+        // not, the key means nothing there, the ask is refused, and a refusal at
+        // that door writes nothing — the heir is untouched and still speaks. Then
+        // she knocks as the heir, as she would have. One extra round trip in the
+        // one case where a reply was lost, and the relation is not stranded.
+        //
+        // No stranger gains anything by it: whoever holds the invitation could
+        // always knock as the heir, and her own key is admitted only where the
+        // door already bound it to her.
+        if (inv.heir !== undefined && !k.spoke && k.sent) {
+            const own = { ward: inv.ward, heir: inv.heir, current: k.current, next: k.next, seq: k.seq };
+            const r = await inside.send(bind, own, true, method, args, wanted);
+            k.seq = own.seq;
+            k.current = own.current;
+            k.next = own.next;
+            if (isUnreached(r))
+                return r; // still nothing. she knows no more than before.
+            if (!isSilence(r) && !('silence' in r)) {
+                k.spoke = true; // it was heard the first time, and this is the answer
+                bind.answered[name] = true;
+                return r.object;
+            }
+            // Refused. The door never heard her, so the heir is still hers to spend.
+        }
+        const first = inv.heir !== undefined && !k.spoke;
+        const keys = first ? { ward: inv.ward, heir: inv.heir, current: inv.secret, next: k.current, seq: k.seq } : { ward: inv.ward, heir: inv.heir ?? null, current: k.current, next: k.next, seq: k.seq };
+        const r = await inside.send(bind, keys, true, method, args, wanted);
+        k.sent = true; // bytes went out. whether they arrived is the far door's to know.
+        // The number she spoke under, and the key she announced, kept whoever
+        // answered and kept when nobody did. A reply lost on the way back is a
+        // door that has already honoured the number: she must not offer it twice,
+        // or a road that drops one reply silences the relation for good.
+        k.seq = keys.seq;
+        if (!first) {
+            k.current = keys.current;
+            k.next = keys.next;
+        }
+        if (isUnreached(r))
+            return r; // nothing came back. she does not know whether it was heard.
+        k.spoke = true;
+        if (isSilence(r) || 'silence' in r)
+            return silence;
+        bind.answered[name] = true;
+        return r.object;
+    };
+    // The id she took this relation under, if she took it. One relation is one
+    // ward and one heir whichever door it is reached by, so the standing and the
+    // invitation answer to the same name.
+    const keyName = (k) => (k.heir === null ? `public:${k.ward}` : `${k.ward}:${k.heir}`);
+    const takenAs = (name) => Object.keys(bind.standings).find((id) => keyName(bind.standings[id]) === name);
+    const calls = {
+        knock: async (inv, method, args = {}, wanted) => {
+            if (!valid(inv))
+                return silence;
+            // She may knock again, and after take that knock is an ask: the relation
+            // has one home, so it answers on the standing's lane, under the
+            // standing's keys and its count. A second lane here would speak for the
+            // same relation, and the two would refuse each other.
+            const id = takenAs(nameOf(inv));
+            if (id !== undefined)
+                return bounded(wanted, (live) => lane(`ask:${id}`, () => (live() ? asking(id, bind.standings[id], cells.standings[id], method, args, wanted) : Promise.resolve(silence))));
+            return bounded(wanted, (live) => lane(`knock:${nameOf(inv)}`, () => (live() ? knocking(inv, method, args, wanted) : Promise.resolve(silence))));
+        },
+        // Take consumes. Until now the relation lived in the knock record, under
+        // the ward and the heir; from now it lives in the standing, under her id.
+        // It never lives in both: two records seeded from one relation are two
+        // lanes speaking for one line of keys and one count, and whichever spoke
+        // last holds it while the other is refused. She would read that refusal as
+        // the far being falling quiet, which is a thing a sovereign being may do,
+        // so the loss would look exactly like an answer she is owed nothing of.
+        // One relation, one home, and the invitation is spent: knocking it again
+        // is another consumed it, and taking it again births nothing.
+        //
+        // So it is spoken on the relation's lane, like every other word spoken
+        // for it. A take reads the count and the keys a knock writes, and copies
+        // them into the standing. Off the lane it reads them between a knock's
+        // send and its answer: the standing is born holding a number the far door
+        // is about to honour and a key it is about to rotate past, and her first
+        // ask on it is refused. The relation she took correctly would be dead
+        // because a second knock on the same invitation was careless.
+        take: async (id, inv) => {
+            if (!valid(inv))
+                return null;
+            const name = nameOf(inv);
+            return lane(`knock:${name}`, () => {
+                if (!bind.answered[name])
+                    return Promise.resolve(null);
+                // Standings and occupants are one namespace — invite and take each
+                // refuse a name the other holds — so a word reserved in one is
+                // reserved in both.
+                if (reserved(id) || at(cells.standings, id) || at(cells.occupants, id))
+                    return Promise.resolve(null);
+                const k = bind.knocks[name];
+                put(bind.standings, id, { ward: inv.ward, heir: inv.heir ?? null, current: k.current, next: k.next, seq: k.seq }); // the count carries over: the standing goes on where the knock left off
+                put(cells.standings, id, { id, digest: null, blueprint: null, seen: null });
+                delete bind.knocks[name];
+                delete bind.answered[name];
+                return Promise.resolve(id);
+            });
+        },
+        remove: (id) => {
+            drop(cells.standings, id);
+            drop(bind.standings, id);
+        },
+    };
+    const standingAt = (id) => ({
+        id,
+        // The keys are read now, not when the lane reaches this ask: an ask
+        // issued while the standing stood is answered even if she drops it in
+        // the next line. Waiting for the lane is not a reason to lose it.
+        ask: (method, args = {}, wanted) => {
+            const keys = at(bind.standings, id);
+            if (!keys)
+                return Promise.resolve(silence); // she dropped it between one line and the next
+            const rec = at(cells.standings, id);
+            return bounded(wanted, (live) => lane(`ask:${id}`, () => (live() ? asking(id, keys, rec, method, args, wanted) : Promise.resolve(silence))));
+        },
+    });
+    const asking = async (id, keys, rec, method, args, wanted) => {
+        const out = await send(keys, method, args, wanted, rec);
+        if (method === undefined && !isSilence(out) && !isUnreached(out)) {
+            const here = at(cells.standings, id);
+            if (here) {
+                here.blueprint = out;
+                here.digest = here.seen = await digest(out);
+            }
+        }
+        return out;
+    };
+    const standings = new Proxy(calls, {
+        // Own keys only: `in` would also find every name on Object's prototype,
+        // and a standing she took as `constructor` or `toString` would answer with
+        // Object's, not hers.
+        get: (t, id) => (typeof id === 'string' && Object.hasOwn(t, id) ? t[id] : typeof id === 'string' && at(cells.standings, id) ? standingAt(id) : undefined),
+    });
+    return {
+        cells,
+        occupants: {
+            // rotation one: the ward mints the occupant's first key and gives the secret away.
+            // it keeps the pk beside the id and nothing else. the invitation IS the key.
+            invite: async (id) => {
+                if (reserved(id) || at(cells.occupants, id) || at(cells.standings, id))
+                    return null;
+                put(cells.occupants, id, { id, notes: {} });
+                const k = await inside.mintKey(bind);
+                inside.openHeir(k.pk, key, id);
+                put(bind.occupants, id, k.pk);
+                return { ward: inside.pk, heir: k.pk, secret: k.seed };
+            },
+            remove: (id) => {
+                drop(cells.occupants, id);
+                const heir = at(bind.occupants, id);
+                drop(bind.occupants, id);
+                if (heir)
+                    inside.closeHeir(heir); // the heir dies with the id
+            },
+        },
+        standings,
+    };
+}

package/dist/ward/ward.d.ts

@@ -0,0 +1,2 @@
+import type { Ground, WardPointers } from './ground.ts';
+export declare function Ward(ground: Ground): Promise<WardPointers>;

package/dist/ward/ward.js

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: Apache-2.0
+// A ward that is its own ward. Booted by a harbor with one object, the
+// ground, and hands back two pointers: the door and the ask. Boots itself as
+// the first being in its own map, and every being it later instantiates gets
+// a stance built by the same code. Mints every key, seals every ask that
+// leaves, opens every one that arrives.
+import { silence, isSilence, unreached, isUnreached } from '../being/silence.js';
+import { OWNER } from '../being/types.js';
+import { at, open, put, emptyBind, emptyCells } from './partition.js';
+import { Heirs } from './heirs.js';
+import { makeDoor } from './door.js';
+import { buildStance } from './stance.js';
+import { ownerAnswer } from './owner.js';
+import { allow, within, LATE } from './allowance.js';
+import { beingKey, openReply, sealAsk, wardKey, wardPadlock, wardSignPk } from './seal.js';
+import { unhex } from './arithmetic.js';
+import { guardCells, cellFault } from './cells.js';
+// How many minted pks she keeps behind her. Enough to name the keys in play.
+const MINTED = 8;
+// The ward. One call in, two pointers out. Async because keys are derived.
+export async function Ward(ground) {
+    const w = await Self.boot(ground);
+    return { door: w.door, ask: w.ask };
+}
+class Self {
+    key;
+    pk;
+    g;
+    p;
+    heirs;
+    doors = new Map();
+    door;
+    ask;
+    static async boot(ground) {
+        return new Self(ground, await wardKey(ground.seed));
+    }
+    constructor(ground, key) {
+        this.g = ground;
+        this.key = key;
+        this.pk = key.pk;
+        this.p = open(ground.memory); // the partition IS the ward's cells
+        this.heirs = new Heirs(this.p);
+        this.door = makeDoor(key, this.heirs, this.doors, () => this.p.public, (n) => ground.random(n)); // pointer one
+        this.#boot(this.pk, this); // the ward's ward is itself
+        // a restart is silent: every being in the cells is constructed again, unasked.
+        // A throw on a boot the owner asked for is that boot's answer: silence,
+        // and nothing half-lives. This boot nobody asked for, and there is nobody
+        // to hand a silence to. Any constructor may throw — a default that is not
+        // a value, an author's mistake, a shape she no longer recognises after an
+        // upgrade — and let through here it is one being taking down the ward and
+        // every other being in it, on a restart. She is absent instead: no door,
+        // so silence at the door, and her cells sit untouched, waiting for the
+        // run that can read them.
+        for (const [k, c] of Object.entries(this.p.beings)) {
+            if (k === this.pk || !c.class)
+                continue;
+            try {
+                this.#instantiate(k, c.class);
+            }
+            catch {
+                /* she is not here this run. the ward is, and so is everyone else. */
+            }
+        }
+        // pointer two. the owner. the same answer every named asker gets, asker filled in as owner.
+        this.ask = async (method, args = {}) => {
+            try {
+                const out = await this.answer({ id: OWNER }, method, args);
+                return isSilence(out) || isUnreached(out) ? silence : out;
+            }
+            catch {
+                return silence;
+            }
+        };
+    }
+    // ---- the ward as a being. asked only by its owners: the root, through
+    // the ask pointer, and its occupants, through the door, whom only the root
+    // can invite. A stranger cannot be a named asker here, because the door
+    // names nobody the ward did not bind.
+    async answer(asker, method, args = {}) {
+        if (asker.id === undefined)
+            return { error: 'unknown ask' };
+        return ownerAnswer({
+            pk: this.pk,
+            doors: this.doors,
+            publicKey: () => this.p.public,
+            instantiate: (key, className, isPublic) => this.#instantiate(key, className, isPublic),
+        }, asker, method, args);
+    }
+    // ---- ward functions. on the object. no stance reaches them.
+    #instantiate(key, className, isPublic = false) {
+        if (!key || this.doors.has(key))
+            return null;
+        const door = this.#boot(key, className);
+        if (!door)
+            return null;
+        door.cells.class = className; // so a restart finds her
+        if (isPublic)
+            this.p.public = key;
+        return door;
+    }
+    // Nothing is written until there is somebody to write it for: a class the
+    // harbor does not know makes no being, and a boot that made nobody must
+    // leave the partition as it found it.
+    #boot(key, classNameOrSelf) {
+        const cells = guardCells(at(this.p.beings, key) ?? emptyCells());
+        const bind = at(this.p.bind, key) ?? emptyBind();
+        const stance = buildStance({
+            pk: this.pk,
+            mintKey: (b) => this.#mintKey(b),
+            openHeir: (heir, being, id) => this.heirs.open(heir, being, id),
+            closeHeir: (heir) => this.heirs.close(heir),
+            send: (b, keys, announce, method, args, wanted) => this.#send(b, keys, announce, method, args, wanted),
+        }, key, cells, bind);
+        const being = classNameOrSelf === this ? this : this.g.instantiate(classNameOrSelf, stance);
+        if (!being)
+            return null;
+        put(this.p.beings, key, cells);
+        put(this.p.bind, key, bind);
+        const door = { key, cells, bind, stance, being };
+        this.doors.set(key, door);
+        return door;
+    }
+    async #mintKey(bind) {
+        const k = await beingKey(this.g.random(32));
+        // The last few she 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. Nothing is read from this
+        // but the keys of the moment.
+        bind.minted.push(k.pk);
+        if (bind.minted.length > MINTED)
+            bind.minted.splice(0, bind.minted.length - MINTED);
+        return k;
+    }
+    // One send for every door, the ward's own included. Mine: never leaves.
+    // Not mine: carry. Signs as the standing's current key, announces its
+    // next, seals to the far ward, opens the reply with the ephemeral secret,
+    // and rotates to the announced key once the far door has answered under
+    // the current one.
+    async #send(bind, keys, announce, method, args, wanted) {
+        // What she asked for, held to what this ward allows. Asking for nothing is
+        // the default, and asking for more than the ceiling is the ceiling: budget
+        // is granted by a ward, never minted by a being.
+        const budget = allow(wanted);
+        const by = (await beingKey(unhex(keys.current))).pk;
+        // A public being is reached without a heir, and the door keeps nothing for
+        // whoever asked: no key it vouched for, so nothing to announce and nothing
+        // to rotate to. A standing on her signs with one key for life.
+        if (announce && keys.next === null && keys.heir !== null)
+            keys.next = (await this.#mintKey(bind)).seed;
+        const next = keys.next === null ? null : (await beingKey(unhex(keys.next))).pk;
+        // Her count for this relation, one higher every call and never reused. The
+        // far door honours each number once. One relation sends one at a time, so
+        // the numbers leave in the order they were taken.
+        const seq = (keys.seq += 1);
+        // Args that will not go through the seal are args that never left. A
+        // being holds three answers and a throw is not one of them, so an ask
+        // that cannot be sealed is told what is true of it: no door was reached.
+        // Values only, by the same rule her cells keep: a Date would arrive as a
+        // string, a function would not arrive at all, and she would never know
+        // the far being was asked something other than what she said.
+        if (cellFault(args, 'args') !== null)
+            return unreached();
+        let sealed;
+        try {
+            sealed = await sealAsk(keys.heir, { by, next, seq, time: budget.time, method, args }, unhex(keys.current), wardPadlock(keys.ward), this.g.random(32));
+        }
+        catch {
+            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.
+        //
+        // A wait that ran out is silence, never unreached. Unreached promises
+        // nothing was delivered and is safe to retry; a bound that expired knows
+        // no such thing, because the far door may have heard and be working still.
+        //
+        // A harbor answers bytes or nothing. One that throws instead has answered
+        // nothing in a louder voice, and is read as nothing: no door was reached.
+        const carried = (keys.ward === this.pk ? this.door(new Uint8Array(bytes)) : this.g.carry(keys.ward, bytes)).then((b) => b, () => undefined);
+        const out = await within(budget.time, carried);
+        if (out === LATE)
+            return silence;
+        if (out === undefined)
+            return unreached(); // nothing came back. no door was reached.
+        const reply = await openReply(out, ephemeral, wardSignPk(keys.ward));
+        if (!reply)
+            return silence; // did not open, or not from that ward
+        if (!('silence' in reply) && keys.next !== null) {
+            keys.current = keys.next; // the far door holds `next` as announced. move to it.
+            keys.next = null;
+        }
+        return reply;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quo-systems/quo",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Quo: an object asks another object and gets an answer, without knowing where it is. Being, Ward, Harbor.",
   "keywords": [
     "quo",
@@ -18,20 +18,23 @@
     "node": ">=22.18"
   },
   "exports": {
-    ".": "./src/being/index.ts",
-    "./ward": "./src/ward/index.ts",
-    "./harbor": "./src/harbor/index.ts",
-    "./conformance": "./src/conformance/index.ts"
+    ".": { "types": "./dist/being/index.d.ts", "default": "./dist/being/index.js" },
+    "./ward": { "types": "./dist/ward/index.d.ts", "default": "./dist/ward/index.js" },
+    "./harbor": { "types": "./dist/harbor/index.d.ts", "default": "./dist/harbor/index.js" },
+    "./conformance": { "types": "./dist/conformance/index.d.ts", "default": "./dist/conformance/index.js" }
   },
   "scripts": {
-    "check": "npm run typecheck && npm run lint && npm test && npm run check:estate",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "check": "npm run build && npm run typecheck && npm run lint && npm test && npm run check:estate",
     "check:estate": "node --test \"estate/test/*.test.ts\"",
+    "pretypecheck": "npm run build",
     "typecheck": "tsc",
     "typecheck:watch": "tsc --watch",
     "lint": "npm run lint:ts && npm run lint:md",
     "lint:ts": "oxlint --type-aware",
     "lint:md": "markdownlint-cli2",
     "lint:fix": "oxlint --type-aware --fix && markdownlint-cli2 --fix",
+    "pretest": "npm run build",
     "test": "node --test \"test/*.test.ts\"",
     "check:terrain": "node --test \"test/terrain/*.test.ts\" \"estate/test/terrain/*.test.ts\"",
     "test:being": "node --test test/being.test.ts",
@@ -54,6 +57,7 @@
     "access": "public"
   },
   "files": [
+    "dist",
     "src",
     "vectors",
     "SPEC.md",

package/src/harbor/core.ts

@@ -9,8 +9,9 @@
 // tree, and every one of them passes the conformance suite untouched.
 //
 // The directory is filled three ways, in this order: the harbor's own
-// doors; a socket a dialer holds to it, bound at announce and unbound at
-// close; a hint from a link. And one fallback: a dialer with nothing in its
+// doors; a socket a dialer holds to it, bound once the door behind the
+// dialer's claim has proved it holds the key, and unbound at close; a hint
+// from a link. And one fallback: a dialer with nothing in its
 // directory for a pk sends down the socket it holds, because the listener
 // it dialed is the rendezvous and may hold that pk on another socket. Bytes
 // that arrive from the wire go to an own door or a held socket and never
@@ -19,6 +20,9 @@ import { Ward } from '../ward/ward.ts';
 import type { Ground, WardPointers } from '../ward/ground.ts';
 import type { BeingClass, BeingLike } from '../being/types.ts';
 import { request, type Reach } from './reach.ts';
+import { openReply, wardSignPk } from '../ward/seal.ts';
+import { concat, sealingPair, KEY } from '../ward/arithmetic.ts';
+import { within, LATE } from '../ward/allowance.ts';
 import type { Kept, Store, WardRecord } from './store.ts';
 
 export type Hosted = WardPointers & { pk: string; name: string; record: WardRecord; partition: Record<string, unknown>; being(key: string): BeingLike | undefined; save(): Promise<void> };
@@ -30,6 +34,9 @@ export type Bound = { reach: Reach; held: boolean };
 export type Loader = (record: WardRecord) => Promise<Record<string, BeingClass>>;
 
 export const DEFAULT_CODE = 'classes/index.ts';
+// How long a probe waits for the door behind a claim. A claim that answers
+// nothing in this time is not bound; the next announce is another chance.
+const PROBE = 10_000;
 
 export class Harbor {
   readonly store: Store;
@@ -95,8 +102,42 @@ export class Harbor {
     await this.store.hint(pk, url);
   }
 
-  bind(pks: string[], reach: Reach, held: boolean): void {
-    for (const pk of pks) if (!this.doors.has(pk)) this.reaches.set(pk, { reach, held });
+  // An announce is a claim, and a claim binds nothing until proven: anyone
+  // who can reach a listener could otherwise name a pk that is not theirs and
+  // take its reachability. The proof is the door itself, as it already is. A
+  // lid this harbor minted and noise after it is a box that does not open,
+  // and the door answers one such box with silence sealed to the lid and
+  // signed by the ward key. Only the holder of that ward's seed can write
+  // that reply, the lid is fresh so nothing replays, and a box that does not
+  // open writes nothing at the ward. This is the one box a harbor ever opens,
+  // the one it sealed itself, and it reads nothing from it but that the
+  // signature is the claimed key's.
+  async prove(pk: string, reach: Reach): Promise<boolean> {
+    if (!/^[0-9a-f]{128}$/.test(pk)) return false;
+    try {
+      const random = (n: number) => globalThis.crypto.getRandomValues(new Uint8Array(n));
+      const lid = await sealingPair(random(KEY));
+      const back = await within(PROBE, reach.carry(pk, concat([lid.pk, random(KEY)])));
+      if (back === LATE || back === undefined) return false;
+      const reply = await openReply(back, lid.secret, wardSignPk(pk));
+      return reply !== null && 'silence' in reply;
+    } catch {
+      return false;
+    }
+  }
+
+  // Bind what the far side claims, each pk proven at its door first. Both
+  // sides bind this way: the listener the dialer's claims, the dialer the
+  // listener's, since a claim is a claim whichever end made it.
+  async bind(pks: string[], reach: Reach, held: boolean): Promise<void> {
+    // An announce is the whole of what that side holds now, so a pk this
+    // reach was bound for and no longer claims is unbound at once: a ward
+    // that left a dialer is not reachable through it, proof or no proof.
+    for (const [pk, b] of this.reaches) if (b.reach === reach && !pks.includes(pk)) this.reaches.delete(pk);
+    await Promise.all(pks.map(async (pk) => {
+      if (this.doors.has(pk) || !(await this.prove(pk, reach))) return;
+      this.reaches.set(pk, { reach, held });
+    }));
   }
   unbind(reach: Reach): void {
     for (const [pk, b] of this.reaches) if (b.reach === reach) this.reaches.delete(pk);

package/src/harbor/dial.ts

@@ -30,7 +30,7 @@ export function dial(harbor: Harbor, url: string): Dialer {
         // not at the handshake: a listener that opens and then refuses every
         // time would otherwise be dialed at a fixed two seconds for good.
         wait = 1000;
-        harbor.bind(far, s, false); // the listener's pks: reached through this socket, not held for others
+        void harbor.bind(far, s, false); // the listener's claims, each proven at its door: reached through this socket, not held for others
       },
       (why) => {
         harbor.unbind(s);