@valentinkolb/filegate 2.0.0 → 2.2.0

package/README.md

@@ -172,6 +172,14 @@ await client.transfer({
   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:**
@@ -179,6 +187,8 @@ await client.transfer({
 - `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
 
@@ -301,6 +311,9 @@ const client = new Filegate({
 // Get file or directory info
 await client.info({ path: "/data/file.txt", showHidden: false });
 
+// Get directory info with recursive sizes (slower)
+await client.info({ path: "/data/uploads", computeSizes: true });
+
 // Download file (returns streaming Response)
 await client.download({ path: "/data/file.txt" });
 
@@ -346,6 +359,7 @@ await client.transfer({
   gid: 1000,
   fileMode: "644",
   dirMode: "755",
+  ensureUniqueName: true,  // default: append -01, -02 if target exists
 });
 
 // Search files with glob patterns
@@ -439,7 +453,7 @@ All `/files/*` endpoints require `Authorization: Bearer <token>`.
 | GET | `/docs` | OpenAPI documentation (Scalar UI) |
 | GET | `/openapi.json` | OpenAPI specification |
 | GET | `/llms.txt` | LLM-friendly markdown documentation |
-| GET | `/files/info` | Get file or directory info |
+| GET | `/files/info` | Get file or directory info. Use `?computeSizes=true` for recursive dir sizes |
 | GET | `/files/content` | Download file or directory (TAR). Use `?inline=true` to view in browser |
 | PUT | `/files/content` | Upload file |
 | POST | `/files/mkdir` | Create directory |

package/package.json

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

package/src/client.ts

@@ -33,6 +33,8 @@ export interface ClientOptions {
 export interface InfoOptions {
   path: string;
   showHidden?: boolean;
+  /** If true, compute recursive sizes for directories (slower, default: false) */
+  computeSizes?: boolean;
 }
 
 // --- Download ---
@@ -94,6 +96,8 @@ 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 */
@@ -241,6 +245,7 @@ export class Filegate {
       path: opts.path,
       showHidden: String(opts.showHidden ?? false),
     });
+    if (opts.computeSizes) params.set("computeSizes", "true");
     const res = await this._fetch(`${this.url}/files/info?${params}`, { headers: this.hdrs() });
     return this.handleResponse(res);
   }
@@ -305,6 +310,7 @@ export class Filegate {
       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;

package/src/handlers/files.ts

@@ -1,7 +1,7 @@
 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, applyOwnershipRecursive } from "../lib/ownership";
@@ -23,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";
@@ -79,7 +108,7 @@ app.get(
   }),
   v("query", InfoQuerySchema),
   async (c) => {
-    const { path, showHidden } = c.req.valid("query");
+    const { path, showHidden, computeSizes } = c.req.valid("query");
 
     const result = await validatePath(path, { allowBasePath: true });
     if (!result.ok) return c.json({ error: result.error }, result.status);
@@ -97,17 +126,18 @@ app.get(
 
     const entries = await readdir(result.realPath, { withFileTypes: true });
 
-    // Parallel file info retrieval
+    // Parallel file info retrieval (computeSizes only when requested)
     const items = (
       await Promise.all(
         entries
           .filter((e) => showHidden || !e.name.startsWith("."))
-          .map((e) => getFileInfo(join(result.realPath, e.name), result.realPath, true).catch(() => null)),
+          .map((e) => getFileInfo(join(result.realPath, e.name), result.realPath, computeSizes).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 = computeSizes ? items.reduce((sum, item) => sum + item.size, 0) : 0;
+    return c.json({ ...info, size: totalSize, items, total: items.length });
   },
 );
 
@@ -376,7 +406,7 @@ app.post(
   }),
   v("json", TransferBodySchema),
   async (c) => {
-    const { from, to, mode, ownerUid, ownerGid, fileMode, dirMode } = c.req.valid("json");
+    const { from, to, mode, ensureUniqueName, ownerUid, ownerGid, fileMode, dirMode } = c.req.valid("json");
 
     // Build ownership if provided
     const ownership =
@@ -400,18 +430,20 @@ app.post(
         return c.json({ error: "source not found" }, 404);
       }
 
-      await mkdir(join(result.realTo, ".."), { recursive: true });
-      await rename(result.realPath, result.realTo);
+      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(result.realTo, ownership);
+        const ownershipError = await applyOwnershipRecursive(targetPath, ownership);
         if (ownershipError) {
           return c.json({ error: ownershipError }, 500);
         }
       }
 
-      return c.json(await getFileInfo(result.realTo));
+      return c.json(await getFileInfo(targetPath));
     }
 
     // Copy: check if same base or cross-base with ownership
@@ -425,19 +457,21 @@ app.post(
         return c.json({ error: "source not found" }, 404);
       }
 
-      await mkdir(join(sameBaseResult.realTo, ".."), { recursive: true });
-      await cp(sameBaseResult.realPath, sameBaseResult.realTo, { recursive: true });
+      const targetPath = ensureUniqueName ? await getUniquePath(sameBaseResult.realTo) : sameBaseResult.realTo;
+
+      await mkdir(join(targetPath, ".."), { recursive: true });
+      await cp(sameBaseResult.realPath, targetPath, { recursive: true });
 
       // Apply ownership if provided
       if (ownership) {
-        const ownershipError = await applyOwnershipRecursive(sameBaseResult.realTo, ownership);
+        const ownershipError = await applyOwnershipRecursive(targetPath, ownership);
         if (ownershipError) {
-          await rm(sameBaseResult.realTo, { recursive: true }).catch(() => {});
+          await rm(targetPath, { recursive: true }).catch(() => {});
           return c.json({ error: ownershipError }, 500);
         }
       }
 
-      return c.json(await getFileInfo(sameBaseResult.realTo));
+      return c.json(await getFileInfo(targetPath));
     }
 
     // Cross-base copy - ownership is required
@@ -458,17 +492,19 @@ app.post(
       return c.json({ error: "source not found" }, 404);
     }
 
-    await mkdir(join(toResult.realPath, ".."), { recursive: true });
-    await cp(fromResult.realPath, toResult.realPath, { 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(toResult.realPath, ownership);
+    const ownershipError = await applyOwnershipRecursive(targetPath, ownership);
     if (ownershipError) {
-      await rm(toResult.realPath, { recursive: true }).catch(() => {});
+      await rm(targetPath, { recursive: true }).catch(() => {});
       return c.json({ error: ownershipError }, 500);
     }
 
-    return c.json(await getFileInfo(toResult.realPath));
+    return c.json(await getFileInfo(targetPath));
   },
 );
 

package/src/schemas.ts

@@ -4,71 +4,94 @@ 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"),
+    computeSizes: z
+      .string()
+      .optional()
+      .transform((v) => v === "true")
+      .describe("If 'true', compute recursive sizes for directories (slower, default: false)"),
+  })
+  .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,116 +102,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 TransferModeSchema = z.enum(["move", "copy"]);
-
-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({
-  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