hazo_files 1.5.2 → 1.6.0

package/CHANGE_LOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.6.0 (2026-05-21)
+
+### Added
+- **R2 Quota tracking**: Per-scope opt-in quota with threshold callbacks (`setQuotaLimit`, `getQuota`, `recomputeQuota`, `onQuotaThreshold`)
+- **R4 URL import**: `importFromUrl(url, path, opts)` with SSRF protection via `hazo_secure`, 50MB default cap, `source_url` column
+- **R6 Purge**: `createPurgeJobHandlers(fm)` factory + `HAZO_FILES_JOB_TYPES` constants for `hazo_jobs` integration
+- **Actor tracking**: Optional `actor_id` on all `TrackedFileManager` mutations → `changed_by`/`uploaded_by` columns
+- **Migrations 004-006**: `changed_by`, `source_url` columns, and `hazo_file_quotas` table
+- `HAZO_FILES_MIGRATION_V4` export for programmatic V4 migration
+- `HAZO_FILE_QUOTAS_TABLE_SCHEMA` export for quota table DDL
+- `QuotaService`, `QuotaExceededError`, `SSRFError`, `ImportSizeCapError` exported from `hazo_files/server`
+- test-app: Quota, URL Import, and Lifecycle pages with interactive scenarios
+
+### Not breaking
+All additions are opt-in or additive. Existing 1.5.x callers work without changes.
+
 ## [1.5.2] - 2026-05-18
 
 ### Fixed

package/README.md

@@ -21,6 +21,10 @@ A powerful, modular file management package for Node.js and React applications w
 - **Content Tagging**: Optional LLM-based content classification at upload time or on-demand via `content_tag` field
 - **Schema Migrations**: Built-in V2/V3 migration utilities for adding reference tracking and content tagging to existing databases
 - **Background Upload Pipelines**: Framework-agnostic `UploadManager` + React `HazoFileUploadProvider` for multi-step upload pipelines that survive component unmount, with optional sonner toast bridge
+- **Quota Tracking**: Per-scope opt-in quota with threshold callbacks and fail-open semantics
+- **URL Import**: `importFromUrl` with SSRF protection, streaming size cap, and `source_url` provenance tracking
+- **Actor Tracking**: Optional `actor_id` on all mutations, written to `uploaded_by` and `changed_by` columns
+- **Purge Scheduler**: `createPurgeJobHandlers` factory for integrating with hazo_jobs cron workers
 - **TypeScript**: Full type safety and IntelliSense support
 - **OAuth Integration**: Built-in Google Drive and Dropbox OAuth authentication
 - **Prompt Cache Invalidation**: Passthrough for hazo_llm_api prompt cache management via server instance
@@ -1981,6 +1985,187 @@ Contributions are welcome! Please:
 4. Add tests for new functionality
 5. Submit a pull request
 
+## Quota Tracking (v1.6.0)
+
+Per-scope opt-in quota tracking. A scope with no quota row has no limit — uploads succeed regardless (fail-open).
+
+### Setup
+
+Run migration 006 to create the `hazo_file_quotas` table (or use the `HAZO_FILE_QUOTAS_TABLE_SCHEMA` DDL export):
+
+```bash
+psql $DATABASE_URL < node_modules/hazo_files/migrations/006_quota_tracking.sql
+```
+
+Create a CRUD service and pass it to the factory:
+
+```typescript
+import { createHazoFilesServer, HAZO_FILE_QUOTAS_TABLE_SCHEMA } from 'hazo_files/server';
+
+const quotaCrud = createCrudService(adapter, HAZO_FILE_QUOTAS_TABLE_SCHEMA.tableName, {
+  primaryKeys: ['scope_id'],
+  autoId: { enabled: false },
+});
+
+const { fileManager } = await createHazoFilesServer({
+  crudService: fileCrud,
+  quotaCrudService: quotaCrud,
+  onQuotaThreshold: (event) => {
+    console.log(`Quota ${(event.percent * 100).toFixed(0)}% for scope ${event.scopeId}`);
+  },
+  quotaBands: [0.80, 0.95], // default
+  config: { provider: 'local', local: { basePath: './files' } },
+});
+```
+
+### Setting Quota Limits
+
+```typescript
+// Set a 10 GB limit for a scope
+const status = await fileManager.setQuotaLimit('scope-uuid', 10 * 1024 * 1024 * 1024);
+// { scopeId, byteLimit, byteUsed, percentUsed }
+
+// Check quota without uploading
+const quota = await fileManager.getQuota('scope-uuid');
+if (!quota) {
+  console.log('No quota set — unlimited');
+}
+```
+
+### Uploading with Quota Check
+
+When `scope_id` is passed to `uploadFile`, the quota is checked before the upload:
+
+```typescript
+// Throws QuotaExceededError if byteUsed + fileSize > byteLimit
+await fileManager.uploadFile(buffer, '/docs/report.pdf', { scope_id: 'scope-uuid' });
+```
+
+### Threshold Callbacks
+
+The `onQuotaThreshold` callback fires for each band crossed in a single operation. Both 80% and 95% can fire from one upload:
+
+```typescript
+onQuotaThreshold: (event) => {
+  if (event.percent === 0.80) notifyUser('Storage 80% full');
+  if (event.percent === 0.95) blockUploads('Storage 95% full');
+}
+```
+
+---
+
+## URL Import (v1.6.0)
+
+Import a file directly from a URL into virtual storage. Requires the optional peer dependency `hazo_secure`.
+
+### Installation
+
+```bash
+npm install hazo_secure   # optional peer dep
+```
+
+### Usage
+
+```typescript
+const result = await fileManager.importFromUrl(
+  'https://cdn.example.com/documents/report.pdf',
+  '/imports/report.pdf',
+  {
+    maxBytes: 50 * 1024 * 1024, // 50MB cap (default)
+    referrer: 'https://myapp.example.com/dashboard',
+    actor_id: 'user-uuid',      // written to uploaded_by + changed_by
+  }
+);
+// result.data: { virtualPath, size, sourceUrl }
+```
+
+The imported file's `source_url` column is set to the fetch URL for provenance tracking.
+
+### SSRF Protection
+
+Configure an allowlist in the server factory to restrict importable domains:
+
+```typescript
+const { fileManager } = await createHazoFilesServer({
+  ssrf: {
+    allowlist: ['cdn.example.com', 'assets.myapp.com'],
+  },
+  // ...
+});
+```
+
+Without an allowlist, private IPs (RFC-1918) are always blocked. Blocked requests throw `SSRFError`.
+
+### Size Cap
+
+If the response body exceeds `maxBytes`, the fetch is aborted and `ImportSizeCapError` is thrown. No partial file is left in storage.
+
+---
+
+## Actor Tracking (v1.6.0)
+
+All `TrackedFileManager` mutation methods accept an optional `actor_id` parameter:
+
+```typescript
+await fileManager.uploadFile(buffer, '/path/file.pdf', { actor_id: 'user-uuid' });
+await fileManager.moveItem('/old', '/new', { actor_id: 'user-uuid' });
+await fileManager.renameFile('/old.pdf', 'new.pdf', { actor_id: 'user-uuid' });
+await fileManager.renameFolder('/old-dir', 'new-dir', { actor_id: 'user-uuid' });
+await fileManager.deleteFile('/path/file.pdf', { actor_id: 'user-uuid' });
+await fileManager.softDeleteFile(fileId, { actor_id: 'user-uuid' });
+```
+
+When `actor_id` is provided:
+- `uploaded_by` is set on creation (uploadFile only)
+- `changed_by` is written on every mutation
+
+Run migrations 004 and 005 to add these columns to existing databases:
+
+```bash
+psql $DATABASE_URL < node_modules/hazo_files/migrations/004_changed_by.sql
+psql $DATABASE_URL < node_modules/hazo_files/migrations/005_source_url.sql
+```
+
+---
+
+## Purge via hazo_jobs (v1.6.0)
+
+`createPurgeJobHandlers` creates handlers compatible with hazo_jobs workers for scheduled hard-deletion of soft-deleted files.
+
+```typescript
+import { createPurgeJobHandlers, HAZO_FILES_JOB_TYPES } from 'hazo_files/server';
+
+const handlers = createPurgeJobHandlers(fm, {
+  submitJob: (type, payload) => jobs.submit({ type, payload }),
+});
+
+// Register with your hazo_jobs worker:
+worker.register(HAZO_FILES_JOB_TYPES.PURGE_PLAN, handlers[HAZO_FILES_JOB_TYPES.PURGE_PLAN]);
+worker.register(HAZO_FILES_JOB_TYPES.PURGE_ONE,  handlers[HAZO_FILES_JOB_TYPES.PURGE_ONE]);
+
+// Create schedule via hazo_jobs REST or admin UI:
+await jobs.schedules.create({
+  name: 'hazo_files_purge',
+  cron: '30 3 * * *',
+  type: HAZO_FILES_JOB_TYPES.PURGE_PLAN,
+  payload: { retentionDays: 30 },
+});
+```
+
+**purge_plan**: Finds all `soft_deleted` records older than `retentionDays` and submits individual `purge_one` jobs. Supports `dryRun: true` to return `wouldPurge` list without deleting.
+
+**purge_one**: Hard-deletes a single file's physical storage and DB record. Idempotent — no-op if record not found.
+
+**Note**: Quota is decremented at soft-delete time, not at purge time.
+
+---
+
+## Image Processing
+
+Image resizing, thumbnail generation, and EXIF extraction are provided by the companion package `hazo_images`, which depends on `hazo_files` for storage.
+
+---
+
 ## Support
 
 - GitHub Issues: [https://github.com/pub12/hazo_files/issues](https://github.com/pub12/hazo_files/issues)

package/SETUP_CHECKLIST.md

@@ -1297,6 +1297,102 @@ Run through this final checklist to ensure everything is working:
 - Verify hazo_files/ui is imported correctly
 - Check browser console for errors
 
+## Part 9: V4 Setup (1.6.0 Features)
+
+### 9.1 Run Migrations 004-006
+
+- [ ] Add actor tracking columns:
+  ```bash
+  psql $DATABASE_URL < node_modules/hazo_files/migrations/004_changed_by.sql
+  psql $DATABASE_URL < node_modules/hazo_files/migrations/005_source_url.sql
+  ```
+  *(For SQLite: run the commented-out `ALTER TABLE` statements manually)*
+
+- [ ] Create quota tracking table:
+  ```bash
+  psql $DATABASE_URL < node_modules/hazo_files/migrations/006_quota_tracking.sql
+  ```
+
+### 9.2 Quota Tracking (optional)
+
+- [ ] Create CRUD service for `hazo_file_quotas`:
+  ```typescript
+  import { HAZO_FILE_QUOTAS_TABLE_SCHEMA } from 'hazo_files/server';
+
+  const quotaCrud = createCrudService(adapter, HAZO_FILE_QUOTAS_TABLE_SCHEMA.tableName, {
+    primaryKeys: ['scope_id'],
+    autoId: { enabled: false },
+  });
+  ```
+
+- [ ] Pass to server factory:
+  ```typescript
+  const { fileManager } = await createHazoFilesServer({
+    quotaCrudService: quotaCrud,
+    onQuotaThreshold: (event) => {
+      console.log(`Scope ${event.scopeId} at ${(event.percent * 100).toFixed(0)}%`);
+    },
+    // ... other options
+  });
+  ```
+
+- [ ] Set quota limits for scopes:
+  ```typescript
+  await fileManager.setQuotaLimit(scopeId, 10 * 1024 * 1024 * 1024); // 10 GB
+  ```
+
+### 9.3 URL Import / SSRF Guard (optional)
+
+- [ ] Install optional peer dependency:
+  ```bash
+  npm install hazo_secure
+  ```
+
+- [ ] Configure SSRF allowlist in factory:
+  ```typescript
+  const { fileManager } = await createHazoFilesServer({
+    ssrf: { allowlist: ['cdn.example.com', 'assets.myapp.com'] },
+    // ...
+  });
+  ```
+
+- [ ] Use `importFromUrl` in your API route:
+  ```typescript
+  const result = await fileManager.importFromUrl(url, '/imports/file.pdf', {
+    actor_id: userId,
+    maxBytes: 50 * 1024 * 1024,
+  });
+  ```
+
+### 9.4 Purge Scheduler via hazo_jobs (optional)
+
+- [ ] Install hazo_jobs (separate package):
+  ```bash
+  npm install hazo_jobs
+  ```
+
+- [ ] Register purge handlers with your worker:
+  ```typescript
+  import { createPurgeJobHandlers, HAZO_FILES_JOB_TYPES } from 'hazo_files/server';
+
+  const handlers = createPurgeJobHandlers(fm, {
+    submitJob: (type, payload) => jobs.submit({ type, payload }),
+  });
+
+  worker.register(HAZO_FILES_JOB_TYPES.PURGE_PLAN, handlers[HAZO_FILES_JOB_TYPES.PURGE_PLAN]);
+  worker.register(HAZO_FILES_JOB_TYPES.PURGE_ONE,  handlers[HAZO_FILES_JOB_TYPES.PURGE_ONE]);
+  ```
+
+- [ ] Create recurring schedule:
+  ```typescript
+  await jobs.schedules.create({
+    name: 'hazo_files_purge',
+    cron: '30 3 * * *',   // 3:30 AM daily
+    type: HAZO_FILES_JOB_TYPES.PURGE_PLAN,
+    payload: { retentionDays: 30 },
+  });
+  ```
+
 ## Next Steps
 
 - [ ] Review [README.md](README.md) for advanced usage examples

package/dist/index.d.mts

@@ -187,6 +187,10 @@ interface FileMetadataInput {
     original_filename?: string;
     /** Content tag classifying the document type (V3) */
     content_tag?: string;
+    /** Actor UUID who performed this mutation (V4) */
+    changed_by?: string;
+    /** Source URL when file was imported via importFromUrl (V4) */
+    source_url?: string;
 }
 /**
  * Input for updating an existing metadata record
@@ -433,6 +437,10 @@ interface FileMetadataRecordV2 extends FileMetadataRecord {
     deleted_at?: string | null;
     /** Content tag classifying the document type (V3) */
     content_tag?: string | null;
+    /** Actor UUID who last mutated this record (V4 — migration 004) */
+    changed_by?: string | null;
+    /** Source URL when file was imported via importFromUrl (V4 — migration 005) */
+    source_url?: string | null;
 }
 /**
  * Options for adding a reference to a file
@@ -770,8 +778,9 @@ declare class FileMetadataService {
     recordAccess(path: string, storageType: StorageProvider): Promise<boolean>;
     /**
      * Record a file deletion
+     * changedBy is accepted for API consistency but not written (record is deleted)
      */
-    recordDelete(path: string, storageType: StorageProvider): Promise<boolean>;
+    recordDelete(path: string, storageType: StorageProvider, _changedBy?: string): Promise<boolean>;
     /**
      * Record a directory deletion (recursive)
      */
@@ -779,11 +788,11 @@ declare class FileMetadataService {
     /**
      * Record a file or folder move
      */
-    recordMove(sourcePath: string, destinationPath: string, storageType: StorageProvider): Promise<boolean>;
+    recordMove(sourcePath: string, destinationPath: string, storageType: StorageProvider, changedBy?: string): Promise<boolean>;
     /**
      * Record a file or folder rename
      */
-    recordRename(path: string, newName: string, storageType: StorageProvider): Promise<boolean>;
+    recordRename(path: string, newName: string, storageType: StorageProvider, changedBy?: string): Promise<boolean>;
     /**
      * Find a record by path and storage type
      */
@@ -887,9 +896,9 @@ declare class FileMetadataService {
      */
     softDelete(fileId: string): Promise<boolean>;
     /**
-     * Update specific V2 fields on a record
+     * Update specific V2/V4 fields on a record
      */
-    updateFields(fileId: string, fields: Partial<Pick<FileMetadataRecordV2, 'scope_id' | 'uploaded_by' | 'original_filename' | 'storage_verified_at' | 'status' | 'content_tag'>>): Promise<boolean>;
+    updateFields(fileId: string, fields: Partial<Pick<FileMetadataRecordV2, 'scope_id' | 'uploaded_by' | 'original_filename' | 'storage_verified_at' | 'status' | 'content_tag' | 'changed_by' | 'source_url'>>): Promise<boolean>;
     /**
      * Find orphaned files (zero references)
      */
@@ -1053,6 +1062,138 @@ declare function createFileManager(options?: FileManagerOptions): FileManager;
  */
 declare function createInitializedFileManager(options?: FileManagerOptions): Promise<FileManager>;
 
+/**
+ * Quota Service
+ * Per-scope opt-in quota tracking with threshold callbacks.
+ *
+ * A scope without a hazo_file_quotas row has no quota and uploads succeed (fail-open).
+ */
+/**
+ * Quota status for a scope
+ */
+interface QuotaStatus {
+    scopeId: string;
+    byteLimit: number;
+    byteUsed: number;
+    percentUsed: number;
+}
+/**
+ * Event emitted when usage crosses a configured threshold band
+ */
+interface QuotaThresholdEvent {
+    scopeId: string;
+    /** Fractional threshold crossed, e.g. 0.80 or 0.95 */
+    percent: number;
+    bytesUsed: number;
+    byteLimit: number;
+}
+/**
+ * Raw row shape from hazo_file_quotas table
+ */
+interface QuotaRow {
+    scope_id: string;
+    byte_limit: number;
+    byte_used: number;
+    updated_at: string;
+    [key: string]: unknown;
+}
+/**
+ * Minimal interface for the quota CRUD service (hazo_connect compatible)
+ */
+interface QuotaCrudServiceLike {
+    findBy(criteria: Record<string, unknown>): Promise<QuotaRow[]>;
+    findOneBy(criteria: Record<string, unknown>): Promise<QuotaRow | null>;
+    insert(data: Partial<QuotaRow> | Partial<QuotaRow>[]): Promise<QuotaRow[]>;
+    updateById(id: unknown, patch: Partial<QuotaRow>): Promise<QuotaRow[]>;
+    list(configure?: (qb: unknown) => unknown): Promise<QuotaRow[]>;
+}
+/**
+ * Options for QuotaService
+ */
+interface QuotaServiceOptions {
+    /** hazo_connect CRUD service pointed at hazo_file_quotas table */
+    crudService: QuotaCrudServiceLike;
+    /** Callback fired when usage crosses a threshold band */
+    onThreshold?: (event: QuotaThresholdEvent) => void;
+    /** Fractional threshold bands (default: [0.80, 0.95]) */
+    bands?: number[];
+    /** Logger for diagnostics */
+    logger?: {
+        debug?(message: string, data?: Record<string, unknown>): void;
+        warn?(message: string, data?: Record<string, unknown>): void;
+        error?(message: string, data?: Record<string, unknown>): void;
+    };
+}
+/**
+ * Per-scope opt-in quota tracking.
+ *
+ * Fail-open: a scope without a quota row has no quota and all uploads succeed.
+ */
+declare class QuotaService {
+    private crud;
+    private onThreshold?;
+    private bands;
+    private logger?;
+    constructor(opts: QuotaServiceOptions);
+    /**
+     * Get quota status for a scope.
+     * Returns null if no quota row exists (fail-open = no quota set).
+     */
+    getQuota(scopeId: string): Promise<QuotaStatus | 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.
+     */
+    setQuotaLimit(scopeId: string, bytes: number): Promise<QuotaStatus>;
+    /**
+     * 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.)
+     */
+    recomputeQuota(scopeId: string): Promise<QuotaStatus>;
+    /**
+     * 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.
+     */
+    checkQuota(scopeId: string, deltaBytes: number): Promise<void>;
+    /**
+     * 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.
+     */
+    checkAndIncrement(scopeId: string, deltaBytes: number): Promise<void>;
+    /**
+     * Decrement usage (call after soft-delete or hard-delete).
+     * Clamps to zero; no-ops if no quota row.
+     */
+    decrementUsage(scopeId: string, deltaBytes: number): Promise<void>;
+    /**
+     * Increment usage manually (admin override).
+     * Does NOT throw on exceeded quota — admin is explicitly bypassing.
+     */
+    incrementUsage(scopeId: string, deltaBytes: number): Promise<void>;
+    /**
+     * Fire threshold callbacks for all bands crossed going from prevUsed → newUsed.
+     * Bands are sorted ascending so callbacks fire in order (80% before 95%).
+     */
+    private fireThresholdCallbacks;
+    private rowToStatus;
+}
+
 /**
  * Tracked File Manager
  * Extends FileManager to add database tracking of file operations
@@ -1068,6 +1209,10 @@ interface TrackedFileManagerFullOptions extends FileManagerOptions {
     tracking?: DatabaseTrackingConfig;
     /** Logger for structured file operation logging */
     logger?: MetadataLogger;
+    /** Optional quota service for per-scope upload limits */
+    quotaService?: QuotaService;
+    /** SSRF allowlist passed to importFromUrl (host strings) */
+    ssrfAllowlist?: string[];
 }
 /**
  * Extended upload options with hash tracking
@@ -1081,6 +1226,10 @@ interface TrackedUploadOptions extends UploadOptions {
      * Set to true when you need to immediately query/update the file record.
      */
     awaitRecording?: boolean;
+    /** Actor ID (UUID) to record in uploaded_by and changed_by columns */
+    actor_id?: string;
+    /** Scope ID for quota tracking and organizational grouping */
+    scope_id?: string;
 }
 /**
  * TrackedFileManager - File manager with database tracking
@@ -1091,6 +1240,8 @@ interface TrackedUploadOptions extends UploadOptions {
 declare class TrackedFileManager extends FileManager {
     private metadataService;
     private trackingConfig;
+    private quotaService;
+    private ssrfAllowlist;
     constructor(options?: TrackedFileManagerFullOptions);
     /**
      * Check if tracking is enabled and service is available
@@ -1120,19 +1271,27 @@ declare class TrackedFileManager extends FileManager {
     /**
      * Move a file or folder and update its path in the database
      */
-    moveItem(sourcePath: string, destinationPath: string, options?: MoveOptions): Promise<OperationResult<FileSystemItem>>;
+    moveItem(sourcePath: string, destinationPath: string, options?: MoveOptions & {
+        actor_id?: string;
+    }): Promise<OperationResult<FileSystemItem>>;
     /**
      * Delete a file and remove its record from the database
      */
-    deleteFile(path: string): Promise<OperationResult>;
+    deleteFile(path: string, opts?: {
+        actor_id?: string;
+    }): Promise<OperationResult>;
     /**
      * Rename a file and update its record in the database
      */
-    renameFile(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FileItem>>;
+    renameFile(path: string, newName: string, options?: RenameOptions & {
+        actor_id?: string;
+    }): Promise<OperationResult<FileItem>>;
     /**
      * Rename a folder and update its record in the database
      */
-    renameFolder(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FolderItem>>;
+    renameFolder(path: string, newName: string, options?: RenameOptions & {
+        actor_id?: string;
+    }): Promise<OperationResult<FolderItem>>;
     /**
      * Write a file with string content and track it
      */
@@ -1211,8 +1370,33 @@ declare class TrackedFileManager extends FileManager {
     getFilesById(fileIds: string[]): Promise<FileWithStatus[]>;
     /**
      * Soft-delete a file (marks as soft_deleted, does not remove physical file)
+     * Also decrements quota usage if quotaService is configured.
+     */
+    softDeleteFile(fileId: string, opts?: {
+        actor_id?: string;
+    }): Promise<boolean>;
+    /**
+     * Get quota status for a scope.
+     * Returns null if no quota is configured (fail-open).
+     */
+    getQuota(scopeId: string): Promise<QuotaStatus | null>;
+    /**
+     * Set or update the byte limit for a scope.
+     * Creates a quota row if one does not exist.
+     */
+    setQuotaLimit(scopeId: string, bytes: number): Promise<QuotaStatus | null>;
+    /**
+     * Recompute and return the quota status for a scope.
      */
-    softDeleteFile(fileId: string): Promise<boolean>;
+    recomputeQuota(scopeId: string): Promise<QuotaStatus | null>;
+    /**
+     * Increment usage for a scope (admin override — does not throw on exceeded quota).
+     */
+    incrementQuotaUsage(scopeId: string, deltaBytes: number): Promise<void>;
+    /**
+     * Decrement usage for a scope (e.g. after manual cleanup).
+     */
+    decrementQuotaUsage(scopeId: string, deltaBytes: number): Promise<void>;
     /**
      * Find orphaned files (files with zero references)
      */
@@ -1235,6 +1419,31 @@ declare class TrackedFileManager extends FileManager {
         file_id?: string;
         ref_id?: string;
     }>>;
+    /**
+     * 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
+     */
+    importFromUrl(url: string, virtualPath: string, opts?: {
+        referrer?: string;
+        maxBytes?: number;
+        actor_id?: string;
+        /** Scope ID for quota checking and tracking. If provided, quota is checked before upload. */
+        scope_id?: string;
+    }): Promise<OperationResult<{
+        virtualPath: string;
+        size: number;
+        sourceUrl: string;
+    }>>;
 }
 /**
  * Create a new TrackedFileManager instance
@@ -1821,6 +2030,10 @@ interface HazoFilesColumnDefinitions {
     original_filename: 'TEXT';
     /** Content tag classifying the document type (V3) */
     content_tag: 'TEXT';
+    /** UUID of the actor who last mutated this record (V4 — migration 004) */
+    changed_by: 'TEXT' | 'UUID';
+    /** Source URL when file was imported via importFromUrl (V4 — migration 005) */
+    source_url: 'TEXT';
 }
 /**
  * Schema definition for a specific database type