@decentnetwork/beagle-service 0.1.0 → 0.2.0

package/dist/routes.d.ts

@@ -1,4 +1,4 @@
-import type { AdapterOptions, Agent, Auth, Handlers, NodeHandler, RouteHandler, SessionConfig, UserRecord, Users } from "./types.js";
+import type { AdapterOptions, Agent, Auth, Handlers, NodeHandler, RateLimitConfig, RouteHandler, RouteName, ServiceRequest, SessionConfig, SignInHook, UserRecord, Users } from "./types.js";
 import { type Logger } from "./util.js";
 /** The library's own fields only: a site's extra fields (a plan, notes) do
  *  not reach the page unless the site says so with `publicUser`. */
@@ -8,9 +8,16 @@ export interface RoutesOptions {
     users: Users;
     session?: SessionConfig;
     publicUser?: (user: UserRecord) => Record<string, unknown>;
+    onSignIn?: SignInHook;
+    rateLimit?: RateLimitConfig | false;
     agent: () => Agent | undefined;
     log: Logger;
+    now?: () => number;
 }
+/** Counts sign-in and launch attempts in fixed windows, per client and for
+ *  all clients together. Returns the seconds to wait when a request is over
+ *  the limit, else 0. In memory: each server process counts for itself. */
+export declare function createRateLimit(config: RateLimitConfig | false | undefined, now: () => number): (req: ServiceRequest) => number;
 export declare function createRoutes(opts: RoutesOptions): {
     handle: RouteHandler;
     handlers: Handlers;
@@ -18,4 +25,5 @@ export declare function createRoutes(opts: RoutesOptions): {
     expressHandler: (o?: AdapterOptions) => NodeHandler;
     nextApiHandler: (o?: AdapterOptions) => NodeHandler;
     fetchHandler: (o?: AdapterOptions) => (request: Request) => Promise<Response>;
+    route: (name: RouteName) => NodeHandler;
 };

package/dist/routes.js

@@ -10,6 +10,8 @@ const MESSAGES = {
     "launch-replayed": "This launch assertion was already used.",
     blocked: "This identity may not use the site.",
     "register-required": "Registration is required to go on.",
+    "sign-in-refused": "This site did not accept the sign-in.",
+    "rate-limited": "Too many sign-in attempts. Try again shortly.",
     "not-signed-in": "Not signed in.",
     "invalid-fields": "Some registration fields are missing or not accepted.",
     "not-found": "No such route.",
@@ -23,10 +25,61 @@ export function defaultPublicUser(user) {
     const { userid, address, name, avatar, punkId, door, status, profile, firstSeen, lastSeen } = user;
     return { userid, address, name, avatar, punkId, door, status, profile, firstSeen, lastSeen };
 }
+const LOOPBACK = /^(127\.|::1$|::ffff:127\.)/;
+/** Counts sign-in and launch attempts in fixed windows, per client and for
+ *  all clients together. Returns the seconds to wait when a request is over
+ *  the limit, else 0. In memory: each server process counts for itself. */
+export function createRateLimit(config, now) {
+    if (config === false)
+        return () => 0;
+    const cfg = config ?? {};
+    const windowMs = Math.max(1, cfg.windowSeconds ?? 60) * 1000;
+    const perClient = cfg.perClient ?? 30;
+    const total = cfg.total ?? 600;
+    const hops = cfg.trustProxy === true ? 1 : typeof cfg.trustProxy === "number" ? Math.max(0, Math.floor(cfg.trustProxy)) : 0;
+    const windows = new Map();
+    function clientOf(req) {
+        if (cfg.key)
+            return cfg.key(req) || null;
+        if (hops > 0) {
+            // Each proxy appends the address it saw; the entry `hops` from the
+            // right is the one written by the outermost proxy we trust.
+            const list = String(headerOf(req, "x-forwarded-for") ?? "").split(",").map((x) => x.trim()).filter(Boolean);
+            const seen = list[list.length - hops];
+            if (seen)
+                return seen;
+        }
+        const ip = typeof req.ip === "string" ? req.ip : "";
+        // A connection from this machine is a proxy in front of the server, or
+        // the operator: one address standing for everybody is not a client.
+        return ip && !LOOPBACK.test(ip) ? ip : null;
+    }
+    function over(key, max, t) {
+        let w = windows.get(key);
+        if (!w || t - w.start >= windowMs)
+            windows.set(key, (w = { start: t, n: 0 }));
+        if (w.n >= max)
+            return Math.max(1, Math.ceil((w.start + windowMs - t) / 1000));
+        w.n++;
+        return 0;
+    }
+    return (req) => {
+        const t = now();
+        if (windows.size > 20_000)
+            for (const [k, w] of windows)
+                if (t - w.start >= windowMs)
+                    windows.delete(k);
+        const who = clientOf(req);
+        // A client over its own limit is turned away before it can use up the
+        // allowance everybody shares.
+        return (who ? over(`c:${who}`, perClient, t) : 0) || over("*", total, t);
+    };
+}
 export function createRoutes(opts) {
     const { auth, users, log } = opts;
     const transport = opts.session?.transport ?? "cookie";
     const publicUser = opts.publicUser ?? defaultPublicUser;
+    const limited = createRateLimit(opts.rateLimit, opts.now ?? Date.now);
     const lower = (req) => {
         const headers = {};
         for (const [k, v] of Object.entries(req.headers ?? {}))
@@ -53,7 +106,8 @@ export function createRoutes(opts) {
         headers: { ...baseHeaders(req), ...extra },
         body,
     });
-    const refuse = (req, status, error, more = {}, extra = {}) => answer(req, status, { ok: false, error, message: MESSAGES[error], ...more }, extra);
+    // `ok`, `error` and `message` come first and are the library's, whatever `more` holds.
+    const refuse = (req, status, error, more = {}, extra = {}) => answer(req, status, Object.assign({ ok: false, error, message: MESSAGES[error] }, more, { ok: false, error, message: MESSAGES[error] }), extra);
     const agentInfo = () => {
         const a = opts.agent();
         return a ? { agent: { userid: a.userid, address: a.address, name: a.nickname ?? null } } : {};
@@ -68,20 +122,44 @@ export function createRoutes(opts) {
         const req = lower(raw);
         return wrongMethod(req, "GET") ?? answer(req, 200, { ok: true, nonce: auth.issueNonce(), expiresIn: 120 });
     };
+    const isRefusal = (r) => !!r && typeof r === "object" && !!r.refuse;
     async function establish(req, v) {
         if (!v.ok)
             return refuse(req, v.status, v.error);
+        const origin = auth.allowedOrigin(req);
         const known = await users.get(v.userid);
         if (known?.status === "blocked")
             return refuse(req, 403, "blocked");
-        const user = await users.recordSignIn(v.userid, v.hints, { door: v.door });
+        let user = await users.recordSignIn(v.userid, v.hints, { door: v.door, origin });
         if (user.status === "blocked")
             return refuse(req, 403, "blocked");
+        // The site's part, before any session exists: it may add to the answer,
+        // or refuse. The record is written by now (the hook can store on it).
+        let own = {};
+        if (opts.onSignIn) {
+            const r = await opts.onSignIn(user, {
+                origin: origin ?? "",
+                door: user.door,
+                route: v.door === "launch" ? "launch" : "sign-in",
+                first: !known || !known.firstSeen,
+                request: req,
+            });
+            if (isRefusal(r)) {
+                const error = typeof r.refuse === "string" ? r.refuse : "sign-in-refused";
+                return answer(req, r.status ?? 403, { ok: false, error, message: r.message ?? MESSAGES["sign-in-refused"] });
+            }
+            if (r && typeof r === "object")
+                own = r;
+            // What the hook stored on the record belongs in the answer too.
+            user = (await users.get(user.userid)) ?? user;
+            if (user.status === "blocked")
+                return refuse(req, 403, "blocked");
+        }
         const session = auth.mintSession(user.userid);
         const registration = users.registration(user);
         const extra = {};
         if (transport !== "bearer")
-            extra["set-cookie"] = [auth.cookie(session.token, auth.allowedOrigin(req))];
+            extra["set-cookie"] = [auth.cookie(session.token, origin)];
         const body = {
             user: publicUser(user),
             registration,
@@ -92,17 +170,22 @@ export function createRoutes(opts) {
         // A visitor past the limit under `then: "refuse"` is told 403, and still
         // gets the session: without it they could never prove who is registering.
         // That session opens `register`, `logout` and nothing else.
+        // The site's fields first: the library's own are never replaced by them.
         if (registration.refused)
-            return refuse(req, 403, "register-required", body, extra);
-        return answer(req, 200, { ok: true, ...body }, extra);
+            return refuse(req, 403, "register-required", { ...own, ...body }, extra);
+        return answer(req, 200, Object.assign({ ok: true }, own, body, { ok: true }), extra);
     }
+    const tooMany = (req) => {
+        const wait = limited(req);
+        return wait ? refuse(req, 429, "rate-limited", {}, { "retry-after": String(wait) }) : null;
+    };
     const signIn = async (raw) => {
         const req = lower(raw);
-        return wrongMethod(req, "POST") ?? establish(req, await auth.verifySignIn(auth.allowedOrigin(req), req.body));
+        return wrongMethod(req, "POST") ?? tooMany(req) ?? establish(req, await auth.verifySignIn(auth.allowedOrigin(req), req.body));
     };
     const launch = async (raw) => {
         const req = lower(raw);
-        return wrongMethod(req, "POST") ?? establish(req, await auth.verifyLaunch(auth.allowedOrigin(req), req.body));
+        return wrongMethod(req, "POST") ?? tooMany(req) ?? establish(req, await auth.verifyLaunch(auth.allowedOrigin(req), req.body));
     };
     const me = async (raw) => {
         const req = lower(raw);
@@ -153,7 +236,34 @@ export function createRoutes(opts) {
         }
         return answer(req, 200, { ok: true, user: publicUser(r.user), registration: users.registration(r.user), ...agentInfo() });
     };
-    const handlers = { nonce, signIn, launch, me, logout, register };
+    /** A route answers; it does not throw at the site that called it. */
+    const guarded = (name, route) => async (raw) => {
+        try {
+            return await route(raw);
+        }
+        catch (e) {
+            log(`beagle-service: ${name} failed: ${e?.stack ?? msgOf(e)}`);
+            return refuse(lower(raw), 500, "server-error");
+        }
+    };
+    const handlers = {
+        nonce: guarded("nonce", nonce),
+        signIn: guarded("sign-in", signIn),
+        launch: guarded("launch", launch),
+        me: guarded("me", me),
+        logout: guarded("logout", logout),
+        register: guarded("register", register),
+    };
+    const preflight = (req) => ({
+        status: 204,
+        headers: {
+            ...baseHeaders(req),
+            "access-control-allow-methods": "GET, POST, OPTIONS",
+            "access-control-allow-headers": "content-type, authorization",
+            "access-control-max-age": "600",
+        },
+        body: null,
+    });
     // `/beagle` and `/beagle-launch` are the paths the Sign in with Beagle
     // guide uses; a page written from it works unchanged.
     const table = {
@@ -173,18 +283,8 @@ export function createRoutes(opts) {
             const route = table[path];
             if (!route)
                 return refuse(req, 404, "not-found");
-            if (req.method === "OPTIONS") {
-                return {
-                    status: 204,
-                    headers: {
-                        ...baseHeaders(req),
-                        "access-control-allow-methods": "GET, POST, OPTIONS",
-                        "access-control-allow-headers": "content-type, authorization",
-                        "access-control-max-age": "600",
-                    },
-                    body: null,
-                };
-            }
+            if (req.method === "OPTIONS")
+                return preflight(req);
             return await route(req);
         }
         catch (e) {
@@ -253,10 +353,42 @@ export function createRoutes(opts) {
     }
     function write(res, r) {
         res.statusCode = r.status;
-        for (const [k, v] of Object.entries(r.headers))
-            res.setHeader(k, v);
+        for (const [k, v] of Object.entries(r.headers)) {
+            // A cookie the site set on this response before calling us stays.
+            const held = k === "set-cookie" && typeof res.getHeader === "function" ? res.getHeader("set-cookie") : undefined;
+            res.setHeader(k, held ? [].concat(held, v) : v);
+        }
         res.end(r.body === null ? undefined : JSON.stringify(r.body));
     }
+    /** Express computes `req.ip` from its own "trust proxy" setting; elsewhere
+     *  it is the address of the connection. */
+    const ipOf = (req) => (typeof req.ip === "string" && req.ip) || req.socket?.remoteAddress || req.connection?.remoteAddress || null;
+    /** One route, whatever path the framework mounted it on. */
+    function routeHandler(name) {
+        const route = handlers[name];
+        if (!route)
+            throw new TypeError(`beagle-service: no route "${String(name)}"; the routes are ${Object.keys(handlers).join(", ")}`);
+        return async (req, res) => {
+            const headers = req.headers ?? {};
+            try {
+                if (req.method === "OPTIONS")
+                    return write(res, preflight(lower({ method: "OPTIONS", headers })));
+                let body;
+                if (req.method === "POST") {
+                    const b = await readBody(req);
+                    if (!b.ok)
+                        return write(res, refuse(lower({ method: req.method, headers }), b.status, b.error));
+                    body = b.body;
+                }
+                write(res, await route({ method: req.method, headers, body, ip: ipOf(req), raw: req }));
+            }
+            catch (e) {
+                log(`beagle-service: ${req.method} ${req.url} failed: ${e?.stack ?? msgOf(e)}`);
+                if (!res.headersSent)
+                    write(res, refuse(lower({ method: req.method, headers }), 500, "server-error"));
+            }
+        };
+    }
     function nodeAdapter(o, fallThrough) {
         const prefix = o.prefix ?? "/api/auth";
         return async (req, res, next) => {
@@ -276,7 +408,7 @@ export function createRoutes(opts) {
                         return write(res, refuse(lower({ method: req.method, headers }), b.status, b.error));
                     body = b.body;
                 }
-                write(res, await handle({ method: req.method, path, headers, body }));
+                write(res, await handle({ method: req.method, path, headers, body, ip: ipOf(req), raw: req }));
             }
             catch (e) {
                 log(`beagle-service: ${req.method} ${req.url} failed: ${e?.stack ?? msgOf(e)}`);
@@ -307,7 +439,7 @@ export function createRoutes(opts) {
                     return reply(refuse(lower({ method: request.method, headers }), b.status, b.error));
                 body = b.body;
             }
-            return reply(await handle({ method: request.method, path, headers, body }));
+            return reply(await handle({ method: request.method, path, headers, body, raw: request }));
         };
     }
     return {
@@ -317,5 +449,6 @@ export function createRoutes(opts) {
         expressHandler: (o = {}) => nodeAdapter(o, true),
         nextApiHandler: (o = {}) => nodeAdapter(o, false),
         fetchHandler,
+        route: routeHandler,
     };
 }

package/dist/stores.d.ts

@@ -1,12 +1,20 @@
-import type { StateStore, UserStore } from "./types.js";
+import type { StateStore, UserChange, UserRecord, UserStore } from "./types.js";
+/** `record` with the fields a change names set or removed, and every other
+ *  field as it is. What a store does with the second argument of `put`. */
+export declare function applyUserChange(record: UserRecord, change: Pick<UserChange, "set" | "unset">): UserRecord;
 /** Users in one JSON file, `{ [userid]: record }`, rewritten atomically on
- *  every change. The whole table is held in memory; good for a site with up to
- *  some tens of thousands of users and one server process. */
+ *  every change. The whole table is held in memory and read again when the
+ *  file was replaced by another writer, so the operator's command, or a second
+ *  store on the same file, works beside a running server. A change is applied
+ *  field by field to the record that is on disk at that moment. Good for a
+ *  site with up to some tens of thousands of users on one machine. */
 export declare function jsonFileUserStore(file: string): UserStore;
 /** Users in memory; gone when the process ends. For tests. */
 export declare function memoryUserStore(): UserStore;
 /** Used nonces, used launch assertions and revoked sessions in one JSON file,
- *  written atomically before each answer. One server process. */
+ *  written atomically before each answer. Like the users file it is read again
+ *  when another writer replaced it, so two stores on one file (a module
+ *  evaluated twice, two processes on one machine) see each other's entries. */
 export declare function jsonFileStateStore(file: string, now?: () => number): StateStore;
 /** The same in memory. A restart forgets it, which reopens launch replay for
  *  two minutes; for tests. */

package/dist/stores.js

@@ -1,21 +1,33 @@
-import { atomicWriteJson, readJsonFile } from "./util.js";
+import { SharedJsonFile } from "./util.js";
+const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+/** `record` with the fields a change names set or removed, and every other
+ *  field as it is. What a store does with the second argument of `put`. */
+export function applyUserChange(record, change) {
+    const next = { ...record, ...structuredClone(change.set) };
+    for (const k of change.unset)
+        delete next[k];
+    return next;
+}
 // ── users ───────────────────────────────────────────────────────────────────
 /** Users in one JSON file, `{ [userid]: record }`, rewritten atomically on
- *  every change. The whole table is held in memory; good for a site with up to
- *  some tens of thousands of users and one server process. */
+ *  every change. The whole table is held in memory and read again when the
+ *  file was replaced by another writer, so the operator's command, or a second
+ *  store on the same file, works beside a running server. A change is applied
+ *  field by field to the record that is on disk at that moment. Good for a
+ *  site with up to some tens of thousands of users on one machine. */
 export function jsonFileUserStore(file) {
-    const users = new Map(Object.entries(readJsonFile(file, {})));
-    const flush = () => atomicWriteJson(file, Object.fromEntries(users));
+    const shared = new SharedJsonFile(file);
     return {
         get: (userid) => {
-            const u = users.get(userid);
-            return u ? structuredClone(u) : null;
-        },
-        put: (user) => {
-            users.set(user.userid, structuredClone(user));
-            flush();
+            const table = shared.read();
+            return has(table, userid) ? structuredClone(table[userid]) : null;
         },
-        list: () => [...users.values()].map((u) => structuredClone(u)),
+        put: (user, change) => shared.update((table) => {
+            const current = has(table, user.userid) ? table[user.userid] : null;
+            table[user.userid] = current && change ? applyUserChange(current, change) : structuredClone(user);
+            return { write: true, result: undefined };
+        }),
+        list: () => Object.values(shared.read()).map((u) => structuredClone(u)),
     };
 }
 /** Users in memory; gone when the process ends. For tests. */
@@ -30,40 +42,51 @@ export function memoryUserStore() {
         list: () => [...users.values()].map((u) => structuredClone(u)),
     };
 }
-function setStore(load, save, now) {
-    const sets = load();
-    const prune = () => {
-        const t = now();
-        for (const ns of Object.keys(sets)) {
-            for (const [k, exp] of Object.entries(sets[ns]))
-                if (exp < t)
-                    delete sets[ns][k];
-        }
-    };
+function prune(sets, t) {
+    for (const ns of Object.keys(sets)) {
+        for (const [k, exp] of Object.entries(sets[ns]))
+            if (exp < t)
+                delete sets[ns][k];
+    }
+}
+/** Used nonces, used launch assertions and revoked sessions in one JSON file,
+ *  written atomically before each answer. Like the users file it is read again
+ *  when another writer replaced it, so two stores on one file (a module
+ *  evaluated twice, two processes on one machine) see each other's entries. */
+export function jsonFileStateStore(file, now = Date.now) {
+    const shared = new SharedJsonFile(file);
     return {
-        addOnce(ns, key, expiresAt) {
-            prune();
+        addOnce: (ns, key, expiresAt) => shared.update((sets) => {
+            prune(sets, now());
             const set = (sets[ns] ??= {});
-            if (Object.prototype.hasOwnProperty.call(set, key))
-                return false;
+            if (has(set, key))
+                return { write: false, result: false };
             set[key] = expiresAt;
             // Written before the answer goes out: a restart must not forget it.
-            save(sets);
-            return true;
-        },
+            return { write: true, result: true };
+        }),
         has(ns, key) {
-            const exp = sets[ns]?.[key];
-            return exp !== undefined && exp >= now();
+            const set = shared.read()[ns];
+            return !!set && has(set, key) && set[key] >= now();
         },
     };
 }
-/** Used nonces, used launch assertions and revoked sessions in one JSON file,
- *  written atomically before each answer. One server process. */
-export function jsonFileStateStore(file, now = Date.now) {
-    return setStore(() => readJsonFile(file, {}), (s) => atomicWriteJson(file, s), now);
-}
 /** The same in memory. A restart forgets it, which reopens launch replay for
  *  two minutes; for tests. */
 export function memoryStateStore(now = Date.now) {
-    return setStore(() => ({}), () => { }, now);
+    const sets = {};
+    return {
+        addOnce(ns, key, expiresAt) {
+            prune(sets, now());
+            const set = (sets[ns] ??= {});
+            if (has(set, key))
+                return false;
+            set[key] = expiresAt;
+            return true;
+        },
+        has(ns, key) {
+            const set = sets[ns];
+            return !!set && has(set, key) && set[key] >= now();
+        },
+    };
 }