@decentnetwork/beagle-service 0.1.0 → 0.2.0

package/dist/auth.js

@@ -2,7 +2,7 @@ import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { verifyLaunch as connectVerifyLaunch, verifySignIn as connectVerifySignIn } from "@decentnetwork/beagle-connect";
-import { isUserid } from "./util.js";
+import { isUserid, msgOf } from "./util.js";
 /** How long a nonce lives, and how far a launch timestamp may be from now. */
 export const NONCE_TTL_MS = 120_000;
 export const LAUNCH_MAX_AGE_MS = 120_000;
@@ -32,6 +32,11 @@ export function normalizeOrigins(list) {
     }
     return out;
 }
+/** Throw now if the configured origins cannot be used. A function is called once. */
+export function checkOrigins(source) {
+    if (!(source instanceof Set))
+        normalizeOrigins(typeof source === "function" ? source() : source);
+}
 /** The signing secret: the configured one, else a 32-byte one kept in `file`. */
 export function loadSecret(configured, file) {
     if (configured) {
@@ -69,12 +74,61 @@ export function headerOf(req, name) {
 }
 const isSigHex = (v) => typeof v === "string" && /^[0-9a-fA-F]{128}$/.test(v);
 export function createAuth(opts) {
-    const { origins, state, users, secret } = opts;
+    const { state, users, secret } = opts;
     const now = opts.now ?? Date.now;
+    const log = opts.log ?? (() => { });
     const cfg = opts.session ?? {};
     const ttlMs = (cfg.ttlDays ?? 30) * DAY_MS;
     const cookieName = cfg.cookieName ?? "beagle_session";
     const sameSite = cfg.sameSite ?? "Lax";
+    if (opts.serverId !== undefined && (typeof opts.serverId !== "string" || !opts.serverId || opts.serverId.length > 64)) {
+        throw new TypeError("beagle-service: `serverId` must be a string of 1 to 64 characters");
+    }
+    // Only the nonce MAC carries the server's name: a session is signed the
+    // same way on every server that has the secret.
+    const noncePurpose = opts.serverId ? `nonce@${opts.serverId}` : "nonce";
+    // ── which origins may ask ─────────────────────────────────────────────────
+    // A fixed set, or a function asked on each request. The function's answer
+    // is parsed again only when it differs from the last one; an answer that
+    // does not parse is logged and the last good list stays in force.
+    let fixed = new Set();
+    let source = null;
+    let sourceKey = null;
+    let complainedAt = 0;
+    function setOrigins(next) {
+        if (typeof next === "function") {
+            const list = next();
+            const set = normalizeOrigins(list); // throws: the caller learns it now
+            fixed = set;
+            source = next;
+            sourceKey = JSON.stringify(list);
+        }
+        else {
+            fixed = next instanceof Set ? new Set(next) : normalizeOrigins(next);
+            source = null;
+            sourceKey = null;
+        }
+    }
+    setOrigins(opts.origins);
+    function current() {
+        if (!source)
+            return fixed;
+        try {
+            const list = source();
+            const key = JSON.stringify(list);
+            if (key !== sourceKey) {
+                fixed = normalizeOrigins(list);
+                sourceKey = key;
+            }
+        }
+        catch (e) {
+            if (Date.now() - complainedAt > 60_000) {
+                complainedAt = Date.now();
+                log(`beagle-service: the origins function gave a list that cannot be used (${msgOf(e)}); keeping ${[...fixed].join(", ")}`);
+            }
+        }
+        return fixed;
+    }
     const mac = (purpose, body) => createHmac("sha256", secret).update(`${purpose}\n${body}`).digest("base64url");
     const macOk = (purpose, body, got) => {
         const want = Buffer.from(mac(purpose, body));
@@ -88,23 +142,25 @@ export function createAuth(opts) {
     // across a restart.
     function issueNonce() {
         const body = `${randomBytes(18).toString("base64url")}.${(now() + NONCE_TTL_MS).toString(36)}`;
-        return `${body}.${mac("nonce", body).slice(0, 22)}`;
+        return `${body}.${mac(noncePurpose, body).slice(0, 22)}`;
     }
-    async function consumeNonce(nonce) {
+    /** The nonce's id and expiry when it is ours (this server's, with
+     *  `serverId`) and has not expired. Reads nothing, writes nothing. */
+    function readNonce(nonce) {
         if (typeof nonce !== "string" || nonce.length > 128)
-            return false;
+            return null;
         const parts = nonce.split(".");
         if (parts.length !== 3)
-            return false;
+            return null;
         const body = `${parts[0]}.${parts[1]}`;
-        const want = Buffer.from(mac("nonce", body).slice(0, 22));
+        const want = Buffer.from(mac(noncePurpose, body).slice(0, 22));
         const have = Buffer.from(parts[2]);
         if (want.length !== have.length || !timingSafeEqual(want, have))
-            return false;
+            return null;
         const exp = parseInt(parts[1], 36);
         if (!Number.isFinite(exp) || exp < now())
-            return false;
-        return await state.addOnce("nonce", parts[0], exp);
+            return null;
+        return { id: parts[0], exp };
     }
     // ── the two assertions ────────────────────────────────────────────────────
     const fail = (status, error) => ({ ok: false, status, error });
@@ -122,25 +178,31 @@ export function createAuth(opts) {
     }
     function allowedOrigin(req) {
         const origin = headerOf(req, "origin");
-        return origin && origins.has(origin) ? origin : null;
+        return origin && current().has(origin) ? origin : null;
     }
     async function verifySignIn(origin, body) {
-        if (!origin || !origins.has(origin))
+        if (!origin || !current().has(origin))
             return fail(403, "origin-not-allowed");
         if (!body || typeof body !== "object")
             return fail(400, "bad-request");
         const b = body;
-        // First, and whatever the signature turns out to be: a nonce that has been
-        // presented once is spent.
-        if (!(await consumeNonce(b.nonce)))
+        const nonce = readNonce(b.nonce);
+        if (!nonce || (await state.has("nonce", nonce.id)))
             return fail(401, "bad-nonce");
         if (!isUserid(b.userid) || !isSigHex(b.sig) || !connectVerifySignIn(b.userid, origin, b.nonce, b.sig)) {
             return fail(401, "bad-signature");
         }
+        // Spent here, by the sign-in that verified, and only here: a request with
+        // no valid signature costs no write and adds nothing to the used list, so
+        // nobody without a key can grow it, or burn a nonce a visitor still holds.
+        // `addOnce` is the single-use guarantee: of two requests with the same
+        // valid assertion, one gets true.
+        if (!(await state.addOnce("nonce", nonce.id, nonce.exp)))
+            return fail(401, "bad-nonce");
         return { ok: true, userid: b.userid, hints: hintsOf(b), door: doorOf(b.uiOrigin) };
     }
     async function verifyLaunch(origin, body) {
-        if (!origin || !origins.has(origin))
+        if (!origin || !current().has(origin))
             return fail(403, "origin-not-allowed");
         if (!body || typeof body !== "object")
             return fail(400, "bad-request");
@@ -202,29 +264,48 @@ export function createAuth(opts) {
         }
         return null;
     }
+    const SAFE_METHOD = /^(GET|HEAD|OPTIONS)$/i;
     async function authenticate(req, o = {}) {
         const none = { ok: false, status: 401, error: "not-signed-in" };
-        const found = tokenFrom(req);
-        if (!found)
-            return none;
-        const t = readToken(found.token);
-        if (!t)
-            return none;
-        if (await state.has("revoked", t.sid))
-            return none;
-        const user = o.touch === false ? await users.get(t.userid) : await users.touch(t.userid);
-        if (!user)
-            return none;
-        if (user.status === "blocked")
-            return { ok: false, status: 403, error: "blocked" };
-        if (user.sessionsValidFrom && t.issuedAt < user.sessionsValidFrom)
-            return none;
-        const session = { ...t, via: found.via };
-        const registration = users.registration(user);
-        if (registration.refused && !o.allowUnregistered) {
-            return { ok: false, status: 403, error: "register-required", user, session, registration };
+        try {
+            const found = tokenFrom(req);
+            if (!found)
+                return none;
+            const t = readToken(found.token);
+            if (!t)
+                return none;
+            if (await state.has("revoked", t.sid))
+                return none;
+            // A cookie is sent by the browser whoever wrote the page; the Origin
+            // header says who did. A bearer token is put there by the caller.
+            if (o.checkOrigin && found.via === "cookie") {
+                const method = req?.method;
+                if (!(typeof method === "string" && SAFE_METHOD.test(method)) && !allowedOrigin(req)) {
+                    return { ok: false, status: 403, error: "origin-not-allowed" };
+                }
+            }
+            const touch = o.touch ?? cfg.touch ?? true;
+            const user = touch ? await users.touch(t.userid) : await users.get(t.userid);
+            if (!user)
+                return none;
+            if (user.status === "blocked")
+                return { ok: false, status: 403, error: "blocked" };
+            if (user.sessionsValidFrom && t.issuedAt < user.sessionsValidFrom)
+                return none;
+            const session = { ...t, via: found.via };
+            const registration = users.registration(user);
+            if (registration.refused && !o.allowUnregistered) {
+                return { ok: false, status: 403, error: "register-required", user, session, registration };
+            }
+            return { ok: true, user, session, registration };
+        }
+        catch (e) {
+            // A store that cannot be read is not "nobody is signed in" and it is
+            // not an exception either: a caller that wraps this in try/catch and
+            // goes on would be deciding without knowing who asks.
+            log(`beagle-service: authenticate could not read the session: ${e?.stack ?? msgOf(e)}`);
+            return { ok: false, status: 500, error: "server-error" };
         }
-        return { ok: true, user, session, registration };
     }
     async function revoke(token) {
         const t = readToken(token);
@@ -245,6 +326,8 @@ export function createAuth(opts) {
     return {
         issueNonce,
         allowedOrigin,
+        origins: () => [...current()],
+        setOrigins,
         verifySignIn,
         verifyLaunch,
         authenticate,

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// beagle-service: the operator's command.
+//
+//   npx beagle-service users list [--status visitor|registered|blocked] [--json]
+//   npx beagle-service users show    <userid>
+//   npx beagle-service users block   <userid> [why…]
+//   npx beagle-service users unblock <userid>
+//
+// It changes the same records the running site reads, through the library's
+// own `users`, never by editing a file by hand. With the default file store a
+// block takes effect at once, on sign-in and on every session that userid
+// holds: the site reads the file again when it was replaced. No restart.
+//
+// Where the users are:
+//   --data <dir>      the site's dataDir, for the default store (default ./data)
+//   --config <file>   a module that exports the site's own `store` (and its
+//                     `register` / `visitor` settings), or a ready `users`;
+//                     default: beagle-service.config.{mjs,cjs,js} in this directory
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { jsonFileUserStore } from "./stores.js";
+import { createUsers } from "./users.js";
+const USAGE = `usage: beagle-service users list [--status visitor|registered|blocked] [--json]
+       beagle-service users show    <userid>
+       beagle-service users block   <userid> [why…]
+       beagle-service users unblock <userid>
+
+options: --data <dir>     the site's dataDir, for the default file store (default ./data)
+         --config <file>  a module exporting { store, register?, visitor? } or { users }
+                          (default: beagle-service.config.mjs / .cjs / .js here, if there is one)`;
+class Usage extends Error {
+}
+function parse(argv) {
+    const words = [];
+    const flags = new Map();
+    const takesValue = new Set(["data", "config", "status"]);
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith("--")) {
+            words.push(a);
+            continue;
+        }
+        const eq = a.indexOf("=");
+        const name = eq > 0 ? a.slice(2, eq) : a.slice(2);
+        if (eq > 0)
+            flags.set(name, a.slice(eq + 1));
+        else if (takesValue.has(name)) {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Usage(`--${name} needs a value`);
+            flags.set(name, v);
+        }
+        else
+            flags.set(name, true);
+    }
+    return { words, flags };
+}
+async function usersFrom(flags) {
+    const named = flags.get("config");
+    let file = typeof named === "string" ? resolve(named) : null;
+    if (file && !existsSync(file))
+        throw new Error(`no such config file: ${file}`);
+    if (!file) {
+        for (const name of ["beagle-service.config.mjs", "beagle-service.config.cjs", "beagle-service.config.js"]) {
+            if (existsSync(resolve(name))) {
+                file = resolve(name);
+                break;
+            }
+        }
+    }
+    let config = {};
+    if (file) {
+        const mod = await import(pathToFileURL(file).href);
+        config = mod.default ?? mod;
+        if (typeof config === "function")
+            config = await config();
+        if (!config || typeof config !== "object")
+            throw new Error(`${file} must export an object, or a function that returns one`);
+        if (config.users && typeof config.users.block === "function")
+            return config.users;
+    }
+    const data = flags.get("data");
+    const dataDir = typeof data === "string" ? data : (config.dataDir ?? "./data");
+    if (!config.store && !existsSync(join(dataDir, "users.json"))) {
+        throw new Error(`no users file at ${join(dataDir, "users.json")}; name the site's data directory with --data, or its own store with --config`);
+    }
+    return createUsers({
+        store: config.store ?? jsonFileUserStore(join(dataDir, "users.json")),
+        register: config.register,
+        visitor: config.visitor,
+        log: (m) => console.error(m),
+    });
+}
+const line = (u) => [
+    u.userid,
+    u.status.padEnd(10),
+    String(u.signIns || 0).padStart(5),
+    (u.lastSeen || "-").padEnd(24),
+    u.name || "",
+    u.blocked ? `[blocked ${u.blocked.at}: ${u.blocked.why}]` : "",
+]
+    .join("  ")
+    .trimEnd();
+async function main(argv) {
+    const { words, flags } = parse(argv);
+    if (flags.has("help") || words.length === 0) {
+        console.log(USAGE);
+        return words.length === 0 && !flags.has("help") ? 2 : 0;
+    }
+    const [group, cmd, userid, ...rest] = words;
+    if (group !== "users" || !cmd)
+        throw new Usage(`unknown command: ${words.join(" ")}`);
+    if (cmd === "list") {
+        const status = flags.get("status");
+        if (status !== undefined && status !== "visitor" && status !== "registered" && status !== "blocked") {
+            throw new Usage("--status is visitor, registered or blocked");
+        }
+        const all = await (await usersFrom(flags)).list(status ? { status: status } : undefined);
+        if (flags.has("json"))
+            console.log(JSON.stringify(all, null, 2));
+        else {
+            for (const u of all)
+                console.log(line(u));
+            console.log(`${all.length} user(s)`);
+        }
+        return 0;
+    }
+    if (!userid || !["show", "block", "unblock"].includes(cmd))
+        throw new Usage(cmd === "show" || cmd === "block" || cmd === "unblock" ? `${cmd} needs a userid` : `unknown command: users ${cmd}`);
+    const users = await usersFrom(flags);
+    if (cmd === "show") {
+        const u = await users.get(userid);
+        if (!u) {
+            console.error("no such user");
+            return 1;
+        }
+        console.log(JSON.stringify(u, null, 2));
+        return 0;
+    }
+    if (cmd === "block") {
+        console.log(line(await users.block(userid, rest.join(" "))));
+        return 0;
+    }
+    const u = await users.unblock(userid);
+    if (!u) {
+        console.error("no such user");
+        return 1;
+    }
+    console.log(line(u));
+    return 0;
+}
+// Exit by hand once the output is flushed: a site's own store may hold a
+// connection open that would keep the process alive.
+const exit = (code) => process.stdout.write("", () => process.stderr.write("", () => process.exit(code)));
+main(process.argv.slice(2)).then(exit, (e) => {
+    if (e instanceof Usage) {
+        console.error(`${e.message}\n\n${USAGE}`);
+        return exit(2);
+    }
+    console.error(String(e?.message ?? e));
+    exit(1);
+});

package/dist/commonjs.cjs

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.load = load;
+exports.createBeagleService = createBeagleService;
+exports.sharedBeagleService = sharedBeagleService;
+let loading;
+/** The whole library, as `import("@decentnetwork/beagle-service")` gives it:
+ *  `const { createUsers, jsonFileStateStore } = await load();` */
+function load() {
+    return (loading ??= import("./index.js"));
+}
+/** As the ES module's `createBeagleService`. */
+function createBeagleService(config) {
+    return load().then((lib) => lib.createBeagleService(config));
+}
+const UNAVAILABLE = { ok: false, error: "server-error", message: "Sign-in is not available on this server." };
+/** As the ES module's `sharedBeagleService`: returns at once, never throws,
+ *  and is the same service for every caller in the process. */
+function sharedBeagleService(config, opts) {
+    const real = () => load().then((lib) => lib.sharedBeagleService(config, opts));
+    const down = (res) => {
+        if (res.headersSent)
+            return;
+        res.statusCode = 500;
+        res.setHeader("content-type", "application/json; charset=utf-8");
+        res.end(JSON.stringify(UNAVAILABLE));
+    };
+    const node = (pick) => async (req, res, next) => {
+        let svc;
+        try {
+            svc = await real();
+        }
+        catch {
+            return down(res);
+        }
+        return pick(svc)(req, res, next);
+    };
+    return {
+        ready: () => real().then((svc) => svc.ready()),
+        authenticate: (req, o) => real().then((svc) => svc.authenticate(req, o), () => ({ ok: false, status: 500, error: "server-error" })),
+        handle: (req) => real().then((svc) => svc.handle(req), () => ({ status: 500, headers: { "content-type": "application/json; charset=utf-8" }, body: UNAVAILABLE })),
+        route: (name) => node((svc) => svc.route(name)),
+        nodeHandler: (o) => node((svc) => svc.nodeHandler(o)),
+        expressHandler: (o) => node((svc) => svc.expressHandler(o)),
+        nextApiHandler: (o) => node((svc) => svc.nextApiHandler(o)),
+        fetchHandler: (o) => (request) => real().then((svc) => svc.fetchHandler(o)(request)),
+        close: () => real().then((svc) => svc.close()),
+    };
+}

package/dist/commonjs.d.cts

@@ -0,0 +1,11 @@
+import type * as Library from "./index.js" with { "resolution-mode": "import" };
+type Lib = typeof Library;
+/** The whole library, as `import("@decentnetwork/beagle-service")` gives it:
+ *  `const { createUsers, jsonFileStateStore } = await load();` */
+export declare function load(): Promise<Lib>;
+/** As the ES module's `createBeagleService`. */
+export declare function createBeagleService(config: Library.BeagleServiceConfig): Promise<Library.BeagleService>;
+/** As the ES module's `sharedBeagleService`: returns at once, never throws,
+ *  and is the same service for every caller in the process. */
+export declare function sharedBeagleService(config: Library.BeagleServiceConfig | (() => Library.BeagleServiceConfig), opts?: Library.SharedOptions): Library.SharedBeagleService;
+export type * from "./types.js" with { "resolution-mode": "import" };

package/dist/index.d.ts

@@ -1,9 +1,23 @@
-import type { BeagleService, BeagleServiceConfig } from "./types.js";
+import type { BeagleService, BeagleServiceConfig, SharedBeagleService, SharedOptions } from "./types.js";
 export declare function createBeagleService(config: BeagleServiceConfig): Promise<BeagleService>;
+/** The service for this process: created on first use, and the same one for
+ *  every caller with the same `key`, however many times the calling module is
+ *  evaluated (Next.js bundles pages and API routes apart) and whichever of
+ *  `import` and `require` loaded this package.
+ *
+ *  Returns at once and never throws. A configuration that is wrong shows in
+ *  `ready()`, which rejects; the routes then answer 500 and `authenticate`
+ *  answers `ok: false`. A failed start is not kept: it is tried again, at most
+ *  every `retryMs`.
+ *
+ *  `config` may be a function, so that reading the environment happens at
+ *  first use and not when the module is loaded. The first call for a key
+ *  decides the configuration. */
+export declare function sharedBeagleService(config: BeagleServiceConfig | (() => BeagleServiceConfig), opts?: SharedOptions): SharedBeagleService;
 export { createAuth, normalizeOrigins, NONCE_TTL_MS, LAUNCH_MAX_AGE_MS } from "./auth.js";
 export { createUsers, DEFAULT_PROFILE_GATEWAY } from "./users.js";
 export { createAgent, loadServers, DEFAULT_SERVERS_URL } from "./agent.js";
 export { Outbox, splitText } from "./outbox.js";
-export { jsonFileUserStore, memoryUserStore, jsonFileStateStore, memoryStateStore } from "./stores.js";
+export { jsonFileUserStore, memoryUserStore, jsonFileStateStore, memoryStateStore, applyUserChange } from "./stores.js";
 export { defaultPublicUser } from "./routes.js";
 export * from "./types.js";

package/dist/index.js

@@ -12,17 +12,20 @@
 // Nothing here makes one site special. Every key is an equal identity; a site
 // that uses this package is one Carrier service provider among any number.
 import { join } from "node:path";
-import { createAuth, loadSecret, normalizeOrigins } from "./auth.js";
+import { checkOrigins, createAuth, loadSecret } from "./auth.js";
+import { msgOf } from "./util.js";
 import { createRoutes } from "./routes.js";
 import { jsonFileStateStore, jsonFileUserStore } from "./stores.js";
 import { createUsers } from "./users.js";
 export async function createBeagleService(config) {
     if (!config || typeof config !== "object")
         throw new TypeError("beagle-service: createBeagleService needs a config object");
-    const origins = normalizeOrigins(config.origins);
     const dataDir = config.dataDir ?? "./data";
     const now = config.now ?? Date.now;
     const log = config.log ?? ((m) => console.warn(m));
+    // A malformed origin is found here, when the service is created, before a
+    // file is made or a request is answered.
+    checkOrigins(config.origins);
     const store = config.store ?? jsonFileUserStore(join(dataDir, "users.json"));
     const state = config.state ?? jsonFileStateStore(join(dataDir, "state.json"), now);
     const secret = loadSecret(config.sessionSecret, join(dataDir, "session-secret"));
@@ -35,9 +38,19 @@ export async function createBeagleService(config) {
         log,
         fetch: config.fetch,
     });
-    const auth = createAuth({ origins, state, users, secret, session: config.session, now });
+    const auth = createAuth({ origins: config.origins, state, users, secret, serverId: config.serverId, session: config.session, now, log });
     let agent;
-    const routes = createRoutes({ auth, users, session: config.session, publicUser: config.publicUser, agent: () => agent, log });
+    const routes = createRoutes({
+        auth,
+        users,
+        session: config.session,
+        publicUser: config.publicUser,
+        onSignIn: config.onSignIn,
+        rateLimit: config.rateLimit,
+        agent: () => agent,
+        log,
+        now,
+    });
     if (config.agent) {
         // Only when asked for: a site that needs sign-in alone starts no peer.
         const { createAgent } = await import("./agent.js");
@@ -53,16 +66,125 @@ export async function createBeagleService(config) {
         expressHandler: routes.expressHandler,
         nextApiHandler: routes.nextApiHandler,
         fetchHandler: routes.fetchHandler,
+        route: routes.route,
         close: async () => {
             await agent?.stop();
         },
     };
 }
+// ── one service per process ─────────────────────────────────────────────────
+const SHARED = Symbol.for("@decentnetwork/beagle-service/shared");
+const UNAVAILABLE = {
+    status: 500,
+    headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" },
+    body: { ok: false, error: "server-error", message: "Sign-in is not available on this server." },
+};
+/** The service for this process: created on first use, and the same one for
+ *  every caller with the same `key`, however many times the calling module is
+ *  evaluated (Next.js bundles pages and API routes apart) and whichever of
+ *  `import` and `require` loaded this package.
+ *
+ *  Returns at once and never throws. A configuration that is wrong shows in
+ *  `ready()`, which rejects; the routes then answer 500 and `authenticate`
+ *  answers `ok: false`. A failed start is not kept: it is tried again, at most
+ *  every `retryMs`.
+ *
+ *  `config` may be a function, so that reading the environment happens at
+ *  first use and not when the module is loaded. The first call for a key
+ *  decides the configuration. */
+export function sharedBeagleService(config, opts = {}) {
+    const registry = (globalThis[SHARED] ??= new Map());
+    const key = opts.key ?? "default";
+    const held = registry.get(key);
+    if (held)
+        return held;
+    const retryMs = opts.retryMs ?? 5000;
+    let starting = null;
+    let failure = null;
+    let complainedAt = 0;
+    function ready() {
+        if (starting)
+            return starting;
+        if (failure && Date.now() - failure.at < retryMs)
+            return Promise.reject(failure.error);
+        const attempt = Promise.resolve().then(() => createBeagleService(typeof config === "function" ? config() : config));
+        starting = attempt;
+        attempt.then(() => (failure = null), (error) => {
+            // Not kept: the next call after `retryMs` starts again.
+            if (starting === attempt)
+                starting = null;
+            failure = { error, at: Date.now() };
+            if (Date.now() - complainedAt > 60_000) {
+                complainedAt = Date.now();
+                console.error(`beagle-service: the service could not start: ${msgOf(error)}`);
+            }
+        });
+        return attempt;
+    }
+    const down = (res) => {
+        if (res.headersSent)
+            return;
+        res.statusCode = UNAVAILABLE.status;
+        for (const [k, v] of Object.entries(UNAVAILABLE.headers))
+            res.setHeader(k, v);
+        res.end(JSON.stringify(UNAVAILABLE.body));
+    };
+    const node = (pick) => async (req, res, next) => {
+        let svc;
+        try {
+            svc = await ready();
+        }
+        catch {
+            return down(res);
+        }
+        return pick(svc)(req, res, next);
+    };
+    const shared = {
+        ready,
+        async authenticate(req, o) {
+            try {
+                return await (await ready()).auth.authenticate(req, o);
+            }
+            catch {
+                return { ok: false, status: 500, error: "server-error" };
+            }
+        },
+        async handle(req) {
+            try {
+                return await (await ready()).handle(req);
+            }
+            catch {
+                return UNAVAILABLE;
+            }
+        },
+        route: (name) => node((svc) => svc.route(name)),
+        nodeHandler: (o) => node((svc) => svc.nodeHandler(o)),
+        expressHandler: (o) => node((svc) => svc.expressHandler(o)),
+        nextApiHandler: (o) => node((svc) => svc.nextApiHandler(o)),
+        fetchHandler: (o) => async (request) => {
+            try {
+                return await (await ready()).fetchHandler(o)(request);
+            }
+            catch {
+                return new Response(JSON.stringify(UNAVAILABLE.body), { status: UNAVAILABLE.status, headers: UNAVAILABLE.headers });
+            }
+        },
+        async close() {
+            if (registry.get(key) === shared)
+                registry.delete(key);
+            const svc = await starting?.catch(() => null);
+            starting = null;
+            await svc?.close();
+        },
+    };
+    registry.set(key, shared);
+    return shared;
+}
 export { createAuth, normalizeOrigins, NONCE_TTL_MS, LAUNCH_MAX_AGE_MS } from "./auth.js";
 export { createUsers, DEFAULT_PROFILE_GATEWAY } from "./users.js";
 export { createAgent, loadServers, DEFAULT_SERVERS_URL } from "./agent.js";
 export { Outbox, splitText } from "./outbox.js";
-export { jsonFileUserStore, memoryUserStore, jsonFileStateStore, memoryStateStore } from "./stores.js";
+export { jsonFileUserStore, memoryUserStore, jsonFileStateStore, memoryStateStore, applyUserChange } from "./stores.js";
 export { defaultPublicUser } from "./routes.js";
 // `export *` rather than `export type *`: types.ts holds types only, and this
 // form is read by TypeScript versions before 5.0 too.