@decentnetwork/beagle-service 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Decent Network contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,460 @@
-# 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+, ESM, MIT, types included
+```
+
+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).
+
+---
+
+## 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. 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.
+- **`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, … }
+```
+
+`authenticate(req, { allowUnregistered: true })` lets a visitor past the limit through (the register route uses it).
+
+### Frameworks
+
+```js
+// node:http
+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;
+
+// Next.js API route: pages/api/auth/[...beagle].js
+export default async (req, res) => (await beagle).nextApiHandler({ prefix: "/api/auth" })(req, res);
+
+// 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);
+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 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.
+
+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"
+  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 }) => {});
+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) => {});
+```
+
+### 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.
+
+For Postgres, sqlite or anything else, implement three calls; `put` gets the whole record and must keep all of it:
+
+```js
+const store = {
+  get:  async (userid) => row ?? null,
+  put:  async (user) => { /* upsert by user.userid, store the whole object */ },
+  list: async () => rows,
+};
+await createBeagleService({ origins, store });
+```
+
+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`:
+
+```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. |
+| `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. |
+| `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, `"/"` | |
+| `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"`. |
+| `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 | |
+
+## Files in `dataDir`
+
+```text
+users.json            the users (default store)
+state.json            used nonces, used launch assertions, revoked sessions
+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.
+
+## 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          # 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)
+```

package/dist/agent.d.ts

@@ -0,0 +1,18 @@
+import type { Agent, AgentConfig, AgentServers, Users } from "./types.js";
+import { type Logger } from "./util.js";
+/** The public server list the Beagle apps read: bootstrap and Express nodes
+ *  of the Carrier network. Any list in the same format can stand in for it. */
+export declare const DEFAULT_SERVERS_URL = "https://beagle.chat/assets/bgservers.json";
+export interface AgentOptions {
+    config: AgentConfig;
+    users: Users;
+    /** Directory for the agent's files. */
+    dir: string;
+    now?: () => number;
+    log?: Logger;
+    fetch?: typeof fetch;
+}
+/** Bootstrap and Express nodes from a `bgservers.json`-format list. The last
+ *  good answer is kept on disk, so a restart works while the URL is down. */
+export declare function loadServers(source: AgentServers | string | undefined, cacheFile: string, doFetch: typeof fetch, log: Logger): Promise<AgentServers>;
+export declare function createAgent(o: AgentOptions): Promise<Agent>;