hazo_files 1.5.2 → 1.6.0

package/dist/server/index.mjs

@@ -5,6 +5,11 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
+// src/services/tracked-file-manager.ts
+import * as fs3 from "fs";
+import * as os from "os";
+import * as path3 from "path";
+
 // src/config/index.ts
 import * as ini from "ini";
 import * as fs from "fs";
@@ -172,63 +177,63 @@ var HazoFilesError = class extends Error {
   }
 };
 var FileNotFoundError = class extends HazoFilesError {
-  constructor(path3) {
-    super(`File not found: ${path3}`, "FILE_NOT_FOUND", { path: path3 });
+  constructor(path4) {
+    super(`File not found: ${path4}`, "FILE_NOT_FOUND", { path: path4 });
     this.name = "FileNotFoundError";
   }
 };
 var DirectoryNotFoundError = class extends HazoFilesError {
-  constructor(path3) {
-    super(`Directory not found: ${path3}`, "DIRECTORY_NOT_FOUND", { path: path3 });
+  constructor(path4) {
+    super(`Directory not found: ${path4}`, "DIRECTORY_NOT_FOUND", { path: path4 });
     this.name = "DirectoryNotFoundError";
   }
 };
 var FileExistsError = class extends HazoFilesError {
-  constructor(path3) {
-    super(`File already exists: ${path3}`, "FILE_EXISTS", { path: path3 });
+  constructor(path4) {
+    super(`File already exists: ${path4}`, "FILE_EXISTS", { path: path4 });
     this.name = "FileExistsError";
   }
 };
 var DirectoryExistsError = class extends HazoFilesError {
-  constructor(path3) {
-    super(`Directory already exists: ${path3}`, "DIRECTORY_EXISTS", { path: path3 });
+  constructor(path4) {
+    super(`Directory already exists: ${path4}`, "DIRECTORY_EXISTS", { path: path4 });
     this.name = "DirectoryExistsError";
   }
 };
 var DirectoryNotEmptyError = class extends HazoFilesError {
-  constructor(path3) {
-    super(`Directory is not empty: ${path3}`, "DIRECTORY_NOT_EMPTY", { path: path3 });
+  constructor(path4) {
+    super(`Directory is not empty: ${path4}`, "DIRECTORY_NOT_EMPTY", { path: path4 });
     this.name = "DirectoryNotEmptyError";
   }
 };
 var PermissionDeniedError = class extends HazoFilesError {
-  constructor(path3, operation) {
-    super(`Permission denied for ${operation} on: ${path3}`, "PERMISSION_DENIED", { path: path3, operation });
+  constructor(path4, operation) {
+    super(`Permission denied for ${operation} on: ${path4}`, "PERMISSION_DENIED", { path: path4, operation });
     this.name = "PermissionDeniedError";
   }
 };
 var InvalidPathError = class extends HazoFilesError {
-  constructor(path3, reason) {
-    super(`Invalid path "${path3}": ${reason}`, "INVALID_PATH", { path: path3, reason });
+  constructor(path4, reason) {
+    super(`Invalid path "${path4}": ${reason}`, "INVALID_PATH", { path: path4, reason });
     this.name = "InvalidPathError";
   }
 };
 var FileTooLargeError = class extends HazoFilesError {
-  constructor(path3, size, maxSize) {
+  constructor(path4, size, maxSize) {
     super(
-      `File "${path3}" is too large (${size} bytes). Maximum allowed: ${maxSize} bytes`,
+      `File "${path4}" is too large (${size} bytes). Maximum allowed: ${maxSize} bytes`,
       "FILE_TOO_LARGE",
-      { path: path3, size, maxSize }
+      { path: path4, size, maxSize }
     );
     this.name = "FileTooLargeError";
   }
 };
 var InvalidExtensionError = class extends HazoFilesError {
-  constructor(path3, extension, allowedExtensions) {
+  constructor(path4, extension, allowedExtensions) {
     super(
       `File extension "${extension}" is not allowed. Allowed: ${allowedExtensions.join(", ")}`,
       "INVALID_EXTENSION",
-      { path: path3, extension, allowedExtensions }
+      { path: path4, extension, allowedExtensions }
     );
     this.name = "InvalidExtensionError";
   }
@@ -251,6 +256,32 @@ var OperationError = class extends HazoFilesError {
     this.name = "OperationError";
   }
 };
+var QuotaExceededError = class extends HazoFilesError {
+  constructor(scopeId, byteUsed, byteLimit, deltaBytes) {
+    super(
+      `Quota exceeded for scope ${scopeId}: would use ${byteUsed + deltaBytes} of ${byteLimit} bytes`,
+      "QUOTA_EXCEEDED",
+      { scopeId, byteUsed, byteLimit, deltaBytes }
+    );
+    this.name = "QuotaExceededError";
+  }
+};
+var SSRFError = class extends HazoFilesError {
+  constructor(url, reason) {
+    super(`SSRF check failed for URL "${url}": ${reason}`, "SSRF_ERROR", { url, reason });
+    this.name = "SSRFError";
+  }
+};
+var ImportSizeCapError = class extends HazoFilesError {
+  constructor(url, capBytes) {
+    super(
+      `Import from "${url}" aborted: response exceeds ${capBytes} byte limit`,
+      "IMPORT_SIZE_CAP",
+      { url, capBytes }
+    );
+    this.name = "ImportSizeCapError";
+  }
+};
 
 // src/common/utils.ts
 function successResult(data) {
@@ -494,10 +525,10 @@ var BaseStorageModule = class {
    * Get folder tree structure.
    * Default implementation that can be overridden by subclasses for optimization.
    */
-  async getFolderTree(path3 = "/", depth = 3) {
+  async getFolderTree(path4 = "/", depth = 3) {
     this.ensureInitialized();
     try {
-      const result = await this.buildTree(path3, depth, 0);
+      const result = await this.buildTree(path4, depth, 0);
       return successResult(result);
     } catch (error) {
       return errorResult(`Failed to get folder tree: ${error.message}`);
@@ -506,11 +537,11 @@ var BaseStorageModule = class {
   /**
    * Recursively build folder tree
    */
-  async buildTree(path3, maxDepth, currentDepth) {
+  async buildTree(path4, maxDepth, currentDepth) {
     if (currentDepth >= maxDepth) {
       return [];
     }
-    const listResult = await this.listDirectory(path3, { recursive: false });
+    const listResult = await this.listDirectory(path4, { recursive: false });
     if (!listResult.success || !listResult.data) {
       return [];
     }
@@ -1329,12 +1360,12 @@ var GoogleDriveModule = class extends BaseStorageModule {
    */
   driveFileToItem(file, virtualPath) {
     const isFolder2 = file.mimeType === FOLDER_MIME_TYPE;
-    const path3 = virtualPath || "";
+    const path4 = virtualPath || "";
     if (isFolder2) {
       return createFolderItem({
         id: file.id,
         name: file.name,
-        path: path3,
+        path: path4,
         createdAt: file.createdTime ? new Date(file.createdTime) : /* @__PURE__ */ new Date(),
         modifiedAt: file.modifiedTime ? new Date(file.modifiedTime) : /* @__PURE__ */ new Date(),
         metadata: {
@@ -1346,7 +1377,7 @@ var GoogleDriveModule = class extends BaseStorageModule {
     return createFileItem({
       id: file.id,
       name: file.name,
-      path: path3,
+      path: path4,
       size: parseInt(file.size || "0", 10),
       mimeType: file.mimeType || "application/octet-stream",
       createdAt: file.createdTime ? new Date(file.createdTime) : /* @__PURE__ */ new Date(),
@@ -1445,10 +1476,10 @@ var GoogleDriveModule = class extends BaseStorageModule {
       }
       let media;
       if (typeof source === "string") {
-        const fs3 = await import("fs");
+        const fs4 = await import("fs");
         media = {
           mimeType: "application/octet-stream",
-          body: fs3.createReadStream(source)
+          body: fs4.createReadStream(source)
         };
       } else if (Buffer.isBuffer(source)) {
         media = {
@@ -1497,10 +1528,10 @@ var GoogleDriveModule = class extends BaseStorageModule {
         options.onProgress(100, buffer.length, buffer.length);
       }
       if (localPath) {
-        const fs3 = await import("fs");
-        const path3 = await import("path");
-        await fs3.promises.mkdir(path3.dirname(localPath), { recursive: true });
-        await fs3.promises.writeFile(localPath, buffer);
+        const fs4 = await import("fs");
+        const path4 = await import("path");
+        await fs4.promises.mkdir(path4.dirname(localPath), { recursive: true });
+        await fs4.promises.writeFile(localPath, buffer);
         return this.successResult(localPath);
       }
       return this.successResult(buffer);
@@ -1688,10 +1719,10 @@ var GoogleDriveModule = class extends BaseStorageModule {
       return false;
     }
   }
-  async getFolderTree(path3 = "/", depth = 3) {
+  async getFolderTree(path4 = "/", depth = 3) {
     try {
       await this.ensureAuthenticated();
-      return super.getFolderTree(path3, depth);
+      return super.getFolderTree(path4, depth);
     } catch (error) {
       return this.errorResult(`Failed to get folder tree: ${error.message}`);
     }
@@ -1982,12 +2013,12 @@ var DropboxModule = class extends BaseStorageModule {
    */
   metadataToItem(entry, virtualPath) {
     const isFolder2 = entry[".tag"] === "folder";
-    const path3 = virtualPath || this.toVirtualPath(entry.path_display || entry.name);
+    const path4 = virtualPath || this.toVirtualPath(entry.path_display || entry.name);
     if (isFolder2) {
       return createFolderItem({
         id: entry.id,
         name: entry.name,
-        path: path3,
+        path: path4,
         createdAt: /* @__PURE__ */ new Date(),
         modifiedAt: /* @__PURE__ */ new Date(),
         metadata: {
@@ -2000,7 +2031,7 @@ var DropboxModule = class extends BaseStorageModule {
     return createFileItem({
       id: fileEntry.id,
       name: fileEntry.name,
-      path: path3,
+      path: path4,
       size: fileEntry.size,
       mimeType: getMimeType(fileEntry.name),
       createdAt: new Date(fileEntry.client_modified),
@@ -2076,8 +2107,8 @@ var DropboxModule = class extends BaseStorageModule {
       const dbxPath = this.toDropboxPath(remotePath);
       let contents;
       if (typeof source === "string") {
-        const fs3 = await import("fs");
-        contents = await fs3.promises.readFile(source);
+        const fs4 = await import("fs");
+        contents = await fs4.promises.readFile(source);
       } else if (Buffer.isBuffer(source)) {
         contents = source;
       } else {
@@ -2146,10 +2177,10 @@ var DropboxModule = class extends BaseStorageModule {
         options.onProgress(100, buffer.length, buffer.length);
       }
       if (localPath) {
-        const fs3 = await import("fs");
-        const path3 = await import("path");
-        await fs3.promises.mkdir(path3.dirname(localPath), { recursive: true });
-        await fs3.promises.writeFile(localPath, buffer);
+        const fs4 = await import("fs");
+        const path4 = await import("path");
+        await fs4.promises.mkdir(path4.dirname(localPath), { recursive: true });
+        await fs4.promises.writeFile(localPath, buffer);
         return this.successResult(localPath);
       }
       return this.successResult(buffer);
@@ -2318,10 +2349,10 @@ var DropboxModule = class extends BaseStorageModule {
       return false;
     }
   }
-  async getFolderTree(path3 = "/", depth = 3) {
+  async getFolderTree(path4 = "/", depth = 3) {
     try {
       await this.ensureAuthenticated();
-      return super.getFolderTree(path3, depth);
+      return super.getFolderTree(path4, depth);
     } catch (error) {
       return this.errorResult(`Failed to get folder tree: ${error.message}`);
     }
@@ -2440,13 +2471,13 @@ var FileManager = class {
   /**
    * Create a directory at the specified path
    */
-  async createDirectory(path3) {
+  async createDirectory(path4) {
     this.ensureInitialized();
     const start = Date.now();
-    const result = await this.module.createDirectory(path3);
+    const result = await this.module.createDirectory(path4);
     this.logFileOp(result.success ? "info" : "error", {
       operation: "upload",
-      file_path: path3,
+      file_path: path4,
       mime_type: "folder",
       storage: this.config?.provider,
       duration_ms: Date.now() - start,
@@ -2461,13 +2492,13 @@ var FileManager = class {
    * @param path - Directory path
    * @param recursive - If true, remove directory and all contents
    */
-  async removeDirectory(path3, recursive = false) {
+  async removeDirectory(path4, recursive = false) {
     this.ensureInitialized();
     const start = Date.now();
-    const result = await this.module.removeDirectory(path3, recursive);
+    const result = await this.module.removeDirectory(path4, recursive);
     this.logFileOp(result.success ? "info" : "error", {
       operation: "delete",
-      file_path: path3,
+      file_path: path4,
       mime_type: "folder",
       storage: this.config?.provider,
       duration_ms: Date.now() - start,
@@ -2546,13 +2577,13 @@ var FileManager = class {
   /**
    * Delete a file
    */
-  async deleteFile(path3) {
+  async deleteFile(path4) {
     this.ensureInitialized();
     const start = Date.now();
-    const result = await this.module.deleteFile(path3);
+    const result = await this.module.deleteFile(path4);
     this.logFileOp(result.success ? "info" : "error", {
       operation: "delete",
-      file_path: path3,
+      file_path: path4,
       storage: this.config?.provider,
       duration_ms: Date.now() - start,
       success: result.success,
@@ -2566,14 +2597,14 @@ var FileManager = class {
    * @param newName - New filename (not full path)
    * @param options - Rename options
    */
-  async renameFile(path3, newName, options) {
+  async renameFile(path4, newName, options) {
     this.ensureInitialized();
     const start = Date.now();
-    const result = await this.module.renameFile(path3, newName, options);
+    const result = await this.module.renameFile(path4, newName, options);
     this.logFileOp(result.success ? "info" : "error", {
       operation: "move",
       file_name: result.data?.name,
-      file_path: path3,
+      file_path: path4,
       storage: this.config?.provider,
       duration_ms: Date.now() - start,
       success: result.success,
@@ -2588,14 +2619,14 @@ var FileManager = class {
    * @param newName - New folder name (not full path)
    * @param options - Rename options
    */
-  async renameFolder(path3, newName, options) {
+  async renameFolder(path4, newName, options) {
     this.ensureInitialized();
     const start = Date.now();
-    const result = await this.module.renameFolder(path3, newName, options);
+    const result = await this.module.renameFolder(path4, newName, options);
     this.logFileOp(result.success ? "info" : "error", {
       operation: "move",
       file_name: result.data?.name,
-      file_path: path3,
+      file_path: path4,
       storage: this.config?.provider,
       duration_ms: Date.now() - start,
       success: result.success,
@@ -2610,54 +2641,54 @@ var FileManager = class {
    * @param path - Directory path
    * @param options - List options
    */
-  async listDirectory(path3, options) {
+  async listDirectory(path4, options) {
     this.ensureInitialized();
-    return this.module.listDirectory(path3, options);
+    return this.module.listDirectory(path4, options);
   }
   /**
    * Get information about a file or folder
    */
-  async getItem(path3) {
+  async getItem(path4) {
     this.ensureInitialized();
-    return this.module.getItem(path3);
+    return this.module.getItem(path4);
   }
   /**
    * Check if a file or folder exists
    */
-  async exists(path3) {
+  async exists(path4) {
     this.ensureInitialized();
-    return this.module.exists(path3);
+    return this.module.exists(path4);
   }
   /**
    * Get folder tree structure
    * @param path - Starting path (default: root)
    * @param depth - Maximum depth to traverse
    */
-  async getFolderTree(path3 = "/", depth = 3) {
+  async getFolderTree(path4 = "/", depth = 3) {
     this.ensureInitialized();
-    return this.module.getFolderTree(path3, depth);
+    return this.module.getFolderTree(path4, depth);
   }
   // ============ Convenience Methods ============
   /**
    * Create a file with string content
    */
-  async writeFile(path3, content, options) {
+  async writeFile(path4, content, options) {
     const buffer = Buffer.from(content, "utf-8");
-    return this.uploadFile(buffer, path3, options);
+    return this.uploadFile(buffer, path4, options);
   }
   /**
    * Read a file as string
    */
-  async readFile(path3) {
-    const result = await this.downloadFile(path3);
+  async readFile(path4) {
+    const result = await this.downloadFile(path4);
     if (!result.success) {
       return { success: false, error: result.error };
     }
     if (Buffer.isBuffer(result.data)) {
       return { success: true, data: result.data.toString("utf-8") };
     }
-    const fs3 = await import("fs");
-    const content = await fs3.promises.readFile(result.data, "utf-8");
+    const fs4 = await import("fs");
+    const content = await fs4.promises.readFile(result.data, "utf-8");
     return { success: true, data: content };
   }
   /**
@@ -2668,22 +2699,22 @@ var FileManager = class {
     if (!downloadResult.success) {
       return { success: false, error: downloadResult.error };
     }
-    const buffer = Buffer.isBuffer(downloadResult.data) ? downloadResult.data : await import("fs").then((fs3) => fs3.promises.readFile(downloadResult.data));
+    const buffer = Buffer.isBuffer(downloadResult.data) ? downloadResult.data : await import("fs").then((fs4) => fs4.promises.readFile(downloadResult.data));
     return this.uploadFile(buffer, destinationPath, options);
   }
   /**
    * Ensure a directory exists (creates if needed)
    */
-  async ensureDirectory(path3) {
-    const exists = await this.exists(path3);
+  async ensureDirectory(path4) {
+    const exists = await this.exists(path4);
     if (exists) {
-      const item = await this.getItem(path3);
+      const item = await this.getItem(path4);
       if (item.success && item.data?.isDirectory) {
         return { success: true, data: item.data };
       }
       return { success: false, error: "Path exists but is not a directory" };
     }
-    return this.createDirectory(path3);
+    return this.createDirectory(path4);
   }
 };
 function createFileManager(options) {
@@ -2996,6 +3027,8 @@ var FileMetadataService = class {
       if (input.uploaded_by !== void 0) record.uploaded_by = input.uploaded_by;
       if (input.original_filename !== void 0) record.original_filename = input.original_filename;
       if (input.content_tag !== void 0) record.content_tag = input.content_tag;
+      if (input.changed_by !== void 0) record.changed_by = input.changed_by;
+      if (input.source_url !== void 0) record.source_url = input.source_url;
       const results = await this.crud.insert(record);
       const duration_ms = Date.now() - start;
       this.logger?.debug?.("Recorded file upload", { path: input.file_path });
@@ -3028,32 +3061,32 @@ var FileMetadataService = class {
   /**
    * Record a directory creation
    */
-  async recordDirectoryCreation(path3, storageType, metadata) {
+  async recordDirectoryCreation(path4, storageType, metadata) {
     return this.recordUpload({
-      filename: getBaseName(path3),
+      filename: getBaseName(path4),
       file_type: "folder",
       file_data: metadata,
-      file_path: path3,
+      file_path: path4,
       storage_type: storageType
     });
   }
   /**
    * Record a file access (download)
    */
-  async recordAccess(path3, storageType) {
+  async recordAccess(path4, storageType) {
     const start = Date.now();
     try {
-      const existing = await this.findByPath(path3, storageType);
+      const existing = await this.findByPath(path4, storageType);
       if (existing) {
         await this.crud.updateById(existing.id, {
           changed_at: this.now()
         });
         const duration_ms = Date.now() - start;
-        this.logger?.debug?.("Recorded file access", { path: path3 });
+        this.logger?.debug?.("Recorded file access", { path: path4 });
         this.logger?.info?.("file_operation", {
           operation: "download",
           file_name: existing.filename,
-          file_path: path3,
+          file_path: path4,
           mime_type: existing.file_type,
           size_bytes: existing.file_size,
           storage: storageType,
@@ -3067,7 +3100,7 @@ var FileMetadataService = class {
       const duration_ms = Date.now() - start;
       this.logger?.error?.("file_operation", {
         operation: "download",
-        file_path: path3,
+        file_path: path4,
         storage: storageType,
         duration_ms,
         success: false,
@@ -3079,19 +3112,20 @@ var FileMetadataService = class {
   }
   /**
    * Record a file deletion
+   * changedBy is accepted for API consistency but not written (record is deleted)
    */
-  async recordDelete(path3, storageType) {
+  async recordDelete(path4, storageType, _changedBy) {
     const start = Date.now();
     try {
-      const existing = await this.findByPath(path3, storageType);
+      const existing = await this.findByPath(path4, storageType);
       if (existing) {
         await this.crud.deleteById(existing.id);
         const duration_ms = Date.now() - start;
-        this.logger?.debug?.("Recorded file deletion", { path: path3 });
+        this.logger?.debug?.("Recorded file deletion", { path: path4 });
         this.logger?.info?.("file_operation", {
           operation: "delete",
           file_name: existing.filename,
-          file_path: path3,
+          file_path: path4,
           mime_type: existing.file_type,
           size_bytes: existing.file_size,
           storage: storageType,
@@ -3105,7 +3139,7 @@ var FileMetadataService = class {
       const duration_ms = Date.now() - start;
       this.logger?.error?.("file_operation", {
         operation: "delete",
-        file_path: path3,
+        file_path: path4,
         storage: storageType,
         duration_ms,
         success: false,
@@ -3118,23 +3152,23 @@ var FileMetadataService = class {
   /**
    * Record a directory deletion (recursive)
    */
-  async recordDirectoryDelete(path3, storageType, recursive) {
+  async recordDirectoryDelete(path4, storageType, recursive) {
     try {
       if (recursive) {
         const records = await this.crud.findBy({ storage_type: storageType });
         const toDelete = records.filter(
-          (r) => r.file_path === path3 || r.file_path.startsWith(path3 + "/")
+          (r) => r.file_path === path4 || r.file_path.startsWith(path4 + "/")
         );
         for (const record of toDelete) {
           await this.crud.deleteById(record.id);
         }
         this.logger?.debug?.("Recorded recursive directory deletion", {
-          path: path3,
+          path: path4,
           count: toDelete.length
         });
         return true;
       } else {
-        return this.recordDelete(path3, storageType);
+        return this.recordDelete(path4, storageType);
       }
     } catch (error) {
       this.logError("recordDirectoryDelete", error);
@@ -3144,16 +3178,18 @@ var FileMetadataService = class {
   /**
    * Record a file or folder move
    */
-  async recordMove(sourcePath, destinationPath, storageType) {
+  async recordMove(sourcePath, destinationPath, storageType, changedBy) {
     const start = Date.now();
     try {
       const existing = await this.findByPath(sourcePath, storageType);
       if (existing) {
-        await this.crud.updateById(existing.id, {
+        const patch = {
           file_path: destinationPath,
           filename: getBaseName(destinationPath),
           changed_at: this.now()
-        });
+        };
+        if (changedBy !== void 0) patch.changed_by = changedBy;
+        await this.crud.updateById(existing.id, patch);
         const duration_ms = Date.now() - start;
         this.logger?.debug?.("Recorded file move", { from: sourcePath, to: destinationPath });
         this.logger?.info?.("file_operation", {
@@ -3187,24 +3223,26 @@ var FileMetadataService = class {
   /**
    * Record a file or folder rename
    */
-  async recordRename(path3, newName, storageType) {
+  async recordRename(path4, newName, storageType, changedBy) {
     const start = Date.now();
     try {
-      const existing = await this.findByPath(path3, storageType);
+      const existing = await this.findByPath(path4, storageType);
       if (existing) {
-        const parentPath = getDirName(path3);
+        const parentPath = getDirName(path4);
         const newPath = parentPath === "/" ? `/${newName}` : `${parentPath}/${newName}`;
-        await this.crud.updateById(existing.id, {
+        const patch = {
           filename: newName,
           file_path: newPath,
           changed_at: this.now()
-        });
+        };
+        if (changedBy !== void 0) patch.changed_by = changedBy;
+        await this.crud.updateById(existing.id, patch);
         const duration_ms = Date.now() - start;
-        this.logger?.debug?.("Recorded file rename", { path: path3, newName });
+        this.logger?.debug?.("Recorded file rename", { path: path4, newName });
         this.logger?.info?.("file_operation", {
           operation: "move",
           file_name: existing.filename,
-          file_path: path3,
+          file_path: path4,
           mime_type: existing.file_type,
           size_bytes: existing.file_size,
           storage: storageType,
@@ -3219,7 +3257,7 @@ var FileMetadataService = class {
       const duration_ms = Date.now() - start;
       this.logger?.error?.("file_operation", {
         operation: "move",
-        file_path: path3,
+        file_path: path4,
         storage: storageType,
         duration_ms,
         success: false,
@@ -3233,10 +3271,10 @@ var FileMetadataService = class {
   /**
    * Find a record by path and storage type
    */
-  async findByPath(path3, storageType) {
+  async findByPath(path4, storageType) {
     try {
       return await this.crud.findOneBy({
-        file_path: path3,
+        file_path: path4,
         storage_type: storageType
       });
     } catch (error) {
@@ -3279,9 +3317,9 @@ var FileMetadataService = class {
   /**
    * Update custom metadata for a file
    */
-  async updateMetadata(path3, storageType, metadata) {
+  async updateMetadata(path4, storageType, metadata) {
     try {
-      const existing = await this.findByPath(path3, storageType);
+      const existing = await this.findByPath(path4, storageType);
       if (existing) {
         const currentData = JSON.parse(existing.file_data || "{}");
         const newData = { ...currentData, ...metadata };
@@ -3289,7 +3327,7 @@ var FileMetadataService = class {
           file_data: JSON.stringify(newData),
           changed_at: this.now()
         });
-        this.logger?.debug?.("Updated file metadata", { path: path3 });
+        this.logger?.debug?.("Updated file metadata", { path: path4 });
         return true;
       }
       return false;
@@ -3305,9 +3343,9 @@ var FileMetadataService = class {
    * Get parsed file_data structure for a file
    * Automatically migrates old format to new extraction structure
    */
-  async getFileData(path3, storageType) {
+  async getFileData(path4, storageType) {
     try {
-      const existing = await this.findByPath(path3, storageType);
+      const existing = await this.findByPath(path4, storageType);
       if (!existing) {
         return null;
       }
@@ -3320,9 +3358,9 @@ var FileMetadataService = class {
   /**
    * Get merged extraction data for a file
    */
-  async getMergedData(path3, storageType) {
+  async getMergedData(path4, storageType) {
     try {
-      const fileData = await this.getFileData(path3, storageType);
+      const fileData = await this.getFileData(path4, storageType);
       if (!fileData) {
         return null;
       }
@@ -3335,12 +3373,12 @@ var FileMetadataService = class {
   /**
    * Add an extraction to a file's data
    */
-  async addExtraction(path3, storageType, data, options) {
+  async addExtraction(path4, storageType, data, options) {
     const start = Date.now();
     try {
-      const existing = await this.findByPath(path3, storageType);
+      const existing = await this.findByPath(path4, storageType);
       if (!existing) {
-        this.logger?.warn?.("Cannot add extraction: file not found", { path: path3 });
+        this.logger?.warn?.("Cannot add extraction: file not found", { path: path4 });
         return null;
       }
       const currentFileData = parseFileData(existing.file_data);
@@ -3355,11 +3393,11 @@ var FileMetadataService = class {
       });
       const newExtraction = result.data.raw_data[result.data.raw_data.length - 1];
       const duration_ms = Date.now() - start;
-      this.logger?.debug?.("Added extraction", { path: path3, extractionId: newExtraction.id });
+      this.logger?.debug?.("Added extraction", { path: path4, extractionId: newExtraction.id });
       this.logger?.info?.("file_operation", {
         operation: "extract",
         file_name: existing.filename,
-        file_path: path3,
+        file_path: path4,
         mime_type: existing.file_type,
         storage: storageType,
         duration_ms,
@@ -3371,7 +3409,7 @@ var FileMetadataService = class {
       const duration_ms = Date.now() - start;
       this.logger?.error?.("file_operation", {
         operation: "extract",
-        file_path: path3,
+        file_path: path4,
         storage: storageType,
         duration_ms,
         success: false,
@@ -3384,9 +3422,9 @@ var FileMetadataService = class {
   /**
    * Remove an extraction by ID
    */
-  async removeExtractionById(path3, storageType, id, options) {
+  async removeExtractionById(path4, storageType, id, options) {
     try {
-      const existing = await this.findByPath(path3, storageType);
+      const existing = await this.findByPath(path4, storageType);
       if (!existing) {
         return false;
       }
@@ -3400,7 +3438,7 @@ var FileMetadataService = class {
         file_data: stringifyFileData(result.data),
         changed_at: this.now()
       });
-      this.logger?.debug?.("Removed extraction by ID", { path: path3, extractionId: id });
+      this.logger?.debug?.("Removed extraction by ID", { path: path4, extractionId: id });
       return true;
     } catch (error) {
       this.logError("removeExtractionById", error);
@@ -3410,9 +3448,9 @@ var FileMetadataService = class {
   /**
    * Remove an extraction by index
    */
-  async removeExtractionByIndex(path3, storageType, index, options) {
+  async removeExtractionByIndex(path4, storageType, index, options) {
     try {
-      const existing = await this.findByPath(path3, storageType);
+      const existing = await this.findByPath(path4, storageType);
       if (!existing) {
         return false;
       }
@@ -3426,7 +3464,7 @@ var FileMetadataService = class {
         file_data: stringifyFileData(result.data),
         changed_at: this.now()
       });
-      this.logger?.debug?.("Removed extraction by index", { path: path3, index });
+      this.logger?.debug?.("Removed extraction by index", { path: path4, index });
       return true;
     } catch (error) {
       this.logError("removeExtractionByIndex", error);
@@ -3436,9 +3474,9 @@ var FileMetadataService = class {
   /**
    * Get all extractions for a file
    */
-  async getExtractions(path3, storageType) {
+  async getExtractions(path4, storageType) {
     try {
-      const fileData = await this.getFileData(path3, storageType);
+      const fileData = await this.getFileData(path4, storageType);
       if (!fileData) {
         return null;
       }
@@ -3451,9 +3489,9 @@ var FileMetadataService = class {
   /**
    * Get a specific extraction by ID
    */
-  async getExtractionById(path3, storageType, id) {
+  async getExtractionById(path4, storageType, id) {
     try {
-      const fileData = await this.getFileData(path3, storageType);
+      const fileData = await this.getFileData(path4, storageType);
       if (!fileData) {
         return null;
       }
@@ -3466,9 +3504,9 @@ var FileMetadataService = class {
   /**
    * Clear all extractions for a file
    */
-  async clearExtractions(path3, storageType) {
+  async clearExtractions(path4, storageType) {
     try {
-      const existing = await this.findByPath(path3, storageType);
+      const existing = await this.findByPath(path4, storageType);
       if (!existing) {
         return false;
       }
@@ -3476,7 +3514,7 @@ var FileMetadataService = class {
         file_data: stringifyFileData(createEmptyFileDataStructure()),
         changed_at: this.now()
       });
-      this.logger?.debug?.("Cleared all extractions", { path: path3 });
+      this.logger?.debug?.("Cleared all extractions", { path: path4 });
       return true;
     } catch (error) {
       this.logError("clearExtractions", error);
@@ -3686,7 +3724,7 @@ var FileMetadataService = class {
     return this.updateStatus(fileId, "soft_deleted");
   }
   /**
-   * Update specific V2 fields on a record
+   * Update specific V2/V4 fields on a record
    */
   async updateFields(fileId, fields) {
     try {
@@ -3817,6 +3855,7 @@ var TrackedFileManager = class extends FileManager {
   constructor(options = {}) {
     super(options);
     this.metadataService = null;
+    this.quotaService = null;
     this.trackingConfig = {
       enabled: options.tracking?.enabled ?? false,
       tableName: options.tracking?.tableName ?? "hazo_files",
@@ -3830,6 +3869,8 @@ var TrackedFileManager = class extends FileManager {
         logErrors: this.trackingConfig.logErrors
       });
     }
+    this.quotaService = options.quotaService ?? null;
+    this.ssrfAllowlist = options.ssrfAllowlist ?? [];
   }
   /**
    * Check if tracking is enabled and service is available
@@ -3847,11 +3888,11 @@ var TrackedFileManager = class extends FileManager {
   /**
    * Create a directory and record it in the database
    */
-  async createDirectory(path3) {
-    const result = await super.createDirectory(path3);
+  async createDirectory(path4) {
+    const result = await super.createDirectory(path4);
     if (result.success && this.isTrackingEnabled()) {
       this.metadataService.recordDirectoryCreation(
-        path3,
+        path4,
         this.getStorageType(),
         result.data?.metadata
       ).catch(() => {
@@ -3862,11 +3903,11 @@ var TrackedFileManager = class extends FileManager {
   /**
    * Remove a directory and delete its record from the database
    */
-  async removeDirectory(path3, recursive = false) {
-    const result = await super.removeDirectory(path3, recursive);
+  async removeDirectory(path4, recursive = false) {
+    const result = await super.removeDirectory(path4, recursive);
     if (result.success && this.isTrackingEnabled()) {
       this.metadataService.recordDirectoryDelete(
-        path3,
+        path4,
         this.getStorageType(),
         recursive
       ).catch(() => {
@@ -3884,7 +3925,16 @@ var TrackedFileManager = class extends FileManager {
     if (source instanceof Buffer) {
       fileBuffer = source;
     }
+    const scope_id = options?.scope_id;
+    const preCheckSize = fileBuffer?.length ?? 0;
+    if (this.quotaService && scope_id && preCheckSize > 0) {
+      await this.quotaService.checkQuota(scope_id, preCheckSize);
+    }
     const result = await super.uploadFile(source, remotePath, options);
+    if (result.success && this.quotaService && scope_id && preCheckSize > 0) {
+      await this.quotaService.incrementUsage(scope_id, preCheckSize).catch(() => {
+      });
+    }
     if (result.success && this.isTrackingEnabled() && result.data) {
       const fileItem = result.data;
       const skipHash = options?.skipHash ?? false;
@@ -3908,7 +3958,10 @@ var TrackedFileManager = class extends FileManager {
         file_path: remotePath,
         storage_type: this.getStorageType(),
         file_hash: fileHash,
-        file_size: fileSize
+        file_size: fileSize,
+        uploaded_by: options?.actor_id,
+        changed_by: options?.actor_id,
+        scope_id: options?.scope_id
       });
       if (awaitRecording) {
         await recordPromise;
@@ -3942,7 +3995,8 @@ var TrackedFileManager = class extends FileManager {
       this.metadataService.recordMove(
         sourcePath,
         destinationPath,
-        this.getStorageType()
+        this.getStorageType(),
+        options?.actor_id
       ).catch(() => {
       });
     }
@@ -3951,12 +4005,13 @@ var TrackedFileManager = class extends FileManager {
   /**
    * Delete a file and remove its record from the database
    */
-  async deleteFile(path3) {
-    const result = await super.deleteFile(path3);
+  async deleteFile(path4, opts) {
+    const result = await super.deleteFile(path4);
     if (result.success && this.isTrackingEnabled()) {
       this.metadataService.recordDelete(
-        path3,
-        this.getStorageType()
+        path4,
+        this.getStorageType(),
+        opts?.actor_id
       ).catch(() => {
       });
     }
@@ -3965,13 +4020,14 @@ var TrackedFileManager = class extends FileManager {
   /**
    * Rename a file and update its record in the database
    */
-  async renameFile(path3, newName, options) {
-    const result = await super.renameFile(path3, newName, options);
+  async renameFile(path4, newName, options) {
+    const result = await super.renameFile(path4, newName, options);
     if (result.success && this.isTrackingEnabled()) {
       this.metadataService.recordRename(
-        path3,
+        path4,
         newName,
-        this.getStorageType()
+        this.getStorageType(),
+        options?.actor_id
       ).catch(() => {
       });
     }
@@ -3980,13 +4036,14 @@ var TrackedFileManager = class extends FileManager {
   /**
    * Rename a folder and update its record in the database
    */
-  async renameFolder(path3, newName, options) {
-    const result = await super.renameFolder(path3, newName, options);
+  async renameFolder(path4, newName, options) {
+    const result = await super.renameFolder(path4, newName, options);
     if (result.success && this.isTrackingEnabled()) {
       this.metadataService.recordRename(
-        path3,
+        path4,
         newName,
-        this.getStorageType()
+        this.getStorageType(),
+        options?.actor_id
       ).catch(() => {
       });
     }
@@ -3996,15 +4053,15 @@ var TrackedFileManager = class extends FileManager {
   /**
    * Write a file with string content and track it
    */
-  async writeFile(path3, content, options) {
+  async writeFile(path4, content, options) {
     const buffer = Buffer.from(content, "utf-8");
-    return this.uploadFile(buffer, path3, options);
+    return this.uploadFile(buffer, path4, options);
   }
   /**
    * Read a file and optionally track access
    */
-  async readFile(path3) {
-    return super.readFile(path3);
+  async readFile(path4) {
+    return super.readFile(path4);
   }
   /**
    * Copy a file and track the new file
@@ -4049,11 +4106,11 @@ var TrackedFileManager = class extends FileManager {
    * }
    * ```
    */
-  async hasFileChanged(path3) {
+  async hasFileChanged(path4) {
     if (!this.isTrackingEnabled()) {
       return null;
     }
-    const record = await this.metadataService.findByPath(path3, this.getStorageType());
+    const record = await this.metadataService.findByPath(path4, this.getStorageType());
     if (!record) {
       return null;
     }
@@ -4061,7 +4118,7 @@ var TrackedFileManager = class extends FileManager {
     if (!storedHash) {
       return true;
     }
-    const downloadResult = await super.downloadFile(path3);
+    const downloadResult = await super.downloadFile(path4);
     if (!downloadResult.success || !downloadResult.data) {
       return null;
     }
@@ -4081,11 +4138,11 @@ var TrackedFileManager = class extends FileManager {
    * @param path - Virtual path to the file
    * @returns Stored hash or null if not found/not tracked
    */
-  async getStoredHash(path3) {
+  async getStoredHash(path4) {
     if (!this.isTrackingEnabled()) {
       return null;
     }
-    const record = await this.metadataService.findByPath(path3, this.getStorageType());
+    const record = await this.metadataService.findByPath(path4, this.getStorageType());
     return record?.file_hash || null;
   }
   /**
@@ -4094,11 +4151,11 @@ var TrackedFileManager = class extends FileManager {
    * @param path - Virtual path to the file
    * @returns Stored size in bytes or null if not found/not tracked
    */
-  async getStoredSize(path3) {
+  async getStoredSize(path4) {
     if (!this.isTrackingEnabled()) {
       return null;
     }
-    const record = await this.metadataService.findByPath(path3, this.getStorageType());
+    const record = await this.metadataService.findByPath(path4, this.getStorageType());
     return record?.file_size ?? null;
   }
   // ============ Reference Tracking Methods (V2) ============
@@ -4132,10 +4189,67 @@ var TrackedFileManager = class extends FileManager {
   }
   /**
    * Soft-delete a file (marks as soft_deleted, does not remove physical file)
+   * Also decrements quota usage if quotaService is configured.
    */
-  async softDeleteFile(fileId) {
+  async softDeleteFile(fileId, opts) {
     if (!this.isTrackingEnabled()) return false;
-    return this.metadataService.softDelete(fileId);
+    let fileSizeForQuota;
+    let scopeIdForQuota;
+    if (this.quotaService) {
+      const record = await this.metadataService.findById(fileId);
+      if (record) {
+        fileSizeForQuota = record.file_size ?? void 0;
+        scopeIdForQuota = record.scope_id;
+      }
+    }
+    const ok = await this.metadataService.softDelete(fileId);
+    if (ok) {
+      if (opts?.actor_id) {
+        await this.metadataService.updateFields(fileId, { changed_by: opts.actor_id });
+      }
+      if (this.quotaService && scopeIdForQuota && fileSizeForQuota !== void 0) {
+        await this.quotaService.decrementUsage(scopeIdForQuota, fileSizeForQuota);
+      }
+    }
+    return ok;
+  }
+  // ============ Quota Pass-through Methods ============
+  /**
+   * Get quota status for a scope.
+   * Returns null if no quota is configured (fail-open).
+   */
+  async getQuota(scopeId) {
+    if (!this.quotaService) return null;
+    return this.quotaService.getQuota(scopeId);
+  }
+  /**
+   * Set or update the byte limit for a scope.
+   * Creates a quota row if one does not exist.
+   */
+  async setQuotaLimit(scopeId, bytes) {
+    if (!this.quotaService) return null;
+    return this.quotaService.setQuotaLimit(scopeId, bytes);
+  }
+  /**
+   * Recompute and return the quota status for a scope.
+   */
+  async recomputeQuota(scopeId) {
+    if (!this.quotaService) return null;
+    return this.quotaService.recomputeQuota(scopeId);
+  }
+  /**
+   * Increment usage for a scope (admin override — does not throw on exceeded quota).
+   */
+  async incrementQuotaUsage(scopeId, deltaBytes) {
+    if (!this.quotaService) return;
+    return this.quotaService.incrementUsage(scopeId, deltaBytes);
+  }
+  /**
+   * Decrement usage for a scope (e.g. after manual cleanup).
+   */
+  async decrementQuotaUsage(scopeId, deltaBytes) {
+    if (!this.quotaService) return;
+    return this.quotaService.decrementUsage(scopeId, deltaBytes);
   }
   /**
    * Find orphaned files (files with zero references)
@@ -4227,6 +4341,139 @@ var TrackedFileManager = class extends FileManager {
       }
     };
   }
+  /**
+   * Import a file from a URL into virtual storage.
+   *
+   * Uses hazo_secure/fetch for SSRF protection (optional peer dependency).
+   * Streams the response to a temp file, counting bytes live.
+   * On cap exceeded: aborts, deletes temp file, throws ImportSizeCapError.
+   * On success: uploads to virtualPath, sets source_url in DB record.
+   *
+   * @param url - URL to fetch
+   * @param virtualPath - Destination virtual path in storage
+   * @param opts.referrer - Optional Referer header to send
+   * @param opts.maxBytes - Maximum response size in bytes (default: 50MB)
+   * @param opts.actor_id - Actor UUID to record in uploaded_by / changed_by
+   */
+  async importFromUrl(url, virtualPath, opts) {
+    const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+    const maxBytes = opts?.maxBytes ?? DEFAULT_MAX_BYTES;
+    let hazoSecureMod = null;
+    try {
+      hazoSecureMod = await import("hazo_secure/fetch");
+    } catch {
+      return {
+        success: false,
+        error: 'importFromUrl requires the optional peer dependency "hazo_secure" to be installed. Run: npm install hazo_secure'
+      };
+    }
+    const safeFetch = hazoSecureMod.safeFetch;
+    const SafeFetchErrorClass = hazoSecureMod.SafeFetchError;
+    const policy = {
+      blockPrivateIps: true,
+      allowedProtocols: ["https:", "http:"]
+    };
+    if (this.ssrfAllowlist.length > 0) {
+      policy.allowedHosts = this.ssrfAllowlist;
+    }
+    const headers = {};
+    if (opts?.referrer) {
+      headers["Referer"] = opts.referrer;
+    }
+    const tmpFile = path3.join(os.tmpdir(), `hazo_import_${Date.now()}_${Math.random().toString(36).slice(2)}.tmp`);
+    let tmpWriteStream = null;
+    try {
+      const controller = new AbortController();
+      let response;
+      try {
+        response = await safeFetch(url, {
+          policy,
+          headers,
+          signal: controller.signal
+        });
+      } catch (err) {
+        if (SafeFetchErrorClass && err instanceof SafeFetchErrorClass) {
+          const ssrfErr = err;
+          throw new SSRFError(url, ssrfErr.message);
+        }
+        throw err;
+      }
+      if (!response) {
+        return { success: false, error: `No response from ${url}` };
+      }
+      if (!response.ok) {
+        return { success: false, error: `HTTP ${response.status} from ${url}` };
+      }
+      if (!response.body) {
+        return { success: false, error: `No response body from ${url}` };
+      }
+      tmpWriteStream = fs3.createWriteStream(tmpFile);
+      let totalBytes = 0;
+      let capExceeded = false;
+      const reader = response.body.getReader();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          totalBytes += value.length;
+          if (totalBytes > maxBytes) {
+            capExceeded = true;
+            controller.abort();
+            reader.cancel().catch(() => {
+            });
+            break;
+          }
+          await new Promise((resolve2, reject) => {
+            tmpWriteStream.write(value, (err) => err ? reject(err) : resolve2());
+          });
+        }
+      } finally {
+        await new Promise((resolve2) => tmpWriteStream.end(resolve2));
+      }
+      if (capExceeded) {
+        try {
+          fs3.unlinkSync(tmpFile);
+        } catch {
+        }
+        throw new ImportSizeCapError(url, maxBytes);
+      }
+      if (this.quotaService && opts?.scope_id && totalBytes > 0) {
+        await this.quotaService.checkQuota(opts.scope_id, totalBytes);
+      }
+      const uploadResult = await this.uploadFile(tmpFile, virtualPath, {
+        actor_id: opts?.actor_id,
+        scope_id: opts?.scope_id,
+        awaitRecording: true
+      });
+      try {
+        fs3.unlinkSync(tmpFile);
+      } catch {
+      }
+      if (!uploadResult.success) {
+        return { success: false, error: uploadResult.error };
+      }
+      if (this.isTrackingEnabled()) {
+        const record = await this.metadataService.findByPath(virtualPath, this.getStorageType());
+        if (record) {
+          await this.metadataService.updateFields(record.id, { source_url: url });
+        }
+      }
+      return {
+        success: true,
+        data: { virtualPath, size: totalBytes, sourceUrl: url }
+      };
+    } catch (err) {
+      try {
+        fs3.unlinkSync(tmpFile);
+      } catch {
+      }
+      if (err instanceof SSRFError || err instanceof ImportSizeCapError) {
+        throw err;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      return { success: false, error: `importFromUrl failed: ${msg}` };
+    }
+  }
 };
 function createTrackedFileManager(options) {
   return new TrackedFileManager(options);
@@ -5285,6 +5532,206 @@ function createUploadExtractService(fileManager, namingService, extractionServic
   return new UploadExtractService(fileManager, namingService, extractionService, defaultContentTagConfig);
 }
 
+// src/services/quota-service.ts
+var QuotaService = class {
+  constructor(opts) {
+    this.crud = opts.crudService;
+    this.onThreshold = opts.onThreshold;
+    this.bands = (opts.bands ?? [0.8, 0.95]).slice().sort((a, b) => a - b);
+    this.logger = opts.logger;
+  }
+  /**
+   * Get quota status for a scope.
+   * Returns null if no quota row exists (fail-open = no quota set).
+   */
+  async getQuota(scopeId) {
+    try {
+      const row = await this.crud.findOneBy({ scope_id: scopeId });
+      if (!row) return null;
+      return this.rowToStatus(row);
+    } catch (error) {
+      this.logger?.error?.("QuotaService.getQuota failed", {
+        scopeId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return null;
+    }
+  }
+  /**
+   * Set (or update) the byte limit for a scope.
+   * Creates a quota row if one does not exist (with byte_used = 0).
+   * Returns the current stored status after upsert.
+   *
+   * @note This method does NOT auto-reconcile byte_used via a SUM query —
+   *   it simply upserts the limit and returns the stored row. To reconcile
+   *   byte_used against actual file sizes, call recomputeQuota() separately
+   *   after a SUM(file_size) query on hazo_files for the scope.
+   */
+  async setQuotaLimit(scopeId, bytes) {
+    try {
+      const existing = await this.crud.findOneBy({ scope_id: scopeId });
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      if (existing) {
+        await this.crud.updateById(scopeId, {
+          byte_limit: bytes,
+          updated_at: now
+        });
+      } else {
+        await this.crud.insert({
+          scope_id: scopeId,
+          byte_limit: bytes,
+          byte_used: 0,
+          updated_at: now
+        });
+      }
+      const row = await this.crud.findOneBy({ scope_id: scopeId });
+      if (!row) {
+        return { scopeId, byteLimit: bytes, byteUsed: 0, percentUsed: 0 };
+      }
+      return this.rowToStatus(row);
+    } catch (error) {
+      this.logger?.error?.("QuotaService.setQuotaLimit failed", {
+        scopeId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    }
+  }
+  /**
+   * Recompute byteUsed by reading the current row.
+   * (Full reconciliation against actual file sizes should be done externally
+   * via a SUM query on hazo_files; this method just returns the stored state.)
+   */
+  async recomputeQuota(scopeId) {
+    const row = await this.crud.findOneBy({ scope_id: scopeId });
+    if (!row) {
+      throw new Error(`No quota row found for scope ${scopeId}`);
+    }
+    return this.rowToStatus(row);
+  }
+  /**
+   * Pre-upload check ONLY — does NOT increment.
+   * Throws QuotaExceededError if the upload would exceed the limit.
+   * If no quota row exists for the scope, succeeds silently (fail-open).
+   *
+   * Use this before the upload, then call incrementUsage after confirmed success.
+   * This prevents quota inflation when an upload fails mid-stream.
+   */
+  async checkQuota(scopeId, deltaBytes) {
+    const row = await this.crud.findOneBy({ scope_id: scopeId });
+    if (!row) {
+      return;
+    }
+    const prevUsed = row.byte_used;
+    const newUsed = prevUsed + deltaBytes;
+    if (newUsed > row.byte_limit) {
+      throw new QuotaExceededError(scopeId, prevUsed, row.byte_limit, deltaBytes);
+    }
+  }
+  /**
+   * Pre-upload check and increment (atomic). Throws QuotaExceededError if the upload
+   * would exceed the limit. If no quota row exists, succeeds silently (fail-open).
+   * Also fires threshold callbacks for any bands crossed by the new usage.
+   *
+   * @deprecated Prefer checkQuota() before upload + incrementUsage() after success.
+   *   checkAndIncrement() increments before the upload completes; if the upload
+   *   subsequently fails the quota is inflated with no rollback.
+   */
+  async checkAndIncrement(scopeId, deltaBytes) {
+    await this.checkQuota(scopeId, deltaBytes);
+    const row = await this.crud.findOneBy({ scope_id: scopeId });
+    if (!row) return;
+    const prevUsed = row.byte_used;
+    const newUsed = prevUsed + deltaBytes;
+    await this.crud.updateById(scopeId, {
+      byte_used: newUsed,
+      updated_at: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    this.fireThresholdCallbacks(scopeId, prevUsed, newUsed, row.byte_limit);
+  }
+  /**
+   * Decrement usage (call after soft-delete or hard-delete).
+   * Clamps to zero; no-ops if no quota row.
+   */
+  async decrementUsage(scopeId, deltaBytes) {
+    try {
+      const row = await this.crud.findOneBy({ scope_id: scopeId });
+      if (!row) return;
+      const newUsed = Math.max(0, row.byte_used - deltaBytes);
+      await this.crud.updateById(scopeId, {
+        byte_used: newUsed,
+        updated_at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    } catch (error) {
+      this.logger?.error?.("QuotaService.decrementUsage failed", {
+        scopeId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  /**
+   * Increment usage manually (admin override).
+   * Does NOT throw on exceeded quota — admin is explicitly bypassing.
+   */
+  async incrementUsage(scopeId, deltaBytes) {
+    try {
+      const row = await this.crud.findOneBy({ scope_id: scopeId });
+      if (!row) return;
+      const prevUsed = row.byte_used;
+      const newUsed = prevUsed + deltaBytes;
+      await this.crud.updateById(scopeId, {
+        byte_used: newUsed,
+        updated_at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      this.fireThresholdCallbacks(scopeId, prevUsed, newUsed, row.byte_limit);
+    } catch (error) {
+      this.logger?.error?.("QuotaService.incrementUsage failed", {
+        scopeId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  /**
+   * Fire threshold callbacks for all bands crossed going from prevUsed → newUsed.
+   * Bands are sorted ascending so callbacks fire in order (80% before 95%).
+   */
+  fireThresholdCallbacks(scopeId, prevUsed, newUsed, byteLimit) {
+    if (!this.onThreshold || byteLimit <= 0) return;
+    const prevPercent = prevUsed / byteLimit;
+    const newPercent = newUsed / byteLimit;
+    for (const band of this.bands) {
+      if (prevPercent < band && newPercent >= band) {
+        try {
+          this.onThreshold({
+            scopeId,
+            percent: band,
+            bytesUsed: newUsed,
+            byteLimit
+          });
+        } catch (err) {
+          this.logger?.error?.("QuotaService threshold callback threw", {
+            band,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      }
+    }
+  }
+  rowToStatus(row) {
+    const byteLimit = row.byte_limit;
+    const byteUsed = row.byte_used;
+    return {
+      scopeId: row.scope_id,
+      byteLimit,
+      byteUsed,
+      percentUsed: byteLimit > 0 ? byteUsed / byteLimit : 0
+    };
+  }
+};
+function createQuotaService(opts) {
+  return new QuotaService(opts);
+}
+
 // src/server/factory.ts
 async function createHazoFilesServer(options = {}) {
   const {
@@ -5299,8 +5746,20 @@ async function createHazoFilesServer(options = {}) {
     namingTableName = "hazo_files_naming",
     enableTracking = !!crudService,
     trackDownloads = true,
-    defaultContentTagConfig
+    defaultContentTagConfig,
+    ssrf,
+    quotaCrudService,
+    onQuotaThreshold,
+    quotaBands
   } = options;
+  let quotaService;
+  if (quotaCrudService) {
+    quotaService = new QuotaService({
+      crudService: quotaCrudService,
+      onThreshold: onQuotaThreshold,
+      bands: quotaBands
+    });
+  }
   const fileManagerOptions = {
     config,
     crudService,
@@ -5310,7 +5769,9 @@ async function createHazoFilesServer(options = {}) {
       tableName: metadataTableName,
       trackDownloads,
       logErrors: true
-    }
+    },
+    quotaService,
+    ssrfAllowlist: ssrf?.allowlist
   };
   const fileManager = await createInitializedTrackedFileManager(fileManagerOptions);
   const metadataService = fileManager.getMetadataService();
@@ -5354,6 +5815,124 @@ async function createBasicFileManager(config, crudService) {
   });
 }
 
+// src/services/purge-handlers.ts
+var HAZO_FILES_JOB_TYPES = {
+  PURGE_PLAN: "hazo_files.purge_plan",
+  PURGE_ONE: "hazo_files.purge_one"
+};
+function createPurgeJobHandlers(fm, opts) {
+  const { submitJob, logger } = opts ?? {};
+  const purgePlanHandler = async (job) => {
+    const { retentionDays = 30, dryRun = false } = job.payload ?? {};
+    const cutoffMs = retentionDays * 24 * 60 * 60 * 1e3;
+    const cutoffDate = new Date(Date.now() - cutoffMs);
+    const metadataService = fm.getMetadataService();
+    if (!metadataService) {
+      logger?.warn?.("purge_plan: no metadata service available (tracking disabled)");
+      return { purgedCount: 0 };
+    }
+    let allRecords = [];
+    try {
+      const crud = metadataService.crud;
+      if (crud && typeof crud.findBy === "function") {
+        allRecords = await crud.findBy({ status: "soft_deleted" });
+      }
+    } catch (err) {
+      logger?.error?.("purge_plan: failed to query soft-deleted records", {
+        error: err instanceof Error ? err.message : String(err)
+      });
+      return { purgedCount: 0 };
+    }
+    const eligible = allRecords.filter((r) => {
+      if (!r.deleted_at) return false;
+      const deletedAt = new Date(r.deleted_at);
+      return deletedAt < cutoffDate;
+    });
+    logger?.info?.("purge_plan: found eligible records", {
+      total: allRecords.length,
+      eligible: eligible.length,
+      retentionDays,
+      dryRun
+    });
+    if (dryRun) {
+      return {
+        purgedCount: 0,
+        wouldPurge: eligible.map((r) => r.id)
+      };
+    }
+    let purgedCount = 0;
+    if (submitJob) {
+      for (const record of eligible) {
+        try {
+          await submitJob(HAZO_FILES_JOB_TYPES.PURGE_ONE, { fileId: record.id });
+          purgedCount++;
+        } catch (err) {
+          logger?.error?.("purge_plan: failed to submit purge_one job", {
+            fileId: record.id,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      }
+    } else {
+      for (const record of eligible) {
+        try {
+          await hardDeleteRecord(fm, record, metadataService, logger);
+          purgedCount++;
+        } catch (err) {
+          logger?.error?.("purge_plan: failed to inline-purge record", {
+            fileId: record.id,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      }
+    }
+    return { purgedCount };
+  };
+  const purgeOneHandler = async (job) => {
+    const { fileId } = job.payload;
+    const metadataService = fm.getMetadataService();
+    if (!metadataService) {
+      logger?.warn?.("purge_one: no metadata service (tracking disabled)", { fileId });
+      return;
+    }
+    const record = await metadataService.findById(fileId);
+    if (!record) {
+      logger?.info?.("purge_one: record not found (already purged)", { fileId });
+      return;
+    }
+    if (record.status !== "soft_deleted") {
+      logger?.warn?.("[hazo_files] purge_one skipping non-soft-deleted file", {
+        fileId,
+        status: record.status
+      });
+      return;
+    }
+    await hardDeleteRecord(fm, record, metadataService, logger);
+    logger?.info?.("purge_one: completed", { fileId, file_path: record.file_path });
+  };
+  return {
+    [HAZO_FILES_JOB_TYPES.PURGE_PLAN]: purgePlanHandler,
+    [HAZO_FILES_JOB_TYPES.PURGE_ONE]: purgeOneHandler
+  };
+}
+async function hardDeleteRecord(fm, record, _metadataService, logger) {
+  try {
+    const deleteResult = await fm.deleteFile(record.file_path);
+    if (!deleteResult.success) {
+      logger?.warn?.("purge: physical delete returned error (continuing)", {
+        fileId: record.id,
+        file_path: record.file_path,
+        error: deleteResult.error
+      });
+    }
+  } catch (err) {
+    logger?.warn?.("purge: physical delete threw (continuing)", {
+      fileId: record.id,
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+
 // src/schema/index.ts
 var HAZO_FILES_DEFAULT_TABLE_NAME = "hazo_files";
 var HAZO_FILES_TABLE_SCHEMA = {
@@ -5637,6 +6216,77 @@ function getMigrationV3ForTable(tableName, dbType) {
     backfill: migration.backfill
   };
 }
+var HAZO_FILES_MIGRATION_V4 = {
+  tableName: HAZO_FILES_DEFAULT_TABLE_NAME,
+  sqlite: {
+    // NOT IDEMPOTENT — SQLite ALTER TABLE does not support IF NOT EXISTS.
+    // Wrap each statement in try/catch when running on SQLite.
+    alterStatements: [
+      "ALTER TABLE hazo_files ADD COLUMN changed_by TEXT",
+      "ALTER TABLE hazo_files ADD COLUMN source_url TEXT"
+    ],
+    indexes: [
+      "CREATE INDEX IF NOT EXISTS idx_hazo_files_changed_by ON hazo_files (changed_by)",
+      "CREATE INDEX IF NOT EXISTS idx_hazo_files_source_url ON hazo_files (source_url)"
+    ],
+    backfill: ""
+    // No backfill needed — columns are nullable
+  },
+  postgres: {
+    alterStatements: [
+      "ALTER TABLE hazo_files ADD COLUMN IF NOT EXISTS changed_by UUID",
+      "ALTER TABLE hazo_files ADD COLUMN IF NOT EXISTS source_url TEXT"
+    ],
+    indexes: [
+      "CREATE INDEX IF NOT EXISTS idx_hazo_files_changed_by ON hazo_files (changed_by)",
+      "CREATE INDEX IF NOT EXISTS idx_hazo_files_source_url ON hazo_files (source_url)"
+    ],
+    backfill: ""
+    // No backfill needed — columns are nullable
+  },
+  newColumns: ["changed_by", "source_url"]
+};
+function getMigrationV4ForTable(tableName, dbType) {
+  validateTableName(tableName);
+  const migration = HAZO_FILES_MIGRATION_V4[dbType];
+  const defaultName = HAZO_FILES_MIGRATION_V4.tableName;
+  return {
+    alterStatements: migration.alterStatements.map(
+      (stmt) => stmt.replace(new RegExp(defaultName, "g"), tableName)
+    ),
+    indexes: migration.indexes.map(
+      (idx) => idx.replace(new RegExp(defaultName, "g"), tableName)
+    ),
+    backfill: migration.backfill
+  };
+}
+var HAZO_FILE_QUOTAS_DEFAULT_TABLE_NAME = "hazo_file_quotas";
+var HAZO_FILE_QUOTAS_TABLE_SCHEMA = {
+  tableName: HAZO_FILE_QUOTAS_DEFAULT_TABLE_NAME,
+  sqlite: {
+    ddl: `CREATE TABLE IF NOT EXISTS hazo_file_quotas (
+  scope_id TEXT PRIMARY KEY,
+  byte_limit INTEGER NOT NULL,
+  byte_used INTEGER NOT NULL DEFAULT 0,
+  updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+)`,
+    indexes: [
+      "CREATE INDEX IF NOT EXISTS idx_hazo_file_quotas_used ON hazo_file_quotas (byte_used)"
+    ]
+  },
+  postgres: {
+    ddl: `CREATE TABLE IF NOT EXISTS hazo_file_quotas (
+  scope_id UUID PRIMARY KEY,
+  byte_limit BIGINT NOT NULL,
+  byte_used BIGINT NOT NULL DEFAULT 0,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+)`,
+    indexes: [
+      "CREATE INDEX IF NOT EXISTS idx_hazo_file_quotas_used ON hazo_file_quotas (byte_used)"
+    ]
+  },
+  columns: ["scope_id", "byte_limit", "byte_used", "updated_at"]
+};
 
 // src/migrations/add-reference-tracking.ts
 async function migrateToV2(executor, dbType, tableName) {
@@ -5696,12 +6346,17 @@ export {
   GoogleDriveAuth,
   GoogleDriveModule,
   HAZO_FILES_DEFAULT_TABLE_NAME,
+  HAZO_FILES_JOB_TYPES,
   HAZO_FILES_MIGRATION_V2,
   HAZO_FILES_MIGRATION_V3,
+  HAZO_FILES_MIGRATION_V4,
   HAZO_FILES_NAMING_DEFAULT_TABLE_NAME,
   HAZO_FILES_NAMING_TABLE_SCHEMA,
   HAZO_FILES_TABLE_SCHEMA,
+  HAZO_FILE_QUOTAS_DEFAULT_TABLE_NAME,
+  HAZO_FILE_QUOTAS_TABLE_SCHEMA,
   HazoFilesError,
+  ImportSizeCapError,
   InvalidExtensionError,
   InvalidPathError,
   LLMExtractionService,
@@ -5709,6 +6364,9 @@ export {
   NamingConventionService,
   OperationError,
   PermissionDeniedError,
+  QuotaExceededError,
+  QuotaService,
+  SSRFError,
   SYSTEM_COUNTER_VARIABLES,
   SYSTEM_DATE_VARIABLES,
   SYSTEM_FILE_VARIABLES,
@@ -5744,6 +6402,8 @@ export {
   createLocalModule,
   createModule,
   createNamingConventionService,
+  createPurgeJobHandlers,
+  createQuotaService,
   createTrackedFileManager,
   createUploadExtractService,
   createVariableSegment,
@@ -5772,6 +6432,7 @@ export {
   getMergedData,
   getMigrationForTable,
   getMigrationV3ForTable,
+  getMigrationV4ForTable,
   getMimeType,
   getNameWithoutExtension,
   getNamingSchemaForTable,