@decentnetwork/beagle-service 0.1.0 → 0.2.0

package/dist/types.d.ts

@@ -14,6 +14,8 @@ export interface UserRecord {
     punkId: number | null;
     /** Which Beagle answered: the popup's origin, or "launch" for an Apps-tab arrival. */
     door: string | null;
+    /** The origin of the site's page the last sign-in was signed for. */
+    origin?: string | null;
     status: UserStatus;
     /** The site's registration fields (`register.required` / `register.optional`). */
     profile: Record<string, unknown>;
@@ -46,12 +48,34 @@ export interface PublishedProfile {
     owner?: string;
     fetchedAt: string;
 }
+/** What one write changed, as the second argument of `UserStore.put`. */
+export interface UserChange {
+    /** The record as it was read for this write; null when there was none. */
+    prev: UserRecord | null;
+    /** Top-level fields that were added or got a new value, with that value. */
+    set: Record<string, unknown>;
+    /** Top-level fields that were removed. */
+    unset: string[];
+}
 /** Where users are kept. Implement these three calls for Postgres, sqlite or
- *  anything else. `put` receives the whole record and must store all of it,
- *  including fields it does not recognise. */
+ *  anything else.
+ *
+ *  `get` may return any object that names the userid; fields this library
+ *  needs and does not find are filled in when it is read (a record that
+ *  predates the library is fine).
+ *
+ *  `put` receives the whole record, including fields the store does not
+ *  recognise, and as a second argument what this write changed. A store that
+ *  other code writes to as well should store only `change.set` and remove
+ *  `change.unset`: then a field somebody else wrote since the read is not
+ *  written back from an old copy. A store that ignores the second argument
+ *  and stores the whole record (an adapter written for 0.1.0) keeps working.
+ *
+ *  When `get` and `put` are synchronous, the library calls them in the same
+ *  turn of the event loop with nothing in between. */
 export interface UserStore {
     get(userid: string): Promise<UserRecord | null> | UserRecord | null;
-    put(user: UserRecord): Promise<void> | void;
+    put(user: UserRecord, change?: UserChange): Promise<void> | void;
     list(): Promise<UserRecord[]> | UserRecord[];
 }
 /** Small durable sets with expiry: used nonces, used launch assertions and
@@ -124,6 +148,7 @@ export interface UsersEvents {
     "sign-in": [user: UserRecord, info: {
         first: boolean;
         door: string | null;
+        origin: string | null;
     }];
     /** A visitor became a registered user. */
     registered: [user: UserRecord];
@@ -160,6 +185,7 @@ export interface Users {
         punkId?: unknown;
     }, info?: {
         door?: string | null;
+        origin?: string | null;
     }): Promise<UserRecord>;
     /** Note activity: `lastSeen`, and `visits` after a gap. Written at most
      *  once a minute per user. */
@@ -181,7 +207,56 @@ export interface SessionConfig {
     cookieDomain?: string;
     /** Default "/". */
     cookiePath?: string;
+    /** `authenticate()` notes the user's activity (`lastSeen`, `visits`), which
+     *  is one write to the users store per user per minute at most. false: it
+     *  only reads. One call can say otherwise with `authenticate(req, { touch })`.
+     *  Default true. */
+    touch?: boolean;
+}
+/** A limit on sign-in and launch attempts, counted in memory per process. */
+export interface RateLimitConfig {
+    /** Attempts one client may make per window. Default 30. */
+    perClient?: number;
+    /** Attempts all clients together may make per window. Default 600. */
+    total?: number;
+    /** Default 60. */
+    windowSeconds?: number;
+    /** Read the client's address from `X-Forwarded-For`: true for one proxy in
+     *  front of the server, or how many. Default false: the connection's own
+     *  address, and a connection from this machine (a local proxy) counts
+     *  against `total` only. */
+    trustProxy?: boolean | number;
+    /** Name the client yourself; null counts against `total` only. */
+    key?: (request: ServiceRequest) => string | null | undefined;
+}
+/** What `onSignIn` is told beside the user. */
+export interface SignInInfo {
+    /** The origin of the site's page the assertion was signed for. */
+    origin: string;
+    /** Which Beagle answered: the popup's origin, or "launch". */
+    door: string | null;
+    /** Which route verified it. */
+    route: "sign-in" | "launch";
+    /** The first sign-in of this userid. */
+    first: boolean;
+    /** The request as the route got it (`raw` is the framework's own object,
+     *  when an adapter made the request). */
+    request: ServiceRequest;
 }
+/** Refuse a sign-in from `onSignIn`: no session is issued. */
+export interface SignInRefusal {
+    /** true, or the `error` code the page gets. Default "sign-in-refused". */
+    refuse: true | string;
+    /** Default 403. */
+    status?: number;
+    message?: string;
+}
+/** Runs after the assertion is verified and the user record is written, and
+ *  before the session is issued and the answer goes out. Return an object and
+ *  its fields are added to the sign-in answer (the library's own fields win);
+ *  return `{ refuse }` to refuse. It is awaited; if it throws, the sign-in
+ *  answers 500 and no session is issued. */
+export type SignInHook = (user: UserRecord, info: SignInInfo) => void | Record<string, unknown> | SignInRefusal | Promise<void | Record<string, unknown> | SignInRefusal>;
 export interface SessionInfo {
     userid: string;
     /** Session id; logout revokes this. */
@@ -191,7 +266,7 @@ export interface SessionInfo {
     /** How the token arrived. */
     via: "cookie" | "bearer";
 }
-export type ErrorCode = "origin-not-allowed" | "bad-request" | "bad-nonce" | "bad-signature" | "launch-expired" | "launch-replayed" | "blocked" | "register-required" | "not-signed-in" | "invalid-fields" | "not-found" | "method-not-allowed" | "too-large" | "server-error";
+export type ErrorCode = "origin-not-allowed" | "bad-request" | "bad-nonce" | "bad-signature" | "launch-expired" | "launch-replayed" | "blocked" | "register-required" | "sign-in-refused" | "rate-limited" | "not-signed-in" | "invalid-fields" | "not-found" | "method-not-allowed" | "too-large" | "server-error";
 export type VerifyResult = {
     ok: true;
     userid: string;
@@ -226,23 +301,45 @@ export interface HeadersCarrier {
     headers: Record<string, string | string[] | undefined> | {
         get(name: string): string | null;
     };
+    method?: string;
+}
+/** The exact origins of the site's pages: a list, or a function that returns
+ *  the list as it is now (called on each request; keep it cheap). */
+export type OriginsSource = string[] | (() => string[]);
+export interface AuthenticateOptions {
+    /** Let a visitor past the limit through (the register route does). */
+    allowUnregistered?: boolean;
+    /** Note the user's activity; see `session.touch`. */
+    touch?: boolean;
+    /** For the site's own state-changing routes: a session that arrived in a
+     *  cookie is accepted only when the request's `Origin` header is on the
+     *  list (403 `origin-not-allowed` otherwise). A bearer token needs no
+     *  Origin. When the request object has a `method` and it is GET, HEAD or
+     *  OPTIONS, nothing is checked, so the option can be passed on every call. */
+    checkOrigin?: boolean;
 }
 export interface Auth {
     /** A single-use nonce that lives 120 s. */
     issueNonce(): string;
     /** The request's `Origin` header when it is on the exact list, else null. */
     allowedOrigin(req: HeadersCarrier): string | null;
-    /** Check a `decent-auth` assertion: origin, nonce (consumed either way), signature. */
+    /** The exact origins accepted now. */
+    origins(): string[];
+    /** Replace the list while running. Throws on a malformed entry and keeps
+     *  the list it had. Used nonces, launch assertions and sessions are not
+     *  touched. */
+    setOrigins(origins: OriginsSource): void;
+    /** Check a `decent-auth` assertion: origin, nonce, signature. The nonce is
+     *  spent by the sign-in that verifies; one that fails writes nothing. */
     verifySignIn(origin: string | null | undefined, body: unknown): Promise<VerifyResult>;
     /** Check a `decent-launch` assertion: origin, ±120 s, signature, then replay (consumed last, kept on disk). */
     verifyLaunch(origin: string | null | undefined, body: unknown): Promise<VerifyResult>;
     /** Who is making this request, for the site's own routes. Refuses a blocked
      *  user (403 `blocked`) and a visitor past the limit under `then: "refuse"`
-     *  (403 `register-required`) unless `allowUnregistered` is set. */
-    authenticate(req: HeadersCarrier, opts?: {
-        allowUnregistered?: boolean;
-        touch?: boolean;
-    }): Promise<AuthResult>;
+     *  (403 `register-required`) unless `allowUnregistered` is set. Never
+     *  rejects: no session, a bad one, or a store that cannot be read all answer
+     *  `ok: false` (the last with status 500 `server-error`). */
+    authenticate(req: HeadersCarrier, opts?: AuthenticateOptions): Promise<AuthResult>;
     /** A session token for `userid`. */
     mintSession(userid: string): {
         token: string;
@@ -271,6 +368,10 @@ export interface ServiceRequest {
     headers: Record<string, string | string[] | undefined>;
     /** The parsed JSON body of a POST. */
     body?: unknown;
+    /** The client's address, for the rate limit. The adapters fill it in. */
+    ip?: string | null;
+    /** The framework's own request object, when an adapter made this one. */
+    raw?: unknown;
 }
 export interface ServiceResponse {
     status: number;
@@ -287,6 +388,7 @@ export interface Handlers {
     logout: RouteHandler;
     register: RouteHandler;
 }
+export type RouteName = keyof Handlers;
 export interface AdapterOptions {
     /** Where the routes are mounted. Default "/api/auth". */
     prefix?: string;
@@ -449,8 +551,10 @@ export interface Agent {
 export interface BeagleServiceConfig {
     /** Exact origins the site's pages are served from, e.g. "https://your.app"
      *  (scheme, host, port). No suffix matching. `http://localhost:3000` only
-     *  when it is listed. */
-    origins: string[];
+     *  when it is listed. A function is called on each request, for a list that
+     *  changes while the server runs; `auth.setOrigins()` does the same from
+     *  outside. A malformed entry throws when the service is created. */
+    origins: OriginsSource;
     /** Where the library keeps its files. Default "./data". */
     dataDir?: string;
     /** Users backend. Default: `<dataDir>/users.json`. */
@@ -459,7 +563,15 @@ export interface BeagleServiceConfig {
     state?: StateStore;
     /** Signs sessions and nonces. Default: generated into `<dataDir>/session-secret`. */
     sessionSecret?: string;
+    /** A name for this server among several that have one `sessionSecret` and
+     *  cannot share a `state` store. A nonce is then accepted only by the server
+     *  that issued it; sessions stay valid on all of them. */
+    serverId?: string;
     session?: SessionConfig;
+    /** Limit on sign-in and launch attempts. false turns it off. */
+    rateLimit?: RateLimitConfig | false;
+    /** The site's part of a sign-in, before the answer goes out. */
+    onSignIn?: SignInHook;
     register?: RegisterConfig;
     visitor?: VisitorConfig;
     /** Import the userid's beagles.eth record after sign-in. true, or the gateway and cache time. */
@@ -489,8 +601,41 @@ export interface BeagleService {
     expressHandler(opts?: AdapterOptions): NodeHandler;
     /** For `pages/api/auth/[...beagle].js` in Next.js: `export default svc.nextApiHandler()`. */
     nextApiHandler(opts?: AdapterOptions): NodeHandler;
+    /** One route as a `(req, res)` handler, whatever path it is mounted on: for
+     *  a site that gives each route its own file (beside NextAuth's catch-all,
+     *  or under names of its own). */
+    route(name: RouteName): NodeHandler;
     /** For Web `Request`/`Response` hosts, such as Next.js App Router route handlers. */
     fetchHandler(opts?: AdapterOptions): (request: Request) => Promise<Response>;
     /** Stop the agent and timers. */
     close(): Promise<void>;
 }
+/** A service that is created on first use and kept for the life of the
+ *  process, whoever asks for it and however often the module that asks is
+ *  evaluated. Nothing here throws at the caller for a service that cannot
+ *  start, except `ready()`. */
+export interface SharedBeagleService {
+    /** The service. Rejects when it cannot be created (a malformed `origins`
+     *  entry, a users file that does not parse); the failure is not kept, the
+     *  next call tries again. Await it at start to find a bad configuration
+     *  before the first request. */
+    ready(): Promise<BeagleService>;
+    /** `auth.authenticate` of the service. Never rejects: when the service
+     *  cannot start it answers `ok: false`, status 500. */
+    authenticate(req: HeadersCarrier, opts?: AuthenticateOptions): Promise<AuthResult>;
+    /** As on the service; they answer 500 `server-error` while it cannot start. */
+    handle: RouteHandler;
+    route(name: RouteName): NodeHandler;
+    nodeHandler(opts?: AdapterOptions): NodeHandler;
+    expressHandler(opts?: AdapterOptions): NodeHandler;
+    nextApiHandler(opts?: AdapterOptions): NodeHandler;
+    fetchHandler(opts?: AdapterOptions): (request: Request) => Promise<Response>;
+    /** Close the service if it was created, and forget it. */
+    close(): Promise<void>;
+}
+export interface SharedOptions {
+    /** A process may hold several services under different keys. Default "default". */
+    key?: string;
+    /** After a failed start, wait this long before trying again. Default 5000. */
+    retryMs?: number;
+}

package/dist/users.js

@@ -1,4 +1,4 @@
-import { addressOf, Hub, isUserid, KeyedLock, msgOf } from "./util.js";
+import { addressOf, Hub, isThenable, isUserid, KeyedLock, msgOf } from "./util.js";
 export const DEFAULT_PROFILE_GATEWAY = "https://ens-gateway.beaglechat.workers.dev";
 const DAY_MS = 86_400_000;
 const TOUCH_EVERY_MS = 60_000;
@@ -50,6 +50,67 @@ export function createUsers(opts) {
         visits: 0,
         signIns: 0,
     });
+    /** What the store handed back, as a record this library can work with. A
+     *  store may hold records that are older than the library, or that another
+     *  program wrote: all that is asked of one is that it is an object. Missing
+     *  fields get the value a new record would have; nothing is written. */
+    function normalise(raw, userid) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return null;
+        const r = raw;
+        const u = { ...blank(typeof r.userid === "string" && r.userid ? r.userid : userid) };
+        for (const [k, v] of Object.entries(r))
+            if (v !== undefined && k !== "userid")
+                u[k] = v;
+        if (u.status !== "visitor" && u.status !== "registered" && u.status !== "blocked")
+            u.status = "visitor";
+        if (!u.profile || typeof u.profile !== "object" || Array.isArray(u.profile))
+            u.profile = {};
+        if (typeof u.visits !== "number" || !(u.visits >= 0))
+            u.visits = 0;
+        if (typeof u.signIns !== "number" || !(u.signIns >= 0))
+            u.signIns = 0;
+        if (typeof u.firstSeen !== "string" || Number.isNaN(Date.parse(u.firstSeen)))
+            u.firstSeen = null;
+        if (typeof u.lastSeen !== "string" || Number.isNaN(Date.parse(u.lastSeen)))
+            u.lastSeen = null;
+        return u;
+    }
+    /** The top-level fields in which `next` differs from `prev`. */
+    function changeOf(prev, next) {
+        const set = {};
+        const unset = [];
+        for (const [k, v] of Object.entries(next)) {
+            if (v === undefined)
+                continue;
+            if (!prev || JSON.stringify(prev[k]) !== JSON.stringify(v))
+                set[k] = v;
+        }
+        if (prev)
+            for (const k of Object.keys(prev))
+                if (next[k] === undefined && prev[k] !== undefined)
+                    unset.push(k);
+        return { prev, set, unset };
+    }
+    /** Read one record, let `step` decide, write what it decided. One at a time
+     *  per userid in this object; and with a store whose `get` and `put` are
+     *  synchronous, with nothing at all between the read and the write. The
+     *  store gets the changed fields beside the record, so it can leave alone
+     *  what somebody else wrote. */
+    function mutate(userid, step) {
+        const apply = (raw) => {
+            const prev = normalise(raw, userid);
+            const { next, out } = step(prev);
+            if (!next)
+                return out;
+            const done = store.put(next, changeOf(prev, next));
+            return isThenable(done) ? done.then(() => out) : out;
+        };
+        return lock.run(userid, () => {
+            const got = store.get(userid);
+            return isThenable(got) ? got.then(apply) : apply(got);
+        });
+    }
     const missingOf = (profile) => required.filter((f) => isEmpty(profile?.[f]));
     /** visitor or registered, from what the profile holds today. */
     const statusFor = (user) => (missingOf(user.profile).length === 0 ? "registered" : "visitor");
@@ -75,9 +136,14 @@ export function createUsers(opts) {
         state.refused = over && visitor.then === "refuse";
         return state;
     }
-    const get = async (userid) => (await store.get(userid)) ?? null;
+    const get = async (userid) => normalise(await store.get(userid), userid);
     async function list(filter) {
-        const all = await store.list();
+        const all = [];
+        for (const raw of await store.list()) {
+            const u = typeof raw?.userid === "string" ? normalise(raw, raw.userid) : null;
+            if (u)
+                all.push(u);
+        }
         return filter?.status ? all.filter((u) => u.status === filter.status) : all;
     }
     function emitLater(event, ...args) {
@@ -89,12 +155,11 @@ export function createUsers(opts) {
     async function recordSignIn(userid, hints = {}, info = {}) {
         if (!isUserid(userid))
             throw new TypeError("beagle-service: not a userid");
-        const events = [];
-        const user = await lock.run(userid, async () => {
-            const prev = await get(userid);
+        const t = now();
+        const { user, events } = await mutate(userid, (prev) => {
+            const events = [];
             if (prev?.status === "blocked")
-                return prev;
-            const t = now();
+                return { out: { user: prev, events } };
             const next = { ...blank(userid), ...prev };
             const first = !prev || !prev.firstSeen;
             // A blank or malformed hint never replaces a value already held: the
@@ -113,6 +178,9 @@ export function createUsers(opts) {
             }
             if (info.door)
                 next.door = info.door.slice(0, 200);
+            const origin = typeof info.origin === "string" && info.origin ? info.origin.slice(0, 200) : null;
+            if (origin)
+                next.origin = origin;
             next.firstSeen ??= iso(t);
             if (!prev?.lastSeen || t - Date.parse(prev.lastSeen) > gapMs)
                 next.visits = (next.visits || 0) + 1;
@@ -122,13 +190,13 @@ export function createUsers(opts) {
             next.status = statusFor(next);
             if (next.status === "registered")
                 next.registeredAt ??= iso(t);
-            await store.put(next);
-            lastTouch.set(userid, t);
-            events.push(() => emitLater("sign-in", next, { first, door: next.door }));
+            events.push(() => emitLater("sign-in", next, { first, door: next.door, origin }));
             if (next.status === "registered" && was !== "registered")
                 events.push(() => emitLater("registered", next));
-            return next;
+            return { next, out: { user: next, events } };
         });
+        if (events.length)
+            lastTouch.set(userid, t);
         for (const fire of events)
             fire();
         if (opts.importProfile && user.status !== "blocked")
@@ -139,24 +207,23 @@ export function createUsers(opts) {
         const t = now();
         if (t - (lastTouch.get(userid) ?? 0) < TOUCH_EVERY_MS)
             return get(userid);
-        return lock.run(userid, async () => {
-            const prev = await get(userid);
+        return mutate(userid, (prev) => {
             if (!prev || prev.status === "blocked")
-                return prev;
+                return { out: prev };
             lastTouch.set(userid, t);
+            // Another process, or another copy of this object, may have noted it.
+            if (prev.lastSeen && Math.abs(t - Date.parse(prev.lastSeen)) < TOUCH_EVERY_MS)
+                return { out: prev };
             const next = { ...prev, lastSeen: iso(t) };
             if (!prev.lastSeen || t - Date.parse(prev.lastSeen) > gapMs)
                 next.visits = (prev.visits || 0) + 1;
-            await store.put(next);
-            return next;
+            return { next, out: next };
         });
     }
     async function update(userid, patch) {
         if (patch.status === "blocked")
             throw new TypeError("beagle-service: use users.block(userid, why) to block");
-        const events = [];
-        const user = await lock.run(userid, async () => {
-            const prev = await get(userid);
+        const { user, fire } = await mutate(userid, (prev) => {
             if (!prev)
                 throw new Error(`beagle-service: no user ${userid}`);
             if (prev.status === "blocked" && patch.status)
@@ -167,15 +234,13 @@ export function createUsers(opts) {
                 userid: prev.userid,
                 profile: patch.profile ? { ...prev.profile, ...patch.profile } : prev.profile,
             };
-            if (next.status === "registered" && prev.status !== "registered") {
+            const fire = next.status === "registered" && prev.status !== "registered";
+            if (fire)
                 next.registeredAt ??= iso(now());
-                events.push(() => emitLater("registered", next));
-            }
-            await store.put(next);
-            return next;
+            return { next, out: { user: next, fire } };
         });
-        for (const fire of events)
-            fire();
+        if (fire)
+            emitLater("registered", user);
         return user;
     }
     async function register(userid, submitted) {
@@ -235,37 +300,32 @@ export function createUsers(opts) {
             }
             accepted[field] = value;
         }
-        const events = [];
-        const result = await lock.run(userid, async () => {
-            const prev = await get(userid);
+        const { result, fire } = await mutate(userid, (prev) => {
+            const no = (result) => ({ out: { result, fire: false } });
             if (!prev)
-                return { ok: false, error: "not-found" };
+                return no({ ok: false, error: "not-found" });
             if (prev.status === "blocked")
-                return { ok: false, error: "blocked" };
+                return no({ ok: false, error: "blocked" });
             const profile = { ...prev.profile, ...accepted };
             for (const f of missingOf(profile))
                 errors[f] ??= "required";
             if (Object.keys(errors).length)
-                return { ok: false, error: "invalid-fields", fields: errors };
+                return no({ ok: false, error: "invalid-fields", fields: errors });
             const next = { ...prev, profile, status: "registered" };
             next.registeredAt ??= iso(now());
-            await store.put(next);
-            if (prev.status !== "registered")
-                events.push(() => emitLater("registered", next));
-            return { ok: true, user: next };
+            return { next, out: { result: { ok: true, user: next }, fire: prev.status !== "registered" } };
         });
-        for (const fire of events)
-            fire();
+        if (fire && result.ok)
+            emitLater("registered", result.user);
         return result;
     }
     async function block(userid, why = "") {
         if (!isUserid(userid))
             throw new TypeError("beagle-service: not a userid");
-        let fire = false;
-        const user = await lock.run(userid, async () => {
-            const prev = (await get(userid)) ?? blank(userid);
+        const { user, fire } = await mutate(userid, (found) => {
+            const prev = found ?? blank(userid);
             if (prev.status === "blocked")
-                return prev;
+                return { out: { user: prev, fire: false } };
             const t = now();
             const next = {
                 ...prev,
@@ -274,36 +334,26 @@ export function createUsers(opts) {
                 // Sessions issued up to now are dead for good, also after an unblock.
                 sessionsValidFrom: t + 1,
             };
-            await store.put(next);
-            fire = true;
-            return next;
+            return { next, out: { user: next, fire: true } };
         });
         if (fire)
             emitLater("blocked", user);
         return user;
     }
     async function unblock(userid) {
-        let fire = false;
-        const user = await lock.run(userid, async () => {
-            const prev = await get(userid);
+        const { user, fire } = await mutate(userid, (prev) => {
             if (!prev || prev.status !== "blocked")
-                return prev;
+                return { out: { user: prev, fire: false } };
             const next = { ...prev, blocked: null, status: "visitor" };
             next.status = prev.blocked?.was === "registered" || (prev.firstSeen && statusFor(next) === "registered") ? "registered" : "visitor";
-            await store.put(next);
-            fire = true;
-            return next;
+            return { next, out: { user: next, fire: true } };
         });
         if (fire && user)
             emitLater("unblocked", user);
         return user;
     }
     async function revokeSessions(userid) {
-        await lock.run(userid, async () => {
-            const prev = await get(userid);
-            if (prev)
-                await store.put({ ...prev, sessionsValidFrom: now() + 1 });
-        });
+        await mutate(userid, (prev) => (prev ? { next: { ...prev, sessionsValidFrom: now() + 1 }, out: undefined } : { out: undefined }));
     }
     // ── beagles.eth profile import ────────────────────────────────────────────
     const gateway = (typeof opts.importProfile === "object" && opts.importProfile.gateway) || DEFAULT_PROFILE_GATEWAY;

package/dist/util.d.ts

@@ -5,6 +5,26 @@ export declare function atomicWriteJson(file: string, value: unknown, mode?: num
  *  does not parse throws, because treating it as empty would let the next
  *  write replace real data with nothing. */
 export declare function readJsonFile<T>(file: string, fallback: T): T;
+/** One JSON object in one file, shared by every store instance and every
+ *  process that opens it (a server and the operator's command beside it, or a
+ *  module a bundler evaluated twice). A read looks at the file's identity
+ *  first and loads it again when another writer replaced it; a change is made
+ *  under a lock file, on the copy that is on disk at that moment, and written
+ *  with a rename. All of it is synchronous: no other code of this process runs
+ *  between the read and the write. */
+export declare class SharedJsonFile<T extends Record<string, any>> {
+    #private;
+    constructor(file: string);
+    /** The current content. Do not change it; use `update`. */
+    read(): T;
+    /** Change the content. `change` gets what is on disk now and says whether
+     *  it has to be written. */
+    update<R>(change: (value: T) => {
+        write: boolean;
+        result: R;
+    }): R;
+}
+export declare const isThenable: <T>(v: T | PromiseLike<T>) => v is PromiseLike<T>;
 /** A userid is the base58 of a 32-byte public key. */
 export declare function isUserid(v: unknown): v is string;
 /** The address when it is a well-formed Carrier address of `userid`, else null.
@@ -21,8 +41,8 @@ export declare class Hub<Events extends Record<string, unknown[]>> {
     /** Runs listeners in registration order and waits for each. */
     emit<K extends keyof Events>(event: K, ...args: Events[K]): Promise<void>;
 }
-/** Run async jobs for the same key one after another. */
+/** Run jobs for the same key one after another. */
 export declare class KeyedLock {
     #private;
-    run<T>(key: string, job: () => Promise<T>): Promise<T>;
+    run<T>(key: string, job: () => T | PromiseLike<T>): Promise<T>;
 }