docs: strict content type AdminForth/2032/fix-upload-plugin-and-storage-

Storage adapters: strictContentType option of the S3 adapters. Upload
plugin API: the examples send the contentType returned with the upload
URL, and size has to be the real size of the file.

Author: srelon

documentation/docs/tutorial/06-Adapters/04-storage-adapters.md

@@ -16,12 +16,31 @@ pnpm add @adminforth/storage-adapter-amazon-s3
 
 Stores uploaded files in [Amazon S3](https://aws.amazon.com/s3/), providing scalable cloud storage. 
 
+### Strict content type
+
+The upload plugin picks the content type of a file by its extension, e.g. `image/png` for `.png`. By default S3 does not check it on upload, so a client can store a file with any `Content-Type`, e.g. `text/html` under a `.png` key, and the browser will open it as a page. Set `strictContentType: true` to sign the content type into the upload URL, then an upload with another type is rejected:
+
+```ts
+new AdminForthAdapterS3Storage({
+  bucket: process.env.AWS_BUCKET_NAME as string,
+  region: process.env.AWS_REGION as string,
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID as string,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY as string,
+  strictContentType: true,
+}),
+```
+
+Before turning it on, update `@adminforth/bulk-ai-flow`, `@adminforth/markdown`, `@adminforth/rich-editor` and `@adminforth/oauth`: their older versions send the type reported by the browser, and the upload fails when it differs from the one picked by the extension. Your own code that uploads files to the URL from the [upload plugin API](../09-Plugins/05-1-upload-api.md) has to send the `contentType` returned with the URL as well. While the option is off, the adapter logs a warning on start. It will be on by default in the next major version.
+
 ## S3 compatible adapter
 ```bash
 pnpm add @adminforth/storage-adapter-s3-compatible
 ```
 
 Provides S3 compatible interface for object storage services such as MinIO, Wasabi, Cloudflare R2 or other third-party S3 providers.
+
+It supports the same `strictContentType` option as the Amazon S3 adapter, see [Strict content type](#strict-content-type).
+
 ### How the adapter works
 
 The Amazon S3 adapter uses tagging to mark objects with the special tag `adminforth-candidate-for-cleanup`, and then creates a lifecycle rule that automatically expires objects with that tag.

documentation/docs/tutorial/09-Plugins/05-1-upload-api.md

@@ -115,14 +115,14 @@ app.post(
 
     const plugin = admin.getPluginById('my_reports_plugin');
 
-    const { uploadUrl, filePath, uploadExtraParams, pathColumnName } = await plugin.getUploadUrl({
+    const { uploadUrl, contentType: uploadContentType, filePath, uploadExtraParams, pathColumnName } = await plugin.getUploadUrl({
       recordId, // can be undefined for new records
       filename, // e.g. file.name
       contentType, // e.g. file.type
-      size, // optional, will be validated against maxFileSize to drop error earlier
+      size, // e.g. file.size: validated against maxFileSize, the upload URL then accepts only a file of exactly this size
     });
 
-    res.json({ uploadUrl, filePath, uploadExtraParams, pathColumnName });
+    res.json({ uploadUrl, contentType: uploadContentType, filePath, uploadExtraParams, pathColumnName });
   }),
 );
 ```
@@ -133,7 +133,7 @@ On the frontend:
 const file = input.files[0];
 
 // 1) Ask your backend to generate upload URL
-const { uploadUrl, filePath, uploadExtraParams } = await fetch('/api/uploads/get-url-existing', {
+const { uploadUrl, contentType, filePath, uploadExtraParams } = await fetch('/api/uploads/get-url-existing', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({
@@ -166,7 +166,8 @@ await new Promise<void>((resolve, reject) => {
   });
 
   xhr.open('PUT', uploadUrl, true);
-  xhr.setRequestHeader('Content-Type', file.type || 'application/octet-stream');
+  // the type picked by the plugin from the file extension, the storage may reject another one
+  xhr.setRequestHeader('Content-Type', contentType);
 
   if (uploadExtraParams) {
     Object.entries(uploadExtraParams).forEach(([key, value]) => {
@@ -321,7 +322,7 @@ async function onFileChange(e: Event) {
   if (!file) return;
 
   // 1) Ask backend for presigned URL
-  const { uploadUrl, filePath, uploadExtraParams, pathColumnName } = await fetch(
+  const { uploadUrl, contentType, filePath, uploadExtraParams, pathColumnName } = await fetch(
     '/api/uploads/avatar/get-url',
     {
       method: 'POST',
@@ -357,7 +358,8 @@ async function onFileChange(e: Event) {
     });
 
     xhr.open('PUT', uploadUrl, true);
-    xhr.setRequestHeader('Content-Type', file.type || 'application/octet-stream');
+    // the type picked by the plugin from the file extension, the storage may reject another one
+    xhr.setRequestHeader('Content-Type', contentType);
 
     if (uploadExtraParams) {
       Object.entries(uploadExtraParams).forEach(([key, value]) => {
@@ -395,14 +397,14 @@ app.post(
 
     const plugin = admin.getPluginById('my_reports_plugin');
 
-    const { uploadUrl, filePath, uploadExtraParams, pathColumnName } = await plugin.getUploadUrl({
+    const { uploadUrl, contentType: uploadContentType, filePath, uploadExtraParams, pathColumnName } = await plugin.getUploadUrl({
       recordId, // can be undefined for create pages
       filename,
       contentType,
-      size, // optional
+      size, // exact size of the file, the upload URL accepts only this size
     });
 
-    res.json({ uploadUrl, filePath, uploadExtraParams, pathColumnName });
+    res.json({ uploadUrl, contentType: uploadContentType, filePath, uploadExtraParams, pathColumnName });
   }),
 );
 ```