@nodetool-ai/websocket 0.7.0-rc.23 → 0.8.1

package/dist/lib/link-codes.js

@@ -0,0 +1,100 @@
+/**
+ * One-time link codes for the external-identity flow, shared by the two
+ * surfaces that mint and consume them.
+ *
+ * A link always writes the same `external_identities` row, but it can start
+ * from either end, and the half the code carries is the half the starter
+ * already knows:
+ *
+ * - **Bot-minted** (`POST /api/integrations/:provider/link/start`, service
+ *   token): the bridge knows the external account, not the NodeTool user. The
+ *   code carries `externalId` and is redeemed by a signed-in browser, which
+ *   supplies the user.
+ * - **Web-minted** (`integrations.createLinkCode` over tRPC, user session): the
+ *   browser knows the user, not the external account. The code carries
+ *   `userId`, goes into a `t.me/<bot>?start=<code>` deep link, and is redeemed
+ *   by the bridge's `/link/complete`, which supplies the external id.
+ *
+ * Both halves are therefore always present at redemption, and neither surface
+ * ever accepts the half it did not mint on the caller's word: a browser cannot
+ * name an external account, and the bridge cannot name a user.
+ *
+ * Storage is in-memory on purpose (design §5): a code lives ten minutes, and
+ * losing one on restart costs a second `/link`, not data.
+ */
+import { randomBytes } from "node:crypto";
+/** How long a link code stays usable. */
+export const LINK_CODE_TTL_MS = 10 * 60 * 1000;
+export class LinkCodeStore {
+    codes = new Map();
+    now;
+    ttlMs;
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+        this.ttlMs = options.ttlMs ?? LINK_CODE_TTL_MS;
+    }
+    /** Mint a code bound to an external account, awaiting a NodeTool user. */
+    mintForExternalAccount(provider, externalId) {
+        return this.mint({
+            kind: "external",
+            provider,
+            externalId,
+            expiresAtMs: this.now() + this.ttlMs
+        });
+    }
+    /** Mint a code bound to a NodeTool user, awaiting an external account. */
+    mintForUser(provider, userId) {
+        return this.mint({
+            kind: "user",
+            provider,
+            userId,
+            expiresAtMs: this.now() + this.ttlMs
+        });
+    }
+    /**
+     * Read a code without spending it, so a confirmation page can name the
+     * account it is about to link. An expired code reads as absent.
+     */
+    peek(code) {
+        this.prune();
+        return this.codes.get(code) ?? null;
+    }
+    /**
+     * Spend a code. Single use: it is removed whether or not the caller goes on
+     * to accept it, so a guessed code cannot be probed against several accounts.
+     */
+    consume(code) {
+        this.prune();
+        const entry = this.codes.get(code);
+        if (!entry)
+            return null;
+        this.codes.delete(code);
+        return entry;
+    }
+    /** Codes currently outstanding — for tests and diagnostics. */
+    get size() {
+        this.prune();
+        return this.codes.size;
+    }
+    mint(entry) {
+        this.prune();
+        const code = randomBytes(24).toString("base64url");
+        this.codes.set(code, entry);
+        return { code, expiresAtMs: entry.expiresAtMs };
+    }
+    prune() {
+        const cutoff = this.now();
+        for (const [code, entry] of this.codes) {
+            if (entry.expiresAtMs <= cutoff)
+                this.codes.delete(code);
+        }
+    }
+}
+/**
+ * The process-wide store. Both directions must see one another's codes — a
+ * deep link minted in the browser is redeemed by the bridge, and vice versa —
+ * so the service routes and the tRPC router share this instance. Tests inject
+ * their own.
+ */
+export const sharedLinkCodes = new LinkCodeStore();
+//# sourceMappingURL=link-codes.js.map

package/dist/lib/link-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-codes.js","sourceRoot":"","sources":["../../src/lib/link-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,yCAAyC;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AA+B/C,MAAM,OAAO,aAAa;IACP,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;IACpC,GAAG,CAAe;IAClB,KAAK,CAAS;IAE/B,YAAY,OAAO,GAAyB,EAAE;QAC5C,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,gBAAgB,CAAC;IACjD,CAAC;IAED,0EAA0E;IAC1E,sBAAsB,CAAC,QAAgB,EAAE,UAAkB;QACzD,OAAO,IAAI,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,UAAU;YAChB,QAAQ;YACR,UAAU;YACV,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK;SACrC,CAAC,CAAC;IACL,CAAC;IAED,0EAA0E;IAC1E,WAAW,CAAC,QAAgB,EAAE,MAAc;QAC1C,OAAO,IAAI,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,MAAM;YACZ,QAAQ;YACR,MAAM;YACN,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK;SACrC,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,IAAY;QACf,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;IACtC,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,IAAY;QAClB,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,+DAA+D;IAC/D,IAAI,IAAI;QACN,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAEO,IAAI,CAAC,KAAe;QAC1B,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,MAAM,IAAI,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;IAClD,CAAC;IAEO,KAAK;QACX,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACvC,IAAI,KAAK,CAAC,WAAW,IAAI,MAAM;gBAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,aAAa,EAAE,CAAC"}

package/dist/lib/local-asset-upload.d.ts

@@ -0,0 +1,5 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { type HttpApiOptions } from "../http-api.js";
+/** Stage multipart bytes on disk before publishing an asset. */
+export declare function handleLocalAssetUpload(request: FastifyRequest, reply: FastifyReply, options: HttpApiOptions): Promise<void>;
+//# sourceMappingURL=local-asset-upload.d.ts.map

package/dist/lib/local-asset-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-asset-upload.d.ts","sourceRoot":"","sources":["../../src/lib/local-asset-upload.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG5D,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,gBAAgB,CAAC;AAExB,gEAAgE;AAChE,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAuDf"}

package/dist/lib/local-asset-upload.js

@@ -0,0 +1,69 @@
+import { createWriteStream } from "node:fs";
+import { mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { getMaxLocalUploadBytes } from "@nodetool-ai/storage";
+import { bridge } from "./bridge.js";
+import { handleAssetsRoot } from "../http-api.js";
+/** Stage multipart bytes on disk before publishing an asset. */
+export async function handleLocalAssetUpload(request, reply, options) {
+    await bridge(request, reply, async (webRequest) => {
+        const directory = await mkdtemp(join(tmpdir(), "nodetool-upload-"));
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        request.raw.once("aborted", abort);
+        let metadata = {};
+        let file;
+        try {
+            for await (const part of request.parts({
+                limits: {
+                    fileSize: getMaxLocalUploadBytes(),
+                    files: 1,
+                    fields: 2,
+                    parts: 3,
+                    fieldSize: 1024 * 1024
+                }
+            })) {
+                if (part.type === "file") {
+                    if (part.fieldname !== "file") {
+                        part.file.resume();
+                        throw Object.assign(new Error("Expected multipart field 'file'"), { statusCode: 400 });
+                    }
+                    const path = join(directory, "upload");
+                    await pipeline(part.file, createWriteStream(path, { flags: "wx", mode: 0o600 }), {
+                        signal: controller.signal
+                    });
+                    if (part.file.truncated) {
+                        throw Object.assign(new Error("Upload exceeds maximum size"), { statusCode: 413 });
+                    }
+                    file = {
+                        path,
+                        name: part.filename,
+                        contentType: part.mimetype,
+                        size: (await stat(path)).size
+                    };
+                }
+                else if (part.fieldname === "json" || part.fieldname === "asset") {
+                    if (part.valueTruncated) {
+                        throw Object.assign(new Error("Asset metadata is too large"), { statusCode: 413 });
+                    }
+                    try {
+                        metadata = typeof part.value === "string" ? JSON.parse(part.value) : part.value;
+                    }
+                    catch {
+                        throw Object.assign(new Error("Invalid asset metadata JSON"), { statusCode: 400 });
+                    }
+                }
+            }
+            controller.signal.throwIfAborted();
+            const staged = file ? { metadata, file } : { metadata };
+            return await handleAssetsRoot(webRequest, options, staged);
+        }
+        finally {
+            request.raw.removeListener("aborted", abort);
+            await rm(directory, { recursive: true, force: true });
+        }
+    }, options.userIdHeader);
+}
+//# sourceMappingURL=local-asset-upload.js.map

package/dist/lib/local-asset-upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-asset-upload.js","sourceRoot":"","sources":["../../src/lib/local-asset-upload.ts"],"names":[],"mappings":"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"}

package/dist/lib/local-file-access.d.ts

@@ -0,0 +1,31 @@
+export declare const LOCAL_FILE_ROOTS_ENV = "NODETOOL_LOCAL_FILE_ROOTS";
+/** The `NODETOOL_LOCAL_FILE_ROOTS` entry that lifts the containment check. */
+export declare const UNRESTRICTED_ROOT = "*";
+/** Whether a resolved root list places no containment requirement on a path. */
+export declare function isUnrestricted(roots: string[]): boolean;
+/** Roots a local path may resolve into. Never empty. */
+export declare function getLocalFileRoots(): string[];
+export type LocalPathDenial = "invalid" | "outside_roots" | "sensitive";
+export type LocalPathResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: LocalPathDenial;
+};
+/** Human-readable reason, safe to return to the caller. */
+export declare function localPathDenialMessage(reason: LocalPathDenial): string;
+/**
+ * Resolve a caller-supplied path against the allowed roots.
+ *
+ * A relative path resolves against the first root (against home when the roots
+ * are unrestricted), so the file browser's "." still means "home" out of the
+ * box. A leading `~` expands. Containment is checked twice:
+ * lexically on the resolved path, then again on the symlink-resolved path —
+ * a link at an allowed location (`~/shortcut -> /etc`) passes the first check
+ * but the stat/stream that follows would traverse it. realpath runs against
+ * the deepest existing ancestor so a not-yet-created leaf still gets its
+ * parent chain verified.
+ */
+export declare function resolveLocalPath(userPath: string, roots?: string[]): Promise<LocalPathResult>;
+//# sourceMappingURL=local-file-access.d.ts.map

package/dist/lib/local-file-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-access.d.ts","sourceRoot":"","sources":["../../src/lib/local-file-access.ts"],"names":[],"mappings":"AA8BA,eAAO,MAAM,oBAAoB,8BAA8B,CAAC;AAEhE,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAEvD;AAkBD,wDAAwD;AACxD,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAe5C;AAuCD,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,eAAe,GAAG,WAAW,CAAC;AAExE,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC;AAE3C,2DAA2D;AAC3D,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAYtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAM,EAAwB,GACpC,OAAO,CAAC,eAAe,CAAC,CA8C1B"}

package/dist/lib/local-file-access.js

@@ -0,0 +1,169 @@
+/**
+ * Path policy shared by the two surfaces that read arbitrary local files: the
+ * REST preview stream (`GET /api/files/local`) and the tRPC file browser
+ * (`files.list`).
+ *
+ * The two used to disagree. The browser was sandboxed to `$HOME`, while the
+ * preview stream took any absolute path and only refused a handful of
+ * sensitive dotfiles — so an authenticated caller could stream `/etc/passwd`,
+ * the SQLite database, or a `.env` holding `SECRETS_MASTER_KEY`. Both now
+ * resolve through `resolveLocalPath`, which is an allowlist: a path must sit
+ * inside a configured root, and the denylist applies on top of that.
+ *
+ * Roots default to the user's home directory. `NODETOOL_LOCAL_FILE_ROOTS`
+ * (platform path-delimited) replaces that default, which is how a desktop user
+ * previews media off an external volume.
+ *
+ * The single entry `*` lifts the containment check entirely. That is for the
+ * desktop app, which spawns this server as the user's own process on loopback
+ * and lets them drag a file in from anywhere — the run path already reads any
+ * absolute `file://` URI, so restricting only the *preview* left a dropped file
+ * that runs fine but shows a broken image. The denylist below still applies.
+ *
+ * These surfaces are already disabled when `NODETOOL_ENV=production`; this is
+ * the second layer, for the dev/desktop/self-hosted deployments where the file
+ * browser is live and more than one person can reach the port.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+export const LOCAL_FILE_ROOTS_ENV = "NODETOOL_LOCAL_FILE_ROOTS";
+/** The `NODETOOL_LOCAL_FILE_ROOTS` entry that lifts the containment check. */
+export const UNRESTRICTED_ROOT = "*";
+/** Whether a resolved root list places no containment requirement on a path. */
+export function isUnrestricted(roots) {
+    return roots.includes(UNRESTRICTED_ROOT);
+}
+/**
+ * Never part of a legitimate preview or browse flow, even inside a root.
+ * Mirrors the Electron main-process denylist so the file-read surfaces agree.
+ */
+const SENSITIVE_HOME_ENTRIES = [
+    ".ssh",
+    ".aws",
+    ".gnupg",
+    ".kube",
+    ".docker",
+    ".config/gcloud",
+    ".netrc",
+    ".pgpass",
+    ".npmrc"
+];
+/** Roots a local path may resolve into. Never empty. */
+export function getLocalFileRoots() {
+    const configured = process.env[LOCAL_FILE_ROOTS_ENV];
+    if (configured) {
+        const roots = configured
+            .split(path.delimiter)
+            .map((entry) => entry.trim())
+            .filter(Boolean)
+            .map((entry) => entry === UNRESTRICTED_ROOT
+            ? UNRESTRICTED_ROOT
+            : path.resolve(expandTilde(entry)));
+        if (roots.length > 0)
+            return roots;
+    }
+    return [path.resolve(os.homedir())];
+}
+function expandTilde(candidate) {
+    if (candidate === "~")
+        return os.homedir();
+    if (candidate.startsWith("~/") || candidate.startsWith("~\\")) {
+        return path.join(os.homedir(), candidate.slice(2));
+    }
+    return candidate;
+}
+function isWithin(candidate, root) {
+    return candidate === root || candidate.startsWith(root + path.sep);
+}
+function isWithinAnyRoot(candidate, roots) {
+    return roots.some((root) => isWithin(candidate, root));
+}
+function isSensitivePath(resolved) {
+    const home = path.resolve(os.homedir());
+    return SENSITIVE_HOME_ENTRIES.some((entry) => {
+        const forbidden = path.resolve(home, entry);
+        return isWithin(resolved, forbidden);
+    });
+}
+/** The roots plus their symlink-resolved forms, deduped. */
+async function realRoots(roots) {
+    const all = new Set(roots);
+    for (const root of roots) {
+        try {
+            all.add(await fs.realpath(root));
+        }
+        catch {
+            // A configured root that doesn't exist just contributes nothing.
+        }
+    }
+    return [...all];
+}
+/** Human-readable reason, safe to return to the caller. */
+export function localPathDenialMessage(reason) {
+    switch (reason) {
+        case "invalid":
+            return "Invalid path";
+        case "sensitive":
+            return "Access to this path is not permitted";
+        case "outside_roots":
+            return ("Path is outside the allowed roots " +
+                `(set ${LOCAL_FILE_ROOTS_ENV} to allow more)`);
+    }
+}
+/**
+ * Resolve a caller-supplied path against the allowed roots.
+ *
+ * A relative path resolves against the first root (against home when the roots
+ * are unrestricted), so the file browser's "." still means "home" out of the
+ * box. A leading `~` expands. Containment is checked twice:
+ * lexically on the resolved path, then again on the symlink-resolved path —
+ * a link at an allowed location (`~/shortcut -> /etc`) passes the first check
+ * but the stat/stream that follows would traverse it. realpath runs against
+ * the deepest existing ancestor so a not-yet-created leaf still gets its
+ * parent chain verified.
+ */
+export async function resolveLocalPath(userPath, roots = getLocalFileRoots()) {
+    if (!userPath || userPath.includes("\0")) {
+        return { ok: false, reason: "invalid" };
+    }
+    const unrestricted = isUnrestricted(roots);
+    const relativeBase = unrestricted ? os.homedir() : roots[0];
+    const expanded = expandTilde(userPath);
+    const resolved = path.isAbsolute(expanded)
+        ? path.resolve(expanded)
+        : path.resolve(relativeBase, expanded);
+    if (!unrestricted && !isWithinAnyRoot(resolved, roots)) {
+        return { ok: false, reason: "outside_roots" };
+    }
+    if (isSensitivePath(resolved)) {
+        return { ok: false, reason: "sensitive" };
+    }
+    // A root can itself sit behind a symlink (macOS `/var` → `/private/var`), so
+    // the post-realpath containment check compares against the real roots too.
+    const resolvedRoots = unrestricted ? roots : await realRoots(roots);
+    let probe = resolved;
+    for (;;) {
+        try {
+            const real = await fs.realpath(probe);
+            // Re-anchor the not-yet-resolved tail onto the real ancestor so a link
+            // in the middle of the path can't smuggle the leaf out of the roots.
+            const realResolved = path.join(real, path.relative(probe, resolved));
+            if (!unrestricted && !isWithinAnyRoot(realResolved, resolvedRoots)) {
+                return { ok: false, reason: "outside_roots" };
+            }
+            if (isSensitivePath(realResolved)) {
+                return { ok: false, reason: "sensitive" };
+            }
+            break;
+        }
+        catch {
+            const parent = path.dirname(probe);
+            if (parent === probe)
+                break; // reached the filesystem root unresolved
+            probe = parent;
+        }
+    }
+    return { ok: true, path: resolved };
+}
+//# sourceMappingURL=local-file-access.js.map

package/dist/lib/local-file-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-access.js","sourceRoot":"","sources":["../../src/lib/local-file-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9B,MAAM,CAAC,MAAM,oBAAoB,GAAG,2BAA2B,CAAC;AAEhE,8EAA8E;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC,gFAAgF;AAChF,MAAM,UAAU,cAAc,CAAC,KAAe;IAC5C,OAAO,KAAK,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,sBAAsB,GAAG;IAC7B,MAAM;IACN,MAAM;IACN,QAAQ;IACR,OAAO;IACP,SAAS;IACT,gBAAgB;IAChB,QAAQ;IACR,SAAS;IACT,QAAQ;CACT,CAAC;AAEF,wDAAwD;AACxD,MAAM,UAAU,iBAAiB;IAC/B,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IACrD,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,KAAK,GAAG,UAAU;aACrB,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;aACrB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;aAC5B,MAAM,CAAC,OAAO,CAAC;aACf,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACb,KAAK,KAAK,iBAAiB;YACzB,CAAC,CAAC,iBAAiB;YACnB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CACrC,CAAC;QACJ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,WAAW,CAAC,SAAiB;IACpC,IAAI,SAAS,KAAK,GAAG;QAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;IAC3C,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9D,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,QAAQ,CAAC,SAAiB,EAAE,IAAY;IAC/C,OAAO,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;AACrE,CAAC;AAED,SAAS,eAAe,CAAC,SAAiB,EAAE,KAAe;IACzD,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,eAAe,CAAC,QAAgB;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IACxC,OAAO,sBAAsB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;QAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC5C,OAAO,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,4DAA4D;AAC5D,KAAK,UAAU,SAAS,CAAC,KAAe;IACtC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,iEAAiE;QACnE,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;AAClB,CAAC;AAQD,2DAA2D;AAC3D,MAAM,UAAU,sBAAsB,CAAC,MAAuB;IAC5D,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,SAAS;YACZ,OAAO,cAAc,CAAC;QACxB,KAAK,WAAW;YACd,OAAO,sCAAsC,CAAC;QAChD,KAAK,eAAe;YAClB,OAAO,CACL,oCAAoC;gBACpC,QAAQ,oBAAoB,iBAAiB,CAC9C,CAAC;IACN,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAgB,EAChB,KAAK,GAAa,iBAAiB,EAAE;IAErC,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC1C,CAAC;IAED,MAAM,YAAY,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,YAAY,GAAG,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAE5D,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QACxC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;QACxB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IAEzC,IAAI,CAAC,YAAY,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;QACvD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAChD,CAAC;IACD,IAAI,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC5C,CAAC;IAED,6EAA6E;IAC7E,2EAA2E;IAC3E,MAAM,aAAa,GAAG,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC;IAEpE,IAAI,KAAK,GAAG,QAAQ,CAAC;IACrB,SAAS,CAAC;QACR,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACtC,uEAAuE;YACvE,qEAAqE;YACrE,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;YACrE,IAAI,CAAC,YAAY,IAAI,CAAC,eAAe,CAAC,YAAY,EAAE,aAAa,CAAC,EAAE,CAAC;gBACnE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;YAChD,CAAC;YACD,IAAI,eAAe,CAAC,YAAY,CAAC,EAAE,CAAC;gBAClC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;YAC5C,CAAC;YACD,MAAM;QACR,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACnC,IAAI,MAAM,KAAK,KAAK;gBAAE,MAAM,CAAC,yCAAyC;YACtE,KAAK,GAAG,MAAM,CAAC;QACjB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AACtC,CAAC"}

package/dist/lib/localhost-trust.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Helpers for deciding whether a connection may bypass authentication because
+ * it originates from the local host.
+ *
+ * The naive "trust anything from 127.0.0.1/::1" rule is dangerous behind a
+ * reverse proxy, container network, or SSH tunnel: in those topologies the
+ * proxy itself connects from loopback, so a blanket localhost bypass silently
+ * disables auth in exactly the deployment where it is needed. These helpers
+ * make the trust explicit and opt-in, and keep X-Forwarded-For parsing scoped
+ * to a configured set of proxies.
+ */
+/**
+ * Parse a boolean-ish environment variable.
+ *
+ * Returns `undefined` when the variable is unset, empty, or unrecognized so the
+ * caller can apply its own default.
+ */
+export declare function parseBoolEnv(value: string | undefined): boolean | undefined;
+/** True when `ip` is an IPv4 or IPv6 loopback address. */
+export declare function isLoopbackAddress(ip: string | undefined | null): boolean;
+/**
+ * Resolve whether loopback connections should bypass authentication.
+ *
+ * - An explicit `NODETOOL_TRUST_LOCALHOST` value (true/false) always wins.
+ * - Otherwise the bypass defaults OFF whenever auth is enforced — so a
+ *   reverse-proxied/containerized deployment doesn't silently accept every
+ *   request — and ON when auth is not enforced (local desktop/dev).
+ */
+export declare function resolveTrustLocalhost(opts: {
+    envValue: string | undefined;
+    enforceAuth: boolean;
+}): boolean;
+/**
+ * Parse `NODETOOL_TRUSTED_PROXIES` into a list of IPs/CIDRs suitable for
+ * Fastify's `trustProxy` option. Empty input means no proxy is trusted, so
+ * X-Forwarded-For is ignored and the socket peer address is used instead.
+ */
+export declare function parseTrustedProxies(value: string | undefined): string[];
+/**
+ * Parse `NODETOOL_TRUST_LOCAL_NETWORKS` into a list of source CIDRs whose
+ * connections are trusted to run as the local user in Local mode without a
+ * token. Same comma-separated shape as {@link parseTrustedProxies}.
+ *
+ * This exists because Docker (and other NAT topologies) rewrite the source of a
+ * published-port connection to the bridge gateway (e.g. 172.17.0.1), so the
+ * request never arrives from loopback and the {@link isLoopbackAddress} bypass
+ * can't fire. Trusting the bridge range restores the "single local user" model
+ * for containerized self-hosting.
+ */
+export declare function parseTrustedLocalNetworks(value: string | undefined): string[];
+/**
+ * Whether `ip` falls inside `cidr`. Supports IPv4 CIDRs (and IPv4-mapped IPv6
+ * peers), a bare IP as a /32, and the `0.0.0.0/0` / `::/0` wildcards that match
+ * everything. Genuine IPv6 is matched only by exact (normalized) equality.
+ */
+export declare function isIpInCidr(ip: string | undefined | null, cidr: string): boolean;
+/** True when `ip` matches any of the trusted source `networks` (CIDRs/IPs). */
+export declare function isTrustedLocalAddress(ip: string | undefined | null, networks: string[]): boolean;
+//# sourceMappingURL=localhost-trust.d.ts.map

package/dist/lib/localhost-trust.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localhost-trust.d.ts","sourceRoot":"","sources":["../../src/lib/localhost-trust.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAO3E;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAUxE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAIV;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAMvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAE7E;AA0BD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAsB/E;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAC7B,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAET"}

package/dist/lib/localhost-trust.js

@@ -0,0 +1,139 @@
+/**
+ * Helpers for deciding whether a connection may bypass authentication because
+ * it originates from the local host.
+ *
+ * The naive "trust anything from 127.0.0.1/::1" rule is dangerous behind a
+ * reverse proxy, container network, or SSH tunnel: in those topologies the
+ * proxy itself connects from loopback, so a blanket localhost bypass silently
+ * disables auth in exactly the deployment where it is needed. These helpers
+ * make the trust explicit and opt-in, and keep X-Forwarded-For parsing scoped
+ * to a configured set of proxies.
+ */
+/**
+ * Parse a boolean-ish environment variable.
+ *
+ * Returns `undefined` when the variable is unset, empty, or unrecognized so the
+ * caller can apply its own default.
+ */
+export function parseBoolEnv(value) {
+    if (value == null)
+        return undefined;
+    const v = value.trim().toLowerCase();
+    if (v === "")
+        return undefined;
+    if (v === "1" || v === "true" || v === "yes" || v === "on")
+        return true;
+    if (v === "0" || v === "false" || v === "no" || v === "off")
+        return false;
+    return undefined;
+}
+/** True when `ip` is an IPv4 or IPv6 loopback address. */
+export function isLoopbackAddress(ip) {
+    if (!ip)
+        return false;
+    const addr = ip.trim().toLowerCase();
+    return (addr === "::1" ||
+        addr === "::ffff:127.0.0.1" ||
+        // Whole 127.0.0.0/8 block is loopback.
+        addr.startsWith("127.") ||
+        addr.startsWith("::ffff:127."));
+}
+/**
+ * Resolve whether loopback connections should bypass authentication.
+ *
+ * - An explicit `NODETOOL_TRUST_LOCALHOST` value (true/false) always wins.
+ * - Otherwise the bypass defaults OFF whenever auth is enforced — so a
+ *   reverse-proxied/containerized deployment doesn't silently accept every
+ *   request — and ON when auth is not enforced (local desktop/dev).
+ */
+export function resolveTrustLocalhost(opts) {
+    const explicit = parseBoolEnv(opts.envValue);
+    if (explicit !== undefined)
+        return explicit;
+    return !opts.enforceAuth;
+}
+/**
+ * Parse `NODETOOL_TRUSTED_PROXIES` into a list of IPs/CIDRs suitable for
+ * Fastify's `trustProxy` option. Empty input means no proxy is trusted, so
+ * X-Forwarded-For is ignored and the socket peer address is used instead.
+ */
+export function parseTrustedProxies(value) {
+    if (!value)
+        return [];
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/**
+ * Parse `NODETOOL_TRUST_LOCAL_NETWORKS` into a list of source CIDRs whose
+ * connections are trusted to run as the local user in Local mode without a
+ * token. Same comma-separated shape as {@link parseTrustedProxies}.
+ *
+ * This exists because Docker (and other NAT topologies) rewrite the source of a
+ * published-port connection to the bridge gateway (e.g. 172.17.0.1), so the
+ * request never arrives from loopback and the {@link isLoopbackAddress} bypass
+ * can't fire. Trusting the bridge range restores the "single local user" model
+ * for containerized self-hosting.
+ */
+export function parseTrustedLocalNetworks(value) {
+    return parseTrustedProxies(value);
+}
+/** Parse a dotted-quad IPv4 string to a 32-bit integer, or null if malformed. */
+function ipv4ToInt(ip) {
+    if (!ip)
+        return null;
+    const m = ip.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (!m)
+        return null;
+    const parts = m.slice(1).map((n) => Number(n));
+    if (parts.some((p) => p > 255))
+        return null;
+    return ((parts[0] * 2 ** 24 + parts[1] * 2 ** 16 + parts[2] * 2 ** 8 + parts[3]) >>>
+        0);
+}
+/**
+ * Reduce an address to its dotted-quad IPv4 form when possible, unwrapping the
+ * IPv4-mapped IPv6 form Node often reports for bridged connections
+ * (`::ffff:172.17.0.1` → `172.17.0.1`). Returns null for genuine IPv6.
+ */
+function toIpv4(ip) {
+    const addr = ip.trim().toLowerCase();
+    const mapped = addr.startsWith("::ffff:") ? addr.slice(7) : addr;
+    return /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(mapped) ? mapped : null;
+}
+/**
+ * Whether `ip` falls inside `cidr`. Supports IPv4 CIDRs (and IPv4-mapped IPv6
+ * peers), a bare IP as a /32, and the `0.0.0.0/0` / `::/0` wildcards that match
+ * everything. Genuine IPv6 is matched only by exact (normalized) equality.
+ */
+export function isIpInCidr(ip, cidr) {
+    if (!ip)
+        return false;
+    const c = cidr.trim().toLowerCase();
+    if (!c)
+        return false;
+    if (c === "0.0.0.0/0" || c === "::/0")
+        return true;
+    const slash = c.indexOf("/");
+    const range = slash === -1 ? c : c.slice(0, slash);
+    const prefixStr = slash === -1 ? null : c.slice(slash + 1);
+    const ipInt = ipv4ToInt(toIpv4(ip));
+    const rangeInt = ipv4ToInt(toIpv4(range));
+    if (ipInt !== null && rangeInt !== null) {
+        if (prefixStr === "")
+            return false;
+        const prefix = prefixStr === null ? 32 : Number(prefixStr);
+        if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32)
+            return false;
+        const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+        return ((ipInt ^ rangeInt) & mask) === 0;
+    }
+    // Not an IPv4 CIDR — fall back to exact IPv6 match (prefix ignored).
+    return ip.trim().toLowerCase() === range;
+}
+/** True when `ip` matches any of the trusted source `networks` (CIDRs/IPs). */
+export function isTrustedLocalAddress(ip, networks) {
+    return networks.some((cidr) => isIpInCidr(ip, cidr));
+}
+//# sourceMappingURL=localhost-trust.js.map

package/dist/lib/localhost-trust.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localhost-trust.js","sourceRoot":"","sources":["../../src/lib/localhost-trust.ts"],"names":[],"mappings":"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"}

package/dist/lib/mcp-mount.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Whether this server offers `/mcp`, and where.
+ *
+ * The mount's production gate is read in two places — `server.ts` registers
+ * the route by it, and the agent-access router reports it to the settings UI
+ * — so it lives here rather than as the same expression written twice. A UI
+ * that says "connected" over a route that was never registered is worse than
+ * no UI.
+ */
+/**
+ * The `/mcp` streamable-HTTP mount carries the full agent toolbelt, so it is
+ * off in production unless the operator opts in.
+ */
+export declare function isMcpHttpEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** The env var that turns the mount on, named so the UI and the boot log agree. */
+export declare const MCP_ENABLE_FLAG = "NODETOOL_ENABLE_MCP";
+/**
+ * The absolute `/mcp` URL, when the operator configured a public address.
+ *
+ * Null otherwise — the server behind a proxy cannot know the address a
+ * browser reached it at, so the client falls back to its own origin, which is
+ * by construction an address that works.
+ */
+export declare function configuredMcpUrl(env?: NodeJS.ProcessEnv): string | null;
+//# sourceMappingURL=mcp-mount.d.ts.map

package/dist/lib/mcp-mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-mount.d.ts","sourceRoot":"","sources":["../../src/lib/mcp-mount.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE9E;AAED,mFAAmF;AACnF,eAAO,MAAM,eAAe,wBAAwB,CAAC;AAErD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,IAAI,CAIf"}