@decentnetwork/beagle-service 0.0.0-stage → 0.2.0

package/dist/routes.js

@@ -0,0 +1,454 @@
+import { headerOf } from "./auth.js";
+import { msgOf } from "./util.js";
+const MAX_BODY_BYTES = 64 * 1024;
+const MESSAGES = {
+    "origin-not-allowed": "This origin is not on the site's list.",
+    "bad-request": "The request body is not what this route expects.",
+    "bad-nonce": "The nonce is unknown, expired or already used. Ask for a new one.",
+    "bad-signature": "The signature did not verify.",
+    "launch-expired": "The launch assertion is more than two minutes from now.",
+    "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.",
+    "method-not-allowed": "Wrong method for this route.",
+    "too-large": "The request body is too large.",
+    "server-error": "The server could not answer.",
+};
+/** 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`. */
+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 ?? {}))
+            headers[k.toLowerCase()] = v;
+        return { ...req, method: String(req.method || "GET").toUpperCase(), headers };
+    };
+    function baseHeaders(req) {
+        const h = {
+            "content-type": "application/json; charset=utf-8",
+            "cache-control": "no-store",
+            vary: "Origin",
+        };
+        // CORS for the listed origins only, so a page on one origin can call an
+        // API on another (with the cookie, or with a bearer token).
+        const origin = auth.allowedOrigin(req);
+        if (origin) {
+            h["access-control-allow-origin"] = origin;
+            h["access-control-allow-credentials"] = "true";
+        }
+        return h;
+    }
+    const answer = (req, status, body, extra = {}) => ({
+        status,
+        headers: { ...baseHeaders(req), ...extra },
+        body,
+    });
+    // `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 } } : {};
+    };
+    const wrongMethod = (req, want) => (req.method === want ? null : refuse(req, 405, "method-not-allowed", {}, { allow: `${want}, OPTIONS` }));
+    /** A state-changing request must come from one of the site's pages (the
+     *  browser sets Origin; page script cannot), or carry a bearer token, which
+     *  no other site can make a browser send. */
+    const fromOurPage = (req) => auth.allowedOrigin(req) !== null || /^bearer /i.test(headerOf(req, "authorization") ?? "");
+    // ── the six routes ────────────────────────────────────────────────────────
+    const nonce = async (raw) => {
+        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");
+        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, origin)];
+        const body = {
+            user: publicUser(user),
+            registration,
+            expiresAt: new Date(session.expiresAt).toISOString(),
+            ...(transport !== "cookie" ? { token: session.token } : {}),
+            ...agentInfo(),
+        };
+        // 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", { ...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") ?? tooMany(req) ?? establish(req, await auth.verifySignIn(auth.allowedOrigin(req), req.body));
+    };
+    const launch = async (raw) => {
+        const req = lower(raw);
+        return wrongMethod(req, "POST") ?? tooMany(req) ?? establish(req, await auth.verifyLaunch(auth.allowedOrigin(req), req.body));
+    };
+    const me = async (raw) => {
+        const req = lower(raw);
+        const bad = wrongMethod(req, "GET");
+        if (bad)
+            return bad;
+        const who = await auth.authenticate(req);
+        if (!who.ok) {
+            const more = who.user ? { user: publicUser(who.user), registration: who.registration, ...agentInfo() } : {};
+            return refuse(req, who.status, who.error, more);
+        }
+        return answer(req, 200, { ok: true, user: publicUser(who.user), registration: who.registration, ...agentInfo() });
+    };
+    const logout = async (raw) => {
+        const req = lower(raw);
+        const bad = wrongMethod(req, "POST");
+        if (bad)
+            return bad;
+        if (!fromOurPage(req))
+            return refuse(req, 403, "origin-not-allowed");
+        const token = auth.tokenOf(req);
+        if (token)
+            await auth.revoke(token);
+        const extra = {};
+        if (transport !== "bearer")
+            extra["set-cookie"] = [auth.cookie(null, auth.allowedOrigin(req))];
+        return answer(req, 200, { ok: true }, extra);
+    };
+    const register = async (raw) => {
+        const req = lower(raw);
+        const bad = wrongMethod(req, "POST");
+        if (bad)
+            return bad;
+        if (!fromOurPage(req))
+            return refuse(req, 403, "origin-not-allowed");
+        const who = await auth.authenticate(req, { allowUnregistered: true });
+        if (!who.ok)
+            return refuse(req, who.status, who.error);
+        if (!req.body || typeof req.body !== "object")
+            return refuse(req, 400, "bad-request");
+        const b = req.body;
+        const submitted = b.profile && typeof b.profile === "object" ? b.profile : b;
+        const r = await users.register(who.user.userid, submitted);
+        if (!r.ok) {
+            if (r.error === "invalid-fields")
+                return refuse(req, 400, "invalid-fields", { fields: r.fields });
+            return refuse(req, r.error === "blocked" ? 403 : 401, r.error === "blocked" ? "blocked" : "not-signed-in");
+        }
+        return answer(req, 200, { ok: true, user: publicUser(r.user), registration: users.registration(r.user), ...agentInfo() });
+    };
+    /** 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 = {
+        "/nonce": nonce,
+        "/sign-in": signIn,
+        "/beagle": signIn,
+        "/launch": launch,
+        "/beagle-launch": launch,
+        "/me": me,
+        "/logout": logout,
+        "/register": register,
+    };
+    const handle = async (raw) => {
+        const req = lower(raw);
+        try {
+            const path = "/" + String(req.path ?? "").split("?")[0].replace(/^\/+|\/+$/g, "");
+            const route = table[path];
+            if (!route)
+                return refuse(req, 404, "not-found");
+            if (req.method === "OPTIONS")
+                return preflight(req);
+            return await route(req);
+        }
+        catch (e) {
+            log(`beagle-service: ${req.method} ${req.path} failed: ${e?.stack ?? msgOf(e)}`);
+            return refuse(req, 500, "server-error");
+        }
+    };
+    // ── adapters ──────────────────────────────────────────────────────────────
+    /** "/nonce" for "/api/auth/nonce" under prefix "/api/auth"; null outside it. */
+    function below(prefix, url) {
+        const p = "/" + prefix.replace(/^\/+|\/+$/g, "");
+        let pathname;
+        try {
+            pathname = new URL(url, "http://x").pathname;
+        }
+        catch {
+            return null;
+        }
+        if (p === "/")
+            return pathname;
+        if (pathname === p)
+            return "/";
+        return pathname.startsWith(p + "/") ? pathname.slice(p.length) : null;
+    }
+    function readBody(req) {
+        // Express (`express.json()`) and Next.js have parsed it already.
+        if (req.body !== undefined && req.body !== null && typeof req.body === "object" && !Buffer.isBuffer(req.body)) {
+            return Promise.resolve({ ok: true, body: req.body });
+        }
+        if (typeof req.body === "string" || Buffer.isBuffer(req.body))
+            return Promise.resolve(parse(String(req.body)));
+        return new Promise((resolve) => {
+            const chunks = [];
+            let size = 0;
+            let done = false;
+            const finish = (r) => {
+                if (!done) {
+                    done = true;
+                    resolve(r);
+                }
+            };
+            req.on("data", (c) => {
+                size += c.length;
+                if (size > MAX_BODY_BYTES) {
+                    finish({ ok: false, error: "too-large", status: 413 });
+                    req.resume?.();
+                }
+                else
+                    chunks.push(c);
+            });
+            req.on("end", () => finish(parse(Buffer.concat(chunks).toString("utf8"))));
+            req.on("error", () => finish({ ok: false, error: "bad-request", status: 400 }));
+        });
+    }
+    function parse(raw) {
+        if (raw.length > MAX_BODY_BYTES)
+            return { ok: false, error: "too-large", status: 413 };
+        if (raw.trim() === "")
+            return { ok: true, body: undefined };
+        try {
+            return { ok: true, body: JSON.parse(raw) };
+        }
+        catch {
+            return { ok: false, error: "bad-request", status: 400 };
+        }
+    }
+    function write(res, r) {
+        res.statusCode = r.status;
+        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) => {
+            const headers = req.headers ?? {};
+            // Express strips the mount path from `url`; `originalUrl` keeps it.
+            const path = below(prefix, req.originalUrl ?? req.url ?? "/");
+            if (path === null) {
+                if (fallThrough && typeof next === "function")
+                    return void next();
+                return write(res, refuse(lower({ method: req.method, headers }), 404, "not-found"));
+            }
+            try {
+                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 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)}`);
+                if (!res.headersSent)
+                    write(res, refuse(lower({ method: req.method, headers }), 500, "server-error"));
+            }
+        };
+    }
+    function fetchHandler(o = {}) {
+        const prefix = o.prefix ?? "/api/auth";
+        return async (request) => {
+            const headers = {};
+            request.headers.forEach((v, k) => (headers[k] = v));
+            const reply = (r) => {
+                const h = new Headers();
+                for (const [k, v] of Object.entries(r.headers))
+                    for (const one of Array.isArray(v) ? v : [v])
+                        h.append(k, one);
+                return new Response(r.body === null ? null : JSON.stringify(r.body), { status: r.status, headers: h });
+            };
+            const path = below(prefix, request.url);
+            if (path === null)
+                return reply(refuse(lower({ method: request.method, headers }), 404, "not-found"));
+            let body;
+            if (request.method === "POST") {
+                const b = parse(await request.text());
+                if (!b.ok)
+                    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, raw: request }));
+        };
+    }
+    return {
+        handle,
+        handlers,
+        nodeHandler: (o = {}) => nodeAdapter(o, false),
+        expressHandler: (o = {}) => nodeAdapter(o, true),
+        nextApiHandler: (o = {}) => nodeAdapter(o, false),
+        fetchHandler,
+        route: routeHandler,
+    };
+}

package/dist/stores.d.ts

@@ -0,0 +1,21 @@
+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 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. 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. */
+export declare function memoryStateStore(now?: () => number): StateStore;

package/dist/stores.js

@@ -0,0 +1,92 @@
+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 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 shared = new SharedJsonFile(file);
+    return {
+        get: (userid) => {
+            const table = shared.read();
+            return has(table, userid) ? structuredClone(table[userid]) : null;
+        },
+        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. */
+export function memoryUserStore() {
+    const users = new Map();
+    return {
+        get: (userid) => {
+            const u = users.get(userid);
+            return u ? structuredClone(u) : null;
+        },
+        put: (user) => void users.set(user.userid, structuredClone(user)),
+        list: () => [...users.values()].map((u) => structuredClone(u)),
+    };
+}
+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) => shared.update((sets) => {
+            prune(sets, now());
+            const set = (sets[ns] ??= {});
+            if (has(set, key))
+                return { write: false, result: false };
+            set[key] = expiresAt;
+            // Written before the answer goes out: a restart must not forget it.
+            return { write: true, result: true };
+        }),
+        has(ns, key) {
+            const set = shared.read()[ns];
+            return !!set && has(set, key) && set[key] >= now();
+        },
+    };
+}
+/** The same in memory. A restart forgets it, which reopens launch replay for
+ *  two minutes; for tests. */
+export function memoryStateStore(now = Date.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();
+        },
+    };
+}