first commit

docs/api-stack/api/api-plugin-file-upload/src/schemas/routes/initiate.md

@@ -0,0 +1,50 @@
+# `initiate.ts`
+
+## Purpose
+
+Defines the request body and response shape for `POST /uploads/initiate`, the chunked upload bootstrap endpoint. The client declares the file's total size, SHA-256 hash, and optional MIME type up-front; the server returns the `uploadId`, server-chosen `chunkSize`, and `totalChunks` so the client can deterministically slice the file.
+
+## Features
+
+- Client-declared `totalSha256` is the contract the server later verifies on `complete` — mismatch raises `UPLOAD.HASH_MISMATCH` (HTTP 422).
+- `mimeType` defaults to `application/octet-stream` so clients uploading binary payloads need not guess.
+- `chunkSize` may be overridden by the client; absent, the server uses the configured `defaultChunkSize`.
+- 255-char `fileName` cap matches POSIX `NAME_MAX`.
+
+## Usage: Basic
+
+```ts
+import { InitiateUploadBodySchema } from "@suaveplan/api-plugin-file-upload/schemas/routes";
+
+const body = InitiateUploadBodySchema.parse(await c.req.json());
+```
+
+## Usage: Advanced
+
+```ts
+import { InitiateUploadBodySchema } from "@suaveplan/api-plugin-file-upload";
+import fc from "fast-check";
+
+fc.assert(
+    fc.property(
+        fc.record({
+            fileName: fc.string({ minLength: 1, maxLength: 255 }),
+            totalSize: fc.integer({ min: 1, max: 1024 * 1024 * 1024 }),
+            totalSha256: fc.hexaString({ minLength: 64, maxLength: 64 }),
+        }),
+        (input) => InitiateUploadBodySchema.safeParse(input).success
+    ),
+    { numRuns: 200 }
+);
+```
+
+## API Reference
+
+- `InitiateUploadBodySchema` — Zod schema for the request body.
+- `InitiateUploadResponseSchema` — Zod schema for the success response (`uploadId`, `chunkSize`, `totalChunks`).
+- `InitiateUploadBody` / `InitiateUploadResponse` — `z.infer` aliases.
+
+## Implementation Notes
+
+- The server intentionally trusts the client-declared `totalSha256` only as a verification target — the actual hash is computed server-side from the assembled bytes. A mismatch surfaces as a 422 so clients can re-derive and retry without rebuilding the entire upload state.
+- `chunkSize` is server-bounded by `defaultChunkSize` to prevent pathological tiny-chunk attacks; the validator at the service layer caps client-supplied values.