@kya-os/checkpoint-wasm-runtime 1.5.1 → 1.6.0

package/dist/policy.d.mts

@@ -0,0 +1,148 @@
+import { D as Decision } from './types-C3RniIOM.mjs';
+export { B as BlockReason } from './types-C3RniIOM.mjs';
+import '@kya-os/checkpoint-shared';
+
+/**
+ * Cedar policy-evaluator bridge — Node fallback.
+ *
+ * Surfaces the `PolicyEvaluator` class exported by the cedar-enabled
+ * `kya-os-engine` WASM artifact (built by
+ * `rust/scripts/build-engine-cedar-wasm.sh`, gated on the Rust
+ * `wasm,cedar` features). A JS host (the gateway) compiles a tenant
+ * policy bundle once and authorizes many requests against it in-process,
+ * with no round-trip to a separate policy service.
+ *
+ * The cedar artifact is a SEPARATE, larger binary than the lean
+ * detection artifact — it pulls in `cedar-policy`. Detection-only
+ * consumers load `./engine` (the lean `verify()` glue); only callers that
+ * need in-process authorization reach for this bridge.
+ *
+ * ## Lazy loading
+ *
+ * The cedar `--target nodejs` glue instantiates the ~2 MB cedar WASM the
+ * moment it is `require`d (it `fs.readFileSync`s its `.wasm` sibling at
+ * module load). To keep the separate-artifact promise — detection-only
+ * consumers must NOT pay cedar's memory/startup — the glue is loaded
+ * LAZILY: nothing happens on `import`; the artifact is `require`d (and
+ * memoised) only on the first {@link createPolicyEvaluator} call. This is
+ * also why cedar lives behind the dedicated `./policy` subpath and is NOT
+ * re-exported from the `./node` barrel.
+ *
+ * `createRequire(__filename)` resolves the glue at call time in both
+ * builds — native `require` under CJS, the tsup `shims` / `createRequire`
+ * banner under ESM. The glue stays external (regex
+ * `wasm/kya-os-engine-cedar/` in tsup's `commonOpts.external`), so its
+ * `__dirname` resolves against `node_modules/.../wasm/kya-os-engine-cedar/`
+ * where the `.wasm` lives, and `"type": "commonjs"` on the artifact's
+ * package.json keeps Node from throwing `ERR_REQUIRE_ESM`.
+ *
+ * Direct .wasm path (for callers building their own loaders):
+ *   `@kya-os/checkpoint-wasm-runtime/wasm/kya-os-engine-cedar/kya_os_engine_bg.wasm`
+ */
+
+/**
+ * Owned, plain-data request the host hands to
+ * {@link PolicyEvaluatorRuntime.authorize}. Mirrors the Rust
+ * `AuthorizeInput` (`rust/crates/kya-os-engine/src/policy/authorize.rs`);
+ * keys are camelCase across the wasm-bindgen boundary, matching every
+ * other engine wire type.
+ *
+ * The evaluator is **synchronous over pre-resolved facts** (H-1 Kickoff
+ * § 4.5): the host pre-fetches the agent's delegation chain, reputation,
+ * etc. and ships the results here — no JS callbacks cross the boundary.
+ *
+ * `agentDid` and `reputation` are optional (omit or pass `undefined` for
+ * an anonymous or reputation-less request); `grantedScopes` defaults to an
+ * empty list when omitted.
+ */
+interface AuthorizeInput {
+    /** Agent DID if identity has been established, otherwise omitted. */
+    agentDid?: string;
+    /** The action being requested (e.g., `"book_flight"`). */
+    action: string;
+    /** The resource being acted on (e.g., `"travel_api"`). */
+    resource: string;
+    /** Scopes granted by the agent's delegation chain. Defaults to `[]`. */
+    grantedScopes?: string[];
+    /** Agent's reputation score in `[0.0, 1.0]`, if computed. */
+    reputation?: number;
+    /** Tenant identifier. */
+    tenantId: string;
+}
+/**
+ * Structural type of the WASM `PolicyEvaluator` class the cedar glue
+ * exports. Pinned here so this bridge type-checks against the artifact's
+ * `.d.ts` (`constructor(policy_text: string)`, `authorize(input): any`,
+ * `free()`).
+ */
+interface WasmPolicyEvaluator {
+    authorize(input: AuthorizeInput): unknown;
+    free(): void;
+}
+/**
+ * Host-facing wrapper around one compiled Cedar policy bundle.
+ *
+ * Construction compiles the bundle once; every {@link authorize} call
+ * evaluates a single owned request against it without re-parsing policy
+ * text (the compile-once / evaluate-many contract the engine upholds,
+ * carried across the boundary).
+ */
+declare class PolicyEvaluatorRuntime {
+    private readonly inner;
+    /**
+     * @param inner - The compiled WASM `PolicyEvaluator` handle. Built in
+     *   {@link createPolicyEvaluator}; reused by every {@link authorize}
+     *   call for the lifetime of this wrapper.
+     */
+    constructor(inner: WasmPolicyEvaluator);
+    /**
+     * Authorize one owned request against the compiled policy bundle.
+     *
+     * The evaluator owns the fail-closed posture — a request it cannot
+     * marshal into Cedar, or one matching no `permit`, comes back as a
+     * {@link Decision} `Block` (not a thrown error). Authorization
+     * *verdicts* never throw; they surface inside the returned value.
+     *
+     * @throws {Error} only for boundary faults the WASM glue rejects: a
+     *   malformed `input` that fails `AuthorizeInput` deserialisation, or a
+     *   failure serialising the resulting `Decision`.
+     */
+    authorize(input: AuthorizeInput): Decision;
+    /**
+     * Release the compiled bundle's WASM memory. Call when the evaluator is
+     * no longer needed; after this the wrapper must not be reused.
+     */
+    free(): void;
+}
+/**
+ * Compile a Cedar policy bundle into a reusable in-process evaluator.
+ *
+ * Mirrors `createNodeDetector`'s WASM loading: routes through the cedar
+ * `--target nodejs` glue, which self-loads its `.wasm` sibling via CJS
+ * `__dirname` + `require('fs')`. The returned {@link PolicyEvaluatorRuntime}
+ * holds one compiled bundle and authorizes many requests against it.
+ *
+ * @param policyText - The tenant's Cedar policy bundle as source text.
+ * @throws {Error} if `policyText` is not syntactically valid Cedar — a
+ *   malformed bundle is an infrastructure fault surfaced here at
+ *   construction, never as a per-request deny.
+ *
+ * @example
+ * ```typescript
+ * import { createPolicyEvaluator } from '@kya-os/checkpoint-wasm-runtime/policy';
+ *
+ * const evaluator = createPolicyEvaluator('permit(principal, action, resource);');
+ * const decision = evaluator.authorize({
+ *   action: 'book_flight',
+ *   resource: 'travel_api',
+ *   tenantId: 'tenant-a',
+ *   grantedScopes: ['book_flight'],
+ * });
+ * if (decision.kind === 'Permit') {
+ *   // proceed
+ * }
+ * ```
+ */
+declare function createPolicyEvaluator(policyText: string): PolicyEvaluatorRuntime;
+
+export { type AuthorizeInput, Decision, PolicyEvaluatorRuntime, createPolicyEvaluator };

package/dist/policy.d.ts

@@ -0,0 +1,148 @@
+import { D as Decision } from './types-C3RniIOM.js';
+export { B as BlockReason } from './types-C3RniIOM.js';
+import '@kya-os/checkpoint-shared';
+
+/**
+ * Cedar policy-evaluator bridge — Node fallback.
+ *
+ * Surfaces the `PolicyEvaluator` class exported by the cedar-enabled
+ * `kya-os-engine` WASM artifact (built by
+ * `rust/scripts/build-engine-cedar-wasm.sh`, gated on the Rust
+ * `wasm,cedar` features). A JS host (the gateway) compiles a tenant
+ * policy bundle once and authorizes many requests against it in-process,
+ * with no round-trip to a separate policy service.
+ *
+ * The cedar artifact is a SEPARATE, larger binary than the lean
+ * detection artifact — it pulls in `cedar-policy`. Detection-only
+ * consumers load `./engine` (the lean `verify()` glue); only callers that
+ * need in-process authorization reach for this bridge.
+ *
+ * ## Lazy loading
+ *
+ * The cedar `--target nodejs` glue instantiates the ~2 MB cedar WASM the
+ * moment it is `require`d (it `fs.readFileSync`s its `.wasm` sibling at
+ * module load). To keep the separate-artifact promise — detection-only
+ * consumers must NOT pay cedar's memory/startup — the glue is loaded
+ * LAZILY: nothing happens on `import`; the artifact is `require`d (and
+ * memoised) only on the first {@link createPolicyEvaluator} call. This is
+ * also why cedar lives behind the dedicated `./policy` subpath and is NOT
+ * re-exported from the `./node` barrel.
+ *
+ * `createRequire(__filename)` resolves the glue at call time in both
+ * builds — native `require` under CJS, the tsup `shims` / `createRequire`
+ * banner under ESM. The glue stays external (regex
+ * `wasm/kya-os-engine-cedar/` in tsup's `commonOpts.external`), so its
+ * `__dirname` resolves against `node_modules/.../wasm/kya-os-engine-cedar/`
+ * where the `.wasm` lives, and `"type": "commonjs"` on the artifact's
+ * package.json keeps Node from throwing `ERR_REQUIRE_ESM`.
+ *
+ * Direct .wasm path (for callers building their own loaders):
+ *   `@kya-os/checkpoint-wasm-runtime/wasm/kya-os-engine-cedar/kya_os_engine_bg.wasm`
+ */
+
+/**
+ * Owned, plain-data request the host hands to
+ * {@link PolicyEvaluatorRuntime.authorize}. Mirrors the Rust
+ * `AuthorizeInput` (`rust/crates/kya-os-engine/src/policy/authorize.rs`);
+ * keys are camelCase across the wasm-bindgen boundary, matching every
+ * other engine wire type.
+ *
+ * The evaluator is **synchronous over pre-resolved facts** (H-1 Kickoff
+ * § 4.5): the host pre-fetches the agent's delegation chain, reputation,
+ * etc. and ships the results here — no JS callbacks cross the boundary.
+ *
+ * `agentDid` and `reputation` are optional (omit or pass `undefined` for
+ * an anonymous or reputation-less request); `grantedScopes` defaults to an
+ * empty list when omitted.
+ */
+interface AuthorizeInput {
+    /** Agent DID if identity has been established, otherwise omitted. */
+    agentDid?: string;
+    /** The action being requested (e.g., `"book_flight"`). */
+    action: string;
+    /** The resource being acted on (e.g., `"travel_api"`). */
+    resource: string;
+    /** Scopes granted by the agent's delegation chain. Defaults to `[]`. */
+    grantedScopes?: string[];
+    /** Agent's reputation score in `[0.0, 1.0]`, if computed. */
+    reputation?: number;
+    /** Tenant identifier. */
+    tenantId: string;
+}
+/**
+ * Structural type of the WASM `PolicyEvaluator` class the cedar glue
+ * exports. Pinned here so this bridge type-checks against the artifact's
+ * `.d.ts` (`constructor(policy_text: string)`, `authorize(input): any`,
+ * `free()`).
+ */
+interface WasmPolicyEvaluator {
+    authorize(input: AuthorizeInput): unknown;
+    free(): void;
+}
+/**
+ * Host-facing wrapper around one compiled Cedar policy bundle.
+ *
+ * Construction compiles the bundle once; every {@link authorize} call
+ * evaluates a single owned request against it without re-parsing policy
+ * text (the compile-once / evaluate-many contract the engine upholds,
+ * carried across the boundary).
+ */
+declare class PolicyEvaluatorRuntime {
+    private readonly inner;
+    /**
+     * @param inner - The compiled WASM `PolicyEvaluator` handle. Built in
+     *   {@link createPolicyEvaluator}; reused by every {@link authorize}
+     *   call for the lifetime of this wrapper.
+     */
+    constructor(inner: WasmPolicyEvaluator);
+    /**
+     * Authorize one owned request against the compiled policy bundle.
+     *
+     * The evaluator owns the fail-closed posture — a request it cannot
+     * marshal into Cedar, or one matching no `permit`, comes back as a
+     * {@link Decision} `Block` (not a thrown error). Authorization
+     * *verdicts* never throw; they surface inside the returned value.
+     *
+     * @throws {Error} only for boundary faults the WASM glue rejects: a
+     *   malformed `input` that fails `AuthorizeInput` deserialisation, or a
+     *   failure serialising the resulting `Decision`.
+     */
+    authorize(input: AuthorizeInput): Decision;
+    /**
+     * Release the compiled bundle's WASM memory. Call when the evaluator is
+     * no longer needed; after this the wrapper must not be reused.
+     */
+    free(): void;
+}
+/**
+ * Compile a Cedar policy bundle into a reusable in-process evaluator.
+ *
+ * Mirrors `createNodeDetector`'s WASM loading: routes through the cedar
+ * `--target nodejs` glue, which self-loads its `.wasm` sibling via CJS
+ * `__dirname` + `require('fs')`. The returned {@link PolicyEvaluatorRuntime}
+ * holds one compiled bundle and authorizes many requests against it.
+ *
+ * @param policyText - The tenant's Cedar policy bundle as source text.
+ * @throws {Error} if `policyText` is not syntactically valid Cedar — a
+ *   malformed bundle is an infrastructure fault surfaced here at
+ *   construction, never as a per-request deny.
+ *
+ * @example
+ * ```typescript
+ * import { createPolicyEvaluator } from '@kya-os/checkpoint-wasm-runtime/policy';
+ *
+ * const evaluator = createPolicyEvaluator('permit(principal, action, resource);');
+ * const decision = evaluator.authorize({
+ *   action: 'book_flight',
+ *   resource: 'travel_api',
+ *   tenantId: 'tenant-a',
+ *   grantedScopes: ['book_flight'],
+ * });
+ * if (decision.kind === 'Permit') {
+ *   // proceed
+ * }
+ * ```
+ */
+declare function createPolicyEvaluator(policyText: string): PolicyEvaluatorRuntime;
+
+export { type AuthorizeInput, Decision, PolicyEvaluatorRuntime, createPolicyEvaluator };

package/dist/policy.js

@@ -0,0 +1,52 @@
+'use strict';
+
+var module$1 = require('module');
+
+// src/policy-evaluator.ts
+var cedarRequire = module$1.createRequire(__filename);
+var cedarModule;
+function loadCedarModule() {
+  cedarModule ??= cedarRequire(
+    "@kya-os/checkpoint-wasm-runtime/wasm/kya-os-engine-cedar/kya_os_engine.js"
+  );
+  return cedarModule;
+}
+var PolicyEvaluatorRuntime = class {
+  /**
+   * @param inner - The compiled WASM `PolicyEvaluator` handle. Built in
+   *   {@link createPolicyEvaluator}; reused by every {@link authorize}
+   *   call for the lifetime of this wrapper.
+   */
+  constructor(inner) {
+    this.inner = inner;
+  }
+  /**
+   * Authorize one owned request against the compiled policy bundle.
+   *
+   * The evaluator owns the fail-closed posture — a request it cannot
+   * marshal into Cedar, or one matching no `permit`, comes back as a
+   * {@link Decision} `Block` (not a thrown error). Authorization
+   * *verdicts* never throw; they surface inside the returned value.
+   *
+   * @throws {Error} only for boundary faults the WASM glue rejects: a
+   *   malformed `input` that fails `AuthorizeInput` deserialisation, or a
+   *   failure serialising the resulting `Decision`.
+   */
+  authorize(input) {
+    return this.inner.authorize(input);
+  }
+  /**
+   * Release the compiled bundle's WASM memory. Call when the evaluator is
+   * no longer needed; after this the wrapper must not be reused.
+   */
+  free() {
+    this.inner.free();
+  }
+};
+function createPolicyEvaluator(policyText) {
+  const { PolicyEvaluator } = loadCedarModule();
+  return new PolicyEvaluatorRuntime(new PolicyEvaluator(policyText));
+}
+
+exports.PolicyEvaluatorRuntime = PolicyEvaluatorRuntime;
+exports.createPolicyEvaluator = createPolicyEvaluator;

package/dist/policy.mjs

@@ -0,0 +1,53 @@
+import { createRequire } from 'module';
+import 'path';
+import { fileURLToPath } from 'url';
+
+createRequire(import.meta.url);
+var getFilename = () => fileURLToPath(import.meta.url);
+var __filename$1 = /* @__PURE__ */ getFilename();
+var cedarRequire = createRequire(__filename$1);
+var cedarModule;
+function loadCedarModule() {
+  cedarModule ??= cedarRequire(
+    "@kya-os/checkpoint-wasm-runtime/wasm/kya-os-engine-cedar/kya_os_engine.js"
+  );
+  return cedarModule;
+}
+var PolicyEvaluatorRuntime = class {
+  /**
+   * @param inner - The compiled WASM `PolicyEvaluator` handle. Built in
+   *   {@link createPolicyEvaluator}; reused by every {@link authorize}
+   *   call for the lifetime of this wrapper.
+   */
+  constructor(inner) {
+    this.inner = inner;
+  }
+  /**
+   * Authorize one owned request against the compiled policy bundle.
+   *
+   * The evaluator owns the fail-closed posture — a request it cannot
+   * marshal into Cedar, or one matching no `permit`, comes back as a
+   * {@link Decision} `Block` (not a thrown error). Authorization
+   * *verdicts* never throw; they surface inside the returned value.
+   *
+   * @throws {Error} only for boundary faults the WASM glue rejects: a
+   *   malformed `input` that fails `AuthorizeInput` deserialisation, or a
+   *   failure serialising the resulting `Decision`.
+   */
+  authorize(input) {
+    return this.inner.authorize(input);
+  }
+  /**
+   * Release the compiled bundle's WASM memory. Call when the evaluator is
+   * no longer needed; after this the wrapper must not be reused.
+   */
+  free() {
+    this.inner.free();
+  }
+};
+function createPolicyEvaluator(policyText) {
+  const { PolicyEvaluator } = loadCedarModule();
+  return new PolicyEvaluatorRuntime(new PolicyEvaluator(policyText));
+}
+
+export { PolicyEvaluatorRuntime, createPolicyEvaluator };

package/dist/reporter.d.mts

@@ -0,0 +1,102 @@
+import { V as VerifyResult, f as EngineInfo } from './types-C3RniIOM.mjs';
+import '@kya-os/checkpoint-shared';
+
+/**
+ * Detection reporter — fire-and-forget POST to the dashboard's
+ * `/api/v1/log-detection` ingest endpoint.
+ *
+ * The engine-backed middlewares (`withCheckpoint` in `checkpoint-express`
+ * and `checkpoint-nextjs`) run verification locally via WASM. Without
+ * this reporter the verdict path works in-process but nothing flows
+ * back to the dashboard — the onboarding "Verify" check fails forever
+ * because the `detections` table never sees a row.
+ *
+ * Mirrors the contract of the legacy `CheckpointApiClient.logDetection`
+ * (see `checkpoint-nextjs/src/api-client.ts`) so the server-side
+ * ingest at `/api/v1/log-detection` accepts both paths identically.
+ *
+ * Subpath: `@kya-os/checkpoint-wasm-runtime/reporter`.
+ *
+ * @license MIT OR Apache-2.0
+ */
+
+/**
+ * Request context the middleware extracts from its framework-native
+ * request object. Shape matches the `ContextSchema` accepted by
+ * `/api/v1/log-detection`.
+ */
+interface ReporterContext {
+    userAgent?: string;
+    ipAddress?: string;
+    path?: string;
+    url?: string;
+    method?: string;
+}
+/**
+ * Configuration for the detection reporter.
+ */
+interface DetectionReporterConfig {
+    /**
+     * Project API key. Resolved server-side at the ingest endpoint into
+     * the project association used to insert the detection row. Required.
+     */
+    apiKey: string;
+    /**
+     * Dashboard base URL. Defaults to `https://kya.vouched.id`. Override
+     * for staging environments or self-hosted dashboards.
+     */
+    baseUrl?: string;
+    /**
+     * Per-request timeout in milliseconds. Defaults to 5000ms. The POST
+     * is fire-and-forget — a timeout aborts the request but never blocks
+     * the verdict path.
+     */
+    timeoutMs?: number;
+    /**
+     * Emit `console.warn` on reporter failures. Defaults to `false` —
+     * fire-and-forget means silent by design. Enable during development
+     * to surface mis-configured `apiKey` / `baseUrl`.
+     */
+    debug?: boolean;
+}
+/**
+ * Self-catching reporter promise. Call after every `verifyRequest`
+ * decision. Callers that can extend request lifetime (for example,
+ * NextFetchEvent.waitUntil) should attach this promise; callers that
+ * cannot may still ignore it safely because errors are swallowed
+ * (unless `debug: true`).
+ */
+type DetectionReporter = (result: VerifyResult, ctx: ReporterContext) => Promise<void>;
+/**
+ * Build a fire-and-forget reporter bound to a single project API key.
+ *
+ * The returned function is safe to call from any verdict path — it
+ * never throws, never awaits the network round-trip, and never affects
+ * the response.
+ */
+declare function makeDetectionReporter(config: DetectionReporterConfig): DetectionReporter;
+/**
+ * Translate the engine's `VerifyResult` into the request body shape
+ * accepted by `/api/v1/log-detection`. Exported for tests + for
+ * advanced consumers wiring a custom transport.
+ */
+declare function buildLogDetectionPayload(result: VerifyResult, ctx: ReporterContext): {
+    detection: {
+        isAgent: boolean;
+        confidence: number;
+        agentName: string | undefined;
+        agentType: string | undefined;
+        detectionClass: string | undefined;
+        verificationMethod: "signature" | "pattern" | "behavioral" | "network" | "mcp_i_handshake" | "none" | "error" | undefined;
+        reasons: string[];
+    };
+    context: ReporterContext;
+    source: "middleware";
+    enforcement: {
+        action: string;
+        reason?: string;
+    };
+    engine: EngineInfo | undefined;
+};
+
+export { type DetectionReporter, type DetectionReporterConfig, type ReporterContext, buildLogDetectionPayload, makeDetectionReporter };

package/dist/reporter.d.ts

@@ -0,0 +1,102 @@
+import { V as VerifyResult, f as EngineInfo } from './types-C3RniIOM.js';
+import '@kya-os/checkpoint-shared';
+
+/**
+ * Detection reporter — fire-and-forget POST to the dashboard's
+ * `/api/v1/log-detection` ingest endpoint.
+ *
+ * The engine-backed middlewares (`withCheckpoint` in `checkpoint-express`
+ * and `checkpoint-nextjs`) run verification locally via WASM. Without
+ * this reporter the verdict path works in-process but nothing flows
+ * back to the dashboard — the onboarding "Verify" check fails forever
+ * because the `detections` table never sees a row.
+ *
+ * Mirrors the contract of the legacy `CheckpointApiClient.logDetection`
+ * (see `checkpoint-nextjs/src/api-client.ts`) so the server-side
+ * ingest at `/api/v1/log-detection` accepts both paths identically.
+ *
+ * Subpath: `@kya-os/checkpoint-wasm-runtime/reporter`.
+ *
+ * @license MIT OR Apache-2.0
+ */
+
+/**
+ * Request context the middleware extracts from its framework-native
+ * request object. Shape matches the `ContextSchema` accepted by
+ * `/api/v1/log-detection`.
+ */
+interface ReporterContext {
+    userAgent?: string;
+    ipAddress?: string;
+    path?: string;
+    url?: string;
+    method?: string;
+}
+/**
+ * Configuration for the detection reporter.
+ */
+interface DetectionReporterConfig {
+    /**
+     * Project API key. Resolved server-side at the ingest endpoint into
+     * the project association used to insert the detection row. Required.
+     */
+    apiKey: string;
+    /**
+     * Dashboard base URL. Defaults to `https://kya.vouched.id`. Override
+     * for staging environments or self-hosted dashboards.
+     */
+    baseUrl?: string;
+    /**
+     * Per-request timeout in milliseconds. Defaults to 5000ms. The POST
+     * is fire-and-forget — a timeout aborts the request but never blocks
+     * the verdict path.
+     */
+    timeoutMs?: number;
+    /**
+     * Emit `console.warn` on reporter failures. Defaults to `false` —
+     * fire-and-forget means silent by design. Enable during development
+     * to surface mis-configured `apiKey` / `baseUrl`.
+     */
+    debug?: boolean;
+}
+/**
+ * Self-catching reporter promise. Call after every `verifyRequest`
+ * decision. Callers that can extend request lifetime (for example,
+ * NextFetchEvent.waitUntil) should attach this promise; callers that
+ * cannot may still ignore it safely because errors are swallowed
+ * (unless `debug: true`).
+ */
+type DetectionReporter = (result: VerifyResult, ctx: ReporterContext) => Promise<void>;
+/**
+ * Build a fire-and-forget reporter bound to a single project API key.
+ *
+ * The returned function is safe to call from any verdict path — it
+ * never throws, never awaits the network round-trip, and never affects
+ * the response.
+ */
+declare function makeDetectionReporter(config: DetectionReporterConfig): DetectionReporter;
+/**
+ * Translate the engine's `VerifyResult` into the request body shape
+ * accepted by `/api/v1/log-detection`. Exported for tests + for
+ * advanced consumers wiring a custom transport.
+ */
+declare function buildLogDetectionPayload(result: VerifyResult, ctx: ReporterContext): {
+    detection: {
+        isAgent: boolean;
+        confidence: number;
+        agentName: string | undefined;
+        agentType: string | undefined;
+        detectionClass: string | undefined;
+        verificationMethod: "signature" | "pattern" | "behavioral" | "network" | "mcp_i_handshake" | "none" | "error" | undefined;
+        reasons: string[];
+    };
+    context: ReporterContext;
+    source: "middleware";
+    enforcement: {
+        action: string;
+        reason?: string;
+    };
+    engine: EngineInfo | undefined;
+};
+
+export { type DetectionReporter, type DetectionReporterConfig, type ReporterContext, buildLogDetectionPayload, makeDetectionReporter };