@weaveprotocol/core 0.2.0 → 0.2.2

package/dist/network/mailbox.js

@@ -0,0 +1,125 @@
+/**
+ * @module network/mailbox
+ * Talking to a relay's mailbox: leaving a sealed knock under a door's topic,
+ * and reading what was left under one's own (`packages/relay/relay.mjs`).
+ *
+ * Each call opens its own short-lived socket, says one thing, waits for the
+ * answer and closes. A mailbox socket never joins a room, so it names no DID,
+ * and the relay can't tie a knock to the peer that left it or fetched it.
+ *
+ *   client → { type: 'drop', topic, blob, ttl? }       relay → { type: 'dropped', topic, id } | { type: 'refused', topic, reason }
+ *   client → { type: 'fetch', topic, after? }          relay → { type: 'mail', topic, items: [{ seq, id, at, blob }], more }
+ *   client → { type: 'challenge' }                     relay → { type: 'challenge', nonce }
+ *   client → { type: 'purge', topic, sign, ids?, sig } relay → { type: 'purged', topic, count } | { type: 'refused', topic, reason }
+ */
+/** At most this many pages per fetch: 16 knocks each, and a door holds 64 */
+const MAX_PAGES = 8;
+export function createMailboxClient(options = {}) {
+    const timeoutMs = options.timeoutMs ?? 8000;
+    /** Opens a socket, sends one message, and resolves with the first answer `pick` accepts */
+    function ask(relay, message, pick) {
+        return talk(relay, (send) => send(message), async (answer) => pick(answer));
+    }
+    /**
+     * Opens a socket and holds a short conversation: `start` says the first
+     * thing, `hear` answers what comes back (it may `send` again) and settles it
+     * by returning a value.
+     */
+    function talk(relay, start, hear) {
+        const Socket = options.WebSocket ?? globalThis.WebSocket;
+        if (!Socket)
+            return Promise.reject(new Error('No WebSocket here to reach a relay with'));
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const ws = new Socket(relay);
+            const finish = (error, value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                try {
+                    ws.close();
+                }
+                catch {
+                    // already closing
+                }
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+            };
+            const timer = setTimeout(() => finish(new Error(`${relay} did not answer`)), timeoutMs);
+            const say = (message) => ws.send(JSON.stringify(message));
+            ws.onopen = () => start(say);
+            ws.onerror = () => finish(new Error(`Could not reach ${relay}`));
+            ws.onclose = () => finish(new Error(`${relay} closed the connection`));
+            ws.onmessage = (event) => {
+                let answer;
+                try {
+                    answer = JSON.parse(String(event.data));
+                }
+                catch {
+                    return;
+                }
+                if (!answer || typeof answer !== 'object')
+                    return;
+                hear(answer, say).then((value) => {
+                    if (value !== undefined)
+                        finish(null, value);
+                }, (error) => finish(error instanceof Error ? error : new Error(String(error))));
+            };
+        });
+    }
+    const client = {
+        drop(relay, topic, blob, ttlSeconds) {
+            return ask(relay, { type: 'drop', topic, blob, ...(ttlSeconds ? { ttl: ttlSeconds } : {}) }, (answer) => {
+                if (answer.topic !== topic)
+                    return undefined;
+                if (answer.type === 'dropped' && typeof answer.id === 'string')
+                    return answer.id;
+                if (answer.type === 'refused')
+                    throw new Error(`${relay} refused the knock: ${String(answer.reason ?? 'no reason given')}`);
+                return undefined;
+            });
+        },
+        async fetch(relay, topic, after = 0) {
+            const found = [];
+            let from = after;
+            for (let page = 0; page < MAX_PAGES; page++) {
+                const { items, more } = await ask(relay, { type: 'fetch', topic, after: from }, (answer) => answer.type === 'mail' && answer.topic === topic && Array.isArray(answer.items)
+                    ? { items: answer.items.filter(isMailItem), more: answer.more === true }
+                    : undefined);
+                found.push(...items);
+                if (!more || items.length === 0)
+                    break;
+                from = Math.max(...items.map((item) => item.seq));
+            }
+            return found;
+        },
+        purge(relay, topic, sign, ids, signChallenge) {
+            return talk(relay, (send) => send({ type: 'challenge' }), async (answer, send) => {
+                if (answer.type === 'challenge' && typeof answer.nonce === 'string') {
+                    send({ type: 'purge', topic, sign, ...(ids ? { ids: [...ids] } : {}), sig: await signChallenge(answer.nonce) });
+                    return undefined;
+                }
+                if (answer.topic !== topic)
+                    return undefined;
+                if (answer.type === 'purged' && typeof answer.count === 'number')
+                    return answer.count;
+                if (answer.type === 'refused')
+                    throw new Error(`${relay} refused to clear the door: ${String(answer.reason ?? 'no reason given')}`);
+                return undefined;
+            });
+        },
+    };
+    return Object.freeze(client);
+}
+function isMailItem(value) {
+    const item = value;
+    return (!!item &&
+        Number.isSafeInteger(item.seq) &&
+        typeof item.id === 'string' &&
+        typeof item.at === 'number' &&
+        typeof item.blob === 'string');
+}
+//# sourceMappingURL=mailbox.js.map

package/dist/network/mailbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.js","sourceRoot":"","sources":["../../src/network/mailbox.ts"],"names":[],"mappings":"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"}

package/dist/node/host.d.ts

@@ -15,7 +15,7 @@
  * — through the carry spaces — which account asked for which.
  *
  * Subscriptions live in the host's own store, next to the carried spaces. The
- * payment side (`cli/src/host/…`) only ever moves a subscription's date.
+ * payment side (`packages/cli/src/host/…`) only ever moves a subscription's date.
  */
 import type { CryptoProvider } from '../types.js';
 import { type ServerAuth } from '../network/peer-auth.js';
@@ -39,7 +39,7 @@ export interface Subscription {
     };
     /** The payment provider's reference for whoever pays — nothing else about them is kept */
     readonly customer?: string;
-    /** A wallet payment asked for and not yet seen (`cli/src/wallet.ts`) */
+    /** A wallet payment asked for and not yet seen (`packages/cli/src/wallet.ts`) */
     readonly invoice?: Invoice;
 }
 /** A payment a host asked a wallet for: an exact amount, so the transfer that arrives says whose it is */

package/dist/node/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/node/host.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/node/host.ts"],"names":[],"mappings":"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"}

package/dist/node/index.d.ts

@@ -16,5 +16,5 @@ export type { StoreFactory, StoreOptions } from './stores.js';
 export type { Keeper } from '../space/roles.js';
 export { NODE_ACTIONS, runAction, checkActionInput } from './actions.js';
 export type { NodeAction, ActionSchema } from './actions.js';
-export type { P2PNode, NodeConfig, NodeNetworkConfig, CacheConfig, NodeSpaces, NodeRecords, NodeRecord, NodeEvent, SpaceSummary, SpaceStatus, SpaceProfile, NewSpace, InvitePreview, ListOptions, ConnectionState, DelegateParams, Delegated, NodeCollection, NodeCollections, DefineCollection, NodeAccount, NodeCarriers, NodeNotifications, NotifyView, NodeHosting, HostingView, CarrierSummary, AccountProfileView, NodeContacts, ContactView, ContactRequest, } from './types.js';
+export type { P2PNode, NodeConfig, NodeNetworkConfig, CacheConfig, NodeSpaces, NodeRecords, NodeRecord, NodeEvent, SpaceSummary, SpaceStatus, SpaceProfile, NewSpace, InvitePreview, ListOptions, ConnectionState, DelegateParams, Delegated, NodeCollection, NodeCollections, DefineCollection, NodeAccount, NodeCarriers, NodeNotifications, NotifyView, NodeHosting, HostingView, CarrierSummary, AccountProfileView, NodeContacts, ContactView, ContactRequest, NodeDoors, DoorView, KnockView, SentKnockView, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/node/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACpH,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5D,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAChG,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC9D,YAAY,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC7D,YAAY,EACV,OAAO,EACP,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,WAAW,EACX,eAAe,EACf,cAAc,EACd,SAAS,EACT,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACpH,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5D,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAChG,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC9D,YAAY,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC7D,YAAY,EACV,OAAO,EACP,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,WAAW,EACX,eAAe,EACf,cAAc,EACd,SAAS,EACT,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,cAAc,EACd,SAAS,EACT,QAAQ,EACR,SAAS,EACT,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/node/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/node/node.ts"],"names":[],"mappings":"AAqBA,OAAO,EAA+C,KAAK,UAAU,EAAkB,MAAM,qBAAqB,CAAC;AAkDnH,OAAO,KAAK,EASV,UAAU,EAaV,OAAO,EAER,MAAM,YAAY,CAAC;AAEpB,yEAAyE;AACzE,eAAO,MAAM,kBAAkB,EAAE,UAA+C,CAAC;AA+CjF;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAu5CrE"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/node/node.ts"],"names":[],"mappings":"AAqBA,OAAO,EAA+C,KAAK,UAAU,EAAkB,MAAM,qBAAqB,CAAC;AA6EnH,OAAO,KAAK,EAYV,UAAU,EAaV,OAAO,EAER,MAAM,YAAY,CAAC;AAEpB,yEAAyE;AACzE,eAAO,MAAM,kBAAkB,EAAE,UAA+C,CAAC;AA+CjF;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CA+sDrE"}

package/dist/node/node.js

@@ -30,8 +30,10 @@ import { DEFAULT_ICE_SERVERS } from '../network/rtc-transport.js';
 import { deriveInviteKey } from '../space/space-access.js';
 import { base64UrlDecode, base64UrlEncode } from '../utils/encoding.js';
 import { onePerKey } from '../records/rules.js';
-import { contactKeyPair, deriveMemberKeyBytes, openSealed, sealFor } from '../identity/contact-key.js';
-import { contact as contactSchema, contactRequest as contactRequestSchema } from '../schemas/contacts.js';
+import { contactKeyPair, contactPublicKey, deriveDoorKeyBytes, deriveDoorSignKeyBytes, deriveMemberKeyBytes, openSealed, sealFor } from '../identity/contact-key.js';
+import { contact as contactSchema, contactRequest as contactRequestSchema, door as doorSchema, knock as knockSchema, knockAnswer as knockAnswerSchema, } from '../schemas/contacts.js';
+import { checkAnswer, clip, doorTopic, encodeDoorCode, KNOCK_TTL_SECONDS, knockId, MAX_DOOR_RELAYS, openKnock, parseDoorCode, sealKnock, signAnswer, signPurge, } from '../doors/doors.js';
+import { createMailboxClient } from '../network/mailbox.js';
 import { team } from '../space/presets.js';
 import { CARRIER_COLLECTION, deriveAccountRegistry, deriveContactsSpace, MEMBERSHIP_COLLECTION, PROFILE_COLLECTION, PROFILE_KEY, } from '../space/account-registry.js';
 import { CARRY_CLOSED_KEY, makePass, PASS_COLLECTION, passKey } from '../space/pass.js';
@@ -1137,11 +1139,14 @@ export async function createNode(config) {
             const name = contact.name.trim().slice(0, 200);
             if (!name)
                 throw new Error('A contact needs a name');
+            // An answer to their knock still to be written stays to be written.
+            const pending = (await contactRecords()).find((record) => record.body.did === contact.did)?.body?.door;
             return writeContact({
                 did: contact.did,
                 name,
                 ...(contact.space ? { space: contact.space } : {}),
                 ...(contact.note ? { note: contact.note.slice(0, 2000) } : {}),
+                ...(pending ? { door: pending } : {}),
             });
         },
         async remove(did) {
@@ -1227,6 +1232,306 @@ export async function createNode(config) {
             return [...seen].filter((account) => account !== config.signer.did && account !== did).sort();
         },
     });
+    // ─── Doors ─────────────────────────────────────────────────────────
+    //
+    // A door is a `std.door` in the contacts space; its keys are derived from
+    // the contact key and its id, so every device with the contact key opens the
+    // same doors. Knocks wait in the mailboxes of the relays a door names.
+    //
+    // A knock you left is a `std.knock` until the person behind the door
+    // answers in the space for two — a `std.knock-answer` signed with the
+    // door's signing key — when it becomes a contact and the invite is closed.
+    // Accepting a knock writes that answer as soon as this account's membership
+    // there has landed; until then the contact carries the door's id.
+    // See `packages/core/src/doors/doors.ts`.
+    const mailbox = config.mailbox ?? createMailboxClient();
+    /** Knocks seen at this node's doors, by id: opened (null when they didn't check out), and until when to keep them */
+    const knockCache = new Map();
+    const DAY_MS = 24 * 3600 * 1000;
+    function requireContactKey(what) {
+        // Agents never open doors or knock, even one a home gave the contact key.
+        if (agentSession)
+            throw new Error(`An agent can't use doors. ${what} is the person's to do.`);
+        if (!config.contactKey)
+            throw new Error(`${what} needs your contact key. Connect to your account home again, and allow contacts.`);
+        return config.contactKey;
+    }
+    /** A door's keys, from the contact key and its id */
+    async function doorKeys(id) {
+        const contactKey = requireContactKey('A door');
+        const key = await deriveDoorKeyBytes(contactKey, id);
+        const sign = await deriveDoorSignKeyBytes(contactKey, id);
+        const signPublic = contactPublicKey(sign);
+        return { key, sign, publicKey: contactPublicKey(key), signPublic, topic: await doorTopic(signPublic) };
+    }
+    async function doorRecords() {
+        if (!contactsSpaceId)
+            return [];
+        return (await (await contactsRuntime()).list({ collection: doorSchema.name })).filter((record) => record.verified && record.root === config.signer.did && typeof record.body?.id === 'string' && Array.isArray(record.body.relays));
+    }
+    async function doorView(record) {
+        const body = record.body;
+        const keys = await doorKeys(body.id);
+        return Object.freeze({
+            id: body.id,
+            ...(body.label ? { label: body.label } : {}),
+            ...(body.name ? { name: body.name } : {}),
+            key: keys.publicKey,
+            sign: keys.signPublic,
+            relays: Object.freeze([...body.relays]),
+            code: encodeDoorCode({ key: keys.publicKey, sign: keys.signPublic, relays: body.relays, ...(body.name ? { name: body.name } : {}) }),
+            createdAt: record.createdAt,
+        });
+    }
+    /** Clears knocks from every relay a door names, as its owner; how many relays did */
+    async function purgeDoor(door, ids) {
+        const keys = await doorKeys(door.id);
+        const done = await Promise.allSettled(door.relays.map((relay) => mailbox.purge(relay, keys.topic, keys.signPublic, ids, (nonce) => signPurge(keys.sign, keys.topic, nonce, ids))));
+        return done.filter((result) => result.status === 'fulfilled').length;
+    }
+    async function sentRecords() {
+        if (!contactsSpaceId)
+            return [];
+        return (await (await contactsRuntime()).list({ collection: knockSchema.name })).filter((record) => record.verified &&
+            record.root === config.signer.did &&
+            typeof record.body?.space === 'string' &&
+            typeof record.body.sign === 'string' &&
+            typeof record.body.invite === 'string');
+    }
+    /**
+     * Knocks of yours: answered ones become contacts, and the invite is closed;
+     * ones nobody answered within the knock's life are let go, space and all.
+     */
+    async function settleSent() {
+        for (const record of await sentRecords()) {
+            const { space, name, sign, invite } = record.body;
+            if (!(await registry.get(space))) {
+                await (await contactsRuntime()).remove(record.key);
+                continue;
+            }
+            const open = await runtime(space);
+            const { members } = await open.access();
+            let answered = null;
+            for (const answer of await open.list({ collection: knockAnswerSchema.name })) {
+                const did = answer.root;
+                if (!answer.verified || !did || did === config.signer.did || answer.createdBy !== did || typeof answer.body?.sig !== 'string')
+                    continue;
+                if (!members.some((member) => member.did === did))
+                    continue;
+                if (await checkAnswer(sign, space, did, answer.body.sig)) {
+                    answered = did;
+                    break;
+                }
+            }
+            if (answered) {
+                // Whoever else the invite reached, nobody more joins with it.
+                await spaces.closeInvite(space, invite).catch(() => { });
+                const given = (await open.profiles()).find((profile) => profile.did === answered)?.name;
+                await writeContact({ did: answered, name: given ?? name, space });
+                await (await contactsRuntime()).remove(record.key);
+            }
+            else if (Date.now() - Date.parse(record.createdAt) > KNOCK_TTL_SECONDS * 1000 + DAY_MS) {
+                await spaces.leave(space).catch(() => { });
+                await (await contactsRuntime()).remove(record.key);
+            }
+        }
+    }
+    /** Writes the answer to knocks this account accepted, once it can write in the space for two */
+    async function answerAccepted() {
+        for (const record of await contactRecords()) {
+            const { did, space, door } = record.body;
+            if (typeof door !== 'string' || typeof space !== 'string')
+                continue;
+            if (!(await registry.get(space)))
+                continue;
+            const open = await runtime(space);
+            if ((await open.access()).role === null)
+                continue;
+            const { sign } = await doorKeys(door);
+            try {
+                await open.put(knockAnswerSchema.name, { sig: await signAnswer(sign, space, config.signer.did) });
+            }
+            catch {
+                continue; // The space's definition of answers hasn't arrived yet.
+            }
+            const { door: _answered, ...rest } = record.body;
+            await writeContact({ ...rest, did });
+        }
+    }
+    /** What the mailboxes of this node's doors hold now, opened and cached */
+    async function readDoors() {
+        const now = Date.now();
+        for (const [id, cached] of knockCache)
+            if (cached.until <= now)
+                knockCache.delete(id);
+        const found = [];
+        for (const record of await doorRecords()) {
+            const { id: doorId, relays } = record.body;
+            const keys = await doorKeys(doorId);
+            // Every relay, in full: a door holds 64 knocks at most, and a knock
+            // cleared from another device should go from here too. What was opened
+            // once is not opened again.
+            const held = new Map();
+            for (const result of await Promise.allSettled(relays.map((relay) => mailbox.fetch(relay, keys.topic)))) {
+                if (result.status !== 'fulfilled')
+                    continue;
+                for (const item of result.value) {
+                    // A relay's id is only its word: file the knock under the hash of what it is.
+                    const id = await knockId(item.blob);
+                    const seen = held.get(id);
+                    if (!seen || item.at < seen.at)
+                        held.set(id, { blob: item.blob, at: item.at });
+                }
+            }
+            for (const [id, item] of held) {
+                let cached = knockCache.get(id);
+                if (!cached) {
+                    cached = { opened: await openKnock(keys.key, item.blob, item.at, provider), door: doorId, until: item.at + KNOCK_TTL_SECONDS * 1000 };
+                    knockCache.set(id, cached);
+                }
+                if (cached.opened)
+                    found.push({ id, door: doorId, opened: cached.opened });
+            }
+        }
+        return found;
+    }
+    const doors = Object.freeze({
+        async list() {
+            if (!config.contactKey || agentSession)
+                return [];
+            return Promise.all((await doorRecords()).map(doorView));
+        },
+        async open(options = {}) {
+            requireContactKey('Opening a door');
+            if (!contactsSpaceId)
+                await contactsRuntime();
+            const relays = [...(options.relays ?? (config.network?.relays ?? []).filter((url) => checkRelays([url]) === null))].slice(0, MAX_DOOR_RELAYS);
+            if (relays.length === 0)
+                throw new Error('A door needs a relay to hold its knocks, and this node has none.');
+            const name = clip((options.name ?? (await ownName()) ?? '').trim(), 64);
+            const label = options.label ? clip(options.label.trim(), 64) : '';
+            const id = base64UrlEncode(globalThis.crypto.getRandomValues(new Uint8Array(16)));
+            // Checks the relays and name the way a knocker will.
+            const keys = await doorKeys(id);
+            encodeDoorCode({ key: keys.publicKey, sign: keys.signPublic, relays, ...(name ? { name } : {}) });
+            const open = await contactsRuntime();
+            await ensureDefined(open, doorSchema);
+            return doorView(await open.put(doorSchema.name, { id, relays, ...(name ? { name } : {}), ...(label ? { label } : {}) }));
+        },
+        async close(id) {
+            const found = (await doorRecords()).find((record) => record.body.id === id);
+            if (found)
+                await (await contactsRuntime()).remove(found.key);
+            for (const [knock, cached] of knockCache)
+                if (cached.door === id)
+                    knockCache.delete(knock);
+        },
+        async clear(id) {
+            requireContactKey('Clearing a door');
+            const found = (await doorRecords()).find((record) => record.body.id === id);
+            if (!found)
+                throw new Error('There is no such door');
+            if ((await purgeDoor(found.body, null)) === 0)
+                throw new Error("None of the door's relays could be reached to clear it.");
+            for (const [knock, cached] of knockCache)
+                if (cached.door === id)
+                    knockCache.delete(knock);
+        },
+        async knock(code, options = {}) {
+            requireContactKey('Knocking on a door');
+            requireEverywhere('Knocking on a door');
+            const door = parseDoorCode(code);
+            for (const mine of await doors.list())
+                if (mine.key === door.key)
+                    throw new Error('That is one of your own doors');
+            if (!contactsSpaceId)
+                await contactsRuntime();
+            const mine = (await ownName()) ?? 'Someone';
+            const theirs = door.name ?? 'Contact';
+            const pair = await spaces.create({ name: `${clip(mine, 64)} & ${theirs}`, visibility: 'private', ...team });
+            let invite;
+            try {
+                // Defined now, by the one who may: the answer is written by someone who joins as an editor.
+                await ensureDefined(await runtime(pair.id), knockAnswerSchema);
+                invite = await spaces.invite(pair.id, { role: 'editor' });
+                const blob = await sealKnock(door.key, { from: config.signer.did, name: mine, invite, ...(options.note ? { note: options.note } : {}) }, { did: session.did, key: session.key, proof: session.proof() }, provider);
+                const topic = await doorTopic(door.sign);
+                const left = await Promise.allSettled(door.relays.map((relay) => mailbox.drop(relay, topic, blob, KNOCK_TTL_SECONDS)));
+                if (!left.some((result) => result.status === 'fulfilled')) {
+                    const reasons = left.map((result) => (result.status === 'rejected' ? String(result.reason?.message ?? result.reason) : '')).filter(Boolean);
+                    throw new Error(`None of their door's relays took the knock. ${reasons.join('; ')}`);
+                }
+            }
+            catch (error) {
+                await spaces.leave(pair.id).catch(() => { });
+                throw error;
+            }
+            const open = await contactsRuntime();
+            await ensureDefined(open, knockSchema);
+            await open.put(knockSchema.name, { space: pair.id, name: theirs, door: door.key, sign: door.sign, invite });
+            return { space: pair.id };
+        },
+        async knocks() {
+            requireContactKey('Reading knocks');
+            await settleSent().catch(() => { });
+            await answerAccepted().catch(() => { });
+            const blocked = new Set((await contactRecords()).filter((record) => record.body.blocked === true).map((record) => record.body.did));
+            const found = [];
+            for (const { id, door, opened } of await readDoors()) {
+                if (opened.from === config.signer.did || blocked.has(opened.from))
+                    continue;
+                // Already accepted, here or on another device.
+                if (await registry.get(opened.pairSpace))
+                    continue;
+                found.push(Object.freeze({
+                    id,
+                    door,
+                    from: opened.from,
+                    name: opened.name,
+                    ...(opened.note ? { note: opened.note } : {}),
+                    pairSpace: opened.pairSpace,
+                    at: new Date(opened.at).toISOString(),
+                }));
+            }
+            return found.sort((a, b) => b.at.localeCompare(a.at));
+        },
+        async sent() {
+            await settleSent().catch(() => { });
+            return (await sentRecords()).map((record) => Object.freeze({ space: record.body.space, name: record.body.name, at: record.createdAt }));
+        },
+        async accept(id) {
+            requireContactKey('Opening the door to someone');
+            requireEverywhere('Opening the door to someone');
+            if (!knockCache.get(id)?.opened)
+                await readDoors();
+            const cached = knockCache.get(id);
+            const knocked = cached?.opened;
+            if (!cached || !knocked)
+                throw new Error('That knock is gone: it expired, or the door was closed or cleared.');
+            await spaces.join(knocked.invite);
+            const known = await contacts.get(knocked.from);
+            const contact = await writeContact({ did: knocked.from, name: known?.name ?? knocked.name, space: knocked.pairSpace, door: cached.door });
+            await answerAccepted().catch(() => { });
+            // Done with: nobody needs it in the mailboxes any more.
+            const door = (await doorRecords()).find((record) => record.body.id === cached.door);
+            if (door)
+                await purgeDoor(door.body, [id]).catch(() => 0);
+            knockCache.delete(id);
+            return contact;
+        },
+        async dismiss(id) {
+            requireContactKey('Dismissing a knock');
+            if (!knockCache.has(id))
+                await readDoors();
+            const cached = knockCache.get(id);
+            if (!cached)
+                return;
+            const door = (await doorRecords()).find((record) => record.body.id === cached.door);
+            if (door)
+                await purgeDoor(door.body, [id]);
+            knockCache.delete(id);
+        },
+    });
     const collections = Object.freeze({
         async list(spaceId) {
             return (await runtime(spaceId)).collections();
@@ -1460,6 +1765,18 @@ export async function createNode(config) {
                 accept: person('accept contact requests'),
                 others: person('look inside a contact\'s space'),
             }),
+            // Doors are the person's: an agent has none and knocks on none.
+            doors: Object.freeze({
+                list: async () => [],
+                open: person('open a door'),
+                close: person('close a door'),
+                knock: person('knock on anyone\'s door'),
+                clear: person('clear a door'),
+                knocks: person('read knocks'),
+                sent: person('look at knocks'),
+                accept: person('open the door to anyone'),
+                dismiss: person('dismiss a knock'),
+            }),
             delegation: () => note,
             iceServers: node.iceServers,
             delegate: person('pass its access on'),
@@ -1483,6 +1800,7 @@ export async function createNode(config) {
         hosting,
         notifications,
         contacts,
+        doors,
         asAgent,
         delegation: () => current,
         iceServers: async () => (mesh ? mesh.iceServers() : (config.network?.iceServers ?? DEFAULT_ICE_SERVERS)),