@decentnetwork/beagle-service 0.1.0 → 0.2.0

package/README.md

@@ -15,9 +15,11 @@ Three parts. Use the first alone, or all three:
 | [`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+, ESM, MIT, types included
+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.
 
@@ -46,6 +48,18 @@ 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.
 
 ---
 
@@ -85,9 +99,12 @@ button.onclick = async () => {
 - **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. It is spent the first time it is presented, whether or not the signature verifies.
-  A nonce carries its expiry and the server's MAC, so issuing one stores nothing; using one records it in the state
-  store, so it stays spent across a restart.
+- **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
@@ -116,7 +133,93 @@ who.user;            // the full record
 who.registration;    // { status, missing, due, refused, … }
 ```
 
-`authenticate(req, { allowUnregistered: true })` lets a visitor past the limit through (the register route uses it).
+**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
 
@@ -127,24 +230,88 @@ http.createServer(svc.nodeHandler({ prefix: "/api/auth" }));
 // Express: other paths go to next()
 app.use(svc.expressHandler({ prefix: "/api/auth" }));
 
-// Next.js: one service for the whole server, in lib/beagle.js
-globalThis.__beagle ??= createBeagleService({ origins: ["https://your.app"], dataDir: "./data" });
-export const beagle = globalThis.__beagle;
+// 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
 
-// Next.js API route: pages/api/auth/[...beagle].js
-export default async (req, res) => (await beagle).nextApiHandler({ prefix: "/api/auth" })(req, res);
+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.
 
-// Next.js App Router (or any Web Request/Response host): app/api/auth/[...beagle]/route.js
-const handler = async (request) => (await beagle).fetchHandler({ prefix: "/api/auth" })(request);
+```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 };
+```
 
-// Anything else
-const { status, headers, body } = await svc.handle({ method, path: "/sign-in", headers, body });
-await svc.handlers.signIn({ method, headers, body });   // nonce, signIn, launch, me, logout, register
+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 });
 ```
 
-In Next.js the service is kept on `globalThis` because the pages and app routes are bundled apart and a module can be
-evaluated more than once. Request bodies are JSON and at most 64 KB.
+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)`.
@@ -159,6 +326,7 @@ One record per userid, created at the first sign-in:
 {
   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,
@@ -229,31 +397,79 @@ again.
 ### Events
 
 ```js
-svc.users.on("sign-in", (user, { first, door }) => {});
+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 server process and up to some tens of thousands of users. A file that does not parse stops the
-start instead of being treated as empty.
+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; `put` gets the whole record and must keep all of it:
+For Postgres, sqlite or anything else, implement three calls:
 
 ```js
 const store = {
   get:  async (userid) => row ?? null,
-  put:  async (user) => { /* upsert by user.userid, store the whole object */ },
+  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). With more than one server process, put it in the shared database too and set one `sessionSecret`:
+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 = {
@@ -364,16 +580,24 @@ copy is kept on disk so a restart works while that URL is down. Pass `agent.serv
 
 | Key | Default | Meaning |
 |---|---|---|
-| `origins` | required | Exact origins of your pages. |
+| `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 }`. |
@@ -406,15 +630,19 @@ copy is kept on disk so a restart works while that URL is down. Pass `agent.serv
 | `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`, `server-error` | 400, 413, 404, 405, 500 | |
+| `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
@@ -445,6 +673,36 @@ The design note this package was built from gave a shape "as a guide". What chan
   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
@@ -454,7 +712,10 @@ browser-side sign-in picker.
 ## Tests
 
 ```bash
-npm test          # 45 tests: every sign-in case through real HTTP routes, a kill-and-restart replay check, users, agent;
-                  # plus a typecheck of a consumer file against the shipped declarations
-npm run e2e       # the agent on the public network with throwaway identities (about 8 minutes)
+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)
 ```

package/dist/auth.d.ts

@@ -1,4 +1,5 @@
-import type { Auth, HeadersCarrier, SessionConfig, StateStore, Users } from "./types.js";
+import type { Auth, HeadersCarrier, OriginsSource, SessionConfig, StateStore, Users } from "./types.js";
+import { type Logger } from "./util.js";
 /** How long a nonce lives, and how far a launch timestamp may be from now. */
 export declare const NONCE_TTL_MS = 120000;
 export declare const LAUNCH_MAX_AGE_MS = 120000;
@@ -6,15 +7,22 @@ export declare const LAUNCH_MAX_AGE_MS = 120000;
  *  not `scheme://host[:port]`, so a typo is found at start, not as a sign-in
  *  that never verifies. */
 export declare function normalizeOrigins(list: unknown): Set<string>;
+/** Throw now if the configured origins cannot be used. A function is called once. */
+export declare function checkOrigins(source: OriginsSource | Set<string>): void;
 /** The signing secret: the configured one, else a 32-byte one kept in `file`. */
 export declare function loadSecret(configured: string | undefined, file: string): string;
 export declare function headerOf(req: HeadersCarrier | undefined, name: string): string | undefined;
 export interface AuthOptions {
-    origins: Set<string>;
+    /** A list, a function that returns the list as it is now, or the set
+     *  `normalizeOrigins` made. */
+    origins: OriginsSource | Set<string>;
     state: StateStore;
     users: Users;
     secret: string;
+    /** Binds nonces to this server; see `BeagleServiceConfig.serverId`. */
+    serverId?: string;
     session?: SessionConfig;
     now?: () => number;
+    log?: Logger;
 }
 export declare function createAuth(opts: AuthOptions): Auth;