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

package/dist/lib/instance-id.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Which server instance this process is.
+ *
+ * On Fly every machine gets `FLY_MACHINE_ID`, and it is also the value the
+ * proxy's `fly-replay: instance=<id>` header addresses — so the same string
+ * both stamps a job row and routes a handshake back to its owner.
+ * `NODETOOL_INSTANCE_ID` overrides it for tests and for other multi-instance
+ * deployments.
+ *
+ * Null means single-machine: nothing to route to, and every feature keyed off
+ * this is inert — which is also what a malformed value gets. The id is written
+ * into a response header verbatim (`fly-replay: instance=<id>`), so anything
+ * outside {@link INSTANCE_ID_PATTERN} is rejected here rather than trusted to
+ * be caught downstream.
+ */
+export declare function getInstanceId(): string | null;
+/**
+ * What an instance id may contain. Fly machine ids are hex, but other
+ * deployments name their instances; the bound that matters is that the value
+ * cannot carry CRLF into a response header.
+ */
+export declare const INSTANCE_ID_PATTERN: RegExp;
+/** True for a value safe to interpolate into a header. */
+export declare function isValidInstanceId(value: string): boolean;
+//# sourceMappingURL=instance-id.d.ts.map

package/dist/lib/instance-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-id.d.ts","sourceRoot":"","sources":["../../src/lib/instance-id.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,IAAI,CAc7C;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAAqB,CAAC;AAEtD,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAExD"}

package/dist/lib/instance-id.js

@@ -0,0 +1,44 @@
+import { createLogger } from "@nodetool-ai/config";
+const log = createLogger("nodetool.websocket.instance-id");
+const warnedAbout = new Set();
+/**
+ * Which server instance this process is.
+ *
+ * On Fly every machine gets `FLY_MACHINE_ID`, and it is also the value the
+ * proxy's `fly-replay: instance=<id>` header addresses — so the same string
+ * both stamps a job row and routes a handshake back to its owner.
+ * `NODETOOL_INSTANCE_ID` overrides it for tests and for other multi-instance
+ * deployments.
+ *
+ * Null means single-machine: nothing to route to, and every feature keyed off
+ * this is inert — which is also what a malformed value gets. The id is written
+ * into a response header verbatim (`fly-replay: instance=<id>`), so anything
+ * outside {@link INSTANCE_ID_PATTERN} is rejected here rather than trusted to
+ * be caught downstream.
+ */
+export function getInstanceId() {
+    const configured = process.env["NODETOOL_INSTANCE_ID"] ?? process.env["FLY_MACHINE_ID"];
+    const trimmed = configured?.trim();
+    if (!trimmed)
+        return null;
+    if (!isValidInstanceId(trimmed)) {
+        // Called per run start and per upgrade, so say it once per bad value.
+        if (!warnedAbout.has(trimmed)) {
+            warnedAbout.add(trimmed);
+            log.warn("Ignoring a malformed instance id", { value: trimmed });
+        }
+        return null;
+    }
+    return trimmed;
+}
+/**
+ * What an instance id may contain. Fly machine ids are hex, but other
+ * deployments name their instances; the bound that matters is that the value
+ * cannot carry CRLF into a response header.
+ */
+export const INSTANCE_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+/** True for a value safe to interpolate into a header. */
+export function isValidInstanceId(value) {
+    return INSTANCE_ID_PATTERN.test(value);
+}
+//# sourceMappingURL=instance-id.js.map

package/dist/lib/instance-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-id.js","sourceRoot":"","sources":["../../src/lib/instance-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,GAAG,GAAG,YAAY,CAAC,gCAAgC,CAAC,CAAC;AAE3D,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,UAAU,GACd,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACvE,MAAM,OAAO,GAAG,UAAU,EAAE,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,sEAAsE;QACtE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACzB,GAAG,CAAC,IAAI,CAAC,kCAAkC,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QACnE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AAEtD,0DAA0D;AAC1D,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,OAAO,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC"}

package/dist/lib/link-codes.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ */
+/** How long a link code stays usable. */
+export declare const LINK_CODE_TTL_MS: number;
+/** A code the bridge minted, waiting for a signed-in user to claim it. */
+export interface BotMintedLinkCode {
+    kind: "external";
+    provider: string;
+    externalId: string;
+    expiresAtMs: number;
+}
+/** A code a signed-in user minted, waiting for an external account to claim it. */
+export interface WebMintedLinkCode {
+    kind: "user";
+    provider: string;
+    userId: string;
+    expiresAtMs: number;
+}
+export type LinkCode = BotMintedLinkCode | WebMintedLinkCode;
+export interface MintedLinkCode {
+    code: string;
+    expiresAtMs: number;
+}
+export interface LinkCodeStoreOptions {
+    /** Injected clock, so expiry is testable without waiting. */
+    now?: () => number;
+    ttlMs?: number;
+}
+export declare class LinkCodeStore {
+    private readonly codes;
+    private readonly now;
+    private readonly ttlMs;
+    constructor(options?: LinkCodeStoreOptions);
+    /** Mint a code bound to an external account, awaiting a NodeTool user. */
+    mintForExternalAccount(provider: string, externalId: string): MintedLinkCode;
+    /** Mint a code bound to a NodeTool user, awaiting an external account. */
+    mintForUser(provider: string, userId: string): MintedLinkCode;
+    /**
+     * 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: string): LinkCode | 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: string): LinkCode | null;
+    /** Codes currently outstanding — for tests and diagnostics. */
+    get size(): number;
+    private mint;
+    private prune;
+}
+/**
+ * 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 declare const sharedLinkCodes: LinkCodeStore;
+//# sourceMappingURL=link-codes.d.ts.map

package/dist/lib/link-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-codes.d.ts","sourceRoot":"","sources":["../../src/lib/link-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,yCAAyC;AACzC,eAAO,MAAM,gBAAgB,QAAiB,CAAC;AAE/C,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,QAAQ,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IACrD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B,YAAY,OAAO,GAAE,oBAAyB,EAG7C;IAED,0EAA0E;IAC1E,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAO3E;IAED,0EAA0E;IAC1E,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAO5D;IAED;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAGlC;IAED;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAMrC;IAED,+DAA+D;IAC/D,IAAI,IAAI,IAAI,MAAM,CAGjB;IAED,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,KAAK;CAMd;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,eAAsB,CAAC"}

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":"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"}

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"}