@weaveprotocol/core 0.1.2 → 0.2.0

package/dist/node/node.js

@@ -15,21 +15,29 @@
  * 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, deriveMemberKeyBytes, openSealed, sealFor } from '../identity/contact-key.js';
+import { contact as contactSchema, contactRequest as contactRequestSchema } from '../schemas/contacts.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 +57,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 +156,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 +230,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 +246,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 +256,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 +276,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 +349,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 +367,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 +428,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 +462,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 +573,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 +607,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 +625,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 +645,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 +653,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 +669,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 +684,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 +753,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 +761,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 +787,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 +864,369 @@ 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');
+            return writeContact({
+                did: contact.did,
+                name,
+                ...(contact.space ? { space: contact.space } : {}),
+                ...(contact.note ? { note: contact.note.slice(0, 2000) } : {}),
+            });
+        },
+        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();
+        },
+    });
     const collections = Object.freeze({
         async list(spaceId) {
             return (await runtime(spaceId)).collections();
@@ -657,6 +1237,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 +1296,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 +1425,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 +1435,31 @@ 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'),
+            }),
             delegation: () => note,
             iceServers: node.iceServers,
             delegate: person('pass its access on'),
@@ -868,6 +1480,9 @@ export async function createNode(config) {
         collections,
         account: accountApi,
         carriers,
+        hosting,
+        notifications,
+        contacts,
         asAgent,
         delegation: () => current,
         iceServers: async () => (mesh ? mesh.iceServers() : (config.network?.iceServers ?? DEFAULT_ICE_SERVERS)),