@lelouchhe/webagent 0.7.0 → 0.9.0

package/lib/files/paths.js

@@ -0,0 +1,155 @@
+/**
+ * Path resolution and directory listing helpers for the file viewer.
+ *
+ * Contract (confirmed design): the viewer accepts *absolute* paths or `~`
+ * prefixes only — relative paths are rejected outright so there is no base
+ * ambiguity to exploit. `~` expands to HOME, then `realpath` canonicalizes
+ * symlinks and `..` segments once; every path on the system is legal by
+ * design (single-owner personal tool), so there is deliberately no escape
+ * rejection logic — the guards here prevent blocking on special files,
+ * unbounded directory scans, and whole-file buffering.
+ */
+import { constants } from "node:fs";
+import { open, opendir, realpath, stat, } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, basename } from "node:path";
+import { expandHomePath } from "../home-path.js";
+import { MAX_LIST_ITEMS } from "./limits.js";
+/** HTTP status-backed error; routes map it to a JSON error response. */
+export class FilePathError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Expand a user-supplied path string into an absolute path.
+ * Accepts `/absolute/path` and `~/...` / `~`. Everything else (including
+ * `~user` and bare relative paths) is rejected with 400.
+ */
+export function expandPath(raw, home = homedir()) {
+    if (raw.length === 0)
+        throw new FilePathError(400, "Missing path");
+    if (raw.includes("\0"))
+        throw new FilePathError(400, "Invalid path");
+    const expanded = expandHomePath(raw, home);
+    if (raw.startsWith("~") && expanded === raw) {
+        throw new FilePathError(400, "Unsupported ~user expansion");
+    }
+    if (!isAbsolute(expanded)) {
+        throw new FilePathError(400, "Path must be absolute or start with ~");
+    }
+    return expanded;
+}
+/** realpath canonicalization; missing paths map to 404. */
+export async function canonicalize(target) {
+    try {
+        return await realpath(target);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new FilePathError(404, "Path does not exist");
+        }
+        throw err;
+    }
+}
+/** stat a canonical path; non-regular files (fifo/socket/device) → 400. */
+export async function statMeta(path) {
+    const s = await stat(path);
+    let kind;
+    if (s.isFile())
+        kind = "file";
+    else if (s.isDirectory())
+        kind = "dir";
+    else
+        throw new FilePathError(400, "Not a regular file or directory");
+    return {
+        path,
+        name: basename(path),
+        kind,
+        size: s.size,
+        mtime: s.mtimeMs,
+    };
+}
+/**
+ * List one directory: scan at most MAX_LIST_ITEMS plus one sentinel raw entry,
+ * omit dotfiles/special nodes, then sort the bounded result dirs-first and
+ * lexicographically. Entries that vanish mid-list are skipped.
+ */
+export async function listDirectory(target) {
+    const dir = await opendir(target);
+    const entries = [];
+    let scanned = 0;
+    let truncated = false;
+    // Dir's async iterator closes the descriptor both at EOF and on break.
+    for await (const entry of dir) {
+        scanned++;
+        // Read one sentinel beyond the cap so `truncated` is authoritative,
+        // but never materialize/sort an unbounded directory.
+        if (scanned > MAX_LIST_ITEMS) {
+            truncated = true;
+            break;
+        }
+        if (entry.name.startsWith("."))
+            continue;
+        try {
+            const s = await stat(join(target, entry.name));
+            // Only expose targets the viewer can actually open. Symlinks to
+            // regular files/dirs pass because stat follows them; fifos, sockets,
+            // and devices are omitted rather than mislabelled as files.
+            if (!s.isDirectory() && !s.isFile())
+                continue;
+            entries.push({
+                name: entry.name,
+                kind: s.isDirectory() ? "dir" : "file",
+                size: s.isFile() ? s.size : null,
+                mtime: s.mtimeMs,
+            });
+        }
+        catch {
+            // Raced deletion — skip rather than fail the whole listing.
+        }
+    }
+    entries.sort(compareEntries);
+    return { entries, truncated };
+}
+function compareEntries(a, b) {
+    if (a.kind !== b.kind)
+        return a.kind === "dir" ? -1 : 1;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+/** Read up to `n` bytes from the head of a regular file (mime sniffing). */
+export async function readHead(file, n = 4096) {
+    const h = await open(file, "r");
+    try {
+        const st = await h.stat();
+        const len = Math.min(st.size, n);
+        const buf = Buffer.alloc(len);
+        if (len > 0)
+            await h.read(buf, 0, len, 0);
+        return buf;
+    }
+    finally {
+        await h.close();
+    }
+}
+/**
+ * Open without following a final symlink and without blocking on a FIFO.
+ * Windows lacks equivalent POSIX flags; fstat below remains authoritative.
+ */
+export function openForStreaming(file) {
+    const safeFlags = process.platform === "win32"
+        ? constants.O_RDONLY
+        : constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+    return open(file, safeFlags);
+}
+/** Read mime-sniff bytes from an already validated descriptor. */
+export async function readHandleHead(handle, size, n = 4096) {
+    const len = Math.min(size, n);
+    const buf = Buffer.alloc(len);
+    if (len === 0)
+        return buf;
+    const { bytesRead } = await handle.read(buf, 0, len, 0);
+    return buf.subarray(0, bytesRead);
+}

package/lib/files/routes.js

@@ -0,0 +1,232 @@
+/**
+ * File viewer HTTP routes — read-only access to arbitrary local files.
+ *
+ * URL space claimed: `/api/v1/files/{info,list,content}`.
+ * Sessionless by design (confirmed): the caller passes an absolute or
+ * `~`-prefixed path; the server own `~` expansion + realpath canonicalization.
+ * Relative paths are rejected. Bearer auth is enforced by the shared
+ * `/api/**` gate in routes.ts — these paths are deliberately NOT in the
+ * public whitelist, with one exception: `content` IS whitelisted so
+ * `<img>` / `<a download>` can fetch without an Authorization header, and
+ * it instead requires an HMAC sig+exp signed URL (issued by `info`),
+ * mirroring the attachment scheme.
+ *
+ * Guards (see paths.ts + limits.ts): only regular files/dirs are served
+ * (no fifos/sockets/devices), directory scans and inline previews are bounded,
+ * downloads stream with backpressure, and responses carry nosniff + a
+ * restrictive CSP. The viewer renders text/markdown/image only — nothing here
+ * executes content.
+ */
+import { basename, dirname } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { signAttachmentUrl, verifyAttachmentSig } from "../auth.js";
+import { buildContentDisposition, sniffMime } from "../attachments.js";
+import { HTTP_STATUS } from "../http-status.js";
+import { abbreviateHomePath } from "../home-path.js";
+import { log } from "../log.js";
+import { MAX_IMAGE_BYTES, MAX_TEXT_PREVIEW_BYTES } from "./limits.js";
+import { canonicalize, expandPath, FilePathError, listDirectory, openForStreaming, readHandleHead, readHead, statMeta, } from "./paths.js";
+const flog = log.scope("files");
+const CONTENT_TTL_SECONDS = 3600; // signed URLs live 1h, like attachments
+const SNIFF_BYTES = 4096;
+function fileSystemError(err) {
+    const code = err?.code;
+    if (code === "EACCES" || code === "EPERM") {
+        return new FilePathError(HTTP_STATUS.FORBIDDEN, "Permission denied");
+    }
+    if (code === "ENOENT" || code === "ENOTDIR") {
+        return new FilePathError(HTTP_STATUS.NOT_FOUND, "Path does not exist");
+    }
+    if (code === "ELOOP" ||
+        code === "EINVAL" ||
+        code === "ENAMETOOLONG" ||
+        code === "ERR_INVALID_ARG_VALUE") {
+        return new FilePathError(HTTP_STATUS.BAD_REQUEST, "Invalid path");
+    }
+    return null;
+}
+function json(res, status, body) {
+    res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+    });
+    res.end(JSON.stringify(body));
+}
+function previewLimitFor(mime) {
+    const m = mime.toLowerCase();
+    if (m.startsWith("image/"))
+        return MAX_IMAGE_BYTES;
+    if (m.startsWith("text/"))
+        return MAX_TEXT_PREVIEW_BYTES;
+    return null;
+}
+/** Expand + canonicalize a caller-supplied path; 400 on empty/relative. */
+async function resolvePath(raw) {
+    if (!raw)
+        throw new FilePathError(400, "Missing path");
+    return canonicalize(expandPath(raw));
+}
+function contentBasePath(pathRaw) {
+    return `/api/v1/files/content?path=${encodeURIComponent(pathRaw)}`;
+}
+async function streamHandle(res, handle, size) {
+    const stream = handle.createReadStream({
+        autoClose: false,
+        start: 0,
+        ...(size > 0 ? { end: size - 1 } : {}),
+    });
+    try {
+        await pipeline(stream, res);
+    }
+    catch (err) {
+        // Headers are already committed. A client disconnect or disk read error
+        // must terminate the stream, never fall through to a second JSON response.
+        if (!res.destroyed) {
+            res.destroy(err instanceof Error ? err : undefined);
+        }
+    }
+}
+export async function handleFileRoutes(req, res, deps) {
+    const url = req.url ?? "/";
+    if (!url.startsWith("/api/v1/files"))
+        return false;
+    const m = url.match(/^\/api\/v1\/files\/(info|list|content)(?:\?(.*))?$/);
+    if (!m)
+        return false;
+    const method = req.method ?? "GET";
+    if (method !== "GET") {
+        res.setHeader("Allow", "GET");
+        json(res, HTTP_STATUS.METHOD_NOT_ALLOWED, {
+            error: "Read-only: GET only",
+        });
+        return true;
+    }
+    try {
+        const params = new URLSearchParams(m[2]);
+        const pathRaw = params.get("path") ?? "";
+        switch (m[1]) {
+            case "info":
+                await handleInfo(res, deps, pathRaw);
+                return true;
+            case "list":
+                await handleList(res, pathRaw);
+                return true;
+            case "content":
+                await handleContent(res, deps, pathRaw, params);
+                return true;
+        }
+    }
+    catch (err) {
+        if (err instanceof FilePathError) {
+            json(res, err.status, { error: err.message });
+            return true;
+        }
+        const fsError = fileSystemError(err);
+        if (fsError) {
+            json(res, fsError.status, { error: fsError.message });
+            return true;
+        }
+        flog.error("file route failed", { url, error: String(err) });
+        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, { error: "internal_error" });
+        return true;
+    }
+    return false;
+}
+async function handleInfo(res, deps, pathRaw) {
+    const canonical = await resolvePath(pathRaw);
+    const meta = await statMeta(canonical);
+    const out = {
+        path: meta.path,
+        pathDisplay: abbreviateHomePath(meta.path),
+        name: meta.name,
+        kind: meta.kind,
+        size: meta.size,
+        mtime: meta.mtime,
+    };
+    if (meta.kind === "file") {
+        const mime = await sniffMime(await readHead(canonical, SNIFF_BYTES));
+        const previewLimit = previewLimitFor(mime);
+        out.mime = mime;
+        if (previewLimit !== null)
+            out.maxBytes = previewLimit;
+        if (deps.secret) {
+            const basePath = contentBasePath(canonical);
+            out.contentUrl = `${basePath}&${signAttachmentUrl(basePath, deps.secret, CONTENT_TTL_SECONDS)}`;
+        }
+    }
+    json(res, HTTP_STATUS.OK, out);
+}
+async function handleList(res, pathRaw) {
+    const canonical = await resolvePath(pathRaw);
+    const meta = await statMeta(canonical);
+    if (meta.kind !== "dir") {
+        throw new FilePathError(HTTP_STATUS.BAD_REQUEST, "Not a directory");
+    }
+    const { entries, truncated } = await listDirectory(canonical);
+    const parent = dirname(canonical);
+    json(res, HTTP_STATUS.OK, {
+        path: canonical,
+        pathDisplay: abbreviateHomePath(canonical),
+        parent,
+        parentDisplay: abbreviateHomePath(parent),
+        truncated,
+        entries,
+    });
+}
+async function handleContent(res, deps, pathRaw, params) {
+    const basePath = contentBasePath(pathRaw);
+    const sig = params.get("sig") ?? "";
+    const exp = params.get("exp") ?? "";
+    // content is whitelisted in auth-middleware.ts (media tags / downloads
+    // cannot send Authorization headers), so it must verify its own URL.
+    // Unlike the older attachment route, this new security-sensitive route
+    // fails closed when no signing secret is wired.
+    if (!deps.secret) {
+        json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+            error: "file_content_signing_unavailable",
+        });
+        return;
+    }
+    if (!sig || !exp || !verifyAttachmentSig(basePath, exp, sig, deps.secret)) {
+        res.writeHead(HTTP_STATUS.UNAUTHORIZED, {
+            "Content-Type": "application/json",
+        });
+        res.end(JSON.stringify({ error: "Unauthorized" }));
+        return;
+    }
+    const canonical = await resolvePath(pathRaw);
+    // `info` signs the realpath-canonical string. If that path now resolves to
+    // another target (for example it was replaced by a symlink), the old
+    // capability must not silently acquire authority over the new target.
+    if (canonical !== pathRaw) {
+        json(res, HTTP_STATUS.UNAUTHORIZED, { error: "Unauthorized" });
+        return;
+    }
+    const handle = await openForStreaming(canonical);
+    try {
+        const stats = await handle.stat();
+        if (!stats.isFile()) {
+            throw new FilePathError(HTTP_STATUS.BAD_REQUEST, "Not a regular file");
+        }
+        const mime = await sniffMime(await readHandleHead(handle, stats.size, SNIFF_BYTES));
+        const previewLimit = previewLimitFor(mime);
+        const disposition = previewLimit !== null && stats.size <= previewLimit
+            ? "inline"
+            : "attachment";
+        res.writeHead(HTTP_STATUS.OK, {
+            "Content-Type": mime,
+            "X-Content-Type-Options": "nosniff",
+            // Ordinary project files change in place; never let reopening show a
+            // cached pre-edit body under the same path-bound signed URL.
+            "Cache-Control": "no-store",
+            // Belt-and-braces: even if a mime mis-sniff ever lets a browser
+            // interpret this body as HTML, it can't load any subresource.
+            "Content-Security-Policy": "default-src 'none'",
+            "Content-Disposition": buildContentDisposition(disposition, basename(canonical)),
+        });
+        await streamHandle(res, handle, stats.size);
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}

package/lib/home-path.js

@@ -0,0 +1,35 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, sep } from "node:path";
+const NATIVE_PATH = { isAbsolute, join, relative, sep };
+function portableDisplayPath(input, path) {
+    return path.sep === "\\" ? input.replace(/\\/g, "/") : input;
+}
+/**
+ * Expand the current user's HOME shorthand with one authoritative grammar.
+ * Both `~/` and `~\` are accepted; named-user forms stay untouched.
+ */
+export function expandHomePath(input, home = homedir(), path = NATIVE_PATH) {
+    if (input === "~")
+        return home;
+    if (input.startsWith("~/") || input.startsWith("~\\")) {
+        const tail = input.slice(2).replace(/[\\/]/g, path.sep);
+        return path.join(home, tail);
+    }
+    return input;
+}
+/**
+ * Abbreviate HOME and normalize Windows display paths to portable `/`
+ * separators. Canonical filesystem paths remain native and are stored/signed
+ * separately; this function is exclusively for UI round-tripping.
+ */
+export function abbreviateHomePath(input, home = homedir(), path = NATIVE_PATH) {
+    const relativePath = path.relative(home, input);
+    if (relativePath === "")
+        return "~";
+    if (relativePath === ".." ||
+        relativePath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativePath)) {
+        return portableDisplayPath(input, path);
+    }
+    return `~/${portableDisplayPath(relativePath, path)}`;
+}

package/lib/http-status.js

@@ -7,6 +7,7 @@ export const HTTP_STATUS = Object.freeze({
     UNAUTHORIZED: 401,
     FORBIDDEN: 403,
     NOT_FOUND: 404,
+    METHOD_NOT_ALLOWED: 405,
     CONFLICT: 409,
     GONE: 410,
     PAYLOAD_TOO_LARGE: 413,

package/lib/message-cleanup.js

@@ -6,13 +6,14 @@ const DAY_MS = 24 * 60 * 60 * 1000;
  * Returns the number of rows removed. `now` is injectable for tests.
  * ttlDays=0 means "keep forever" — returns 0 without touching the DB.
  */
-export function sweepOnce(store, ttlDays, now = Date.now()) {
+export function sweepOnce(store, ttlDays, now = Date.now(), onPendingCountChange) {
     if (ttlDays <= 0)
         return 0;
     const threshold = now - ttlDays * DAY_MS;
     const removed = store.deleteOlderThan(threshold);
     if (removed > 0) {
         mlog.info("ttl sweep", { removed, ttl_days: ttlDays });
+        onPendingCountChange?.(store.countUnprocessed());
     }
     return removed;
 }
@@ -23,14 +24,14 @@ export function sweepOnce(store, ttlDays, now = Date.now()) {
  *
  * ttlDays=0 disables the scheduler entirely (handle.armed=false).
  */
-export function startMessageCleanup(store, ttlDays) {
-    sweepOnce(store, ttlDays);
+export function startMessageCleanup(store, ttlDays, onPendingCountChange) {
+    sweepOnce(store, ttlDays, Date.now(), onPendingCountChange);
     if (ttlDays <= 0) {
         return { armed: false, stop: () => { } };
     }
     const timer = setInterval(() => {
         try {
-            sweepOnce(store, ttlDays);
+            sweepOnce(store, ttlDays, Date.now(), onPendingCountChange);
         }
         catch (err) {
             mlog.error("ttl sweep failed", { error: err });