@abyss-project/probe 2.0.0 → 2.0.1

package/src/utils/probe-scan-cost.utils.ts

@@ -1,101 +1,101 @@
-// ──────────────────────────────────────────────
-// AbyssProbe scan cost model — pure, shared (client + server, no endpoint).
-//
-// Ported from abyss-storage's OWN weighted AV-scan cost model
-// (`apps/api/src/services/av-scan-usage.ts#computeAvScanCost`, introduced in
-// storage commit 317e4a0 "wire the weighted AV-scan quota", since made dead
-// code there by the AV v3 Phase 3b-2 hand-off — "storage never bills —
-// AbyssProbe does" — but the FORMULA itself is exactly what AbyssProbe's own
-// weighted billing needs, so it is ported here verbatim rather than
-// reinvented):
-//
-//   cost = round( (BASE + K_MB * ceil(sizeOctet / 1 MiB)) * MODE_WEIGHT[mode] )
-//
-// ASYNC costs LESS than SYNC (MODE_WEIGHT.async=1 < MODE_WEIGHT.sync=3) — a
-// synchronous scan holds the caller's request (and an engine worker) until
-// the verdict and cannot be batched/load-balanced, so it costs more than an
-// asynchronous (queued) scan of the SAME bytes. This is the numeric backing
-// for the scanner UI's "l'analyse en arrière-plan économise des tokens"
-// tooltip (WS1).
-//
-// PURE + DETERMINISTIC + no I/O: this is the SINGLE source of truth for
-// AbyssProbe's scan cost, used on BOTH sides of the wire —
-//   - server (apps/api/src/services/probe-scan.service.ts): the REAL cost
-//     billed via recordProbeScanUsage and persisted on probe_scans.costUnits
-//     once a scan reaches a verdict (DONE).
-//   - client (the AbyssProbe UI, or any external caller): a cost PREVIEW
-//     before scanning — call this with the picked file's size and the
-//     intended mode to show the estimated token cost, matching exactly what
-//     the server will bill (no separate "estimate" formula to drift out of
-//     sync with the real one — same function, same constants, both sides).
-//
-// Deliberately NOT exposed as an HTTP endpoint (no `POST /scan/estimate`):
-// the whole point of a pure function is that the client can compute it
-// locally, instantly, with zero round-trip — see this package's root README
-// note on `sdk.probe.*`'s HTTP-call-only convention; a helper like this one
-// (and `verifyProbeWebhookSignature` before it) is instead a plain top-level
-// export, not a `sdk.probe.*` method.
-// ──────────────────────────────────────────────
-
-import { ProbeScanMode } from '../types';
-
-/** Flat floor every scanned file pays (the "one scan" cost). Tunable. */
-export const PROBE_SCAN_COST_BASE = 1;
-
-/** Additional units per (ceil'd) mebibyte of scanned bytes. Tunable. */
-export const PROBE_SCAN_COST_K_MB = 1;
-
-/**
- * Per-mode cost multiplier. A synchronous scan blocks the caller's request
- * (and an engine worker) until the verdict and cannot be queued/batched, so
- * it costs strictly MORE than an asynchronous scan of the same bytes —
- * ASYNC < SYNC is a load-bearing invariant relied on by the scanner UI's
- * "background analysis saves tokens" messaging (WS1). Tunable, but this
- * ordering must never be inverted.
- */
-export const PROBE_SCAN_COST_MODE_WEIGHT: Record<ProbeScanMode, number> = {
-  [ProbeScanMode.ASYNC]: 1,
-  [ProbeScanMode.SYNC]: 3,
-};
-
-/** One mebibyte, the unit the per-MB term is quantised to. */
-const ONE_MB = 1024 * 1024;
-
-/**
- * Weighted cost of one AbyssProbe scan, in `ACCOUNT_AV_SCAN_UNITS` ("tokens"
- * in the UI). Pure + deterministic — same inputs always produce the same
- * output, no I/O, safe to call from a browser or a server.
- *
- * Returns `0` for a non-finite / non-positive `sizeOctet` (nothing to scan,
- * nothing to bill) rather than throwing — a defensive, never-crash contract
- * appropriate for a client-side cost preview that might run ahead of full
- * input validation (e.g. while a file is still being selected).
- *
- * `mode` defaults to the (cheaper) ASYNC weight when given an unrecognised
- * value, mirroring the ported formula's own `MODE_WEIGHT[mode] ?? MODE_WEIGHT.async`
- * fallback — never silently the MORE expensive weight.
- *
- * `mode`'s type is widened to `| 'sync' | 'async'` alongside the enum
- * itself, NOT just `ProbeScanMode`: apps/api's own server-side
- * `database/probe-scan.enum.ts#ProbeScanMode` is a SEPARATE TypeScript enum
- * declaration (kept server-local — see that file's header comment on why —
- * with the identical 'sync'/'async' runtime values, so the wire format never
- * drifts). TypeScript string enums are nominal: a same-valued member of that
- * OTHER enum is not directly assignable to THIS package's `ProbeScanMode`
- * parameter type, but IS assignable to a plain string-literal type matching
- * its value — so the server can call this exact function (`scan.mode`,
- * `estimateProbeScanCost`'s whole reason for living being ONE shared formula
- * on both sides of the wire, see this file's header comment) without a cast.
- */
-export const estimateProbeScanCost = (
-  sizeOctet: number,
-  mode: ProbeScanMode | 'sync' | 'async',
-): number => {
-  if (!Number.isFinite(sizeOctet) || sizeOctet <= 0) {
-    return 0;
-  }
-  const megabytes = Math.ceil(sizeOctet / ONE_MB);
-  const weight =
-    PROBE_SCAN_COST_MODE_WEIGHT[mode] ?? PROBE_SCAN_COST_MODE_WEIGHT[ProbeScanMode.ASYNC];
-  return Math.round((PROBE_SCAN_COST_BASE + PROBE_SCAN_COST_K_MB * megabytes) * weight);
-};
+// ──────────────────────────────────────────────
+// AbyssProbe scan cost model — pure, shared (client + server, no endpoint).
+//
+// Ported from abyss-storage's OWN weighted AV-scan cost model
+// (`apps/api/src/services/av-scan-usage.ts#computeAvScanCost`, introduced in
+// storage commit 317e4a0 "wire the weighted AV-scan quota", since made dead
+// code there by the AV v3 Phase 3b-2 hand-off — "storage never bills —
+// AbyssProbe does" — but the FORMULA itself is exactly what AbyssProbe's own
+// weighted billing needs, so it is ported here verbatim rather than
+// reinvented):
+//
+//   cost = round( (BASE + K_MB * ceil(sizeOctet / 1 MiB)) * MODE_WEIGHT[mode] )
+//
+// ASYNC costs LESS than SYNC (MODE_WEIGHT.async=1 < MODE_WEIGHT.sync=3) — a
+// synchronous scan holds the caller's request (and an engine worker) until
+// the verdict and cannot be batched/load-balanced, so it costs more than an
+// asynchronous (queued) scan of the SAME bytes. This is the numeric backing
+// for the scanner UI's "l'analyse en arrière-plan économise des tokens"
+// tooltip (WS1).
+//
+// PURE + DETERMINISTIC + no I/O: this is the SINGLE source of truth for
+// AbyssProbe's scan cost, used on BOTH sides of the wire —
+//   - server (apps/api/src/services/probe-scan.service.ts): the REAL cost
+//     billed via recordProbeScanUsage and persisted on probe_scans.costUnits
+//     once a scan reaches a verdict (DONE).
+//   - client (the AbyssProbe UI, or any external caller): a cost PREVIEW
+//     before scanning — call this with the picked file's size and the
+//     intended mode to show the estimated token cost, matching exactly what
+//     the server will bill (no separate "estimate" formula to drift out of
+//     sync with the real one — same function, same constants, both sides).
+//
+// Deliberately NOT exposed as an HTTP endpoint (no `POST /scan/estimate`):
+// the whole point of a pure function is that the client can compute it
+// locally, instantly, with zero round-trip — see this package's root README
+// note on `sdk.probe.*`'s HTTP-call-only convention; a helper like this one
+// (and `verifyProbeWebhookSignature` before it) is instead a plain top-level
+// export, not a `sdk.probe.*` method.
+// ──────────────────────────────────────────────
+
+import { ProbeScanMode } from '../types';
+
+/** Flat floor every scanned file pays (the "one scan" cost). Tunable. */
+export const PROBE_SCAN_COST_BASE = 1;
+
+/** Additional units per (ceil'd) mebibyte of scanned bytes. Tunable. */
+export const PROBE_SCAN_COST_K_MB = 1;
+
+/**
+ * Per-mode cost multiplier. A synchronous scan blocks the caller's request
+ * (and an engine worker) until the verdict and cannot be queued/batched, so
+ * it costs strictly MORE than an asynchronous scan of the same bytes —
+ * ASYNC < SYNC is a load-bearing invariant relied on by the scanner UI's
+ * "background analysis saves tokens" messaging (WS1). Tunable, but this
+ * ordering must never be inverted.
+ */
+export const PROBE_SCAN_COST_MODE_WEIGHT: Record<ProbeScanMode, number> = {
+  [ProbeScanMode.ASYNC]: 1,
+  [ProbeScanMode.SYNC]: 3,
+};
+
+/** One mebibyte, the unit the per-MB term is quantised to. */
+const ONE_MB = 1024 * 1024;
+
+/**
+ * Weighted cost of one AbyssProbe scan, in `ACCOUNT_AV_SCAN_UNITS` ("tokens"
+ * in the UI). Pure + deterministic — same inputs always produce the same
+ * output, no I/O, safe to call from a browser or a server.
+ *
+ * Returns `0` for a non-finite / non-positive `sizeOctet` (nothing to scan,
+ * nothing to bill) rather than throwing — a defensive, never-crash contract
+ * appropriate for a client-side cost preview that might run ahead of full
+ * input validation (e.g. while a file is still being selected).
+ *
+ * `mode` defaults to the (cheaper) ASYNC weight when given an unrecognised
+ * value, mirroring the ported formula's own `MODE_WEIGHT[mode] ?? MODE_WEIGHT.async`
+ * fallback — never silently the MORE expensive weight.
+ *
+ * `mode`'s type is widened to `| 'sync' | 'async'` alongside the enum
+ * itself, NOT just `ProbeScanMode`: apps/api's own server-side
+ * `database/probe-scan.enum.ts#ProbeScanMode` is a SEPARATE TypeScript enum
+ * declaration (kept server-local — see that file's header comment on why —
+ * with the identical 'sync'/'async' runtime values, so the wire format never
+ * drifts). TypeScript string enums are nominal: a same-valued member of that
+ * OTHER enum is not directly assignable to THIS package's `ProbeScanMode`
+ * parameter type, but IS assignable to a plain string-literal type matching
+ * its value — so the server can call this exact function (`scan.mode`,
+ * `estimateProbeScanCost`'s whole reason for living being ONE shared formula
+ * on both sides of the wire, see this file's header comment) without a cast.
+ */
+export const estimateProbeScanCost = (
+  sizeOctet: number,
+  mode: ProbeScanMode | 'sync' | 'async',
+): number => {
+  if (!Number.isFinite(sizeOctet) || sizeOctet <= 0) {
+    return 0;
+  }
+  const megabytes = Math.ceil(sizeOctet / ONE_MB);
+  const weight =
+    PROBE_SCAN_COST_MODE_WEIGHT[mode] ?? PROBE_SCAN_COST_MODE_WEIGHT[ProbeScanMode.ASYNC];
+  return Math.round((PROBE_SCAN_COST_BASE + PROBE_SCAN_COST_K_MB * megabytes) * weight);
+};

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

@@ -1,56 +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
-// the extraction signature header `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 (re-displayable on IProbeWebhook). */
-  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-require-imports
-  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;
-  }
-}
+// ──────────────────────────────────────────────
+// 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
+// the extraction signature header `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 (re-displayable on IProbeWebhook). */
+  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-require-imports
+  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/tsconfig.check.json

@@ -1,15 +1,15 @@
-{
-  // Perimetre de VERIFICATION, distinct de celui du build.
-  //
-  // `tsconfig.json` exclut `src/**/*.spec.ts` parce qu'il sert a emettre `dist/`, ou une spec
-  // n'a rien a faire. Mais eslint s'appuie sur ce meme fichier via `parserOptions.project` :
-  // les cinq specs du paquet sortaient donc en « Parsing error: that TSConfig does not include
-  // this file », mesure du 2026-09-09, et n'etaient lintees par personne.
-  //
-  // Ce fichier sert uniquement a eslint. Il n'emet rien et ne change pas ce que `build` produit.
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "noEmit": true
-  },
-  "exclude": ["./dist/**/*"]
-}
+{
+  // Perimetre de VERIFICATION, distinct de celui du build.
+  //
+  // `tsconfig.json` exclut `src/**/*.spec.ts` parce qu'il sert a emettre `dist/`, ou une spec
+  // n'a rien a faire. Mais eslint s'appuie sur ce meme fichier via `parserOptions.project` :
+  // les cinq specs du paquet sortaient donc en « Parsing error: that TSConfig does not include
+  // this file », mesure du 2026-09-09, et n'etaient lintees par personne.
+  //
+  // Ce fichier sert uniquement a eslint. Il n'emet rien et ne change pas ce que `build` produit.
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "exclude": ["./dist/**/*"]
+}

package/tsconfig.json

@@ -1,36 +1,36 @@
-{
-  "compilerOptions": {
-    "incremental": false,
-    "target": "es2021",
-    "lib": [
-      "dom",
-      "es2021"
-    ],
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    "module": "commonjs",
-    "rootDir": "src",
-    "moduleResolution": "node",
-    "resolveJsonModule": true,
-    "allowJs": true,
-    "declaration": true,
-    "sourceMap": true,
-    "outDir": "./dist",
-    "removeComments": true,
-    "allowSyntheticDefaultImports": true,
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "strict": true,
-    "strictNullChecks": true,
-    "strictFunctionTypes": true,
-    "strictPropertyInitialization": false,
-    "skipLibCheck": true
-  },
-  "include": [
-    "./src"
-  ],
-  "exclude": [
-    "./dist/**/*",
-    "./src/**/*.spec.ts"
-  ]
-}
+{
+  "compilerOptions": {
+    "incremental": false,
+    "target": "es2021",
+    "lib": [
+      "dom",
+      "es2021"
+    ],
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "module": "commonjs",
+    "rootDir": "src",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "declaration": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "removeComments": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictPropertyInitialization": false,
+    "skipLibCheck": true
+  },
+  "include": [
+    "./src"
+  ],
+  "exclude": [
+    "./dist/**/*",
+    "./src/**/*.spec.ts"
+  ]
+}