hazo_files 1.5.2 → 2.0.0

package/dist/server/index.d.mts

@@ -1,3 +1,5 @@
+import { JobHandler } from 'hazo_jobs';
+import { Readable } from 'node:stream';
 import { OAuth2Client } from 'google-auth-library';
 
 /**
@@ -187,6 +189,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 +439,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 +780,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 +790,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 +898,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 +1064,142 @@ 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;
+}
+/**
+ * Create a QuotaService instance
+ */
+declare function createQuotaService(opts: QuotaServiceOptions): QuotaService;
+
 /**
  * Tracked File Manager
  * Extends FileManager to add database tracking of file operations
@@ -1068,6 +1215,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 +1232,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 +1246,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 +1277,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 +1376,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 +1425,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
@@ -1804,6 +2019,29 @@ interface HazoFilesServerOptions {
      * When set, uploads can automatically classify document content.
      */
     defaultContentTagConfig?: ContentTagConfig;
+    /**
+     * SSRF protection configuration for importFromUrl.
+     * When provided, only URLs matching the allowlist will be permitted.
+     */
+    ssrf?: {
+        /** Allowed host strings (e.g. ['example.com', 'cdn.myapp.com']) */
+        allowlist: string[];
+    };
+    /**
+     * CRUD service for the hazo_file_quotas table.
+     * Required if you want to use per-scope quota tracking.
+     */
+    quotaCrudService?: QuotaCrudServiceLike;
+    /**
+     * Callback fired when a quota threshold band is crossed.
+     * Receives scopeId, percent crossed, bytesUsed, and byteLimit.
+     */
+    onQuotaThreshold?: (event: QuotaThresholdEvent) => void;
+    /**
+     * Fractional threshold bands that trigger onQuotaThreshold.
+     * Default: [0.80, 0.95]
+     */
+    quotaBands?: number[];
 }
 /**
  * Result of createHazoFilesServer
@@ -1881,6 +2119,95 @@ declare function createHazoFilesServer(options?: HazoFilesServerOptions): Promis
  */
 declare function createBasicFileManager(config: HazoFilesConfig, crudService?: CrudServiceLike<FileMetadataRecord>): Promise<TrackedFileManager>;
 
+/**
+ * Purge Job Handlers
+ *
+ * Factory for hazo_jobs-compatible job handlers that perform file lifecycle purge operations.
+ * Uses types-only import from hazo_jobs — no runtime dependency.
+ *
+ * @example
+ * ```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]);
+ * ```
+ */
+
+/**
+ * Job type constants for hazo_files purge operations
+ */
+declare const HAZO_FILES_JOB_TYPES: {
+    readonly PURGE_PLAN: "hazo_files.purge_plan";
+    readonly PURGE_ONE: "hazo_files.purge_one";
+};
+type HazoFilesJobType = typeof HAZO_FILES_JOB_TYPES[keyof typeof HAZO_FILES_JOB_TYPES];
+/**
+ * Payload for the purge_plan job.
+ * Finds soft-deleted files older than retentionDays and schedules purge_one jobs.
+ */
+interface PurgePlanPayload {
+    /** Number of days after soft-delete before a file is eligible for purge. Default: 30 */
+    retentionDays?: number;
+    /**
+     * Dry-run mode: return wouldPurge list but do not submit any purge_one jobs
+     * and do not delete anything.
+     */
+    dryRun?: boolean;
+}
+/**
+ * Payload for the purge_one job.
+ * Hard-deletes a single soft-deleted file record and its physical storage.
+ */
+interface PurgeOnePayload {
+    fileId: string;
+}
+/**
+ * Result returned by the purge_plan handler
+ */
+interface PurgePlanResult {
+    /** Number of files purged (or queued for purge) */
+    purgedCount: number;
+    /**
+     * Populated only when dryRun: true.
+     * Array of fileIds that would be purged.
+     */
+    wouldPurge?: string[];
+}
+/**
+ * Options for the purge job handler factory
+ */
+interface PurgeJobHandlerOptions {
+    /**
+     * Function to submit a child job.
+     * When provided, purge_plan submits individual purge_one jobs via this function.
+     * When omitted, purge_plan returns the fileIds in the result and does not submit jobs.
+     */
+    submitJob?: (type: string, payload: unknown) => Promise<void>;
+    /** Logger for diagnostics */
+    logger?: {
+        info?(message: string, data?: Record<string, unknown>): void;
+        warn?(message: string, data?: Record<string, unknown>): void;
+        error?(message: string, data?: Record<string, unknown>): void;
+    };
+}
+/**
+ * Create purge job handlers for hazo_files lifecycle management.
+ *
+ * The handlers are compatible with hazo_jobs JobHandler<TPayload, TResult>.
+ *
+ * @param fm - TrackedFileManager instance
+ * @param opts - Optional submitJob function and logger
+ */
+declare function createPurgeJobHandlers(fm: TrackedFileManager, opts?: PurgeJobHandlerOptions): {
+    [HAZO_FILES_JOB_TYPES.PURGE_PLAN]: JobHandler<PurgePlanPayload, PurgePlanResult>;
+    [HAZO_FILES_JOB_TYPES.PURGE_ONE]: JobHandler<PurgeOnePayload>;
+};
+
 /**
  * Database Schema Exports for hazo_files
  *
@@ -1948,6 +2275,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
@@ -2170,6 +2501,169 @@ declare const HAZO_FILES_MIGRATION_V3: HazoFilesMigrationV3;
  * Get V3 migration statements for a custom table name
  */
 declare function getMigrationV3ForTable(tableName: string, dbType: 'sqlite' | 'postgres'): MigrationSchemaDefinition;
+/**
+ * Migration schema for adding V4 actor-tracking and source_url columns.
+ *
+ * @note PostgreSQL ALTER statements use `IF NOT EXISTS` and are idempotent.
+ *       SQLite `ALTER TABLE ADD COLUMN` does NOT support `IF NOT EXISTS` —
+ *       wrap each statement in a try/catch or check `PRAGMA table_info(hazo_files)`
+ *       before running on SQLite to avoid "duplicate column name" errors.
+ *
+ * @example
+ * ```typescript
+ * import { HAZO_FILES_MIGRATION_V4 } from 'hazo_files';
+ *
+ * // SQLite — wrap in try/catch (NOT idempotent)
+ * for (const stmt of HAZO_FILES_MIGRATION_V4.sqlite.alterStatements) {
+ *   try { await db.run(stmt); } catch { /* column already exists *\/ }
+ * }
+ *
+ * // PostgreSQL — idempotent (uses IF NOT EXISTS)
+ * for (const stmt of HAZO_FILES_MIGRATION_V4.postgres.alterStatements) {
+ *   await client.query(stmt);
+ * }
+ * for (const idx of HAZO_FILES_MIGRATION_V4.postgres.indexes) {
+ *   await client.query(idx);
+ * }
+ * ```
+ */
+interface HazoFilesMigrationV4 {
+    /** Default table name */
+    tableName: string;
+    /** SQLite migration statements */
+    sqlite: MigrationSchemaDefinition;
+    /** PostgreSQL migration statements */
+    postgres: MigrationSchemaDefinition;
+    /** New column names added in V4 */
+    newColumns: readonly string[];
+}
+declare const HAZO_FILES_MIGRATION_V4: HazoFilesMigrationV4;
+/**
+ * Get V4 migration statements for a custom table name
+ */
+declare function getMigrationV4ForTable(tableName: string, dbType: 'sqlite' | 'postgres'): MigrationSchemaDefinition;
+/**
+ * Default table name for quota tracking
+ */
+declare const HAZO_FILE_QUOTAS_DEFAULT_TABLE_NAME = "hazo_file_quotas";
+/**
+ * Column definitions for the hazo_file_quotas table
+ */
+interface HazoFileQuotasColumnDefinitions {
+    /** Scope ID — primary key, links to organizational unit */
+    scope_id: 'TEXT' | 'UUID';
+    /** Maximum allowed bytes for this scope */
+    byte_limit: 'INTEGER' | 'BIGINT';
+    /** Current bytes used (reconciled against actual file records) */
+    byte_used: 'INTEGER' | 'BIGINT';
+    /** ISO timestamp of last update */
+    updated_at: 'TEXT' | 'TIMESTAMP';
+}
+/**
+ * Schema definition for hazo_file_quotas table.
+ *
+ * Opt-in per-scope quota. A scope without a row has no quota (fail-open).
+ *
+ * @example
+ * ```typescript
+ * import { HAZO_FILE_QUOTAS_TABLE_SCHEMA } from 'hazo_files';
+ *
+ * // PostgreSQL
+ * await client.query(HAZO_FILE_QUOTAS_TABLE_SCHEMA.postgres.ddl);
+ * for (const idx of HAZO_FILE_QUOTAS_TABLE_SCHEMA.postgres.indexes) {
+ *   await client.query(idx);
+ * }
+ * ```
+ */
+declare const HAZO_FILE_QUOTAS_TABLE_SCHEMA: {
+    tableName: string;
+    sqlite: DatabaseSchemaDefinition;
+    postgres: DatabaseSchemaDefinition;
+    columns: readonly ["scope_id", "byte_limit", "byte_used", "updated_at"];
+};
+
+type StoragePath = string;
+interface PutOpts {
+    /** Reject if the target path already exists (atomic). */
+    ifNotExists?: boolean;
+    /** Hint for content-type; provider may sniff if absent. */
+    contentType?: string;
+    /** Free-form key/value metadata persisted with the file when supported. */
+    metadata?: Record<string, string>;
+}
+interface PutResult {
+    /** Provider tag — `"app_file_server"`, `"gdrive"`, `"in_memory"`. */
+    provider: string;
+    /** Provider-native identifier (path for app-server; file ID for GDrive). */
+    native_id: string;
+    /** Size in bytes of the persisted body. */
+    size: number;
+}
+interface SignedUrlOpts {
+    /** Seconds the URL is valid for. */
+    ttl_seconds?: number;
+    /** Suggested download filename (Content-Disposition). */
+    filename_hint?: string;
+}
+interface ProbeResult {
+    ok: boolean;
+    /** Machine-readable error tag when ok=false. */
+    error?: "drive_not_shared" | "write_denied" | "invalid_id" | "transient" | "config_missing";
+    /** Free-form detail for logging. */
+    message?: string;
+}
+/**
+ * Storage provider abstraction. Every method MUST be idempotent at the
+ * data-content level — re-invoking put with identical body is allowed.
+ *
+ * Paths are logical; providers translate to native identifiers internally.
+ */
+interface FileStorageProvider {
+    put(path: StoragePath, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: StoragePath): Promise<Buffer | Readable>;
+    delete(path: StoragePath): Promise<void>;
+    exists(path: StoragePath): Promise<boolean>;
+    getSignedUrl(path: StoragePath, opts?: SignedUrlOpts): Promise<string>;
+    /** Used by validation cron + onboarding step 2. */
+    probe(): Promise<ProbeResult>;
+}
+declare class StorageCollisionExhausted extends Error {
+    attempts: number;
+    lastPath: StoragePath;
+    constructor(attempts: number, lastPath: StoragePath);
+}
+declare class StorageNotConfigured extends Error {
+    constructor();
+}
+declare class StorageUnavailable extends Error {
+    reason: ProbeResult["error"];
+    constructor(reason: ProbeResult["error"], message: string);
+}
+
+interface AppFileServerOpts {
+    /** Filesystem root. All paths are resolved relative to this. */
+    root: string;
+    /** HMAC secret used to sign download URLs. */
+    hmac_secret: string;
+    /** Default signed-URL TTL in seconds. */
+    default_ttl_seconds?: number;
+}
+declare class AppFileServerProvider implements FileStorageProvider {
+    readonly provider_tag: "app_file_server";
+    private readonly root;
+    private readonly secret;
+    private readonly default_ttl;
+    constructor(opts: AppFileServerOpts);
+    private resolve;
+    put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, opts?: SignedUrlOpts): Promise<string>;
+    /** Verify a token produced by `getSignedUrl`. Used by the `/api/files/serve` route. */
+    verifySignedUrl(token: string, path: string): boolean;
+    probe(): Promise<ProbeResult>;
+}
 
 /**
  * Migration: Add Reference Tracking (V2)
@@ -2853,6 +3347,15 @@ declare class ConfigurationError extends HazoFilesError {
 declare class OperationError extends HazoFilesError {
     constructor(operation: string, message: string, details?: Record<string, unknown>);
 }
+declare class QuotaExceededError extends HazoFilesError {
+    constructor(scopeId: string, byteUsed: number, byteLimit: number, deltaBytes: number);
+}
+declare class SSRFError extends HazoFilesError {
+    constructor(url: string, reason: string);
+}
+declare class ImportSizeCapError extends HazoFilesError {
+    constructor(url: string, capBytes: number);
+}
 
 /**
  * MIME type utilities
@@ -3225,4 +3728,4 @@ declare function toV2Record(record: FileMetadataRecord): FileMetadataRecordV2;
  */
 declare function buildFileWithStatus(record: FileMetadataRecord): FileWithStatus;
 
-export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, DropboxAuth, type DropboxAuthCallbacks, type DropboxAuthConfig, type DropboxConfig, DropboxModule, type DropboxTokenData, type ExtractionData, type ExtractionOptions, type ExtractionResult, type FileBrowserState, type FileDataStructure, FileExistsError, type FileInfo, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, type FileMetadataRecordV2, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, FileNotFoundError, type FileRef, type FileRefVisibility, type FileStatus, type FileSystemItem, FileTooLargeError, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_MIGRATION_V2, HAZO_FILES_MIGRATION_V3, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesServerInstance, type HazoFilesServerOptions, type HazoFilesTableSchema, type HazoLLMInstance, type HazoLogger, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMFactoryConfig, type LLMProvider, type ListNamingConventionsOptions, type ListOptions, type LocalStorageConfig, LocalStorageModule, type MetadataLogger, type MigrationExecutor, type MigrationSchemaDefinition, type MoveOptions, type NameGenerationOptions, type NamingConventionInput, type NamingConventionRecord, NamingConventionService, type NamingConventionServiceOptions, type NamingConventionType, type NamingConventionUpdate, type NamingRuleConfiguratorProps, type NamingRuleHistoryEntry, type NamingRuleSchema, type NamingVariable, OperationError, type OperationResult, type ParsedNamingConvention, type PatternSegment, PermissionDeniedError, type ProgressCallback, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type StorageModule, type StorageProvider, type TokenData, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TrackedUploadOptions, type TreeNode, type UploadExtractOptions, type UploadExtractResult, UploadExtractService, type UploadOptions, type UploadWithRefOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, addExtractionToFileData, backfillV2Defaults, buildFileWithStatus, clearExtractions, clonePattern, computeFileHash, computeFileHashFromStream, computeFileHashSync, computeFileInfo, createAndInitializeModule, createBasicFileManager, createDropboxAuth, createDropboxModule, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createHazoFilesServer, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createTrackedFileManager, createUploadExtractService, createVariableSegment, deepMerge, errorResult, filterItems, formatBytes, formatCounter, formatDateToken, generateExtractionId, generateId, generatePreviewName, generateRefId, generateSampleConfig, generateSegmentId, getBaseName, getBreadcrumbs, getDirName, getExtension, getExtensionFromMime, getExtractionById, getExtractionCount, getExtractions, getFileCategory, getFileMetadataValues, getMergedData, getMigrationForTable, getMigrationV3ForTable, getMimeType, getNameWithoutExtension, getNamingSchemaForTable, getParentPath, getPathSegments, getRegisteredProviders, getRelativePath, getSchemaForTable, getSystemVariablePreviewValues, hasExtension, hasExtractionStructure, hasFileContentChanged, hashesEqual, hazo_files_generate_file_name, hazo_files_generate_folder_name, isAudio, isChildPath, isCounterVariable, isDateVariable, isDocument, isFile, isFileMetadataVariable, isFolder, isImage, isPreviewable, isProviderRegistered, isText, isVideo, joinPath, loadConfig, loadConfigAsync, migrateToV2, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath };
+export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AppFileServerOpts, AppFileServerProvider, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, DropboxAuth, type DropboxAuthCallbacks, type DropboxAuthConfig, type DropboxConfig, DropboxModule, type DropboxTokenData, type ExtractionData, type ExtractionOptions, type ExtractionResult, type FileBrowserState, type FileDataStructure, FileExistsError, type FileInfo, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, type FileMetadataRecordV2, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, FileNotFoundError, type FileRef, type FileRefVisibility, type FileStatus, type FileStorageProvider, type FileSystemItem, FileTooLargeError, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, 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, type HazoFileQuotasColumnDefinitions, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesJobType, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesMigrationV4, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesServerInstance, type HazoFilesServerOptions, type HazoFilesTableSchema, type HazoLLMInstance, type HazoLogger, ImportSizeCapError, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMFactoryConfig, type LLMProvider, type ListNamingConventionsOptions, type ListOptions, type LocalStorageConfig, LocalStorageModule, type MetadataLogger, type MigrationExecutor, type MigrationSchemaDefinition, type MoveOptions, type NameGenerationOptions, type NamingConventionInput, type NamingConventionRecord, NamingConventionService, type NamingConventionServiceOptions, type NamingConventionType, type NamingConventionUpdate, type NamingRuleConfiguratorProps, type NamingRuleHistoryEntry, type NamingRuleSchema, type NamingVariable, OperationError, type OperationResult, type ParsedNamingConvention, type PatternSegment, PermissionDeniedError, type ProbeResult, type ProgressCallback, type PurgeJobHandlerOptions, type PurgeOnePayload, type PurgePlanPayload, type PurgePlanResult, type PutOpts, type PutResult, type QuotaCrudServiceLike, QuotaExceededError, QuotaService, type QuotaServiceOptions, type QuotaStatus, type QuotaThresholdEvent, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SSRFError, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type SignedUrlOpts, StorageCollisionExhausted, type StorageModule, StorageNotConfigured, type StoragePath, type StorageProvider, StorageUnavailable, type TokenData, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TrackedUploadOptions, type TreeNode, type UploadExtractOptions, type UploadExtractResult, UploadExtractService, type UploadOptions, type UploadWithRefOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, addExtractionToFileData, backfillV2Defaults, buildFileWithStatus, clearExtractions, clonePattern, computeFileHash, computeFileHashFromStream, computeFileHashSync, computeFileInfo, createAndInitializeModule, createBasicFileManager, createDropboxAuth, createDropboxModule, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createHazoFilesServer, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createPurgeJobHandlers, createQuotaService, createTrackedFileManager, createUploadExtractService, createVariableSegment, deepMerge, errorResult, filterItems, formatBytes, formatCounter, formatDateToken, generateExtractionId, generateId, generatePreviewName, generateRefId, generateSampleConfig, generateSegmentId, getBaseName, getBreadcrumbs, getDirName, getExtension, getExtensionFromMime, getExtractionById, getExtractionCount, getExtractions, getFileCategory, getFileMetadataValues, getMergedData, getMigrationForTable, getMigrationV3ForTable, getMigrationV4ForTable, getMimeType, getNameWithoutExtension, getNamingSchemaForTable, getParentPath, getPathSegments, getRegisteredProviders, getRelativePath, getSchemaForTable, getSystemVariablePreviewValues, hasExtension, hasExtractionStructure, hasFileContentChanged, hashesEqual, hazo_files_generate_file_name, hazo_files_generate_folder_name, isAudio, isChildPath, isCounterVariable, isDateVariable, isDocument, isFile, isFileMetadataVariable, isFolder, isImage, isPreviewable, isProviderRegistered, isText, isVideo, joinPath, loadConfig, loadConfigAsync, migrateToV2, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath };