hazo_files 1.5.2 → 2.0.0

package/dist/index.mjs

@@ -165,63 +165,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";
   }
@@ -244,6 +244,22 @@ var OperationError = class extends HazoFilesError {
     this.name = "OperationError";
   }
 };
+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) {
@@ -487,10 +503,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}`);
@@ -499,11 +515,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 [];
     }
@@ -1322,12 +1338,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: {
@@ -1339,7 +1355,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(),
@@ -1438,10 +1454,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 = {
@@ -1490,10 +1506,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);
@@ -1681,10 +1697,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}`);
     }
@@ -1975,12 +1991,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: {
@@ -1993,7 +2009,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),
@@ -2069,8 +2085,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 {
@@ -2139,10 +2155,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);
@@ -2311,10 +2327,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}`);
     }
@@ -2433,13 +2449,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,
@@ -2454,13 +2470,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,
@@ -2539,13 +2555,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,
@@ -2559,14 +2575,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,
@@ -2581,14 +2597,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,
@@ -2603,54 +2619,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 };
   }
   /**
@@ -2661,22 +2677,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) {
@@ -2688,6 +2704,11 @@ async function createInitializedFileManager(options) {
   return manager;
 }
 
+// src/services/tracked-file-manager.ts
+import * as fs3 from "fs";
+import * as os from "os";
+import * as path3 from "path";
+
 // src/common/file-data-utils.ts
 function generateExtractionId() {
   return `ext_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
@@ -2989,6 +3010,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 });
@@ -3021,32 +3044,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,
@@ -3060,7 +3083,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,
@@ -3072,19 +3095,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,
@@ -3098,7 +3122,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,
@@ -3111,23 +3135,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);
@@ -3137,16 +3161,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", {
@@ -3180,24 +3206,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,
@@ -3212,7 +3240,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,
@@ -3226,10 +3254,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) {
@@ -3272,9 +3300,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 };
@@ -3282,7 +3310,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;
@@ -3298,9 +3326,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;
       }
@@ -3313,9 +3341,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;
       }
@@ -3328,12 +3356,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);
@@ -3348,11 +3376,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,
@@ -3364,7 +3392,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,
@@ -3377,9 +3405,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;
       }
@@ -3393,7 +3421,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);
@@ -3403,9 +3431,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;
       }
@@ -3419,7 +3447,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);
@@ -3429,9 +3457,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;
       }
@@ -3444,9 +3472,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;
       }
@@ -3459,9 +3487,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;
       }
@@ -3469,7 +3497,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);
@@ -3679,7 +3707,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 {
@@ -3810,6 +3838,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",
@@ -3823,6 +3852,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
@@ -3840,11 +3871,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(() => {
@@ -3855,11 +3886,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(() => {
@@ -3877,7 +3908,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;
@@ -3901,7 +3941,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;
@@ -3935,7 +3978,8 @@ var TrackedFileManager = class extends FileManager {
       this.metadataService.recordMove(
         sourcePath,
         destinationPath,
-        this.getStorageType()
+        this.getStorageType(),
+        options?.actor_id
       ).catch(() => {
       });
     }
@@ -3944,12 +3988,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(() => {
       });
     }
@@ -3958,13 +4003,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(() => {
       });
     }
@@ -3973,13 +4019,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(() => {
       });
     }
@@ -3989,15 +4036,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
@@ -4042,11 +4089,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;
     }
@@ -4054,7 +4101,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;
     }
@@ -4074,11 +4121,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;
   }
   /**
@@ -4087,11 +4134,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) ============
@@ -4125,10 +4172,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)
@@ -4220,6 +4324,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);