@docsworth/cli 0.0.0-stage → 0.3.0

package/dist/core/serve/sessions.d.ts

@@ -0,0 +1,40 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Identity } from "../acl.js";
+import { type AuditLog } from "../audit-log.js";
+import { type IdentitySource, KnowledgeService, RepoLoader } from "../service.js";
+export interface SessionOptions {
+    root: string;
+    identity: IdentitySource;
+    /** The identity proven at server start, to attribute the first event of each session. */
+    who: Identity;
+    audit: AuditLog | null;
+    includeQueries: boolean;
+    now: () => Date;
+    maxSessions?: number;
+    idleMs?: number;
+    log?: (msg: string) => void;
+}
+export declare const MAX_SESSIONS = 16;
+export declare const SESSION_IDLE_MS: number;
+export declare class SessionTable {
+    private readonly opts;
+    private readonly sessions;
+    /** Sessions being set up: counted against the cap before they have an id. */
+    private starting;
+    /** One load of the repo for every session; its watcher marks it stale on any change. */
+    readonly loader: RepoLoader;
+    private readonly sweeper;
+    private readonly max;
+    private readonly idleMs;
+    constructor(opts: SessionOptions);
+    get size(): number;
+    /** The services of live sessions (tests). */
+    services(): KnowledgeService[];
+    handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    private open;
+    /** The session that has had no request in flight for longest, if any. */
+    private idlest;
+    /** Close sessions idle longer than the limit, never one with a request in flight. */
+    sweep(now?: number): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/core/serve/sessions.js

@@ -0,0 +1,203 @@
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { actorOf } from "../audit-log.js";
+import { auditTransport } from "../mcp/audit-transport.js";
+import { createMcpServer } from "../mcp/server.js";
+import { KnowledgeService, RepoLoader } from "../service.js";
+export const MAX_SESSIONS = 16;
+/** An initialize request is a few hundred bytes; a first request bigger than this isn't one. */
+const MAX_START_BYTES = 64 * 1024;
+export const SESSION_IDLE_MS = 30 * 60_000;
+function json(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body));
+}
+const NOT_A_START = { status: 400, error: { code: "invalid", message: "start a session with an initialize request" } };
+/**
+ * A first request's body, if it can start a session: the headers the transport requires,
+ * and exactly one initialize request. Checked before a slot is counted or reclaimed, so a
+ * request the transport would refuse can't close someone's idle session for nothing.
+ */
+async function startBody(req) {
+    const accept = req.headers.accept ?? "";
+    if (!accept.includes("application/json") || !accept.includes("text/event-stream"))
+        return { status: 406, error: { code: "invalid", message: "the client must accept both application/json and text/event-stream" } };
+    if (!(req.headers["content-type"] ?? "").includes("application/json"))
+        return { status: 415, error: { code: "invalid", message: "the body must be application/json" } };
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_START_BYTES)
+            return NOT_A_START;
+        chunks.push(chunk);
+    }
+    let body;
+    try {
+        body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        return NOT_A_START;
+    }
+    const only = Array.isArray(body) ? (body.length === 1 ? body[0] : undefined) : body;
+    return isInitializeRequest(only) ? { body } : NOT_A_START;
+}
+export class SessionTable {
+    opts;
+    sessions = new Map();
+    /** Sessions being set up: counted against the cap before they have an id. */
+    starting = 0;
+    /** One load of the repo for every session; its watcher marks it stale on any change. */
+    loader;
+    sweeper;
+    max;
+    idleMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.max = opts.maxSessions ?? MAX_SESSIONS;
+        this.idleMs = opts.idleMs ?? SESSION_IDLE_MS;
+        // One load and one watcher for every session: a change marks the load stale, and the
+        // next call from any session builds a new one, never in the middle of a write that is
+        // still landing. It watches pages only. The config and CODEOWNERS (the policy, admins,
+        // owners) sit outside the knowledge root, and every call already stats them, so a
+        // tightened policy applies to an open session's next call (test/serve.test.ts,
+        // "applies a tightened policy").
+        this.loader = new RepoLoader(opts.root);
+        // A new load is built inside one session's call; every session with nothing in flight
+        // moves onto it now, and a busy one when its last request ends (handle). So however
+        // the repo changes, the sessions hold one load between them, not one each.
+        this.loader.onLoad = () => {
+            for (const s of this.sessions.values())
+                if (s.active === 0)
+                    s.service.release();
+        };
+        this.loader.watch();
+        this.sweeper = setInterval(() => void this.sweep(), Math.min(60_000, this.idleMs));
+        this.sweeper.unref();
+    }
+    get size() {
+        return this.sessions.size;
+    }
+    /** The services of live sessions (tests). */
+    services() {
+        return [...this.sessions.values()].map((s) => s.service);
+    }
+    async handle(req, res) {
+        const sid = req.headers["mcp-session-id"];
+        if (sid !== undefined) {
+            const session = typeof sid === "string" ? this.sessions.get(sid) : undefined;
+            if (!session)
+                return json(res, 404, { error: { code: "not_found", message: "no such session; it may have expired: start a new one" } });
+            session.active++;
+            try {
+                return await session.http.handleRequest(req, res);
+            }
+            finally {
+                session.active--;
+                session.lastUsed = Date.now();
+                if (session.active === 0)
+                    session.service.release();
+            }
+        }
+        if (req.method !== "POST")
+            return json(res, 400, { error: NOT_A_START.error });
+        const first = await startBody(req);
+        if (!("body" in first))
+            return json(res, first.status, { error: first.error });
+        // Checked and counted with no await in between, so concurrent starts can't pass the cap.
+        // A full server makes room by closing the session idle longest: a closed tab never
+        // tells the server, so refusing would lock the user out until it expired. Only when
+        // every slot is busy (answering, or still starting) is a new one refused.
+        let reclaimed;
+        if (this.sessions.size + this.starting >= this.max) {
+            reclaimed = this.idlest();
+            if (!reclaimed)
+                return json(res, 503, { error: { code: "unavailable", message: `this server is answering ${this.max} sessions at once; try again in a moment` } });
+            this.sessions.delete(reclaimed.http.sessionId); // out of the table before any await
+        }
+        // This start's slot: counted in `starting` until its session joins the table, then
+        // there instead (never in both, or a start beside a slow first answer finds no room).
+        this.starting++;
+        let reserved = true;
+        const joined = () => {
+            if (reserved)
+                this.starting--;
+            reserved = false;
+        };
+        try {
+            if (reclaimed)
+                await reclaimed.server.close().catch((err) => this.opts.log?.(`closing an idle session failed: ${err.message}`));
+            const session = await this.open(joined);
+            try {
+                await session.http.handleRequest(req, res, first.body); // the body is read: hand it over
+            }
+            finally {
+                // Busy from birth: the session joins the table while this request is still
+                // being answered, so a sweep in between must not take it.
+                session.active--;
+                session.lastUsed = Date.now();
+                if (session.active === 0)
+                    session.service.release(); // as for any request (above)
+            }
+            // A first request that wasn't an initialize gets the SDK's error and no session.
+            if (!session.http.sessionId)
+                await session.server.close();
+        }
+        finally {
+            joined();
+        }
+    }
+    async open(joined) {
+        const o = this.opts;
+        const service = new KnowledgeService(o.root, o.identity, o.now, this.loader);
+        const http = new StreamableHTTPServerTransport({
+            sessionIdGenerator: randomUUID,
+            enableJsonResponse: true,
+            onsessioninitialized: (id) => {
+                this.sessions.set(id, session);
+                joined();
+            },
+        });
+        const transport = o.audit
+            ? auditTransport(http, o.audit, () => o.identity.get(), {
+                includeQueries: o.includeQueries,
+                initialActor: actorOf(o.who),
+                known: () => service.knownValues(),
+                snapshot: () => service.snapshot(),
+                log: o.log,
+            })
+            : http;
+        // On the wrapper, not on `http`: the audit transport takes over the inner onclose.
+        // Set before connect, which chains the server's own handler after this one.
+        transport.onclose = () => {
+            if (http.sessionId)
+                this.sessions.delete(http.sessionId);
+            service.close();
+        };
+        const server = createMcpServer(service, { who: o.who, whoami: () => o.identity.get(), surface: "http" });
+        const session = { http, server, service, lastUsed: Date.now(), active: 1 };
+        await server.connect(transport);
+        return session;
+    }
+    /** The session that has had no request in flight for longest, if any. */
+    idlest() {
+        let found;
+        for (const s of this.sessions.values())
+            if (s.active === 0 && (!found || s.lastUsed < found.lastUsed))
+                found = s;
+        return found;
+    }
+    /** Close sessions idle longer than the limit, never one with a request in flight. */
+    async sweep(now = Date.now()) {
+        const idle = [...this.sessions.values()].filter((s) => s.active === 0 && now - s.lastUsed > this.idleMs);
+        // Out of the table first, so a start can't pick one of these to reclaim as well.
+        for (const s of idle)
+            this.sessions.delete(s.http.sessionId);
+        await Promise.all(idle.map((s) => s.server.close()));
+    }
+    async close() {
+        clearInterval(this.sweeper);
+        this.loader.close();
+        await Promise.all([...this.sessions.values()].map((s) => s.server.close()));
+    }
+}

package/dist/core/serve/token.d.ts

@@ -0,0 +1,10 @@
+import { UserError } from "../errors.js";
+export declare const TOKEN_FILE = "serve-token";
+export declare class TokenError extends UserError {
+}
+/** The serve token kept in `dir`, created on first use, or replaced with `rotate`. */
+export declare function loadToken(dir: string, opts?: {
+    rotate?: boolean;
+}): string;
+/** Constant-time comparison of a presented token with the expected one. */
+export declare function tokenMatches(expected: string, presented: string | undefined): boolean;

package/dist/core/serve/token.js

@@ -0,0 +1,96 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, closeSync, constants, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { UserError } from "../errors.js";
+// The bearer token `docsworth serve` checks on every /mcp request. It persists in this
+// user's state directory (outside the repo, never committable), so a paired browser
+// extension keeps working across restarts; `--rotate-token` replaces it. The file is
+// handled like the audit log's: a 0700 directory that isn't a symlink, a 0600 file opened
+// without following links, and writes that are atomic.
+export const TOKEN_FILE = "serve-token";
+const TOKEN_SHAPE = /^[A-Za-z0-9_-]{43}$/; // 32 random bytes, base64url
+export class TokenError extends UserError {
+}
+function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const st = lstatSync(dir);
+    if (st.isSymbolicLink() || !st.isDirectory())
+        throw new TokenError(`${dir} is a symlink or not a directory; refusing to keep the serve token there`);
+    if ((st.mode & 0o077) !== 0)
+        chmodSync(dir, 0o700);
+}
+/** The token in `file`, or null if there is none yet. */
+function readToken(file) {
+    let fd;
+    try {
+        fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return null;
+        if (code === "ELOOP")
+            throw new TokenError(`${file} is a symlink; refusing to read the serve token through it`);
+        throw err;
+    }
+    try {
+        const st = fstatSync(fd);
+        if (!st.isFile())
+            throw new TokenError(`${file} is not a regular file; refusing to use it as the serve token`);
+        // A token others could read is a token others have: refuse it rather than quietly fix it.
+        if ((st.mode & 0o077) !== 0)
+            throw new TokenError(`${file} can be read by other users; run \`docsworth serve --rotate-token\` to replace it`);
+        const token = readFileSync(fd, "utf8").trim();
+        if (!TOKEN_SHAPE.test(token))
+            throw new TokenError(`${file} doesn't hold a serve token; run \`docsworth serve --rotate-token\``);
+        return token;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Write a new token to `file` through a fresh 0600 file in the same directory. When the
+ * token is first created, the new file is linked into place, so of two servers starting
+ * at once only one token wins and both read it; a rotation renames over the old one.
+ */
+function writeToken(dir, file, replace) {
+    const tmp = join(dir, `.${TOKEN_FILE}.${process.pid}.${randomBytes(4).toString("hex")}`);
+    const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        writeSync(fd, `${randomBytes(32).toString("base64url")}\n`);
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (replace)
+        return renameSync(tmp, file); // replaces a symlink itself, never its target
+    try {
+        linkSync(tmp, file);
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err; // another start won
+    }
+    finally {
+        unlinkSync(tmp);
+    }
+}
+/** The serve token kept in `dir`, created on first use, or replaced with `rotate`. */
+export function loadToken(dir, opts = {}) {
+    ensureDir(dir);
+    const file = join(dir, TOKEN_FILE);
+    if (opts.rotate)
+        writeToken(dir, file, true);
+    else if (readToken(file) === null)
+        writeToken(dir, file, false);
+    return readToken(file);
+}
+/** Constant-time comparison of a presented token with the expected one. */
+export function tokenMatches(expected, presented) {
+    if (typeof presented !== "string")
+        return false;
+    const a = Buffer.from(expected);
+    const b = Buffer.from(presented);
+    return a.length === b.length && timingSafeEqual(a, b);
+}