@valentinkolb/filegate 1.1.1 → 2.0.0

package/README.md

@@ -144,6 +144,42 @@ Filegate does not validate whether the specified uid/gid exists on the system, n
 
 This feature is intended for scenarios like NFS shares exposed through Filegate, where preserving the original permission structure is required.
 
+### Transfer (Move/Copy)
+
+The `transfer` endpoint handles both moving and copying files or directories:
+
+```typescript
+// Move (rename) a file - same base path only
+await client.transfer({
+  from: "/data/old-name.txt",
+  to: "/data/new-name.txt",
+  mode: "move",
+});
+
+// Copy within same base path - no ownership required
+await client.transfer({
+  from: "/data/file.txt",
+  to: "/data/backup/file.txt",
+  mode: "copy",
+});
+
+// Copy across different base paths - ownership required
+await client.transfer({
+  from: "/data/file.txt",
+  to: "/backup/file.txt",
+  mode: "copy",
+  uid: 1000,
+  gid: 1000,
+  fileMode: "644",
+});
+```
+
+**Rules:**
+- `mode: "move"` - Only within the same base path (uses filesystem rename)
+- `mode: "copy"` without ownership - Only within the same base path
+- `mode: "copy"` with ownership - Allows cross-base copying (ownership is applied recursively)
+- Both operations work recursively on directories
+
 ### Chunked Uploads
 
 For large files, use chunked uploads. They support:
@@ -294,11 +330,23 @@ await client.mkdir({ path: "/data/new-folder", mode: "755" });
 // Delete file or directory
 await client.delete({ path: "/data/old-file.txt" });
 
-// Move (within same base path)
-await client.move({ from: "/data/old.txt", to: "/data/new.txt" });
+// Transfer: Move or copy files/directories
+await client.transfer({
+  from: "/data/old.txt",
+  to: "/data/new.txt",
+  mode: "move",  // or "copy"
+});
 
-// Copy (within same base path)
-await client.copy({ from: "/data/file.txt", to: "/data/backup.txt" });
+// Transfer with ownership (required for cross-base copy)
+await client.transfer({
+  from: "/data/file.txt",
+  to: "/backup/file.txt",
+  mode: "copy",
+  uid: 1000,
+  gid: 1000,
+  fileMode: "644",
+  dirMode: "755",
+});
 
 // Search files with glob patterns
 await client.glob({
@@ -396,8 +444,7 @@ All `/files/*` endpoints require `Authorization: Bearer <token>`.
 | PUT | `/files/content` | Upload file |
 | POST | `/files/mkdir` | Create directory |
 | DELETE | `/files/delete` | Delete file or directory |
-| POST | `/files/move` | Move file or directory |
-| POST | `/files/copy` | Copy file or directory |
+| POST | `/files/transfer` | Move or copy file/directory. Cross-base copy requires ownership |
 | GET | `/files/search` | Search with glob pattern. Use `?directories=true` to include folders |
 | POST | `/files/upload/start` | Start or resume chunked upload |
 | POST | `/files/upload/chunk` | Upload a chunk |

package/package.json

@@ -1,8 +1,6 @@
 {
   "name": "@valentinkolb/filegate",
-  "version": "1.1.1",
-  "description": "Secure file proxy for building custom file management systems. Streaming uploads, chunked transfers, Unix permissions.",
-  "module": "index.ts",
+  "version": "2.0.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -27,10 +25,7 @@
     "test:watch": "bun test --preload ./tests/setup.ts --watch",
     "test:unit": "bun test --preload ./tests/setup.ts tests/lib tests/schemas.test.ts tests/config.test.ts tests/utils.test.ts",
     "test:integration": "bun test tests/integration",
-    "test:integration:up": "docker compose -f compose.test.yml up -d --build --wait",
-    "test:integration:down": "docker compose -f compose.test.yml down -v",
-    "test:integration:run": "bun run test:integration:up && bun run test:integration && bun run test:integration:down",
-    "test:all": "bun run test:unit && bun run test:integration:run"
+    "test:all": "bun run test:unit && bun run test:integration"
   },
   "exports": {
     ".": "./src/index.ts",

package/src/client.ts

@@ -89,16 +89,19 @@ export interface DeleteOptions {
   path: string;
 }
 
-// --- Move ---
-export interface MoveOptions {
-  from: string;
-  to: string;
-}
-
-// --- Copy ---
-export interface CopyOptions {
+// --- Transfer (Move/Copy) ---
+export interface TransferOptions {
   from: string;
   to: string;
+  mode: "move" | "copy";
+  /** Owner UID - required for cross-base copy */
+  uid?: number;
+  /** Owner GID - required for cross-base copy */
+  gid?: number;
+  /** File mode (e.g. "644") - required for cross-base copy */
+  fileMode?: string;
+  /** Directory mode (e.g. "755") - if not set, derived from fileMode */
+  dirMode?: string;
 }
 
 // --- Glob (Search) ---
@@ -293,23 +296,24 @@ export class Filegate {
   }
 
   // ==========================================================================
-  // Move & Copy
+  // Transfer (Move/Copy)
   // ==========================================================================
 
-  async move(opts: MoveOptions): Promise<FileProxyResponse<FileInfo>> {
-    const res = await this._fetch(`${this.url}/files/move`, {
-      method: "POST",
-      headers: this.jsonHdrs(),
-      body: JSON.stringify({ from: opts.from, to: opts.to }),
-    });
-    return this.handleResponse(res);
-  }
+  async transfer(opts: TransferOptions): Promise<FileProxyResponse<FileInfo>> {
+    const body: Record<string, unknown> = {
+      from: opts.from,
+      to: opts.to,
+      mode: opts.mode,
+    };
+    if (opts.uid !== undefined) body.ownerUid = opts.uid;
+    if (opts.gid !== undefined) body.ownerGid = opts.gid;
+    if (opts.fileMode) body.fileMode = opts.fileMode;
+    if (opts.dirMode) body.dirMode = opts.dirMode;
 
-  async copy(opts: CopyOptions): Promise<FileProxyResponse<FileInfo>> {
-    const res = await this._fetch(`${this.url}/files/copy`, {
+    const res = await this._fetch(`${this.url}/files/transfer`, {
       method: "POST",
       headers: this.jsonHdrs(),
-      body: JSON.stringify({ from: opts.from, to: opts.to }),
+      body: JSON.stringify(body),
     });
     return this.handleResponse(res);
   }

package/src/handlers/files.ts

@@ -4,7 +4,7 @@ import { readdir, mkdir, rm, rename, cp, stat } from "node:fs/promises";
 import { join, basename, relative } from "node:path";
 import sanitizeFilename from "sanitize-filename";
 import { validatePath, validateSameBase } from "../lib/path";
-import { parseOwnershipBody, applyOwnership } from "../lib/ownership";
+import { parseOwnershipBody, applyOwnership, applyOwnershipRecursive } from "../lib/ownership";
 import { jsonResponse, binaryResponse, requiresAuth } from "../lib/openapi";
 import { v } from "../lib/validator";
 import {
@@ -15,8 +15,7 @@ import {
   PathQuerySchema,
   ContentQuerySchema,
   MkdirBodySchema,
-  MoveBodySchema,
-  CopyBodySchema,
+  TransferBodySchema,
   UploadFileHeadersSchema,
   type FileInfo,
 } from "../schemas";
@@ -47,19 +46,20 @@ const getDirSize = async (dirPath: string): Promise<number> => {
   }
 };
 
-const getFileInfo = async (path: string, relativeTo?: string): Promise<FileInfo> => {
+const getFileInfo = async (path: string, relativeTo?: string, computeDirSize?: boolean): Promise<FileInfo> => {
   const file = Bun.file(path);
   const s = await stat(path);
   const name = basename(path);
+  const isDir = s.isDirectory();
 
   return {
     name,
     path: relativeTo ? relative(relativeTo, path) : path,
-    type: s.isDirectory() ? "directory" : "file",
-    size: s.isDirectory() ? 0 : s.size,
+    type: isDir ? "directory" : "file",
+    size: isDir ? (computeDirSize ? await getDirSize(path) : 0) : s.size,
     mtime: s.mtime.toISOString(),
     isHidden: name.startsWith("."),
-    mimeType: s.isDirectory() ? undefined : file.type,
+    mimeType: isDir ? undefined : file.type,
   };
 };
 
@@ -102,7 +102,7 @@ app.get(
       await Promise.all(
         entries
           .filter((e) => showHidden || !e.name.startsWith("."))
-          .map((e) => getFileInfo(join(result.realPath, e.name), result.realPath).catch(() => null)),
+          .map((e) => getFileInfo(join(result.realPath, e.name), result.realPath, true).catch(() => null)),
       )
     ).filter((item): item is FileInfo => item !== null);
 
@@ -357,73 +357,118 @@ app.delete(
   },
 );
 
-// POST /move
+// POST /transfer
 app.post(
-  "/move",
+  "/transfer",
   describeRoute({
     tags: ["Files"],
-    summary: "Move file or directory",
-    description: "Move within same base path only",
+    summary: "Move or copy file/directory",
+    description:
+      "Transfer files between locations. Mode 'move' requires same base path. " +
+      "Mode 'copy' allows cross-base transfer when ownership (ownerUid, ownerGid, fileMode) is provided.",
     ...requiresAuth,
     responses: {
-      200: jsonResponse(FileInfoSchema, "Moved"),
+      200: jsonResponse(FileInfoSchema, "Transferred"),
       400: jsonResponse(ErrorSchema, "Bad request"),
       403: jsonResponse(ErrorSchema, "Forbidden"),
       404: jsonResponse(ErrorSchema, "Not found"),
     },
   }),
-  v("json", MoveBodySchema),
+  v("json", TransferBodySchema),
   async (c) => {
-    const { from, to } = c.req.valid("json");
+    const { from, to, mode, ownerUid, ownerGid, fileMode, dirMode } = c.req.valid("json");
 
-    const result = await validateSameBase(from, to);
-    if (!result.ok) return c.json({ error: result.error }, result.status);
+    // Build ownership if provided
+    const ownership =
+      ownerUid != null && ownerGid != null && fileMode != null
+        ? {
+            uid: ownerUid,
+            gid: ownerGid,
+            mode: parseInt(fileMode, 8),
+            dirMode: dirMode ? parseInt(dirMode, 8) : undefined,
+          }
+        : null;
 
-    try {
-      await stat(result.realPath);
-    } catch {
-      return c.json({ error: "source not found" }, 404);
+    // Move always requires same base
+    if (mode === "move") {
+      const result = await validateSameBase(from, to);
+      if (!result.ok) return c.json({ error: result.error }, result.status);
+
+      try {
+        await stat(result.realPath);
+      } catch {
+        return c.json({ error: "source not found" }, 404);
+      }
+
+      await mkdir(join(result.realTo, ".."), { recursive: true });
+      await rename(result.realPath, result.realTo);
+
+      // Apply ownership if provided (for move within same base)
+      if (ownership) {
+        const ownershipError = await applyOwnershipRecursive(result.realTo, ownership);
+        if (ownershipError) {
+          return c.json({ error: ownershipError }, 500);
+        }
+      }
+
+      return c.json(await getFileInfo(result.realTo));
     }
 
-    await mkdir(join(result.realTo, ".."), { recursive: true });
-    await rename(result.realPath, result.realTo);
+    // Copy: check if same base or cross-base with ownership
+    const sameBaseResult = await validateSameBase(from, to);
 
-    return c.json(await getFileInfo(result.realTo));
-  },
-);
+    if (sameBaseResult.ok) {
+      // Same base - no ownership required
+      try {
+        await stat(sameBaseResult.realPath);
+      } catch {
+        return c.json({ error: "source not found" }, 404);
+      }
 
-// POST /copy
-app.post(
-  "/copy",
-  describeRoute({
-    tags: ["Files"],
-    summary: "Copy file or directory",
-    description: "Copy within same base path only",
-    ...requiresAuth,
-    responses: {
-      200: jsonResponse(FileInfoSchema, "Copied"),
-      400: jsonResponse(ErrorSchema, "Bad request"),
-      403: jsonResponse(ErrorSchema, "Forbidden"),
-      404: jsonResponse(ErrorSchema, "Not found"),
-    },
-  }),
-  v("json", CopyBodySchema),
-  async (c) => {
-    const { from, to } = c.req.valid("json");
+      await mkdir(join(sameBaseResult.realTo, ".."), { recursive: true });
+      await cp(sameBaseResult.realPath, sameBaseResult.realTo, { recursive: true });
 
-    const result = await validateSameBase(from, to);
-    if (!result.ok) return c.json({ error: result.error }, result.status);
+      // Apply ownership if provided
+      if (ownership) {
+        const ownershipError = await applyOwnershipRecursive(sameBaseResult.realTo, ownership);
+        if (ownershipError) {
+          await rm(sameBaseResult.realTo, { recursive: true }).catch(() => {});
+          return c.json({ error: ownershipError }, 500);
+        }
+      }
+
+      return c.json(await getFileInfo(sameBaseResult.realTo));
+    }
+
+    // Cross-base copy - ownership is required
+    if (!ownership) {
+      return c.json({ error: "cross-base copy requires ownership (ownerUid, ownerGid, fileMode)" }, 400);
+    }
+
+    // Validate source and destination separately
+    const fromResult = await validatePath(from);
+    if (!fromResult.ok) return c.json({ error: fromResult.error }, fromResult.status);
+
+    const toResult = await validatePath(to, { createParents: true, ownership });
+    if (!toResult.ok) return c.json({ error: toResult.error }, toResult.status);
 
     try {
-      await stat(result.realPath);
+      await stat(fromResult.realPath);
     } catch {
       return c.json({ error: "source not found" }, 404);
     }
 
-    await mkdir(join(result.realTo, ".."), { recursive: true });
-    await cp(result.realPath, result.realTo, { recursive: true });
+    await mkdir(join(toResult.realPath, ".."), { recursive: true });
+    await cp(fromResult.realPath, toResult.realPath, { recursive: true });
+
+    // Apply ownership recursively to copied content
+    const ownershipError = await applyOwnershipRecursive(toResult.realPath, ownership);
+    if (ownershipError) {
+      await rm(toResult.realPath, { recursive: true }).catch(() => {});
+      return c.json({ error: ownershipError }, 500);
+    }
 
-    return c.json(await getFileInfo(result.realTo));
+    return c.json(await getFileInfo(toResult.realPath));
   },
 );
 

package/src/lib/ownership.ts

@@ -1,4 +1,5 @@
-import { chown, chmod } from "node:fs/promises";
+import { chown, chmod, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
 import { dirname } from "node:path";
 import { config } from "../config";
 
@@ -101,3 +102,32 @@ export const applyOwnershipToNewDirs = async (
     current = dirname(current);
   }
 };
+
+// Apply ownership recursively to a file or directory (and all its contents)
+export const applyOwnershipRecursive = async (path: string, ownership: Ownership | null): Promise<string | null> => {
+  if (!ownership) return null;
+
+  const s = await stat(path);
+
+  if (s.isDirectory()) {
+    // Apply directory mode to the directory itself
+    const dirMode = getEffectiveDirMode(ownership);
+    const dirOwnership: Ownership = { ...ownership, mode: dirMode };
+    const err = await applyOwnership(path, dirOwnership);
+    if (err) return err;
+
+    // Recursively apply to contents
+    const entries = await readdir(path, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(path, entry.name);
+      const err = await applyOwnershipRecursive(fullPath, ownership);
+      if (err) return err;
+    }
+  } else {
+    // Apply file mode to files
+    const err = await applyOwnership(path, ownership);
+    if (err) return err;
+  }
+
+  return null;
+};

package/src/schemas.ts

@@ -89,14 +89,22 @@ export const MkdirBodySchema = z.object({
     .optional(),
 });
 
-export const MoveBodySchema = z.object({
-  from: z.string().min(1),
-  to: z.string().min(1),
-});
+export const TransferModeSchema = z.enum(["move", "copy"]);
 
-export const CopyBodySchema = z.object({
+export const TransferBodySchema = z.object({
   from: z.string().min(1),
   to: z.string().min(1),
+  mode: TransferModeSchema,
+  ownerUid: z.number().int().optional(),
+  ownerGid: z.number().int().optional(),
+  fileMode: z
+    .string()
+    .regex(/^[0-7]{3,4}$/)
+    .optional(),
+  dirMode: z
+    .string()
+    .regex(/^[0-7]{3,4}$/)
+    .optional(),
 });
 
 export const UploadStartBodySchema = z.object({