@decentnetwork/beagle-service 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,721 @@
-# Temporary Holding Version
+# @decentnetwork/beagle-service
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The web backend for a site whose users sign in with their Beagle identity.
+
+A visitor's identity is a key pair made on their own device; the `userid` is the public key. Your site learns who
+they are from a signature, keeps its own record of them, and can talk to them through its own Carrier identity.
+There is no account server and no provider in the middle: any site can do this, and every key is an equal identity.
+
+Three parts. Use the first alone, or all three:
+
+| Part | What it does |
+|---|---|
+| [`auth`](#1-auth-sign-in-on-the-server) | Sign in with Beagle on the server: nonce, exact origin check, both assertions, a launch replay store that survives a restart, sessions with expiry and logout, routes for `node:http`, Express and Next.js. |
+| [`users`](#2-users-visitor-registered-blocked) | One record per userid: `visitor`, `registered` or `blocked`. Registration fields you choose, a limit for visitors who never register, a blacklist, a JSON-file store and an adapter interface. |
+| [`agent`](#3-agent-the-sites-own-carrier-identity) | The site's own Carrier identity, in your process: who may become a friend, requests kept on disk, friend requests from your side, a persistent outbox, incoming messages with the sender's record. |
+
+```bash
+npm install @decentnetwork/beagle-service        # Node 20+, import or require, MIT, types included
+```
+
+Coming from 0.1.0? See [Upgrading from 0.1.0](#upgrading-from-010): no code has to change.
+
+The browser side is [`@decentnetwork/beagle-connect`](https://www.npmjs.com/package/@decentnetwork/beagle-connect)
+(`signIn`, `readLaunch`, `addFriend`). This package is the server those calls talk to.
+
+## Quick start
+
+```js
+import http from "node:http";
+import { createBeagleService } from "@decentnetwork/beagle-service";
+
+const svc = await createBeagleService({
+  origins: ["https://your.app"],                       // exact: scheme, host, port
+  dataDir: "./data",
+  register: { required: ["email"], optional: ["phone", "location"] },
+  visitor: { maxDays: 14, then: "refuse" },
+  agent: {                                             // omit if the site only needs sign-in
+    nickname: "Your App",
+    accept: "signed-in",
+    befriendOn: "register",
+  },
+});
+
+http.createServer(svc.nodeHandler({ prefix: "/api/auth" })).listen(3000);
+
+svc.agent.onMessage(({ user, reply }) => reply(`hello ${user?.name ?? ""}`));
+await svc.users.block(userid, "spam");
+```
+
+A complete site in one file, with its page: [`examples/minimal-site`](examples/minimal-site).
+A CommonJS Next.js site that also has NextAuth: [`examples/next-pages-cjs`](examples/next-pages-cjs).
+
+### From CommonJS
+
+```js
+const { createBeagleService, sharedBeagleService, load } = require("@decentnetwork/beagle-service");
+```
+
+`require` gives the three functions a site starts from. The library itself is an ES module (so are the two packages
+it checks signatures with), which is why everything else comes through one more call:
+`const { createUsers, jsonFileStateStore } = await load();`. That is the same module `import` gives; there is one copy
+of the library in the process whichever way it was loaded. TypeScript reads the CommonJS declarations from 5.3 on.
+
+---
+
+## 1. `auth`: sign-in on the server
+
+### Routes
+
+Mounted under a prefix (default `/api/auth`). All answers are JSON; errors are `{ ok: false, error, message }`.
+
+| Route | Body | Answers |
+|---|---|---|
+| `GET /nonce` | | `{ nonce, expiresIn: 120 }` |
+| `POST /sign-in` (also `/beagle`) | what `signIn()` resolved: `{ userid, nonce, sig, address, name, avatar, uiOrigin }` | `{ user, registration, expiresAt, agent? }` and the session |
+| `POST /launch` (also `/beagle-launch`) | what `readLaunch()` returned: `{ userid, ts, sig, address, name, punkId }` | the same |
+| `GET /me` | | `{ user, registration, agent? }`, or 401 |
+| `POST /logout` | | `{ ok: true }`; the token is revoked, not only the cookie cleared |
+| `POST /register` | `{ profile: { email: "…" } }` | `{ user, registration }`, or 400 `invalid-fields` with `fields: { email: "required" }` |
+
+The page side, with `beagle-connect`:
+
+```js
+import { signIn, readLaunch } from "@decentnetwork/beagle-connect";
+
+const launch = await readLaunch();                      // arrived from Beagle's Apps tab?
+if (launch) await post("/api/auth/launch", launch);
+
+button.onclick = async () => {
+  const win = window.open("about:blank", "beagle-connect", "width=420,height=560");   // inside the click
+  const { nonce } = await (await fetch("/api/auth/nonce")).json();
+  const who = await signIn({ nonce, existingWindow: win });
+  await post("/api/auth/sign-in", who);
+};
+```
+
+### What is checked
+
+- **Origin**: the request's `Origin` header (set by the browser, not by page script) against your exact list.
+  No suffix matching, no wildcard, never an origin from the body. `http://localhost:3000` counts only if you list it.
+  A malformed entry in `origins` (a bare hostname, a path, a `*`) throws at start.
+- **Nonce**: single use, 120 s. A nonce carries its expiry and the server's MAC, so issuing one stores nothing. It is
+  spent by the sign-in that verifies, and recorded in the state store then, so it stays spent across a restart. A
+  request whose signature does not verify writes nothing: nobody without a key can grow the used list, or use up a
+  nonce a visitor still holds. Of two requests with the same valid assertion, one signs in.
+- **Rate limit** on `sign-in` and `launch`, on by default: 30 attempts a minute from one address and 600 a minute
+  from everybody, then 429 `rate-limited` with `Retry-After`. See [`rateLimit`](#rate-limit).
+- **`decent-auth` and `decent-launch`** are verified with `beagle-connect`'s `verifySignIn` / `verifyLaunch`
+  (XEdDSA over the X25519 identity key). The two prefixes differ, so a launch assertion never signs in, nor the reverse.
+- **Launch**: `ts` within ±120 s, then the signature, then replay, last, so a forged repeat cannot burn an assertion a
+  real visitor still holds. The replay store is on disk and is written before the answer goes out. It is keyed on what
+  was signed (userid, origin, `ts`), not on the signature's bytes: the same assertion with its hex in another case, or
+  any second signature over the same message, is a repeat too.
+- **POST from a cookie session** must come from a listed origin (or carry a bearer token).
+
+### Sessions
+
+A signed token with the expiry inside it (`ttlDays`, default 30) and a session id. By default it is a cookie:
+`HttpOnly; Secure; SameSite=Lax`. `Secure` is left off only for an `http://` origin you listed yourself (a localhost
+during development). With `session: { transport: "bearer" }` the token is returned in the sign-in answer and sent back
+as `Authorization: Bearer …` (for an API on another origin than the page); `"both"` does both. CORS headers are sent
+for the listed origins only.
+
+Logout revokes the session id until the token would have expired. Blocking a user, or `users.revokeSessions(userid)`,
+ends every session of that user.
+
+### In your own routes
+
+```js
+const who = await svc.auth.authenticate(req);           // any object with `headers`
+if (!who.ok) return send(res, who.status, { error: who.error });   // 401 not-signed-in, 403 blocked / register-required
+who.user;            // the full record
+who.registration;    // { status, missing, due, refused, … }
+```
+
+**Reading a session is asynchronous**, and `authenticate()` never throws and never rejects. No session, a bad one, a
+blocked user and a store that could not be read all come back as `ok: false` with a status (the last is 500
+`server-error`). Decide on `who.ok` and on nothing else. Code that wraps the call in `try { … } catch { /* treat as
+public */ }`, or that forgets the `await` and tests the promise, would be deciding without knowing who asks, and a
+private page would be served to anybody.
+
+Options, all off unless given:
+
+| `authenticate(req, { … })` | |
+|---|---|
+| `allowUnregistered: true` | lets a visitor past the limit through (the register route uses it) |
+| `touch: false` | read only. By default the call notes the user's activity (`lastSeen`, `visits`): one write to the users store per user, at most once a minute, however many requests arrive. `session: { touch: false }` turns that off for every call; the visitor limit by `maxVisits` then counts sign-ins only. |
+| `checkOrigin: true` | for your routes that change something: a session that came in a **cookie** is accepted only when the request's `Origin` header is on your list (else 403 `origin-not-allowed`), the same rule the library applies to its own `logout` and `register`. A bearer token needs no `Origin`. When `req.method` is GET, HEAD or OPTIONS nothing is checked, so the option can be passed on every call. |
+
+### Your part of a sign-in
+
+```js
+onSignIn: async (user, { origin, door, route, first, request }) => {
+  await permits.refresh(user.userid);                       // awaited before the answer goes out
+  if (await banned(user.userid)) return { refuse: "no-permit", status: 403, message: "A permit is needed." };
+  return { role: await roleOf(user.userid) };              // added to the sign-in answer
+},
+```
+
+`onSignIn` runs after the assertion is verified and the user record is written, and before the session is issued.
+It gets the user, the `origin` that was signed for, the `door` (the Beagle that answered, or `"launch"`), the `route`
+(`"sign-in"` or `"launch"`), whether this is the userid's `first` sign-in, and the `request` (`request.raw` is the
+framework's own request object). An object it returns is merged into the answer; the library's own fields (`ok`,
+`user`, `registration`, `expiresAt`, `token`, `agent`) are not replaced. `{ refuse }` refuses: no session is issued
+and the page gets your `error` code. If the hook throws, the sign-in answers 500 and no session is issued. A refused
+sign-in still leaves the user record, with the sign-in counted.
+
+### Origins that change while the server runs
+
+```js
+origins: () => ["https://your.app", `http://${currentLanAddress()}:3000`],   // asked on each request; keep it cheap
+svc.auth.setOrigins(["https://your.app", "https://new.your.app"]);           // or set it from outside
+svc.auth.origins();                                                         // the list in force
+```
+
+Used nonces, used launch assertions and sessions are not touched by a change. A malformed entry throws when the
+service is created and from `setOrigins()`; if the function returns one later, it is logged and the last good list
+stays in force.
+
+### Rate limit
+
+```js
+rateLimit: { perClient: 30, total: 600, windowSeconds: 60 }    // the defaults
+rateLimit: { trustProxy: true }                                // one proxy in front: take the address from X-Forwarded-For
+rateLimit: { key: (request) => request.headers["cf-connecting-ip"] }
+rateLimit: false
+```
+
+Counted in memory, per server process, for `sign-in` and `launch` together. The client is the connection's address
+(`req.ip` under Express). A connection from the machine itself, which is what a reverse proxy on the same host looks
+like, is not a client: it counts against `total` only, until you set `trustProxy` or `key`. The same goes for a
+request you pass to `handlers.*` yourself without an `ip`.
+
+### A script that signs in
+
+A browser adds the `Origin` header by itself; a script has to send it. The server takes the origin from that header
+only, never from the body. Name the site's own origin in the header and in the string that is signed:
+
+```js
+const { nonce } = await (await fetch(`${site}/api/auth/nonce`)).json();
+const sig = Buffer.from(signDetached(secretKey, new TextEncoder().encode(`decent-auth\n${site}\n${nonce}`))).toString("hex");
+const res = await fetch(`${site}/api/auth/sign-in`, { method: "POST", headers, body: JSON.stringify({ userid, nonce, sig }) });
+```
+
+with `headers = { Origin: site, "content-type": "application/json" }` and `signDetached` from `@decentnetwork/peer`.
+Without `Origin` the answer is 403 `origin-not-allowed`. The whole script:
+[`examples/sign-in-from-script.mjs`](examples/sign-in-from-script.mjs).
+
+### Several servers
+
+One `sessionSecret` on all of them makes a session from one valid on the others. What is used once, and what a
+sign-out reaches, depends on the `state` store:
+
+| | A nonce is used once | A launch assertion is used once | A sign-out is known |
+|---|---|---|---|
+| a shared `state` store | overall | overall | on every server |
+| separate stores, `serverId` set on each | overall: only the server that issued it accepts it | per server, within its two minutes | on the server where it happened |
+| separate stores, no `serverId` | per server | per server, within its two minutes | on the server where it happened |
+
+`serverId: "eu-1"` is for servers that cannot reach a common database. It goes into the nonce's MAC and nowhere
+else, so the page has to post the sign-in to the server it got the nonce from. Blocking is per users store: with
+separate stores, block on each.
+
+### Frameworks
+
+```js
+// node:http
+http.createServer(svc.nodeHandler({ prefix: "/api/auth" }));
+
+// Express: other paths go to next()
+app.use(svc.expressHandler({ prefix: "/api/auth" }));
+
+// One route as a (req, res) handler, on whatever path you mount it
+app.post("/login/beagle", svc.route("signIn"));         // nonce, signIn, launch, me, logout, register
+
+// Anything else
+const { status, headers, body } = await svc.handle({ method, path: "/sign-in", headers, body, ip });
+await svc.handlers.signIn({ method, headers, body, ip });
+```
+
+Request bodies are JSON and at most 64 KB. The routes answer; they do not throw at the code that called them.
+
+### Next.js
+
+One service for the whole server, in `lib/beagle.js`. `sharedBeagleService` returns at once, creates the service on
+first use, and is the same service for every caller in the process: Next.js bundles pages, API routes and
+`instrumentation.js` apart and may evaluate this file more than once.
+
+```js
+// lib/beagle.js: CommonJS shown; with ES modules, `import { sharedBeagleService } from …` and `export const beagle`
+const { sharedBeagleService } = require("@decentnetwork/beagle-service");
+
+const beagle = sharedBeagleService(() => ({
+  origins: process.env.BEAGLE_ORIGINS.split(","),
+  dataDir: "./data",
+}));
+module.exports = { beagle };
+```
+
+`beagle.route(name)`, `beagle.authenticate(req, opts)`, `beagle.nextApiHandler()`, `beagle.fetchHandler()` and
+`beagle.handle()` work like the service's own and never throw: while the service cannot start (a malformed origin),
+the routes answer 500 `server-error` and `authenticate` answers `ok: false`. A failed start is not kept; it is tried
+again (at most every 5 s, `retryMs`), so a rejected promise does not sit on `globalThis` for the life of the
+process. `await beagle.ready()` gives the service itself (`users`, `auth`, `agent`), and rejects with the reason
+when it cannot be created.
+
+**Find a wrong configuration at start.** Nothing in a Next.js site runs before the first request unless you say so:
+
+```js
+// instrumentation.js (Next.js 15; next to pages/)
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+  await require("./lib/beagle").beagle.ready();
+}
+```
+
+With a bad entry in `origins`, `next start` then prints the reason at once ("Failed to prepare server … is not an
+exact origin") and answers 500 to every request, instead of failing the first sign-in.
+
+**A site that already has NextAuth** has `pages/api/auth/[...nextauth].js`, and two catch-all routes in one directory
+do not build. Give each Beagle route its own file beside it; a named file wins over the catch-all, and none of these
+names is one of NextAuth's:
+
+```js
+// pages/api/auth/sign-in.js   (and nonce.js, launch.js, me.js, logout.js, register.js; any file names you like)
+const { beagle } = require("../../../lib/beagle");
+export default beagle.route("signIn");
+```
+
+`route(name)` is `handlers[name]` with the request read and the answer written for you. When a route of yours has
+to do more than that, call the handler itself and send what it returns:
+`const { status, headers, body } = await (await beagle.ready()).handlers.signIn({ method: req.method, headers: req.headers, body: req.body, ip })`.
+For the usual reason to do that, adding the site's fields to a sign-in, use [`onSignIn`](#your-part-of-a-sign-in).
+
+**A site with no catch-all under `/api/auth`** can use one file instead:
+
+```js
+// pages/api/auth/[...beagle].js
+const { beagle } = require("../../../lib/beagle");
+export default beagle.nextApiHandler({ prefix: "/api/auth" });
+
+// App Router (or any Web Request/Response host): app/api/auth/[...beagle]/route.js
+const handler = beagle.fetchHandler({ prefix: "/api/auth" });
+export { handler as GET, handler as POST, handler as OPTIONS };
+```
+
+In your own API routes and in `getServerSideProps`:
+
+```js
+const who = await beagle.authenticate(req, { checkOrigin: true });
+if (!who.ok) return res.status(who.status).json({ error: who.error });
+```
+
+All of this, built with `next build` and run with `next start`: [`examples/next-pages-cjs`](examples/next-pages-cjs).
+
+The pieces are also there on their own: `svc.auth.issueNonce()`, `verifySignIn(origin, body)`,
+`verifyLaunch(origin, body)`, `mintSession(userid)`, `readToken(token)`, `revoke(token)`, `cookie(token, origin)`.
+
+---
+
+## 2. `users`: visitor, registered, blocked
+
+One record per userid, created at the first sign-in:
+
+```js
+{
+  userid, address, name, avatar, punkId,      // address/name/avatar/punkId are unsigned hints from the visitor's Beagle
+  door,                                        // which Beagle answered: its origin, or "launch"
+  origin,                                      // the origin of your page the last sign-in was signed for
+  status,                                      // "visitor" | "registered" | "blocked"
+  profile: { email: "…" },                     // your registration fields
+  firstSeen, lastSeen, visits, signIns, registeredAt,
+  blocked: { at, why, was },                   // while blocked
+}
+```
+
+`address` is stored only when it parses as a Carrier address of that userid, and a blank or wrong hint never replaces
+one already held: it is what a friend request needs, and no later sign-in is sure to carry it.
+
+**An update merges.** `svc.users.update(userid, { plan: "paid", profile: { resume: "cv.pdf" } })` changes those keys
+and keeps every other field, including fields this library has never heard of. Sign-in, registration, block and
+unblock all work the same way; nothing rebuilds a record from a fixed list. The routes return only the library's own
+fields as `user`; pass `publicUser: (user) => ({ … })` to choose what the page sees.
+
+### Registration is your choice
+
+```js
+register: { required: [], optional: [] }                          // default: every visitor is a user at once
+register: { required: ["email"] }
+register: { required: ["email", "phone", "location"], optional: ["company"] }
+```
+
+A visitor who has given every required field is `registered`. `POST /register` checks and stores the fields; it
+answers 400 `invalid-fields` and stores nothing when a required field is missing or a field is refused. `email` and
+`phone` get a loose shape check. Anything stricter is yours:
+
+```js
+register: {
+  required: ["email"],
+  // true accepts, false or a string refuses (the string goes to the page), { value } stores a normalised value.
+  verify: async (field, value, user, submitted) => {
+    if (field !== "email") return true;
+    if (await codes.matches(user.userid, value, submitted.emailCode)) return { value: value.toLowerCase() };
+    await mailer.sendCode(user.userid, value);        // sending the email or SMS is your part
+    return "confirmation-code-needed";
+  },
+}
+```
+
+If you add a required field later, users who lack it are visitors again at their next sign-in.
+
+### The visitor limit
+
+```js
+visitor: { maxDays: 14, maxVisits: 10, then: "ask" }   // or then: "refuse"
+```
+
+Past either limit a visitor's `registration.due` is true. With `"ask"` the site keeps answering and the page shows
+its form. With `"refuse"`, `/me` and `authenticate()` answer 403 `register-required` until they register. The sign-in
+answer is 403 too, and still carries a session: without one they could not prove who is registering. That session
+opens `register` and `logout` only.
+
+A visit is a burst of activity; 30 minutes of silence (`visitGapMinutes`) ends it.
+
+### The blacklist
+
+```js
+await svc.users.block(userid, "spam");     // also works before the userid has ever signed in
+await svc.users.unblock(userid);
+await svc.users.list({ status: "blocked" });
+```
+
+A blocked userid is refused at sign-in and launch (403 `blocked`), its sessions stop working at once, and the agent
+refuses its friend requests, removes it as a friend and drops what was queued for it. After `unblock` they sign in
+again.
+
+### Events
+
+```js
+svc.users.on("sign-in", (user, { first, door, origin }) => {});   // origin: the one that was signed for
+svc.users.on("registered", (user) => {});     // also fires at first sign-in when nothing is required
+svc.users.on("blocked", (user) => {});
+svc.users.on("unblocked", (user) => {});
+```
+
+Events are not awaited: the answer does not wait for a listener. For something that must happen before the sign-in
+answer goes out, use [`onSignIn`](#your-part-of-a-sign-in).
+
+### The operator's command
+
+```bash
+npx beagle-service users list [--status blocked] [--json]
+npx beagle-service users show    <userid>
+npx beagle-service users block   <userid> [why…]
+npx beagle-service users unblock <userid>
+```
+
+Run it in the site's directory, beside the running server; `--data <dir>` names the `dataDir` when it is not
+`./data`. With the default file store a block takes effect at once, on sign-in and on every session that userid
+holds, with no restart: the server reads the file again when it was replaced.
+
+For a site with its own `store`, put a `beagle-service.config.js` (or `.cjs`, `.mjs`) in that directory, or name one
+with `--config <file>`. It exports what the site passes to the library: `{ store, register, visitor }`, or a
+function that returns it, or `{ users }` for a `users` object the site built itself:
+
+```js
+// beagle-service.config.js
+module.exports = { store: require("./lib/users-store"), register: { required: ["email"] } };
+```
+
+### Storage
+
+The default is `<dataDir>/users.json`, rewritten atomically (temp file, fsync, rename) on every change and held in
+memory: right for one machine and up to some tens of thousands of users. A file that does not parse stops the start
+instead of being treated as empty. The file is read again when another writer replaced it, and a change is made
+under a lock file on the record that is on disk at that moment, field by field. So the operator's command, a script,
+or a second server process on the same directory can work beside the server, and two updates to different fields of
+one record at the same moment both survive.
+
+For Postgres, sqlite or anything else, implement three calls:
+
+```js
+const store = {
+  get:  async (userid) => row ?? null,
+  put:  async (user, change) => { /* see below */ },
+  list: async () => rows,
+};
+await createBeagleService({ origins, store });
+```
+
+`put` gets the whole record, and as a second argument what this write changed:
+`{ prev, set: { field: value, … }, unset: ["field", …] }`, top-level fields, with `prev` the record as the library
+read it (`null` for a new one). There are two ways to write a `put`, and both are correct:
+
+- **Store the whole record** and ignore `change` (every adapter written for 0.1.0 does). Right when nothing but
+  the library writes those records between its read and its write. When `get` and `put` are synchronous, the library
+  calls them in the same turn of the event loop with nothing in between, so other code in the same process cannot
+  get in between either.
+- **Store what changed**: set the fields in `change.set`, remove those in `change.unset`, insert `user` when there is
+  no row. Do this when other code or other processes write the same rows (`UPDATE … SET col = …` for the changed
+  columns, or `data = data || $set` for a JSON column). A field somebody else wrote since the library's read is then
+  not written back from an old copy. `applyUserChange(row, change)` is that merge for a plain object.
+
+**The minimum a store may return** from `get` and `list` is an object with the `userid`: `{ userid }`. A record that
+is older than the library, or that another program wrote, is fine. Fields the library needs and does not find are
+filled in when it reads (`status: "visitor"`, `profile: {}`, `visits: 0`, `signIns: 0`, `null` for the rest), in
+memory only; every other field passes through untouched and is kept on every write.
+
+Used nonces, used launch assertions and revoked sessions live in a second small store (`<dataDir>/state.json` by
+default, shared the same way between processes on one machine). With servers on more than one machine, put it in
+the shared database too and set one `sessionSecret`; when they cannot share one, see
+[Several servers](#several-servers):
+
+```js
+const state = {
+  addOnce: async (ns, key, expiresAt) => /* true if inserted, false if (ns, key) was already there */,
+  has:     async (ns, key) => /* true if there and not expired */,
+};
+```
+
+### Published profiles
+
+`importProfile: true` reads the userid's `beagles.eth` record after sign-in
+(`GET <gateway>/getAddress/<userid>`, cached for 24 h) and stores it under `user.published`
+(`name`, `displayName`, `description`, `avatar`, `url`, `owner`). A record proves only what its owner signed.
+
+---
+
+## 3. `agent`: the site's own Carrier identity
+
+One identity for the site's role, held in your process with `@decentnetwork/peer`. People add it like any contact;
+nothing is delivered either way before a friend request is accepted. The key is created on first start in
+`<dataDir>/agent/peer.save`: back it up, it *is* the identity.
+
+```js
+svc.agent.userid; svc.agent.address;      // show the address on your site; the routes return it as `agent`
+await svc.agent.ready;                    // joined the network (sign-in does not wait for this)
+```
+
+### Who may become a friend
+
+| `accept` | A friend request is accepted when |
+|---|---|
+| `"all"` | always |
+| `"signed-in"` (default) | the userid has signed in on the site |
+| `"registered"` | the user's status is `registered` |
+| `"manual"` | you call `svc.agent.accept(userid)` |
+| `(request, user) => …` | it returns `true`; `false` holds the request, `"reject"` refuses it |
+
+A blocked userid is always refused. A request from someone who does not qualify yet is **held on disk** and accepted
+the moment they sign in, register or are unblocked; a restart loses none. Held requests are dropped after `holdDays`
+(default 7). `svc.agent.pending()` lists them; `accept(userid)` / `reject(userid)` answer one by hand.
+
+### Friend requests from your side
+
+```js
+befriendOn: "register"                    // or "sign-in", or "never" (default)
+await svc.agent.befriend(userid);         // → { ok: true, how: "requested" | "accepted" | "already-friends" | "already-asked" }
+```
+
+The request goes to the user's stored `address` (a userid alone is not enough to send one). Each user is asked once;
+`{ force: true }` asks again. If they had already asked, their request is accepted instead.
+
+### Sending
+
+```js
+const receipt = await svc.agent.send(userid, "Your order shipped.");
+// { id, deliveryIds: ["bs-…-0"], state: "queued" }
+svc.agent.on("delivered", ({ deliveryId, to, via, confirmed }) => {});
+svc.agent.on("dead-letter", ({ why, item }) => {});
+```
+
+`send` resolves when the message is on disk (`<dataDir>/agent/outbox.json`); delivery starts on the next turn of the
+event loop.
+
+- The `deliveryId` is fixed when the message is queued. A retry, a second road or a send repeated after a crash
+  carries the same id. Whether the friend's client sees it is decided by the peer: it wraps a text in the
+  id-carrying envelope only for a friend whose protocol version it has learned (2 or more, from the profile the
+  friend's client sends when a session comes up). Such a friend shows a repeated message once. For any other
+  friend (a phone app, or a client whose profile has not arrived yet) the text goes out plain and the id is your
+  own handle for the message.
+- A session that has just proven itself (something arrived from the friend in the last 15 s) gets the message live,
+  with 4 s for the confirmation. Otherwise, or when no confirmation comes, it is posted to an Express node at once
+  (`sendTextViaExpress`) and the friend collects it when they are back. `via` says which road took it; `confirmed` is
+  true only for a live delivery the friend's side acknowledged.
+- When neither road takes it, the message waits: 5 s, 10 s, 20 s … up to 10 minutes between tries. A queue is per
+  recipient: one unreachable friend never holds up another, and one recipient's messages keep their order.
+- A message to someone with a friend request still open waits for the acceptance.
+- Dead letters (`<dataDir>/agent/dead-letter.jsonl`): `not-a-friend` (no friendship and no request open),
+  `bad-address` (not a userid), `blocked`, `expired` (`maxQueueHours`, default 72).
+- A text over one message (about 700 bytes of UTF-8) is split at line breaks or spaces; each part has its own
+  `deliveryId`.
+
+### Receiving
+
+```js
+svc.agent.onMessage(async ({ userid, user, text, deliveryId, via, reply }) => {
+  if (user?.status !== "registered") return reply("Please register on the site first.");
+  await reply(await answer(user, text));
+});
+```
+
+`user` is the sender's record, or `null` for a friend who never signed in (possible under `accept: "all"` or a
+function). Act on `userid`, the key the message came from, never on a userid written in the text. Messages from a
+blocked userid are not delivered to the handler.
+
+### Other
+
+`svc.agent.isFriend(userid)`, `unfriend(userid)`, `outbox()`, `deadLetters()`, and events `request-held`,
+`friend-accepted`, `friend-refused`, `friend-removed`. For what this library leaves out (files, calls, groups), the
+underlying peer is `svc.agent.peer`. `await svc.close()` stops the agent.
+
+Bootstrap and Express nodes come from the public list the Beagle apps read (`DEFAULT_SERVERS_URL`); the last good
+copy is kept on disk so a restart works while that URL is down. Pass `agent.servers` (a URL in the same format, or
+`{ bootstrapNodes, expressNodes }`) to use your own. Without an Express node there is no offline delivery.
+
+---
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `origins` | required | Exact origins of your pages: a list, or a function that returns the list as it is now. |
+| `dataDir` | `"./data"` | Where the library keeps its files. |
+| `store` | `<dataDir>/users.json` | Users backend (`get`, `put`, `list`). |
+| `state` | `<dataDir>/state.json` | Replay and revocation backend (`addOnce`, `has`). |
+| `sessionSecret` | generated into `<dataDir>/session-secret` | Signs sessions and nonces. Set it when several processes share users. |
+| `serverId` | none | Names this server among several with one secret and separate `state` stores: a nonce is accepted only where it was issued. |
+| `onSignIn` | none | `(user, { origin, door, route, first, request }) => fields \| { refuse }`, awaited before the sign-in answer. |
+| `rateLimit` | on | `false`, or `{ perClient, total, windowSeconds, trustProxy, key }` for `sign-in` and `launch`. |
+| `rateLimit.perClient`, `total` | `30`, `600` | Attempts per window from one address, and from everybody. |
+| `rateLimit.windowSeconds` | `60` | |
+| `rateLimit.trustProxy` | `false` | `true` (one proxy) or a number: take the address from `X-Forwarded-For`. |
+| `rateLimit.key` | the connection's address | `(request) => string \| null`: name the client yourself. |
+| `session.ttlDays` | `30` | Session lifetime. |
+| `session.transport` | `"cookie"` | `"cookie"`, `"bearer"` or `"both"`. |
+| `session.cookieName` | `"beagle_session"` | |
+| `session.sameSite` | `"Lax"` | `"Lax"`, `"Strict"` or `"None"`. |
+| `session.cookieDomain`, `session.cookiePath` | none, `"/"` | |
+| `session.touch` | `true` | `authenticate()` notes activity: at most one users write per user per minute. `false`: it only reads. |
+| `register.required` | `[]` | Fields a visitor must give to be `registered`. Empty: registered at once. |
+| `register.optional` | `[]` | Fields the register route also stores. |
+| `register.verify` | none | `(field, value, user, submitted) => true \| false \| "reason" \| { value }`. |
+| `visitor.maxDays` | none | Days a visitor may stay unregistered. |
+| `visitor.maxVisits` | none | Visits a visitor may make unregistered. |
+| `visitor.then` | `"ask"` | `"ask"` or `"refuse"` (403 `register-required`). |
+| `visitor.visitGapMinutes` | `30` | Silence that separates two visits. |
+| `importProfile` | `false` | `true`, or `{ gateway, ttlHours }`. |
+| `publicUser` | library fields only | What the routes return as `user`. |
+| `agent` | none | The site's Carrier identity; omit for sign-in only. |
+| `agent.keyFile` | `<dataDir>/agent/peer.save` | The identity's key. |
+| `agent.nickname`, `statusMessage`, `punkId`, `avatarUrl` | none | The agent's profile; it is advertised with `platform: "agent"`. |
+| `agent.accept` | `"signed-in"` | `"all"`, `"signed-in"`, `"registered"`, `"manual"` or a function. |
+| `agent.befriendOn` | `"never"` | `"sign-in"`, `"register"` or `"never"`. |
+| `agent.hello` | the nickname | Greeting in friend requests the agent sends. |
+| `agent.holdDays` | `7` | How long an unanswered request is kept. |
+| `agent.maxQueueHours` | `72` | How long a message may wait before it is dead-lettered. |
+| `agent.servers` | `DEFAULT_SERVERS_URL` | A server-list URL, or `{ bootstrapNodes, expressNodes }`. |
+| `agent.peerOptions` | none | Extra options for `Peer.create` (for example `udpPort`). |
+| `log` | `console.warn` | Warnings and errors. |
+
+## Errors
+
+| `error` | Status | When |
+|---|---|---|
+| `origin-not-allowed` | 403 | The `Origin` header is missing or not on the list. |
+| `bad-nonce` | 401 | Unknown, expired or already used. |
+| `bad-signature` | 401 | The signature does not verify for that userid, origin and nonce or `ts`. |
+| `launch-expired` | 401 | `ts` is more than 120 s from now, either way. |
+| `launch-replayed` | 401 | The assertion was accepted before. |
+| `blocked` | 403 | The userid is on the blacklist. |
+| `register-required` | 403 | A visitor past the limit under `then: "refuse"`. |
+| `sign-in-refused`, or your own code | 403, or your own | `onSignIn` returned `{ refuse }`. |
+| `rate-limited` | 429 | Too many `sign-in` / `launch` attempts; `Retry-After` says how long. |
+| `not-signed-in` | 401 | No session, or an expired or revoked one. |
+| `invalid-fields` | 400 | Registration fields missing or refused; see `fields`. |
+| `bad-request`, `too-large`, `not-found`, `method-not-allowed` | 400, 413, 404, 405 | |
+| `server-error` | 500 | A store or the `onSignIn` hook failed, or (shared service) the service cannot start. Also `authenticate()`'s answer then. |
+
+## Files in `dataDir`
+
+```text
+users.json            the users (default store)
+state.json            used nonces, used launch assertions, revoked sessions
+*.json.lock           there for the few milliseconds of a write
+session-secret        the signing secret, mode 0600
+agent/peer.save       the agent's key, plus the peer's own friend store beside it
+agent/pending.json    friend requests held
+agent/asked.json      who the agent has sent a request to
+agent/outbox.json     messages not delivered yet
+agent/dead-letter.jsonl
+agent/servers.json    last good copy of the server list
+```
+
+All of it is runtime state: keep it out of git, back up `agent/peer.save` and `users.json`.
+
+## Where this differs from the first sketch of the API
+
+The design note this package was built from gave a shape "as a guide". What changed, and why:
+
+- **`onMessage` passes `userid` and `reply()` beside `user`.** `user` is `null` for a friend who never signed in, so
+  a handler written as `send(user.userid, …)` would throw for exactly those senders.
+- **`agent.send` resolves when the message is on disk**, with a receipt, not when it is delivered. Delivery can take
+  days for an offline friend; it is reported by the `delivered` and `dead-letter` events.
+- **The launch replay store is keyed on the signed message** (userid, origin, `ts`) instead of the signature bytes.
+  A store keyed on the hex string lets the same assertion through again in another letter case.
+- **Nonces are not kept in a table.** Each carries its expiry and a MAC; only used ones are recorded. They survive a
+  restart and work across processes.
+- **`then: "refuse"` at sign-in is a 403 that still carries a session**, limited to `register` and `logout`.
+  Otherwise a refused visitor could never register.
+- **A policy function may return `"reject"`** as well as `true` (accept) and `false` (hold).
+- **`store` is the users backend only**; the replay and revocation sets have their own small adapter, `state`,
+  because a replay check needs an atomic insert, not a read and a write.
+- **A request from an origin that is not listed answers 403**, where the published sign-in guide's sample answers 400.
+
+## Upgrading from 0.1.0
+
+A site written for 0.1.0 runs on 0.2.0 without a code change, with a `store` and `state` of its own or the default
+ones (run: a 0.1.0-style site in `test/upgrade.test.mjs`). What behaves differently, all of it:
+
+- **A sign-in whose signature does not verify no longer spends the nonce** and writes nothing. The nonce is spent
+  by the sign-in that verifies. A page that asked for a new nonce after a failure keeps working.
+- **Sign-in and launch are rate-limited by default**: 30 attempts a minute per client address and 600 a minute in
+  total, then 429 `rate-limited`. Behind a proxy on another machine every visitor has the proxy's address: set
+  `rateLimit: { trustProxy: true }` (or `key`), or `rateLimit: false` for the 0.1.0 behaviour.
+- **`authenticate()` and `handlers.*` no longer reject.** When a store throws they answer status 500
+  `server-error` (`ok: false` from `authenticate`). Code that relied on a `catch` now gets an answer to check.
+- **The user record has a new field, `origin`**, written at each sign-in; the `sign-in` event's info has `origin`.
+  A store with fixed columns that drops unknown fields loses nothing it had before.
+- **`store.put` is called with a second argument**, and with a store whose calls are synchronous the library's
+  `get` and `put` now run back to back. `users.get()` and `users.list()` fill in missing fields of old records
+  (in memory), and `list()` leaves out entries that are not objects with a `userid`.
+- **The default file stores are read again when the file changed on disk**, and write under `<file>.lock`. Editing
+  `users.json` by hand while the server runs now takes effect (it used to be overwritten by the next write).
+- **`authenticate()` skips its activity write** when `lastSeen` is less than a minute old, whichever process wrote it.
+- **`require("@decentnetwork/beagle-service")` works.** `package.json` `main` now names the CommonJS file;
+  `import` resolves as before.
+- **TypeScript**: `Auth` gained `origins()` and `setOrigins()`, `BeagleService` gained `route()`, `ErrorCode` gained
+  `"sign-in-refused"` and `"rate-limited"`, `BeagleServiceConfig.origins` also accepts a function. An object you
+  typed as one of the first two by hand (a test double) needs the new members.
+
+New and off unless you use them: `onSignIn`, `origins` as a function and `auth.setOrigins()`, `serverId`,
+`session.touch`, `authenticate(req, { checkOrigin })`, `svc.route(name)`, `sharedBeagleService()`, the
+`beagle-service users` command.
+
+## Not in this version
+
+The wallet door, gates and permits; sending the confirmation email or SMS; files, calls and groups; quotas and
+billing; a chat history store; several agent roles in one process; linking several keys to one person; the
+browser-side sign-in picker.
+
+## Tests
+
+```bash
+npm test                     # every sign-in case through real HTTP routes, a kill-and-restart replay check, users, agent,
+                             # the gaps the first site found (test/gaps.test.mjs), a 0.1.0-style site (test/upgrade.test.mjs);
+                             # plus typechecks of an ES module and a CommonJS consumer against the shipped declarations
+npm run test:gaps-on-0.1.0   # the gap tests against the published 0.1.0: every one must fail there
+npm run e2e:next             # examples/next-pages-cjs with the packed package: next build, next start (about 2 minutes)
+npm run e2e                  # the agent on the public network with throwaway identities (about 8 minutes)
+```