@muhgholy/next-drive 4.23.7 → 4.23.10

package/README.md

@@ -7,7 +7,8 @@ File storage and management for Next.js and Express apps. Includes a responsive
 -    📁 **File Management** – Upload, rename, move, organize files and folders
 -    🔍 **Search** – Search active files or trash with real-time filtering
 -    🗑️ **Trash System** – Soft delete, restore, and empty trash
--    📱 **Responsive UI** – Optimized for desktop and mobile
+-    � **Anonymous Uploads** – One-time uploads with auto-expiry, confirmation, and abuse prevention
+-    �📱 **Responsive UI** – Optimized for desktop and mobile
 -    🎬 **Video Thumbnails** – Auto-generated thumbnails (requires FFmpeg)
 -    🔐 **Security** – Signed URLs and configurable upload limits
 -    📊 **View Modes** – Grid/List views with sorting and grouping
@@ -188,6 +189,8 @@ function MyForm() {
 }
 ```
 
+> For unauthenticated, one-time uploads, add the `allowUnauthenticated` prop. See [Anonymous (One-Time) Uploads](#anonymous-one-time-uploads).
+
 ---
 
 ## Express Integration
@@ -582,6 +585,128 @@ await driveDelete(items[0]);
 
 ---
 
+## Anonymous (One-Time) Uploads
+
+Let **unauthenticated** users upload a file once — without giving them access to a drive. The user picks a file, it uploads with progress (just like the drive explorer), and you receive a normal `TDriveFile` (with a real `drive.id`). The file is **temporary**: it is automatically deleted after a TTL (default **60 minutes**) unless your backend explicitly confirms it.
+
+The same `DriveFileChooser` adapts to the visitor automatically: **logged-in users get the full drive explorer** (browse + pick existing files or upload to their own drive, stored permanently), while **anonymous visitors get a one-time upload** (temporary, auto-expiring). You opt in with a single `allowUnauthenticated` prop.
+
+This is useful for forms where you need a `drive.id` for an anonymous visitor (e.g. a contact form attachment, a job application, or a guest submission) but don't want to expose your authenticated drive.
+
+**Lifecycle:** `pick file → upload → returns TDriveFile (temporary)` → your backend saves `drive.id` → `driveConfirm(id)` keeps it → otherwise `drivePurgeExpired()` deletes it after the TTL.
+
+### 1. Enable in your server configuration
+
+Add an `unauthenticated` block to `security`. It is **completely separate** from your authenticated limits (it has its own size and MIME allow-list). The feature is disabled unless `enabled: true`.
+
+```typescript
+security: {
+	// ...your normal authenticated limits
+	maxUploadSizeInBytes: 50 * 1024 * 1024,
+	allowedMimeTypes: ["image/*", "video/*", "application/pdf"],
+
+	unauthenticated: {
+		enabled: true,
+		ttlMinutes: 60, // Lifetime before auto-delete (default 60)
+		maxUploadSizeInBytes: 25 * 1024 * 1024, // 25MB (separate from authenticated limit)
+		allowedMimeTypes: ["image/*", "application/pdf"],
+
+		// Optional abuse prevention (all fields optional)
+		abuse: {
+			perIp: { windowMinutes: 10, max: 20 }, // Max 20 uploads / 10 min per IP
+			hourlyPerIp: 60, // Max 60 uploads / hour per IP
+			maxConcurrent: 10, // Max simultaneous anonymous uploads (global)
+			maxLiveBytes: 2 * 1024 * 1024 * 1024, // Max total live temporary storage (global)
+		},
+	},
+}
+```
+
+> Anonymous uploads do **not** count against any user's quota and are stored with no owner.
+
+### 2. Client component
+
+Pass the `allowUnauthenticated` prop to `DriveFileChooser`. It checks the visitor's auth status once on mount:
+
+- **Logged in** → opens the normal drive explorer (browse and pick existing files or upload to their own drive).
+- **Not logged in** → opens the native file picker and uploads anonymously, returning the uploaded `TDriveFile`.
+
+```tsx
+import { useState } from "react";
+import { DriveFileChooser } from "@muhgholy/next-drive/client";
+import type { TDriveFile } from "@muhgholy/next-drive/client";
+
+function GuestForm() {
+	const [file, setFile] = useState<TDriveFile | null>(null);
+
+	return (
+		<DriveFileChooser
+			allowUnauthenticated
+			value={file}
+			onChange={setFile}
+			accept="image/*"
+			placeholder="Upload an attachment"
+		/>
+	);
+}
+```
+
+> `DriveFileChooser` must be inside a `DriveProvider` (it reads `apiEndpoint` and resolves auth from context). The `multiple` and `accept` props work the same as the standard chooser.
+
+### 3. Confirm to keep the file
+
+After you persist the returned `drive.id` (e.g. attach it to a submitted form record), call `driveConfirm` to clear its expiry so it is never auto-deleted:
+
+```typescript
+import { driveConfirm } from "@muhgholy/next-drive/server";
+
+const kept = await driveConfirm(driveFile.id);
+// kept === true if the file exists
+```
+
+**Returns:** `Promise<boolean>` — `true` if the file exists. Safe to call on files uploaded while logged in (they are already permanent, so it is a harmless no-op) — so your form handler can always call `driveConfirm` regardless of whether the visitor was authenticated.
+
+### 4. Purge expired (unconfirmed) files
+
+Run `drivePurgeExpired` on a schedule (cron job or interval) to permanently delete temporary files whose TTL has passed and were never confirmed:
+
+```typescript
+import { drivePurgeExpired } from "@muhgholy/next-drive/server";
+
+// e.g. in a cron route or a setInterval on your server
+const result = await drivePurgeExpired();
+console.log(`Purged ${result.removed.length} expired files, freed ${result.totalFreedInBytes} bytes`);
+```
+
+**Returns:** `{ removed: string[], totalFreedInBytes: number }`
+
+> [!IMPORTANT]
+> Confirmed files are never purged. Only files that are both expired **and** unconfirmed are removed. If you never call `drivePurgeExpired`, temporary files will remain — schedule it (e.g. hourly).
+
+### Determining the client IP (behind a proxy)
+
+Per-IP limits resolve the client IP from `cf-connecting-ip`, then the first entry of `x-forwarded-for`, then the socket address. Override the trusted headers or supply your own resolver:
+
+```typescript
+unauthenticated: {
+	enabled: true,
+	maxUploadSizeInBytes: 25 * 1024 * 1024,
+	allowedMimeTypes: ["image/*"],
+	abuse: {
+		perIp: { windowMinutes: 10, max: 20 },
+		trustedHeaders: ["cf-connecting-ip", "x-forwarded-for"], // checked in order
+		clientId: (req) => (req.headers["cf-connecting-ip"] as string) ?? "unknown", // full override
+	},
+}
+```
+
+> [!WARNING]
+> Only trust forwarded IP headers if every request reaches your origin through a proxy you control (e.g. Cloudflare). If clients can reach the origin directly, these headers can be spoofed — lock your origin down to your proxy's IPs.
+>
+> Abuse counters are kept in-memory per process. In a multi-instance deployment, each instance enforces limits independently; use a shared store (e.g. Redis) if you need cross-instance limits.
+
+---
+
 ## Configuration Options
 
 ### Security
@@ -596,9 +721,35 @@ security: {
 		expiresIn: 3600, // seconds
 	},
 	trash: { retentionDays: 30 },
+	// Anonymous one-time uploads (see "Anonymous (One-Time) Uploads" section)
+	unauthenticated: {
+		enabled: true,
+		ttlMinutes: 60,
+		maxUploadSizeInBytes: 25 * 1024 * 1024,
+		allowedMimeTypes: ['image/*', 'application/pdf'],
+		abuse: {
+			perIp: { windowMinutes: 10, max: 20 },
+			hourlyPerIp: 60,
+			maxConcurrent: 10,
+			maxLiveBytes: 2 * 1024 * 1024 * 1024,
+		},
+	},
 }
 ```
 
+| Option                                | Type       | Default     | Description                                                      |
+| ------------------------------------- | ---------- | ----------- | ---------------------------------------------------------------- |
+| `unauthenticated.enabled`             | `boolean`  | `false`     | Enable anonymous one-time uploads                                |
+| `unauthenticated.ttlMinutes`          | `number`   | `60`        | Minutes before an unconfirmed upload becomes eligible for purge  |
+| `unauthenticated.maxUploadSizeInBytes`| `number`   | —           | Max size per anonymous upload (separate from authenticated)      |
+| `unauthenticated.allowedMimeTypes`    | `string[]` | —           | Allowed MIME types for anonymous uploads                         |
+| `unauthenticated.abuse.perIp`         | `{ windowMinutes, max }` | — | Sliding-window per-IP upload limit                            |
+| `unauthenticated.abuse.hourlyPerIp`   | `number`   | —           | Max anonymous uploads per IP per hour                            |
+| `unauthenticated.abuse.maxConcurrent` | `number`   | —           | Max simultaneous anonymous uploads (global, per process)         |
+| `unauthenticated.abuse.maxLiveBytes`  | `number`   | —           | Max total live temporary storage in bytes (global)              |
+| `unauthenticated.abuse.trustedHeaders`| `string[]` | `['cf-connecting-ip', 'x-forwarded-for']` | Headers checked in order to resolve client IP |
+| `unauthenticated.abuse.clientId`      | `(req) => string` | —    | Full override for resolving the client identifier                |
+
 ### CORS (Cross-Origin)
 
 Required when client and API are on different domains: