@decentnetwork/beagle-service 0.0.0-stage → 0.1.0

package/dist/auth.js

@@ -0,0 +1,257 @@
+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";
+/** 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;
+const DAY_MS = 86_400_000;
+/** Turn the configured list into exact origins. Throws on anything that is
+ *  not `scheme://host[:port]`, so a typo is found at start, not as a sign-in
+ *  that never verifies. */
+export function normalizeOrigins(list) {
+    if (!Array.isArray(list) || list.length === 0) {
+        throw new TypeError('beagle-service: `origins` must list the exact origins of your pages, e.g. ["https://your.app"]');
+    }
+    const out = new Set();
+    for (const raw of list) {
+        let u = null;
+        if (typeof raw === "string" && !raw.includes("*")) {
+            try {
+                u = new URL(raw);
+            }
+            catch {
+                u = null;
+            }
+        }
+        if (!u || u.origin === "null" || u.pathname !== "/" || u.search || u.hash || u.username || u.password) {
+            throw new TypeError(`beagle-service: origin ${JSON.stringify(raw)} is not an exact origin. Write scheme, host and port, e.g. "https://your.app" or "http://localhost:3000"; wildcards and paths are not accepted`);
+        }
+        out.add(u.origin);
+    }
+    return out;
+}
+/** The signing secret: the configured one, else a 32-byte one kept in `file`. */
+export function loadSecret(configured, file) {
+    if (configured) {
+        if (configured.length < 16)
+            throw new TypeError("beagle-service: `sessionSecret` must be at least 16 characters");
+        return configured;
+    }
+    try {
+        const s = readFileSync(file, "utf8").trim();
+        if (s)
+            return s;
+    }
+    catch {
+        /* first start */
+    }
+    const s = randomBytes(32).toString("hex");
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, s, { mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        /* best effort on filesystems without modes */
+    }
+    return s;
+}
+export function headerOf(req, name) {
+    const h = req?.headers;
+    if (!h)
+        return undefined;
+    if (typeof h.get === "function")
+        return h.get(name) ?? undefined;
+    const v = h[name] ?? h[name.toLowerCase()];
+    return Array.isArray(v) ? v[0] : v;
+}
+const isSigHex = (v) => typeof v === "string" && /^[0-9a-fA-F]{128}$/.test(v);
+export function createAuth(opts) {
+    const { origins, state, users, secret } = opts;
+    const now = opts.now ?? Date.now;
+    const cfg = opts.session ?? {};
+    const ttlMs = (cfg.ttlDays ?? 30) * DAY_MS;
+    const cookieName = cfg.cookieName ?? "beagle_session";
+    const sameSite = cfg.sameSite ?? "Lax";
+    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));
+        const have = Buffer.from(got);
+        return want.length === have.length && timingSafeEqual(want, have);
+    };
+    // ── nonces ────────────────────────────────────────────────────────────────
+    // A nonce carries its own expiry and our MAC, so issuing one stores nothing
+    // and any server process can recognise it. Using one stores it (until it
+    // would have expired anyway), which is what makes it single-use, also
+    // 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)}`;
+    }
+    async function consumeNonce(nonce) {
+        if (typeof nonce !== "string" || nonce.length > 128)
+            return false;
+        const parts = nonce.split(".");
+        if (parts.length !== 3)
+            return false;
+        const body = `${parts[0]}.${parts[1]}`;
+        const want = Buffer.from(mac("nonce", body).slice(0, 22));
+        const have = Buffer.from(parts[2]);
+        if (want.length !== have.length || !timingSafeEqual(want, have))
+            return false;
+        const exp = parseInt(parts[1], 36);
+        if (!Number.isFinite(exp) || exp < now())
+            return false;
+        return await state.addOnce("nonce", parts[0], exp);
+    }
+    // ── the two assertions ────────────────────────────────────────────────────
+    const fail = (status, error) => ({ ok: false, status, error });
+    const hintsOf = (b) => ({ address: b.address, name: b.name, avatar: b.avatar, punkId: b.punkId });
+    function doorOf(v) {
+        if (typeof v !== "string" || v.length > 200)
+            return null;
+        try {
+            const o = new URL(v).origin;
+            return o === "null" ? null : o;
+        }
+        catch {
+            return null;
+        }
+    }
+    function allowedOrigin(req) {
+        const origin = headerOf(req, "origin");
+        return origin && origins.has(origin) ? origin : null;
+    }
+    async function verifySignIn(origin, body) {
+        if (!origin || !origins.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)))
+            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");
+        }
+        return { ok: true, userid: b.userid, hints: hintsOf(b), door: doorOf(b.uiOrigin) };
+    }
+    async function verifyLaunch(origin, body) {
+        if (!origin || !origins.has(origin))
+            return fail(403, "origin-not-allowed");
+        if (!body || typeof body !== "object")
+            return fail(400, "bad-request");
+        const b = body;
+        const ts = typeof b.ts === "number" ? b.ts : typeof b.ts === "string" && /^\d{1,16}$/.test(b.ts) ? Number(b.ts) : NaN;
+        // Both directions: a clock ahead of ours is as suspect as one behind.
+        if (!Number.isSafeInteger(ts) || Math.abs(now() - ts) > LAUNCH_MAX_AGE_MS)
+            return fail(401, "launch-expired");
+        if (!isUserid(b.userid) || !isSigHex(b.sig) || !connectVerifyLaunch(b.userid, origin, ts, b.sig)) {
+            return fail(401, "bad-signature");
+        }
+        // Last, so a forged repeat cannot burn an assertion a real visitor still
+        // holds. Keyed on what was signed (who, for which origin, at which
+        // instant), not on the signature's bytes: the same assertion written with
+        // other hex case, or any second signature over the same message, is a
+        // repeat too.
+        const fresh = await state.addOnce("launch", `${b.userid}|${origin}|${ts}`, now() + 2 * LAUNCH_MAX_AGE_MS);
+        if (!fresh)
+            return fail(401, "launch-replayed");
+        return { ok: true, userid: b.userid, hints: hintsOf(b), door: "launch" };
+    }
+    // ── sessions ──────────────────────────────────────────────────────────────
+    function mintSession(userid) {
+        const t = now();
+        const sid = randomBytes(12).toString("base64url");
+        const expiresAt = t + ttlMs;
+        const body = Buffer.from(JSON.stringify({ u: userid, i: sid, t, e: expiresAt })).toString("base64url");
+        return { token: `v1.${body}.${mac("session", body)}`, sid, expiresAt };
+    }
+    function readToken(token) {
+        if (typeof token !== "string" || token.length > 1024)
+            return null;
+        const parts = token.split(".");
+        if (parts.length !== 3 || parts[0] !== "v1" || !macOk("session", parts[1], parts[2]))
+            return null;
+        try {
+            const p = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+            if (typeof p.u !== "string" || typeof p.i !== "string" || !Number.isFinite(p.t) || !Number.isFinite(p.e))
+                return null;
+            if (p.e < now())
+                return null;
+            return { userid: p.u, sid: p.i, issuedAt: p.t, expiresAt: p.e };
+        }
+        catch {
+            return null;
+        }
+    }
+    function tokenFrom(req) {
+        const authz = headerOf(req, "authorization");
+        if (authz && /^bearer /i.test(authz))
+            return { token: authz.slice(7).trim(), via: "bearer" };
+        const cookies = headerOf(req, "cookie");
+        if (cookies) {
+            for (const part of cookies.split(";")) {
+                const i = part.indexOf("=");
+                if (i > 0 && part.slice(0, i).trim() === cookieName)
+                    return { token: part.slice(i + 1).trim(), via: "cookie" };
+            }
+        }
+        return null;
+    }
+    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 };
+        }
+        return { ok: true, user, session, registration };
+    }
+    async function revoke(token) {
+        const t = readToken(token);
+        if (t)
+            await state.addOnce("revoked", t.sid, t.expiresAt);
+    }
+    function cookie(token, origin) {
+        const parts = [`${cookieName}=${token ?? ""}`, `Path=${cfg.cookiePath ?? "/"}`, "HttpOnly", `SameSite=${sameSite}`];
+        parts.push(`Max-Age=${token ? Math.floor(ttlMs / 1000) : 0}`);
+        if (cfg.cookieDomain)
+            parts.push(`Domain=${cfg.cookieDomain}`);
+        // Secure always, except for a page the site itself listed under plain
+        // http (a localhost during development): a browser would drop it there.
+        if (sameSite === "None" || !origin?.startsWith("http://"))
+            parts.push("Secure");
+        return parts.join("; ");
+    }
+    return {
+        issueNonce,
+        allowedOrigin,
+        verifySignIn,
+        verifyLaunch,
+        authenticate,
+        mintSession,
+        readToken,
+        tokenOf: (req) => tokenFrom(req)?.token ?? null,
+        revoke,
+        cookie,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { BeagleService, BeagleServiceConfig } from "./types.js";
+export declare function createBeagleService(config: BeagleServiceConfig): Promise<BeagleService>;
+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 { defaultPublicUser } from "./routes.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,69 @@
+// @decentnetwork/beagle-service — the web backend for a site on Beagle identity.
+//
+// Three parts; a site may use the first alone:
+//
+//   auth   Sign in with Beagle on the server: nonce, exact origin, the two
+//          assertions, a launch replay store that survives a restart, sessions.
+//   users  one record per userid: visitor, registered or blocked; the site's
+//          own registration fields; the visitor limit; the blacklist.
+//   agent  the site's own Carrier identity: who may become a friend, requests
+//          held on disk, a persistent outbox, messages with the sender's record.
+//
+// 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 { 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));
+    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"));
+    const users = createUsers({
+        store,
+        register: config.register,
+        visitor: config.visitor,
+        importProfile: config.importProfile,
+        now,
+        log,
+        fetch: config.fetch,
+    });
+    const auth = createAuth({ origins, state, users, secret, session: config.session, now });
+    let agent;
+    const routes = createRoutes({ auth, users, session: config.session, publicUser: config.publicUser, agent: () => agent, log });
+    if (config.agent) {
+        // Only when asked for: a site that needs sign-in alone starts no peer.
+        const { createAgent } = await import("./agent.js");
+        agent = await createAgent({ config: config.agent, users, dir: join(dataDir, "agent"), now, log, fetch: config.fetch });
+    }
+    return {
+        users,
+        auth,
+        agent,
+        handle: routes.handle,
+        handlers: routes.handlers,
+        nodeHandler: routes.nodeHandler,
+        expressHandler: routes.expressHandler,
+        nextApiHandler: routes.nextApiHandler,
+        fetchHandler: routes.fetchHandler,
+        close: async () => {
+            await agent?.stop();
+        },
+    };
+}
+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 { 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.
+export * from "./types.js";

package/dist/outbox.d.ts

@@ -0,0 +1,63 @@
+import type { DeadLetter, DeadLetterReason, DeliveryEvent, OutboxItem } from "./types.js";
+import { type Logger } from "./util.js";
+/** Cut `text` into parts that each fit one message (about 700 bytes of
+ *  UTF-8), at a line break or a space where one is near. The parts joined
+ *  together are the text, unchanged. */
+export declare function splitText(text: string): string[];
+export interface OutboxTransport {
+    /** "friend": the friendship is settled. "pending": a request is out, or one
+     *  of theirs is held. "none": there is no way a message could reach them. */
+    relation(userid: string): "friend" | "pending" | "none";
+    /** A live session that carried something from the friend a moment ago. */
+    proven(userid: string): boolean;
+    /** Live send with a short confirmation window; throws when nothing took it. */
+    sendLive(userid: string, text: string, deliveryId: string): Promise<"acked" | "accepted" | "offline">;
+    /** Post to an Express node whatever the session looks like; throws when it cannot. */
+    sendExpress(userid: string, text: string, deliveryId: string): Promise<void>;
+}
+export interface OutboxOptions {
+    file: string;
+    deadFile: string;
+    transport: OutboxTransport;
+    now?: () => number;
+    log?: Logger;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    maxAgeMs?: number;
+    onDelivered?: (e: DeliveryEvent) => void;
+    onDead?: (d: DeadLetter) => void;
+}
+/**
+ * Messages on their way out, kept in one JSON file.
+ *
+ * - A message is written to disk before `enqueue` returns and removed only
+ *   after a road took it, so a restart loses nothing.
+ * - Its `deliveryId` is fixed when it is queued. A retry, a second road or a
+ *   send repeated after a crash carries the same id, and a friend that reads
+ *   the delivery envelope shows it once.
+ * - One queue per recipient: a recipient's messages go in order, and an
+ *   unreachable recipient never holds up another.
+ * - The road (the rule the agentnet daemon uses): a session that has just
+ *   proven itself gets the message live, with a short wait for the
+ *   confirmation; otherwise, or when no confirmation comes, it is posted to
+ *   an Express node at once. Only when neither road takes it does it wait,
+ *   with a delay that doubles up to `maxDelayMs`.
+ * - What can never arrive is moved to the dead-letter file with the reason.
+ */
+export declare class Outbox {
+    #private;
+    constructor(o: OutboxOptions);
+    list(): OutboxItem[];
+    deadLetters(limit?: number): DeadLetter[];
+    /** Put a text on disk for `to`. Synchronous: when it returns, the message survives a crash. */
+    enqueue(to: string, text: string): OutboxItem[];
+    /** Record a message that cannot be sent at all, without queueing it. */
+    refuse(to: string, text: string, why: DeadLetterReason): OutboxItem[];
+    /** Dead-letter everything queued for `to`. */
+    dropFor(to: string, why: DeadLetterReason): number;
+    /** Something changed for `to` (accepted, connected): try now, not after the delay. */
+    kick(to: string): void;
+    stop(): void;
+    /** Try the head of every recipient's queue that is due. */
+    pump(): Promise<void>;
+}