@valentinkolb/filegate 2.3.6 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/filegate",
-  "version": "2.3.6",
+  "version": "2.4.0",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/config.ts

@@ -29,6 +29,10 @@ export const config = {
   uploadExpirySecs: int("UPLOAD_EXPIRY_HOURS", 24) * 60 * 60,
   uploadTempDir: process.env.UPLOAD_TEMP_DIR ?? "/tmp/filegate-uploads",
   diskCleanupIntervalMs: int("DISK_CLEANUP_INTERVAL_HOURS", 6) * 60 * 60 * 1000,
+  indexEnabled: process.env.ENABLE_INDEX !== "false",
+  indexDatabaseUrl: process.env.INDEX_DATABASE_URL ?? "sqlite://:memory:",
+  indexRescanIntervalMs: int("INDEX_RESCAN_INTERVAL_MINUTES", 30) * 60 * 1000,
+  indexScanConcurrency: int("INDEX_SCAN_CONCURRENCY", 4),
   devUid: optionalInt("DEV_UID_OVERRIDE"),
   devGid: optionalInt("DEV_GID_OVERRIDE"),
   get isDev() {

package/src/handlers/files.ts

@@ -7,6 +7,15 @@ import { validatePath, validateSameBase } from "../lib/path";
 import { parseOwnershipBody, applyOwnership, applyOwnershipRecursive } from "../lib/ownership";
 import { jsonResponse, binaryResponse, requiresAuth } from "../lib/openapi";
 import { v } from "../lib/validator";
+import {
+  indexFile,
+  identifyPath,
+  resolveId,
+  removeFromIndex,
+  removeFromIndexRecursive,
+  updateIndexPath,
+  enrichFileInfoBatch,
+} from "../lib/index";
 import {
   FileInfoSchema,
   DirInfoSchema,
@@ -75,6 +84,44 @@ const getDirSize = async (dirPath: string): Promise<number> => {
   }
 };
 
+const resolveQueryPath = async (
+  path: string | undefined,
+  id: string | undefined,
+): Promise<{ ok: true; path: string } | { ok: false; status: 400 | 404; error: string }> => {
+  if (id) {
+    if (!config.indexEnabled) {
+      return { ok: false, status: 400, error: "index disabled" };
+    }
+    const resolved = await resolveId(id);
+    if (!resolved) return { ok: false, status: 404, error: "not found" };
+    return { ok: true, path: join(resolved.basePath, resolved.relPath) };
+  }
+
+  if (!path) {
+    return { ok: false, status: 400, error: "path or id required" };
+  }
+
+  return { ok: true, path };
+};
+
+const withFileId = async (info: FileInfo, basePath: string, absPath: string): Promise<FileInfo> => {
+  if (!config.indexEnabled) return info;
+  const relPath = relative(basePath, absPath);
+  const fileId = await identifyPath(basePath, relPath);
+  return fileId ? { ...info, fileId } : info;
+};
+
+const enrichListingItems = async (items: FileInfo[], basePath: string, dirPath: string): Promise<FileInfo[]> => {
+  if (!config.indexEnabled || items.length === 0) return items;
+  const relPaths = items.map((item) => relative(basePath, join(dirPath, item.path)));
+  const tempItems = items.map((item, i) => ({ ...item, path: relPaths[i] ?? item.path }));
+  const enriched = await enrichFileInfoBatch(tempItems, basePath);
+  return items.map((item, i) => {
+    const fileId = enriched[i]?.fileId;
+    return fileId ? { ...item, fileId } : item;
+  });
+};
+
 const getFileInfo = async (path: string, relativeTo?: string, computeDirSize?: boolean): Promise<FileInfo> => {
   const file = Bun.file(path);
   const s = await stat(path);
@@ -108,9 +155,12 @@ app.get(
   }),
   v("query", InfoQuerySchema),
   async (c) => {
-    const { path, showHidden, computeSizes } = c.req.valid("query");
+    const { path, id, showHidden, computeSizes } = c.req.valid("query");
+
+    const resolved = await resolveQueryPath(path, id);
+    if (!resolved.ok) return c.json({ error: resolved.error }, resolved.status);
 
-    const result = await validatePath(path, { allowBasePath: true });
+    const result = await validatePath(resolved.path, { allowBasePath: true });
     if (!result.ok) return c.json({ error: result.error }, result.status);
 
     let s;
@@ -121,13 +171,14 @@ app.get(
     }
 
     if (!s.isDirectory()) {
-      return c.json(await getFileInfo(result.realPath));
+      const info = await getFileInfo(result.realPath);
+      return c.json(await withFileId(info, result.basePath, result.realPath));
     }
 
     const entries = await readdir(result.realPath, { withFileTypes: true });
 
     // Parallel file info retrieval (computeSizes only when requested)
-    const items = (
+    let items = (
       await Promise.all(
         entries
           .filter((e) => showHidden || !e.name.startsWith("."))
@@ -135,9 +186,12 @@ app.get(
       )
     ).filter((item): item is FileInfo => item !== null);
 
+    items = await enrichListingItems(items, result.basePath, result.realPath);
+
     const info = await getFileInfo(result.realPath);
+    const infoWithId = await withFileId(info, result.basePath, result.realPath);
     const totalSize = computeSizes ? items.reduce((sum, item) => sum + item.size, 0) : 0;
-    return c.json({ ...info, size: totalSize, items, total: items.length });
+    return c.json({ ...infoWithId, size: totalSize, items, total: items.length });
   },
 );
 
@@ -160,9 +214,12 @@ app.get(
   }),
   v("query", ContentQuerySchema),
   async (c) => {
-    const { path, inline } = c.req.valid("query");
+    const { path, id, inline } = c.req.valid("query");
+
+    const resolved = await resolveQueryPath(path, id);
+    if (!resolved.ok) return c.json({ error: resolved.error }, resolved.status);
 
-    const result = await validatePath(path);
+    const result = await validatePath(resolved.path);
     if (!result.ok) return c.json({ error: result.error }, result.status);
 
     let s;
@@ -209,11 +266,12 @@ app.get(
       const archive = new Bun.Archive(files);
       const archiveBlob = await archive.blob();
 
+      const tarName = `${dirName}.tar`;
       return new Response(archiveBlob, {
         headers: {
           "Content-Type": "application/x-tar",
-          "Content-Disposition": `attachment; filename="${dirName}.tar"`,
-          "X-File-Name": `${dirName}.tar`,
+          "Content-Disposition": `attachment; filename="${encodeURIComponent(tarName)}"; filename*=UTF-8''${encodeURIComponent(tarName)}`,
+          "X-File-Name": encodeURIComponent(tarName),
         },
       });
     }
@@ -229,14 +287,15 @@ app.get(
     }
 
     const filename = basename(result.realPath);
+    const encodedFilename = encodeURIComponent(filename);
     const disposition = inline ? "inline" : "attachment";
 
     return new Response(file.stream(), {
       headers: {
         "Content-Type": file.type,
         "Content-Length": String(file.size),
-        "Content-Disposition": `${disposition}; filename="${filename}"`,
-        "X-File-Name": filename,
+        "Content-Disposition": `${disposition}; filename="${encodedFilename}"; filename*=UTF-8''${encodedFilename}`,
+        "X-File-Name": encodedFilename,
       },
     });
   },
@@ -318,7 +377,27 @@ app.put(
       return c.json({ error: ownershipError }, 500);
     }
 
-    return c.json(await getFileInfo(result.realPath), 201);
+    const info = await getFileInfo(result.realPath);
+
+    if (!config.indexEnabled) {
+      return c.json(info, 201);
+    }
+
+    try {
+      const s = await stat(result.realPath);
+      const relPath = relative(result.basePath, result.realPath);
+      const outcome = await indexFile(result.basePath, relPath, {
+        dev: s.dev,
+        ino: s.ino,
+        size: s.size,
+        mtimeMs: s.mtimeMs,
+        isDirectory: s.isDirectory(),
+      });
+      return c.json({ ...info, fileId: outcome.id }, 201);
+    } catch (err) {
+      console.error("[Filegate] Index update failed:", err);
+      return c.json(info, 201);
+    }
   },
 );
 
@@ -352,7 +431,27 @@ app.post(
       return c.json({ error: ownershipError }, 500);
     }
 
-    return c.json(await getFileInfo(result.realPath), 201);
+    const info = await getFileInfo(result.realPath);
+
+    if (!config.indexEnabled) {
+      return c.json(info, 201);
+    }
+
+    try {
+      const s = await stat(result.realPath);
+      const relPath = relative(result.basePath, result.realPath);
+      const outcome = await indexFile(result.basePath, relPath, {
+        dev: s.dev,
+        ino: s.ino,
+        size: s.size,
+        mtimeMs: s.mtimeMs,
+        isDirectory: s.isDirectory(),
+      });
+      return c.json({ ...info, fileId: outcome.id }, 201);
+    } catch (err) {
+      console.error("[Filegate] Index update failed:", err);
+      return c.json(info, 201);
+    }
   },
 );
 
@@ -372,9 +471,12 @@ app.delete(
   }),
   v("query", PathQuerySchema),
   async (c) => {
-    const { path } = c.req.valid("query");
+    const { path, id } = c.req.valid("query");
+
+    const resolved = await resolveQueryPath(path, id);
+    if (!resolved.ok) return c.json({ error: resolved.error }, resolved.status);
 
-    const result = await validatePath(path);
+    const result = await validatePath(resolved.path);
     if (!result.ok) return c.json({ error: result.error }, result.status);
 
     let s;
@@ -384,6 +486,19 @@ app.delete(
       return c.json({ error: "not found" }, 404);
     }
 
+    if (config.indexEnabled) {
+      const relPath = relative(result.basePath, result.realPath);
+      if (s.isDirectory()) {
+        await removeFromIndexRecursive(result.basePath, relPath).catch((err) => {
+          console.error("[Filegate] Index remove failed:", err);
+        });
+      } else {
+        await removeFromIndex(result.basePath, relPath).catch((err) => {
+          console.error("[Filegate] Index remove failed:", err);
+        });
+      }
+    }
+
     await rm(result.realPath, { recursive: s.isDirectory() });
     return c.body(null, 204);
   },
@@ -432,6 +547,9 @@ app.post(
         return c.json({ error: "source not found" }, 404);
       }
 
+      const sourceRelPath = relative(result.basePath, result.realPath);
+      const existingId = config.indexEnabled ? await identifyPath(result.basePath, sourceRelPath) : null;
+
       const targetPath = ensureUniqueName ? await getUniquePath(result.realTo) : result.realTo;
 
       await mkdir(join(targetPath, ".."), { recursive: true });
@@ -445,7 +563,32 @@ app.post(
         }
       }
 
-      return c.json(await getFileInfo(targetPath));
+      const info = await getFileInfo(targetPath);
+
+      if (!config.indexEnabled) {
+        return c.json(info);
+      }
+
+      try {
+        const targetRelPath = relative(result.basePath, targetPath);
+        if (existingId) {
+          await updateIndexPath(existingId, result.basePath, targetRelPath);
+          return c.json({ ...info, fileId: existingId });
+        }
+
+        const s = await stat(targetPath);
+        const outcome = await indexFile(result.basePath, targetRelPath, {
+          dev: s.dev,
+          ino: s.ino,
+          size: s.size,
+          mtimeMs: s.mtimeMs,
+          isDirectory: s.isDirectory(),
+        });
+        return c.json({ ...info, fileId: outcome.id });
+      } catch (err) {
+        console.error("[Filegate] Index update failed:", err);
+        return c.json(info);
+      }
     }
 
     // Copy: check if same base or cross-base with ownership
@@ -473,7 +616,27 @@ app.post(
         }
       }
 
-      return c.json(await getFileInfo(targetPath));
+      const info = await getFileInfo(targetPath);
+
+      if (!config.indexEnabled) {
+        return c.json(info);
+      }
+
+      try {
+        const targetRelPath = relative(sameBaseResult.basePath, targetPath);
+        const s = await stat(targetPath);
+        const outcome = await indexFile(sameBaseResult.basePath, targetRelPath, {
+          dev: s.dev,
+          ino: s.ino,
+          size: s.size,
+          mtimeMs: s.mtimeMs,
+          isDirectory: s.isDirectory(),
+        });
+        return c.json({ ...info, fileId: outcome.id });
+      } catch (err) {
+        console.error("[Filegate] Index update failed:", err);
+        return c.json(info);
+      }
     }
 
     // Cross-base copy - ownership is required
@@ -506,7 +669,27 @@ app.post(
       return c.json({ error: ownershipError }, 500);
     }
 
-    return c.json(await getFileInfo(targetPath));
+    const info = await getFileInfo(targetPath);
+
+    if (!config.indexEnabled) {
+      return c.json(info);
+    }
+
+    try {
+      const targetRelPath = relative(toResult.basePath, targetPath);
+      const s = await stat(targetPath);
+      const outcome = await indexFile(toResult.basePath, targetRelPath, {
+        dev: s.dev,
+        ino: s.ino,
+        size: s.size,
+        mtimeMs: s.mtimeMs,
+        isDirectory: s.isDirectory(),
+      });
+      return c.json({ ...info, fileId: outcome.id });
+    } catch (err) {
+      console.error("[Filegate] Index update failed:", err);
+      return c.json(info);
+    }
   },
 );
 

package/src/handlers/indexHandler.ts

@@ -0,0 +1,107 @@
+import { Hono } from "hono";
+import { describeRoute } from "hono-openapi";
+import { join } from "node:path";
+import { jsonResponse, requiresAuth } from "../lib/openapi";
+import { v } from "../lib/validator";
+import {
+  RescanResponseSchema,
+  IndexStatsSchema,
+  BulkResolveBodySchema,
+  BulkResolveResponseSchema,
+  ErrorSchema,
+} from "../schemas";
+import { config } from "../config";
+import { bulkResolve, getIndexStats } from "../lib/index";
+import { scanAll } from "../lib/scanner";
+
+const app = new Hono();
+
+app.post(
+  "/rescan",
+  describeRoute({
+    tags: ["Index"],
+    summary: "Rescan file index",
+    ...requiresAuth,
+    responses: {
+      200: jsonResponse(RescanResponseSchema, "Rescan completed"),
+      400: jsonResponse(ErrorSchema, "Bad request"),
+      500: jsonResponse(ErrorSchema, "Internal error"),
+    },
+  }),
+  async (c) => {
+    if (!config.indexEnabled) {
+      return c.json({ error: "index disabled" }, 400);
+    }
+
+    try {
+      const result = await scanAll();
+      return c.json(result);
+    } catch (err) {
+      console.error("[Filegate] Index rescan failed:", err);
+      return c.json({ error: "rescan failed" }, 500);
+    }
+  },
+);
+
+app.get(
+  "/stats",
+  describeRoute({
+    tags: ["Index"],
+    summary: "Get index stats",
+    ...requiresAuth,
+    responses: {
+      200: jsonResponse(IndexStatsSchema, "Index stats"),
+      400: jsonResponse(ErrorSchema, "Bad request"),
+      500: jsonResponse(ErrorSchema, "Internal error"),
+    },
+  }),
+  async (c) => {
+    if (!config.indexEnabled) {
+      return c.json({ error: "index disabled" }, 400);
+    }
+
+    try {
+      const stats = await getIndexStats();
+      return c.json(stats);
+    } catch (err) {
+      console.error("[Filegate] Index stats failed:", err);
+      return c.json({ error: "stats failed" }, 500);
+    }
+  },
+);
+
+app.post(
+  "/resolve",
+  describeRoute({
+    tags: ["Index"],
+    summary: "Resolve file IDs to paths",
+    ...requiresAuth,
+    responses: {
+      200: jsonResponse(BulkResolveResponseSchema, "Resolved paths"),
+      400: jsonResponse(ErrorSchema, "Bad request"),
+      500: jsonResponse(ErrorSchema, "Internal error"),
+    },
+  }),
+  v("json", BulkResolveBodySchema),
+  async (c) => {
+    if (!config.indexEnabled) {
+      return c.json({ error: "index disabled" }, 400);
+    }
+
+    try {
+      const { ids } = c.req.valid("json");
+      const resolved = await bulkResolve(ids);
+      const response: Record<string, string | null> = {};
+      for (const id of ids) {
+        const entry = resolved[id];
+        response[id] = entry ? join(entry.basePath, entry.relPath) : null;
+      }
+      return c.json(response);
+    } catch (err) {
+      console.error("[Filegate] Index resolve failed:", err);
+      return c.json({ error: "resolve failed" }, 500);
+    }
+  },
+);
+
+export default app;

package/src/handlers/search.ts

@@ -15,6 +15,7 @@ import {
   type SearchResult,
 } from "../schemas";
 import { config } from "../config";
+import { enrichFileInfoBatch } from "../lib/index";
 
 const app = new Hono();
 
@@ -128,6 +129,12 @@ app.get(
       validPaths.map((p) => searchInPath(p, pattern, showHidden, limit, files, directories)),
     );
 
+    if (config.indexEnabled) {
+      for (const result of results) {
+        result.files = await enrichFileInfoBatch(result.files, result.basePath);
+      }
+    }
+
     const totalFiles = results.reduce((sum, r) => sum + r.total, 0);
 
     return c.json({ results, totalFiles });

package/src/handlers/thumbnail.ts

@@ -1,11 +1,14 @@
 import { Hono } from "hono";
 import { describeRoute } from "hono-openapi";
 import { stat } from "node:fs/promises";
+import { join } from "node:path";
 import sharp from "sharp";
 import { validatePath } from "../lib/path";
 import { jsonResponse, requiresAuth } from "../lib/openapi";
 import { v } from "../lib/validator";
 import { ImageThumbnailQuerySchema, ErrorSchema } from "../schemas";
+import { config } from "../config";
+import { resolveId } from "../lib/index";
 
 const app = new Hono();
 
@@ -35,6 +38,26 @@ const FORMAT_MIME: Record<string, string> = {
   avif: "image/avif",
 };
 
+const resolveQueryPath = async (
+  path: string | undefined,
+  id: string | undefined,
+): Promise<{ ok: true; path: string } | { ok: false; status: 400 | 404; error: string }> => {
+  if (id) {
+    if (!config.indexEnabled) {
+      return { ok: false, status: 400, error: "index disabled" };
+    }
+    const resolved = await resolveId(id);
+    if (!resolved) return { ok: false, status: 404, error: "not found" };
+    return { ok: true, path: join(resolved.basePath, resolved.relPath) };
+  }
+
+  if (!path) {
+    return { ok: false, status: 400, error: "path or id required" };
+  }
+
+  return { ok: true, path };
+};
+
 // GET /thumbnail/image - Generate image thumbnail
 app.get(
   "/image",
@@ -62,10 +85,13 @@ app.get(
   }),
   v("query", ImageThumbnailQuerySchema),
   async (c) => {
-    const { path, width, height, fit, position, format, quality } = c.req.valid("query");
+    const { path, id, width, height, fit, position, format, quality } = c.req.valid("query");
+
+    const resolved = await resolveQueryPath(path, id);
+    if (!resolved.ok) return c.json({ error: resolved.error }, resolved.status);
 
     // Validate path
-    const result = await validatePath(path);
+    const result = await validatePath(resolved.path);
     if (!result.ok) return c.json({ error: result.error }, result.status);
 
     // Check if file exists and is a file

package/src/handlers/upload.ts

@@ -1,12 +1,13 @@
 import { Hono } from "hono";
 import { describeRoute } from "hono-openapi";
 import { mkdir, readdir, rm, stat, rename, readFile, writeFile } from "node:fs/promises";
-import { join, dirname } from "node:path";
+import { join, dirname, relative } from "node:path";
 import { getSemaphore } from "@henrygd/semaphore";
 import { validatePath } from "../lib/path";
 import { applyOwnership, type Ownership } from "../lib/ownership";
 import { jsonResponse, requiresAuth } from "../lib/openapi";
 import { v } from "../lib/validator";
+import { indexFile } from "../lib/index";
 import {
   UploadStartBodySchema,
   UploadStartResponseSchema,
@@ -326,6 +327,26 @@ app.post(
       const fullPath = join(meta.path, meta.filename);
       const file = Bun.file(fullPath);
       const s = await stat(fullPath);
+      let fileId: string | undefined;
+
+      if (config.indexEnabled) {
+        const pathResult = await validatePath(fullPath);
+        if (pathResult.ok) {
+          try {
+            const relPath = relative(pathResult.basePath, pathResult.realPath);
+            const outcome = await indexFile(pathResult.basePath, relPath, {
+              dev: s.dev,
+              ino: s.ino,
+              size: s.size,
+              mtimeMs: s.mtimeMs,
+              isDirectory: s.isDirectory(),
+            });
+            fileId = outcome.id;
+          } catch (err) {
+            console.error("[Filegate] Index update failed:", err);
+          }
+        }
+      }
 
       return c.json({
         completed: true as const,
@@ -338,6 +359,7 @@ app.post(
           isHidden: meta.filename.startsWith("."),
           checksum: meta.checksum,
           mimeType: file.type,
+          ...(fileId ? { fileId } : {}),
         },
       });
     }

package/src/index.ts

@@ -12,6 +12,9 @@ import filesRoutes from "./handlers/files";
 import searchRoutes from "./handlers/search";
 import uploadRoutes, { cleanupOrphanedChunks } from "./handlers/upload";
 import thumbnailRoutes from "./handlers/thumbnail";
+import indexRoutes from "./handlers/indexHandler";
+import { initIndex, closeIndex } from "./lib/index";
+import { scanAll } from "./lib/scanner";
 
 // Dev mode warning
 if (config.isDev) {
@@ -27,10 +30,42 @@ console.log(`[Filegate] ALLOWED_BASE_PATHS: ${config.allowedPaths.join(", ")}`);
 console.log(`[Filegate] MAX_UPLOAD_MB: ${config.maxUploadBytes / 1024 / 1024}`);
 console.log(`[Filegate] PORT: ${config.port}`);
 
+if (config.indexEnabled) {
+  await initIndex(config.indexDatabaseUrl);
+  console.log(`[Filegate] INDEX_DATABASE_URL: ${config.indexDatabaseUrl}`);
+}
+
 // Periodic disk cleanup for orphaned chunks (every 6h by default)
 setInterval(cleanupOrphanedChunks, config.diskCleanupIntervalMs);
 setTimeout(cleanupOrphanedChunks, 10_000); // Run 10s after startup
 
+if (config.indexEnabled) {
+  const runRescan = async () => {
+    try {
+      const result = await scanAll();
+      console.log(
+        `[Filegate] Index rescan: scanned=${result.scanned} skipped=${result.skipped} added=${result.added} moved=${result.moved} removed=${result.removed} durationMs=${result.durationMs}`,
+      );
+    } catch (err) {
+      console.error("[Filegate] Index rescan failed:", err);
+    }
+  };
+
+  setInterval(runRescan, config.indexRescanIntervalMs);
+  setTimeout(runRescan, 15_000);
+
+  const shutdown = async () => {
+    try {
+      await closeIndex();
+    } catch (err) {
+      console.error("[Filegate] Index shutdown failed:", err);
+    }
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
 // Main app
 const app = new Hono();
 
@@ -58,7 +93,8 @@ const api = new Hono()
   .route("/", filesRoutes)
   .route("/", searchRoutes)
   .route("/upload", uploadRoutes)
-  .route("/thumbnail", thumbnailRoutes);
+  .route("/thumbnail", thumbnailRoutes)
+  .route("/index", indexRoutes);
 
 app.route("/files", api);
 
@@ -88,6 +124,7 @@ app.onError((err, c) => {
 export default {
   port: config.port,
   fetch: app.fetch,
+  development: false,
 };
 
 console.log(`[Filegate] Listening on http://localhost:${config.port}`);

package/src/lib/index.ts

@@ -0,0 +1,325 @@
+import { SQL } from "bun";
+import type { FileInfo } from "../schemas";
+
+type StatInfo = {
+  dev: number;
+  ino: number;
+  size: number;
+  mtimeMs: number;
+  isDirectory: boolean;
+};
+
+export type IndexOutcome = {
+  id: string;
+  action: "existing" | "moved" | "added";
+};
+
+export type IndexStats = {
+  totalFiles: number;
+  totalDirs: number;
+  dbSizeBytes: number;
+  lastScanAt: number | null;
+};
+
+export type ScanState = {
+  mtimeMs: number;
+  scannedAt: number;
+};
+
+let sql: InstanceType<typeof SQL> | null = null;
+
+const getSql = (): InstanceType<typeof SQL> => {
+  if (!sql) throw new Error("index not initialized");
+  return sql;
+};
+
+const isSqliteUrl = (url: string): boolean => {
+  return url === ":memory:" || url.startsWith("sqlite:") || url.startsWith("file:");
+};
+
+const escapeLike = (value: string): string => value.replace(/[\\%_]/g, "\\$&");
+
+// --- Init ---
+export const initIndex = async (databaseUrl: string): Promise<void> => {
+  sql = new SQL(databaseUrl);
+
+  if (isSqliteUrl(databaseUrl)) {
+    await sql`PRAGMA journal_mode = WAL`.catch(() => {});
+    await sql`PRAGMA synchronous = NORMAL`.catch(() => {});
+  }
+
+  await sql`
+    CREATE TABLE IF NOT EXISTS file_index (
+      id TEXT PRIMARY KEY,
+      base_path TEXT NOT NULL,
+      rel_path TEXT NOT NULL,
+      dev INTEGER NOT NULL,
+      ino INTEGER NOT NULL,
+      size INTEGER NOT NULL,
+      mtime_ms INTEGER NOT NULL,
+      is_dir INTEGER NOT NULL DEFAULT 0,
+      indexed_at INTEGER NOT NULL,
+      UNIQUE(base_path, rel_path)
+    )
+  `;
+
+  await sql`CREATE INDEX IF NOT EXISTS idx_file_dev_ino ON file_index(dev, ino)`;
+  await sql`CREATE INDEX IF NOT EXISTS idx_file_base ON file_index(base_path)`;
+
+  await sql`
+    CREATE TABLE IF NOT EXISTS scan_state (
+      base_path TEXT NOT NULL,
+      dir_path TEXT NOT NULL,
+      mtime_ms INTEGER NOT NULL,
+      scanned_at INTEGER NOT NULL,
+      PRIMARY KEY(base_path, dir_path)
+    )
+  `;
+};
+
+export const closeIndex = async (): Promise<void> => {
+  await sql?.close();
+  sql = null;
+};
+
+// --- UUID v7 Generator ---
+export const generateId = (): string => {
+  const bytes = new Uint8Array(16);
+  const now = Date.now();
+
+  let time = now;
+  for (let i = 5; i >= 0; i--) {
+    bytes[i] = time & 0xff;
+    time = Math.floor(time / 256);
+  }
+
+  globalThis.crypto.getRandomValues(bytes.subarray(6));
+
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x70;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+
+  const hex = Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+};
+
+// --- Core CRUD ---
+export const indexFile = async (
+  basePath: string,
+  relPath: string,
+  s: StatInfo,
+  indexedAt: number = Date.now(),
+): Promise<IndexOutcome> => {
+  const db = getSql();
+
+  const [existingByPath] = await db`
+    SELECT id FROM file_index WHERE base_path = ${basePath} AND rel_path = ${relPath}
+  `;
+
+  if (existingByPath) {
+    await db`
+      UPDATE file_index
+      SET dev = ${s.dev}, ino = ${s.ino}, size = ${s.size}, mtime_ms = ${s.mtimeMs},
+          is_dir = ${s.isDirectory ? 1 : 0}, indexed_at = ${indexedAt}
+      WHERE id = ${existingByPath.id}
+    `;
+    return { id: existingByPath.id, action: "existing" };
+  }
+
+  const [existingByInode] = await db`
+    SELECT id FROM file_index WHERE dev = ${s.dev} AND ino = ${s.ino}
+  `;
+
+  if (existingByInode) {
+    await db`
+      UPDATE file_index
+      SET base_path = ${basePath}, rel_path = ${relPath}, size = ${s.size}, mtime_ms = ${s.mtimeMs},
+          is_dir = ${s.isDirectory ? 1 : 0}, indexed_at = ${indexedAt}
+      WHERE id = ${existingByInode.id}
+    `;
+    return { id: existingByInode.id, action: "moved" };
+  }
+
+  const id = generateId();
+  await db`
+    INSERT INTO file_index (id, base_path, rel_path, dev, ino, size, mtime_ms, is_dir, indexed_at)
+    VALUES (${id}, ${basePath}, ${relPath}, ${s.dev}, ${s.ino}, ${s.size}, ${s.mtimeMs},
+            ${s.isDirectory ? 1 : 0}, ${indexedAt})
+  `;
+
+  return { id, action: "added" };
+};
+
+export const resolveId = async (id: string): Promise<{ basePath: string; relPath: string } | null> => {
+  const db = getSql();
+  const [row] = await db`SELECT base_path, rel_path FROM file_index WHERE id = ${id}`;
+  return row ? { basePath: row.base_path, relPath: row.rel_path } : null;
+};
+
+export const identifyPath = async (basePath: string, relPath: string): Promise<string | null> => {
+  const db = getSql();
+  const [row] = await db`SELECT id FROM file_index WHERE base_path = ${basePath} AND rel_path = ${relPath}`;
+  return row?.id ?? null;
+};
+
+export const updateIndexPath = async (id: string, newBasePath: string, newRelPath: string): Promise<void> => {
+  const db = getSql();
+  await db`UPDATE file_index SET base_path = ${newBasePath}, rel_path = ${newRelPath} WHERE id = ${id}`;
+};
+
+export const removeFromIndex = async (basePath: string, relPath: string): Promise<void> => {
+  const db = getSql();
+  await db`DELETE FROM file_index WHERE base_path = ${basePath} AND rel_path = ${relPath}`;
+};
+
+export const removeFromIndexRecursive = async (basePath: string, relPath: string): Promise<void> => {
+  const db = getSql();
+
+  if (!relPath) {
+    await db`DELETE FROM file_index WHERE base_path = ${basePath}`;
+    return;
+  }
+
+  const prefix = `${escapeLike(relPath)}/`;
+  const likePattern = `${prefix}%`;
+
+  await db`
+    DELETE FROM file_index
+    WHERE base_path = ${basePath}
+      AND (rel_path = ${relPath} OR rel_path LIKE ${likePattern} ESCAPE '\\')
+  `;
+};
+
+// --- Scan State ---
+export const getScanState = async (basePath: string, dirPath: string): Promise<ScanState | null> => {
+  const db = getSql();
+  const [row] = await db`
+    SELECT mtime_ms, scanned_at FROM scan_state WHERE base_path = ${basePath} AND dir_path = ${dirPath}
+  `;
+  return row ? { mtimeMs: row.mtime_ms, scannedAt: row.scanned_at } : null;
+};
+
+export const setScanState = async (basePath: string, dirPath: string, mtimeMs: number, scannedAt: number): Promise<void> => {
+  const db = getSql();
+  const [row] = await db`
+    SELECT 1 as present FROM scan_state WHERE base_path = ${basePath} AND dir_path = ${dirPath}
+  `;
+  if (row) {
+    await db`
+      UPDATE scan_state SET mtime_ms = ${mtimeMs}, scanned_at = ${scannedAt}
+      WHERE base_path = ${basePath} AND dir_path = ${dirPath}
+    `;
+    return;
+  }
+
+  await db`
+    INSERT INTO scan_state (base_path, dir_path, mtime_ms, scanned_at)
+    VALUES (${basePath}, ${dirPath}, ${mtimeMs}, ${scannedAt})
+  `;
+};
+
+export const touchIndexedAtUnderDir = async (
+  basePath: string,
+  dirPath: string,
+  indexedAt: number,
+): Promise<void> => {
+  const db = getSql();
+
+  if (!dirPath) {
+    await db`UPDATE file_index SET indexed_at = ${indexedAt} WHERE base_path = ${basePath}`;
+    return;
+  }
+
+  const prefix = `${escapeLike(dirPath)}/`;
+  const likePattern = `${prefix}%`;
+
+  await db`
+    UPDATE file_index
+    SET indexed_at = ${indexedAt}
+    WHERE base_path = ${basePath}
+      AND (rel_path = ${dirPath} OR rel_path LIKE ${likePattern} ESCAPE '\\')
+  `;
+};
+
+export const removeStaleEntries = async (basePath: string, beforeMs: number): Promise<number> => {
+  const db = getSql();
+  const [countRow] = await db`
+    SELECT COUNT(*) as count FROM file_index WHERE base_path = ${basePath} AND indexed_at < ${beforeMs}
+  `;
+  const count = Number(countRow?.count ?? 0);
+  await db`DELETE FROM file_index WHERE base_path = ${basePath} AND indexed_at < ${beforeMs}`;
+  return count;
+};
+
+// --- Batch ---
+export const bulkResolve = async (
+  ids: string[],
+): Promise<Record<string, { basePath: string; relPath: string } | null>> => {
+  if (ids.length === 0) return {};
+
+  const db = getSql();
+  const rows = await db`SELECT id, base_path, rel_path FROM file_index WHERE id IN ${db(ids)}`;
+  const map = new Map<string, { basePath: string; relPath: string }>();
+
+  for (const row of rows) {
+    map.set(row.id, { basePath: row.base_path, relPath: row.rel_path });
+  }
+
+  const result: Record<string, { basePath: string; relPath: string } | null> = {};
+  for (const id of ids) {
+    result[id] = map.get(id) ?? null;
+  }
+
+  return result;
+};
+
+export const enrichFileInfo = async (info: FileInfo, basePath: string): Promise<FileInfo> => {
+  const fileId = await identifyPath(basePath, info.path);
+  return fileId ? { ...info, fileId } : info;
+};
+
+export const enrichFileInfoBatch = async (infos: FileInfo[], basePath: string): Promise<FileInfo[]> => {
+  if (infos.length === 0) return infos;
+  const db = getSql();
+  const paths = infos.map((i) => i.path);
+  const rows = await db`
+    SELECT rel_path, id FROM file_index WHERE base_path = ${basePath} AND rel_path IN ${db(paths)}
+  `;
+  const pathToId = new Map<string, string>();
+  for (const row of rows as { rel_path: string; id: string }[]) {
+    pathToId.set(row.rel_path, row.id);
+  }
+  return infos.map((info) => {
+    const fileId = pathToId.get(info.path);
+    return fileId ? { ...info, fileId } : info;
+  });
+};
+
+// --- Stats ---
+export const getIndexStats = async (): Promise<IndexStats> => {
+  const db = getSql();
+
+  const [fileRow] = await db`SELECT COUNT(*) as count FROM file_index WHERE is_dir = 0`;
+  const [dirRow] = await db`SELECT COUNT(*) as count FROM file_index WHERE is_dir = 1`;
+  const [scanRow] = await db`SELECT MAX(scanned_at) as last_scan_at FROM scan_state`;
+
+  let dbSizeBytes = 0;
+  try {
+    const [pageCountRow] = await db`PRAGMA page_count`;
+    const [pageSizeRow] = await db`PRAGMA page_size`;
+    const pageCount = Number(pageCountRow?.page_count ?? 0);
+    const pageSize = Number(pageSizeRow?.page_size ?? 0);
+    dbSizeBytes = pageCount * pageSize;
+  } catch {
+    dbSizeBytes = 0;
+  }
+
+  return {
+    totalFiles: Number(fileRow?.count ?? 0),
+    totalDirs: Number(dirRow?.count ?? 0),
+    dbSizeBytes,
+    lastScanAt: scanRow?.last_scan_at ?? null,
+  };
+};

package/src/lib/openapi.ts

@@ -28,6 +28,7 @@ export const openApiMeta: Partial<GenerateSpecOptions> = {
       { name: "Files", description: "File operations (info, download, upload, mkdir, move, copy, delete)" },
       { name: "Search", description: "File search with glob patterns" },
       { name: "Upload", description: "Resumable chunked uploads" },
+      { name: "Index", description: "File index management" },
     ],
     components: {
       securitySchemes: {

package/src/lib/scanner.ts

@@ -0,0 +1,121 @@
+import { readdir, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { config } from "../config";
+import { validatePath } from "./path";
+import {
+  indexFile,
+  getScanState,
+  setScanState,
+  touchIndexedAtUnderDir,
+  removeStaleEntries,
+} from "./index";
+
+export type ScanResult = {
+  scanned: number;
+  skipped: number;
+  added: number;
+  moved: number;
+  removed: number;
+  durationMs: number;
+};
+
+const emptyResult = (): ScanResult => ({
+  scanned: 0,
+  skipped: 0,
+  added: 0,
+  moved: 0,
+  removed: 0,
+  durationMs: 0,
+});
+
+export const scanBasePath = async (basePath: string): Promise<ScanResult> => {
+  const start = performance.now();
+  const scanStart = Date.now();
+  const result = emptyResult();
+
+  const queue: string[] = [basePath];
+  const concurrency = Math.max(1, config.indexScanConcurrency);
+
+  const processDir = async (dirPath: string) => {
+    const dirStat = await stat(dirPath).catch(() => null);
+    if (!dirStat || !dirStat.isDirectory()) return;
+
+    const relDir = relative(basePath, dirPath);
+    const scanState = await getScanState(basePath, relDir);
+
+    if (scanState && scanState.mtimeMs === dirStat.mtimeMs) {
+      result.skipped++;
+      await touchIndexedAtUnderDir(basePath, relDir, scanStart);
+      await setScanState(basePath, relDir, dirStat.mtimeMs, scanStart);
+      return;
+    }
+
+    result.scanned++;
+
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = join(dirPath, entry.name);
+      const entryStat = await stat(entryPath).catch(() => null);
+      if (!entryStat) continue;
+
+      const relPath = relative(basePath, entryPath);
+      const outcome = await indexFile(
+        basePath,
+        relPath,
+        {
+          dev: entryStat.dev,
+          ino: entryStat.ino,
+          size: entryStat.size,
+          mtimeMs: entryStat.mtimeMs,
+          isDirectory: entryStat.isDirectory(),
+        },
+        scanStart,
+      );
+
+      if (outcome.action === "added") result.added++;
+      if (outcome.action === "moved") result.moved++;
+
+      if (entry.isDirectory()) {
+        queue.push(entryPath);
+      }
+    }
+
+    await setScanState(basePath, relDir, dirStat.mtimeMs, scanStart);
+  };
+
+  const workers = Array.from({ length: concurrency }, async () => {
+    while (true) {
+      const dir = queue.shift();
+      if (!dir) break;
+      await processDir(dir);
+    }
+  });
+
+  await Promise.all(workers);
+
+  result.removed = await removeStaleEntries(basePath, scanStart);
+  result.durationMs = Math.round(performance.now() - start);
+
+  return result;
+};
+
+export const scanAll = async (): Promise<ScanResult> => {
+  const start = performance.now();
+  const aggregate = emptyResult();
+
+  for (const base of config.allowedPaths) {
+    const baseResult = await validatePath(base, { allowBasePath: true });
+    if (!baseResult.ok) {
+      throw new Error(`invalid base path: ${baseResult.error}`);
+    }
+    const result = await scanBasePath(baseResult.basePath);
+    aggregate.scanned += result.scanned;
+    aggregate.skipped += result.skipped;
+    aggregate.added += result.added;
+    aggregate.moved += result.moved;
+    aggregate.removed += result.removed;
+  }
+
+  aggregate.durationMs = Math.round(performance.now() - start);
+  return aggregate;
+};

package/src/schemas.ts

@@ -21,6 +21,7 @@ export const FileInfoSchema = z
     mtime: z.iso.datetime().describe("Last modification time in ISO 8601 format"),
     isHidden: z.boolean().describe("True if the name starts with a dot"),
     mimeType: z.string().optional().describe("MIME type of the file (only for files)"),
+    fileId: z.string().optional().describe("Stable file identifier (UUID v7)"),
   })
   .describe("Information about a file or directory");
 
@@ -35,24 +36,33 @@ export const DirInfoSchema = FileInfoSchema.extend({
 
 export const PathQuerySchema = z
   .object({
-    path: z.string().min(1).describe("Absolute path to the file or directory"),
+    path: z.string().min(1).optional().describe("Absolute path to the file or directory"),
+    id: z.string().min(1).optional().describe("Stable file identifier (UUID v7)"),
+  })
+  .refine((v) => (v.path ? !v.id : !!v.id), {
+    message: "exactly one of 'path' or 'id' must be provided",
   })
   .describe("Query parameters for path-based operations");
 
 export const ContentQuerySchema = z
   .object({
-    path: z.string().min(1).describe("Absolute path to the file or directory to download"),
+    path: z.string().min(1).optional().describe("Absolute path to the file or directory to download"),
+    id: z.string().min(1).optional().describe("Stable file identifier (UUID v7)"),
     inline: z
       .string()
       .optional()
       .transform((v) => v === "true")
       .describe("If 'true', display in browser instead of downloading (Content-Disposition: inline)"),
   })
+  .refine((v) => (v.path ? !v.id : !!v.id), {
+    message: "exactly one of 'path' or 'id' must be provided",
+  })
   .describe("Query parameters for content download");
 
 export const InfoQuerySchema = z
   .object({
-    path: z.string().min(1).describe("Absolute path to the file or directory"),
+    path: z.string().min(1).optional().describe("Absolute path to the file or directory"),
+    id: z.string().min(1).optional().describe("Stable file identifier (UUID v7)"),
     showHidden: z
       .string()
       .optional()
@@ -64,6 +74,9 @@ export const InfoQuerySchema = z
       .transform((v) => v === "true")
       .describe("If 'true', compute recursive sizes for directories (slower, default: false)"),
   })
+  .refine((v) => (v.path ? !v.id : !!v.id), {
+    message: "exactly one of 'path' or 'id' must be provided",
+  })
   .describe("Query parameters for file/directory info");
 
 export const SearchQuerySchema = z
@@ -188,6 +201,36 @@ export const SearchResponseSchema = z
   })
   .describe("Complete search response with results from all searched paths");
 
+export const RescanResponseSchema = z
+  .object({
+    scanned: z.number().describe("Directories scanned"),
+    skipped: z.number().describe("Directories skipped (mtime unchanged)"),
+    added: z.number().describe("New files indexed"),
+    moved: z.number().describe("Moves detected"),
+    removed: z.number().describe("Stale index entries removed"),
+    durationMs: z.number().describe("Total scan duration in milliseconds"),
+  })
+  .describe("Index rescan result");
+
+export const IndexStatsSchema = z
+  .object({
+    totalFiles: z.number().describe("Number of indexed files"),
+    totalDirs: z.number().describe("Number of indexed directories"),
+    dbSizeBytes: z.number().describe("Database size in bytes (0 if unavailable)"),
+    lastScanAt: z.number().nullable().describe("Last scan timestamp (ms since epoch)"),
+  })
+  .describe("Index statistics");
+
+export const BulkResolveBodySchema = z
+  .object({
+    ids: z.array(z.string().min(1)).describe("List of file IDs to resolve"),
+  })
+  .describe("Bulk resolve request");
+
+export const BulkResolveResponseSchema = z
+  .record(z.string(), z.string().nullable())
+  .describe("Map of file ID to absolute path or null if missing");
+
 export const UploadStartResponseSchema = z
   .object({
     uploadId: z
@@ -278,7 +321,8 @@ export const ThumbnailFormatSchema = z.enum(["webp", "jpeg", "png", "avif"]).des
 
 export const ImageThumbnailQuerySchema = z
   .object({
-    path: z.string().min(1).describe("Absolute path to the image file"),
+    path: z.string().min(1).optional().describe("Absolute path to the image file"),
+    id: z.string().min(1).optional().describe("Stable file identifier (UUID v7)"),
     width: z
       .string()
       .optional()
@@ -313,6 +357,9 @@ export const ImageThumbnailQuerySchema = z
       .refine((v) => v >= 1 && v <= 100, "quality must be between 1 and 100")
       .describe("Output quality 1-100 (default: 80)"),
   })
+  .refine((v) => (v.path ? !v.id : !!v.id), {
+    message: "exactly one of 'path' or 'id' must be provided",
+  })
   .describe("Query parameters for image thumbnail generation");
 
 export type ImageThumbnailQuery = z.infer<typeof ImageThumbnailQuerySchema>;