@abyss-project/tools 2.1.0 → 2.2.0

package/src/index.ts

@@ -32,6 +32,10 @@ import * as extractionApi from './api/extraction.api';
 import * as extractionSettingsApi from './api/extraction-settings.api';
 import * as extractionPlanPresetApi from './api/extraction-plan-preset.api';
 import * as monitorApi from './api/monitor.api';
+import * as probeScanApi from './api/probe-scan.api';
+import * as probeWebhookApi from './api/probe-webhook.api';
+import * as probeScanApplicationApi from './api/probe-scan.application.api';
+import * as probeWebhookApplicationApi from './api/probe-webhook.application.api';
 
 export * from './api';
 export * from './types';
@@ -42,8 +46,24 @@ export * from './server-sent-events';
 const DEFAULT_BASE_URL = 'https://tools-api.abyss-project.fr/api/';
 
 export const API_KEY_HEADER = 'abyss-api-key';
+/**
+ * Application-level API key header (Phase 3a — AbyssProbe application/API-key
+ * authentication). Same literal value every other Abyss service's own core
+ * package independently declares for its `ApplicationMiddleware` (abyss-
+ * storage, abyss-monitor, abyss-console — see
+ * probe-application.middleware.ts for the mirrored resolution logic).
+ */
+export const API_KEY_APPLICATION_HEADER = 'abyss-api-key-application';
 export const ADMIN_TOKEN_HEADER = 'abyss-admin-token';
 
+/**
+ * Header carrying the HMAC-SHA256 signature of a probe webhook delivery's
+ * raw JSON body (see apps/api/src/services/probe-webhook-delivery.service.ts).
+ * Verify it with {@link verifyProbeWebhookSignature} (re-exported from './utils').
+ */
+export const PROBE_WEBHOOK_SIGNATURE_HEADER = 'x-probe-signature';
+export const PROBE_WEBHOOK_SIGNATURE_ALGORITHM = 'sha256';
+
 const NUMBER_RETRY_API = 10;
 const BASE_DELAY_BETWEEN_RETRY = 5000;
 const RETRY_CODES = [
@@ -316,6 +336,48 @@ type AbyssToolsCoreSDK = {
   monitor: {
     up: typeof monitorApi.upMonitor;
   };
+  probe: {
+    /** `POST /scan` — sync (default) or async depending on `options.mode`. */
+    scan: typeof probeScanApi.scan;
+    /** `POST /scan` forced to `mode: sync` — precisely-typed 200 response. */
+    scanSync: typeof probeScanApi.scanSync;
+    /** `POST /scan?mode=async` — precisely-typed 202 response. */
+    scanAsync: typeof probeScanApi.scanAsync;
+    /** `GET /scan/:scanId` — poll a scan's status/verdict. */
+    getScan: typeof probeScanApi.getScan;
+    /** `GET /scan` — paginated history/search. */
+    listScans: typeof probeScanApi.listScans;
+    webhook: {
+      create: typeof probeWebhookApi.createProbeWebhook;
+      list: typeof probeWebhookApi.listProbeWebhook;
+      delete: typeof probeWebhookApi.deleteProbeWebhook;
+    };
+    /**
+     * Application/API-key-auth counterpart (Phase 3a) — for inter-service
+     * callers (abyss-storage, external integrations) instead of a
+     * personal/org session. Same request/response contracts as the methods
+     * above, hitting `/application/:applicationId/...` and authenticated
+     * with the `abyss-api-key-application` header ({@link
+     * API_KEY_APPLICATION_HEADER}) instead of the personal `abyss-api-key`.
+     */
+    application: {
+      /** `POST /application/:applicationId/scan` — sync (default) or async depending on `options.mode`. */
+      scan: typeof probeScanApplicationApi.scanApplication;
+      /** `POST /application/:applicationId/scan` forced to `mode: sync` — precisely-typed 200 response. */
+      scanSync: typeof probeScanApplicationApi.scanSyncApplication;
+      /** `POST /application/:applicationId/scan?mode=async` — precisely-typed 202 response. */
+      scanAsync: typeof probeScanApplicationApi.scanAsyncApplication;
+      /** `GET /application/:applicationId/scan/:scanId` — poll a scan's status/verdict. */
+      getScan: typeof probeScanApplicationApi.getScanApplication;
+      /** `GET /application/:applicationId/scan` — paginated history/search. */
+      listScans: typeof probeScanApplicationApi.listScansApplication;
+      webhook: {
+        create: typeof probeWebhookApplicationApi.createProbeWebhookApplication;
+        list: typeof probeWebhookApplicationApi.listProbeWebhookApplication;
+        delete: typeof probeWebhookApplicationApi.deleteProbeWebhookApplication;
+      };
+    };
+  };
   tag: {
     list: typeof tagApi.listTag;
     create: typeof tagApi.createTag;
@@ -707,6 +769,30 @@ export class AbyssToolsCore {
       monitor: {
         up: monitorApi.upMonitor,
       },
+      probe: {
+        scan: probeScanApi.scan,
+        scanSync: probeScanApi.scanSync,
+        scanAsync: probeScanApi.scanAsync,
+        getScan: probeScanApi.getScan,
+        listScans: probeScanApi.listScans,
+        webhook: {
+          create: probeWebhookApi.createProbeWebhook,
+          list: probeWebhookApi.listProbeWebhook,
+          delete: probeWebhookApi.deleteProbeWebhook,
+        },
+        application: {
+          scan: probeScanApplicationApi.scanApplication,
+          scanSync: probeScanApplicationApi.scanSyncApplication,
+          scanAsync: probeScanApplicationApi.scanAsyncApplication,
+          getScan: probeScanApplicationApi.getScanApplication,
+          listScans: probeScanApplicationApi.listScansApplication,
+          webhook: {
+            create: probeWebhookApplicationApi.createProbeWebhookApplication,
+            list: probeWebhookApplicationApi.listProbeWebhookApplication,
+            delete: probeWebhookApplicationApi.deleteProbeWebhookApplication,
+          },
+        },
+      },
       tag: {
         list: tagApi.listTag,
         create: tagApi.createTag,

package/src/types/enum/api-error.enum.ts

@@ -20,29 +20,4 @@ export enum Code {
   atlasDocumentLimitReached = 'atlas_document_limit_reached',
   boardCardDocumentLimitReached = 'board_card_document_limit_reached',
   boardCardMoveInvalidDestination = 'board_card_move_invalid_destination',
-  // AV v3 P2 async-enforce: thrown by assertNotPendingScan while a document's
-  // antivirus scan is still running (scanStatus === 'pending_scan'). Mapped
-  // to HTTP 423 in http-response-error.module.ts.
-  boardCardDocumentAnalysing = 'board_card_document_analysing',
-  atlasDocumentAnalysing = 'atlas_document_analysing',
-  // AV v3 P3 async-enforce: thrown by extractionFileService.assertNotPendingScan
-  // while an ARCHIVE-OWNED extraction_files row's antivirus scan is still
-  // running (scanStatus === 'pending_scan'). Gates only derived OUTPUTS
-  // (bundle/records/diff/export/share) — never the extraction metadata
-  // itself, which already ran synchronously before any verdict was known.
-  // Mapped to HTTP 423 in http-response-error.module.ts.
-  extractionFileAnalysing = 'extraction_file_analysing',
-  // AV v3 P3 async-enforce server backstop: thrown by
-  // beamUploadService.attachFiles when a resolved storage file's scanStatus
-  // is not PENDING_SCAN at attach time. AbyssBeam's presign is front-driven
-  // (resumable-upload.ts calls AbyssStorage directly, never through this
-  // backend), so a client could omit `antivirus: { scan: true }` on its own
-  // presign request; a properly-enrolled fresh upload is always
-  // PENDING_SCAN the moment attach is called (the async worker has not run
-  // yet), so anything else — most tellingly a null/absent scanStatus,
-  // meaning no scan was ever requested — means enrollment was bypassed and
-  // the attach is rejected outright. Not mapped in http-response-error
-  // .module.ts's statusByCode table, so it falls through to the default 400
-  // (a rejected request, not a "still analysing" 423 state).
-  beamFileNotEnrolled = 'beam_file_not_enrolled',
 }

package/src/types/enum/index.ts

@@ -11,4 +11,4 @@ export * from './extraction-feedback-issue-type.enum';
 export * from './provider-kind.enum';
 export * from './interpreter-kind.enum';
 export * from './combine-strategy.enum';
-export * from './file-scan-status.enum';
+export * from './probe-scan.enum';

package/src/types/enum/probe-scan.enum.ts

@@ -0,0 +1,44 @@
+// Mirrors apps/api/src/database/probe-scan.enum.ts EXACTLY (same string
+// values — this SDK talks to that API over the wire, so the values must
+// match byte-for-byte). Kept as a single file here too, on purpose: the
+// server groups all three enums in one file for the same reason (they are
+// one cohesive scan vocabulary), see that file's header comment.
+
+/**
+ * Antivirus scan verdict. `null` on the wire while the scan has not reached
+ * `DONE` yet (see {@link ProbeScanStatus}) — a scan that never completes
+ * (e.g. the engine throws) is left at its last real status with no
+ * fabricated verdict.
+ */
+export enum ProbeScanVerdict {
+  CLEAN = 'clean',
+  INFECTED = 'infected',
+}
+
+/**
+ * How the scan was (or will be) run: `SYNC` blocks the request until the
+ * engine returns the verdict inline; `ASYNC` queues the job and delivers the
+ * verdict later via a registered webhook and/or the per-request
+ * `callbackUrl`, and/or by polling `GET /scan/:scanId`.
+ */
+export enum ProbeScanMode {
+  SYNC = 'sync',
+  ASYNC = 'async',
+}
+
+/**
+ * Scan lifecycle. A SYNC scan skips `QUEUED` entirely (created directly at
+ * `SCANNING`). An ASYNC scan is created at `QUEUED`, flipped to `SCANNING`
+ * once a worker picks the job off the queue, then to `DONE` or `ERROR`.
+ *
+ * `ERROR` (async-only) is a TERMINAL, no-verdict state — there is no
+ * automatic requeue/retry (the uploaded bytes are deleted the moment the job
+ * ends, success or failure). A caller that wants to retry submits a brand
+ * new `POST /scan?mode=async`.
+ */
+export enum ProbeScanStatus {
+  QUEUED = 'queued',
+  SCANNING = 'scanning',
+  DONE = 'done',
+  ERROR = 'error',
+}

package/src/types/interface/api/requests/index.ts

@@ -27,3 +27,5 @@ export * from './metrics.request';
 export * from './tag.request';
 export * from './transfer.request';
 export * from './extraction.request';
+export * from './probe-scan.request';
+export * from './probe-webhook.request';

package/src/types/interface/api/requests/probe-scan.request.ts

@@ -0,0 +1,50 @@
+import { ProbeScanMode, ProbeScanStatus, ProbeScanVerdict } from '../../../enum';
+
+// Mirrors apps/api/src/api/controllers/probe-scan.controller.ts's ScanBody +
+// HistoryQuery, and apps/api/src/api/validators/probe-scan.validator.ts's
+// historyQuery() Joi schema (field names/optionality).
+
+/**
+ * Options accepted by `sdk.probe.scan(file, options)` — `POST /scan`. `mode`
+ * and `organizationId` travel as query params (`?mode=async&organization_id=`);
+ * `context` and `callbackUrl` travel as multipart text fields alongside the
+ * file — the sdk client handles that split, callers just pass one object.
+ */
+export interface IScanOptions {
+  /** sync (default — verdict returned inline) or async (queued, 202 + webhook/poll). */
+  mode?: ProbeScanMode;
+  /** Personal scope (default) or an organization the caller belongs to. */
+  organizationId?: string;
+  /** Free-form caller reference (e.g. `{ applicationFileId }`), stored verbatim. */
+  context?: Record<string, unknown>;
+  /** ASYNC-only per-request delivery override (https only). Ignored for a SYNC scan. */
+  callbackUrl?: string;
+  /** Filename reported to the server (defaults to `'file'`). Cosmetic only. */
+  filename?: string;
+  /** Content-Type hint used when constructing a Blob from a raw buffer/Uint8Array in a browser context. */
+  mimeType?: string;
+}
+
+/**
+ * `GET /scan` query — all filters optional, combined with AND.
+ * `contextKey`/`contextValue` must be supplied together (business-reference
+ * search inside the free-form `context` JSONB column) — supplying one
+ * without the other is rejected by the API (400).
+ */
+export interface IListScansQuery {
+  organizationId?: string;
+  verdict?: ProbeScanVerdict;
+  mode?: ProbeScanMode;
+  status?: ProbeScanStatus;
+  /** Date range on `createdAt`, inclusive at both ends. */
+  from?: Date;
+  to?: Date;
+  /** Case-insensitive partial match on the original file name. */
+  fileName?: string;
+  contextKey?: string;
+  contextValue?: string;
+  /** @default 1 */
+  page?: number;
+  /** @default 20, server max 200. */
+  limit?: number;
+}

package/src/types/interface/api/requests/probe-webhook.request.ts

@@ -0,0 +1,12 @@
+// Mirrors apps/api/src/api/controllers/probe-webhook.controller.ts's
+// ScopeQuery/CreateBody and probe-webhook.validator.ts's Joi schemas.
+
+/** Shared by create/list/delete — personal scope (default) or an organization. */
+export interface IProbeWebhookScopeQuery {
+  organizationId?: string;
+}
+
+export interface ICreateProbeWebhookBody {
+  /** HTTPS endpoint the verdict is POSTed to. Required, `https://` only. */
+  callbackUrl: string;
+}

package/src/types/interface/api/responses/beam.response.ts

@@ -3,7 +3,6 @@ import { IResponse } from '../type-message/response';
 import { IBeamTransfer, IBeamFile, IBeamRecipient } from '../../models/beam.dto';
 import { IContentShare } from '../../models/content-share.dto';
 import { BeamVisibility, BeamServeDenyReasonCode, BeamDownloadKind } from '../../../enum/beam.enum';
-import { FileScanStatus } from '../../../enum/file-scan-status.enum';
 
 export interface IGetBeamData {
   beamTransfer: IBeamTransfer;
@@ -41,16 +40,7 @@ export type IFinalizeBeamResponse = IResponse<IFinalizeBeamData>;
 // browser-facing view: no owner ids, no password/manage hashes; adds
 // hasPassword/isLocked/hasThumbnail so the front can render the locked state.
 export interface IBeamPublicFile {
-  // AV v3 P3 async-enforce — the listing endpoint (GET /b/:slug) is the ONE
-  // beam serve path that is not gated by beamServingService.gateFile (it is
-  // a metadata list, not a byte stream). Per the link-live-gate-per-file
-  // decision the share link itself always works, but a file whose own
-  // scanStatus is not (yet) CLEAN must not hand out a servable identifier:
-  // id is null and hasThumbnail is forced false so the front cannot build a
-  // download/thumb URL for a pending or quarantined file. A legacy NULL
-  // scanStatus (row written before this column existed) is treated as
-  // servable, matching gateFile.
-  id: string | null;
+  id: string;
   name: string;
   sizeOctet: number;
   mimeType: string | null;
@@ -58,10 +48,6 @@ export interface IBeamPublicFile {
   hasThumbnail: boolean;
   width: number | null;
   height: number | null;
-  // Exposed as-is (never redacted) regardless of servability, so the front
-  // can render an "analysing" placeholder for a withheld file instead of it
-  // just silently vanishing from the list.
-  scanStatus: FileScanStatus | null;
 }
 
 export interface IBeamPublicView {

package/src/types/interface/api/responses/index.ts

@@ -31,3 +31,5 @@ export * from './recent.response';
 export * from './transfer.response';
 export * from './extraction.response';
 export * from './monitor.response';
+export * from './probe-scan.response';
+export * from './probe-webhook.response';

package/src/types/interface/api/responses/probe-scan.response.ts

@@ -0,0 +1,38 @@
+import { IResponse } from '../type-message/response';
+import { BasePaginate } from '../type-message/base-paginate';
+import { ProbeScanStatus, ProbeScanVerdict } from '../../../enum';
+import { IProbeScanDetail, IProbeScanHistoryItem } from '../../models';
+
+// Mirrors apps/api/src/api/controllers/probe-scan.controller.ts's local
+// ScanSyncResponseData / ScanAsyncResponseData / GetScanResponseData /
+// PaginateScanResponseData EXACTLY.
+
+/** `POST /scan` (default, or explicit `?mode=sync`) — HTTP 200. */
+export interface IScanSyncData {
+  scanId: string;
+  verdict: ProbeScanVerdict;
+  viruses: string[];
+}
+export type IScanSyncResponse = IResponse<IScanSyncData>;
+
+/** `POST /scan?mode=async` — HTTP 202, job queued. */
+export interface IScanAsyncData {
+  scanId: string;
+  status: ProbeScanStatus.QUEUED;
+}
+export type IScanAsyncResponse = IResponse<IScanAsyncData>;
+
+/**
+ * `POST /scan`'s actual response body is one or the other of the two data
+ * shapes above, discriminated by the request's own `mode` (sync -> 200 +
+ * {@link IScanSyncData}, async -> 202 + {@link IScanAsyncData}). A caller
+ * that only ever uses one mode should prefer the sdk's `scanSync`/`scanAsync`
+ * wrappers, which return the precise, non-union type.
+ */
+export type IScanResponse = IScanSyncResponse | IScanAsyncResponse;
+
+/** `GET /scan/:scanId` — HTTP 200. */
+export type IGetScanResponse = IResponse<IProbeScanDetail>;
+
+/** `GET /scan` — HTTP 200, paginated history/search. */
+export type IPaginateScanResponse = IResponse<BasePaginate<IProbeScanHistoryItem>>;

package/src/types/interface/api/responses/probe-webhook.response.ts

@@ -0,0 +1,17 @@
+import { IResponse } from '../type-message/response';
+import { IProbeWebhook, IProbeWebhookCreated } from '../../models';
+
+// Mirrors apps/api/src/api/controllers/probe-webhook.controller.ts's local
+// response shapes EXACTLY.
+
+/** `POST /webhook` — HTTP 201. The only response that ever carries `secret`. */
+export type ICreateProbeWebhookResponse = IResponse<IProbeWebhookCreated>;
+
+/** `GET /webhook` — HTTP 200. A flat scope-filtered list, NOT paginated. */
+export interface IListProbeWebhookData {
+  webhooks: IProbeWebhook[];
+}
+export type IListProbeWebhookResponse = IResponse<IListProbeWebhookData>;
+
+/** `DELETE /webhook/:webhookId` — HTTP 200. */
+export type IDeleteProbeWebhookResponse = IResponse<{ ok: true }>;

package/src/types/interface/models/atlas-document.dto.ts

@@ -1,19 +1,11 @@
 import { IAtlasPage } from './atlas-page.dto';
 import { IAtlas } from './atlas.dto';
-import { FileScanStatus } from '../../enum/file-scan-status.enum';
 
 export interface IAtlasDocument {
   id: string;
   atlasPageId: string;
   atlasId: string;
   name: string;
-  // AV v3 P2 async-enforce — WIRE CAVEAT: these 4 fields type as always-present
-  // here (the true, always-populated stored/model shape), but the HTTP JSON
-  // response actually redacts all four to `null` while scanStatus is
-  // 'pending_scan' (see the AtlasDocument model's toJSON() override) —
-  // pending_scan grants no servable identifier to any caller, owner included.
-  // A future front consumer of this DTO must treat them as possibly-null at
-  // runtime whenever scanStatus === 'pending_scan', despite the `string` type.
   externalId: string;
   publicAccessId: string;
   thumbnailId: string | null;
@@ -21,16 +13,6 @@ export interface IAtlasDocument {
   sizeOctet: number;
   mimeType: string;
   checksum: string;
-  // AV v3 P2 async-enforce: antivirus verdict mirrored from AbyssStorage,
-  // seeded pending_scan at the UPLOAD webhook, updated by applyScanResult /
-  // purgeInfected on the SCAN_RESULT webhook. Null for rows created before
-  // this column existed. See assertNotPendingScan for the 423 gate.
-  scanStatus: FileScanStatus | null;
-  // Id of the user who requested this upload (currentUser at presign time),
-  // resolved server-side — never client-supplied. Null for an API-key/
-  // anonymous upload. Used ONLY to notify the uploader if the file is later
-  // found infected (purgeInfected) — not a permission/ownership field.
-  uploadedByUserId: string | null;
   createdAt?: Date;
   updatedAt?: Date;
 

package/src/types/interface/models/beam.dto.ts

@@ -2,7 +2,6 @@ import { IOrganization } from './organization.dto';
 import { IUser } from './user.dto';
 import { IProject } from './project.dto';
 import { BeamVisibility, BeamDownloadKind } from '../../enum/beam.enum';
-import { FileScanStatus } from '../../enum/file-scan-status.enum';
 
 export interface IBeamTransfer {
   id: string;
@@ -39,13 +38,6 @@ export interface IBeamTransfer {
 export interface IBeamFile {
   id: string;
   transferId: string;
-  // AV v3 P3 async-enforce — WIRE CAVEAT: typed as always-present here (the
-  // true, always-populated stored/model shape), but the HTTP JSON response
-  // actually redacts this (and thumbnailStorageFileId) to null while
-  // scanStatus is 'pending_scan' (see the BeamFile model's get() override) —
-  // pending_scan grants no servable identifier to any caller. A future front
-  // consumer of this DTO must treat it as possibly-null at runtime whenever
-  // scanStatus === 'pending_scan', despite the `string` type.
   // abyss-storage applicationFileId (PRIVATE bucket); resolved at serve time (B4).
   storageFileId: string;
   thumbnailStorageFileId: string | null;
@@ -59,20 +51,6 @@ export interface IBeamFile {
   position: number;
   createdAt?: Date;
 
-  // AV v3 P3 async-enforce: antivirus verdict mirrored from AbyssStorage,
-  // seeded at attach time (beamUploadService#attachFiles — REQUIRES
-  // pending_scan, a server-side backstop against a client presign that
-  // omitted antivirus enrollment; see resumable-upload.ts) and updated by
-  // applyScanResult / purgeInfected on the SCAN_RESULT webhook. Null for
-  // rows created before this column existed. See
-  // beamServingService#gateFile for the per-file serve gate.
-  scanStatus: FileScanStatus | null;
-  // Id of the user who requested this attach (currentUser at attach time,
-  // resolved server-side — never client-supplied). Null for an anonymous
-  // transfer's attach. Used ONLY to notify the uploader if the file is later
-  // found infected (purgeInfected) — not a permission/ownership field.
-  uploadedByUserId: string | null;
-
   transfer?: IBeamTransfer;
 }
 

package/src/types/interface/models/board-card-document.dto.ts

@@ -1,19 +1,11 @@
 import { IBoardCard } from './board-card.dto';
 import { IBoard } from './board.dto';
-import { FileScanStatus } from '../../enum/file-scan-status.enum';
 
 export interface IBoardCardDocument {
   id: string;
   boardCardId: string;
   boardId: string;
   name: string;
-  // AV v3 P2 async-enforce — WIRE CAVEAT: these 4 fields type as always-present
-  // here (the true, always-populated stored/model shape), but the HTTP JSON
-  // response actually redacts all four to `null` while scanStatus is
-  // 'pending_scan' (see the BoardCardDocument model's toJSON() override) —
-  // pending_scan grants no servable identifier to any caller, owner included.
-  // A future front consumer of this DTO must treat them as possibly-null at
-  // runtime whenever scanStatus === 'pending_scan', despite the `string` type.
   externalId: string;
   publicAccessId: string;
   thumbnailId: string | null;
@@ -21,16 +13,6 @@ export interface IBoardCardDocument {
   checksum: string;
   mimeType: string;
   sizeOctet: number;
-  // AV v3 P2 async-enforce: antivirus verdict mirrored from AbyssStorage,
-  // seeded pending_scan at the UPLOAD webhook, updated by applyScanResult /
-  // purgeInfected on the SCAN_RESULT webhook. Null for rows created before
-  // this column existed. See assertNotPendingScan for the 423 gate.
-  scanStatus: FileScanStatus | null;
-  // Id of the user who requested this upload (currentUser at presign time),
-  // resolved server-side — never client-supplied. Null for an API-key/
-  // anonymous upload. Used ONLY to notify the uploader if the file is later
-  // found infected (purgeInfected) — not a permission/ownership field.
-  uploadedByUserId: string | null;
   updatedAt?: Date;
   createdAt?: Date;
 

package/src/types/interface/models/extraction.dto.ts

@@ -6,7 +6,6 @@
 import { ExtractionWarningCode } from '../../../types/enum/extraction-warning.enum';
 import { ExtractionFeedbackIssueType } from '../../../types/enum/extraction-feedback-issue-type.enum';
 import { DocumentType } from '../../../types/enum/document-type.enum';
-import { FileScanStatus } from '../../enum/file-scan-status.enum';
 import type { IFieldValue, IExecutionManifest, IGlobalConfidence } from './extraction-plan.dto';
 
 // Re-export so consumers can import ExtractionFeedbackIssueType from the DTO barrel.
@@ -67,13 +66,6 @@ export interface IExtractionFile {
   pdfMimeType: string;
   pdfPageCount: number | null;
   pdfFilename: string | null;
-  // AV v3 P3 async-enforce — WIRE CAVEAT: typed always-present here (the
-  // stored/model shape), but the HTTP JSON response redacts this to `null`
-  // while scanStatus is 'pending_scan' (see the ExtractionFile model's
-  // get() override) — pending_scan grants no servable identifier to any
-  // caller, owner included. Never gated for a by-reference (caller-owned)
-  // file: AbyssExtract never mirrors a scan verdict locally for those (see
-  // scanStatus below), gating on the caller's live verdict instead.
   applicationFileId: string | null;
   userExternalId: string | null;
   userMetadata: Record<string, unknown> | null;
@@ -82,15 +74,6 @@ export interface IExtractionFile {
   detectedIban: string | null;
   detectedBic: string | null;
   detectedCurrency: string | null;
-  // AV v3 P3 async-enforce: antivirus verdict mirrored from AbyssStorage for
-  // an ARCHIVE-OWNED file only (seeded at extractionFileService.upsert from
-  // the archive-upload response — see extraction-extract.service.ts#archivePdf).
-  // Null for by-reference files (gated live on the caller's own verdict
-  // instead — no local mirror, since AbyssExtract never receives a
-  // SCAN_RESULT webhook for a file it did not request the scan for) and for
-  // rows created before this column existed. See assertNotPendingScan for
-  // the 423 gate this enables on derived-output endpoints.
-  scanStatus: FileScanStatus | null;
   createdAt: string;
   updatedAt: string;
 }

package/src/types/interface/models/index.ts

@@ -32,3 +32,6 @@ export * from './content-share.dto';
 export * from './extraction.dto';
 export * from './extraction-plan.dto';
 export * from './extraction-spatial-template.dto';
+export * from './probe-scan.dto';
+export * from './probe-webhook.dto';
+export * from './probe-webhook-delivery.dto';

package/src/types/interface/models/probe-scan.dto.ts

@@ -0,0 +1,48 @@
+import { ProbeScanMode, ProbeScanStatus, ProbeScanVerdict } from '../../enum';
+
+// Mirrors apps/api/src/api/controllers/probe-scan.controller.ts's local
+// response interfaces. AbyssProbe deliberately returns TWO different scan
+// shapes depending on the endpoint — never the raw `probe_scans` row, and
+// never a single one-size-fits-all model — so this file mirrors that with
+// two distinct interfaces rather than forcing one canonical "IProbeScan".
+
+/**
+ * `GET /scan/:scanId` shape (poll the queued -> scanning -> done/error
+ * progression). Deliberately minimal: no fileName/fileSize/mimeType/mode/
+ * timestamps, no internal ownership columns (userId/organizationId/
+ * callbackUrl) — a caller polling by id already knows what it submitted.
+ */
+export interface IProbeScanDetail {
+  scanId: string;
+  status: ProbeScanStatus;
+  /** null until `status` is DONE. */
+  verdict: ProbeScanVerdict | null;
+  /** null until `status` is DONE; [] when DONE and clean. */
+  viruses: string[] | null;
+  /** Free-form caller reference echoed back verbatim (see IProbeScanHistoryItem#context). */
+  context: Record<string, unknown> | null;
+}
+
+/**
+ * One row of `GET /scan`'s paginated history/search list. Richer than
+ * {@link IProbeScanDetail} (adds fileName/fileSize/mimeType/mode/timestamps)
+ * but still never echoes internal ownership columns (userId, organizationId,
+ * callbackUrl) — a caller already knows their own scope from the request
+ * they made.
+ */
+export interface IProbeScanHistoryItem {
+  scanId: string;
+  fileName: string;
+  fileSize: number;
+  mimeType: string;
+  verdict: ProbeScanVerdict | null;
+  viruses: string[] | null;
+  mode: ProbeScanMode;
+  status: ProbeScanStatus;
+  context: Record<string, unknown> | null;
+  /** Set the moment the engine call starts (SYNC: row-creation time; ASYNC: when a worker picks the job off the queue). */
+  startedAt: Date;
+  /** Set once the engine call returns. null while status is not DONE. */
+  finishedAt: Date | null;
+  createdAt: Date;
+}

package/src/types/interface/models/probe-webhook-delivery.dto.ts

@@ -0,0 +1,26 @@
+import { ProbeScanVerdict } from '../../enum';
+
+// Mirrors apps/api/src/services/probe-webhook-delivery.service.ts's
+// ProbeWebhookPayload EXACTLY (same field set, same JSON.stringify'd body a
+// receiver's raw request body will deserialize into) — this is the payload
+// AbyssProbe POSTs to every registered webhook's `callbackUrl` (and to a
+// scan's own per-request `callbackUrl`, see probe-scan docs) once an ASYNC
+// scan reaches a verdict (`status: DONE`).
+//
+// `verdict` is typed as the concrete enum here (not `string` like the
+// server's internal type) because delivery only ever happens on a DONE scan,
+// where the verdict is always set — see dispatchProbeScanWebhooks's guard.
+
+/**
+ * Body of a webhook delivery, signed via HMAC-SHA256 of
+ * `JSON.stringify(payload)` — see {@link PROBE_WEBHOOK_SIGNATURE_HEADER} and
+ * {@link verifyProbeWebhookSignature} (this package's root / utils).
+ */
+export interface IProbeWebhookDeliveryPayload {
+  scanId: string;
+  /** Free-form caller reference, echoed back verbatim (see IProbeScanHistoryItem#context). */
+  context: Record<string, unknown> | null;
+  verdict: ProbeScanVerdict;
+  /** [] when clean. */
+  viruses: string[];
+}

package/src/types/interface/models/probe-webhook.dto.ts

@@ -0,0 +1,25 @@
+// Mirrors apps/api/src/api/controllers/probe-webhook.controller.ts's local
+// WebhookResponseData / CreateWebhookResponseData. Public shape of a
+// registered `probe_webhooks` row — never carries `secret` except right
+// after creation (see IProbeWebhookCreated below); never echoes the
+// internal ownership columns (userId/organizationId/applicationId) either,
+// same discipline as the scan models.
+
+export interface IProbeWebhook {
+  id: string;
+  /** HTTPS endpoint the verdict is POSTed to. */
+  callbackUrl: string;
+  /** Disabled webhooks are skipped by dispatch (soft-off, not deleted). */
+  active: boolean;
+  createdAt: Date;
+}
+
+/**
+ * Create-only response shape: the ONE time `secret` is ever returned by the
+ * API ("Secret generated server-side, returned once on create"). Store it
+ * immediately — there is no reset-secret / re-reveal endpoint (see this
+ * package's header note on the deliberately small CRUD surface).
+ */
+export interface IProbeWebhookCreated extends IProbeWebhook {
+  secret: string;
+}

package/src/types/tests/beam.dto.spec.ts

@@ -46,8 +46,6 @@ describe('beam DTOs', () => {
       height: 600,
       downloadCount: 0,
       position: 0,
-      scanStatus: null,
-      uploadedByUserId: null,
     };
     const recipient: IBeamRecipient = {
       id: 'r1',