feat: add the openapi docs

docs/integration-guide.md

@@ -0,0 +1,98 @@
+# Frontend integration guide
+
+## Architecture
+
+Use a backend-for-frontend (BFF) as the trust boundary:
+
+```text
+Browser → BFF (holds ACCESS_KEY + SECRET_KEY, issues presigned URLs) → I.R.I.S. Worker → Google Drive
+```
+
+Never put `SECRET_KEY` in browser code, a static site, or a public environment variable. The browser receives only a short-lived presigned URL for one method and object key.
+
+## Enable browser access
+
+Configure the Worker with an explicit allow-list of web origins:
+
+```ini
+CORS_ALLOWED_ORIGINS=https://app.example.com,http://localhost:5173
+```
+
+Set it to `*` only for a genuinely public, credential-free integration. Leaving it unset emits no CORS headers. I.R.I.S. exposes `ETag`, `Content-Range`, `Content-Length`, `Last-Modified`, `Accept-Ranges`, and `x-amz-request-id`, so browser code can inspect the headers that form the effective S3 response payload.
+
+### Server-to-server compatibility
+
+CORS does not restrict non-browser clients. `Access-Control-*` headers are emitted only when a request has an allowed `Origin`; a CLI, Dokploy, rclone, aws-cli, or other service request with no `Origin` keeps its normal S3 status and body. With an exact origin allow-list, responses also include `Vary: Origin`, including requests without an `Origin`, so shared caches cannot replay a no-origin object response to a browser. S3 clients ignore this cache-control metadata.
+
+An `OPTIONS` request with no `Origin`, or a preflight from a disallowed origin, receives the same bare `204` as a CORS-disabled Worker. A disallowed `Origin` never changes the underlying S3 result—it simply receives no `Access-Control-*` headers.
+
+## Presign in the BFF
+
+Use `@aws-sdk/s3-request-presigner` and send a limited expiry. I.R.I.S. validates `X-Amz-Expires` and rejects URLs after their signing time plus that value.
+
+```ts
+import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+
+const client = new S3Client({
+    endpoint: env.IRIS_ENDPOINT,
+    region: env.IRIS_REGION,
+    credentials: {
+        accessKeyId: env.IRIS_ACCESS_KEY,
+        secretAccessKey: env.IRIS_SECRET_KEY,
+    },
+    forcePathStyle: true,
+});
+
+const url = await getSignedUrl(
+    client,
+    new PutObjectCommand({
+        Bucket: "assets",
+        Key: "uploads/avatar.png",
+        ContentType: "image/png",
+    }),
+    { expiresIn: 300 },
+);
+```
+
+Keep the `ContentType` in the command and send precisely that same `Content-Type` from the browser. It becomes the Drive `mimeType`. A non-simple content type causes a preflight request, which is why the Worker CORS configuration is necessary.
+
+## Upload one object
+
+Use `Blob`, `File`, `ArrayBuffer`, or a typed array as the body. This lets the browser provide a known body length. Do **not** use a `ReadableStream` unless the BFF signs `x-amz-decoded-content-length` and the browser sends it: multipart part uploads require `Content-Length` or `x-amz-decoded-content-length`.
+
+```ts
+const response = await fetch(presignedUrl, {
+    method: "PUT",
+    headers: { "Content-Type": file.type || "application/octet-stream" },
+    body: file,
+});
+
+if (!response.ok) throw new Error(await response.text());
+const etag = response.headers.get("ETag");
+```
+
+`ETag` is readable only when the request `Origin` is configured in `CORS_ALLOWED_ORIGINS`.
+
+## Multipart upload
+
+Cloudflare request limits mean a single PUT is best kept below roughly 100 MB. For larger files, have the BFF initiate the upload, issue a presigned URL for each part, and complete the upload after the browser returns all ETags.
+
+Use 16 MB parts as a practical baseline. Upload parts **strictly sequentially starting at 1**. I.R.I.S. waits up to 20 seconds for an earlier part; out-of-order work then receives `503 SlowDown`. Requests more than 64 part numbers ahead are rejected immediately.
+
+1. BFF signs `POST /bucket/key?uploads` and starts the multipart upload.
+2. BFF issues a signed `PUT` URL for part 1; browser uploads it and records the `ETag`.
+3. Repeat one part at a time for parts 2 through $n$.
+4. BFF signs `POST /bucket/key?uploadId=…`; browser sends the `CompleteMultipartUpload` XML body containing the sequential part numbers and ETags.
+
+See [`examples/browser-multipart.ts`](./examples/browser-multipart.ts) for a complete browser-side loop.
+
+## Build a file browser
+
+List with `prefix` and `delimiter=/`:
+
+```text
+GET /assets?prefix=photos/&delimiter=/
+```
+
+Files appear in `Contents`; immediate child folders appear as `CommonPrefixes`. Google Drive directories are physical folders, not zero-byte marker objects. Read [limitations](./limitations.md) before designing pagination or rename/move features.