@weaveprotocol/core 0.1.2 → 0.2.1

package/dist/node/node.js

@@ -15,21 +15,31 @@
  * for one signature an hour, never one per write.
  */
 import { runQuery } from '../query/engine.js';
-import { nameOf } from '../query/types.js';
+import { nameOf, plainQuery } from '../query/types.js';
 import { createP256Provider } from '../identity/crypto-p256.js';
 import { publicKeyToDid, P256_MULTICODEC } from '../identity/did.js';
 import { delegateCapabilities, parseUCAN, verifyUCAN } from '../identity/ucan.js';
 import { isAgentNote } from '../identity/agent-note.js';
 import { createSigner } from '../schema/signer.js';
 import { createSchemaEngine } from '../schema/schema-engine.js';
-import { createSpaceManager, parseSpaceInvite } from '../space/space-manager.js';
+import { createSpaceManager, encodeSpaceInvite, parseSpaceInvite, } from '../space/space-manager.js';
+import { checkRelays, MANAGE, MAX_KEEPERS, MAX_RELAYS, roleHolds } from '../space/roles.js';
 import { meshFor, noteCid, openSpaceRuntime } from './space-runtime.js';
 import { createServerAuth } from '../network/peer-auth.js';
 import { DEFAULT_ICE_SERVERS } from '../network/rtc-transport.js';
 import { deriveInviteKey } from '../space/space-access.js';
-import { base64UrlDecode } from '../utils/encoding.js';
-import { CARRIER_COLLECTION, deriveAccountRegistry, MEMBERSHIP_COLLECTION, PROFILE_COLLECTION, PROFILE_KEY, } from '../space/account-registry.js';
+import { base64UrlDecode, base64UrlEncode } from '../utils/encoding.js';
+import { onePerKey } from '../records/rules.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';
+import { carriedFor, checkNotify, NOTIFY_COLLECTION, SUBSCRIPTION_COLLECTION } from '../space/notify.js';
+import { createHostClient, describeHost, HOSTING_COLLECTION, HostError, newSubscriptionSeed, payLink, readStatus, subscriptionKey, } from '../session/hosting.js';
+import { base32Encode, sha256 } from '../utils/hash.js';
 /** Everything a session key may do, across every space the node holds */
 export const SESSION_CAPABILITY = { with: '*', can: 'expression/*' };
 const DEFAULT_TTL_SECONDS = 3600;
@@ -49,6 +59,22 @@ function summarize(record) {
         joining: record.invite !== null,
     });
 }
+/** Every collection a query reads: its own, and each `include … from` */
+function collectionsOf(query) {
+    const plain = plainQuery(query);
+    const found = new Set();
+    if (typeof plain.collection === 'string')
+        found.add(plain.collection);
+    const walk = (includes) => {
+        for (const include of Object.values(includes ?? {})) {
+            if (typeof include?.from === 'string')
+                found.add(include.from);
+            walk(include?.include);
+        }
+    };
+    walk(plain.include);
+    return [...found];
+}
 /** Accepts a bare invite or a whole share link carrying one (`…#invite=…`). */
 function bareInvite(invite) {
     return /[#&?]invite=([^&\s]+)/.exec(invite)?.[1] ?? invite.trim();
@@ -132,6 +158,28 @@ export async function createNode(config) {
     // derives for itself. Hidden from `list`; everything else treats it as a space.
     const account = config.accountKey ? await deriveAccountRegistry(config.accountKey, config.signer.did, provider) : null;
     const accountSpaceId = account?.space.id ?? null;
+    // The account's contacts, in a space derived the same way — or, for an app
+    // given it by its account home, named in the config. Hidden from `list` too.
+    const contactsRecord = config.accountKey ? await deriveContactsSpace(config.accountKey, config.signer.did, provider) : null;
+    const contactsSpaceId = contactsRecord?.space.id ?? config.contactsSpace ?? null;
+    // Kept in the node's own list like a joined space, so it can be shared with an app like one.
+    if (contactsRecord && !(await registry.get(contactsRecord.space.id))) {
+        await registry.join(await encodeSpaceInvite(contactsRecord, config.signer.did));
+    }
+    /** Whether a space is the account's own machinery, not one it uses */
+    const hidden = (spaceId) => carrySpaces.has(spaceId) || spaceId === contactsSpaceId;
+    /** The contact key, for a node allowed to open contact requests */
+    const contactKeys = config.contactKey ? await contactKeyPair(config.contactKey) : null;
+    /**
+     * An invite to a space, naming where its members meet: the relays the space
+     * names, or before it names any, this node's — so the joiner finds the
+     * inviter even when their app uses other relays.
+     */
+    async function inviteTo(spaceId, options = {}) {
+        const named = (await findRecord(spaceId))?.relays ?? [];
+        const own = (config.network?.relays ?? []).filter((url) => checkRelays([url]) === null).slice(0, MAX_RELAYS);
+        return registry.createInvite(spaceId, config.signer.did, { ...options, ...(named.length ? {} : own.length ? { relays: own } : {}) });
+    }
     async function findRecord(spaceId) {
         return spaceId === accountSpaceId ? account : registry.get(spaceId);
     }
@@ -184,11 +232,11 @@ export async function createNode(config) {
      * all; a space not open now hears on its next open.
      */
     async function publishProfile(spaceId, open) {
-        if (spaceId === accountSpaceId || agentSession)
+        if (spaceId === accountSpaceId || spaceId === contactsSpaceId || agentSession)
             return;
         const name = await ownName();
         if (name)
-            await open.publishProfile({ name });
+            await open.publishProfile({ name, ...(contactKeys ? { contactKey: contactKeys.publicKey } : {}) });
     }
     async function publishProfileToOpenSpaces() {
         for (const [spaceId, open] of runtimes) {
@@ -200,7 +248,7 @@ export async function createNode(config) {
             return Promise.reject(new Error('Node is closed'));
         let open = runtimes.get(spaceId);
         if (!open) {
-            open = requireRecord(spaceId).then((record) => openSpaceRuntime({
+            open = requireRecord(spaceId).then(async (record) => openSpaceRuntime({
                 record,
                 stores: config.stores,
                 provider,
@@ -210,7 +258,9 @@ export async function createNode(config) {
                 rootDid: config.signer.did,
                 ...(config.network ? { network: config.network } : {}),
                 ...(mesh ? { mesh } : {}),
-                peopleOnly: spaceId === accountSpaceId || carrySpaces.has(spaceId),
+                peopleOnly: spaceId === accountSpaceId || spaceId === contactsSpaceId || carrySpaces.has(spaceId),
+                // The account's own spaces are always held whole: every device needs all of them.
+                ...(config.cache && spaceId !== accountSpaceId && spaceId !== contactsSpaceId && !carrySpaces.has(spaceId) ? { cache: config.cache } : {}),
                 watchIntervalMs: config.watchIntervalMs ?? 2000,
                 emit: fromRuntime,
                 onRole: (role) => {
@@ -228,12 +278,27 @@ export async function createNode(config) {
                         return;
                     void registry.clearInvite(spaceId).then(() => emit({ type: 'spaces' }));
                 },
+                memberKey: spaceId === accountSpaceId ? null : config.accountKey ? await deriveMemberKeyBytes(config.accountKey, spaceId) : (record.memberKey ?? null),
+                onRelays: async (relays) => {
+                    if (spaceId !== accountSpaceId)
+                        await registry.setRelays(spaceId, relays);
+                },
+                onKeys: async (keys, current) => {
+                    if (spaceId === accountSpaceId)
+                        return;
+                    await registry.addKeys(spaceId, keys, current);
+                    // The account's other devices, and its carriers, follow the new key.
+                    await remember(spaceId, { refresh: true });
+                    void reconcile();
+                },
             }));
             // A failed open must not be cached, or the space stays broken until restart.
             open.catch(() => runtimes.delete(spaceId));
             void open.then((rt) => publishProfile(spaceId, rt)).catch(() => { });
             // A revoke that arrived on an earlier visit.
             void open.then((rt) => checkRevoked(spaceId, rt)).catch(() => { });
+            // Carriers added since this space was last open.
+            void open.then((rt) => nameKeepers(spaceId, rt)).catch(() => { });
             runtimes.set(spaceId, open);
         }
         return open;
@@ -286,6 +351,15 @@ export async function createNode(config) {
     // deleted: it left — and rejoining is simply the next version. Every device
     // converges on the same answer, because it is the same record.
     const membershipKey = (spaceId) => `space:${spaceId}`;
+    /** The space key an invite carries, if it can be read */
+    const inviteKeyOf = (invite) => {
+        try {
+            return typeof invite === 'string' ? parseSpaceInvite(invite).key : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
     async function memberships() {
         if (!accountSpaceId)
             return [];
@@ -295,15 +369,21 @@ export async function createNode(config) {
             record.root === config.signer.did &&
             (record.deleted || (typeof record.body?.space === 'string' && record.key === membershipKey(record.body.space))));
     }
-    async function remember(spaceId) {
+    /**
+     * Records in the registry that the account belongs to a space. With
+     * `refresh`, rewrites the record if the space's key changed since, so a
+     * new device joins with the key in use now.
+     */
+    async function remember(spaceId, options = {}) {
         if (!accountSpaceId || agentSession)
             return;
         const open = await runtime(accountSpaceId);
-        if (await open.get(membershipKey(spaceId)))
-            return;
+        const known = await open.get(membershipKey(spaceId));
         // A view-only invite: what lets the account write is its role in the
         // space, which every device reads there. Invite secrets are never kept.
-        const invite = await registry.createInvite(spaceId, config.signer.did);
+        const invite = await inviteTo(spaceId);
+        if (known && (!options.refresh || known.deleted || inviteKeyOf(known.body?.invite) === inviteKeyOf(invite)))
+            return;
         await open.upsertSystem(MEMBERSHIP_COLLECTION, membershipKey(spaceId), { space: spaceId, invite });
     }
     async function forget(spaceId) {
@@ -350,13 +430,15 @@ export async function createNode(config) {
         if (!account || agentSession)
             return;
         const wanted = new Map();
-        // The registry too, so a restore can come through the carrier.
+        // The registry and the contacts too, so a restore can come through the carrier.
         wanted.set(await passKey(account.space.id), await makePass(account));
+        if (contactsRecord)
+            wanted.set(await passKey(contactsRecord.space.id), await makePass(contactsRecord));
         for (const membership of await memberships()) {
             if (membership.deleted || !membership.body)
                 continue;
             const spaceId = membership.body.space;
-            if (carrySpaces.has(spaceId))
+            if (hidden(spaceId))
                 continue;
             const record = await registry.get(spaceId);
             if (!record)
@@ -382,6 +464,80 @@ export async function createNode(config) {
         for (const [key, record] of held)
             if (!record.deleted)
                 await carry.removeSystem(key);
+        // Subscriptions, with each value replaced by the space's tag: the carrier matches, never learns.
+        const spaces = [];
+        for (const membership of await memberships()) {
+            if (membership.deleted || !membership.body || hidden(membership.body.space))
+                continue;
+            const record = await registry.get(membership.body.space);
+            if (record)
+                spaces.push({ id: record.space.id, key: record.key, visibility: record.space.visibility });
+        }
+        const subscriptions = new Map();
+        for (const view of await notifyRecords())
+            subscriptions.set(view.id, await carriedFor(view, spaces));
+        const carried = new Map((await carry.list({ collection: SUBSCRIPTION_COLLECTION, includeDeleted: true }))
+            .filter((record) => record.verified && record.root === config.signer.did)
+            .map((record) => [record.key, record]));
+        for (const [key, body] of subscriptions) {
+            const current = carried.get(key);
+            if (!current || current.deleted || JSON.stringify(current.body) !== JSON.stringify(body))
+                await carry.upsertSystem(SUBSCRIPTION_COLLECTION, key, body);
+            carried.delete(key);
+        }
+        for (const [key, record] of carried)
+            if (!record.deleted)
+                await carry.removeSystem(key);
+    }
+    /** The account's subscriptions, as it made them */
+    async function notifyRecords() {
+        if (!accountSpaceId)
+            return [];
+        const found = [];
+        for (const record of await (await runtime(accountSpaceId)).list({ collection: NOTIFY_COLLECTION })) {
+            if (!record.verified || record.root !== config.signer.did || !record.key.startsWith('notify:') || checkNotify(record.body) !== null)
+                continue;
+            found.push({ ...record.body, id: record.key });
+        }
+        return found.sort((a, b) => a.since.localeCompare(b.since));
+    }
+    /** Every carrier gets the subscriptions as they are now */
+    async function passSubscriptionsOn() {
+        for (const { record } of await carrierRecords()) {
+            if (!record.deleted && record.body)
+                await syncPasses(record.body).catch(() => { });
+        }
+    }
+    /**
+     * Names the account's carriers — its extensions, its hosts — as keepers of
+     * a space it manages, and stops naming ones it removed, so apps there hold
+     * only what they use. Other keepers the space names stay. Done as each space
+     * opens and whenever the carriers change; a space this account doesn't
+     * manage is left to whoever does.
+     */
+    async function nameKeepers(spaceId, rt) {
+        if (!account || agentSession || spaceId === accountSpaceId || hidden(spaceId))
+            return;
+        const access = await rt.access();
+        if (!roleHolds(access.role, MANAGE))
+            return;
+        const carriers = await carrierRecords();
+        const active = carriers.filter(({ record }) => !record.deleted && record.body).map(({ record }) => record.body);
+        const gone = new Set();
+        for (const { record } of carriers) {
+            if (!record.deleted)
+                continue;
+            for (const version of await (await runtime(accountSpaceId)).history(record.key))
+                if (version.body?.did)
+                    gone.add(version.body.did);
+        }
+        for (const carrier of active)
+            gone.delete(carrier.did);
+        const kept = access.keepers.filter((keeper) => !gone.has(keeper.did));
+        const added = active.filter((carrier) => !kept.some((keeper) => keeper.did === carrier.did)).map((c) => ({ did: c.did, name: c.name.slice(0, 80) }));
+        if (added.length === 0 && kept.length === access.keepers.length)
+            return;
+        await rt.setKeepers([...kept, ...added].slice(0, MAX_KEEPERS), access.copies);
     }
     /**
      * Makes this node's spaces match the account's: join what the account
@@ -419,6 +575,9 @@ export async function createNode(config) {
         }
         for (const spaceId of carrySpaces)
             known.add(spaceId);
+        // Derived on every device: nothing to record.
+        if (contactsSpaceId)
+            known.add(contactsSpaceId);
         for (const membership of await memberships()) {
             const spaceId = membership.key.slice('space:'.length);
             known.add(spaceId);
@@ -450,6 +609,11 @@ export async function createNode(config) {
             // Only a device that may write in the carry space can do this; others leave it to one that can.
             await syncPasses(record.body).catch(() => { });
         }
+        // Carriers came or went: the open spaces this account manages say so.
+        for (const [spaceId, open] of runtimes)
+            void open.then((rt) => nameKeepers(spaceId, rt)).catch(() => { });
+        // Not awaited: a host that is slow to answer must not hold up the rest.
+        void keepHosted().catch(() => { });
         if (changed)
             emit({ type: 'spaces' });
     }
@@ -463,7 +627,7 @@ export async function createNode(config) {
     }
     const spaces = Object.freeze({
         async list() {
-            return (await registry.list()).filter((record) => !carrySpaces.has(record.space.id)).map(summarize);
+            return (await registry.list()).filter((record) => !hidden(record.space.id)).map(summarize);
         },
         async get(spaceId) {
             const record = await findRecord(spaceId);
@@ -483,7 +647,7 @@ export async function createNode(config) {
         },
         async invite(spaceId, options = {}) {
             if (options.write === false)
-                return registry.createInvite(spaceId, config.signer.did);
+                return inviteTo(spaceId);
             const open = await runtime(spaceId);
             const { roles, role: mine } = await open.access();
             // By default the lowest role below your own; with none below you, a view-only invite.
@@ -491,10 +655,10 @@ export async function createNode(config) {
             if (!role) {
                 if (options.role !== undefined || !mine)
                     throw new Error(mine ? `There is no role "${options.role}"` : 'You hold no role here, so you can only share it to view');
-                return registry.createInvite(spaceId, config.signer.did);
+                return inviteTo(spaceId);
             }
             const { secret } = await open.openInvite(role);
-            return registry.createInvite(spaceId, config.signer.did, { secret, role });
+            return inviteTo(spaceId, { secret, role });
         },
         preview(invite) {
             const parsed = parseSpaceInvite(bareInvite(invite));
@@ -507,8 +671,10 @@ export async function createNode(config) {
                 role: typeof parsed.invite === 'string' ? (parsed.role ?? null) : null,
             };
         },
-        async join(invite) {
+        async join(invite, options = {}) {
             const record = await registry.join(bareInvite(invite));
+            if (options.memberKey)
+                await registry.setMemberKey(record.space.id, options.memberKey);
             // A runtime opened before the key arrived would still be unable to read.
             await closeRuntime(record.space.id);
             await remember(record.space.id);
@@ -520,6 +686,8 @@ export async function createNode(config) {
         async leave(spaceId) {
             if (spaceId === accountSpaceId)
                 throw new Error('The account registry cannot be left');
+            if (spaceId === contactsSpaceId)
+                throw new Error('The contacts space cannot be left');
             await forget(spaceId);
             await closeRuntime(spaceId);
             await registry.remove(spaceId);
@@ -587,7 +755,7 @@ export async function createNode(config) {
             if (!keyOrLink.startsWith('did:key:')) {
                 const secret = parseSpaceInvite(bareInvite(keyOrLink)).invite;
                 if (!secret)
-                    throw new Error('That invite is view-only — there is nothing to close. To stop someone reading, the space needs a new key.');
+                    throw new Error('That invite is view-only — there is nothing to close. To stop it working, give the space a new key (changeKey).');
                 key = (await deriveInviteKey(base64UrlDecode(secret), provider)).did;
             }
             await (await runtime(spaceId)).closeInvite(key);
@@ -595,15 +763,24 @@ export async function createNode(config) {
         async revoke(spaceId, token) {
             await (await runtime(spaceId)).revoke(token);
         },
+        async changeKey(spaceId) {
+            await (await runtime(spaceId)).rotateKey();
+        },
+        async setRelays(spaceId, relays) {
+            await (await runtime(spaceId)).setRelays(relays);
+        },
+        async setKeepers(spaceId, keepers, copies) {
+            await (await runtime(spaceId)).setKeepers(keepers, copies ?? null);
+        },
         async authenticator(spaceId) {
             const record = await findRecord(spaceId);
             if (!record)
                 return null;
             // Every peer proves its own DID; in a private space, readers are also
-            // checked against the space's public read key. The welcome is signed by
-            // the key this node introduces itself with.
-            const readKey = record.space.visibility === 'private' ? (record.space.readKey ?? '') : null;
-            return createServerAuth(spaceId, readKey, sessionKeys.privateKey, provider);
+            // checked against the read key the space's history names now. The
+            // welcome is signed by the key this node introduces itself with.
+            const read = record.space.visibility === 'private' ? (await runtime(spaceId)).readAccess() : null;
+            return createServerAuth(spaceId, read, sessionKeys.privateKey, provider);
         },
     });
     // With an account key, start following the registry at once: it is how this
@@ -612,6 +789,48 @@ export async function createNode(config) {
         await runtime(accountSpaceId);
         await reconcile();
     }
+    const notifications = Object.freeze({
+        list: notifyRecords,
+        async add(when) {
+            if (!accountSpaceId)
+                throw new Error('Subscriptions need the account key');
+            const body = { ...when, label: when.label.trim(), since: when.since ?? new Date().toISOString() };
+            const problem = checkNotify(body);
+            if (problem)
+                throw new Error(problem);
+            const id = `notify:${base32Encode(globalThis.crypto.getRandomValues(new Uint8Array(10)))}`;
+            await (await runtime(accountSpaceId)).upsertSystem(NOTIFY_COLLECTION, id, body);
+            await passSubscriptionsOn();
+            return { ...body, id };
+        },
+        async update(id, changes) {
+            if (!accountSpaceId)
+                throw new Error('Subscriptions need the account key');
+            const current = (await notifyRecords()).find((view) => view.id === id);
+            if (!current)
+                throw new Error('There is no such subscription');
+            const { id: _id, ...was } = current;
+            const body = {
+                ...was,
+                ...(changes.label !== undefined ? { label: changes.label.trim() } : {}),
+                ...(changes.paused !== undefined ? { paused: changes.paused } : {}),
+            };
+            const problem = checkNotify(body);
+            if (problem)
+                throw new Error(problem);
+            await (await runtime(accountSpaceId)).upsertSystem(NOTIFY_COLLECTION, id, body);
+            await passSubscriptionsOn();
+            return { ...body, id };
+        },
+        async remove(id) {
+            if (!accountSpaceId)
+                throw new Error('Subscriptions need the account key');
+            if (!(await notifyRecords()).some((view) => view.id === id))
+                return;
+            await (await runtime(accountSpaceId)).removeSystem(id);
+            await passSubscriptionsOn();
+        },
+    });
     const carriers = Object.freeze({
         async list() {
             return (await carrierRecords())
@@ -647,6 +866,672 @@ export async function createNode(config) {
             await (await runtime(accountSpaceId)).removeSystem(found.key);
         },
     });
+    // ─── Hosting ───────────────────────────────────────────────────────
+    //
+    // A host is a carrier the account pays for. The subscription key lives in
+    // the registry (`sys.hosting`), so every device signs as the same
+    // subscription, and any of them hands the host the carry space once it is
+    // paid — the one that paid, or the next one to notice.
+    const hostingKey = async (url) => `hosting:${Array.from((await sha256(new TextEncoder().encode(url))).subarray(0, 20), (b) => b.toString(16).padStart(2, '0')).join('')}`;
+    /** The hosting records the account wrote, live */
+    async function hostingRecords() {
+        if (!accountSpaceId)
+            return [];
+        const records = await (await runtime(accountSpaceId)).list({ collection: HOSTING_COLLECTION });
+        return records
+            .filter((record) => record.verified && record.root === config.signer.did && typeof record.body?.url === 'string' && typeof record.body.seed === 'string')
+            .map((record) => record.body);
+    }
+    async function hostClient(hosting) {
+        const key = await subscriptionKey(base64UrlDecode(hosting.seed), provider);
+        return { client: createHostClient(hosting.url, hosting.host, key, provider), subscription: key.did };
+    }
+    /** What the host at a known address says about itself — refused when it's another host now */
+    async function describeKnown(hosting) {
+        const description = await describeHost(hosting.url);
+        if (description.did !== hosting.host)
+            throw new Error("The host at this address has another key now, so it's another host");
+        return description;
+    }
+    /** The carry space shared with a host: the one the account made for it, or a new one */
+    async function carryFor(hosting) {
+        const known = (await carrierRecords()).find(({ record }) => !record.deleted && record.body?.did === hosting.host)?.record.body;
+        return known ? known.invite : (await carriers.add({ did: hosting.host, name: new URL(hosting.url).host })).invite;
+    }
+    /** Last time each host was handed the spaces, or refused them — so asking again waits a while */
+    const handedAt = new Map();
+    const HAND_AGAIN_MS = 60_000;
+    /** Handovers under way, so a second look waits for the first instead of reporting the spaces not carried */
+    const handing = new Map();
+    /**
+     * Keeps what the host signed in the registry, so every device shows it and
+     * the person holds the host's word — written only when what it says changed.
+     */
+    async function keepReceipt(hosting, kept, status, receipt, name) {
+        if (agentSession || !accountSpaceId)
+            return;
+        const same = kept && kept.state === status.state && kept.paidUntil === status.paidUntil && kept.renews === status.renews && hosting.name === name;
+        if (same)
+            return;
+        const record = { ...hosting, name, receipt };
+        await (await runtime(accountSpaceId)).upsertSystem(HOSTING_COLLECTION, await hostingKey(hosting.url), record);
+    }
+    /** Asks a host how it stands, and hands it the spaces if it is paid for but not carrying them */
+    async function viewHosting(hosting, force = false) {
+        const { client, subscription } = await hostClient(hosting);
+        const kept = hosting.receipt ? await readStatus(hosting.receipt, hosting.host, provider) : null;
+        const base = { url: hosting.url, host: hosting.host, subscription, since: hosting.since };
+        try {
+            const description = await describeKnown(hosting);
+            let { status, receipt } = await client.status();
+            const due = force || Date.now() - (handedAt.get(hosting.url) ?? 0) > HAND_AGAIN_MS;
+            const paid = status.state === 'active' || status.state === 'grace' || (description.free && status.state !== 'lapsed');
+            const inFlight = handing.get(hosting.url);
+            if (!status.carrying && inFlight) {
+                // Another look is handing the spaces over right now: wait for it,
+                // rather than answer "not carrying" while they're on their way.
+                const handed = await inFlight.catch(() => null);
+                if (handed)
+                    ({ status, receipt } = handed);
+            }
+            else if (!status.carrying && paid && due && !agentSession) {
+                handedAt.set(hosting.url, Date.now());
+                const attaching = carryFor(hosting).then((invite) => client.attach(config.signer.did, invite));
+                handing.set(hosting.url, attaching);
+                try {
+                    ({ status, receipt } = await attaching);
+                }
+                catch (error) {
+                    // Not paid after all (it lapsed in between): the status says so.
+                    if (!(error instanceof HostError && error.status === 402))
+                        throw error;
+                }
+                finally {
+                    handing.delete(hosting.url);
+                }
+            }
+            await keepReceipt(hosting, kept, status, receipt, description.name);
+            return {
+                ...base,
+                name: description.name,
+                status,
+                live: true,
+                pays: description.pay !== undefined,
+                ...(description.price ? { price: description.price } : {}),
+            };
+        }
+        catch (error) {
+            return { ...base, name: hosting.name ?? new URL(hosting.url).host, status: kept, live: false, pays: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    /** Every device keeps its hosts carrying: after the registry changes, ask each once more */
+    async function keepHosted() {
+        if (agentSession)
+            return;
+        for (const hosting of await hostingRecords())
+            await viewHosting(hosting).catch(() => { });
+    }
+    async function requireHosting(url) {
+        const found = (await hostingRecords()).find((hosting) => hosting.url === url);
+        if (!found)
+            throw new Error(`This account doesn't use the host at ${url}`);
+        return found;
+    }
+    /** An address a device may reach: https://, or http:// on this machine */
+    function checkAddress(address, what) {
+        const url = new URL(address);
+        const local = ['localhost', '127.0.0.1'].includes(url.hostname);
+        if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local))
+            throw new Error(`${what} is reached over https://`);
+        return url;
+    }
+    const hosting = Object.freeze({
+        async list() {
+            return Promise.all((await hostingRecords()).map((known) => viewHosting(known)));
+        },
+        async use(address) {
+            if (!accountSpaceId)
+                throw new Error('Using a host needs the account key');
+            const base = checkAddress(address, 'A host').origin;
+            const known = (await hostingRecords()).find((existing) => existing.url === base);
+            if (known)
+                return viewHosting(known, true);
+            const description = await describeHost(base);
+            const record = { url: base, host: description.did, name: description.name, seed: base64UrlEncode(newSubscriptionSeed()), since: new Date().toISOString() };
+            await (await runtime(accountSpaceId)).upsertSystem(HOSTING_COLLECTION, await hostingKey(base), record);
+            return viewHosting(record, true);
+        },
+        async payPage(url) {
+            const known = await requireHosting(url);
+            const description = await describeKnown(known);
+            if (description.pay === undefined)
+                throw new Error('This host takes no payments');
+            const page = checkAddress(new URL(description.pay, `${known.url}/`).toString(), 'A pay page');
+            return payLink(page.toString(), known.host, await subscriptionKey(base64UrlDecode(known.seed), provider), provider);
+        },
+        async stop(url) {
+            if (!accountSpaceId)
+                throw new Error('Stopping a host needs the account key');
+            const known = await requireHosting(url);
+            const { client } = await hostClient(known);
+            await client.detach().catch(() => { });
+            const carrier = (await carrierRecords()).find(({ record }) => !record.deleted && record.body?.did === known.host);
+            if (carrier)
+                await carriers.remove(carrier.space);
+            await (await runtime(accountSpaceId)).removeSystem(await hostingKey(known.url));
+        },
+    });
+    // ─── Contacts ──────────────────────────────────────────────────────
+    //
+    // One `std.contact` per person in the contacts space, keyed by their DID, so
+    // there is one per person on every device. Asking someone is a
+    // `std.contact-request` in a space you share: the invite to a new space for
+    // two, sealed with their contact key, bound to the space it was posted in and
+    // to who asked whom — so it opens only for them, only there, and only as
+    // coming from the account that wrote it.
+    // The key `onePer: ['did']` derives, so the record for someone is the same one on every device.
+    const contactRecordKey = async (did) => (await onePerKey(contactSchema.name, contactSchema.rules.onePer, { root: config.signer.did, links: [], body: { did } }));
+    const requestContext = (spaceId, from, to) => `weave/contact-request|${spaceId}|${from}|${to}`;
+    async function contactsRuntime() {
+        if (!contactsSpaceId)
+            throw new Error('This app was not given your contacts. Connect to your account home again, and allow contacts.');
+        return runtime(contactsSpaceId);
+    }
+    /** Making and joining spaces for two needs a note good for every space — whole-account access. */
+    function requireEverywhere(what) {
+        if (!current.payload.att.some((capability) => capability.with === '*')) {
+            throw new Error(`${what} makes or joins a space, which needs access to your whole account. Connect to your account home again, and ask for it.`);
+        }
+    }
+    /** Defines a collection in a space that has none by that name yet */
+    async function ensureDefined(open, definition) {
+        if ((await open.collections()).some((collection) => collection.name === definition.name && collection.version !== null))
+            return;
+        try {
+            await open.define(definition);
+        }
+        catch {
+            throw new Error(`This space has no ${definition.title ?? definition.name} collection yet, and you can't add one here. Ask someone who manages it.`);
+        }
+    }
+    async function contactRecords() {
+        if (!contactsSpaceId)
+            return [];
+        const found = [];
+        for (const record of await (await contactsRuntime()).list({ collection: contactSchema.name })) {
+            // Only the account writes its own list; one record per person, under the key their DID gives.
+            if (!record.verified || record.root !== config.signer.did || typeof record.body?.did !== 'string' || typeof record.body.name !== 'string')
+                continue;
+            if (record.key !== (await contactRecordKey(record.body.did)))
+                continue;
+            found.push(record);
+        }
+        return found;
+    }
+    function contactView(record) {
+        const body = record.body;
+        return Object.freeze({
+            did: body.did,
+            name: body.name,
+            space: typeof body.space === 'string' ? body.space : null,
+            ...(typeof body.note === 'string' ? { note: body.note } : {}),
+            blocked: body.blocked === true,
+            updatedAt: record.updatedAt,
+        });
+    }
+    async function writeContact(body) {
+        const open = await contactsRuntime();
+        await ensureDefined(open, contactSchema);
+        // One per person: writing again is the next version of their record.
+        return contactView(await open.put(contactSchema.name, body));
+    }
+    /** Leaves a space for two, unless another contact still names it */
+    async function leavePairSpace(spaceId, did) {
+        if (!spaceId || !(await registry.get(spaceId)))
+            return;
+        if ((await contactRecords()).some((record) => record.body.did !== did && record.body.space === spaceId))
+            return;
+        await spaces.leave(spaceId);
+    }
+    /** A contact request, opened — or null when it isn't one for this account, from the account that wrote it */
+    async function openRequest(spaceId, record) {
+        if (!contactKeys || !record.verified || record.viaAgent || record.collection !== contactRequestSchema.name)
+            return null;
+        if (record.body?.to !== config.signer.did || typeof record.body.sealed !== 'string')
+            return null;
+        const from = record.root;
+        if (!from || record.createdBy !== from || from === config.signer.did)
+            return null;
+        const value = (await openSealed(contactKeys.privateKey, record.body.sealed, requestContext(spaceId, from, config.signer.did)));
+        if (typeof value?.invite !== 'string')
+            return null;
+        let invited;
+        try {
+            invited = parseSpaceInvite(value.invite);
+        }
+        catch {
+            return null;
+        }
+        // A private space the asker made, and the key to it: anything else isn't a space for two from them.
+        if (invited.space.creator !== from || invited.space.visibility !== 'private' || !invited.key)
+            return null;
+        return {
+            from,
+            invite: value.invite,
+            ...(typeof value.note === 'string' && value.note ? { note: value.note.slice(0, 2000) } : {}),
+            pairSpace: invited.space.id,
+        };
+    }
+    const contacts = Object.freeze({
+        async space() {
+            return contactsSpaceId;
+        },
+        async list() {
+            return (await contactRecords()).map(contactView).sort((a, b) => a.name.localeCompare(b.name) || a.did.localeCompare(b.did));
+        },
+        async get(did) {
+            const record = (await contactRecords()).find((found) => found.body.did === did);
+            return record ? contactView(record) : null;
+        },
+        async put(contact) {
+            if (!contact.did.startsWith('did:'))
+                throw new Error('A contact needs their account DID');
+            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) {
+            const found = await contacts.get(did);
+            if (!found)
+                return;
+            await leavePairSpace(found.space, did);
+            await (await contactsRuntime()).remove(await contactRecordKey(did));
+        },
+        async block(did) {
+            const found = await contacts.get(did);
+            await leavePairSpace(found?.space ?? null, did);
+            await writeContact({ did, name: found?.name ?? did, blocked: true, ...(found?.note ? { note: found.note } : {}) });
+        },
+        async ask(spaceId, did, options = {}) {
+            requireEverywhere('Adding a contact');
+            if (did === config.signer.did)
+                throw new Error('That is you');
+            if (!contactsSpaceId)
+                await contactsRuntime();
+            const shared = await runtime(spaceId);
+            const profiles = await shared.profiles();
+            const theirs = profiles.find((profile) => profile.did === did);
+            if (!theirs?.contactKey) {
+                throw new Error("They can't be asked here yet: their profile in this space has no contact key. It appears once they open the space in an up-to-date app.");
+            }
+            await ensureDefined(shared, contactRequestSchema);
+            const mine = (await ownName()) ?? profiles.find((profile) => profile.did === config.signer.did)?.name ?? 'Me';
+            const pair = await spaces.create({ name: `${mine} & ${theirs.name}`, visibility: 'private', ...team });
+            const invite = await spaces.invite(pair.id, { role: 'editor' });
+            await writeContact({ did, name: theirs.name, space: pair.id });
+            const note = options.note?.trim().slice(0, 2000);
+            const sealed = await sealFor(theirs.contactKey, { invite, ...(note ? { note } : {}) }, requestContext(spaceId, config.signer.did, did));
+            const request = await shared.put(contactRequestSchema.name, { to: did, sealed });
+            return { space: pair.id, request: request.key };
+        },
+        async requests(spaceId) {
+            if (!contactKeys)
+                throw new Error("This app can't read contact requests. Connect to your account home again, and allow contacts.");
+            const shared = await runtime(spaceId);
+            const blocked = new Set((await contactRecords()).filter((record) => record.body.blocked === true).map((record) => record.body.did));
+            const names = new Map((await shared.profiles()).map((profile) => [profile.did, profile.name]));
+            const found = [];
+            for (const record of await shared.list({ collection: contactRequestSchema.name })) {
+                const opened = await openRequest(spaceId, record);
+                if (!opened || blocked.has(opened.from))
+                    continue;
+                // Already accepted, here or on another device.
+                if (await registry.get(opened.pairSpace))
+                    continue;
+                found.push({
+                    space: spaceId,
+                    key: record.key,
+                    from: opened.from,
+                    name: names.get(opened.from) ?? null,
+                    ...(opened.note ? { note: opened.note } : {}),
+                    pairSpace: opened.pairSpace,
+                    createdAt: record.createdAt,
+                });
+            }
+            return found;
+        },
+        async accept(spaceId, requestKey) {
+            requireEverywhere('Accepting a contact request');
+            if (!contactKeys)
+                throw new Error("This app can't read contact requests. Connect to your account home again, and allow contacts.");
+            const shared = await runtime(spaceId);
+            const record = await shared.get(requestKey);
+            const opened = record ? await openRequest(spaceId, record) : null;
+            if (!opened)
+                throw new Error('That contact request is gone, or is not for you.');
+            await spaces.join(opened.invite);
+            const name = (await shared.profiles()).find((profile) => profile.did === opened.from)?.name ?? (await contacts.get(opened.from))?.name ?? opened.from;
+            return writeContact({ did: opened.from, name, space: opened.pairSpace });
+        },
+        async others(did) {
+            const found = await contacts.get(did);
+            if (!found?.space || !(await registry.get(found.space)))
+                return [];
+            const open = await runtime(found.space);
+            const [{ members }, profiles, status] = await Promise.all([open.access(), open.profiles(), open.status()]);
+            const seen = new Set([...members.map((member) => member.did), ...profiles.map((profile) => profile.did), ...Object.values(status.accounts)]);
+            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 `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();
@@ -657,6 +1542,9 @@ export async function createNode(config) {
         async delete(spaceId, name) {
             return (await runtime(spaceId)).undefine(name);
         },
+        async tag(spaceId, collection, field, value) {
+            return (await runtime(spaceId)).topicTag(collection, field, value);
+        },
     });
     const accountApi = Object.freeze({
         async profile() {
@@ -713,11 +1601,14 @@ export async function createNode(config) {
         },
         async query(spaceId, query) {
             const space = await runtime(spaceId);
-            return runQuery({
+            // Asked before running, so a node holding part of the space starts fetching what it lacks.
+            const complete = space.use(collectionsOf(query));
+            const result = await runQuery({
                 list: (collection) => space.list({ collection }),
                 get: (key) => space.get(key),
                 linked: (key, options) => space.linked(key, options),
             }, query);
+            return { ...result, complete };
         },
         watch(spaceId, query, onResult, onError) {
             // Changes arrive in bursts during sync; one run at a time, and one more
@@ -839,6 +1730,7 @@ export async function createNode(config) {
             delete: async () => {
                 throw new Error('An agent can\'t remove collections. Ask the person to do it.');
             },
+            tag: async (spaceId, collection, field, value) => (inside(spaceId), collections.tag(spaceId, collection, field, value)),
         });
         return Object.freeze({
             did: config.signer.did,
@@ -848,6 +1740,43 @@ export async function createNode(config) {
             collections: agentCollections,
             account: Object.freeze({ profile: accountApi.profile, setName: person('rename the account'), revoke: person('revoke notes') }),
             carriers: Object.freeze({ list: carriers.list, add: person('add a carrier'), remove: person('remove a carrier') }),
+            notifications: Object.freeze({
+                list: person('look at notifications'),
+                add: person('subscribe to anything'),
+                update: person('change notifications'),
+                remove: person('change notifications'),
+            }),
+            hosting: Object.freeze({
+                list: person('look at hosting'),
+                use: person('start using a host'),
+                payPage: person('pay for hosting'),
+                stop: person('stop using a host'),
+            }),
+            // The list only when the agent was given it; changing it, or asking anyone, is the person's.
+            contacts: Object.freeze({
+                space: async () => (contactsSpaceId && allowed(contactsSpaceId) ? contactsSpaceId : null),
+                list: async () => (contactsSpaceId && allowed(contactsSpaceId) ? contacts.list() : []),
+                get: async (did) => (contactsSpaceId && allowed(contactsSpaceId) ? contacts.get(did) : null),
+                put: person('change contacts'),
+                remove: person('change contacts'),
+                block: person('block anyone'),
+                ask: person('ask anyone to be a contact'),
+                requests: person('open contact requests'),
+                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'),
@@ -868,6 +1797,10 @@ export async function createNode(config) {
         collections,
         account: accountApi,
         carriers,
+        hosting,
+        notifications,
+        contacts,
+        doors,
         asAgent,
         delegation: () => current,
         iceServers: async () => (mesh ? mesh.iceServers() : (config.network?.iceServers ?? DEFAULT_ICE_SERVERS)),