@valentinkolb/filegate 1.1.1 → 2.1.0

package/README.md

@@ -144,6 +144,52 @@ 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",
+});
+
+// Allow overwriting existing files (default: false)
+await client.transfer({
+  from: "/data/new-file.txt",
+  to: "/data/existing-file.txt",
+  mode: "copy",
+  ensureUniqueName: false,  // Overwrite if target exists
+});
+```
+
+**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
+- `ensureUniqueName: true` (default) - Appends `-01`, `-02`, etc. if target exists
+- `ensureUniqueName: false` - Overwrites existing target file
+
 ### Chunked Uploads
 
 For large files, use chunked uploads. They support:
@@ -294,11 +340,24 @@ 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",
+  ensureUniqueName: true,  // default: append -01, -02 if target exists
+});
 
 // Search files with glob patterns
 await client.glob({
@@ -396,8 +455,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.1.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,21 @@ 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";
+  /** If true (default), appends -01, -02, etc. to avoid overwriting existing files */
+  ensureUniqueName?: boolean;
+  /** 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 +298,25 @@ 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.ensureUniqueName !== undefined) body.ensureUniqueName = opts.ensureUniqueName;
+    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

@@ -1,10 +1,10 @@
 import { Hono } from "hono";
 import { describeRoute } from "hono-openapi";
-import { readdir, mkdir, rm, rename, cp, stat } from "node:fs/promises";
-import { join, basename, relative } from "node:path";
+import { readdir, mkdir, rm, rename, cp, stat, access } from "node:fs/promises";
+import { join, basename, relative, dirname, extname } 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";
@@ -24,6 +23,35 @@ import { config } from "../config";
 
 const app = new Hono();
 
+// Generate a unique path by appending -01, -02, etc. if target exists
+const getUniquePath = async (targetPath: string): Promise<string> => {
+  // Check if target exists
+  try {
+    await access(targetPath);
+  } catch {
+    // Doesn't exist, use as-is
+    return targetPath;
+  }
+
+  const dir = dirname(targetPath);
+  const ext = extname(targetPath);
+  const base = basename(targetPath, ext);
+
+  for (let i = 1; i <= 99; i++) {
+    const suffix = i.toString().padStart(2, "0");
+    const newPath = join(dir, `${base}-${suffix}${ext}`);
+    try {
+      await access(newPath);
+    } catch {
+      return newPath;
+    }
+  }
+
+  // Fallback: use timestamp if all 99 are taken
+  const timestamp = Date.now();
+  return join(dir, `${base}-${timestamp}${ext}`);
+};
+
 // Cross-platform directory size using `du` command
 const getDirSize = async (dirPath: string): Promise<number> => {
   const isMac = process.platform === "darwin";
@@ -47,19 +75,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,12 +131,13 @@ 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);
 
     const info = await getFileInfo(result.realPath);
-    return c.json({ ...info, items, total: items.length });
+    const totalSize = items.reduce((sum, item) => sum + item.size, 0);
+    return c.json({ ...info, size: totalSize, items, total: items.length });
   },
 );
 
@@ -357,73 +387,124 @@ 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, ensureUniqueName, 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);
+      }
+
+      const targetPath = ensureUniqueName ? await getUniquePath(result.realTo) : result.realTo;
+
+      await mkdir(join(targetPath, ".."), { recursive: true });
+      await rename(result.realPath, targetPath);
+
+      // Apply ownership if provided (for move within same base)
+      if (ownership) {
+        const ownershipError = await applyOwnershipRecursive(targetPath, ownership);
+        if (ownershipError) {
+          return c.json({ error: ownershipError }, 500);
+        }
+      }
+
+      return c.json(await getFileInfo(targetPath));
     }
 
-    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");
+      const targetPath = ensureUniqueName ? await getUniquePath(sameBaseResult.realTo) : sameBaseResult.realTo;
 
-    const result = await validateSameBase(from, to);
-    if (!result.ok) return c.json({ error: result.error }, result.status);
+      await mkdir(join(targetPath, ".."), { recursive: true });
+      await cp(sameBaseResult.realPath, targetPath, { recursive: true });
+
+      // Apply ownership if provided
+      if (ownership) {
+        const ownershipError = await applyOwnershipRecursive(targetPath, ownership);
+        if (ownershipError) {
+          await rm(targetPath, { recursive: true }).catch(() => {});
+          return c.json({ error: ownershipError }, 500);
+        }
+      }
+
+      return c.json(await getFileInfo(targetPath));
+    }
+
+    // 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 });
+    const targetPath = ensureUniqueName ? await getUniquePath(toResult.realPath) : toResult.realPath;
+
+    await mkdir(join(targetPath, ".."), { recursive: true });
+    await cp(fromResult.realPath, targetPath, { recursive: true });
+
+    // Apply ownership recursively to copied content
+    const ownershipError = await applyOwnershipRecursive(targetPath, ownership);
+    if (ownershipError) {
+      await rm(targetPath, { recursive: true }).catch(() => {});
+      return c.json({ error: ownershipError }, 500);
+    }
 
-    return c.json(await getFileInfo(result.realTo));
+    return c.json(await getFileInfo(targetPath));
   },
 );
 

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

@@ -4,71 +4,89 @@ import { z } from "zod";
 // Common
 // ============================================================================
 
-export const ErrorSchema = z.object({
-  error: z.string(),
-});
-
-export const FileTypeSchema = z.enum(["file", "directory"]);
-
-export const FileInfoSchema = z.object({
-  name: z.string(),
-  path: z.string(),
-  type: FileTypeSchema,
-  size: z.number(),
-  mtime: z.iso.datetime(),
-  isHidden: z.boolean(),
-  mimeType: z.string().optional(),
-});
+export const ErrorSchema = z
+  .object({
+    error: z.string().describe("Error message describing what went wrong"),
+  })
+  .describe("Error response returned when a request fails");
+
+export const FileTypeSchema = z.enum(["file", "directory"]).describe("Type of filesystem entry");
+
+export const FileInfoSchema = z
+  .object({
+    name: z.string().describe("Filename or directory name"),
+    path: z.string().describe("Relative path from the base directory"),
+    type: FileTypeSchema,
+    size: z.number().describe("File size in bytes, or total directory size for directories"),
+    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)"),
+  })
+  .describe("Information about a file or directory");
 
 export const DirInfoSchema = FileInfoSchema.extend({
-  items: z.array(FileInfoSchema),
-  total: z.number(),
-});
+  items: z.array(FileInfoSchema).describe("List of files and directories in this directory"),
+  total: z.number().describe("Total number of items in the directory"),
+}).describe("Directory information including its contents");
 
 // ============================================================================
 // Query Params
 // ============================================================================
 
-export const PathQuerySchema = z.object({
-  path: z.string().min(1),
-});
-
-export const ContentQuerySchema = z.object({
-  path: z.string().min(1),
-  inline: z
-    .string()
-    .optional()
-    .transform((v) => v === "true"), // default: false (attachment)
-});
-
-export const InfoQuerySchema = z.object({
-  path: z.string().min(1),
-  showHidden: z
-    .string()
-    .optional()
-    .transform((v) => v === "true"),
-});
-
-export const SearchQuerySchema = z.object({
-  paths: z.string().min(1),
-  pattern: z.string().min(1).max(500),
-  showHidden: z
-    .string()
-    .optional()
-    .transform((v) => v === "true"),
-  limit: z
-    .string()
-    .optional()
-    .transform((v) => (v ? parseInt(v, 10) : undefined)),
-  files: z
-    .string()
-    .optional()
-    .transform((v) => v !== "false"), // default: true
-  directories: z
-    .string()
-    .optional()
-    .transform((v) => v === "true"), // default: false
-});
+export const PathQuerySchema = z
+  .object({
+    path: z.string().min(1).describe("Absolute path to the file or directory"),
+  })
+  .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"),
+    inline: z
+      .string()
+      .optional()
+      .transform((v) => v === "true")
+      .describe("If 'true', display in browser instead of downloading (Content-Disposition: inline)"),
+  })
+  .describe("Query parameters for content download");
+
+export const InfoQuerySchema = z
+  .object({
+    path: z.string().min(1).describe("Absolute path to the file or directory"),
+    showHidden: z
+      .string()
+      .optional()
+      .transform((v) => v === "true")
+      .describe("If 'true', include hidden files (starting with dot) in directory listings"),
+  })
+  .describe("Query parameters for file/directory info");
+
+export const SearchQuerySchema = z
+  .object({
+    paths: z.string().min(1).describe("Comma-separated list of base paths to search in"),
+    pattern: z.string().min(1).max(500).describe("Glob pattern to match files (e.g., '*.txt', '**/*.pdf')"),
+    showHidden: z
+      .string()
+      .optional()
+      .transform((v) => v === "true")
+      .describe("If 'true', include hidden files in search results"),
+    limit: z
+      .string()
+      .optional()
+      .transform((v) => (v ? parseInt(v, 10) : undefined))
+      .describe("Maximum number of results to return"),
+    files: z
+      .string()
+      .optional()
+      .transform((v) => v !== "false")
+      .describe("If 'false', exclude files from results (default: true)"),
+    directories: z
+      .string()
+      .optional()
+      .transform((v) => v === "true")
+      .describe("If 'true', include directories in results (default: false)"),
+  })
+  .describe("Query parameters for glob-based file search");
 
 /** Count recursive wildcards (**) in a glob pattern */
 export const countRecursiveWildcards = (pattern: string): number => {
@@ -79,108 +97,163 @@ export const countRecursiveWildcards = (pattern: string): number => {
 // Request Bodies
 // ============================================================================
 
-export const MkdirBodySchema = z.object({
-  path: z.string().min(1),
-  ownerUid: z.number().int().optional(),
-  ownerGid: z.number().int().optional(),
-  mode: z
-    .string()
-    .regex(/^[0-7]{3,4}$/)
-    .optional(),
-});
-
-export const MoveBodySchema = z.object({
-  from: z.string().min(1),
-  to: z.string().min(1),
-});
-
-export const CopyBodySchema = z.object({
-  from: z.string().min(1),
-  to: z.string().min(1),
-});
-
-export const UploadStartBodySchema = z.object({
-  path: z.string().min(1),
-  filename: z.string().min(1),
-  size: z.number().int().positive(),
-  checksum: z.string().regex(/^sha256:[a-f0-9]{64}$/),
-  chunkSize: z.number().int().positive(),
-  ownerUid: z.number().int().optional(),
-  ownerGid: z.number().int().optional(),
-  mode: z
-    .string()
-    .regex(/^[0-7]{3,4}$/)
-    .optional(),
-  dirMode: z
-    .string()
-    .regex(/^[0-7]{3,4}$/)
-    .optional(),
-});
+export const MkdirBodySchema = z
+  .object({
+    path: z.string().min(1).describe("Absolute path of the directory to create"),
+    ownerUid: z.number().int().optional().describe("Unix user ID to set as owner"),
+    ownerGid: z.number().int().optional().describe("Unix group ID to set as owner"),
+    mode: z
+      .string()
+      .regex(/^[0-7]{3,4}$/)
+      .optional()
+      .describe("Unix permission mode (e.g., '755' or '0755')"),
+  })
+  .describe("Request body for creating a directory");
+
+export const TransferModeSchema = z
+  .enum(["move", "copy"])
+  .describe("Transfer operation type: 'move' (rename) or 'copy' (duplicate)");
+
+export const TransferBodySchema = z
+  .object({
+    from: z.string().min(1).describe("Source path of the file or directory"),
+    to: z.string().min(1).describe("Destination path for the file or directory"),
+    mode: TransferModeSchema,
+    ensureUniqueName: z
+      .boolean()
+      .default(true)
+      .describe("If true, append -01, -02, etc. to avoid overwriting existing files (default: true)"),
+    ownerUid: z.number().int().optional().describe("Unix user ID for ownership (required for cross-base copy)"),
+    ownerGid: z.number().int().optional().describe("Unix group ID for ownership (required for cross-base copy)"),
+    fileMode: z
+      .string()
+      .regex(/^[0-7]{3,4}$/)
+      .optional()
+      .describe("Unix permission mode for files (e.g., '644', required for cross-base copy)"),
+    dirMode: z
+      .string()
+      .regex(/^[0-7]{3,4}$/)
+      .optional()
+      .describe("Unix permission mode for directories (e.g., '755', defaults to fileMode if not set)"),
+  })
+  .describe("Request body for moving or copying files/directories");
+
+export const UploadStartBodySchema = z
+  .object({
+    path: z.string().min(1).describe("Directory path where the file will be uploaded"),
+    filename: z.string().min(1).describe("Name of the file to upload"),
+    size: z.number().int().positive().describe("Total size of the file in bytes"),
+    checksum: z
+      .string()
+      .regex(/^sha256:[a-f0-9]{64}$/)
+      .describe("SHA-256 checksum of the entire file (format: 'sha256:<64 hex chars>')"),
+    chunkSize: z.number().int().positive().describe("Size of each chunk in bytes"),
+    ownerUid: z.number().int().optional().describe("Unix user ID to set as owner"),
+    ownerGid: z.number().int().optional().describe("Unix group ID to set as owner"),
+    mode: z
+      .string()
+      .regex(/^[0-7]{3,4}$/)
+      .optional()
+      .describe("Unix permission mode for the uploaded file (e.g., '644')"),
+    dirMode: z
+      .string()
+      .regex(/^[0-7]{3,4}$/)
+      .optional()
+      .describe("Unix permission mode for auto-created parent directories (e.g., '755')"),
+  })
+  .describe("Request body to start or resume a chunked upload");
 
 // ============================================================================
 // Response Schemas
 // ============================================================================
 
-export const SearchResultSchema = z.object({
-  basePath: z.string(),
-  files: z.array(FileInfoSchema),
-  total: z.number(),
-  hasMore: z.boolean(),
-});
-
-export const SearchResponseSchema = z.object({
-  results: z.array(SearchResultSchema),
-  totalFiles: z.number(),
-});
-
-export const UploadStartResponseSchema = z.object({
-  uploadId: z.string().regex(/^[a-f0-9]{16}$/),
-  totalChunks: z.number(),
-  chunkSize: z.number(),
-  uploadedChunks: z.array(z.number()),
-  completed: z.literal(false),
-});
-
-export const UploadChunkProgressSchema = z.object({
-  chunkIndex: z.number(),
-  uploadedChunks: z.array(z.number()),
-  completed: z.literal(false),
-});
-
-export const UploadChunkCompleteSchema = z.object({
-  completed: z.literal(true),
-  file: FileInfoSchema.extend({ checksum: z.string() }),
-});
-
-export const UploadChunkResponseSchema = z.union([UploadChunkProgressSchema, UploadChunkCompleteSchema]);
+export const SearchResultSchema = z
+  .object({
+    basePath: z.string().describe("Base path that was searched"),
+    files: z.array(FileInfoSchema).describe("List of matching files and directories"),
+    total: z.number().describe("Number of matches found in this base path"),
+    hasMore: z.boolean().describe("True if there are more results beyond the limit"),
+  })
+  .describe("Search results for a single base path");
+
+export const SearchResponseSchema = z
+  .object({
+    results: z.array(SearchResultSchema).describe("Search results grouped by base path"),
+    totalFiles: z.number().describe("Total number of matches across all base paths"),
+  })
+  .describe("Complete search response with results from all searched paths");
+
+export const UploadStartResponseSchema = z
+  .object({
+    uploadId: z
+      .string()
+      .regex(/^[a-f0-9]{16}$/)
+      .describe("Unique identifier for this upload session"),
+    totalChunks: z.number().describe("Total number of chunks expected"),
+    chunkSize: z.number().describe("Size of each chunk in bytes"),
+    uploadedChunks: z.array(z.number()).describe("Indices of chunks already uploaded (for resume)"),
+    completed: z.literal(false).describe("Always false for start response"),
+  })
+  .describe("Response when starting or resuming a chunked upload");
+
+export const UploadChunkProgressSchema = z
+  .object({
+    chunkIndex: z.number().describe("Index of the chunk that was just uploaded"),
+    uploadedChunks: z.array(z.number()).describe("All chunk indices uploaded so far"),
+    completed: z.literal(false).describe("False while upload is still in progress"),
+  })
+  .describe("Response after uploading a chunk (upload not yet complete)");
+
+export const UploadChunkCompleteSchema = z
+  .object({
+    completed: z.literal(true).describe("True when all chunks have been uploaded"),
+    file: FileInfoSchema.extend({
+      checksum: z.string().describe("SHA-256 checksum of the assembled file"),
+    }).describe("Information about the completed file"),
+  })
+  .describe("Response after uploading the final chunk");
+
+export const UploadChunkResponseSchema = z
+  .union([UploadChunkProgressSchema, UploadChunkCompleteSchema])
+  .describe("Response after uploading a chunk (either progress or completion)");
 
 // ============================================================================
 // Header Schemas
 // ============================================================================
 
-export const UploadFileHeadersSchema = z.object({
-  "x-file-path": z.string().min(1),
-  "x-file-name": z.string().min(1),
-  "x-owner-uid": z.string().regex(/^\d+$/).transform(Number).optional(),
-  "x-owner-gid": z.string().regex(/^\d+$/).transform(Number).optional(),
-  "x-file-mode": z
-    .string()
-    .regex(/^[0-7]{3,4}$/)
-    .optional(),
-  "x-dir-mode": z
-    .string()
-    .regex(/^[0-7]{3,4}$/)
-    .optional(),
-});
-
-export const UploadChunkHeadersSchema = z.object({
-  "x-upload-id": z.string().regex(/^[a-f0-9]{16}$/),
-  "x-chunk-index": z.string().regex(/^\d+$/).transform(Number),
-  "x-chunk-checksum": z
-    .string()
-    .regex(/^sha256:[a-f0-9]{64}$/)
-    .optional(),
-});
+export const UploadFileHeadersSchema = z
+  .object({
+    "x-file-path": z.string().min(1).describe("Directory path where the file will be uploaded"),
+    "x-file-name": z.string().min(1).describe("Name of the file to upload"),
+    "x-owner-uid": z.string().regex(/^\d+$/).transform(Number).optional().describe("Unix user ID to set as owner"),
+    "x-owner-gid": z.string().regex(/^\d+$/).transform(Number).optional().describe("Unix group ID to set as owner"),
+    "x-file-mode": z
+      .string()
+      .regex(/^[0-7]{3,4}$/)
+      .optional()
+      .describe("Unix permission mode for the file (e.g., '644')"),
+    "x-dir-mode": z
+      .string()
+      .regex(/^[0-7]{3,4}$/)
+      .optional()
+      .describe("Unix permission mode for auto-created directories (e.g., '755')"),
+  })
+  .describe("Headers for simple file upload");
+
+export const UploadChunkHeadersSchema = z
+  .object({
+    "x-upload-id": z
+      .string()
+      .regex(/^[a-f0-9]{16}$/)
+      .describe("Upload session ID from the start response"),
+    "x-chunk-index": z.string().regex(/^\d+$/).transform(Number).describe("Zero-based index of this chunk"),
+    "x-chunk-checksum": z
+      .string()
+      .regex(/^sha256:[a-f0-9]{64}$/)
+      .optional()
+      .describe("SHA-256 checksum of this chunk for verification (format: 'sha256:<64 hex chars>')"),
+  })
+  .describe("Headers for uploading a chunk");
 
 // ============================================================================
 // Types