@muhgholy/next-drive 4.23.8 → 4.23.11

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:

package/dist/{chunk-RBSFEEJJ.js → chunk-26KZWPCF.js}

@@ -36,6 +36,7 @@ var DriveSchema = new Schema(
     information: { type: informationSchema, required: true },
     status: { type: String, enum: ["READY", "PROCESSING", "UPLOADING", "FAILED"], default: "PROCESSING" },
     trashedAt: { type: Date, default: null },
+    expiresAt: { type: Date, default: null },
     meta: { type: Schema.Types.Mixed, default: {} },
     createdAt: { type: Date, default: Date.now }
   },
@@ -48,6 +49,7 @@ DriveSchema.index({ owner: 1, trashedAt: 1 });
 DriveSchema.index({ owner: 1, "information.hash": 1 });
 DriveSchema.index({ owner: 1, name: "text" });
 DriveSchema.index({ owner: 1, "provider.type": 1 });
+DriveSchema.index({ expiresAt: 1 });
 DriveSchema.method("toClient", async function() {
   const data = this.toJSON();
   return {
@@ -60,6 +62,7 @@ DriveSchema.method("toClient", async function() {
     information: data.information,
     status: data.status,
     trashedAt: data.trashedAt,
+    expiresAt: data.expiresAt,
     meta: data.meta,
     createdAt: data.createdAt
   };
@@ -246,7 +249,8 @@ var getGlobal = () => {
     globalThis[GLOBAL_KEY] = {
       config: null,
       migrationPromise: null,
-      initialized: false
+      initialized: false,
+      abuse: { ipHits: /* @__PURE__ */ new Map(), concurrent: 0 }
     };
   }
   return globalThis[GLOBAL_KEY];
@@ -275,7 +279,8 @@ var driveConfiguration = async (config) => {
         // 10GB default for ROOT
         allowedMimeTypes: config.security?.allowedMimeTypes ?? ["*/*"],
         signedUrls: config.security?.signedUrls,
-        trash: config.security?.trash
+        trash: config.security?.trash,
+        unauthenticated: config.security?.unauthenticated
       }
     };
   } else {
@@ -293,7 +298,8 @@ var driveConfiguration = async (config) => {
         maxUploadSizeInBytes: config.security?.maxUploadSizeInBytes ?? 10 * 1024 * 1024,
         allowedMimeTypes: config.security?.allowedMimeTypes ?? ["*/*"],
         signedUrls: config.security?.signedUrls,
-        trash: config.security?.trash
+        trash: config.security?.trash,
+        unauthenticated: config.security?.unauthenticated
       },
       information: config.information
     };
@@ -1527,7 +1533,8 @@ var uploadChunkSchema = z.object({
   fileName: nameSchema,
   fileSize: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
   fileType: z.string().min(1).max(255),
-  folderId: z.string().optional()
+  folderId: z.string().optional(),
+  unauthenticated: z.coerce.boolean().optional()
 }).refine((data) => data.chunkIndex < data.totalChunks, {
   message: "Chunk index must be less than total chunks"
 });
@@ -2121,6 +2128,26 @@ var driveCleanup = async () => {
   }
   return { removed, totalFreedInBytes };
 };
+var driveConfirm = async (id) => {
+  const result = await drive_default.updateOne({ _id: id }, { $set: { expiresAt: null } });
+  return result.matchedCount > 0;
+};
+var drivePurgeExpired = async () => {
+  const expired = await drive_default.find({ expiresAt: { $ne: null, $lt: /* @__PURE__ */ new Date() } });
+  const removed = [];
+  let totalFreedInBytes = 0;
+  for (const drive of expired) {
+    const id = String(drive._id);
+    try {
+      await driveDelete(drive);
+      totalFreedInBytes += drive.information.type === "FILE" ? drive.information.sizeInBytes : 0;
+      removed.push(id);
+    } catch (e) {
+      console.error(`[next-drive] Failed to purge expired file ${id}:`, e);
+    }
+  }
+  return { removed, totalFreedInBytes };
+};
 
 // src/server/actions/shared.ts
 var resolveProvider = async (req, owner) => {
@@ -2146,7 +2173,7 @@ var withSignedUrls = (items, config) => {
 
 // src/server/actions/drive.ts
 var handleDriveAction = async (ctx) => {
-  const { req, res, action, config, owner, isRootMode, information, provider, accountId } = ctx;
+  const { req, res, action, config, owner, isRootMode, authenticated, information, provider, accountId } = ctx;
   switch (action) {
     case "list": {
       if (req.method !== "GET") return void res.status(405).json({ status: 405, message: "Listing files requires a GET request" });
@@ -2235,36 +2262,87 @@ var handleDriveAction = async (ctx) => {
         cleanupTempFiles(files);
         return void res.status(400).json({ status: 400, message: uploadData.error.errors[0].message });
       }
-      const { chunkIndex, totalChunks, driveId, fileName, fileSize: fileSizeInBytes, fileType, folderId } = uploadData.data;
+      const { chunkIndex, totalChunks, driveId, fileName, fileSize: fileSizeInBytes, fileType, folderId, unauthenticated } = uploadData.data;
       let currentUploadId = driveId;
       const tempBaseDir = path.join(os2.tmpdir(), "next-drive-uploads");
       if (!currentUploadId) {
         if (chunkIndex !== 0) return void res.status(400).json({ message: "Could not upload: missing upload session for this chunk" });
-        if (fileType && config.security) {
-          if (!validateMimeType(fileType, config.security.allowedMimeTypes)) {
+        if (unauthenticated) {
+          const unauth = config.security?.unauthenticated;
+          if (!unauth?.enabled) {
+            cleanupTempFiles(files);
+            return void res.status(403).json({ status: 403, message: "Anonymous uploads are not enabled" });
+          }
+          if (fileSizeInBytes > unauth.maxUploadSizeInBytes) {
+            cleanupTempFiles(files);
+            return void res.status(413).json({ status: 413, message: "Could not upload: file exceeds the maximum allowed size" });
+          }
+          if (fileType && !validateMimeType(fileType, unauth.allowedMimeTypes)) {
             cleanupTempFiles(files);
             return void res.status(400).json({ status: 400, message: `Could not upload: file type "${fileType}" is not allowed` });
           }
-        }
-        if (!isRootMode) {
-          const quota = await provider.getQuota(owner, accountId, information.storage.quotaInBytes);
-          if (quota.usedInBytes + fileSizeInBytes > quota.quotaInBytes) {
+          const abuse = unauth.abuse;
+          if (abuse) {
+            const store = globalThis.__nextDrive.abuse;
+            const now = Date.now();
+            const ip = abuse.clientId?.(req) ?? (abuse.trustedHeaders ?? ["cf-connecting-ip", "x-forwarded-for"]).map((h) => req.headers[h]).find(Boolean)?.split(",")[0].trim() ?? req.socket.remoteAddress ?? "unknown";
+            const hits = (store.ipHits.get(ip) ?? []).filter((t) => now - t < 36e5);
+            const perIp = abuse.perIp;
+            if (perIp && hits.filter((t) => now - t < perIp.windowMinutes * 6e4).length >= perIp.max) {
+              cleanupTempFiles(files);
+              return void res.status(429).json({ status: 429, message: "Too many uploads, please try again later" });
+            }
+            if (abuse.hourlyPerIp && hits.length >= abuse.hourlyPerIp) {
+              cleanupTempFiles(files);
+              return void res.status(429).json({ status: 429, message: "Hourly upload limit reached, please try again later" });
+            }
+            if (abuse.maxConcurrent && store.concurrent >= abuse.maxConcurrent) {
+              cleanupTempFiles(files);
+              return void res.status(429).json({ status: 429, message: "Server is busy with uploads, please try again later" });
+            }
+            if (abuse.maxLiveBytes) {
+              const [agg] = await drive_default.aggregate([{ $match: { expiresAt: { $ne: null } } }, { $group: { _id: null, total: { $sum: "$information.sizeInBytes" } } }]);
+              if ((agg?.total ?? 0) + fileSizeInBytes > abuse.maxLiveBytes) {
+                cleanupTempFiles(files);
+                return void res.status(429).json({ status: 429, message: "Temporary storage is full, please try again later" });
+              }
+            }
+            hits.push(now);
+            store.ipHits.set(ip, hits);
+            store.concurrent++;
+          }
+        } else {
+          if (!authenticated) {
             cleanupTempFiles(files);
-            return void res.status(413).json({ status: 413, message: "Could not upload: you have run out of storage space" });
+            return void res.status(401).json({ status: 401, message: "Authentication required to upload" });
+          }
+          if (fileType && config.security) {
+            if (!validateMimeType(fileType, config.security.allowedMimeTypes)) {
+              cleanupTempFiles(files);
+              return void res.status(400).json({ status: 400, message: `Could not upload: file type "${fileType}" is not allowed` });
+            }
+          }
+          if (!isRootMode) {
+            const quota = await provider.getQuota(owner, accountId, information.storage.quotaInBytes);
+            if (quota.usedInBytes + fileSizeInBytes > quota.quotaInBytes) {
+              cleanupTempFiles(files);
+              return void res.status(413).json({ status: 413, message: "Could not upload: you have run out of storage space" });
+            }
           }
         }
         currentUploadId = crypto3.randomUUID();
         const uploadDir2 = path.join(tempBaseDir, currentUploadId);
         fs.mkdirSync(uploadDir2, { recursive: true });
         const metadata = {
-          owner,
-          accountId,
+          owner: unauthenticated ? null : owner,
+          accountId: unauthenticated ? null : accountId,
           providerName: provider.name,
           name: fileName,
-          parentId: folderId === "root" || !folderId ? null : folderId,
+          parentId: unauthenticated || folderId === "root" || !folderId ? null : folderId,
           fileSize: fileSizeInBytes,
           mimeType: fileType,
-          totalChunks
+          totalChunks,
+          unauthenticated: !!unauthenticated
         };
         fs.writeFileSync(path.join(uploadDir2, "metadata.json"), JSON.stringify(metadata));
       }
@@ -2350,7 +2428,8 @@ var handleDriveAction = async (ctx) => {
             information: { type: "FILE", sizeInBytes: meta.fileSize, mime: meta.mimeType, path: "" },
             status: "UPLOADING",
             currentChunk: totalChunks,
-            totalChunks
+            totalChunks,
+            expiresAt: meta.unauthenticated ? new Date(Date.now() + (config.security?.unauthenticated?.ttlMinutes ?? 60) * 6e4) : null
           });
           if (meta.providerName === "LOCAL" && drive.information.type === "FILE") {
             drive.information.path = path.join("file", String(drive._id), "data.bin");
@@ -2359,10 +2438,12 @@ var handleDriveAction = async (ctx) => {
           try {
             const item = await provider.uploadFile(drive, finalTempPath, meta.accountId);
             fs.rmSync(uploadDir, { recursive: true, force: true });
+            if (meta.unauthenticated) globalThis.__nextDrive.abuse.concurrent = Math.max(0, globalThis.__nextDrive.abuse.concurrent - 1);
             const newQuota = await provider.getQuota(meta.owner, meta.accountId, information.storage.quotaInBytes);
             res.status(200).json({ status: 200, message: "Upload complete", data: { type: "UPLOAD_COMPLETE", driveId: String(drive._id), item: withSignedUrl(item, config) }, statistic: { storage: newQuota } });
           } catch (err) {
             await drive_default.deleteOne({ _id: drive._id });
+            if (meta.unauthenticated) globalThis.__nextDrive.abuse.concurrent = Math.max(0, globalThis.__nextDrive.abuse.concurrent - 1);
             throw err;
           }
         } else {
@@ -2386,6 +2467,10 @@ var handleDriveAction = async (ctx) => {
       const tempUploadDir = path.join(os2.tmpdir(), "next-drive-uploads", id);
       if (fs.existsSync(tempUploadDir)) {
         try {
+          const metaPath = path.join(tempUploadDir, "metadata.json");
+          if (fs.existsSync(metaPath) && JSON.parse(fs.readFileSync(metaPath, "utf-8")).unauthenticated) {
+            globalThis.__nextDrive.abuse.concurrent = Math.max(0, globalThis.__nextDrive.abuse.concurrent - 1);
+          }
           fs.rmSync(tempUploadDir, { recursive: true, force: true });
         } catch (e) {
           console.error("Failed to cleanup temp upload:", e);
@@ -2592,12 +2677,16 @@ var driveAPIHandler = async (req, res) => {
   if (wasPublicHandled) return;
   try {
     const mode = config.mode || "NORMAL";
-    const information = await getDriveInformation({ method: "REQUEST", req });
-    const { key: owner } = information;
-    const isRootMode = mode === "ROOT";
     if (action === "information") {
       const { clientId, clientSecret, redirectUri } = config.storage?.google || {};
       const googleConfigured = !!(clientId && clientSecret && redirectUri);
+      let authenticated2 = false;
+      try {
+        await getDriveInformation({ method: "REQUEST", req });
+        authenticated2 = true;
+      } catch {
+        authenticated2 = false;
+      }
       res.status(200).json({
         status: 200,
         message: "Information retrieved",
@@ -2605,11 +2694,27 @@ var driveAPIHandler = async (req, res) => {
           providers: {
             google: googleConfigured
           },
-          mode
+          mode,
+          authenticated: authenticated2,
+          unauthenticatedUploads: !!config.security?.unauthenticated?.enabled
         }
       });
       return;
     }
+    const isRootMode = mode === "ROOT";
+    let information;
+    let authenticated = true;
+    try {
+      information = await getDriveInformation({ method: "REQUEST", req });
+    } catch (err) {
+      if ((action === "upload" || action === "cancel") && config.security?.unauthenticated?.enabled) {
+        information = { key: null, storage: { quotaInBytes: 0 } };
+        authenticated = false;
+      } else {
+        throw err;
+      }
+    }
+    const { key: owner } = information;
     const wasAuthHandled = await handleAuthAction(req, res, action, config, owner);
     if (wasAuthHandled) return;
     const { provider, accountId } = await resolveProvider(req, owner);
@@ -2620,6 +2725,7 @@ var driveAPIHandler = async (req, res) => {
       config,
       owner,
       isRootMode,
+      authenticated,
       information,
       provider,
       accountId
@@ -2631,6 +2737,6 @@ var driveAPIHandler = async (req, res) => {
   }
 };
 
-export { driveAPIHandler, driveCleanup, driveConfiguration, driveDelete, driveFilePath, driveFileSchemaZod, driveGetUrl, driveInfo, driveList, driveListFiles, driveReadFile, driveUpload, drive_default, getDriveConfig, getDriveInformation };
-//# sourceMappingURL=chunk-RBSFEEJJ.js.map
-//# sourceMappingURL=chunk-RBSFEEJJ.js.map
+export { driveAPIHandler, driveCleanup, driveConfiguration, driveConfirm, driveDelete, driveFilePath, driveFileSchemaZod, driveGetUrl, driveInfo, driveList, driveListFiles, drivePurgeExpired, driveReadFile, driveUpload, drive_default, getDriveConfig, getDriveInformation };
+//# sourceMappingURL=chunk-26KZWPCF.js.map
+//# sourceMappingURL=chunk-26KZWPCF.js.map