@abyss-project/tools 2.0.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/index.ts

@@ -11,3 +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 './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/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/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/probe.dto.test.ts

@@ -0,0 +1,97 @@
+// Type-level compile test for AbyssProbe's DTO/response shapes — asserts
+// they match the server contract (probe-scan.controller.ts /
+// probe-webhook.controller.ts / probe-webhook-delivery.service.ts) at
+// compile time: any incompatible rename/removal on either side fails
+// `npm run build` here. No jest runner in this SDK package; compile guard
+// only (mirrors ../api/extraction-plan-preset.api.test.ts). Run: npx tsc --noEmit.
+
+import {
+  ProbeScanVerdict,
+  ProbeScanMode,
+  ProbeScanStatus,
+  IProbeScanDetail,
+  IProbeScanHistoryItem,
+  IProbeWebhook,
+  IProbeWebhookCreated,
+  IProbeWebhookDeliveryPayload,
+  IScanSyncData,
+  IScanAsyncData,
+} from '..';
+
+// Enum exhaustiveness: fails to compile if a member is added/removed/renamed
+// here without updating this file — a cheap drift guard for values
+// transported verbatim over the wire (this SDK does not control the
+// server's enum, so a silent value drift is exactly what this must catch).
+const _verdicts: Record<ProbeScanVerdict, true> = { clean: true, infected: true };
+const _modes: Record<ProbeScanMode, true> = { sync: true, async: true };
+const _statuses: Record<ProbeScanStatus, true> = {
+  queued: true,
+  scanning: true,
+  done: true,
+  error: true,
+};
+
+// GET /scan/:scanId
+const _scanDetail: IProbeScanDetail = {
+  scanId: 's1',
+  status: ProbeScanStatus.DONE,
+  verdict: ProbeScanVerdict.CLEAN,
+  viruses: [],
+  context: null,
+};
+
+// GET /scan history row — richer than IProbeScanDetail (fileName/fileSize/
+// mimeType/mode/timestamps), still never the internal ownership columns.
+const _historyItem: IProbeScanHistoryItem = {
+  scanId: 's1',
+  fileName: 'invoice.pdf',
+  fileSize: 1024,
+  mimeType: 'application/pdf',
+  verdict: ProbeScanVerdict.INFECTED,
+  viruses: ['Eicar-Test-Signature'],
+  mode: ProbeScanMode.ASYNC,
+  status: ProbeScanStatus.DONE,
+  context: { applicationFileId: 'af1' },
+  startedAt: new Date(),
+  finishedAt: new Date(),
+  createdAt: new Date(),
+};
+
+// POST /scan — sync (200) / async (202) data shapes.
+const _scanSyncData: IScanSyncData = {
+  scanId: 's1',
+  verdict: ProbeScanVerdict.CLEAN,
+  viruses: [],
+};
+const _scanAsyncData: IScanAsyncData = { scanId: 's1', status: ProbeScanStatus.QUEUED };
+
+// Webhook subscription — list/get shape vs the create-only `secret` shape.
+const _webhook: IProbeWebhook = {
+  id: 'w1',
+  callbackUrl: 'https://example.com/hook',
+  active: true,
+  createdAt: new Date(),
+};
+const _webhookCreated: IProbeWebhookCreated = { ..._webhook, secret: 'shh' };
+
+// Webhook delivery payload — the exact body signed by x-probe-signature
+// (see verifyProbeWebhookSignature).
+const _deliveryPayload: IProbeWebhookDeliveryPayload = {
+  scanId: 's1',
+  context: null,
+  verdict: ProbeScanVerdict.INFECTED,
+  viruses: ['Eicar-Test-Signature'],
+};
+
+void _verdicts;
+void _modes;
+void _statuses;
+void _scanDetail;
+void _historyItem;
+void _scanSyncData;
+void _scanAsyncData;
+void _webhook;
+void _webhookCreated;
+void _deliveryPayload;
+
+export {};

package/src/utils/index.ts

@@ -4,3 +4,4 @@ export * from './shape.utils';
 export * from './icons.utils';
 export * from './enum.utils';
 export * from './extraction-webhook.utils';
+export * from './probe-webhook-signature.utils';

package/src/utils/probe-webhook-signature.utils.ts

@@ -0,0 +1,56 @@
+// ──────────────────────────────────────────────
+// AbyssProbe webhook signature verification (helper for RECEIVERS of a
+// webhook delivery — the abyss-main UI/abyss-storage/any external
+// integrator that registered a callbackUrl).
+//
+// Mirrors this package's own extraction-webhook.utils.ts
+// (verifyExtractionWebhook) — the same package's own precedent for this
+// exact problem — adapted to AbyssProbe's actual wire format: the signature
+// header (see PROBE_WEBHOOK_SIGNATURE_HEADER in this package's root index)
+// carries the RAW hex HMAC digest with no `sha256=` prefix (unlike
+// extraction's `X-RCB-Signature: sha256=<hex>`) — see
+// apps/api/src/services/probe-webhook-delivery.service.ts's `sign()`.
+//
+// Lazy-requires `crypto` so the SDK stays browser-compatible when this
+// utility is never invoked (a browser page is never the receiving end of a
+// server-to-server webhook).
+// ──────────────────────────────────────────────
+
+export interface VerifyProbeWebhookSignatureInput {
+  /** The exact bytes/string the receiver's HTTP framework handed it — must be the RAW body, not a re-serialized JSON.parse/stringify round trip (whitespace/key-order would change the HMAC). */
+  rawBody: string | Buffer;
+  /** The incoming `x-probe-signature` header value. */
+  signatureHeader: string | undefined;
+  /** This webhook registration's secret (returned once at creation — see IProbeWebhookCreated). */
+  secret: string;
+}
+
+/**
+ * Recompute the HMAC-SHA256 of `rawBody` with `secret` and constant-time
+ * compare it against `signatureHeader`. Returns `false` (never throws) for
+ * any malformed input — a hostile/truncated header must not crash the
+ * receiver.
+ */
+export function verifyProbeWebhookSignature(input: VerifyProbeWebhookSignatureInput): boolean {
+  if (!input.signatureHeader || !input.secret) return false;
+
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const crypto = require('crypto');
+  const computed: string = crypto
+    .createHmac('sha256', input.secret)
+    .update(input.rawBody)
+    .digest('hex');
+
+  if (input.signatureHeader.length !== computed.length) return false;
+
+  try {
+    return crypto.timingSafeEqual(
+      Buffer.from(input.signatureHeader, 'hex'),
+      Buffer.from(computed, 'hex'),
+    );
+  } catch {
+    // Buffer.from(..., 'hex') on a non-hex string yields a shorter buffer,
+    // which would otherwise make timingSafeEqual throw on a length mismatch.
+    return false;
+  }
+}