@valentinkolb/filegate 0.0.1

package/src/handlers/upload.ts

@@ -0,0 +1,332 @@
+import { Hono } from "hono";
+import { describeRoute } from "hono-openapi";
+import { redis } from "bun";
+import { mkdir, readdir, rm, stat, rename } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { validatePath } from "../lib/path";
+import { applyOwnership, type Ownership } from "../lib/ownership";
+import { jsonResponse, requiresAuth } from "../lib/openapi";
+import { v } from "../lib/validator";
+import {
+  UploadStartBodySchema,
+  UploadStartResponseSchema,
+  UploadChunkResponseSchema,
+  ErrorSchema,
+  UploadChunkHeadersSchema,
+} from "../schemas";
+import { config } from "../config";
+
+const app = new Hono();
+
+// Deterministic upload ID from path + filename + checksum
+const computeUploadId = (path: string, filename: string, checksum: string): string => {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(`${path}:${filename}:${checksum}`);
+  return hasher.digest("hex").slice(0, 16);
+};
+
+// Single Redis key per upload
+const metaKey = (id: string) => `filegate:upload:${id}`;
+
+// Chunk storage paths
+const chunksDir = (id: string) => join(config.uploadTempDir, id);
+const chunkPath = (id: string, idx: number) => join(chunksDir(id), String(idx));
+
+type UploadMeta = {
+  uploadId: string;
+  path: string;
+  filename: string;
+  size: number;
+  checksum: string;
+  chunkSize: number;
+  totalChunks: number;
+  ownership: Ownership | null;
+};
+
+const saveMeta = async (meta: UploadMeta): Promise<void> => {
+  await redis.set(metaKey(meta.uploadId), JSON.stringify(meta), "EX", config.uploadExpirySecs);
+};
+
+const loadMeta = async (id: string): Promise<UploadMeta | null> => {
+  const data = await redis.get(metaKey(id));
+  return data ? (JSON.parse(data) as UploadMeta) : null;
+};
+
+const refreshExpiry = async (id: string): Promise<void> => {
+  await redis.expire(metaKey(id), config.uploadExpirySecs);
+};
+
+// Get uploaded chunks from filesystem instead of Redis
+const getUploadedChunks = async (id: string): Promise<number[]> => {
+  try {
+    const files = await readdir(chunksDir(id));
+    return files
+      .map((f) => parseInt(f, 10))
+      .filter((n) => !isNaN(n))
+      .sort((a, b) => a - b);
+  } catch {
+    return [];
+  }
+};
+
+const cleanupUpload = async (id: string): Promise<void> => {
+  await Promise.all([redis.del(metaKey(id)), rm(chunksDir(id), { recursive: true }).catch(() => {})]);
+};
+
+const assembleFile = async (meta: UploadMeta): Promise<string | null> => {
+  const chunks = await getUploadedChunks(meta.uploadId);
+  if (chunks.length !== meta.totalChunks) return "missing chunks";
+
+  const fullPath = join(meta.path, meta.filename);
+  const pathResult = await validatePath(fullPath);
+  if (!pathResult.ok) return pathResult.error;
+
+  await mkdir(dirname(pathResult.realPath), { recursive: true });
+
+  const hasher = new Bun.CryptoHasher("sha256");
+  const file = Bun.file(pathResult.realPath);
+  const writer = file.writer();
+
+  try {
+    for (let i = 0; i < meta.totalChunks; i++) {
+      // Stream each chunk instead of loading entirely into memory
+      const chunkFile = Bun.file(chunkPath(meta.uploadId, i));
+      for await (const data of chunkFile.stream()) {
+        hasher.update(data);
+        writer.write(data);
+      }
+    }
+    await writer.end();
+  } catch (e) {
+    writer.end();
+    await rm(pathResult.realPath).catch(() => {});
+    throw e;
+  }
+
+  const finalChecksum = `sha256:${hasher.digest("hex")}`;
+  if (finalChecksum !== meta.checksum) {
+    await rm(pathResult.realPath).catch(() => {});
+    return `checksum mismatch: expected ${meta.checksum}, got ${finalChecksum}`;
+  }
+
+  const ownershipError = await applyOwnership(pathResult.realPath, meta.ownership);
+  if (ownershipError) {
+    await rm(pathResult.realPath).catch(() => {});
+    return ownershipError;
+  }
+
+  await cleanupUpload(meta.uploadId);
+  return null;
+};
+
+// POST /upload/start
+app.post(
+  "/start",
+  describeRoute({
+    tags: ["Upload"],
+    summary: "Start or resume chunked upload",
+    description: "Initialize a new upload or get status of existing upload with same checksum",
+    ...requiresAuth,
+    responses: {
+      200: jsonResponse(UploadStartResponseSchema, "Upload initialized or resumed"),
+      400: jsonResponse(ErrorSchema, "Bad request"),
+      403: jsonResponse(ErrorSchema, "Forbidden"),
+    },
+  }),
+  v("json", UploadStartBodySchema),
+  async (c) => {
+    const body = c.req.valid("json");
+
+    // Validate size limits
+    if (body.size > config.maxUploadBytes) {
+      return c.json({ error: `file size exceeds maximum (${config.maxUploadBytes / 1024 / 1024}MB)` }, 413);
+    }
+    if (body.chunkSize > config.maxChunkBytes) {
+      return c.json({ error: `chunk size exceeds maximum (${config.maxChunkBytes / 1024 / 1024}MB)` }, 400);
+    }
+
+    const fullPath = join(body.path, body.filename);
+    const pathResult = await validatePath(fullPath);
+    if (!pathResult.ok) return c.json({ error: pathResult.error }, pathResult.status);
+
+    // Deterministic upload ID - same file/path/checksum = same ID (enables resume)
+    const uploadId = computeUploadId(body.path, body.filename, body.checksum);
+
+    // Check for existing upload (resume)
+    const existingMeta = await loadMeta(uploadId);
+    if (existingMeta) {
+      // Refresh TTL on resume
+      await refreshExpiry(uploadId);
+      // Get chunks from filesystem
+      const uploadedChunks = await getUploadedChunks(uploadId);
+      return c.json({
+        uploadId,
+        totalChunks: existingMeta.totalChunks,
+        chunkSize: existingMeta.chunkSize,
+        uploadedChunks,
+        completed: false as const,
+      });
+    }
+
+    // New upload
+    const chunkSize = body.chunkSize;
+    const totalChunks = Math.ceil(body.size / chunkSize);
+
+    const ownership: Ownership | null =
+      body.ownerUid != null && body.ownerGid != null && body.mode
+        ? { uid: body.ownerUid, gid: body.ownerGid, mode: parseInt(body.mode, 8) }
+        : null;
+
+    const meta: UploadMeta = {
+      uploadId,
+      path: body.path,
+      filename: body.filename,
+      size: body.size,
+      checksum: body.checksum,
+      chunkSize,
+      totalChunks,
+      ownership,
+    };
+
+    await mkdir(chunksDir(uploadId), { recursive: true });
+    await saveMeta(meta);
+
+    return c.json({
+      uploadId,
+      totalChunks,
+      chunkSize,
+      uploadedChunks: [],
+      completed: false as const,
+    });
+  },
+);
+
+// POST /upload/chunk
+app.post(
+  "/chunk",
+  describeRoute({
+    tags: ["Upload"],
+    summary: "Upload a chunk",
+    description: "Upload a single chunk. Auto-completes when all chunks received.",
+    ...requiresAuth,
+    responses: {
+      200: jsonResponse(UploadChunkResponseSchema, "Chunk received"),
+      400: jsonResponse(ErrorSchema, "Bad request"),
+      404: jsonResponse(ErrorSchema, "Upload not found"),
+    },
+  }),
+  v("header", UploadChunkHeadersSchema),
+  async (c) => {
+    const headers = c.req.valid("header");
+    const uploadId = headers["x-upload-id"];
+    const chunkIndex = headers["x-chunk-index"];
+    const chunkChecksum = headers["x-chunk-checksum"];
+
+    const meta = await loadMeta(uploadId);
+    if (!meta) return c.json({ error: "upload not found" }, 404);
+
+    if (chunkIndex >= meta.totalChunks) {
+      return c.json({ error: `chunk index ${chunkIndex} exceeds total ${meta.totalChunks}` }, 400);
+    }
+
+    const body = c.req.raw.body;
+    if (!body) return c.json({ error: "missing body" }, 400);
+
+    // Stream chunks to a temporary file to avoid memory accumulation
+    const tempChunkPath = chunkPath(uploadId, chunkIndex) + ".tmp";
+    let chunkSize = 0;
+    const hasher = new Bun.CryptoHasher("sha256");
+
+    await mkdir(chunksDir(uploadId), { recursive: true });
+    const tempFile = Bun.file(tempChunkPath);
+    const writer = tempFile.writer();
+
+    try {
+      for await (const chunk of body) {
+        chunkSize += chunk.length;
+        if (chunkSize > config.maxChunkBytes) {
+          writer.end();
+          await rm(tempChunkPath).catch(() => {});
+          return c.json({ error: `chunk size exceeds maximum (${config.maxChunkBytes / 1024 / 1024}MB)` }, 413);
+        }
+        hasher.update(chunk);
+        writer.write(chunk);
+      }
+      await writer.end();
+    } catch (e) {
+      writer.end();
+      await rm(tempChunkPath).catch(() => {});
+      throw e;
+    }
+
+    // Verify checksum if provided
+    if (chunkChecksum) {
+      const computed = `sha256:${hasher.digest("hex")}`;
+      if (computed !== chunkChecksum) {
+        await rm(tempChunkPath).catch(() => {});
+        return c.json({ error: `chunk checksum mismatch: expected ${chunkChecksum}, got ${computed}` }, 400);
+      }
+    }
+
+    // Move temp file to final location (atomic rename, no memory copy)
+    const finalChunkPath = chunkPath(uploadId, chunkIndex);
+    await rename(tempChunkPath, finalChunkPath);
+
+    // Get uploaded chunks from filesystem
+    const uploadedChunks = await getUploadedChunks(uploadId);
+
+    if (uploadedChunks.length === meta.totalChunks) {
+      const assembleError = await assembleFile(meta);
+      if (assembleError) return c.json({ error: assembleError }, 500);
+
+      const fullPath = join(meta.path, meta.filename);
+      const file = Bun.file(fullPath);
+      const s = await stat(fullPath);
+
+      return c.json({
+        completed: true as const,
+        file: {
+          name: meta.filename,
+          path: fullPath,
+          type: "file" as const,
+          size: s.size,
+          mtime: s.mtime.toISOString(),
+          isHidden: meta.filename.startsWith("."),
+          checksum: meta.checksum,
+          mimeType: file.type,
+        },
+      });
+    }
+
+    return c.json({
+      chunkIndex,
+      uploadedChunks,
+      completed: false as const,
+    });
+  },
+);
+
+// Cleanup orphaned chunk directories (Redis keys expired but files remain)
+export const cleanupOrphanedChunks = async () => {
+  try {
+    const dirs = await readdir(config.uploadTempDir);
+    let cleaned = 0;
+
+    for (const dir of dirs) {
+      // Check if upload still exists in Redis
+      const exists = await redis.exists(metaKey(dir));
+      if (!exists) {
+        await rm(chunksDir(dir), { recursive: true }).catch(() => {});
+        cleaned++;
+      }
+    }
+
+    if (cleaned > 0) {
+      console.log(`[Filegate] Cleaned up ${cleaned} orphaned chunk director${cleaned === 1 ? "y" : "ies"}`);
+    }
+  } catch {
+    // Directory doesn't exist yet
+  }
+};
+
+export default app;

package/src/index.ts

@@ -0,0 +1,83 @@
+import { Hono } from "hono";
+import { Scalar } from "@scalar/hono-api-reference";
+import { generateSpecs } from "hono-openapi";
+import { createMarkdownFromOpenApi } from "@scalar/openapi-to-markdown";
+import { bearerAuth } from "hono/bearer-auth";
+import { secureHeaders } from "hono/secure-headers";
+import { config } from "./config";
+import { openApiMeta } from "./lib/openapi";
+import filesRoutes from "./handlers/files";
+import searchRoutes from "./handlers/search";
+import uploadRoutes, { cleanupOrphanedChunks } from "./handlers/upload";
+
+// Dev mode warning
+if (config.isDev) {
+  console.log("╔════════════════════════════════════════════════════════════════╗");
+  console.log("║  WARNING: DEV MODE - UID/GID OVERRIDES ENABLED                 ║");
+  console.log("║  DO NOT USE IN PRODUCTION!                                     ║");
+  console.log(`║  DEV_UID_OVERRIDE: ${String(config.devUid ?? "not set").padEnd(43)}║`);
+  console.log(`║  DEV_GID_OVERRIDE: ${String(config.devGid ?? "not set").padEnd(43)}║`);
+  console.log("╚════════════════════════════════════════════════════════════════╝");
+}
+
+console.log(`[Filegate] ALLOWED_BASE_PATHS: ${config.allowedPaths.join(", ")}`);
+console.log(`[Filegate] MAX_UPLOAD_MB: ${config.maxUploadBytes / 1024 / 1024}`);
+console.log(`[Filegate] REDIS_URL: ${process.env.REDIS_URL ?? "redis://localhost:6379 (default)"}`);
+console.log(`[Filegate] PORT: ${config.port}`);
+
+// Periodic disk cleanup for orphaned chunks (every 6h by default)
+setInterval(cleanupOrphanedChunks, config.diskCleanupIntervalMs);
+setTimeout(cleanupOrphanedChunks, 10_000); // Run 10s after startup
+
+// Main app
+const app = new Hono();
+
+// Security headers
+app.use(
+  "*",
+  secureHeaders({
+    xFrameOptions: "DENY",
+    xContentTypeOptions: "nosniff",
+    referrerPolicy: "strict-origin-when-cross-origin",
+    crossOriginOpenerPolicy: "same-origin",
+    crossOriginResourcePolicy: "same-origin",
+  }),
+);
+
+// Health check (public)
+app.get("/health", (c) => c.text("OK"));
+
+// Protected routes
+const api = new Hono()
+  .use("/*", bearerAuth({ token: config.token }))
+  .route("/", filesRoutes)
+  .route("/", searchRoutes)
+  .route("/upload", uploadRoutes);
+
+app.route("/files", api);
+
+// Generate OpenAPI spec
+const spec = await generateSpecs(app, openApiMeta);
+const llmsTxt = await createMarkdownFromOpenApi(JSON.stringify(spec));
+
+// Documentation endpoints (public)
+app.get("/openapi.json", (c) => c.json(spec));
+app.get("/docs", Scalar({ theme: "saturn", url: "/openapi.json" }));
+app.get("/llms.txt", (c) => c.text(llmsTxt));
+
+// 404 fallback
+app.notFound((c) => c.json({ error: "not found" }, 404));
+
+// Error handler
+app.onError((err, c) => {
+  console.error("[Filegate] Error:", err);
+  return c.json({ error: "internal error" }, 500);
+});
+
+export default {
+  port: config.port,
+  fetch: app.fetch,
+};
+
+console.log(`[Filegate] Listening on http://localhost:${config.port}`);
+console.log(`[Filegate] Docs: http://localhost:${config.port}/docs`);

package/src/lib/openapi.ts

@@ -0,0 +1,47 @@
+import { resolver, type GenerateSpecOptions } from "hono-openapi";
+import type { ZodType } from "zod";
+import { config } from "../config";
+
+/** JSON response helper for OpenAPI docs */
+export const jsonResponse = <T extends ZodType>(schema: T, description: string) => ({
+  description,
+  content: { "application/json": { schema: resolver(schema) } },
+});
+
+/** Binary/stream response helper */
+export const binaryResponse = (mimeType: string, description: string) => ({
+  description,
+  content: { [mimeType]: { schema: { type: "string" as const, format: "binary" } } },
+});
+
+/** OpenAPI spec metadata */
+export const openApiMeta: Partial<GenerateSpecOptions> = {
+  documentation: {
+    info: {
+      title: "File Proxy API",
+      version: "1.0.0",
+      description: "Secure file proxy with streaming uploads/downloads and resumable chunked uploads",
+    },
+    servers: [{ url: `http://localhost:${config.port}`, description: "File Proxy Server" }],
+    tags: [
+      { name: "Health", description: "Health check endpoint" },
+      { 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" },
+    ],
+    components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: "http",
+          scheme: "bearer",
+          description: "Bearer token authentication",
+        },
+      },
+    },
+  },
+};
+
+/** Security requirement for authenticated routes */
+export const requiresAuth = {
+  security: [{ bearerAuth: [] as string[] }],
+};

package/src/lib/ownership.ts

@@ -0,0 +1,64 @@
+import { chown, chmod } from "node:fs/promises";
+import { config } from "../config";
+
+export type Ownership = {
+  uid: number;
+  gid: number;
+  mode: number; // octal, e.g. 0o600
+};
+
+export const parseOwnershipHeaders = (req: Request): Ownership | null => {
+  const uid = req.headers.get("X-Owner-UID");
+  const gid = req.headers.get("X-Owner-GID");
+  const mode = req.headers.get("X-File-Mode");
+
+  if (!uid || !gid || !mode) return null;
+
+  const parsedMode = parseInt(mode, 8);
+  if (isNaN(parsedMode)) return null;
+
+  return {
+    uid: parseInt(uid, 10),
+    gid: parseInt(gid, 10),
+    mode: parsedMode,
+  };
+};
+
+export const parseOwnershipBody = (body: {
+  ownerUid?: number;
+  ownerGid?: number;
+  mode?: string;
+}): Ownership | null => {
+  if (body.ownerUid == null || body.ownerGid == null || !body.mode) return null;
+
+  const mode = parseInt(body.mode, 8);
+  if (isNaN(mode)) return null;
+
+  return { uid: body.ownerUid, gid: body.ownerGid, mode };
+};
+
+export const applyOwnership = async (
+  path: string,
+  ownership: Ownership | null
+): Promise<string | null> => {
+  if (!ownership) return null;
+
+  const uid = config.devUid ?? ownership.uid;
+  const gid = config.devGid ?? ownership.gid;
+
+  if (config.isDev) {
+    console.log(
+      `[DEV] chown ${path}: ${ownership.uid}->${uid}, ${ownership.gid}->${gid}, mode=${ownership.mode.toString(8)}`
+    );
+  }
+
+  try {
+    await chown(path, uid, gid);
+    await chmod(path, ownership.mode);
+    return null;
+  } catch (e: any) {
+    if (e.code === "EPERM") return "permission denied (not root?)";
+    if (e.code === "EINVAL") return `invalid uid=${uid} or gid=${gid}`;
+    return `ownership failed: ${e.message}`;
+  }
+};

package/src/lib/path.ts

@@ -0,0 +1,103 @@
+import { realpath } from "node:fs/promises";
+import { join, normalize, dirname, basename } from "node:path";
+import { config } from "../config";
+
+export type PathResult =
+  | { ok: true; realPath: string; basePath: string }
+  | { ok: false; error: string; status: 400 | 403 | 404 };
+
+// Cache for resolved base paths (they don't change at runtime)
+const realBaseCache = new Map<string, string>();
+
+const getRealBase = async (basePath: string): Promise<string | null> => {
+  const cached = realBaseCache.get(basePath);
+  if (cached) return cached;
+
+  try {
+    const realBase = await realpath(basePath);
+    realBaseCache.set(basePath, realBase);
+    return realBase;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Validates path is within allowed base paths, resolves symlinks.
+ * @param allowBasePath - if true, allows operating on the base path itself
+ */
+export const validatePath = async (path: string, allowBasePath = false): Promise<PathResult> => {
+  const cleaned = normalize(path);
+
+  // Find matching base
+  let basePath: string | null = null;
+  for (const base of config.allowedPaths) {
+    const cleanBase = normalize(base);
+    if (cleaned === cleanBase) {
+      if (!allowBasePath) {
+        return { ok: false, error: "cannot operate on base path", status: 403 };
+      }
+      basePath = cleanBase;
+      break;
+    }
+    if (cleaned.startsWith(cleanBase + "/")) {
+      basePath = cleanBase;
+      break;
+    }
+  }
+
+  if (!basePath) {
+    return { ok: false, error: "path not allowed", status: 403 };
+  }
+
+  // Resolve symlinks
+  let realPath: string;
+  try {
+    realPath = await realpath(cleaned);
+  } catch (e: any) {
+    if (e.code === "ENOENT") {
+      // Path doesn't exist yet - validate parent
+      try {
+        const parentReal = await realpath(dirname(cleaned));
+        realPath = join(parentReal, basename(cleaned));
+      } catch {
+        return { ok: false, error: "parent path not found", status: 404 };
+      }
+    } else {
+      return { ok: false, error: "path resolution failed", status: 400 };
+    }
+  }
+
+  // Verify still within base after symlink resolution (cached)
+  const realBase = await getRealBase(basePath);
+  if (!realBase) {
+    return { ok: false, error: "base path invalid", status: 500 as any };
+  }
+
+  if (realPath !== realBase && !realPath.startsWith(realBase + "/")) {
+    return { ok: false, error: "symlink escape not allowed", status: 403 };
+  }
+
+  return { ok: true, realPath, basePath: realBase };
+};
+
+export type SameBaseResult =
+  | { ok: true; realPath: string; basePath: string; realTo: string }
+  | { ok: false; error: string; status: 400 | 403 | 404 };
+
+/**
+ * Validates both paths are in the same base (for move/copy).
+ */
+export const validateSameBase = async (from: string, to: string): Promise<SameBaseResult> => {
+  const fromResult = await validatePath(from);
+  if (!fromResult.ok) return fromResult;
+
+  const toResult = await validatePath(to);
+  if (!toResult.ok) return toResult;
+
+  if (fromResult.basePath !== toResult.basePath) {
+    return { ok: false, error: "cross-basepath not allowed", status: 400 };
+  }
+
+  return { ...fromResult, realTo: toResult.realPath };
+};

package/src/lib/response.ts

@@ -0,0 +1,10 @@
+export const json = <T>(data: T, status = 200) =>
+  Response.json(data, { status });
+
+export const error = (msg: string, status = 400) =>
+  Response.json({ error: msg }, { status });
+
+export const notFound = (msg = "not found") => error(msg, 404);
+export const forbidden = (msg = "forbidden") => error(msg, 403);
+export const badRequest = (msg: string) => error(msg, 400);
+export const serverError = (msg = "internal error") => error(msg, 500);

package/src/lib/validator.ts

@@ -0,0 +1,21 @@
+import { validator } from "hono-openapi";
+import type { ZodType } from "zod";
+import type { ValidationTargets, Context } from "hono";
+
+/**
+ * Zod validator middleware with OpenAPI support.
+ * Returns 400 with error details on validation failure.
+ */
+export const v = <Target extends keyof ValidationTargets, T extends ZodType>(target: Target, schema: T) =>
+  validator(target, schema, (result, c: Context) => {
+    if (!result.success) {
+      const issues = result.error as readonly { message: string; path?: readonly unknown[] }[];
+      const msg = issues
+        ?.map((issue) => {
+          const path = issue.path?.map((p) => String(p)).join(".");
+          return path ? `${path}: ${issue.message}` : issue.message;
+        })
+        .join(", ");
+      return c.json({ error: msg || "validation failed" }, 400);
+    }
+  });