@decentnetwork/beagle-service 0.1.0 → 0.2.0

package/dist/util.js

@@ -1,4 +1,4 @@
-import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeSync } from "node:fs";
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 import { base58ToBytes, carrierIdFromAddress } from "@decentnetwork/peer";
@@ -39,6 +39,107 @@ export function readJsonFile(file, fallback) {
         throw new Error(`beagle-service: ${file} is not valid JSON (${e.message}); fix or move it before starting`);
     }
 }
+const LOCK_STALE_MS = 5_000;
+const LOCK_WAIT_MS = 3_000;
+const sleepCell = new Int32Array(new SharedArrayBuffer(4));
+/** 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 class SharedJsonFile {
+    #file;
+    #value;
+    #seen = "";
+    constructor(file) {
+        this.#file = file;
+        this.#load();
+    }
+    #identity() {
+        try {
+            const s = statSync(this.#file);
+            return `${s.ino}:${s.size}:${s.mtimeMs}`;
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return "";
+            throw e;
+        }
+    }
+    #load() {
+        const seen = this.#identity();
+        // A null prototype: a key such as "__proto__" is a key like any other.
+        this.#value = Object.assign(Object.create(null), readJsonFile(this.#file, {}));
+        this.#seen = seen;
+    }
+    /** The current content. Do not change it; use `update`. */
+    read() {
+        if (this.#identity() !== this.#seen)
+            this.#load();
+        return this.#value;
+    }
+    /** Change the content. `change` gets what is on disk now and says whether
+     *  it has to be written. */
+    update(change) {
+        mkdirSync(dirname(this.#file), { recursive: true });
+        const lock = `${this.#file}.lock`;
+        const waitUntil = Date.now() + LOCK_WAIT_MS;
+        for (;;) {
+            try {
+                closeSync(openSync(lock, "wx", 0o600));
+                break;
+            }
+            catch (e) {
+                if (e.code !== "EEXIST")
+                    throw e;
+                let age = 0;
+                try {
+                    age = Date.now() - statSync(lock).mtimeMs;
+                }
+                catch {
+                    continue; // released in between
+                }
+                // A writer holds the lock for a few milliseconds. One this old was
+                // left by a process that died while holding it.
+                if (age > LOCK_STALE_MS || Date.now() > waitUntil) {
+                    try {
+                        unlinkSync(lock);
+                    }
+                    catch {
+                        /* someone else removed it */
+                    }
+                    continue;
+                }
+                Atomics.wait(sleepCell, 0, 0, 5);
+            }
+        }
+        try {
+            const value = this.read();
+            const { write, result } = change(value);
+            if (write) {
+                atomicWriteJson(this.#file, value);
+                this.#seen = this.#identity();
+            }
+            return result;
+        }
+        catch (e) {
+            // `change` may have altered the copy in memory before it threw.
+            this.#seen = "\0";
+            throw e;
+        }
+        finally {
+            try {
+                unlinkSync(lock);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+}
+export const isThenable = (v) => !!v && typeof v.then === "function";
 /** A userid is the base58 of a 32-byte public key. */
 export function isUserid(v) {
     if (typeof v !== "string" || v.length < 32 || v.length > 64)
@@ -90,7 +191,7 @@ export class Hub {
         }
     }
 }
-/** Run async jobs for the same key one after another. */
+/** Run jobs for the same key one after another. */
 export class KeyedLock {
     #tails = new Map();
     run(key, job) {

package/examples/next-pages-cjs/README.md

@@ -0,0 +1,30 @@
+# Sign in with Beagle beside NextAuth, in a CommonJS Next.js site
+
+A pages-router site whose `lib/` is CommonJS and which already has NextAuth's catch-all at
+`pages/api/auth/[...nextauth].js`.
+
+```bash
+npm install
+npm run build
+BEAGLE_ORIGINS=http://localhost:3000 npm start
+```
+
+| File | What it shows |
+|---|---|
+| `lib/beagle.js` | `require("@decentnetwork/beagle-service")`, one service per process, the `onSignIn` hook |
+| `instrumentation.js` | the service is created when the server starts, so a wrong `BEAGLE_ORIGINS` stops the start |
+| `pages/api/auth/[...nextauth].js` | NextAuth's catch-all, untouched |
+| `pages/api/auth/nonce.js`, `sign-in.js`, `launch.js`, `me.js`, `logout.js`, `register.js` | one Beagle route per file: `export default beagle.route("signIn")` |
+| `pages/api/notes.js` | a route of the site's own: `beagle.authenticate(req, { checkOrigin: true })` |
+| `pages/index.js` | reading the session in `getServerSideProps`; the popup with `beagle-connect` |
+| `next.config.js`, `lib/peer-for-browser.mjs` | what the browser bundle needs for `beagle-connect` |
+
+The operator's command works beside the running server:
+
+```bash
+npx beagle-service users list
+npx beagle-service users block <userid> spam
+```
+
+`npm run e2e:next` in the package builds this example against the package as it would be published and runs it
+with `next build` and `next start`.

package/examples/next-pages-cjs/instrumentation.js

@@ -0,0 +1,16 @@
+// Next.js runs this once when the server starts (`next start`, `next dev`),
+// before any request. Creating the service here means a wrong configuration
+// (an entry of BEAGLE_ORIGINS that is not an exact origin, a users file that
+// does not parse) is found at start, with its reason, instead of showing up as
+// a failed sign-in later.
+//
+// When `register` rejects, Next.js prints "Failed to prepare server" with the
+// reason and answers 500 to every request until the configuration is fixed and
+// the server started again. To keep the rest of the site up and have only the
+// sign-in routes answer 500, do not await: `beagle.ready().catch(() => {})`
+// (the reason is still printed at start).
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+  const { beagle } = require("./lib/beagle");
+  await beagle.ready();
+}

package/examples/next-pages-cjs/lib/beagle.js

@@ -0,0 +1,23 @@
+// The site's one beagle-service. CommonJS, like the rest of this lib/.
+//
+// `sharedBeagleService` returns at once and creates the service on first use,
+// one per process however many times Next.js evaluates this file. It never
+// throws at a request: while the service cannot start, the routes answer 500
+// and `authenticate` answers `ok: false`.
+const { sharedBeagleService } = require("@decentnetwork/beagle-service");
+
+const list = (v) => String(v || "").split(",").map((s) => s.trim()).filter(Boolean);
+
+const beagle = sharedBeagleService(() => ({
+  // Exact origins of this site's pages: scheme, host and port.
+  origins: list(process.env.BEAGLE_ORIGINS || `http://localhost:${process.env.PORT || 3000}`),
+  dataDir: process.env.BEAGLE_DATA_DIR || "./data",
+  // The site's part of a sign-in, awaited before the answer goes out. What it
+  // returns is added to the answer; `{ refuse: "why" }` refuses the sign-in.
+  onSignIn: async (user, { origin, door, first }) => {
+    if (first) console.log(`first sign-in: ${user.userid} at ${origin} through ${door}`);
+    return { role: user.signIns > 100 ? "regular" : "listener" };
+  },
+}));
+
+module.exports = { beagle };

package/examples/next-pages-cjs/lib/peer-for-browser.mjs

@@ -0,0 +1,2 @@
+export { verifyDetached } from "@decentnetwork/peer/dist/crypto/sign.js";
+export { base58ToBytes } from "@decentnetwork/peer/dist/utils/base58.js";

package/examples/next-pages-cjs/next.config.js

@@ -0,0 +1,11 @@
+const path = require("path");
+
+module.exports = {
+  webpack(config, { isServer }) {
+    // The page uses beagle-connect, which needs two functions of
+    // @decentnetwork/peer (the signature check). Give the browser those two
+    // modules instead of the whole peer.
+    if (!isServer) config.resolve.alias["@decentnetwork/peer$"] = path.join(__dirname, "lib/peer-for-browser.mjs");
+    return config;
+  },
+};

package/examples/next-pages-cjs/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "beagle-service-next-pages-cjs",
+  "private": true,
+  "description": "Sign in with Beagle in a CommonJS Next.js pages-router site that also has NextAuth's catch-all.",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "users": "beagle-service users list"
+  },
+  "dependencies": {
+    "@decentnetwork/beagle-connect": "^0.1.2",
+    "@decentnetwork/beagle-service": "^0.2.0",
+    "next": "^15.3.2",
+    "next-auth": "^4.24.14",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  }
+}

package/examples/next-pages-cjs/pages/api/auth/[...nextauth].js

@@ -0,0 +1,17 @@
+// NextAuth owns the catch-all under /api/auth. A second catch-all in this
+// directory does not build, so the Beagle routes beside it are one file each
+// (nonce.js, sign-in.js, launch.js, me.js, logout.js, register.js); a named
+// file wins over the catch-all, and none of those names is one of NextAuth's.
+import NextAuth from "next-auth";
+import Credentials from "next-auth/providers/credentials";
+
+export default NextAuth({
+  secret: process.env.NEXTAUTH_SECRET || "example-only-secret-change-me",
+  providers: [
+    Credentials({
+      name: "Demo",
+      credentials: { name: { label: "Name", type: "text" } },
+      authorize: async (credentials) => (credentials?.name ? { id: credentials.name, name: credentials.name } : null),
+    }),
+  ],
+});

package/examples/next-pages-cjs/pages/api/auth/launch.js

@@ -0,0 +1,3 @@
+const { beagle } = require("../../../lib/beagle");
+
+export default beagle.route("launch");

package/examples/next-pages-cjs/pages/api/auth/logout.js

@@ -0,0 +1,3 @@
+const { beagle } = require("../../../lib/beagle");
+
+export default beagle.route("logout");

package/examples/next-pages-cjs/pages/api/auth/me.js

@@ -0,0 +1,3 @@
+const { beagle } = require("../../../lib/beagle");
+
+export default beagle.route("me");

package/examples/next-pages-cjs/pages/api/auth/nonce.js

@@ -0,0 +1,3 @@
+const { beagle } = require("../../../lib/beagle");
+
+export default beagle.route("nonce");

package/examples/next-pages-cjs/pages/api/auth/register.js

@@ -0,0 +1,3 @@
+const { beagle } = require("../../../lib/beagle");
+
+export default beagle.route("register");

package/examples/next-pages-cjs/pages/api/auth/sign-in.js

@@ -0,0 +1,3 @@
+const { beagle } = require("../../../lib/beagle");
+
+export default beagle.route("signIn");

package/examples/next-pages-cjs/pages/api/notes.js

@@ -0,0 +1,16 @@
+// One of the site's own routes. Reading a session is asynchronous and never
+// throws: no session, a bad one, a blocked user or a server that cannot check
+// all come back as `ok: false` with a status.
+const { beagle } = require("../../lib/beagle");
+
+const notes = new Map(); // userid -> text; a real site has a database
+
+export default async function handler(req, res) {
+  // checkOrigin: a request that changes something and carries the session
+  // cookie must come from one of this site's pages (its Origin header is on
+  // the list). A GET is not checked.
+  const who = await beagle.authenticate(req, { checkOrigin: true });
+  if (!who.ok) return res.status(who.status).json({ error: who.error });
+  if (req.method === "POST") notes.set(who.user.userid, String(req.body?.text ?? "").slice(0, 500));
+  res.status(200).json({ note: notes.get(who.user.userid) ?? "" });
+}

package/examples/next-pages-cjs/pages/index.js

@@ -0,0 +1,52 @@
+import { useState } from "react";
+import { beagle } from "../lib/beagle"; // used on the server only, in getServerSideProps
+
+export async function getServerSideProps({ req }) {
+  const who = await beagle.authenticate(req);
+  return { props: { user: who.ok ? { userid: who.user.userid, name: who.user.name } : null } };
+}
+
+export default function Home({ user }) {
+  const [me, setMe] = useState(user);
+  const [error, setError] = useState("");
+
+  async function signInWithBeagle() {
+    // Open the window inside the click, or the browser blocks it.
+    const win = window.open("about:blank", "beagle-connect", "width=420,height=560");
+    try {
+      const { signIn } = await import("@decentnetwork/beagle-connect");
+      const { nonce } = await (await fetch("/api/auth/nonce")).json();
+      const who = await signIn({ nonce, existingWindow: win });
+      const res = await fetch("/api/auth/sign-in", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(who) });
+      const answer = await res.json();
+      if (!res.ok) throw new Error(answer.message || answer.error);
+      setMe(answer.user);
+      setError("");
+    } catch (e) {
+      win?.close();
+      setError(String(e.message || e));
+    }
+  }
+
+  async function signOut() {
+    await fetch("/api/auth/logout", { method: "POST" });
+    setMe(null);
+  }
+
+  return (
+    <main style={{ font: "16px system-ui", maxWidth: 560, margin: "64px auto", padding: "0 16px" }}>
+      <h1>Sign in with Beagle</h1>
+      {me ? (
+        <>
+          <p>Signed in as <b>{me.name || "someone"}</b></p>
+          <p><code style={{ wordBreak: "break-all" }}>{me.userid}</code></p>
+          <button onClick={signOut}>Sign out</button>
+        </>
+      ) : (
+        <button onClick={signInWithBeagle}>Sign in with Beagle</button>
+      )}
+      {error && <p role="alert">{error}</p>}
+      <p><a href="/api/auth/signin">NextAuth's own sign-in page</a> lives beside it.</p>
+    </main>
+  );
+}

package/examples/sign-in-from-script.mjs

@@ -0,0 +1,37 @@
+// A script that signs in to a site: a publisher node, a cron job, a test.
+//
+//   node sign-in-from-script.mjs https://your.app
+//
+// A browser adds the `Origin` header by itself; a script has to. The server
+// takes the origin from that header only (never from the body), checks it
+// against its exact list, and checks that the signature was made for it. So a
+// script names the site's own origin, the one its pages are served from, in
+// the header and in the string it signs.
+import { generateKeyPairSync } from "node:crypto";
+import { bytesToBase58, signDetached } from "@decentnetwork/peer";
+
+const site = new URL(process.argv[2] ?? "http://localhost:3000").origin;
+const sendOrigin = !process.argv.includes("--no-origin");
+
+// The script's identity. A real one loads its key from a file it keeps; this
+// one makes a throwaway X25519 key so the example runs anywhere.
+const { publicKey, privateKey } = generateKeyPairSync("x25519");
+const secretKey = new Uint8Array(Buffer.from(privateKey.export({ format: "jwk" }).d, "base64url"));
+const userid = bytesToBase58(new Uint8Array(Buffer.from(publicKey.export({ format: "jwk" }).x, "base64url")));
+const headers = sendOrigin ? { Origin: site, "content-type": "application/json" } : { "content-type": "application/json" };
+
+// README:begin
+const { nonce } = await (await fetch(`${site}/api/auth/nonce`)).json();
+const sig = Buffer.from(signDetached(secretKey, new TextEncoder().encode(`decent-auth\n${site}\n${nonce}`))).toString("hex");
+const res = await fetch(`${site}/api/auth/sign-in`, { method: "POST", headers, body: JSON.stringify({ userid, nonce, sig }) });
+// README:end
+
+const answer = await res.json();
+if (!res.ok) {
+  console.error(`sign-in refused: ${res.status} ${answer.error}`);
+  process.exit(1);
+}
+// The session: send this cookie back on later requests (or use `session: { transport: "bearer" }` on the site).
+const cookie = res.headers.getSetCookie().map((c) => c.split(";")[0]).join("; ");
+const me = await (await fetch(`${site}/api/auth/me`, { headers: { cookie } })).json();
+console.log(`signed in as ${me.user.userid}`);

package/package.json

@@ -1,18 +1,27 @@
 {
   "name": "@decentnetwork/beagle-service",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The web backend for a site on Beagle identity: Sign in with Beagle on the server, a user store with registration and a blacklist, and the site's own Carrier agent.",
   "license": "MIT",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/commonjs.cjs",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs.d.cts",
+        "default": "./dist/commonjs.cjs"
+      }
     },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "beagle-service": "./dist/cli.js"
+  },
   "files": [
     "dist",
     "examples",
@@ -20,11 +29,13 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/cli.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && tsc -p test/types/tsconfig.json && node --test --test-force-exit test/*.test.mjs",
     "e2e": "npm run build && node test/e2e/agent-public.mjs",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "e2e:next": "node test/e2e/next-example.mjs",
+    "test:gaps-on-0.1.0": "node test/gaps-on-0.1.0.mjs"
   },
   "dependencies": {
     "@decentnetwork/beagle-connect": "^0.1.2",
@@ -53,5 +64,6 @@
     "type": "git",
     "url": "git+https://github.com/0xli/beagle.git",
     "directory": "packages/beagle-service"
-  }
+  },
+  "module": "./dist/index.js"
 }