@wildo-ai/saas-backend-lib 1.1.2 → 1.1.3

package/dist/esm/files/services/file-scanning.backend.service.js

@@ -11,14 +11,30 @@
  * 5. Processes combined results (CLEAN / INFECTED)
  * 6. Quarantines infected files
  *
- * Scanning is **optimistic**: the upload response returns immediately
- * with status UPLOADED. The file becomes downloadable only after
- * transitioning to CLEAN (when scanning is enabled). If scanning is
- * disabled, the file stays at UPLOADED and remains downloadable.
+ * Scanning is **fail-closed at the gate, asynchronous in the pipeline** (#433). The upload handler
+ * AWAITS `initiateScan`, which awaits the UPLOADED -> SCANNING transition and only then fires the
+ * pipeline — so the upload response costs one status write, not a scan, and the file is already
+ * non-downloadable when the caller is told the upload succeeded. It becomes downloadable when the
+ * result handler transitions it to CLEAN.
+ *
+ * This paragraph used to say the response "returns immediately with status UPLOADED", and that was
+ * the defect: UPLOADED is a downloadable status, so a field declaring `scanPolicy: 'required'` had
+ * a window in which unscanned bytes were servable. If scanning is not required for the field, the
+ * file stays at UPLOADED and remains downloadable — that half is unchanged and deliberate.
  *
  * Configuration:
- * - Global: `appConfig.files.scanning.enabled` (default: false)
- * - Per-field: `z_file({ scanPolicy: 'required' | 'skip' })` overrides global
+ * - Application-wide: DERIVED, not declared. Scanning is on for a field that states no policy of its
+ *   own exactly when a scanner is reachable — `fileScanning.antivirus` (seeded from `CLAMAV_HOST`) or
+ *   `fileScanning.yara` both enabled and reachable (`YARA_ENABLED` + `YARA_HOST`). Provisioning the
+ *   sidecar IS the application-level opt-in; there is no separate on/off flag. See
+ *   {@link FileScanningBackendService.isGlobalScanningEnabled} for why it is derived rather than declared.
+ * - Per-field: `z_file({ scanPolicy: 'required' | 'skip' })` overrides that, in both directions.
+ *
+ * These two lines used to name `appConfig.files.scanning.enabled`, a configuration path no schema has
+ * ever declared — so the application-wide half was documented, cast through `any`, and dead.
+ *
+ * A scan that was REQUESTED and finds no scanner now FAILS the file rather than passing it; the tail of
+ * `executeScan` carries the reasoning.
  */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -32,7 +48,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { injectable, inject } from 'inversify';
+import { injectable, inject, optional } from 'inversify';
 import { ErrorType, ErrorCustomMessageReference, FileStatus, FILE_STATUS_TRANSITIONS, } from '@wildo-ai/saas-models';
 import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
 import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service.js';
@@ -55,9 +71,10 @@ let FileScanningBackendService = class FileScanningBackendService {
     clamavScanner;
     yaraScanner;
     fileStorageRouter;
+    auditLogsService;
     logDebug;
     onCleanCallbacks = new Map();
-    constructor(logger, errorBuilder, filesService, appConfigService, clamavScanner, yaraScanner, fileStorageRouter) {
+    constructor(logger, errorBuilder, filesService, appConfigService, clamavScanner, yaraScanner, fileStorageRouter, auditLogsService) {
         this.logger = logger;
         this.errorBuilder = errorBuilder;
         this.filesService = filesService;
@@ -65,6 +82,7 @@ let FileScanningBackendService = class FileScanningBackendService {
         this.clamavScanner = clamavScanner;
         this.yaraScanner = yaraScanner;
         this.fileStorageRouter = fileStorageRouter;
+        this.auditLogsService = auditLogsService;
         this.logDebug = this.logger.debugByType('FileScanningBackendService');
     }
     /**
@@ -72,7 +90,17 @@ let FileScanningBackendService = class FileScanningBackendService {
      *
      * Resolution order:
      * 1. Per-field `z_file({ scanPolicy })` wins if set
-     * 2. Falls back to global `appConfig.files.scanning.enabled`
+     * 2. Falls back to the application-wide answer, {@link isGlobalScanningEnabled}
+     *
+     * assurance-control: WILDO.SECURITY.INGESTED_CONTENT_INSPECTION — whether ingested content is
+     * inspected is a declared decision, per field and then per application, rather than an implicit one.
+     *
+     * The per-APPLICATION half of that claim was false until 2026-09-09: step 2 read a configuration path
+     * no schema declares, so it answered `false` in every application ever built and `scanPolicy` was the
+     * only reachable declaration. It is true now because the application-wide answer is DERIVED from the
+     * scanner topology the operator provisions — a declaration made by supplying `CLAMAV_HOST`, and
+     * refused a default. Nothing here is implicit in either direction: a field can still override, and a
+     * requested scan with no scanner refuses rather than passing (see the tail of `executeScan`).
      */
     shouldScan(fileMetadata) {
         const scanPolicy = fileMetadata?.scanPolicy;
@@ -83,13 +111,54 @@ let FileScanningBackendService = class FileScanningBackendService {
         return this.isGlobalScanningEnabled();
     }
     /**
-     * Check if global scanning is enabled in the app configuration.
+     * Whether scanning is on APPLICATION-WIDE, for a file field that states no `scanPolicy` of its own.
+     *
+     * DERIVED from the platform-injected `fileScanning` topology: a scanner being reachable IS the
+     * application-level opt-in.
+     *
+     * ## What this replaced
+     *
+     * `(this.appConfigService.config as Record<string, any>)?.files?.scanning?.enabled === true`. The
+     * `any` cast is the tell — `AppConfigurationSchema` declares no `files` section, `z.object` strips
+     * unknown keys, so the parsed configuration could never carry that path and the expression was
+     * `undefined === true` for every application, for the whole life of the flag. The service's own
+     * docstring documented it as the global switch.
+     *
+     * ## Why DERIVED rather than declared
+     *
+     * Adding an `enabled` boolean to `AppConfiguration_FileScanningSchema` was the other candidate and is
+     * rejected on three counts:
+     *
+     *  - **the answer already exists.** `fileScanning` is a mutation-boundary-PROTECTED section
+     *    (`APP_CONFIG_MUTATION_BOUNDARY_RULES` in `app-config.backend-authored.definitions.ts`: "file-scanning
+     *    sidecar topology and its platform-level opt-in are env/bootstrap-owned"), so an application cannot
+     *    author it. A boolean would have to be seeded from a NEW environment key sitting beside the host key
+     *    that already says the same thing — a second source of truth that can disagree with the first;
+     *  - **it matches the convention of the thing it gates.** ClamAV has no enable flag anywhere in this
+     *    subsystem: `ClamAVScannerBackendService.isConfigured()` states "presence of a host IS the opt-in",
+     *    and `buildFileServicesTopologyFromEnvironment` refuses to emit a plausible default host for exactly
+     *    that reason;
+     *  - **it closes the hole the repair would otherwise open.** A separate boolean makes "globally on, no
+     *    scanner reachable" a REPRESENTABLE state, and that state is precisely the one the pipeline used to
+     *    answer with a CLEAN verdict. Derived, the state cannot exist: the switch is on only when something
+     *    can actually run. The runtime refusal in `executeScan` stays regardless, because `scanPolicy:
+     *    'required'` reaches the same tail without consulting this switch at all.
+     *
+     * The two predicates are the pipeline's OWN — `executeScan` gates its two layers on exactly
+     * `clamavScanner.isConfigured()` and `yaraScanner.isEnabled()` — so the switch and the pipeline cannot
+     * come to different conclusions about whether a scan is possible. Note `isEnabled()` is already the
+     * conjunction of YARA's two independent axes (opted in AND reachable), which is why the "enabled but
+     * unreachable" misconfiguration does not read as an application-wide opt-in here; the startup validator
+     * reports it as its own issue instead.
+     *
+     * The `isInitialized()` guard stays: both scanner reads deliberately throw
+     * `app_configuration_not_initialized` rather than softening to `false`, and a scan decision taken before
+     * configuration has landed is not a decision.
      */
     isGlobalScanningEnabled() {
         if (!this.appConfigService.isInitialized())
             return false;
-        const filesConfig = this.appConfigService.config?.files;
-        return filesConfig?.scanning?.enabled === true;
+        return this.clamavScanner.isConfigured() || this.yaraScanner.isEnabled();
     }
     /**
      * Initiate scanning for a file that just reached UPLOADED status.
@@ -243,13 +312,46 @@ let FileScanningBackendService = class FileScanningBackendService {
                 }
             }
         }
-        // ── All layers passed ──────────────────────────────────────────────
-        if (!this.clamavScanner.isConfigured() && !this.yaraScanner.isEnabled()) {
-            this.logger.warn('No scanners configured — marking as CLEAN', { fileId });
+        // ── Nothing ran: refuse, do not certify ────────────────────────────
+        //
+        // This branch used to log a warning and then hand `handleScanResult` a CLEAN verdict with
+        // `scannerRef: 'none'` — which transitions the file to `FileStatus.CLEAN`, a member of
+        // `FILE_DOWNLOADABLE_STATUSES`. A scan had been REQUESTED (`shouldScan` said yes, `initiateScan`
+        // moved the file to SCANNING, the uploader was told the upload succeeded), and the answer returned
+        // was the answer a PASSING scan gives, produced by no scanner. That is strictly worse than not
+        // scanning at all: a field declaring `scanPolicy: 'required'` ended with bytes certified clean, and
+        // the only trace was a warning in a log nobody reads.
+        //
+        // ERROR -> `FileStatus.FAILED` is the fail-closed terminal, and the right one rather than merely the
+        // safe one: FAILED is outside `FILE_DOWNLOADABLE_STATUSES` so the bytes are blocked, it is outside
+        // `FILE_METADATA_WITHHELD_STATUSES` so the uploader can still poll and see WHY, and
+        // `FILE_STATUS_TRANSITIONS` keeps SCANNING -> FAILED, so nothing about the lifecycle has to move.
+        // A file that failed this way becomes scannable again the moment a scanner is provisioned.
+        //
+        // Keyed on `executedScannerLayers` — direct evidence that nothing ran — rather than on re-asking the
+        // two `isConfigured()` predicates. Re-asking would be a second copy of the decision the two layer
+        // gates above already took, and the copies can disagree if a layer ever grows another skip reason.
+        //
+        // Not redundant with the boot gate, which is the obvious objection. `collectScanningIssues` refuses
+        // to start an application whose fields declare `scanPolicy: 'required'` when ClamAV is unconfigured,
+        // so in a well-formed deployment this branch is unreachable. But that gate builds its population by
+        // walking every resource's file fields inside `try { … } catch { continue; }`: a resource whose field
+        // detection throws contributes no fields and is silently absent from the count. A boot check that can
+        // under-report the population it protects is not a substitute for the refusal at the site itself.
+        if (executedScannerLayers.length === 0) {
+            await this.handleScanResult(fileId, {
+                verdict: FileScanVerdict.ERROR,
+                errorMessage: 'Scan was requested but no scanner is configured (no ClamAV host, and YARA not enabled/reachable) — refusing to certify the file as clean',
+                scannerRef: 'none',
+            }, executionContext);
+            return;
         }
+        // ── All layers that ran, passed ────────────────────────────────────
+        // `join('+')` needs no `|| 'none'` fallback any more: the empty case returned above, so a CLEAN
+        // verdict from here always names at least one scanner that actually executed.
         await this.handleScanResult(fileId, {
             verdict: FileScanVerdict.CLEAN,
-            scannerRef: executedScannerLayers.join('+') || 'none',
+            scannerRef: executedScannerLayers.join('+'),
         }, executionContext);
     }
     /**
@@ -267,6 +369,19 @@ let FileScanningBackendService = class FileScanningBackendService {
             scannerRef: result.scannerRef,
             durationMs: result.durationMs,
         });
+        /*
+         * assurance-control: WILDO.SECURITY.INGESTED_CONTENT_INSPECTION — the scanner's verdict becomes a
+         * member of `FileStatus`, which is also what `FILE_DOWNLOADABLE_STATUSES` reads, so "inspected" and
+         * "servable" are one decision rather than two that could disagree. `FileScanVerdict` names the
+         * scanner's answer; `FileStatus` is the one with consequence, which is why the assurance capability
+         * derives from it.
+         *
+         * The outcome now ALSO reaches the audit trail (#506): `FILE_MALWARE_DETECTED` when a scanner
+         * concludes an infection, `FILE_MALWARE_SCAN_FAILED` when the scan could not run. Both are
+         * emitted AFTER the terminal transition, so the row can never describe a state the record does
+         * not hold. Until they existed, an infection produced a status change and nothing else — the only
+         * way to learn malware had arrived was to notice a row sitting at `QUARANTINED`.
+         */
         switch (result.verdict) {
             case FileScanVerdict.CLEAN:
                 await this.filesService.updateFileStatus(fileId, FileStatus.CLEAN, executionContext);
@@ -296,6 +411,9 @@ let FileScanningBackendService = class FileScanningBackendService {
                     scannerRef: result.scannerRef,
                 });
                 await this.quarantineInfectedFile(fileId, result, executionContext);
+                // AFTER the quarantine transition, so `fileStatus` is what the record holds rather than what
+                // this method intended. If the quarantine failed, the row says INFECTED, which is true.
+                await this.recordScanOutcomeAudit(fileId, result, executionContext);
                 break;
             case FileScanVerdict.ERROR:
                 this.onCleanCallbacks.delete(fileId);
@@ -305,9 +423,69 @@ let FileScanningBackendService = class FileScanningBackendService {
                     scannerRef: result.scannerRef,
                 });
                 await this.filesService.updateFileStatus(fileId, FileStatus.FAILED, executionContext);
+                await this.recordScanOutcomeAudit(fileId, result, executionContext);
                 break;
         }
     }
+    /**
+     * Write the scan outcome to the audit trail (#506).
+     *
+     * Best-effort and never throwing: the file's status transition is the enforcement, and an audit
+     * store being unavailable must not convert a successful quarantine into an exception that leaves
+     * the caller believing the scan failed.
+     *
+     * A CLEAN verdict is deliberately NOT audited. Every upload is scanned, so a clean row per upload
+     * would be the highest-volume event in the trail and would bury the two that matter — and the
+     * upload itself is already recorded by `FILE_UPLOAD_GRANT_REDEEMED`. What is added here is the
+     * conclusion an operator would want to be alerted on.
+     */
+    async recordScanOutcomeAudit(fileId, result, executionContext) {
+        if (!this.auditLogsService)
+            return;
+        try {
+            // Re-read rather than assume: the transition may have failed, and the audit row must describe
+            // the record, not the intent.
+            const fileStatus = await this.resolveRecordedFileStatus(fileId, executionContext);
+            const organizationId = executionContext.initiatorIds?.organizationId;
+            const userId = executionContext.initiatorIds?.userId;
+            if (result.verdict === FileScanVerdict.INFECTED) {
+                await this.auditLogsService.logFileMalwareDetected({
+                    fileId,
+                    scannerRef: result.scannerRef,
+                    threatName: result.threatName,
+                    organizationId,
+                    userId,
+                    fileStatus,
+                }, executionContext);
+                return;
+            }
+            await this.auditLogsService.logFileMalwareScanFailed({
+                fileId,
+                scannerRef: result.scannerRef,
+                failureReason: result.errorMessage,
+                organizationId,
+                userId,
+                fileStatus,
+            }, executionContext);
+        }
+        catch (error) {
+            this.logger.warn('Failed to record the file scan outcome in the audit trail', {
+                fileId,
+                verdict: result.verdict,
+                ...projectCaughtErrorLogFields(error),
+            });
+        }
+    }
+    /** The status the FILES row actually carries after the transition, or `unknown` if it cannot be read. */
+    async resolveRecordedFileStatus(fileId, executionContext) {
+        try {
+            const file = await this.filesService.getFile(fileId, executionContext);
+            return file?.status ?? 'unknown';
+        }
+        catch {
+            return 'unknown';
+        }
+    }
     /**
      * Quarantine an infected file.
      *
@@ -340,12 +518,14 @@ FileScanningBackendService = __decorate([
     __param(4, inject(SAAS_SERVICE_TYPES.ClamAVScannerService)),
     __param(5, inject(SAAS_SERVICE_TYPES.YaraScannerService)),
     __param(6, inject(SAAS_SERVICE_TYPES.FileStorageRouter)),
+    __param(7, inject(SAAS_SERVICE_TYPES.AuditLogsService)),
+    __param(7, optional()),
     __metadata("design:paramtypes", [Function, ErrorBuilderBackendService,
         FilesBackendService,
         AppConfigurationService,
         ClamAVScannerBackendService,
         YaraScannerBackendService,
-        FileStorageRouterBackendService])
+        FileStorageRouterBackendService, Function])
 ], FileScanningBackendService);
 export { FileScanningBackendService };
 //# sourceMappingURL=file-scanning.backend.service.js.map

package/dist/esm/files/services/file-scanning.backend.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-scanning.backend.service.js","sourceRoot":"","sources":["../../../../../src/files/services/file-scanning.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * File Scanning Backend Service\n *\n * Orchestrates antivirus scanning for uploaded files. After a file\n * reaches UPLOADED status, this service:\n *\n * 1. Transitions the file to SCANNING\n * 2. Downloads the file from storage\n * 3. Submits to ClamAV via TCP (signature-based)\n * 4. If ClamAV passes, submits to YARA via REST (pattern-based, optional)\n * 5. Processes combined results (CLEAN / INFECTED)\n * 6. Quarantines infected files\n *\n * Scanning is **optimistic**: the upload response returns immediately\n * with status UPLOADED. The file becomes downloadable only after\n * transitioning to CLEAN (when scanning is enabled). If scanning is\n * disabled, the file stays at UPLOADED and remains downloadable.\n *\n * Configuration:\n * - Global: `appConfig.files.scanning.enabled` (default: false)\n * - Per-field: `z_file({ scanPolicy: 'required' | 'skip' })` overrides global\n */\n\nimport { injectable, inject } from 'inversify';\nimport {\n  ErrorType,\n  ErrorCustomMessageReference,\n  FileStatus,\n  FILE_STATUS_TRANSITIONS,\n} from '@wildo-ai/saas-models';\nimport type { FileSchemaMetadata } from '@wildo-ai/zod-decorators';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport { describeCaughtError, projectCaughtErrorLogFields } from '~wildo-backend-lib/errors/utils/error-log-level-classification.backend.utils';\nimport { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\nimport { FilesBackendService } from '~wildo-backend-lib/files/services/files.backend.service';\nimport { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';\nimport { ClamAVScannerBackendService } from '~wildo-backend-lib/files/scanning/clamav-scanner.backend.service';\nimport {\n  FileScanVerdict,\n  type FileScanResult,\n} from '~wildo-backend-lib/files/scanning/file-scan.types';\nimport { YaraScannerBackendService } from '~wildo-backend-lib/files/scanning/yara-scanner.backend.service';\nimport { FileStorageRouterBackendService } from '~wildo-backend-lib/files/storage/file-storage-router.backend.service';\nexport {\n  FileScanVerdict,\n  type FileScanResult,\n} from '~wildo-backend-lib/files/scanning/file-scan.types';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Service\n// ─────────────────────────────────────────────────────────────────────────────\n\n@injectable()\nexport class FileScanningBackendService {\n  protected logDebug: (message: string, context?: Record<string, unknown>) => void;\n\n  private readonly onCleanCallbacks = new Map<string, () => Promise<void>>();\n\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger)\n    private readonly logger: LoggerService,\n    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService)\n    private readonly errorBuilder: ErrorBuilderBackendService,\n    @inject(SAAS_SERVICE_TYPES.FilesBackendService)\n    private readonly filesService: FilesBackendService,\n    @inject(SAAS_SERVICE_TYPES.AppConfigService)\n    private readonly appConfigService: AppConfigurationService,\n    @inject(SAAS_SERVICE_TYPES.ClamAVScannerService)\n    private readonly clamavScanner: ClamAVScannerBackendService,\n    @inject(SAAS_SERVICE_TYPES.YaraScannerService)\n    private readonly yaraScanner: YaraScannerBackendService,\n    @inject(SAAS_SERVICE_TYPES.FileStorageRouter)\n    private readonly fileStorageRouter: FileStorageRouterBackendService,\n  ) {\n    this.logDebug = this.logger.debugByType('FileScanningBackendService');\n  }\n\n  /**\n   * Determine whether a file should be scanned after upload.\n   *\n   * Resolution order:\n   * 1. Per-field `z_file({ scanPolicy })` wins if set\n   * 2. Falls back to global `appConfig.files.scanning.enabled`\n   */\n  shouldScan(fileMetadata?: FileSchemaMetadata): boolean {\n    const scanPolicy = fileMetadata?.scanPolicy;\n\n    if (scanPolicy === 'required') return true;\n    if (scanPolicy === 'skip') return false;\n\n    return this.isGlobalScanningEnabled();\n  }\n\n  /**\n   * Check if global scanning is enabled in the app configuration.\n   */\n  isGlobalScanningEnabled(): boolean {\n    if (!this.appConfigService.isInitialized()) return false;\n    const filesConfig = (this.appConfigService.config as Record<string, any>)?.files;\n    return filesConfig?.scanning?.enabled === true;\n  }\n\n  /**\n   * Initiate scanning for a file that just reached UPLOADED status.\n   *\n   * Transitions to SCANNING, then dispatches the scan job.\n   * The response is fire-and-forget: the caller does not wait for scan\n   * completion — scan results are processed asynchronously via\n   * `handleScanResult()`.\n   *\n   * @param onClean - Optional callback invoked when scan verdict is CLEAN.\n   *                  Used to chain post-scan work that must only run on safe bytes. Note the file\n   *                  STATUS lifecycle ends at CLEAN for processing purposes — RAG chunking of a\n   *                  `ragSource` file field is per-field derived data (chunk rows), never a file\n   *                  status transition.\n   */\n  async initiateScan(\n    fileId: string,\n    executionContext: ExecutionContext<any>,\n    onClean?: () => Promise<void>,\n  ): Promise<void> {\n    const allowedTransitions = FILE_STATUS_TRANSITIONS[FileStatus.UPLOADED];\n    if (!allowedTransitions.includes(FileStatus.SCANNING)) {\n      throw this.errorBuilder.buildError(\n        ErrorType.VALIDATION,\n        executionContext,\n        {\n          customMessageReference: ErrorCustomMessageReference.FILE_INVALID_STATUS_TRANSITION,\n          context: {\n            fileId, // diagnostic (log-only)\n          },\n        },\n      );\n    }\n\n    await this.filesService.updateFileStatus(\n      fileId,\n      FileStatus.SCANNING,\n      executionContext,\n    );\n\n    if (onClean) {\n      this.onCleanCallbacks.set(fileId, onClean);\n    }\n\n    this.logDebug('File transitioned to SCANNING, dispatching scan', { fileId });\n\n    // Run the full scanning pipeline asynchronously. The file is already in\n    // SCANNING status so downloads are blocked until the result handler\n    // transitions it to CLEAN / INFECTED / FAILED.\n    this.executeScan(fileId, executionContext).catch((err) => {\n      this.logger.error('Scan execution failed unexpectedly', {\n        fileId,\n        ...projectCaughtErrorLogFields(err),\n      });\n    });\n  }\n\n  /**\n   * Download the file from storage and run the scanning pipeline.\n   *\n   * Pipeline order:\n   * 1. ClamAV (signature-based) — if configured\n   * 2. YARA (pattern-based) — if enabled and ClamAV passed\n   *\n   * Short-circuits on first INFECTED verdict. YARA only runs if the\n   * file survived ClamAV — no point in pattern-matching a known virus.\n   */\n  private async executeScan(\n    fileId: string,\n    executionContext: ExecutionContext<any>,\n  ): Promise<void> {\n    const file = await this.filesService.getFile(fileId, executionContext);\n    if (!file) {\n      this.logger.error('File not found for scanning', { fileId });\n      return;\n    }\n\n    // Resolve through FilesBackendService rather than the router directly, so a\n    // LEGACY row that persisted no `storageProvider` falls back to the default\n    // provider instead of failing the scan. Reimplementing the lookup here is what\n    // made this one of five different behaviours for a provider-less row.\n    //\n    // The throw is deliberately converted back into a terminal verdict rather than\n    // propagated. `getStorageProviderForFile` throws INTERNAL when the persisted id\n    // is not registered, and this pipeline is fire-and-forget — its dispatcher's\n    // `.catch()` only LOGS. An escaping throw would therefore leave the file in\n    // SCANNING permanently, and downloads stay blocked until a result handler moves\n    // it out. That is strictly worse than the ERROR verdict this site already\n    // recorded, so the drift is closed WITHOUT adopting the reference behaviour on\n    // the throwing branch.\n    let provider;\n    try {\n      provider = this.filesService.getStorageProviderForFile(file, executionContext);\n    } catch (err) {\n      await this.handleScanResult(fileId, {\n        verdict: FileScanVerdict.ERROR,\n        errorMessage: `Storage provider '${file.storageProvider}' not available for scan download`,\n        scannerRef: 'scan-pipeline',\n      }, executionContext);\n      this.logger.error('Scan aborted: persisted storage provider is not registered', {\n        fileId,\n        storageProvider: file.storageProvider,\n        ...projectCaughtErrorLogFields(err),\n      });\n      return;\n    }\n\n    const downloadParams = {\n      fileId: file.fileId,\n      storageProvider: file.storageProvider,\n      storageRef: file.storageRef,\n    };\n    const executedScannerLayers: string[] = [];\n\n    // ── Layer 1: ClamAV ────────────────────────────────────────────────\n    if (this.clamavScanner.isConfigured()) {\n      executedScannerLayers.push('clamav');\n      let downloadResult;\n      try {\n        downloadResult = await provider.download(downloadParams, executionContext);\n      } catch (err) {\n        await this.handleScanResult(fileId, {\n          verdict: FileScanVerdict.ERROR,\n          errorMessage: `Failed to download file for ClamAV: ${describeCaughtError(err)}`,\n          scannerRef: 'clamav',\n        }, executionContext);\n        return;\n      }\n\n      try {\n        const clamResult = await this.clamavScanner.scanStream(downloadResult.stream, fileId);\n\n        if (clamResult.verdict !== FileScanVerdict.CLEAN) {\n          await this.handleScanResult(fileId, clamResult, executionContext);\n          return;\n        }\n\n        this.logDebug('ClamAV layer passed', { fileId, durationMs: clamResult.durationMs });\n      } finally {\n        if (!downloadResult.stream.destroyed) {\n          downloadResult.stream.destroy();\n        }\n      }\n    } else {\n      this.logDebug('ClamAV not configured — skipping signature scan', { fileId });\n    }\n\n    // ── Layer 2: YARA (optional, platform-level) ───────────────────────\n    if (this.yaraScanner.isEnabled()) {\n      executedScannerLayers.push('yara');\n      let downloadResult;\n      try {\n        downloadResult = await provider.download(downloadParams, executionContext);\n      } catch (err) {\n        await this.handleScanResult(fileId, {\n          verdict: FileScanVerdict.ERROR,\n          errorMessage: `Failed to download file for YARA: ${describeCaughtError(err)}`,\n          scannerRef: 'yara',\n        }, executionContext);\n        return;\n      }\n\n      try {\n        const yaraResult = await this.yaraScanner.scanStream(downloadResult.stream, fileId);\n\n        if (yaraResult.verdict !== FileScanVerdict.CLEAN) {\n          await this.handleScanResult(fileId, yaraResult, executionContext);\n          return;\n        }\n\n        this.logDebug('YARA layer passed', { fileId, durationMs: yaraResult.durationMs });\n      } finally {\n        if (!downloadResult.stream.destroyed) {\n          downloadResult.stream.destroy();\n        }\n      }\n    }\n\n    // ── All layers passed ──────────────────────────────────────────────\n    if (!this.clamavScanner.isConfigured() && !this.yaraScanner.isEnabled()) {\n      this.logger.warn('No scanners configured — marking as CLEAN', { fileId });\n    }\n\n    await this.handleScanResult(fileId, {\n      verdict: FileScanVerdict.CLEAN,\n      scannerRef: executedScannerLayers.join('+') || 'none',\n    }, executionContext);\n  }\n\n  /**\n   * Process the result of a scan job.\n   *\n   * - CLEAN: transition to CLEAN (file becomes downloadable)\n   * - INFECTED: transition to INFECTED, then quarantine\n   * - ERROR: transition to FAILED (retryable via re-scan)\n   */\n  async handleScanResult(\n    fileId: string,\n    result: FileScanResult,\n    executionContext: ExecutionContext<any>,\n  ): Promise<void> {\n    this.logDebug('Processing scan result', {\n      fileId,\n      verdict: result.verdict,\n      threatName: result.threatName,\n      scannerRef: result.scannerRef,\n      durationMs: result.durationMs,\n    });\n\n    switch (result.verdict) {\n      case FileScanVerdict.CLEAN:\n        await this.filesService.updateFileStatus(\n          fileId,\n          FileStatus.CLEAN,\n          executionContext,\n        );\n        this.logDebug('File marked as CLEAN after scan', { fileId });\n\n        // Invoke the post-clean callback (generic post-scan work registered by initiateScan's\n        // caller). RAG ingestion is deliberately NOT chained here: the service-tier write hook and\n        // the hourly reconciliation sweep own corpus derivation, and the ingestion pipeline itself\n        // refuses non-downloadable files — so a file that finishes scanning is picked up by the\n        // next sweep run with no per-file callback wiring.\n        const onClean = this.onCleanCallbacks.get(fileId);\n        if (onClean) {\n          this.onCleanCallbacks.delete(fileId);\n          onClean().catch((err) => {\n            this.logger.error('Post-clean callback failed', {\n              fileId,\n              ...projectCaughtErrorLogFields(err),\n            });\n          });\n        }\n        break;\n\n      case FileScanVerdict.INFECTED:\n        this.onCleanCallbacks.delete(fileId);\n        await this.filesService.updateFileStatus(\n          fileId,\n          FileStatus.INFECTED,\n          executionContext,\n        );\n        this.logger.warn('File flagged as INFECTED', {\n          fileId,\n          threatName: result.threatName,\n          scannerRef: result.scannerRef,\n        });\n\n        await this.quarantineInfectedFile(fileId, result, executionContext);\n        break;\n\n      case FileScanVerdict.ERROR:\n        this.onCleanCallbacks.delete(fileId);\n        this.logger.error('Scan failed with error', {\n          fileId,\n          errorMessage: result.errorMessage,\n          scannerRef: result.scannerRef,\n        });\n        await this.filesService.updateFileStatus(\n          fileId,\n          FileStatus.FAILED,\n          executionContext,\n        );\n        break;\n    }\n  }\n\n  /**\n   * Quarantine an infected file.\n   *\n   * Transitions INFECTED → QUARANTINED. The blob remains in storage\n   * but the file is permanently blocked from download. Operators can\n   * delete quarantined files via admin tooling.\n   */\n  private async quarantineInfectedFile(\n    fileId: string,\n    result: FileScanResult,\n    executionContext: ExecutionContext<any>,\n  ): Promise<void> {\n    try {\n      await this.filesService.updateFileStatus(\n        fileId,\n        FileStatus.QUARANTINED,\n        executionContext,\n      );\n      this.logDebug('Infected file quarantined', {\n        fileId,\n        threatName: result.threatName,\n      });\n    } catch (error) {\n      this.logger.error('Failed to quarantine infected file', {\n        fileId,\n        ...projectCaughtErrorLogFields(error),\n      });\n    }\n  }\n}\n"]}
+{"version":3,"file":"file-scanning.backend.service.js","sourceRoot":"","sources":["../../../../../src/files/services/file-scanning.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * File Scanning Backend Service\n *\n * Orchestrates antivirus scanning for uploaded files. After a file\n * reaches UPLOADED status, this service:\n *\n * 1. Transitions the file to SCANNING\n * 2. Downloads the file from storage\n * 3. Submits to ClamAV via TCP (signature-based)\n * 4. If ClamAV passes, submits to YARA via REST (pattern-based, optional)\n * 5. Processes combined results (CLEAN / INFECTED)\n * 6. Quarantines infected files\n *\n * Scanning is **fail-closed at the gate, asynchronous in the pipeline** (#433). The upload handler\n * AWAITS `initiateScan`, which awaits the UPLOADED -> SCANNING transition and only then fires the\n * pipeline — so the upload response costs one status write, not a scan, and the file is already\n * non-downloadable when the caller is told the upload succeeded. It becomes downloadable when the\n * result handler transitions it to CLEAN.\n *\n * This paragraph used to say the response \"returns immediately with status UPLOADED\", and that was\n * the defect: UPLOADED is a downloadable status, so a field declaring `scanPolicy: 'required'` had\n * a window in which unscanned bytes were servable. If scanning is not required for the field, the\n * file stays at UPLOADED and remains downloadable — that half is unchanged and deliberate.\n *\n * Configuration:\n * - Application-wide: DERIVED, not declared. Scanning is on for a field that states no policy of its\n *   own exactly when a scanner is reachable — `fileScanning.antivirus` (seeded from `CLAMAV_HOST`) or\n *   `fileScanning.yara` both enabled and reachable (`YARA_ENABLED` + `YARA_HOST`). Provisioning the\n *   sidecar IS the application-level opt-in; there is no separate on/off flag. See\n *   {@link FileScanningBackendService.isGlobalScanningEnabled} for why it is derived rather than declared.\n * - Per-field: `z_file({ scanPolicy: 'required' | 'skip' })` overrides that, in both directions.\n *\n * These two lines used to name `appConfig.files.scanning.enabled`, a configuration path no schema has\n * ever declared — so the application-wide half was documented, cast through `any`, and dead.\n *\n * A scan that was REQUESTED and finds no scanner now FAILS the file rather than passing it; the tail of\n * `executeScan` carries the reasoning.\n */\n\nimport { injectable, inject, optional } from 'inversify';\nimport {\n  ErrorType,\n  ErrorCustomMessageReference,\n  FileStatus,\n  FILE_STATUS_TRANSITIONS,\n} from '@wildo-ai/saas-models';\nimport type { FileSchemaMetadata } from '@wildo-ai/zod-decorators';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport type { AuditLogsBackendService } from '~wildo-backend-lib/compliance/audit-trails/services/audit-logs.backend.service';\nimport type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport { describeCaughtError, projectCaughtErrorLogFields } from '~wildo-backend-lib/errors/utils/error-log-level-classification.backend.utils';\nimport { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\nimport { FilesBackendService } from '~wildo-backend-lib/files/services/files.backend.service';\nimport { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';\nimport { ClamAVScannerBackendService } from '~wildo-backend-lib/files/scanning/clamav-scanner.backend.service';\nimport {\n  FileScanVerdict,\n  type FileScanResult,\n} from '~wildo-backend-lib/files/scanning/file-scan.types';\nimport { YaraScannerBackendService } from '~wildo-backend-lib/files/scanning/yara-scanner.backend.service';\nimport { FileStorageRouterBackendService } from '~wildo-backend-lib/files/storage/file-storage-router.backend.service';\nexport {\n  FileScanVerdict,\n  type FileScanResult,\n} from '~wildo-backend-lib/files/scanning/file-scan.types';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Service\n// ─────────────────────────────────────────────────────────────────────────────\n\n@injectable()\nexport class FileScanningBackendService {\n  protected logDebug: (message: string, context?: Record<string, unknown>) => void;\n\n  private readonly onCleanCallbacks = new Map<string, () => Promise<void>>();\n\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger)\n    private readonly logger: LoggerService,\n    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService)\n    private readonly errorBuilder: ErrorBuilderBackendService,\n    @inject(SAAS_SERVICE_TYPES.FilesBackendService)\n    private readonly filesService: FilesBackendService,\n    @inject(SAAS_SERVICE_TYPES.AppConfigService)\n    private readonly appConfigService: AppConfigurationService,\n    @inject(SAAS_SERVICE_TYPES.ClamAVScannerService)\n    private readonly clamavScanner: ClamAVScannerBackendService,\n    @inject(SAAS_SERVICE_TYPES.YaraScannerService)\n    private readonly yaraScanner: YaraScannerBackendService,\n    @inject(SAAS_SERVICE_TYPES.FileStorageRouter)\n    private readonly fileStorageRouter: FileStorageRouterBackendService,\n    /*\n     * `@optional()` because a container without the audit service must still SCAN (#506). The record\n     * is what this issue adds; refusing to inspect content when the recorder is absent would trade a\n     * missing audit row for missing malware detection, which is the worse of the two.\n     *\n     * The emission below is likewise best-effort: an audit failure must not turn a successful\n     * quarantine into an exception that leaves the file mid-transition.\n     */\n    @inject(SAAS_SERVICE_TYPES.AuditLogsService) @optional()\n    private readonly auditLogsService?: AuditLogsBackendService,\n  ) {\n    this.logDebug = this.logger.debugByType('FileScanningBackendService');\n  }\n\n  /**\n   * Determine whether a file should be scanned after upload.\n   *\n   * Resolution order:\n   * 1. Per-field `z_file({ scanPolicy })` wins if set\n   * 2. Falls back to the application-wide answer, {@link isGlobalScanningEnabled}\n   *\n   * assurance-control: WILDO.SECURITY.INGESTED_CONTENT_INSPECTION — whether ingested content is\n   * inspected is a declared decision, per field and then per application, rather than an implicit one.\n   *\n   * The per-APPLICATION half of that claim was false until 2026-09-09: step 2 read a configuration path\n   * no schema declares, so it answered `false` in every application ever built and `scanPolicy` was the\n   * only reachable declaration. It is true now because the application-wide answer is DERIVED from the\n   * scanner topology the operator provisions — a declaration made by supplying `CLAMAV_HOST`, and\n   * refused a default. Nothing here is implicit in either direction: a field can still override, and a\n   * requested scan with no scanner refuses rather than passing (see the tail of `executeScan`).\n   */\n  shouldScan(fileMetadata?: FileSchemaMetadata): boolean {\n    const scanPolicy = fileMetadata?.scanPolicy;\n\n    if (scanPolicy === 'required') return true;\n    if (scanPolicy === 'skip') return false;\n\n    return this.isGlobalScanningEnabled();\n  }\n\n  /**\n   * Whether scanning is on APPLICATION-WIDE, for a file field that states no `scanPolicy` of its own.\n   *\n   * DERIVED from the platform-injected `fileScanning` topology: a scanner being reachable IS the\n   * application-level opt-in.\n   *\n   * ## What this replaced\n   *\n   * `(this.appConfigService.config as Record<string, any>)?.files?.scanning?.enabled === true`. The\n   * `any` cast is the tell — `AppConfigurationSchema` declares no `files` section, `z.object` strips\n   * unknown keys, so the parsed configuration could never carry that path and the expression was\n   * `undefined === true` for every application, for the whole life of the flag. The service's own\n   * docstring documented it as the global switch.\n   *\n   * ## Why DERIVED rather than declared\n   *\n   * Adding an `enabled` boolean to `AppConfiguration_FileScanningSchema` was the other candidate and is\n   * rejected on three counts:\n   *\n   *  - **the answer already exists.** `fileScanning` is a mutation-boundary-PROTECTED section\n   *    (`APP_CONFIG_MUTATION_BOUNDARY_RULES` in `app-config.backend-authored.definitions.ts`: \"file-scanning\n   *    sidecar topology and its platform-level opt-in are env/bootstrap-owned\"), so an application cannot\n   *    author it. A boolean would have to be seeded from a NEW environment key sitting beside the host key\n   *    that already says the same thing — a second source of truth that can disagree with the first;\n   *  - **it matches the convention of the thing it gates.** ClamAV has no enable flag anywhere in this\n   *    subsystem: `ClamAVScannerBackendService.isConfigured()` states \"presence of a host IS the opt-in\",\n   *    and `buildFileServicesTopologyFromEnvironment` refuses to emit a plausible default host for exactly\n   *    that reason;\n   *  - **it closes the hole the repair would otherwise open.** A separate boolean makes \"globally on, no\n   *    scanner reachable\" a REPRESENTABLE state, and that state is precisely the one the pipeline used to\n   *    answer with a CLEAN verdict. Derived, the state cannot exist: the switch is on only when something\n   *    can actually run. The runtime refusal in `executeScan` stays regardless, because `scanPolicy:\n   *    'required'` reaches the same tail without consulting this switch at all.\n   *\n   * The two predicates are the pipeline's OWN — `executeScan` gates its two layers on exactly\n   * `clamavScanner.isConfigured()` and `yaraScanner.isEnabled()` — so the switch and the pipeline cannot\n   * come to different conclusions about whether a scan is possible. Note `isEnabled()` is already the\n   * conjunction of YARA's two independent axes (opted in AND reachable), which is why the \"enabled but\n   * unreachable\" misconfiguration does not read as an application-wide opt-in here; the startup validator\n   * reports it as its own issue instead.\n   *\n   * The `isInitialized()` guard stays: both scanner reads deliberately throw\n   * `app_configuration_not_initialized` rather than softening to `false`, and a scan decision taken before\n   * configuration has landed is not a decision.\n   */\n  isGlobalScanningEnabled(): boolean {\n    if (!this.appConfigService.isInitialized()) return false;\n    return this.clamavScanner.isConfigured() || this.yaraScanner.isEnabled();\n  }\n\n  /**\n   * Initiate scanning for a file that just reached UPLOADED status.\n   *\n   * Transitions to SCANNING, then dispatches the scan job.\n   * The response is fire-and-forget: the caller does not wait for scan\n   * completion — scan results are processed asynchronously via\n   * `handleScanResult()`.\n   *\n   * @param onClean - Optional callback invoked when scan verdict is CLEAN.\n   *                  Used to chain post-scan work that must only run on safe bytes. Note the file\n   *                  STATUS lifecycle ends at CLEAN for processing purposes — RAG chunking of a\n   *                  `ragSource` file field is per-field derived data (chunk rows), never a file\n   *                  status transition.\n   */\n  async initiateScan(\n    fileId: string,\n    executionContext: ExecutionContext<any>,\n    onClean?: () => Promise<void>,\n  ): Promise<void> {\n    const allowedTransitions = FILE_STATUS_TRANSITIONS[FileStatus.UPLOADED];\n    if (!allowedTransitions.includes(FileStatus.SCANNING)) {\n      throw this.errorBuilder.buildError(\n        ErrorType.VALIDATION,\n        executionContext,\n        {\n          customMessageReference: ErrorCustomMessageReference.FILE_INVALID_STATUS_TRANSITION,\n          context: {\n            fileId, // diagnostic (log-only)\n          },\n        },\n      );\n    }\n\n    await this.filesService.updateFileStatus(\n      fileId,\n      FileStatus.SCANNING,\n      executionContext,\n    );\n\n    if (onClean) {\n      this.onCleanCallbacks.set(fileId, onClean);\n    }\n\n    this.logDebug('File transitioned to SCANNING, dispatching scan', { fileId });\n\n    // Run the full scanning pipeline asynchronously. The file is already in\n    // SCANNING status so downloads are blocked until the result handler\n    // transitions it to CLEAN / INFECTED / FAILED.\n    this.executeScan(fileId, executionContext).catch((err) => {\n      this.logger.error('Scan execution failed unexpectedly', {\n        fileId,\n        ...projectCaughtErrorLogFields(err),\n      });\n    });\n  }\n\n  /**\n   * Download the file from storage and run the scanning pipeline.\n   *\n   * Pipeline order:\n   * 1. ClamAV (signature-based) — if configured\n   * 2. YARA (pattern-based) — if enabled and ClamAV passed\n   *\n   * Short-circuits on first INFECTED verdict. YARA only runs if the\n   * file survived ClamAV — no point in pattern-matching a known virus.\n   */\n  private async executeScan(\n    fileId: string,\n    executionContext: ExecutionContext<any>,\n  ): Promise<void> {\n    const file = await this.filesService.getFile(fileId, executionContext);\n    if (!file) {\n      this.logger.error('File not found for scanning', { fileId });\n      return;\n    }\n\n    // Resolve through FilesBackendService rather than the router directly, so a\n    // LEGACY row that persisted no `storageProvider` falls back to the default\n    // provider instead of failing the scan. Reimplementing the lookup here is what\n    // made this one of five different behaviours for a provider-less row.\n    //\n    // The throw is deliberately converted back into a terminal verdict rather than\n    // propagated. `getStorageProviderForFile` throws INTERNAL when the persisted id\n    // is not registered, and this pipeline is fire-and-forget — its dispatcher's\n    // `.catch()` only LOGS. An escaping throw would therefore leave the file in\n    // SCANNING permanently, and downloads stay blocked until a result handler moves\n    // it out. That is strictly worse than the ERROR verdict this site already\n    // recorded, so the drift is closed WITHOUT adopting the reference behaviour on\n    // the throwing branch.\n    let provider;\n    try {\n      provider = this.filesService.getStorageProviderForFile(file, executionContext);\n    } catch (err) {\n      await this.handleScanResult(fileId, {\n        verdict: FileScanVerdict.ERROR,\n        errorMessage: `Storage provider '${file.storageProvider}' not available for scan download`,\n        scannerRef: 'scan-pipeline',\n      }, executionContext);\n      this.logger.error('Scan aborted: persisted storage provider is not registered', {\n        fileId,\n        storageProvider: file.storageProvider,\n        ...projectCaughtErrorLogFields(err),\n      });\n      return;\n    }\n\n    const downloadParams = {\n      fileId: file.fileId,\n      storageProvider: file.storageProvider,\n      storageRef: file.storageRef,\n    };\n    const executedScannerLayers: string[] = [];\n\n    // ── Layer 1: ClamAV ────────────────────────────────────────────────\n    if (this.clamavScanner.isConfigured()) {\n      executedScannerLayers.push('clamav');\n      let downloadResult;\n      try {\n        downloadResult = await provider.download(downloadParams, executionContext);\n      } catch (err) {\n        await this.handleScanResult(fileId, {\n          verdict: FileScanVerdict.ERROR,\n          errorMessage: `Failed to download file for ClamAV: ${describeCaughtError(err)}`,\n          scannerRef: 'clamav',\n        }, executionContext);\n        return;\n      }\n\n      try {\n        const clamResult = await this.clamavScanner.scanStream(downloadResult.stream, fileId);\n\n        if (clamResult.verdict !== FileScanVerdict.CLEAN) {\n          await this.handleScanResult(fileId, clamResult, executionContext);\n          return;\n        }\n\n        this.logDebug('ClamAV layer passed', { fileId, durationMs: clamResult.durationMs });\n      } finally {\n        if (!downloadResult.stream.destroyed) {\n          downloadResult.stream.destroy();\n        }\n      }\n    } else {\n      this.logDebug('ClamAV not configured — skipping signature scan', { fileId });\n    }\n\n    // ── Layer 2: YARA (optional, platform-level) ───────────────────────\n    if (this.yaraScanner.isEnabled()) {\n      executedScannerLayers.push('yara');\n      let downloadResult;\n      try {\n        downloadResult = await provider.download(downloadParams, executionContext);\n      } catch (err) {\n        await this.handleScanResult(fileId, {\n          verdict: FileScanVerdict.ERROR,\n          errorMessage: `Failed to download file for YARA: ${describeCaughtError(err)}`,\n          scannerRef: 'yara',\n        }, executionContext);\n        return;\n      }\n\n      try {\n        const yaraResult = await this.yaraScanner.scanStream(downloadResult.stream, fileId);\n\n        if (yaraResult.verdict !== FileScanVerdict.CLEAN) {\n          await this.handleScanResult(fileId, yaraResult, executionContext);\n          return;\n        }\n\n        this.logDebug('YARA layer passed', { fileId, durationMs: yaraResult.durationMs });\n      } finally {\n        if (!downloadResult.stream.destroyed) {\n          downloadResult.stream.destroy();\n        }\n      }\n    }\n\n    // ── Nothing ran: refuse, do not certify ────────────────────────────\n    //\n    // This branch used to log a warning and then hand `handleScanResult` a CLEAN verdict with\n    // `scannerRef: 'none'` — which transitions the file to `FileStatus.CLEAN`, a member of\n    // `FILE_DOWNLOADABLE_STATUSES`. A scan had been REQUESTED (`shouldScan` said yes, `initiateScan`\n    // moved the file to SCANNING, the uploader was told the upload succeeded), and the answer returned\n    // was the answer a PASSING scan gives, produced by no scanner. That is strictly worse than not\n    // scanning at all: a field declaring `scanPolicy: 'required'` ended with bytes certified clean, and\n    // the only trace was a warning in a log nobody reads.\n    //\n    // ERROR -> `FileStatus.FAILED` is the fail-closed terminal, and the right one rather than merely the\n    // safe one: FAILED is outside `FILE_DOWNLOADABLE_STATUSES` so the bytes are blocked, it is outside\n    // `FILE_METADATA_WITHHELD_STATUSES` so the uploader can still poll and see WHY, and\n    // `FILE_STATUS_TRANSITIONS` keeps SCANNING -> FAILED, so nothing about the lifecycle has to move.\n    // A file that failed this way becomes scannable again the moment a scanner is provisioned.\n    //\n    // Keyed on `executedScannerLayers` — direct evidence that nothing ran — rather than on re-asking the\n    // two `isConfigured()` predicates. Re-asking would be a second copy of the decision the two layer\n    // gates above already took, and the copies can disagree if a layer ever grows another skip reason.\n    //\n    // Not redundant with the boot gate, which is the obvious objection. `collectScanningIssues` refuses\n    // to start an application whose fields declare `scanPolicy: 'required'` when ClamAV is unconfigured,\n    // so in a well-formed deployment this branch is unreachable. But that gate builds its population by\n    // walking every resource's file fields inside `try { … } catch { continue; }`: a resource whose field\n    // detection throws contributes no fields and is silently absent from the count. A boot check that can\n    // under-report the population it protects is not a substitute for the refusal at the site itself.\n    if (executedScannerLayers.length === 0) {\n      await this.handleScanResult(fileId, {\n        verdict: FileScanVerdict.ERROR,\n        errorMessage: 'Scan was requested but no scanner is configured (no ClamAV host, and YARA not enabled/reachable) — refusing to certify the file as clean',\n        scannerRef: 'none',\n      }, executionContext);\n      return;\n    }\n\n    // ── All layers that ran, passed ────────────────────────────────────\n    // `join('+')` needs no `|| 'none'` fallback any more: the empty case returned above, so a CLEAN\n    // verdict from here always names at least one scanner that actually executed.\n    await this.handleScanResult(fileId, {\n      verdict: FileScanVerdict.CLEAN,\n      scannerRef: executedScannerLayers.join('+'),\n    }, executionContext);\n  }\n\n  /**\n   * Process the result of a scan job.\n   *\n   * - CLEAN: transition to CLEAN (file becomes downloadable)\n   * - INFECTED: transition to INFECTED, then quarantine\n   * - ERROR: transition to FAILED (retryable via re-scan)\n   */\n  async handleScanResult(\n    fileId: string,\n    result: FileScanResult,\n    executionContext: ExecutionContext<any>,\n  ): Promise<void> {\n    this.logDebug('Processing scan result', {\n      fileId,\n      verdict: result.verdict,\n      threatName: result.threatName,\n      scannerRef: result.scannerRef,\n      durationMs: result.durationMs,\n    });\n\n    /*\n     * assurance-control: WILDO.SECURITY.INGESTED_CONTENT_INSPECTION — the scanner's verdict becomes a\n     * member of `FileStatus`, which is also what `FILE_DOWNLOADABLE_STATUSES` reads, so \"inspected\" and\n     * \"servable\" are one decision rather than two that could disagree. `FileScanVerdict` names the\n     * scanner's answer; `FileStatus` is the one with consequence, which is why the assurance capability\n     * derives from it.\n     *\n     * The outcome now ALSO reaches the audit trail (#506): `FILE_MALWARE_DETECTED` when a scanner\n     * concludes an infection, `FILE_MALWARE_SCAN_FAILED` when the scan could not run. Both are\n     * emitted AFTER the terminal transition, so the row can never describe a state the record does\n     * not hold. Until they existed, an infection produced a status change and nothing else — the only\n     * way to learn malware had arrived was to notice a row sitting at `QUARANTINED`.\n     */\n    switch (result.verdict) {\n      case FileScanVerdict.CLEAN:\n        await this.filesService.updateFileStatus(\n          fileId,\n          FileStatus.CLEAN,\n          executionContext,\n        );\n        this.logDebug('File marked as CLEAN after scan', { fileId });\n\n        // Invoke the post-clean callback (generic post-scan work registered by initiateScan's\n        // caller). RAG ingestion is deliberately NOT chained here: the service-tier write hook and\n        // the hourly reconciliation sweep own corpus derivation, and the ingestion pipeline itself\n        // refuses non-downloadable files — so a file that finishes scanning is picked up by the\n        // next sweep run with no per-file callback wiring.\n        const onClean = this.onCleanCallbacks.get(fileId);\n        if (onClean) {\n          this.onCleanCallbacks.delete(fileId);\n          onClean().catch((err) => {\n            this.logger.error('Post-clean callback failed', {\n              fileId,\n              ...projectCaughtErrorLogFields(err),\n            });\n          });\n        }\n        break;\n\n      case FileScanVerdict.INFECTED:\n        this.onCleanCallbacks.delete(fileId);\n        await this.filesService.updateFileStatus(\n          fileId,\n          FileStatus.INFECTED,\n          executionContext,\n        );\n        this.logger.warn('File flagged as INFECTED', {\n          fileId,\n          threatName: result.threatName,\n          scannerRef: result.scannerRef,\n        });\n\n        await this.quarantineInfectedFile(fileId, result, executionContext);\n        // AFTER the quarantine transition, so `fileStatus` is what the record holds rather than what\n        // this method intended. If the quarantine failed, the row says INFECTED, which is true.\n        await this.recordScanOutcomeAudit(fileId, result, executionContext);\n        break;\n\n      case FileScanVerdict.ERROR:\n        this.onCleanCallbacks.delete(fileId);\n        this.logger.error('Scan failed with error', {\n          fileId,\n          errorMessage: result.errorMessage,\n          scannerRef: result.scannerRef,\n        });\n        await this.filesService.updateFileStatus(\n          fileId,\n          FileStatus.FAILED,\n          executionContext,\n        );\n        await this.recordScanOutcomeAudit(fileId, result, executionContext);\n        break;\n    }\n  }\n\n  /**\n   * Write the scan outcome to the audit trail (#506).\n   *\n   * Best-effort and never throwing: the file's status transition is the enforcement, and an audit\n   * store being unavailable must not convert a successful quarantine into an exception that leaves\n   * the caller believing the scan failed.\n   *\n   * A CLEAN verdict is deliberately NOT audited. Every upload is scanned, so a clean row per upload\n   * would be the highest-volume event in the trail and would bury the two that matter — and the\n   * upload itself is already recorded by `FILE_UPLOAD_GRANT_REDEEMED`. What is added here is the\n   * conclusion an operator would want to be alerted on.\n   */\n  private async recordScanOutcomeAudit(\n    fileId: string,\n    result: FileScanResult,\n    executionContext: ExecutionContext<any>,\n  ): Promise<void> {\n    if (!this.auditLogsService) return;\n\n    try {\n      // Re-read rather than assume: the transition may have failed, and the audit row must describe\n      // the record, not the intent.\n      const fileStatus = await this.resolveRecordedFileStatus(fileId, executionContext);\n      const organizationId = executionContext.initiatorIds?.organizationId;\n      const userId = executionContext.initiatorIds?.userId;\n\n      if (result.verdict === FileScanVerdict.INFECTED) {\n        await this.auditLogsService.logFileMalwareDetected({\n          fileId,\n          scannerRef: result.scannerRef,\n          threatName: result.threatName,\n          organizationId,\n          userId,\n          fileStatus,\n        }, executionContext);\n        return;\n      }\n\n      await this.auditLogsService.logFileMalwareScanFailed({\n        fileId,\n        scannerRef: result.scannerRef,\n        failureReason: result.errorMessage,\n        organizationId,\n        userId,\n        fileStatus,\n      }, executionContext);\n    } catch (error) {\n      this.logger.warn('Failed to record the file scan outcome in the audit trail', {\n        fileId,\n        verdict: result.verdict,\n        ...projectCaughtErrorLogFields(error),\n      });\n    }\n  }\n\n  /** The status the FILES row actually carries after the transition, or `unknown` if it cannot be read. */\n  private async resolveRecordedFileStatus(\n    fileId: string,\n    executionContext: ExecutionContext<any>,\n  ): Promise<string> {\n    try {\n      const file = await this.filesService.getFile(fileId, executionContext) as { status?: string } | null;\n      return file?.status ?? 'unknown';\n    } catch {\n      return 'unknown';\n    }\n  }\n\n  /**\n   * Quarantine an infected file.\n   *\n   * Transitions INFECTED → QUARANTINED. The blob remains in storage\n   * but the file is permanently blocked from download. Operators can\n   * delete quarantined files via admin tooling.\n   */\n  private async quarantineInfectedFile(\n    fileId: string,\n    result: FileScanResult,\n    executionContext: ExecutionContext<any>,\n  ): Promise<void> {\n    try {\n      await this.filesService.updateFileStatus(\n        fileId,\n        FileStatus.QUARANTINED,\n        executionContext,\n      );\n      this.logDebug('Infected file quarantined', {\n        fileId,\n        threatName: result.threatName,\n      });\n    } catch (error) {\n      this.logger.error('Failed to quarantine infected file', {\n        fileId,\n        ...projectCaughtErrorLogFields(error),\n      });\n    }\n  }\n}\n"]}

package/dist/esm/files/services/file-text-extraction.backend.service.d.ts

@@ -50,8 +50,30 @@
  * owns that decision and documents the full precedence, including the branch that protects an
  * existing RAG corpus from a provider outage. Plain text never touches a provider.
  *
+ * ## Office / OpenDocument — six served LOCALLY, three provider-only (#434, closed 2026-09-09)
+ *
+ * The framework's `Documents` media group admits Word, Excel, PowerPoint and the OpenDocument
+ * trio, and until 2026-09-08 the extractor supported NONE of them: a corpus field using the group
+ * accepted uploads that could never contribute a chunk under any configuration, skipped at debug.
+ *
+ * The nine types are THREE technical problems, and reading them as one is what produced this
+ * header's earlier claim that a local library would cost "three to six" dependencies:
+ *
+ * - **OOXML** (`.docx` `.xlsx` `.pptx`) and **OpenDocument** (`.odt` `.ods` `.odp`) are ZIP+XML —
+ *   the SAME technique, so ONE module reads all six, on two dependencies rather than six
+ *   (`fflate` to unzip, `fast-xml-parser` to read). See
+ *   `office-document-text-extraction.backend.utils.ts`.
+ * - **Legacy binary Office** (`.doc` `.xls` `.ppt`) are OLE2 compound files from a different era.
+ *   A reader for them is a project, not a dependency, so they stay PROVIDER-ONLY.
+ *
+ * So the six take exactly the ladder PDF already takes, with the office extractor in the rung
+ * `pdfjs-dist` occupies: a configured provider is preferred when the field opted into it, the
+ * local library serves everything else, and a deployment with NO provider can finally read the
+ * documents its media group accepts. The three remaining types keep the conditional support and
+ * the precise refusal, because for them the provider genuinely is the only path.
+ *
  * Future:
- * - Office documents (docx via mammoth, xlsx/pptx via dedicated libs)
+ * - Legacy binary Office (`.doc` / `.xls` / `.ppt`) locally, if an OLE2 reader ever earns its place
  * - Audio/video transcript extraction
  *
  * The service operates against the storage provider contract — it downloads
@@ -116,6 +138,14 @@ export declare class FileTextExtractionBackendService {
      * Check if a MIME type supports text extraction.
      */
     isExtractionSupported(mimeType: string): boolean;
+    /**
+     * Whether the configured document-extraction provider declares this MIME type.
+     *
+     * Deliberately narrower than {@link resolveUsableProviderBinding}: no byte length, no logging, and
+     * every failure answers `false`. It is a capability QUESTION asked on a hot path (once per file
+     * per sweep), not the resolution that precedes an actual extraction.
+     */
+    private providerDeclaresMimeType;
     private extractFromText;
     /**
      * THE SELECTION SEAM — provider first when one is configured and usable, local library
@@ -211,6 +241,35 @@ export declare class FileTextExtractionBackendService {
      * which rung of that seam routed here and is logged, so an operator reading the logs can tell
      * "no provider is configured" from "the provider was down" without inspecting configuration.
      */
+    /**
+     * The LOCAL-LIBRARY rung of {@link extractFromDocument}'s ladder, dispatched by MIME.
+     *
+     * Two libraries sit at this rung and they are not interchangeable: `pdfjs-dist` reads a PDF's
+     * text layer, and the ZIP+XML extractor reads OOXML / OpenDocument parts. Handing a document to
+     * the wrong one produces an unreadable-bytes classification that blames the FILE for a routing
+     * mistake — which is exactly the failure the provider-only era's refusal existed to avoid, so it
+     * must not reappear now that there are two locals instead of one.
+     *
+     * One dispatcher rather than a branch at each of the five call sites, because the five rungs are
+     * the same decision reached for five different reasons; branching at each would be five places to
+     * forget the office arm the day a sixth rung appears.
+     */
+    private extractLocally;
+    /**
+     * OOXML / OpenDocument text, read locally (#434).
+     *
+     * `partCount` is reported as `pageCount` deliberately: for a `.pptx` it IS the slide count, and
+     * for the others it is the closest honest analogue of "how many units of this document were
+     * read". Inventing a page count by dividing characters would be a number an operator could
+     * reasonably act on and that means nothing.
+     *
+     * An {@link OfficeDocumentExtractionError} is rethrown UNTOUCHED so the caller's classifier sees
+     * it: every one of its failures is a statement about the document's own bytes — not a readable
+     * ZIP, larger than the decompression bound, or holding none of the parts its type keeps text in
+     * — which is precisely the unreadable-document bucket, and not the provider-unavailable one that
+     * must protect an existing corpus.
+     */
+    private extractFromOfficeDocument;
     private extractFromPDF;
     /** Drain a download stream into a single buffer. Shared by every extraction path. */
     private collectStream;

package/dist/esm/files/services/file-text-extraction.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-text-extraction.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/files/services/file-text-extraction.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAMH,OAAO,EAA0C,KAAK,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAE1F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAC9G,OAAO,EAAE,gBAAgB,EAAE,MAAM,qEAAqE,CAAC;AACvG,OAAO,EAAE,+BAA+B,EAAE,MAAM,sEAAsE,CAAC;AACvH,OAAO,EAAE,mBAAmB,EAAE,MAAM,yDAAyD,CAAC;AAC9F,OAAO,EACL,gCAAgC,EAIjC,MAAM,oFAAoF,CAAC;AAG5F;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;;;;OAWG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAgDD,qBACa,gCAAgC;IAKzC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAE7B,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAGlC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAS7B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IApBtC,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;gBAI9D,MAAM,EAAE,aAAa,EAErB,YAAY,EAAE,0BAA0B,EAExC,iBAAiB,EAAE,+BAA+B,EAGlD,YAAY,EAAE,mBAAmB,EASjC,kBAAkB,CAAC,EAAE,gCAAgC;IAMxE;;OAEG;IACG,WAAW,CACf,IAAI,EAAE,IAAI,EACV,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACvC,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,wBAAwB,CAAC;IAsFpC;;OAEG;IACH,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;YAOlC,eAAe;IAmB7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoDG;YACW,mBAAmB;IAiHjC;;;;;;;;;OASG;IACH,OAAO,CAAC,4BAA4B;IAqCpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;YACW,cAAc;IA8F5B,qFAAqF;YACvE,aAAa;CAO5B"}
+{"version":3,"file":"file-text-extraction.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/files/services/file-text-extraction.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AAMH,OAAO,EAA0C,KAAK,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAQ1F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAC9G,OAAO,EAAE,gBAAgB,EAAE,MAAM,qEAAqE,CAAC;AACvG,OAAO,EAAE,+BAA+B,EAAE,MAAM,sEAAsE,CAAC;AACvH,OAAO,EAAE,mBAAmB,EAAE,MAAM,yDAAyD,CAAC;AAC9F,OAAO,EACL,gCAAgC,EAIjC,MAAM,oFAAoF,CAAC;AAG5F;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;;;;OAWG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAkED,qBACa,gCAAgC;IAKzC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAE7B,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAGlC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAS7B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IApBtC,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;gBAI9D,MAAM,EAAE,aAAa,EAErB,YAAY,EAAE,0BAA0B,EAExC,iBAAiB,EAAE,+BAA+B,EAGlD,YAAY,EAAE,mBAAmB,EASjC,kBAAkB,CAAC,EAAE,gCAAgC;IAMxE;;OAEG;IACG,WAAW,CACf,IAAI,EAAE,IAAI,EACV,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACvC,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,wBAAwB,CAAC;IA0FpC;;OAEG;IACH,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAsBhD;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;YAalB,eAAe;IAmB7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoDG;YACW,mBAAmB;IA4IjC;;;;;;;;;OASG;IACH,OAAO,CAAC,4BAA4B;IAqCpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH;;;;;;;;;;;;OAYG;YACW,cAAc;IAY5B;;;;;;;;;;;;;OAaG;YACW,yBAAyB;YA2BzB,cAAc;IA8F5B,qFAAqF;YACvE,aAAa;CAO5B"}