@abyss-project/tools 2.1.0 → 2.2.0

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;
+  }
+}

package/dist/api/file-scan.api.d.ts

@@ -1,5 +0,0 @@
-/// <reference types="node" />
-/// <reference types="node" />
-import { IFileScanOptions } from '../types';
-import { IFileScanResponse } from '../types';
-export declare const scan: (file: Buffer | Uint8Array, opts?: IFileScanOptions, apiKey?: string) => Promise<IFileScanResponse>;

package/dist/api/file-scan.api.js

@@ -1,49 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.scan = void 0;
-const __1 = require("..");
-const DEFAULT_API_KEY_HEADER = 'abyss-api-key';
-function authHeader(apiKey) {
-    return apiKey ? { [DEFAULT_API_KEY_HEADER]: apiKey } : {};
-}
-async function loadFormData() {
-    if (typeof FormData !== 'undefined' && typeof window !== 'undefined') {
-        return FormData;
-    }
-    const nodeRequire = new Function('return require')();
-    return nodeRequire('form-data');
-}
-const scan = async (file, opts = {}, apiKey) => {
-    const fileName = 'file';
-    const isBrowser = typeof window !== 'undefined' && typeof FormData !== 'undefined';
-    if (isBrowser) {
-        const form = new FormData();
-        const blob = new Blob([file]);
-        form.append('file', blob, fileName);
-        if (opts.organizationId) {
-            form.append('organizationId', opts.organizationId);
-        }
-        return (await __1.AbyssToolsCore.axios.post(`file-scan/scan`, form, {
-            headers: authHeader(apiKey),
-            maxBodyLength: Infinity,
-            maxContentLength: Infinity,
-        })).data;
-    }
-    const FormDataCtor = await loadFormData();
-    const form = new FormDataCtor();
-    const buf = Buffer.isBuffer(file) ? file : Buffer.from(file);
-    form.append('file', buf, { filename: fileName });
-    if (opts.organizationId) {
-        form.append('organizationId', opts.organizationId);
-    }
-    return (await __1.AbyssToolsCore.axios.post(`file-scan/scan`, form, {
-        headers: {
-            ...(typeof form.getHeaders === 'function' ? form.getHeaders() : {}),
-            ...authHeader(apiKey),
-        },
-        maxBodyLength: Infinity,
-        maxContentLength: Infinity,
-    })).data;
-};
-exports.scan = scan;
-//# sourceMappingURL=file-scan.api.js.map

package/dist/api/file-scan.api.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"file-scan.api.js","sourceRoot":"","sources":["../../src/api/file-scan.api.ts"],"names":[],"mappings":";;;AAUA,0BAAoC;AAIpC,MAAM,sBAAsB,GAAG,eAAe,CAAC;AAE/C,SAAS,UAAU,CAAC,MAAe;IACjC,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5D,CAAC;AAED,KAAK,UAAU,YAAY;IACzB,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QACrE,OAAO,QAAQ,CAAC;IAClB,CAAC;IAKD,MAAM,WAAW,GAAgB,IAAI,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;IAClE,OAAO,WAAW,CAAC,WAAW,CAAC,CAAC;AAClC,CAAC;AAQM,MAAM,IAAI,GAAG,KAAK,EACvB,IAAyB,EACzB,OAAyB,EAAE,EAC3B,MAAe,EACa,EAAE;IAC9B,MAAM,QAAQ,GAAG,MAAM,CAAC;IACxB,MAAM,SAAS,GAAG,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,QAAQ,KAAK,WAAW,CAAC;IACnF,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,IAAkB,CAAC,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,CACL,MAAM,kBAAc,CAAC,KAAK,CAAC,IAAI,CAAoB,gBAAgB,EAAE,IAAI,EAAE;YACzE,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC;YAC3B,aAAa,EAAE,QAAQ;YACvB,gBAAgB,EAAE,QAAQ;SAC3B,CAAC,CACH,CAAC,IAAI,CAAC;IACT,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,YAAY,EAAE,CAAC;IAC1C,MAAM,IAAI,GAAG,IAAI,YAAY,EAAE,CAAC;IAChC,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7D,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;IACjD,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,CACL,MAAM,kBAAc,CAAC,KAAK,CAAC,IAAI,CAAoB,gBAAgB,EAAE,IAAI,EAAE;QACzE,OAAO,EAAE;YACP,GAAG,CAAC,OAAO,IAAI,CAAC,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,GAAG,UAAU,CAAC,MAAM,CAAC;SACtB;QACD,aAAa,EAAE,QAAQ;QACvB,gBAAgB,EAAE,QAAQ;KAC3B,CAAC,CACH,CAAC,IAAI,CAAC;AACT,CAAC,CAAC;AAvCW,QAAA,IAAI,QAuCf"}

package/dist/types/enum/analysis-status.enum.d.ts

@@ -1,7 +0,0 @@
-export declare enum AnalysisStatus {
-    PENDING = "pending",
-    CLEAN = "clean",
-    INFECTED = "infected",
-    SKIPPED = "skipped",
-    ERROR = "error"
-}

package/dist/types/enum/analysis-status.enum.js

@@ -1,12 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AnalysisStatus = void 0;
-var AnalysisStatus;
-(function (AnalysisStatus) {
-    AnalysisStatus["PENDING"] = "pending";
-    AnalysisStatus["CLEAN"] = "clean";
-    AnalysisStatus["INFECTED"] = "infected";
-    AnalysisStatus["SKIPPED"] = "skipped";
-    AnalysisStatus["ERROR"] = "error";
-})(AnalysisStatus || (exports.AnalysisStatus = AnalysisStatus = {}));
-//# sourceMappingURL=analysis-status.enum.js.map

package/dist/types/enum/analysis-status.enum.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"analysis-status.enum.js","sourceRoot":"","sources":["../../../src/types/enum/analysis-status.enum.ts"],"names":[],"mappings":";;;AAOA,IAAY,cAMX;AAND,WAAY,cAAc;IACxB,qCAAmB,CAAA;IACnB,iCAAe,CAAA;IACf,uCAAqB,CAAA;IACrB,qCAAmB,CAAA;IACnB,iCAAe,CAAA;AACjB,CAAC,EANW,cAAc,8BAAd,cAAc,QAMzB"}

package/dist/types/enum/file-scan-status.enum.d.ts

@@ -1 +0,0 @@
-export type FileScanStatus = 'pending_scan' | 'clean' | 'infected' | 'skipped' | 'error';

package/dist/types/enum/file-scan-status.enum.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"file-scan-status.enum.js","sourceRoot":"","sources":["../../../src/types/enum/file-scan-status.enum.ts"],"names":[],"mappings":""}

package/dist/types/interface/api/requests/file-scan.request.d.ts

@@ -1,3 +0,0 @@
-export interface IFileScanOptions {
-    organizationId?: string;
-}

package/dist/types/interface/api/requests/file-scan.request.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"file-scan.request.js","sourceRoot":"","sources":["../../../../../src/types/interface/api/requests/file-scan.request.ts"],"names":[],"mappings":""}

package/dist/types/interface/api/responses/file-scan.response.d.ts

@@ -1,7 +0,0 @@
-import { IResponse } from '../type-message/response';
-import { IFileAnalysis } from '../../models/file-scan.dto';
-export interface IFileScanData {
-    analysis: IFileAnalysis;
-    scanCostUnits: number;
-}
-export type IFileScanResponse = IResponse<IFileScanData>;

package/dist/types/interface/api/responses/file-scan.response.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"file-scan.response.js","sourceRoot":"","sources":["../../../../../src/types/interface/api/responses/file-scan.response.ts"],"names":[],"mappings":""}

package/dist/types/interface/models/file-scan.dto.d.ts

@@ -1,11 +0,0 @@
-import { AnalysisStatus } from '../../enum/analysis-status.enum';
-export interface IFileAnalysis {
-    status: AnalysisStatus;
-    engine: string | null;
-    engineVersion: string | null;
-    contentHash: string | null;
-    viruses: string[];
-    startedAt: string | null;
-    finishedAt: string | null;
-    durationMs: number | null;
-}

package/dist/types/interface/models/file-scan.dto.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"file-scan.dto.js","sourceRoot":"","sources":["../../../../src/types/interface/models/file-scan.dto.ts"],"names":[],"mappings":""}

package/src/types/enum/file-scan-status.enum.ts

@@ -1,23 +0,0 @@
-/**
- * Antivirus scan verdict for a stored file, mirrored from AbyssStorage.
- *
- * This is the SAME vocabulary as `@abyss-project/storage`'s `FileScanStatus`
- * enum (`application_files.scanStatus`): `pending_scan` | `clean` | `infected`
- * | `skipped` | `error`. It is intentionally re-declared here as a string
- * union — NOT imported — because abyss-tools-core is standalone (does not
- * depend on `@abyss-project/storage`), the same approach every other core
- * package (abyss-main asset-core, abyss-banking-core, abyss-memories-core)
- * takes. A string union (rather than a local TS enum) is deliberate: the
- * backend assigns a storage `FileScanStatus` enum value straight into this
- * type with no cast (a string-enum member is assignable to the matching
- * string union, but NOT to a distinct local enum with identical values).
- * Keep the members in sync with storage's enum.
- *
- * Used by both async-enforce document surfaces (AV v3 P2): BoardCardDocument
- * and AtlasDocument. `pending_scan` gates `get()` (see
- * board-card-document.service.ts#assertNotPendingScan /
- * atlas-document.service.ts#assertNotPendingScan) with a 423; `infected`
- * never persists on a row (the row is purged instead, see purgeInfected on
- * both services).
- */
-export type FileScanStatus = 'pending_scan' | 'clean' | 'infected' | 'skipped' | 'error';