@weaveprotocol/cli 0.2.0 → 0.2.1

package/README.md

@@ -215,3 +215,20 @@ space anywhere leaves it everywhere.
 
 - **WebRTC on the node.** Browsers reach it over WebSocket. `node-datachannel`
   plugs into the same transport seam if measurement says it is needed.
+- **Publishing.** `weave-protocol-cli` on npm (or a built JS package), and
+  trying the Bun binary with `node-datachannel`.
+- **Hosting, before it's offered to anyone.**
+  - A load test with 1,000 spaces, with metrics. Check the pricing against those numbers, and decide on TURN from them.
+  - A real Stripe test-mode run end to end, and a decision on Stripe Tax or a merchant of record.
+  - A breach plan.
+- **The pay page.**
+  - A real Base Sepolia wallet payment.
+  - A Lightning route (BTCPay), and gasless USDC (EIP-3009).
+  - An optional email for reminders: SMTP, with double opt-in.
+- **TURN.** Run coturn with `use-auth-secret` and quotas, and set
+  `TURN_SECRET` and `TURN_URLS` on the relay and the node. Then test calls
+  across real networks, behind a strict NAT, in Safari, and on a phone
+  switching apps.
+
+What the protocol still has planned is in [the spec](../docs/spec/README.md),
+under **Planned** in each part.

package/dist/weave.mjs

@@ -2499,7 +2499,7 @@ function ecdsa(Point, hash2, ecdsaOpts = {}) {
     const sig = drbg(seed, k2sig);
     return sig.toBytes(opts2.format);
   }
-  function verify(signature, message, publicKey, opts2 = {}) {
+  function verify2(signature, message, publicKey, opts2 = {}) {
     const { lowS, prehash, format: format2 } = validateSigOpts(opts2, defaultSigOpts);
     publicKey = abytes2(publicKey, void 0, "publicKey");
     message = validateMsgAndHash(message, prehash);
@@ -2547,7 +2547,7 @@ function ecdsa(Point, hash2, ecdsaOpts = {}) {
     lengths,
     Point,
     sign,
-    verify,
+    verify: verify2,
     recoverPublicKey,
     Signature,
     hash: hash_
@@ -3610,6 +3610,8 @@ function withWrap(vault, wrap) {
 var CONTACT_KEY_INFO = "weave/p256-contact-key/v1";
 var SEAL_INFO = "weave/contact-seal/v1";
 var MEMBER_KEY_INFO = "weave/p256-member-key/v1";
+var DOOR_KEY_INFO = "weave/p256-door-key/v1";
+var DOOR_SIGN_KEY_INFO = "weave/p256-door-sign-key/v1";
 var P256_SEED_BYTES2 = 48;
 var POINT_BYTES = 65;
 var IV_BYTES2 = 12;
@@ -3628,6 +3630,39 @@ async function deriveContactKeyBytes(seed) {
 async function deriveMemberKeyBytes(accountKey, spaceId) {
   return p256.utils.randomSecretKey(await hkdf2(accountKey, `${MEMBER_KEY_INFO}|${spaceId}`, P256_SEED_BYTES2));
 }
+async function deriveDoorKeyBytes(contactKey, doorId) {
+  return p256.utils.randomSecretKey(await hkdf2(contactKey, `${DOOR_KEY_INFO}|${doorId}`, P256_SEED_BYTES2));
+}
+async function deriveDoorSignKeyBytes(contactKey, doorId) {
+  return p256.utils.randomSecretKey(await hkdf2(contactKey, `${DOOR_SIGN_KEY_INFO}|${doorId}`, P256_SEED_BYTES2));
+}
+async function signWithScalar(secret, data) {
+  const point = p256.getPublicKey(secret, false);
+  const key3 = await globalThis.crypto.subtle.importKey(
+    "jwk",
+    {
+      kty: "EC",
+      crv: "P-256",
+      x: base64UrlEncode(point.subarray(1, 33)),
+      y: base64UrlEncode(point.subarray(33, 65)),
+      d: base64UrlEncode(secret),
+      ext: false
+    },
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["sign"]
+  );
+  return base64UrlEncode(new Uint8Array(await globalThis.crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, key3, data)));
+}
+async function verifyWithPoint(publicKey, data, signature) {
+  try {
+    const point = p256.Point.fromBytes(base64UrlDecode(publicKey)).toBytes(false);
+    const key3 = await globalThis.crypto.subtle.importKey("raw", point, { name: "ECDSA", namedCurve: "P-256" }, false, ["verify"]);
+    return await globalThis.crypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" }, key3, base64UrlDecode(signature), data);
+  } catch {
+    return false;
+  }
+}
 function contactPublicKey(secret) {
   return base64UrlEncode(p256.getPublicKey(secret, true));
 }
@@ -10392,7 +10427,8 @@ var contact = typed()({
       name: { type: "string", maxLength: 200, description: "What you call them" },
       space: { type: "string", maxLength: 256, description: "The id of your space for two" },
       note: { type: "string", maxLength: 2e3 },
-      blocked: { type: "boolean", description: "Their contact requests are hidden, in every space" }
+      blocked: { type: "boolean", description: "Their contact requests are hidden, in every space" },
+      door: { type: "string", maxLength: 64, description: "The door they knocked on, while your answer is still to be written in your space for two" }
     },
     required: ["did", "name"]
   },
@@ -10412,6 +10448,273 @@ var contactRequest = typed()({
   },
   rules: { edit: "creator", delete: "creator" }
 });
+var door = typed()({
+  name: "std.door",
+  title: "Door",
+  description: "A way for people you share no space with to ask to become your contact.",
+  schema: {
+    type: "object",
+    properties: {
+      id: { type: "string", minLength: 16, maxLength: 64, description: "Random; the door key is derived from it" },
+      label: { type: "string", maxLength: 64, description: "What you call this door \u2014 only you see it" },
+      name: { type: "string", maxLength: 64, description: "The name its code gives, shown to whoever knocks" },
+      relays: { type: "array", items: { type: "string", maxLength: 200 }, minItems: 1, maxItems: 3, description: "Whose mailboxes hold its knocks" }
+    },
+    required: ["id", "relays"]
+  },
+  rules: { onePer: ["id"] }
+});
+var knock = typed()({
+  name: "std.knock",
+  title: "Knock",
+  description: "A knock left on a door, waiting for an answer.",
+  schema: {
+    type: "object",
+    properties: {
+      space: { type: "string", maxLength: 256, description: "The space for two it invites them to" },
+      name: { type: "string", maxLength: 64, description: "The name their door code gave" },
+      door: { type: "string", maxLength: 64, description: "The door key knocked on" },
+      sign: { type: "string", maxLength: 64, description: "The door's signing key, which their answer must be signed with" },
+      invite: { type: "string", maxLength: 8e3, description: "The invite sent, to close once they answer" }
+    },
+    required: ["space", "name", "door", "sign", "invite"]
+  },
+  rules: { onePer: ["space"] }
+});
+var knockAnswer = typed()({
+  name: "std.knock-answer",
+  title: "Knock answer",
+  description: "Proof that the account which joined is the one behind the door knocked on.",
+  schema: {
+    type: "object",
+    properties: {
+      sig: { type: "string", maxLength: 200, description: 'The door signing key over "weave/knock-answer/v1|<space>|<account>"' }
+    },
+    required: ["sig"]
+  },
+  rules: { edit: "creator", delete: "creator" }
+});
+
+// ../src/doors/doors.ts
+var MAX_DOOR_RELAYS = 3;
+var KNOCK_TTL_SECONDS = 14 * 24 * 3600;
+var KNOCK_DROP_WINDOW_SECONDS = 600;
+var MAX_NAME = 64;
+var MAX_NOTE = 2e3;
+var MAX_INVITE = 6e3;
+var MAX_PROOF = 4096;
+function clip(text, max) {
+  const chars = Array.from(text);
+  return chars.length <= max ? text : chars.slice(0, max).join("");
+}
+function encodeDoorCode(code) {
+  const problem = checkDoorCode({ v: 1, ...code });
+  if (problem) throw new Error(problem);
+  return base64UrlEncode(
+    utf8Encode(canonicalize({ v: 1, key: code.key, sign: code.sign, relays: [...code.relays], ...code.name ? { name: code.name } : {} }))
+  );
+}
+function parseDoorCode(text) {
+  const trimmed = text.trim();
+  const found = /(?:^|[#?&])door=([A-Za-z0-9_-]+)/.exec(trimmed);
+  const raw = found ? found[1] : trimmed;
+  let parsed;
+  try {
+    parsed = JSON.parse(utf8Decode(base64UrlDecode(raw)));
+  } catch {
+    throw new Error("That is not a door code \u2014 it may be cut short.");
+  }
+  const problem = checkDoorCode(parsed);
+  if (problem) throw new Error(`That door code doesn't work: ${problem}`);
+  const code = parsed;
+  return Object.freeze({ v: 1, key: code.key, sign: code.sign, relays: Object.freeze([...code.relays]), ...code.name ? { name: code.name } : {} });
+}
+function checkDoorCode(value) {
+  const code = value;
+  if (!code || typeof code !== "object" || code.v !== 1) return "it is not a version 1 door";
+  if (!isContactPublicKey(code.key)) return "its key is not a P-256 public key";
+  if (!isContactPublicKey(code.sign) || code.sign === code.key) return "its signing key is not a P-256 public key of its own";
+  if (!Array.isArray(code.relays) || code.relays.length === 0 || code.relays.length > MAX_DOOR_RELAYS) {
+    return `it names 1\u2013${MAX_DOOR_RELAYS} relays`;
+  }
+  const relays = checkRelays(code.relays);
+  if (relays) return relays;
+  if (code.name !== void 0 && (typeof code.name !== "string" || Array.from(code.name).length > MAX_NAME)) return `its name is text of at most ${MAX_NAME} characters`;
+  return null;
+}
+async function doorTopic(sign) {
+  return base64UrlEncode(await sha2562(utf8Encode(`weave/door-topic/v1|${sign}`)));
+}
+var purgeMessage = (topic, nonce, ids) => utf8Encode(`weave/door-purge/v1|${topic}|${nonce}|${ids ? [...ids].sort().join(",") : "*"}`);
+function signPurge(signKey, topic, nonce, ids) {
+  return signWithScalar(signKey, purgeMessage(topic, nonce, ids));
+}
+var answerMessage = (pairSpace, did) => utf8Encode(`weave/knock-answer/v1|${pairSpace}|${did}`);
+function signAnswer(signKey, pairSpace, did) {
+  return signWithScalar(signKey, answerMessage(pairSpace, did));
+}
+function checkAnswer(sign, pairSpace, did, signature) {
+  return verifyWithPoint(sign, answerMessage(pairSpace, did), signature);
+}
+async function knockId(blob) {
+  return base64UrlEncode(await sha2562(utf8Encode(blob)));
+}
+var knockContext = (door2) => `weave/knock/v1|${door2}`;
+async function sealKnock(door2, knock2, session, provider) {
+  const note = knock2.note ? clip(knock2.note.trim(), MAX_NOTE) : void 0;
+  const body = {
+    v: 1,
+    door: door2,
+    from: knock2.from,
+    name: clip(knock2.name.trim(), MAX_NAME) || "Someone",
+    invite: knock2.invite,
+    ...note ? { note } : {},
+    at: Math.floor(Date.now() / 1e3),
+    session: session.did,
+    proof: session.proof
+  };
+  const sig = base64UrlEncode(await provider.sign(session.key, utf8Encode(canonicalize(body))));
+  return sealFor(door2, { body, sig }, knockContext(door2));
+}
+async function openKnock(doorKey, blob, receivedAt, provider) {
+  const door2 = contactPublicKey(doorKey);
+  const opened = await openSealed((await contactKeyPair(doorKey)).privateKey, blob, knockContext(door2));
+  const body = opened?.body;
+  if (!body || typeof opened.sig !== "string") return null;
+  if (body.v !== 1 || body.door !== door2) return null;
+  if (typeof body.from !== "string" || typeof body.session !== "string" || typeof body.name !== "string") return null;
+  if (Array.from(body.name).length > MAX_NAME) return null;
+  if (typeof body.invite !== "string" || body.invite.length > MAX_INVITE) return null;
+  if (typeof body.proof !== "string" || body.proof.length > MAX_PROOF) return null;
+  if (body.note !== void 0 && (typeof body.note !== "string" || Array.from(body.note).length > MAX_NOTE)) return null;
+  if (!Number.isSafeInteger(body.at) || !Number.isFinite(receivedAt)) return null;
+  const now = Math.floor(Date.now() / 1e3);
+  if (body.at > now + UCAN_CLOCK_SKEW_SECONDS || body.at < now - KNOCK_TTL_SECONDS) return null;
+  const dropped = Math.floor(receivedAt / 1e3);
+  if (body.at > dropped + UCAN_CLOCK_SKEW_SECONDS || body.at < dropped - KNOCK_DROP_WINDOW_SECONDS) return null;
+  let signed = false;
+  try {
+    const key3 = await provider.importPublicKey(didToPublicKey(body.session).publicKeyBytes);
+    signed = await provider.verify(key3, base64UrlDecode(opened.sig), utf8Encode(canonicalize(body)));
+  } catch {
+    return null;
+  }
+  if (!signed) return null;
+  if (isAgentNote(body.proof)) return null;
+  const chain = await resolveDelegationRoot(body.proof, () => null, provider, { at: body.at }).catch(() => null);
+  if (!chain?.valid || chain.audience !== body.session || chain.rootDid !== body.from) return null;
+  if (!chain.capabilities.some((capability) => capability.with === "*" && (capability.can === "expression/*" || capability.can === "*"))) return null;
+  let invited;
+  try {
+    invited = parseSpaceInvite(body.invite);
+  } catch {
+    return null;
+  }
+  if (invited.space.creator !== body.from || invited.space.visibility !== "private" || !invited.key) return null;
+  if (await checkSpace(invited.space) !== null) return null;
+  return Object.freeze({
+    from: body.from,
+    name: clip(body.name, MAX_NAME) || "Someone",
+    ...body.note ? { note: body.note } : {},
+    invite: body.invite,
+    pairSpace: invited.space.id,
+    at: body.at * 1e3
+  });
+}
+
+// ../src/network/mailbox.ts
+var MAX_PAGES = 8;
+function createMailboxClient(options = {}) {
+  const timeoutMs = options.timeoutMs ?? 8e3;
+  function ask(relay, message, pick) {
+    return talk(relay, (send2) => send2(message), async (answer) => pick(answer));
+  }
+  function talk(relay, start, hear) {
+    const Socket = options.WebSocket ?? globalThis.WebSocket;
+    if (!Socket) return Promise.reject(new Error("No WebSocket here to reach a relay with"));
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const ws = new Socket(relay);
+      const finish = (error, value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        try {
+          ws.close();
+        } catch {
+        }
+        if (error) reject(error);
+        else resolve(value);
+      };
+      const timer = setTimeout(() => finish(new Error(`${relay} did not answer`)), timeoutMs);
+      const say = (message) => ws.send(JSON.stringify(message));
+      ws.onopen = () => start(say);
+      ws.onerror = () => finish(new Error(`Could not reach ${relay}`));
+      ws.onclose = () => finish(new Error(`${relay} closed the connection`));
+      ws.onmessage = (event) => {
+        let answer;
+        try {
+          answer = JSON.parse(String(event.data));
+        } catch {
+          return;
+        }
+        if (!answer || typeof answer !== "object") return;
+        hear(answer, say).then(
+          (value) => {
+            if (value !== void 0) finish(null, value);
+          },
+          (error) => finish(error instanceof Error ? error : new Error(String(error)))
+        );
+      };
+    });
+  }
+  const client = {
+    drop(relay, topic, blob, ttlSeconds) {
+      return ask(relay, { type: "drop", topic, blob, ...ttlSeconds ? { ttl: ttlSeconds } : {} }, (answer) => {
+        if (answer.topic !== topic) return void 0;
+        if (answer.type === "dropped" && typeof answer.id === "string") return answer.id;
+        if (answer.type === "refused") throw new Error(`${relay} refused the knock: ${String(answer.reason ?? "no reason given")}`);
+        return void 0;
+      });
+    },
+    async fetch(relay, topic, after = 0) {
+      const found = [];
+      let from = after;
+      for (let page = 0; page < MAX_PAGES; page++) {
+        const { items, more } = await ask(
+          relay,
+          { type: "fetch", topic, after: from },
+          (answer) => answer.type === "mail" && answer.topic === topic && Array.isArray(answer.items) ? { items: answer.items.filter(isMailItem), more: answer.more === true } : void 0
+        );
+        found.push(...items);
+        if (!more || items.length === 0) break;
+        from = Math.max(...items.map((item) => item.seq));
+      }
+      return found;
+    },
+    purge(relay, topic, sign, ids, signChallenge) {
+      return talk(
+        relay,
+        (send2) => send2({ type: "challenge" }),
+        async (answer, send2) => {
+          if (answer.type === "challenge" && typeof answer.nonce === "string") {
+            send2({ type: "purge", topic, sign, ...ids ? { ids: [...ids] } : {}, sig: await signChallenge(answer.nonce) });
+            return void 0;
+          }
+          if (answer.topic !== topic) return void 0;
+          if (answer.type === "purged" && typeof answer.count === "number") return answer.count;
+          if (answer.type === "refused") throw new Error(`${relay} refused to clear the door: ${String(answer.reason ?? "no reason given")}`);
+          return void 0;
+        }
+      );
+    }
+  };
+  return Object.freeze(client);
+}
+function isMailItem(value) {
+  const item = value;
+  return !!item && Number.isSafeInteger(item.seq) && typeof item.id === "string" && typeof item.at === "number" && typeof item.blob === "string";
+}
 
 // ../src/space/notify.ts
 var NOTIFY_COLLECTION = "sys.notify";
@@ -11425,11 +11728,13 @@ async function createNode(config) {
       if (!contact2.did.startsWith("did:")) throw new Error("A contact needs their account DID");
       const name = contact2.name.trim().slice(0, 200);
       if (!name) throw new Error("A contact needs a name");
+      const pending = (await contactRecords()).find((record) => record.body.did === contact2.did)?.body?.door;
       return writeContact({
         did: contact2.did,
         name,
         ...contact2.space ? { space: contact2.space } : {},
-        ...contact2.note ? { note: contact2.note.slice(0, 2e3) } : {}
+        ...contact2.note ? { note: contact2.note.slice(0, 2e3) } : {},
+        ...pending ? { door: pending } : {}
       });
     },
     async remove(did) {
@@ -11505,6 +11810,253 @@ async function createNode(config) {
       return [...seen].filter((account2) => account2 !== config.signer.did && account2 !== did).sort();
     }
   });
+  const mailbox = config.mailbox ?? createMailboxClient();
+  const knockCache = /* @__PURE__ */ new Map();
+  const DAY_MS = 24 * 3600 * 1e3;
+  function requireContactKey(what) {
+    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;
+  }
+  async function doorKeys(id) {
+    const contactKey = requireContactKey("A door");
+    const key3 = await deriveDoorKeyBytes(contactKey, id);
+    const sign = await deriveDoorSignKeyBytes(contactKey, id);
+    const signPublic = contactPublicKey(sign);
+    return { key: key3, sign, publicKey: contactPublicKey(key3), signPublic, topic: await doorTopic(signPublic) };
+  }
+  async function doorRecords() {
+    if (!contactsSpaceId) return [];
+    return (await (await contactsRuntime()).list({ collection: door.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
+    });
+  }
+  async function purgeDoor(door2, ids) {
+    const keys = await doorKeys(door2.id);
+    const done = await Promise.allSettled(
+      door2.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: knock.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"
+    );
+  }
+  async function settleSent() {
+    for (const record of await sentRecords()) {
+      const { space: space2, name, sign, invite } = record.body;
+      if (!await registry.get(space2)) {
+        await (await contactsRuntime()).remove(record.key);
+        continue;
+      }
+      const open2 = await runtime(space2);
+      const { members } = await open2.access();
+      let answered = null;
+      for (const answer of await open2.list({ collection: knockAnswer.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, space2, did, answer.body.sig)) {
+          answered = did;
+          break;
+        }
+      }
+      if (answered) {
+        await spaces.closeInvite(space2, invite).catch(() => {
+        });
+        const given = (await open2.profiles()).find((profile) => profile.did === answered)?.name;
+        await writeContact({ did: answered, name: given ?? name, space: space2 });
+        await (await contactsRuntime()).remove(record.key);
+      } else if (Date.now() - Date.parse(record.createdAt) > KNOCK_TTL_SECONDS * 1e3 + DAY_MS) {
+        await spaces.leave(space2).catch(() => {
+        });
+        await (await contactsRuntime()).remove(record.key);
+      }
+    }
+  }
+  async function answerAccepted() {
+    for (const record of await contactRecords()) {
+      const { did, space: space2, door: door2 } = record.body;
+      if (typeof door2 !== "string" || typeof space2 !== "string") continue;
+      if (!await registry.get(space2)) continue;
+      const open2 = await runtime(space2);
+      if ((await open2.access()).role === null) continue;
+      const { sign } = await doorKeys(door2);
+      try {
+        await open2.put(knockAnswer.name, { sig: await signAnswer(sign, space2, config.signer.did) });
+      } catch {
+        continue;
+      }
+      const { door: _answered, ...rest } = record.body;
+      await writeContact({ ...rest, did });
+    }
+  }
+  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);
+      const held = /* @__PURE__ */ 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) {
+          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 * 1e3 };
+          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)));
+      const keys = await doorKeys(id);
+      encodeDoorCode({ key: keys.publicKey, sign: keys.signPublic, relays, ...name ? { name } : {} });
+      const open2 = await contactsRuntime();
+      await ensureDefined(open2, door);
+      return doorView(await open2.put(door.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 [knock2, cached] of knockCache) if (cached.door === id) knockCache.delete(knock2);
+    },
+    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 [knock2, cached] of knockCache) if (cached.door === id) knockCache.delete(knock2);
+    },
+    async knock(code, options = {}) {
+      requireContactKey("Knocking on a door");
+      requireEverywhere("Knocking on a door");
+      const door2 = parseDoorCode(code);
+      for (const mine2 of await doors.list()) if (mine2.key === door2.key) throw new Error("That is one of your own doors");
+      if (!contactsSpaceId) await contactsRuntime();
+      const mine = await ownName() ?? "Someone";
+      const theirs = door2.name ?? "Contact";
+      const pair = await spaces.create({ name: `${clip(mine, 64)} & ${theirs}`, visibility: "private", ...team });
+      let invite;
+      try {
+        await ensureDefined(await runtime(pair.id), knockAnswer);
+        invite = await spaces.invite(pair.id, { role: "editor" });
+        const blob = await sealKnock(
+          door2.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(door2.sign);
+        const left = await Promise.allSettled(door2.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 open2 = await contactsRuntime();
+      await ensureDefined(open2, knock);
+      await open2.put(knock.name, { space: pair.id, name: theirs, door: door2.key, sign: door2.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: door2, opened } of await readDoors()) {
+        if (opened.from === config.signer.did || blocked.has(opened.from)) continue;
+        if (await registry.get(opened.pairSpace)) continue;
+        found.push(
+          Object.freeze({
+            id,
+            door: door2,
+            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 contact2 = await writeContact({ did: knocked.from, name: known?.name ?? knocked.name, space: knocked.pairSpace, door: cached.door });
+      await answerAccepted().catch(() => {
+      });
+      const door2 = (await doorRecords()).find((record) => record.body.id === cached.door);
+      if (door2) await purgeDoor(door2.body, [id]).catch(() => 0);
+      knockCache.delete(id);
+      return contact2;
+    },
+    async dismiss(id) {
+      requireContactKey("Dismissing a knock");
+      if (!knockCache.has(id)) await readDoors();
+      const cached = knockCache.get(id);
+      if (!cached) return;
+      const door2 = (await doorRecords()).find((record) => record.body.id === cached.door);
+      if (door2) await purgeDoor(door2.body, [id]);
+      knockCache.delete(id);
+    }
+  });
   const collections = Object.freeze({
     async list(spaceId) {
       return (await runtime(spaceId)).collections();
@@ -11721,6 +12273,18 @@ async function createNode(config) {
         accept: person("accept contact requests"),
         others: person("look inside a contact's space")
       }),
+      // Doors are the person's: an agent has none and knocks on none.
+      doors: Object.freeze({
+        list: async () => [],
+        open: person("open a door"),
+        close: person("close a door"),
+        knock: person("knock on anyone's door"),
+        clear: person("clear a door"),
+        knocks: person("read knocks"),
+        sent: person("look at knocks"),
+        accept: person("open the door to anyone"),
+        dismiss: person("dismiss a knock")
+      }),
       delegation: () => note,
       iceServers: node.iceServers,
       delegate: person("pass its access on"),
@@ -11744,6 +12308,7 @@ async function createNode(config) {
     hosting,
     notifications,
     contacts,
+    doors,
     asAgent,
     delegation: () => current,
     iceServers: async () => mesh ? mesh.iceServers() : config.network?.iceServers ?? DEFAULT_ICE_SERVERS,
@@ -13390,7 +13955,7 @@ import { createServer } from "node:http";
 import { WebSocketServer } from "ws";
 
 // ../server/relay.mjs
-import { createHmac, randomBytes as randomBytes4 } from "node:crypto";
+import { createHash, createHmac, createPublicKey, randomBytes as randomBytes4, verify } from "node:crypto";
 var MAX_MESSAGE_BYTES = 64 * 1024;
 var MAX_CONNECTIONS = 5e3;
 var MAX_CONNECTIONS_PER_IP = 32;
@@ -13404,6 +13969,32 @@ var RATE_BURST = 100;
 var HEARTBEAT_MS = 15e3;
 var MAX_BUFFERED_BYTES = 1024 * 1024;
 var MAX_TURN_ADDRESSES = 2e4;
+var MAX_BLOB_LENGTH = 12e3;
+var TOPIC_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+var MAX_MAIL_PER_TOPIC = 64;
+var RESERVED_PER_TOPIC = 2;
+var DROP_WINDOW_MS = 36e5;
+var MAILBOX_LIMITS = Object.freeze({
+  /** Topics held at once */
+  maxTopics: 5e4,
+  /** Everything held at once, in blob characters */
+  maxChars: 64 * 1024 * 1024,
+  /**
+   * Past `maxChars`, a reserve only topics holding fewer than two knocks may
+   * use: a mailbox someone filled still takes a knock or two on every door.
+   */
+  reserveChars: 8 * 1024 * 1024,
+  /** How long a knock is kept. A client may ask for less, never more. */
+  ttlSeconds: 14 * 24 * 3600,
+  /** Drops one address may make into one topic per hour: filling a door takes many addresses */
+  dropsPerNetworkPerTopic: 4,
+  /** Drops one address may make in all, per hour: filling the mailbox takes very many */
+  dropsPerNetwork: 30
+});
+var PURGE_SPKI_PREFIX = Buffer.from("3039301306072a8648ce3d020106082a8648ce3d030107032200", "hex");
+var MAX_WATCHES_PER_SOCKET = 32;
+var MAX_PAGE_ITEMS = 16;
+var MAX_PAGE_CHARS = 48 * 1024;
 var ROUTED = /* @__PURE__ */ new Set(["offer", "answer", "candidate"]);
 var DID_PATTERN = /^did:key:z[1-9A-HJ-NP-Za-km-z]+$/;
 var CLOSE_DID_TAKEN = 4009;
@@ -13415,19 +14006,25 @@ function turnFromEnv(env) {
 }
 function createRelay(options = {}) {
   const { turn } = options;
+  const limits = { ...MAILBOX_LIMITS, ...options.mailbox };
   const log = options.log ?? (() => {
   });
   const rooms = /* @__PURE__ */ new Map();
   const clients = /* @__PURE__ */ new Set();
   const perIp = /* @__PURE__ */ new Map();
   const turnByNetwork = /* @__PURE__ */ new Map();
+  const mailbox = /* @__PURE__ */ new Map();
+  const watchers = /* @__PURE__ */ new Map();
+  const dropsBy = /* @__PURE__ */ new Map();
+  let mailChars = 0;
+  let mailSeq = 0;
   function canEnter(room) {
     if (typeof room !== "string" || room.length === 0 || room.length > MAX_ROOM_LENGTH) return false;
     const peers = rooms.get(room);
     return peers ? peers.size < MAX_PEERS_PER_ROOM : rooms.size < MAX_ROOMS;
   }
   function accept(ws, legacyRoom, ip) {
-    const client = { ws, legacyRoom, ip, did: null, rooms: /* @__PURE__ */ new Set(), alive: true, tokens: RATE_BURST, refilled: Date.now() };
+    const client = { ws, legacyRoom, ip, did: null, rooms: /* @__PURE__ */ new Set(), watching: /* @__PURE__ */ new Set(), nonce: null, alive: true, tokens: RATE_BURST, refilled: Date.now() };
     clients.add(client);
     perIp.set(ip, (perIp.get(ip) ?? 0) + 1);
     ws.on("pong", () => client.alive = true);
@@ -13447,6 +14044,7 @@ function createRelay(options = {}) {
       if (left > 0) perIp.set(ip, left);
       else perIp.delete(ip);
       for (const room of [...client.rooms]) leave(client, room);
+      for (const topic of [...client.watching]) unwatch(client, topic);
     };
     ws.on("close", drop);
     ws.on("error", () => ws.terminate());
@@ -13477,6 +14075,10 @@ function createRelay(options = {}) {
       log(`peer joined room ${short(room)} (${rooms.get(room).size} present)`);
       return;
     }
+    if (message.type === "drop" || message.type === "fetch" || message.type === "unwatch" || message.type === "challenge" || message.type === "purge") {
+      handleMail(client, message);
+      return;
+    }
     if (message.type === "ice") {
       if (client.did) offerTurn(client);
       return;
@@ -13494,6 +14096,137 @@ function createRelay(options = {}) {
       }
     }
   }
+  function handleMail(client, message) {
+    if (message.type === "challenge") {
+      client.nonce = randomBytes4(18).toString("base64url");
+      send2(client, JSON.stringify({ type: "challenge", nonce: client.nonce }));
+      return;
+    }
+    const { topic } = message;
+    if (typeof topic !== "string" || !TOPIC_PATTERN.test(topic)) return;
+    if (message.type === "unwatch") {
+      unwatch(client, topic);
+      return;
+    }
+    if (message.type === "purge") {
+      purge(client, message);
+      return;
+    }
+    if (message.type === "fetch") {
+      const after = Number.isSafeInteger(message.after) ? message.after : 0;
+      if (message.watch === true && !client.watching.has(topic) && client.watching.size < MAX_WATCHES_PER_SOCKET) {
+        client.watching.add(topic);
+        if (!watchers.has(topic)) watchers.set(topic, /* @__PURE__ */ new Set());
+        watchers.get(topic).add(client);
+      }
+      const now2 = Date.now();
+      const items = [];
+      let chars = 0;
+      let more = false;
+      for (const item2 of mailbox.get(topic) ?? []) {
+        if (item2.seq <= after || item2.expires <= now2) continue;
+        if (items.length >= MAX_PAGE_ITEMS || chars + item2.blob.length > MAX_PAGE_CHARS) {
+          more = true;
+          break;
+        }
+        items.push(mailItem(item2));
+        chars += item2.blob.length;
+      }
+      send2(client, JSON.stringify({ type: "mail", topic, items, more }));
+      return;
+    }
+    const refuse = (reason) => send2(client, JSON.stringify({ type: "refused", topic, reason }));
+    const { blob } = message;
+    if (typeof blob !== "string" || blob.length === 0 || blob.length > MAX_BLOB_LENGTH || !/^[A-Za-z0-9_-]+$/.test(blob)) {
+      refuse("A knock is base64url, at most 12000 characters");
+      return;
+    }
+    const id = createHash("sha256").update(blob).digest("base64url");
+    const held = mailbox.get(topic) ?? [];
+    if (held.some((item2) => item2.id === id)) {
+      send2(client, JSON.stringify({ type: "dropped", topic, id }));
+      return;
+    }
+    const now = Date.now();
+    const network = networkOf(client.ip);
+    const here = countOf(`${network}|${topic}`, now);
+    const everywhere = countOf(network, now);
+    if (here >= limits.dropsPerNetworkPerTopic) return refuse("Too many knocks on this door from here; try later");
+    if (everywhere >= limits.dropsPerNetwork) return refuse("Too many knocks from here; try later");
+    if (held.length >= MAX_MAIL_PER_TOPIC) return refuse("This door is full");
+    if (!mailbox.has(topic) && mailbox.size >= limits.maxTopics) return refuse("The mailbox is full");
+    const room = held.length < RESERVED_PER_TOPIC ? limits.maxChars + limits.reserveChars : limits.maxChars;
+    if (mailChars + blob.length > room) return refuse("The mailbox is full");
+    const ttl = Number.isFinite(message.ttl) && message.ttl > 0 ? Math.min(message.ttl, limits.ttlSeconds) : limits.ttlSeconds;
+    const item = { seq: ++mailSeq, id, at: now, expires: now + ttl * 1e3, blob };
+    held.push(item);
+    mailbox.set(topic, held);
+    mailChars += blob.length;
+    counted(`${network}|${topic}`, now);
+    counted(network, now);
+    send2(client, JSON.stringify({ type: "dropped", topic, id }));
+    const news = JSON.stringify({ type: "mail", topic, items: [mailItem(item)], more: false });
+    for (const watcher of watchers.get(topic) ?? []) {
+      if (watcher !== client) send2(watcher, news);
+    }
+  }
+  const mailItem = ({ seq, id, at, blob }) => ({ seq, id, at, blob });
+  function countOf(key3, now) {
+    const recent = dropsBy.get(key3);
+    return recent && now - recent.since < DROP_WINDOW_MS ? recent.count : 0;
+  }
+  function counted(key3, now) {
+    const recent = dropsBy.get(key3);
+    if (recent && now - recent.since < DROP_WINDOW_MS) recent.count += 1;
+    else dropsBy.set(key3, { count: 1, since: now });
+  }
+  function purge(client, message) {
+    const { topic, sign, sig } = message;
+    const refuse = (reason) => send2(client, JSON.stringify({ type: "refused", topic, reason }));
+    const nonce = client.nonce;
+    client.nonce = null;
+    const ids = message.ids === void 0 ? null : message.ids;
+    if (!nonce) return refuse("Ask for a challenge first");
+    if (typeof sign !== "string" || !/^[A-Za-z0-9_-]{44}$/.test(sign) || typeof sig !== "string" || sig.length > 200) return refuse("Not a purge");
+    if (ids !== null && (!Array.isArray(ids) || ids.length > MAX_MAIL_PER_TOPIC || !ids.every((id) => typeof id === "string" && id.length <= 64))) {
+      return refuse("Not a purge");
+    }
+    if (createHash("sha256").update(`weave/door-topic/v1|${sign}`).digest("base64url") !== topic) return refuse("That key is not this door\u2019s");
+    let good = false;
+    try {
+      const key3 = createPublicKey({ key: Buffer.concat([PURGE_SPKI_PREFIX, Buffer.from(sign, "base64url")]), format: "der", type: "spki" });
+      const signed = `weave/door-purge/v1|${topic}|${nonce}|${ids ? [...ids].sort().join(",") : "*"}`;
+      good = verify("sha256", Buffer.from(signed), { key: key3, dsaEncoding: "ieee-p1363" }, Buffer.from(sig, "base64url"));
+    } catch {
+      good = false;
+    }
+    if (!good) return refuse("The signature does not check out");
+    const held = mailbox.get(topic) ?? [];
+    const gone = ids === null ? held : held.filter((item) => ids.includes(item.id));
+    for (const item of gone) mailChars -= item.blob.length;
+    const kept = ids === null ? [] : held.filter((item) => !ids.includes(item.id));
+    if (kept.length === 0) mailbox.delete(topic);
+    else mailbox.set(topic, kept);
+    send2(client, JSON.stringify({ type: "purged", topic, count: gone.length }));
+  }
+  function unwatch(client, topic) {
+    client.watching.delete(topic);
+    const watching = watchers.get(topic);
+    watching?.delete(client);
+    if (watching?.size === 0) watchers.delete(topic);
+  }
+  function sweepMail() {
+    const now = Date.now();
+    for (const [topic, held] of mailbox) {
+      const kept = held.filter((item) => item.expires > now);
+      for (const item of held) if (item.expires <= now) mailChars -= item.blob.length;
+      if (kept.length === 0) mailbox.delete(topic);
+      else if (kept.length !== held.length) mailbox.set(topic, kept);
+    }
+    for (const [key3, recent] of dropsBy) {
+      if (now - recent.since >= DROP_WINDOW_MS) dropsBy.delete(key3);
+    }
+  }
   function offerTurn(client) {
     if (!turn) return;
     const network = networkOf(client.ip);
@@ -13551,6 +14284,7 @@ function createRelay(options = {}) {
     for (const [network, held] of turnByNetwork) {
       if (held.expires <= now) turnByNetwork.delete(network);
     }
+    sweepMail();
     for (const client of clients) {
       if (!client.alive) {
         client.ws.terminate();
@@ -14831,7 +15565,7 @@ var ASK = "agent-link:ask";
 var HEARD = "agent-link:heard";
 var ANSWER = "agent-link:answer";
 var DONE = "agent-link:done";
-var MAX_NAME = 80;
+var MAX_NAME2 = 80;
 function readAgentCode(input) {
   const match = /wv_([A-Za-z0-9_-]{22})(?![A-Za-z0-9_-])/.exec(input);
   const secret = match ? base64UrlDecode(match[1]) : null;
@@ -14898,7 +15632,7 @@ async function acceptAgentLink(params) {
       done();
     };
     net.on("peer-connected", (peer) => {
-      void seal2({ did: params.did, name: params.name.slice(0, MAX_NAME) }, key3).then((payload) => {
+      void seal2({ did: params.did, name: params.name.slice(0, MAX_NAME2) }, key3).then((payload) => {
         net.send(peer.did, { type: ASK, from: params.did, payload });
       });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weaveprotocol/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The Weave protocol from a terminal: manage spaces, run an always-on node, serve MCP to agents",
   "type": "module",
   "bin": {