@weaveprotocol/core 0.1.2 → 0.2.0

package/README.md

@@ -11,11 +11,11 @@ devices, and every app is a view onto that data rather than its owner.
 │                        Applications                          │
 ├──────────────┬───────────┬────────────┬──────────┬───────────┤
 │   Accounts   │  Spaces   │ Validation │ Privacy  │   Sync    │
-│ seed, vault, │ roles,    │ crypto →   │ AES-GCM  │ MST anti- │
-│ root signer, │ members × │ structural │ per      │ entropy   │
-│ UCAN, pairing│ pub/priv  │ → UCAN     │ space    │ gossip    │
+│ seed, vault, │ roles,    │ crypto →   │ AES-GCM  │ Negentropy│
+│ root signer, │ members × │ structural │ per      │ per       │
+│ UCAN, pairing│ pub/priv  │ → UCAN     │ space    │ collection│
 ├──────────────┴───────────┴────────────┴──────────┴───────────┤
-│    Storage: Merkle Search Tree over a StorageAdapter         │
+│    Storage: signed versions + plain index over an adapter    │
 │    IndexedDB (per origin) · data folder (shared by origins)  │
 ├──────────────────────────────────────────────────────────────┤
 │    Network: WebRTC data channels                             │
@@ -71,7 +71,7 @@ const ucan = await root.delegate({
 const spaces = createSpaceManager(await createIndexedDBAdapter('my-app/registry'));
 const { space } = await spaces.create({ name: 'Notes', visibility: 'public', creator: me.did });
 
-// 4. A signed record, stored in that space's own Merkle tree
+// 4. A signed record, stored in that space's own store
 const storage = createStorageProvider(await createIndexedDBAdapter(`my-app/space/${space.id}`));
 const signed = await createSigner(provider).sign(
   createExpression({
@@ -222,6 +222,61 @@ await calls.answer(ringing.id);  calls.setMuted(true);  await calls.shareScreen(
 
 The messages, and the reasoning, are at the top of `src/calls/calls.ts`.
 
+### Contacts
+
+A DID is a **name, not an address**: it's on everything you sign, so knowing
+it must not be enough to reach you. What lets two people reach each other is a
+space they share. So **a contact is a private space for two**: records you
+write there wait for the other person, and live messages reach them when
+they're online. There's no directory to look people up in, and no inbox
+strangers can knock on.
+
+```typescript
+// In a space you share with Anna — the book club — ask her to add you.
+const { space } = await node.contacts.ask(club.id, anna, { note: "it's Leif from book club" });
+
+// On Anna's side:
+const [request] = await node.contacts.requests(club.id);   // { from, name, note, pairSpace, … }
+await node.contacts.accept(club.id, request.key);           // joins the space for two, adds Leif
+
+await node.contacts.list();          // [{ did, name, space, note, blocked }]
+await node.contacts.put({ did, name: 'Anna K' });   // what you call them — only you see it
+await node.contacts.remove(anna);    // off the list, and out of your space with her
+await node.contacts.block(anna);     // and her requests are hidden in every space
+await node.contacts.others(anna);    // anyone else in your space with her: [] unless someone was let in
+```
+
+- **The list** is one `std.contact` per person, in a **contacts space**
+  derived from the account key the way the account registry is: every device
+  of the account has it, nobody else can find it, and it's hidden from
+  `spaces.list`. `contacts.space()` gives its id. A carrier carries it, so a
+  restore brings the list back.
+- **Asking** (`ask`) makes a private space for the two of you, puts them on
+  your list with it, and posts a `std.contact-request` in the shared space:
+  the new space's invite, **sealed with their contact key**. The other members
+  can see that you asked, not what. The seal is bound to the space it was
+  posted in and to who asked whom, so a request copied into another space, or
+  re-posted by someone else, doesn't open. Joining is the answer: there's no
+  reply record.
+- **The contact key** is a P-256 key for encryption, derived from the seed
+  under its own label (`deriveContactKeyBytes`), so it's the same on every
+  device and comes back with the recovery code. Its public half goes on your
+  profile in every space you write in (`spaces.profiles(id)[n].contactKey`),
+  and only counts on a profile signed by your own account. An app without the
+  key never takes it off: a profile keeps the newest key it was given.
+- **Conversation or group** is decided by how the space was made, not by how
+  many people are in it: a space is your conversation with Anna because your
+  list says so. A space made with "New space" and shared with one person is
+  never one. If a third account turns up in a space for two, `others` says so,
+  and an app can offer to start a new space with just the two of you, or a new
+  group with everyone.
+
+**What an app gets.** A home gives the contacts to an app that asks with
+`contacts: true`: the contacts space as one more space in its grant, and the
+contact key, which opens requests sent to you. Asking someone and accepting
+also make or join a space, so those need `scope: 'account'`, which includes
+the contacts. Agents never get them.
+
 ## Signing in — the element, and React
 
 Getting to a node takes a sign-in flow: where the data lives (a pod or this
@@ -362,12 +417,51 @@ the account's list on every device.
 An app that is a view onto *everything* — like the example — asks for
 `scope: 'account'`: a note for every space, plus the key the account's space
 list is derived from, so it sees every space and can make and join them. It
+gets the contacts too (see Contacts, above). It
 still never holds the seed: it cannot sign in anywhere as the account, change
 its password or passkeys, or keep access past the note's date.
 
 The home side is `receiveConnectRequest()` and `auth.grant(…)`; see
 [home/README.md](home/README.md).
 
+### Apps hold what they use — keepers hold the rest
+
+A space can name its **keepers**: nodes that hold every record of it, like a
+host or the extension (`node.spaces.setKeepers`, for someone who manages the
+space; the account's carriers are named by themselves in every space it
+manages). Once it does, an app connected to the account home holds only the
+collections it uses, besides the space's own (`sys.*`):
+
+- a query says what it needs — its collection and every `include … from` —
+  and those start syncing from any peer that has them;
+- `result.complete` is false until they have caught up with a node holding
+  the whole space: show "Loading…", not "Nothing here";
+- the app's own writes stay **pending** until enough keepers say they have
+  them (`stored`): the space's `copies`, or 2, never more than it names.
+  Nothing pending is ever dropped;
+- a collection no query has touched for `unusedAfterDays` (30) is dropped,
+  unless the app declared it (`cache.collections`). It syncs back when needed.
+
+A collection can also name **topic fields** (`topics: ['channel', 'mentions']`).
+Each record then carries, on its outside, a keyed hash of each of those values
+(`tags`), so a keeper that can't read the record can still match "in
+#design" or "mentions me" — learning which records share a topic, never which
+topic. `node.collections.tag(space, collection, field, value)` gives the tag to
+match; anyone who can read a record checks its tags and refuses a mismatch.
+
+**"Notify me when…"** (`node.notifications`, and the home's section of that
+name): new records in a collection, in every space or some, perhaps only with
+a topic value ("mentions me"), perhaps only other people's. The account
+registry keeps each one sealed; every carrier gets it with the value replaced
+by each space's tag, so the Weave extension notices matching records as they
+arrive and shows a notification — the space, your label, the time — without
+being able to read them, or what you asked for.
+
+A space that names no keeper is held whole, as before: then the app may be one
+of its copies. How much to hold is each node's choice (`NodeConfig.cache`;
+`startConnectedNode` turns it on unless given `cache: false`); only how
+keepers confirm is protocol. `spaces.status(id)` shows `holds` and `pending`.
+
 ## Modules
 
 ### Identity (`@weaveprotocol/core/identity`)
@@ -484,16 +578,27 @@ Typed, signed data expressions using [Standard Schema](https://standardschema.de
 
 ### Storage (`@weaveprotocol/core/storage`)
 
-Local-first storage with Merkle Search Tree for efficient sync.
+Local-first storage: signed versions, and plain entries saying which is current
+and which versions each collection keeps — the set sync compares.
 
 | Export | Description |
 |--------|-------------|
-| `createStorageProvider()` | MST-backed expression storage; `compact()` deletes tree nodes the root no longer reaches |
+| `createStorageProvider()` | Expression storage: current, first and retained versions (`r/`, `g/`, `h/`), and every kept version by collection (`i/`) for sync; `fingerprint()` is equal on two stores keeping the same versions |
 | `createIndexedDBAdapter()` | IndexedDB storage adapter, scoped to this origin |
 | `createFolderAdapter()` | A user-picked directory, shared by every origin given access |
 | `createEncryptedAdapter()` | Seals chosen keys (space records, space keys) at rest |
-| `reconcileFolder()` | Rebuilds the tree after another writer touched a folder |
-| `insertIntoMST()` / `listMSTEntries()` | Direct MST operations; a listing can stop at a key prefix |
+| `reconcileFolder()` | Places the files another writer added to a folder, and drops entries whose file is gone |
+| `createMirror()` | Keeps a space in a dumb file store too, synced like a peer that never runs code |
+| `createS3BlobStore()` / `createMemoryBlobStore()` | File stores a mirror can use: any S3-compatible bucket (R2, B2, MinIO, AWS), or memory |
+
+**Mirrors.** A bucket or an app folder can hold a space: each writer (one store
+on one device, with a random id) only ever adds immutable segments in its own
+folder, named by a counter and the hash of their bytes — so nothing is written
+twice and nothing needs a lock. A segment holds versions exactly as they travel,
+private bodies still sealed, and everything read back passes the same gates as a
+peer's records: the store can hide things, not forge them. What a writer knows
+the store holds, it never uploads again; a writer compacts its own segments
+into fewer. Merging is the protocol's own — a set of versions that only grows.
 
 ### Spaces
 
@@ -523,7 +628,7 @@ const { space, key } = await spaces.create({
 });
 ```
 
-Give each space its own storage and its own MST and a peer you share one list
+Give each space its own storage and its own sync and a peer you share one list
 with learns nothing about the others.
 
 #### Who may write: roles, and a history every peer replays
@@ -543,8 +648,9 @@ and roles ranked below you, and give out roles up to your own rank. Two people
 at the same rank can never remove each other, only themselves — so the creator
 **hands over** by giving someone their role, then leaving, and the space goes on.
 
-Roles, members, invites, revoked notes and collection definitions are records
-(`sys.role`, `sys.member`, `sys.invite`, `sys.revoke`, `sys.collection`), and
+Roles, members, invites, revoked notes, collection definitions and changes of a
+private space's key are records (`sys.role`, `sys.member`, `sys.invite`,
+`sys.revoke`, `sys.collection`, `sys.key`), and
 every record written anywhere names the latest of them its writer knew, as
 `seen`. That makes the **access history** a small graph, which every peer
 replays the same way (`space/roles.ts`): a change comes after what it saw;
@@ -586,15 +692,35 @@ connect under someone else's name, and in a private space with the read key
 too, checked against its public half. A stranger who learns a space's id, or a
 relay that sees its room, gets no ciphertext. A peer-to-peer handshake also
 signs both ends' DTLS fingerprints, so a relay that swapped in its own offer to
-sit in the middle is caught. Roles govern writing only: someone removed keeps
-the read key until the space's key changes for everyone (BLOCK-14 §2).
+sit in the middle is caught.
+
+**Removing someone from a private space changes its key**, the way Keybase
+changes a team's key. Whoever manages the space, seeing someone lose their
+place (removed, left, or their role deleted), makes a new key by itself and
+writes a `sys.key` record: the new key's id and public read key, and every
+earlier key sealed under the new one. It is part of the access history, so two
+new keys made apart resolve like any other change, and only `manage` may make
+one. Each member's copy goes in a `sys.box`, sealed to their **member key**: a
+key pair per account per space, derived from the account's vault key, whose
+public half each member publishes in the clear (`sys.memberkey`). An account
+home hands an app the member keys of exactly the spaces it grants.
+
+From then on new records are sealed with the new key. Someone removed keeps what
+they could already read, and nothing after it. Holding the current key opens
+every earlier one, so a newcomer reads the space's past. A member who was away
+when the key changed still holds only the older read key: they prove that, and
+send their note sealed under the older key, and a peer holding it lets them in
+if they are still a member. A host with no key takes the current read key only.
+View-only links made before the change stop working; share a new one.
+`node.spaces.changeKey(space)` does the same by hand, for a lost device.
 
 A space's **id is the hash of what is fixed at creation**: creator, visibility,
 starting roles and which one the creator holds, time, a random nonce and the
-read key (the name is left out, so it can change). `join` refuses an invite
-whose space does not hash to its id, or whose key is not the one the space
-names — so whoever passes an invite on cannot change who started the space, or
-with which roles.
+first read key (the name is left out, so it can change). `join` refuses an
+invite whose space does not hash to its id — so whoever passes an invite on
+cannot change who started the space, or with which roles. The key an invite
+carries may be a later one; its id is its hash, so it is either the key the
+history names or one that opens nothing.
 
 **Spaces describe themselves.** A space stores its collections' definitions —
 name, title, description and a JSON Schema — as signed records in
@@ -774,23 +900,36 @@ tell a Weave peer from anyone else, so set coturn's own quotas (`user-quota`,
 `total-quota`, `max-bps`). TURN only forwards encrypted packets; it can't
 see or hear a call.
 
+The relay's Docker image (`server/`, deployed to Fly) runs coturn beside it when
+`TURN_SECRET` is set, already capped that way: `server/fly.toml` says how.
+
 Only peers already in a room hear about a newcomer, so exactly one side creates
 the offer and the two never collide.
 
 ### Sync (`@weaveprotocol/core/sync`)
 
-Anti-entropy gossip protocol for eventual consistency.
+Range-based set reconciliation (Negentropy, as Nostr's NIP-77), one collection at a time.
 
 | Export | Description |
 |--------|-------------|
-| `createSyncEngine()` | Automatic MST reconciliation with heartbeat |
-| `verifyNode()` / `unknownChildren()` | The pieces of a tree walk |
-
-Two peers compare roots — equal means identical, one round trip. Otherwise each
-walks the other's tree from the root, skipping every subtree already in its own,
-so cost follows the size of the difference: one changed entry in 10,000 costs
-about 37 KB on the wire, where sending every key cost 508 KB. Whether a subtree
-is already here is one lookup in the store, not a read of the whole local tree.
+| `createSyncEngine()` | Reconciles a space with its peers, with a heartbeat |
+| `createReconciler()` / `ItemSet` / `fingerprintOf()` | Negentropy itself, wire-compatible with the reference implementation |
+
+A peer says hello with a fingerprint of each collection it keeps — in essence
+the sum of its version ids. Equal fingerprints mean the same versions, and that
+collection is done. For each one that differs, the peer whose id sorts first
+compares fingerprints of ever smaller ranges with the other until both know
+exactly which versions each lacks; then it asks for what it lacks and sends what
+the other does. Cost follows the difference, not the size: one new version
+among 2,000 syncs in under 8 KB, all told. Nothing is stored for sync beyond
+the versions' own index entries: the sets and sums live in memory, updated by
+every change and read again when another writer (a tab, a folder) changed the
+store.
+
+Each hello also says what the peer holds — `all`, or some collections — and
+two peers reconcile only the collections both hold. A version for a collection
+a node doesn't hold is passed over; one it takes in, it tells the sender it has
+(`stored`). One peer's messages are handled in the order they came.
 
 The engine's `validate` hook is the seam where the validation engine sits.
 Expressions a peer sends are only committed if it accepts them; the rest are
@@ -877,7 +1016,7 @@ A directory handle is the exception. Each origin asks for permission once, and b
   accounts.json                       name, DID and id of each account (readable without unlocking)
   accounts/<id>/account.json          that account's seed, encrypted once per way of unlocking it
   accounts/<id>/stores/<namespace>/
-    kv/<key>                          MST nodes, the root pointer, space records (sealed)
+    kv/<key>                          index entries (current, first, retained, by collection), space records (sealed)
     expressions/<cid>.json            one signed record per file
 ```
 
@@ -910,11 +1049,11 @@ const registry = createEncryptedAdapter(
 );
 ```
 
-**Expressions are the truth; the MST is an index over them.** That inversion is what lets several writers share one folder without taking a lock. Every expression file is named by its own content hash, so concurrent writers can only ever add files that agree; the single mutable thing, the root pointer, is derived state that either side can rebuild. `reconcileFolder()` rebuilds it — call it on an interval, on window focus, or after a sync round, since the web has no filesystem change notification.
+**Expressions are the truth; the entries are an index over them.** That inversion is what lets several writers share one folder without taking a lock. Every expression file is named by its own content hash, so concurrent writers can only ever add files that agree; the one thing both can overwrite, which version a record's current entry names, is derived state either side can put right. `reconcileFolder()` does — it places every file that appeared, which corrects an entry a race left wrong — so call it on an interval, on window focus, or after a sync round, since the web has no filesystem change notification.
 
 Two consequences worth having:
 
-- **The folder is the account.** Copy it to a USB stick and it is your whole identity. Put it in iCloud, Dropbox or Syncthing and several devices converge with no relay at all — the folder becomes a second transport alongside WebRTC, and both meet in the same anti-entropy merge.
+- **The folder is the account.** Copy it to a USB stick and it is your whole identity. Put it in iCloud, Dropbox or Syncthing and several devices converge with no relay at all — the folder becomes a second transport alongside WebRTC, and both meet in the same merge: the set of versions only grows, and the version rule picks the same current one everywhere.
 - **It changes nothing about the mesh.** A folder-backed node is an ordinary peer that happens to be durable and readable by several origins — an availability role, never an authority one. Where there is no folder (Safari, Firefox, mobile) a node keeps an origin-scoped replica and gossips exactly as before.
 
 ### Locking the folder
@@ -939,7 +1078,7 @@ await accounts.write(account, withWrap(vault, wrap));
 
 `deviceWrapsFor(vault, rpId)` says which wraps this origin can even attempt; the rest name keys it cannot reach. The gate is enforced in application code rather than by cryptography — see `src/identity/device-key.ts` for what that does and does not protect against. The recovery code needs no wrap, because it *is* the seed in printable form — it opens the folder anywhere, including on a phone or in a browser with no File System Access API, and it is shown once and stored nowhere.
 
-`createEncryptedAdapter` seals `space:`, `spacekey:`, `spaceinvite:` and `spacerole:` values under the vault key, which is what makes a private space genuinely unreadable to someone holding the folder. It is scoped deliberately narrowly: expressions and MST nodes pass through, so what stays legible is each record's author, timestamp and collection, plus anything in a space its owner made public. Sealing those too would mean an opaque blob store, which would cost the property that makes a folder worth having.
+`createEncryptedAdapter` seals `space:`, `spacekey:`, `spaceinvite:` and `spacerole:` values under the vault key, which is what makes a private space genuinely unreadable to someone holding the folder. It is scoped deliberately narrowly: expressions and index entries pass through, so what stays legible is each record's author, timestamp and collection, plus anything in a space its owner made public. Sealing those too would mean an opaque blob store, which would cost the property that makes a folder worth having.
 
 ### Where the root key lives
 
@@ -991,6 +1130,18 @@ space with is a peer in that one only.
 **Several relays**, so there is no single phone book — a peer announced by two
 of them is announced upward once, and replies go back the way they arrived.
 
+**The space says where it meets**, like a Nostr relay list, but the space's
+own. `sys.relays` is part of the access history, so only someone who manages
+the space changes it (`node.spaces.setRelays`), and a new space names its
+creator's relays by itself. Invites carry the list, so a joiner whose app uses
+other relays reaches the space before anything has synced. Every member then
+joins the space's room on those relays as well as their own
+(`mesh.useRelays(room, relays)`); relays only one space names are joined for
+that space's room alone, and dropped once no open space names them. Moving a
+space to another relay, a self-hosted one say, is one change, and everyone
+follows. No DHT: browsers can't be DHT nodes, and would need a relay to reach
+one anyway.
+
 **Peers introduce peers**, so a relay is only needed for the *first* connection.
 Once you are connected to someone, their data channel carries signalling for the
 peers you have not met: `__peers` says who I can see, `__signal` carries
@@ -1089,6 +1240,27 @@ it doubles as a relay), and `weave mcp` to hand the same operations to an agent.
 It reads and writes the same data folder layout a browser does. See
 [cli/README.md](cli/README.md).
 
+**Hosting.** `weave host` keeps many accounts' spaces online without being able
+to read them: it is the extension's carrier (`createCarrierNode`) with one carry
+space per paying account (`createHostNode`), each space held once however many
+members pay for it. A subscription is a key the account makes and keeps in its
+registry (`sys.hosting`), so every device signs as it; `node.hosting.use(url)`
+starts one, and whichever device notices it is paid hands the host the carry
+space. Every call to the host is signed over method, path, time and body.
+The home knows nothing about payment (BLOCK-23): a host describes itself at
+`/.well-known/weave-host` (like a Nostr relay's NIP-11 document), signs every
+status it gives — the home keeps the latest in the registry as the person's
+proof — and takes payments on its own pay page, which `node.hosting.payPage(url)`
+links to with a signature by the subscription key, valid for an hour at that
+host only. On the page: Stripe Checkout and the Customer Portal (card, Apple
+Pay, Google Pay), whose webhook moves a paid-until date taken from Stripe's own
+billing period; and USDC from a crypto wallet straight to the host's address,
+checked on the network by the host. Past the date: a grace period, then the host drops
+the spaces and deletes its copy. With a bucket (`WEAVE_S3_*`) the host's disk
+is only a cache — every carried space and the subscription list live in the
+bucket, sealed, and a new machine starts from it. The account home's Settings
+has **Keep my spaces online**.
+
 ## Example app
 
 `example/` is the Weave website — a landing page for developers at `/`, and
@@ -1101,11 +1273,44 @@ npm install && (cd example && npm install) && (cd home && npm install)   # the C
 npm run dev
 ```
 
-That starts three things: the example app on 5173, the account home it
-connects to on 5174, and an always-on node on port 8787 that is also the relay.
-The node gets a throwaway identity on first run (`cli/.env.dev`, data in
-`.weave-dev/`), and `example/.env.development` points the app at the other two.
-Override either in a `.env.local`.
+That starts everything, with coloured output per part, and Ctrl-C stops it all:
+
+| Part | Where | What |
+|---|---|---|
+| app | http://localhost:5173 | The example app |
+| home | http://localhost:5174 | The account home it connects to |
+| node | port 8787 | An always-on node that is also the relay; a throwaway identity on first run (`cli/.env.dev`, data in `.weave-dev/`) |
+| host | http://localhost:8788 | `weave host`, what "Keep my spaces online" uses, with its pay page at `/pay`; settings in `cli/.env.host.dev` |
+| stripe | — | Only when you add a Stripe test key (below): forwards Stripe's webhooks to the host |
+
+`example/.env.development` and `home/.env.development` point the app and home
+at the rest. Override any of them in a `.env.local`, and the host in
+`cli/.env.host.local`.
+
+**Trying hosting and payments.** In the home: Settings, **Keep my spaces
+online**, **Keep online** (the dev host is filled in), then **Payment**, which
+opens the host's pay page in a new tab. What you can pay with there:
+
+- **A browser wallet, on by default.** Payments go to Base Sepolia, a test
+  network: test money only. In MetaMask (or any browser wallet), get test ETH
+  for the fee from a Base Sepolia faucet (Coinbase's, or Alchemy's) and test
+  USDC from faucet.circle.com (choose Base Sepolia). Pay, and the pay page
+  says "Payment received"; back in the home's tab, the host shows "paid until"
+  and takes your spaces. To see payments arrive, set your own address as
+  `WEAVE_WALLET_ADDRESS` in `cli/.env.host.local`.
+- **A card, in Stripe's test mode.** In `cli/.env.host.local`, add
+  `STRIPE_SECRET_KEY=sk_test_…` and the price ids of a monthly and a yearly
+  recurring test price (`STRIPE_PRICE_MONTHLY`, `STRIPE_PRICE_YEARLY`, from the Stripe
+  dashboard in test mode). With the Stripe CLI installed, `npm run dev`
+  forwards Stripe's webhooks to the host by itself. Pay with card
+  4242 4242 4242 4242, any future date, any CVC.
+- **Phone wallets, by QR code.** Add `WEAVE_WALLETCONNECT_PROJECT_ID` (free at
+  dashboard.reown.com, with localhost allowed in the project) to
+  `cli/.env.host.local`; `npm run dev` builds what the pay page needs. The
+  wallet has to be on Base Sepolia too.
+
+`npm test` covers the same paths without any of this: a fake network, fake
+Stripe calls, and the home's side against a real host.
 
 The example never signs anyone in: "Connect with Weave" opens the home, where
 you make an account or sign in, and allow the example your whole account. Its
@@ -1129,7 +1334,7 @@ between pods, pair a phone by QR code, and see which apps you connected. In the
 example: make private or public spaces, just yours or with people you invite, and share one with a
 friend via an invite link. Everyone in a space is shown by the name
 they gave. Every record is signed by a delegated session key, stored in that
-space's MST, encrypted first if the space is private, and gossiped to peers over
+space's own store, encrypted first if the space is private, and gossiped to peers over
 WebRTC; a record says *verified* once its signature and its delegation chain
 check out here, and *encrypted* when it arrived encrypted.
 
@@ -1218,8 +1423,8 @@ for the same private scalars, and pinned to recorded DIDs so an accidental
 change cannot slip through; recovery codes; account vaults, wraps and account
 stores; data folders with several writers; spaces, invites and
 encrypt-then-sign; UCAN issuing, attenuation and chain validation; phone
-pairing; peer introductions; the MST; the validation gates; and two peers
-reconciling over the anti-entropy protocol, including the forged, stolen,
+pairing; peer introductions; Negentropy, checked against the reference
+implementation; the validation gates; and two peers reconciling, including the forged, stolen,
 unauthorized and malformed expressions their gatekeepers reject. Above those:
 the node API — versioned records, links, queries, collection definitions,
 profiles, the account registry, moving and merging accounts — and the CLI.

package/dist/identity/contact-key.d.ts

@@ -0,0 +1,42 @@
+export interface ContactKeyPair {
+    /** The public half: a compressed P-256 point, base64url. What goes on a profile. */
+    readonly publicKey: string;
+    /** The private half, for opening what was sealed to the public one. Not extractable. */
+    readonly privateKey: CryptoKey;
+}
+/**
+ * The contact key's private scalar, from the account seed — 32 bytes. This is
+ * what an account home hands an app it lets handle contacts.
+ */
+export declare function deriveContactKeyBytes(seed: Uint8Array): Promise<Uint8Array>;
+/**
+ * An account's **member key** for one space: the same kind of key pair, derived
+ * from the account's vault key and the space id. When a private space's key
+ * changes, the new key is sealed to each member's member key (`sys.box`).
+ *
+ * One per space, not one per account, so an account home can hand an app the
+ * member keys for exactly the spaces it grants — and a new space key reaches
+ * that app without it holding anything that opens other spaces' keys.
+ * @param accountKey The vault key bytes (`deriveVaultKeyBytes(seed)`)
+ */
+export declare function deriveMemberKeyBytes(accountKey: Uint8Array, spaceId: string): Promise<Uint8Array>;
+/** The public half, from the private scalar */
+export declare function contactPublicKey(secret: Uint8Array): string;
+/** Whether a string is a contact key's public half: a point on P-256 */
+export declare function isContactPublicKey(value: unknown): value is string;
+/** The key pair, from the private scalar (`deriveContactKeyBytes`) */
+export declare function contactKeyPair(secret: Uint8Array): Promise<ContactKeyPair>;
+/**
+ * Seals a value so only the holder of a contact key can open it.
+ * @param recipient The contact key's public half, as a profile carries it
+ * @param value Anything JSON can carry
+ * @param context What the sealed value belongs to; opening needs the same
+ * @returns base64url: the ephemeral public point, the IV, and the ciphertext
+ */
+export declare function sealFor(recipient: string, value: unknown, context: string): Promise<string>;
+/**
+ * Opens what `sealFor` sealed.
+ * @returns The value, or null when it was not sealed for this key, or for this context, or was changed
+ */
+export declare function openSealed(privateKey: CryptoKey, sealed: string, context: string): Promise<unknown>;
+//# sourceMappingURL=contact-key.d.ts.map

package/dist/identity/contact-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contact-key.d.ts","sourceRoot":"","sources":["../../src/identity/contact-key.ts"],"names":[],"mappings":"AAkCA,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;CAChC;AAYD;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAEjF;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAEvG;AAED,+CAA+C;AAC/C,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAE3D;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAQlE;AAED,sEAAsE;AACtE,wBAAsB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAiBhF;AASD;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAqBjG;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA2BzG"}

package/dist/identity/contact-key.js

@@ -0,0 +1,133 @@
+/**
+ * @module identity/contact-key
+ * The contact key: what lets someone seal a message only you can open, while
+ * you are offline.
+ *
+ * It is a P-256 key pair for key agreement (ECDH), derived from the account's
+ * seed like the root key but under its own label — the same on every device,
+ * and back with the recovery code. It is not the root key: apps never hold the
+ * seed, and one key should not both sign and decrypt. It is not a session key
+ * either: those change every hour, and a request read next week would be
+ * locked to a key that is gone.
+ *
+ * The public half goes on the account's profile in every space it writes in
+ * (`sys.profile`). The private half stays with the account home, and goes to
+ * apps the person lets handle contacts.
+ *
+ * Sealing works like wrapping a space key (`privacy/key-distribution.ts`): a
+ * fresh key pair for each message, a secret shared with the recipient's
+ * public key, and AES-GCM. The `context` is bound in as additional data, so a
+ * sealed message moved anywhere its context no longer matches doesn't open.
+ */
+import { p256 } from '@noble/curves/nist.js';
+import { base64UrlDecode, base64UrlEncode, utf8Decode, utf8Encode } from '../utils/encoding.js';
+/** Domain separation for the contact key. Changing it changes every account's contact key. */
+const CONTACT_KEY_INFO = 'weave/p256-contact-key/v1';
+const SEAL_INFO = 'weave/contact-seal/v1';
+const MEMBER_KEY_INFO = 'weave/p256-member-key/v1';
+/** 48 bytes reduce to a P-256 scalar without bias, as for the root key (`crypto-p256.ts`) */
+const P256_SEED_BYTES = 48;
+const POINT_BYTES = 65;
+const IV_BYTES = 12;
+async function hkdf(ikm, info, length) {
+    const key = await globalThis.crypto.subtle.importKey('raw', ikm, 'HKDF', false, ['deriveBits']);
+    const bits = await globalThis.crypto.subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(0), info: utf8Encode(info) }, key, length * 8);
+    return new Uint8Array(bits);
+}
+/**
+ * The contact key's private scalar, from the account seed — 32 bytes. This is
+ * what an account home hands an app it lets handle contacts.
+ */
+export async function deriveContactKeyBytes(seed) {
+    return p256.utils.randomSecretKey(await hkdf(seed, CONTACT_KEY_INFO, P256_SEED_BYTES));
+}
+/**
+ * An account's **member key** for one space: the same kind of key pair, derived
+ * from the account's vault key and the space id. When a private space's key
+ * changes, the new key is sealed to each member's member key (`sys.box`).
+ *
+ * One per space, not one per account, so an account home can hand an app the
+ * member keys for exactly the spaces it grants — and a new space key reaches
+ * that app without it holding anything that opens other spaces' keys.
+ * @param accountKey The vault key bytes (`deriveVaultKeyBytes(seed)`)
+ */
+export async function deriveMemberKeyBytes(accountKey, spaceId) {
+    return p256.utils.randomSecretKey(await hkdf(accountKey, `${MEMBER_KEY_INFO}|${spaceId}`, P256_SEED_BYTES));
+}
+/** The public half, from the private scalar */
+export function contactPublicKey(secret) {
+    return base64UrlEncode(p256.getPublicKey(secret, true));
+}
+/** Whether a string is a contact key's public half: a point on P-256 */
+export function isContactPublicKey(value) {
+    if (typeof value !== 'string' || value.length > 64)
+        return false;
+    try {
+        p256.Point.fromBytes(base64UrlDecode(value)).assertValidity();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The key pair, from the private scalar (`deriveContactKeyBytes`) */
+export async function contactKeyPair(secret) {
+    const point = p256.getPublicKey(secret, false);
+    const privateKey = 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: 'ECDH', namedCurve: 'P-256' }, false, ['deriveBits']);
+    return Object.freeze({ publicKey: contactPublicKey(secret), privateKey });
+}
+/** The AES key two sides agree on, bound to the ephemeral key it came from */
+async function sealKey(shared, ephemeral, usage) {
+    const ikm = new Uint8Array([...new Uint8Array(shared), ...ephemeral]);
+    const material = await hkdf(ikm, SEAL_INFO, 32);
+    return globalThis.crypto.subtle.importKey('raw', material, { name: 'AES-GCM', length: 256 }, false, [usage]);
+}
+/**
+ * Seals a value so only the holder of a contact key can open it.
+ * @param recipient The contact key's public half, as a profile carries it
+ * @param value Anything JSON can carry
+ * @param context What the sealed value belongs to; opening needs the same
+ * @returns base64url: the ephemeral public point, the IV, and the ciphertext
+ */
+export async function sealFor(recipient, value, context) {
+    const recipientKey = await globalThis.crypto.subtle.importKey('raw', p256.Point.fromBytes(base64UrlDecode(recipient)).toBytes(false), { name: 'ECDH', namedCurve: 'P-256' }, false, []);
+    const ephemeral = await globalThis.crypto.subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits']);
+    const ephemeralPoint = new Uint8Array(await globalThis.crypto.subtle.exportKey('raw', ephemeral.publicKey));
+    const shared = await globalThis.crypto.subtle.deriveBits({ name: 'ECDH', public: recipientKey }, ephemeral.privateKey, 256);
+    const key = await sealKey(shared, ephemeralPoint, 'encrypt');
+    const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_BYTES));
+    const ciphertext = new Uint8Array(await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv: iv, additionalData: utf8Encode(context) }, key, utf8Encode(JSON.stringify(value))));
+    return base64UrlEncode(new Uint8Array([...ephemeralPoint, ...iv, ...ciphertext]));
+}
+/**
+ * Opens what `sealFor` sealed.
+ * @returns The value, or null when it was not sealed for this key, or for this context, or was changed
+ */
+export async function openSealed(privateKey, sealed, context) {
+    try {
+        const bytes = base64UrlDecode(sealed);
+        if (bytes.length <= POINT_BYTES + IV_BYTES)
+            return null;
+        const ephemeralPoint = bytes.subarray(0, POINT_BYTES);
+        const ephemeral = await globalThis.crypto.subtle.importKey('raw', ephemeralPoint, { name: 'ECDH', namedCurve: 'P-256' }, false, []);
+        const shared = await globalThis.crypto.subtle.deriveBits({ name: 'ECDH', public: ephemeral }, privateKey, 256);
+        const key = await sealKey(shared, ephemeralPoint, 'decrypt');
+        const plain = await globalThis.crypto.subtle.decrypt({
+            name: 'AES-GCM',
+            iv: bytes.subarray(POINT_BYTES, POINT_BYTES + IV_BYTES),
+            additionalData: utf8Encode(context),
+        }, key, bytes.subarray(POINT_BYTES + IV_BYTES));
+        return JSON.parse(utf8Decode(new Uint8Array(plain)));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=contact-key.js.map

package/dist/identity/contact-key.js.map

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