@valentinkolb/filegate 1.1.0 → 2.0.0

package/README.md

@@ -108,6 +108,21 @@ With this configuration:
 
 Symlinks that point outside base paths are also blocked.
 
+### Auto-Create Parent Directories
+
+When uploading files, Filegate automatically creates any missing parent directories. This simplifies folder uploads where nested structures need to be created on-the-fly:
+
+```typescript
+// Parent directories /data/new/nested/path will be created automatically
+await client.upload.single({
+  path: "/data/new/nested/path",
+  filename: "file.txt",
+  data: buffer,
+});
+```
+
+This applies to both simple uploads and chunked uploads.
+
 ### File Ownership
 
 Filegate can set Unix file ownership on uploaded files:
@@ -129,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:
@@ -279,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({
@@ -381,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.0",
-  "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

@@ -50,6 +50,8 @@ export interface UploadSingleOptions {
   uid?: number;
   gid?: number;
   mode?: string;
+  /** Directory mode for auto-created parent directories (e.g. "755"). If not set, derived from mode. */
+  dirMode?: string;
 }
 
 // --- Upload Chunked Start ---
@@ -62,6 +64,8 @@ export interface UploadChunkedStartOptions {
   uid?: number;
   gid?: number;
   mode?: string;
+  /** Directory mode for auto-created parent directories (e.g. "755"). If not set, derived from mode. */
+  dirMode?: string;
 }
 
 // --- Upload Chunked Send ---
@@ -85,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) ---
@@ -131,6 +138,7 @@ class UploadClient {
     if (opts.uid !== undefined) uploadHdrs["X-Owner-UID"] = String(opts.uid);
     if (opts.gid !== undefined) uploadHdrs["X-Owner-GID"] = String(opts.gid);
     if (opts.mode) uploadHdrs["X-File-Mode"] = opts.mode;
+    if (opts.dirMode) uploadHdrs["X-Dir-Mode"] = opts.dirMode;
 
     const res = await this._fetch(`${this.url}/files/content`, {
       method: "PUT",
@@ -151,6 +159,7 @@ class UploadClient {
         ownerUid: opts.uid,
         ownerGid: opts.gid,
         mode: opts.mode,
+        dirMode: opts.dirMode,
       };
 
       const res = await this._fetch(`${this.url}/files/upload/start`, {
@@ -287,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,
   };
 };
 
@@ -81,7 +81,7 @@ app.get(
   async (c) => {
     const { path, showHidden } = c.req.valid("query");
 
-    const result = await validatePath(path, true);
+    const result = await validatePath(path, { allowBasePath: true });
     if (!result.ok) return c.json({ error: result.error }, result.status);
 
     let s;
@@ -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);
 
@@ -239,8 +239,6 @@ app.put(
     }
 
     const fullPath = join(dirPath, filename);
-    const result = await validatePath(fullPath);
-    if (!result.ok) return c.json({ error: result.error }, result.status);
 
     // Build ownership from validated headers
     const ownership: import("../lib/ownership").Ownership | null =
@@ -249,10 +247,13 @@ app.put(
             uid: headers["x-owner-uid"],
             gid: headers["x-owner-gid"],
             mode: parseInt(headers["x-file-mode"], 8),
+            dirMode: headers["x-dir-mode"] ? parseInt(headers["x-dir-mode"], 8) : undefined,
           }
         : null;
 
-    await mkdir(dirPath, { recursive: true });
+    // Validate path and create parent directories with ownership
+    const result = await validatePath(fullPath, { createParents: true, ownership });
+    if (!result.ok) return c.json({ error: result.error }, result.status);
 
     const body = c.req.raw.body;
     if (!body) return c.json({ error: "missing body" }, 400);
@@ -356,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/handlers/search.ts

@@ -114,7 +114,7 @@ app.get(
     const validPaths: string[] = [];
 
     for (const p of paths) {
-      const result = await validatePath(p, true);
+      const result = await validatePath(p, { allowBasePath: true });
       if (!result.ok) return c.json({ error: result.error }, result.status);
 
       const s = await stat(result.realPath).catch(() => null);

package/src/handlers/upload.ts

@@ -152,7 +152,20 @@ app.post(
     }
 
     const fullPath = join(body.path, body.filename);
-    const pathResult = await validatePath(fullPath);
+
+    // Build ownership from body
+    const ownership: Ownership | null =
+      body.ownerUid != null && body.ownerGid != null && body.mode
+        ? {
+            uid: body.ownerUid,
+            gid: body.ownerGid,
+            mode: parseInt(body.mode, 8),
+            dirMode: body.dirMode ? parseInt(body.dirMode, 8) : undefined,
+          }
+        : null;
+
+    // Validate path and create parent directories with ownership
+    const pathResult = await validatePath(fullPath, { createParents: true, ownership });
     if (!pathResult.ok) return c.json({ error: pathResult.error }, pathResult.status);
 
     // Deterministic upload ID - same file/path/checksum = same ID (enables resume)
@@ -178,11 +191,6 @@ app.post(
     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,

package/src/lib/ownership.ts

@@ -1,26 +1,49 @@
-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";
 
 export type Ownership = {
   uid: number;
   gid: number;
   mode: number; // octal, e.g. 0o600
+  dirMode?: number; // octal, optional - if not set, derived from mode
+};
+
+// Derive directory mode from file mode (add x where r is set)
+// 644 → 755, 600 → 700, 664 → 775
+export const fileModeToDirectoryMode = (fileMode: number): number => {
+  let dirMode = fileMode;
+  if (fileMode & 0o400) dirMode |= 0o100; // owner read → owner exec
+  if (fileMode & 0o040) dirMode |= 0o010; // group read → group exec
+  if (fileMode & 0o004) dirMode |= 0o001; // other read → other exec
+  return dirMode;
+};
+
+// Get effective directory mode (explicit or derived from file mode)
+export const getEffectiveDirMode = (ownership: Ownership): number => {
+  return ownership.dirMode ?? fileModeToDirectoryMode(ownership.mode);
 };
 
 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");
+  const dirMode = req.headers.get("X-Dir-Mode");
 
   if (!uid || !gid || !mode) return null;
 
   const parsedMode = parseInt(mode, 8);
   if (isNaN(parsedMode)) return null;
 
+  const parsedDirMode = dirMode ? parseInt(dirMode, 8) : undefined;
+  if (dirMode && isNaN(parsedDirMode!)) return null;
+
   return {
     uid: parseInt(uid, 10),
     gid: parseInt(gid, 10),
     mode: parsedMode,
+    dirMode: parsedDirMode,
   };
 };
 
@@ -28,19 +51,20 @@ export const parseOwnershipBody = (body: {
   ownerUid?: number;
   ownerGid?: number;
   mode?: string;
+  dirMode?: 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 };
+  const dirMode = body.dirMode ? parseInt(body.dirMode, 8) : undefined;
+  if (body.dirMode && isNaN(dirMode!)) return null;
+
+  return { uid: body.ownerUid, gid: body.ownerGid, mode, dirMode };
 };
 
-export const applyOwnership = async (
-  path: string,
-  ownership: Ownership | null
-): Promise<string | null> => {
+export const applyOwnership = async (path: string, ownership: Ownership | null): Promise<string | null> => {
   if (!ownership) return null;
 
   const uid = config.devUid ?? ownership.uid;
@@ -48,7 +72,7 @@ export const applyOwnership = async (
 
   if (config.isDev) {
     console.log(
-      `[DEV] chown ${path}: ${ownership.uid}->${uid}, ${ownership.gid}->${gid}, mode=${ownership.mode.toString(8)}`
+      `[DEV] chown ${path}: ${ownership.uid}->${uid}, ${ownership.gid}->${gid}, mode=${ownership.mode.toString(8)}`,
     );
   }
 
@@ -62,3 +86,48 @@ export const applyOwnership = async (
     return `ownership failed: ${e.message}`;
   }
 };
+
+// Apply ownership to directory chain from targetDir up to (not including) basePath
+export const applyOwnershipToNewDirs = async (
+  targetDir: string,
+  basePath: string,
+  ownership: Ownership,
+): Promise<void> => {
+  const dirMode = getEffectiveDirMode(ownership);
+  const dirOwnership: Ownership = { ...ownership, mode: dirMode };
+
+  let current = targetDir;
+  while (current !== basePath && current.startsWith(basePath + "/")) {
+    await applyOwnership(current, dirOwnership);
+    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/lib/path.ts

@@ -1,6 +1,7 @@
-import { realpath } from "node:fs/promises";
+import { realpath, mkdir } from "node:fs/promises";
 import { join, normalize, dirname, basename } from "node:path";
 import { config } from "../config";
+import { applyOwnershipToNewDirs, type Ownership } from "./ownership";
 
 export type PathResult =
   | { ok: true; realPath: string; basePath: string }
@@ -22,11 +23,21 @@ const getRealBase = async (basePath: string): Promise<string | null> => {
   }
 };
 
+export type ValidatePathOptions = {
+  /** If true, allows operating on the base path itself */
+  allowBasePath?: boolean;
+  /** If true, creates parent directories if they don't exist */
+  createParents?: boolean;
+  /** Ownership to apply to newly created directories */
+  ownership?: Ownership | null;
+};
+
 /**
  * Validates path is within allowed base paths, resolves symlinks.
- * @param allowBasePath - if true, allows operating on the base path itself
+ * Optionally creates parent directories with ownership.
  */
-export const validatePath = async (path: string, allowBasePath = false): Promise<PathResult> => {
+export const validatePath = async (path: string, options: ValidatePathOptions = {}): Promise<PathResult> => {
+  const { allowBasePath = false, createParents = false, ownership = null } = options;
   const cleaned = normalize(path);
 
   // Find matching base
@@ -50,6 +61,20 @@ export const validatePath = async (path: string, allowBasePath = false): Promise
     return { ok: false, error: "path not allowed", status: 403 };
   }
 
+  // Create parent directories if requested (AFTER base validation)
+  if (createParents) {
+    const parentPath = dirname(cleaned);
+    await mkdir(parentPath, { recursive: true });
+
+    // Apply ownership to newly created directories
+    if (ownership) {
+      const realBase = await getRealBase(basePath);
+      if (realBase) {
+        await applyOwnershipToNewDirs(parentPath, realBase, ownership);
+      }
+    }
+  }
+
   // Resolve symlinks
   let realPath: string;
   try {

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({
@@ -111,6 +119,10 @@ export const UploadStartBodySchema = z.object({
     .string()
     .regex(/^[0-7]{3,4}$/)
     .optional(),
+  dirMode: z
+    .string()
+    .regex(/^[0-7]{3,4}$/)
+    .optional(),
 });
 
 // ============================================================================
@@ -163,6 +175,10 @@ export const UploadFileHeadersSchema = z.object({
     .string()
     .regex(/^[0-7]{3,4}$/)
     .optional(),
+  "x-dir-mode": z
+    .string()
+    .regex(/^[0-7]{3,4}$/)
+    .optional(),
 });
 
 export const UploadChunkHeadersSchema = z.object({