@weaveprotocol/core 0.2.0 → 0.2.2

package/README.md

@@ -4,6 +4,11 @@ A peer-to-peer data protocol for the browser. You own your identity as a
 written-down code, keep your data in signed records that sync directly between
 devices, and every app is a view onto that data rather than its owner.
 
+> **Building a client, or an agent that needs the architecture?** The
+> protocol is specified in [spec](spec/README.md): wire formats,
+> what is signed, and what every peer must check. The tests are its
+> executable half.
+
 ## Architecture
 
 ```
@@ -35,7 +40,7 @@ devices, and every app is a view onto that data rather than its owner.
 - **Local-first.** Works offline, syncs when peers are reachable.
 - **Few, boring dependencies.** Native browser APIs first. Where a problem is
   hard and already solved — elliptic-curve arithmetic, for one — a very stable,
-  widely used library instead of our own. See [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md).
+  widely used library instead of our own. See [CLAUDE.md](CLAUDE.md#dependencies).
 - **Isomorphic.** Runs in browsers, Node and Bun via `globalThis`.
 - **Functional.** Plain functions and frozen data, no class hierarchies.
 - **Standard Schema.** Bring your own validator (Zod, Valibot, ArkType, …).
@@ -220,7 +225,7 @@ await calls.answer(ringing.id);  calls.setMuted(true);  await calls.shareScreen(
   servers a relay hands out (see the relay, below), with passwords fresh for
   a while. A call asks for them when it starts.
 
-The messages, and the reasoning, are at the top of `src/calls/calls.ts`.
+The messages, and the reasoning, are at the top of `packages/core/src/calls/calls.ts`.
 
 ### Contacts
 
@@ -229,7 +234,7 @@ 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.
+strangers can knock on — unless you open a door (below).
 
 ```typescript
 // In a space you share with Anna — the book club — ask her to add you.
@@ -277,6 +282,50 @@ 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.
 
+### Doors
+
+Someone you share no space with can still ask to become your contact — if you
+give them a **door**. A door is a code you hand out on purpose (a link, a QR
+code, a line in your bio) and can close. It names a key derived from your
+contact key and the relays whose mailboxes hold knocks on it, and nothing
+about who you are.
+
+```typescript
+const door = await anna.doors.open();              // { id, code, relays, … }
+share(`https://chat.example/#door=${door.code}`);
+
+// Leif, who has never shared a space with Anna, pastes the link:
+await leif.doors.knock(link, { note: 'We met at the gig' });   // a space for two, its invite sealed to the door
+
+// Anna, whenever she's next online:
+const [knock] = await anna.doors.knocks();         // { from, name, note, pairSpace, … } — `from` is proven
+await anna.doors.accept(knock.id);                 // joins; Leif is a contact, and she is his once it syncs
+await anna.doors.close(door.id);                   // the code leads nowhere now; contacts stay
+```
+
+- **The relay keeps a mailbox**, the one thing it holds: a sealed blob under a
+  hash of the door's signing key, for up to 14 days. It sees addresses, as it
+  does for any socket, but not whose door it is, which account knocked, or what
+  they said. A door names up to three relays and a knock goes to all of them,
+  so no one relay can shut it.
+- **A knock proves who knocked** before anyone joins anything: it's signed by
+  the knocker's session key under a note for their whole account, like a
+  record, bound to the door it was left at and to when the relay took it.
+- **An answer proves who opened.** Accepting writes an answer in the space for
+  two, signed with the door's key: that, not joining, makes the owner the
+  knocker's contact, and the invite is closed behind them.
+- **The door is not the account.** Its key is not your contact key, so nobody
+  can link a door to your profile in any space. Every device with the contact
+  key opens the same doors.
+- **Spam** is capped at the mailbox (64 knocks a door; 4 a door and 30 in all
+  an hour from one address). `dismiss` lets one knock go without blocking,
+  blocking hides someone's knocks on every door, and a flooded door is cleared
+  by its owner (`clear`), so its code keeps working.
+
+Next: handles that lead to a door, so `@anna.bsky.social` works where a code
+does (planned in [07 — Doors](spec/07-doors.md), Names). The full design is
+[spec/07-doors.md](spec/07-doors.md).
+
 ## Signing in — the element, and React
 
 Getting to a node takes a sign-in flow: where the data lives (a pod or this
@@ -298,7 +347,7 @@ The protocol ships it, so an app does not write it:
 The element fits whatever it is put in — a page, a modal, a side panel — by
 sizing to its container, and draws nothing once someone is in. It renders into
 the page rather than a shadow root, because password managers fill forms there
-reliably and the account password living in one is the point. Colours, font and
+reliably and the everyday password living in one is much of the point. Colours, font and
 radius are custom properties (`--weave-accent`, `--weave-font`, …).
 
 Underneath it is `createWeaveAuth` (`@weaveprotocol/core/session`): the same flow as
@@ -354,10 +403,10 @@ An app connected to an account home passes its node instead:
 
 An app does not have to sign anyone in at all. It can ask an **account home** —
 a page, at an address the person chose, that holds their account — for access,
-and never see the seed. `home/` is one, ready to deploy as your own:
+and never see the seed. `apps/home/` is one, ready to deploy as your own:
 
-[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/leifriksheim/weave&base=home)
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/leifriksheim/weave&root-directory=home)
+[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/leifriksheim/weave&base=apps/home)
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/leifriksheim/weave&root-directory=apps/home)
 
 An app connects with `createWeaveConnection` — the twin of `createWeaveAuth`,
 for apps:
@@ -398,8 +447,8 @@ relays still meet. Underneath are
 
 1. The app makes its own key, kept in its own site's storage and never
    exportable (`appKey()`).
-2. The home opens in a popup. The person unlocks there — the account password
-   from their password manager, or a passkey — and picks which spaces the app
+2. The home opens in a popup. The person unlocks there — a passkey, or the
+   password their password manager keeps — and picks which spaces the app
    gets.
 3. The home signs a note from the account to the app's key: these spaces, read
    or change, for seven days. It hands the note back with invites for those
@@ -422,7 +471,7 @@ 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/home/README.md](apps/home/README.md).
 
 ### Apps hold what they use — keepers hold the rest
 
@@ -865,8 +914,8 @@ Browser-to-browser communication via WebRTC.
 
 #### Signaling relay
 
-`server/relay.mjs` is a dumb relay in a couple hundred lines of Node with no
-dependencies of its own. It runs on its own as `server/signaling-server.mjs`
+`packages/relay/relay.mjs` is a dumb relay in a couple hundred lines of Node with no
+dependencies of its own. It runs on its own as `packages/relay/signaling-server.mjs`
 (an HTTP server and the `ws` library around it), and inside every always-on
 node (`weave serve`), so the two are the same relay. A peer holds one socket and joins a room on it for
 each space, and the relay passes join notices and WebRTC offers, answers and
@@ -900,8 +949,8 @@ 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.
+The relay's Docker image (`packages/relay/`, deployed to Fly) runs coturn beside it when
+`TURN_SECRET` is set, already capped that way: `packages/relay/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.
@@ -1001,7 +1050,7 @@ interface StorageAdapter {
 - `createIndexedDBAdapter(name)` — works in every browser. Origin-scoped.
 - `createFolderAdapter(directory, namespace)` — a directory the user picked, via the File System Access API. **Not** origin-scoped. Chrome, Edge and Opera on the desktop.
 
-The always-on node (`weave run`) uses the folder adapter on disk, in the same layout. **Planned**: mirrors, which keep a space in storage the user already pays for (a Dropbox app folder, Drive, S3) and sync with it like a peer — see `docs/blocks/BLOCK-03-mirrors.md`. OPFS is not on the list: it is origin-private, so it would inherit exactly the limitation a data folder exists to avoid.
+The always-on node (`weave run`) uses the folder adapter on disk, in the same layout. **Planned**: mirrors, which keep a space in storage the user already pays for (a Dropbox app folder, Drive, S3) and sync with it like a peer — see [05 — Sync and storage](spec/05-sync-and-storage.md). OPFS is not on the list: it is origin-private, so it would inherit exactly the limitation a data folder exists to avoid.
 
 ### Data folders — storage that outlives the origin
 
@@ -1076,7 +1125,7 @@ const wrap = await wrapSeedWithDeviceKey(seed, deviceKey, { rpId, credentialId }
 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.
+`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 `packages/core/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 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.
 
@@ -1150,7 +1199,7 @@ Both sides of a new pair learn of each other at once, so the lower identifier
 offers and the other waits — otherwise every introduction would open two
 connections. After that the mesh introduces itself and the relay can go away.
 
-`server/` has a Dockerfile and a `fly.toml` for running one.
+`packages/relay/` has a Dockerfile and a `fly.toml` for running one.
 
 ### Pairing a phone
 
@@ -1234,11 +1283,11 @@ schema.registerCollection({ name: 'app.example.post', schema: PostSchema });
 
 ## Command line, always-on node, and agents
 
-`cli/` is `weave`: every node operation from a terminal, `weave run` to keep an
+`packages/cli/` is `weave`: every node operation from a terminal, `weave run` to keep an
 account's spaces syncing on a server (browsers connect to it over WebSocket, and
 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).
+[packages/cli/README.md](packages/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
@@ -1247,7 +1296,7 @@ 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
+The home knows nothing about payment ([06 — Nodes, sessions and apps](spec/06-nodes-and-sessions.md), Hosts): 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)`
@@ -1263,13 +1312,13 @@ has **Keep my spaces online**.
 
 ## Example app
 
-`example/` is the Weave website — a landing page for developers at `/`, and
+`apps/example/` is the Weave website — a landing page for developers at `/`, and
 why Weave, for people, at `/why` — and, at `/app`, a general-purpose app for your spaces — Vite + React, consuming
-the protocol straight from `src/`. It knows no kinds of data in advance: every
+the protocol straight from `packages/core/src/`. It knows no kinds of data in advance: every
 screen is worked out from what a space says about itself (see *Derived UI* below):
 
 ```bash
-npm install && (cd example && npm install) && (cd home && npm install)   # the CLI is a workspace: the first one installs it
+npm install     # one install for the whole workspace: core, CLI, relay and the apps
 npm run dev
 ```
 
@@ -1279,13 +1328,13 @@ That starts everything, with coloured output per part, and Ctrl-C stops it all:
 |---|---|---|
 | 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` |
+| node | port 8787 | An always-on node that is also the relay; a throwaway identity on first run (`packages/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 `packages/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
+`apps/example/.env.development` and `apps/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`.
+`packages/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
@@ -1297,8 +1346,8 @@ opens the host's pay page in a new tab. What you can pay with there:
   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
+  `WEAVE_WALLET_ADDRESS` in `packages/cli/.env.host.local`.
+- **A card, in Stripe's test mode.** In `packages/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`
@@ -1306,7 +1355,7 @@ opens the host's pay page in a new tab. What you can pay with there:
   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
+  `packages/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
@@ -1325,7 +1374,7 @@ npm run weave -- records list --space <id>
 
 Close every browser holding the space, open the link somewhere else, and the
 records come from the node. Or make the node your own account's — see
-[cli/README.md](cli/README.md) — and it serves every space you make, unasked.
+[packages/cli/README.md](packages/cli/README.md) — and it serves every space you make, unasked.
 
 Between them they exercise the stack end to end. At the home: choose where
 your data lives (a pod, or this browser), create an account (a password your
@@ -1353,7 +1402,7 @@ for fixed ones, and `x-choicesFrom: { rel: 'about', field: 'options' }` for a
 field that picks from a list in the linked record — so a vote stored as `1`
 shows as "Lisbon", its form offers the poll's options, and the poll shows a
 tally. The helpers that work this out are pure functions
-(`example/src/derive/schema-ui.ts`), with nothing DOM-specific in them. An
+(`apps/example/src/derive/schema-ui.ts`), with nothing DOM-specific in them. An
 empty space offers a small "define a collection" form; an agent can do the
 same over WebMCP.
 
@@ -1370,7 +1419,7 @@ above everything that changes as you move around.
 
 **Agents in the browser (WebMCP).** When `/app` loads, it registers
 every node operation as a WebMCP tool on `document.modelContext`
-(`example/src/webmcp.ts`, with `@mcp-b/webmcp-polyfill`: Chrome's own WebMCP
+(`apps/example/src/webmcp.ts`, with `@mcp-b/webmcp-polyfill`: Chrome's own WebMCP
 when present, a polyfill otherwise). A browser agent or extension sees the same
 tools as the CLI and `weave mcp` — `spaces_list`, `records_query`,
 `records_put`, `apps_propose`… — and works as the person, with nothing to
@@ -1381,8 +1430,7 @@ them. Anything that changes a space's people, or hands out its key, asks the
 person first. An app may bring its own screen: a collection definition's
 `screen`, one HTML document, which the example runs in a sandboxed frame with
 no network, talking to the space only through a message port
-(`createScreenBridge`, `apps_screen_guide`). `docs/screens/chess.html` is one
-an agent wrote.
+(`createScreenBridge`, `apps_screen_guide`).
 
 **Agents on your computer (Claude Code, Claude Desktop, Cursor).** "Connect an
 agent", in the account menu, shows one command:
@@ -1390,32 +1438,77 @@ agent", in the account menu, shows one command:
 the tab through the relay, and the person allows it at their account home,
 which signs an agent's note for the whole account, for as long as they chose.
 Everything said on the way is sealed with a key from the code, so the relay
-learns nothing (`src/session/agent-link.ts`). The command then adds `weave` to
+learns nothing (`packages/core/src/session/agent-link.ts`). The command then adds `weave` to
 the agents it finds, and they start `weave mcp` themselves: a node of its own,
 over WebRTC (`node-datachannel`), that follows the account and keeps working
 with every tab closed. What it writes shows "via agent", and every peer
 ignores an agent changing collections, who may do what, or the account's own
-list of spaces. See BLOCK-20.
+list of spaces. See [06 — Nodes, sessions and apps](spec/06-nodes-and-sessions.md), Agents.
+
+## Still to do in the library
+
+What the protocol still has planned is in [the spec](spec/README.md), under
+**Planned** in each part. Library work that isn't protocol:
+
+- **Typed queries, further.** Typed field paths and operator values in
+  `where`, a misspelled collection name as a compile error, typed link roles,
+  types generated from a space's stored definitions, and a dev-time warning
+  when declared schemas differ from the space's catalogue.
+- **Typed collections.** One TypeScript builder that emits the schema, the
+  rules and the types, and typed handles (`node.use(space, Poll)`).
+- **Definitions that update themselves.** `useSchemas` and `addApp` applying
+  harmless changes, with `differences()` in `packages/core/src/schemas/apps.ts` replaced by
+  the planned `compare` ([02](spec/02-records.md), compatible definitions).
+- **Web components** for the standard schemas.
+
+## Repository layout
+
+One npm workspace, installed once at the root (`npm install`):
+
+| Folder | Package | |
+|---|---|---|
+| `packages/core` | `@weaveprotocol/core` (published) | The protocol library, and its tests |
+| `packages/cli` | `@weaveprotocol/cli` (published) | `weave`: the always-on node, hosting, agents, MCP |
+| `packages/relay` | `@weaveprotocol/relay` (private) | The signaling relay and its mailbox, run alone on Fly and inside every node |
+| `apps/home` | — | The account home |
+| `apps/example` | — | The website and the example app |
+| `apps/extension` | — | The Chrome extension |
+| `spec` | — | The protocol specification |
+
+Everything imports the protocol by name, `@weaveprotocol/core`, and only
+through what it exports. Inside the workspace, the `@weaveprotocol/source`
+export condition resolves those imports to `packages/core/src`, so the apps,
+the CLI and the tests run on the source with no build step; published copies
+use `dist`. The CLI bundles the protocol and the relay into one file, so
+`npx @weaveprotocol/cli` and the single-file binaries need nothing else.
 
 ## Releasing
 
-`@weaveprotocol/core` (this folder) and `@weaveprotocol/cli` (`cli/`, an npm
-workspace) are released together, always with the same version:
+`@weaveprotocol/core` (`packages/core/`) and `@weaveprotocol/cli`
+(`packages/cli/`) are released together, always with the same version:
 
 ```bash
 npm run release
 ```
 
-It typechecks and runs the tests, then [bumpp](https://github.com/antfu-collective/bumpp)
+It checks you're logged in to npm first (and runs `npm login` if not),
+typechecks and runs the tests, then [bumpp](https://github.com/antfu-collective/bumpp)
 asks for the next version, writes it to both packages, and commits and tags
-it (`v0.1.2`). Both are published (each builds itself first: `dist/` for the
-core, one bundled file for the CLI), and only then is the commit pushed. The
-settings are in `bump.config.ts`.
+it (`v0.1.2`), locally. Both are published (each builds itself first: `dist/`
+for the core, one bundled file for the CLI), and only then are the commit and
+tag pushed.
+
+If a release stops partway — npm login, a one-time password, the network —
+fix it and run `npm run release` again. It sees the version isn't fully on npm
+yet and publishes what's missing, instead of bumping again. `npm run release
+-- --dry-run` does everything but publish and push. The script is
+`scripts/release.mjs`; bumpp's settings are in `bump.config.ts`.
 
 ## Tests
 
 ```bash
-npm test
+npm test        # every workspace: core's tests, then the CLI's
+npm run typecheck
 ```
 
 Covers key derivation — checked against the public keys Web Crypto generates

package/dist/doors/doors.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @module doors
+ * Doors: how someone you share no space with can ask to become your contact.
+ *
+ * A DID is a name, not an address — knowing it must not be enough to reach
+ * you. A **door** is an address you hand out on purpose, and can close:
+ *
+ * - a **door key**, derived from your contact key and the door's id
+ *   (`deriveDoorKeyBytes`), which says nothing about the account behind it,
+ *   and a **signing key** beside it (`deriveDoorSignKeyBytes`) that proves
+ *   ownership of the door — to a relay clearing its mailbox, and to a knocker
+ *   when you answer;
+ * - the **relays** whose mailboxes hold knocks on it — two or three, chosen by
+ *   you, so no one relay can shut it.
+ *
+ * Both travel in a **door code** (a link, a QR code, a line in a bio). Someone
+ * with it **knocks**: makes a private space for the two of you, and leaves its
+ * invite, sealed to the door key, in the door's mailboxes. The knock is signed
+ * by the knocker's session key under their account's note, like a record, so
+ * it proves who knocked before anyone joins anything. Opening the door is
+ * joining that space.
+ *
+ * ```
+ * code   = base64url(JSON { v: 1, key, sign, relays, name? })
+ * topic  = base64url(SHA-256("weave/door-topic/v1|" + sign))
+ * knock  = sealFor(key, { body, sig }, "weave/knock/v1|" + key)
+ * body   = { v: 1, door: key, from, name, invite, note?, at, session, proof }
+ * sig    = session key signs canonical(body)
+ * ```
+ *
+ * The relay sees a topic and a sealed blob: not whose door it is, not who
+ * knocked, not what they said. See `spec/07-doors.md`.
+ */
+import type { CryptoProvider } from '../types.js';
+/** A door names at most this many relays: enough that one going away doesn't matter */
+export declare const MAX_DOOR_RELAYS = 3;
+/** How long a knock waits in a mailbox, and so how old one may be when opened */
+export declare const KNOCK_TTL_SECONDS: number;
+/**
+ * How far a knock's own time may be from when the relay took it. A knock is
+ * dropped as soon as it is signed, so its time is checked against the relay's
+ * — which the knocker can't choose — and a note that ran out can't be used by
+ * dating a knock back to when it was good.
+ */
+export declare const KNOCK_DROP_WINDOW_SECONDS = 600;
+/** What a door code says: where to knock, and whose door the owner says it is */
+export interface DoorCode {
+    readonly v: 1;
+    /** The door key's public half: a compressed P-256 point, base64url. Knocks are sealed to it. */
+    readonly key: string;
+    /** The door's signing key's public half, likewise. Its hash is the door's topic. */
+    readonly sign: string;
+    /** Relays whose mailboxes hold knocks on it, 1–3 */
+    readonly relays: ReadonlyArray<string>;
+    /** Who the owner says they are — shown to the knocker, and proves nothing */
+    readonly name?: string;
+}
+/** What a knock carries, signed by the knocker's session key */
+export interface KnockBody {
+    readonly v: 1;
+    /** The door knocked on: its key. Binds the knock to this door. */
+    readonly door: string;
+    /** The knocker's account */
+    readonly from: string;
+    /** The name they give */
+    readonly name: string;
+    /** The invite to the space for two they made */
+    readonly invite: string;
+    readonly note?: string;
+    /** When it was signed, Unix seconds */
+    readonly at: number;
+    /** The session key that signed it */
+    readonly session: string;
+    /** The note from `from` to `session`: a UCAN whose chain ends at `from` */
+    readonly proof: string;
+}
+/** A knock that opened and checked out */
+export interface OpenedKnock {
+    readonly from: string;
+    readonly name: string;
+    readonly note?: string;
+    readonly invite: string;
+    /** The id of the space for two */
+    readonly pairSpace: string;
+    /** When it was signed, ms */
+    readonly at: number;
+}
+/** Cuts text to at most `max` characters without splitting one (a surrogate pair stays whole) */
+export declare function clip(text: string, max: number): string;
+/** Encodes a door code: what goes in a link or a QR code */
+export declare function encodeDoorCode(code: Omit<DoorCode, 'v'>): string;
+/**
+ * Reads a door code, or a link carrying one after `#door=` or `door=`.
+ * @throws When it isn't one, saying why
+ */
+export declare function parseDoorCode(text: string): DoorCode;
+/** Why a value is not a door code, or null */
+export declare function checkDoorCode(value: unknown): string | null;
+/**
+ * The mailbox topic of a door: a hash of its signing key. The relay can't tell
+ * whose door it is, and can check that whoever clears it holds that key.
+ */
+export declare function doorTopic(sign: string): Promise<string>;
+/**
+ * What a door's owner signs to clear knocks from a relay's mailbox: the topic,
+ * the relay's one-time challenge, and which knocks (`*` for all of them).
+ */
+export declare const purgeMessage: (topic: string, nonce: string, ids: ReadonlyArray<string> | null) => Uint8Array<ArrayBufferLike>;
+/** Signs a relay's purge challenge with the door's signing key */
+export declare function signPurge(signKey: Uint8Array, topic: string, nonce: string, ids: ReadonlyArray<string> | null): Promise<string>;
+export declare function signAnswer(signKey: Uint8Array, pairSpace: string, did: string): Promise<string>;
+export declare function checkAnswer(sign: string, pairSpace: string, did: string, signature: string): Promise<boolean>;
+/** A knock's id: the hash of its sealed blob, as relays file it */
+export declare function knockId(blob: string): Promise<string>;
+/**
+ * Makes a knock: the body, signed by the session key, sealed to the door key.
+ * @returns The sealed blob, for relays' mailboxes
+ */
+export declare function sealKnock(door: string, knock: {
+    readonly from: string;
+    readonly name: string;
+    readonly invite: string;
+    readonly note?: string;
+}, session: {
+    readonly did: string;
+    readonly key: CryptoKey;
+    readonly proof: string;
+}, provider: CryptoProvider): Promise<string>;
+/**
+ * Opens a knock left on a door, and checks it through: sealed to this door;
+ * signed by a session key that its account's note vouches for, for the whole
+ * account and not by an agent; signed when the relay took it; recent; and
+ * carrying an invite to a private space that account made.
+ * @param doorKey The door key's private scalar (`deriveDoorKeyBytes`)
+ * @param receivedAt When the relay took it, ms, as `fetch` says
+ * @returns The knock, or null when it is anything less
+ */
+export declare function openKnock(doorKey: Uint8Array, blob: string, receivedAt: number, provider: CryptoProvider): Promise<OpenedKnock | null>;
+//# sourceMappingURL=doors.d.ts.map

package/dist/doors/doors.d.ts.map

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