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

package/dist/reporter.js

@@ -0,0 +1,125 @@
+'use strict';
+
+// src/reporter/index.ts
+var DEFAULT_BASE_URL = "https://kya.vouched.id";
+var DEFAULT_TIMEOUT_MS = 5e3;
+var SINGLE_HASH_RULESET_REGEX = /^sha256:[a-f0-9]{64}$/;
+function makeDetectionReporter(config) {
+  if (!config.apiKey) {
+    throw new Error(
+      "makeDetectionReporter: `apiKey` is required. Without it the dashboard cannot associate detections with your project."
+    );
+  }
+  const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  const endpoint = `${baseUrl}/api/v1/log-detection`;
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const debug = config.debug ?? false;
+  return function reportDetection(result, ctx) {
+    const payload = buildLogDetectionPayload(result, ctx);
+    if (debug && !payload.engine && result.engineInfo?.rulesetHash) {
+      console.warn(
+        `[checkpoint-reporter] dropping engine field \u2014 rulesetHash "${result.engineInfo.rulesetHash}" doesn't match dashboard schema /^sha256:[a-f0-9]{64}$/. Detection row will land with NULL engine_* columns.`
+      );
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    return fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${config.apiKey}`
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+      keepalive: true
+    }).then((response) => {
+      if (!response.ok && debug) {
+        console.warn(
+          `[checkpoint-reporter] log-detection HTTP ${response.status} at ${endpoint}`
+        );
+      }
+    }).catch((err) => {
+      if (debug) {
+        console.warn("[checkpoint-reporter] log-detection failed:", err);
+      }
+    }).finally(() => clearTimeout(timeoutId));
+  };
+}
+function buildLogDetectionPayload(result, ctx) {
+  const detection = result.detectionDetail;
+  return {
+    detection: {
+      isAgent: detection.isAgent,
+      confidence: detection.confidence,
+      agentName: detection.detectedAgent?.name,
+      agentType: detection.detectedAgent?.type ?? detection.agentType,
+      detectionClass: stringifyDetectionClass(detection.detectionClass),
+      verificationMethod: detection.verificationMethod,
+      reasons: detection.reasons
+    },
+    context: ctx,
+    source: "middleware",
+    enforcement: extractEnforcement(result),
+    engine: sanitizeEngineInfo(result.engineInfo)
+  };
+}
+function sanitizeEngineInfo(engine) {
+  if (!engine) return void 0;
+  if (!SINGLE_HASH_RULESET_REGEX.test(engine.rulesetHash)) return void 0;
+  return engine;
+}
+var DETECTION_CLASS_WIRE = {
+  Human: "human",
+  AiAgent: "ai_agent",
+  Automation: "automation",
+  Bot: "bot",
+  IncompleteData: "incomplete_data",
+  Unknown: "unknown"
+};
+function stringifyDetectionClass(detectionClass) {
+  if (!detectionClass) return void 0;
+  if (typeof detectionClass === "string") {
+    return DETECTION_CLASS_WIRE[detectionClass] ?? detectionClass;
+  }
+  if (typeof detectionClass === "object" && "type" in detectionClass) {
+    const variant = String(detectionClass.type);
+    return DETECTION_CLASS_WIRE[variant];
+  }
+  return void 0;
+}
+function extractEnforcement(result) {
+  const decision = result.decision;
+  switch (decision.kind) {
+    case "Permit":
+      return { action: result.enforcementMode === "observe" ? "log" : "allow" };
+    case "Block":
+      return { action: "block", reason: decision.reason.kind };
+    case "Challenge":
+      return { action: "challenge" };
+    case "Redirect":
+      return { action: "redirect" };
+    case "Instruct":
+      return { action: "instruct" };
+  }
+}
+/**
+ * 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
+ */
+
+exports.buildLogDetectionPayload = buildLogDetectionPayload;
+exports.makeDetectionReporter = makeDetectionReporter;

package/dist/reporter.mjs

@@ -0,0 +1,122 @@
+// src/reporter/index.ts
+var DEFAULT_BASE_URL = "https://kya.vouched.id";
+var DEFAULT_TIMEOUT_MS = 5e3;
+var SINGLE_HASH_RULESET_REGEX = /^sha256:[a-f0-9]{64}$/;
+function makeDetectionReporter(config) {
+  if (!config.apiKey) {
+    throw new Error(
+      "makeDetectionReporter: `apiKey` is required. Without it the dashboard cannot associate detections with your project."
+    );
+  }
+  const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  const endpoint = `${baseUrl}/api/v1/log-detection`;
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const debug = config.debug ?? false;
+  return function reportDetection(result, ctx) {
+    const payload = buildLogDetectionPayload(result, ctx);
+    if (debug && !payload.engine && result.engineInfo?.rulesetHash) {
+      console.warn(
+        `[checkpoint-reporter] dropping engine field \u2014 rulesetHash "${result.engineInfo.rulesetHash}" doesn't match dashboard schema /^sha256:[a-f0-9]{64}$/. Detection row will land with NULL engine_* columns.`
+      );
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    return fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${config.apiKey}`
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+      keepalive: true
+    }).then((response) => {
+      if (!response.ok && debug) {
+        console.warn(
+          `[checkpoint-reporter] log-detection HTTP ${response.status} at ${endpoint}`
+        );
+      }
+    }).catch((err) => {
+      if (debug) {
+        console.warn("[checkpoint-reporter] log-detection failed:", err);
+      }
+    }).finally(() => clearTimeout(timeoutId));
+  };
+}
+function buildLogDetectionPayload(result, ctx) {
+  const detection = result.detectionDetail;
+  return {
+    detection: {
+      isAgent: detection.isAgent,
+      confidence: detection.confidence,
+      agentName: detection.detectedAgent?.name,
+      agentType: detection.detectedAgent?.type ?? detection.agentType,
+      detectionClass: stringifyDetectionClass(detection.detectionClass),
+      verificationMethod: detection.verificationMethod,
+      reasons: detection.reasons
+    },
+    context: ctx,
+    source: "middleware",
+    enforcement: extractEnforcement(result),
+    engine: sanitizeEngineInfo(result.engineInfo)
+  };
+}
+function sanitizeEngineInfo(engine) {
+  if (!engine) return void 0;
+  if (!SINGLE_HASH_RULESET_REGEX.test(engine.rulesetHash)) return void 0;
+  return engine;
+}
+var DETECTION_CLASS_WIRE = {
+  Human: "human",
+  AiAgent: "ai_agent",
+  Automation: "automation",
+  Bot: "bot",
+  IncompleteData: "incomplete_data",
+  Unknown: "unknown"
+};
+function stringifyDetectionClass(detectionClass) {
+  if (!detectionClass) return void 0;
+  if (typeof detectionClass === "string") {
+    return DETECTION_CLASS_WIRE[detectionClass] ?? detectionClass;
+  }
+  if (typeof detectionClass === "object" && "type" in detectionClass) {
+    const variant = String(detectionClass.type);
+    return DETECTION_CLASS_WIRE[variant];
+  }
+  return void 0;
+}
+function extractEnforcement(result) {
+  const decision = result.decision;
+  switch (decision.kind) {
+    case "Permit":
+      return { action: result.enforcementMode === "observe" ? "log" : "allow" };
+    case "Block":
+      return { action: "block", reason: decision.reason.kind };
+    case "Challenge":
+      return { action: "challenge" };
+    case "Redirect":
+      return { action: "redirect" };
+    case "Instruct":
+      return { action: "instruct" };
+  }
+}
+/**
+ * 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
+ */
+
+export { buildLogDetectionPayload, makeDetectionReporter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-os/checkpoint-wasm-runtime",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Checkpoint WASM runtime for AI agent detection across all environments (formerly @kya-os/agentshield-wasm-runtime)",
   "keywords": [
     "ai",
@@ -42,6 +42,11 @@
       "import": "./dist/node.mjs",
       "require": "./dist/node.js"
     },
+    "./policy": {
+      "types": "./dist/policy.d.ts",
+      "import": "./dist/policy.mjs",
+      "require": "./dist/policy.js"
+    },
     "./wasm": {
       "types": "./dist/wasm.d.ts",
       "import": "./dist/wasm.mjs"
@@ -111,10 +116,16 @@
       "import": "./dist/adapters.mjs",
       "require": "./dist/adapters.js"
     },
-    "./wasm/agentshield_wasm_bg.wasm": "./wasm/agentshield_wasm_bg.wasm",
+    "./reporter": {
+      "types": "./dist/reporter.d.ts",
+      "import": "./dist/reporter.mjs",
+      "require": "./dist/reporter.js"
+    },
     "./wasm/kya-os-engine/kya_os_engine_bg.wasm": "./wasm/kya-os-engine/kya_os_engine_bg.wasm",
     "./wasm/kya-os-engine-web/kya_os_engine_bg.wasm": "./wasm/kya-os-engine-web/kya_os_engine_bg.wasm",
     "./wasm/kya-os-engine-bundler/kya_os_engine_bg.wasm": "./wasm/kya-os-engine-bundler/kya_os_engine_bg.wasm",
+    "./wasm/kya-os-engine-cedar/kya_os_engine_bg.wasm": "./wasm/kya-os-engine-cedar/kya_os_engine_bg.wasm",
+    "./wasm/kya-os-engine-cedar-web/kya_os_engine_bg.wasm": "./wasm/kya-os-engine-cedar-web/kya_os_engine_bg.wasm",
     "./wasm/*": "./wasm/*",
     "./package.json": "./package.json"
   },
@@ -140,15 +151,14 @@
     "lint:fix": "eslint src --ext .ts,.tsx --fix",
     "format": "prettier --write \"src/**/*.{ts,tsx,json,md}\"",
     "format:check": "prettier --check \"src/**/*.{ts,tsx,json,md}\"",
-    "prepublishOnly": "pnpm copy-wasm && pnpm copy-engine-wasm && pnpm copy-engine-wasm-web && pnpm copy-engine-wasm-bundler && pnpm build && pnpm test",
-    "copy-wasm": "mkdir -p ./wasm && cp ../../rust/crates/agentshield-wasm/pkg/agentshield_wasm_bg.wasm ./wasm/",
+    "prepublishOnly": "pnpm copy-engine-wasm && pnpm copy-engine-wasm-web && pnpm copy-engine-wasm-bundler && pnpm build && pnpm test",
     "copy-engine-wasm": "mkdir -p ./wasm/kya-os-engine && cp ../../rust/crates/kya-os-engine/pkg/kya_os_engine_bg.wasm ../../rust/crates/kya-os-engine/pkg/kya_os_engine_bg.wasm.d.ts ../../rust/crates/kya-os-engine/pkg/kya_os_engine.d.ts ../../rust/crates/kya-os-engine/pkg/kya_os_engine.js ./wasm/kya-os-engine/",
     "copy-engine-wasm-web": "mkdir -p ./wasm/kya-os-engine-web && cp ../../rust/crates/kya-os-engine/pkg-web/kya_os_engine_bg.wasm ../../rust/crates/kya-os-engine/pkg-web/kya_os_engine_bg.wasm.d.ts ../../rust/crates/kya-os-engine/pkg-web/kya_os_engine.d.ts ../../rust/crates/kya-os-engine/pkg-web/kya_os_engine.js ./wasm/kya-os-engine-web/",
     "copy-engine-wasm-bundler": "mkdir -p ./wasm/kya-os-engine-bundler && cp ../../rust/crates/kya-os-engine/pkg-bundler/kya_os_engine_bg.wasm ../../rust/crates/kya-os-engine/pkg-bundler/kya_os_engine_bg.wasm.d.ts ../../rust/crates/kya-os-engine/pkg-bundler/kya_os_engine_bg.js ../../rust/crates/kya-os-engine/pkg-bundler/kya_os_engine.d.ts ../../rust/crates/kya-os-engine/pkg-bundler/kya_os_engine.js ./wasm/kya-os-engine-bundler/ && rm -f ./wasm/kya-os-engine-bundler/.gitignore",
     "wasm:rebuild": "bash ../../rust/scripts/build-engine-wasm.sh"
   },
   "dependencies": {
-    "@kya-os/checkpoint-shared": "1.1.0",
+    "@kya-os/checkpoint-shared": "1.2.0",
     "multiformats": "^13"
   },
   "devDependencies": {

package/wasm/kya-os-engine-cedar/README.md

@@ -0,0 +1,26 @@
+# kya-os-engine
+
+Verification engine for the KYA-OS ecosystem. Every TS / .NET / Go / Python /
+Cloudflare-Workers host wrapper is a thin shim around the WASM or WASI build of
+this crate. ADR-001 (Engine-Centric Consolidation) is the architectural
+decision; the locked public API contract is tracked in D-design
+([issue #2484][issue]) and mirrored at
+[`docs/architecture/D-design-ratification.md`][ratification].
+
+`kya-os-engine` is the root of the dependency graph. It depends on
+nothing from `@kya-os/*`, `agentshield-*`, or `checkpoint-*`; the
+direction is the other way.
+
+The public surface is one function (`verify`), one decision vocabulary (`Decision`
+with five variants — `Permit`, `Block`, `Challenge`, `Redirect`, `Instruct`),
+five dependency-injection traits (`DidResolver`, `StatusListCache`,
+`ReputationOracle`, `PolicyEvaluator`, `Clock`), and one canonical-signing-payload
+helper (`canonical_signing_payload`, RFC 8785 / JCS).
+
+This is the **Layer 1 API lock** (D-design, [issue #2484][issue]). The body of
+`verify()` is `todo!()`; trait methods are stubbed. D-impl
+([issue #2485][impl]) satisfies the contract.
+
+[issue]: https://github.com/Know-That-Ai/agent-shield/issues/2484
+[impl]: https://github.com/Know-That-Ai/agent-shield/issues/2485
+[ratification]: ../../../docs/architecture/D-design-ratification.md

package/wasm/kya-os-engine-cedar/kya_os_engine.d.ts

@@ -0,0 +1,77 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Cross-boundary `verify` wrapper. The JS host calls `engine.verify(input,
+ * ctxSpec)`; on success it gets a [`VerifyResult`] JSON object; on
+ * infrastructure failure (or malformed input) it gets a thrown JS error
+ * whose message names the failure mode.
+ *
+ * **Error semantics**:
+ *
+ * - Verification *verdicts* (Block/Challenge/etc.) surface inside the
+ *   returned `VerifyResult` — they are not thrown.
+ * - Engine [`VerifyError`][crate::error::VerifyError] (resolver / cache /
+ *   reputation / policy infra failures) surface as thrown JS errors.
+ * - Serde deserialisation failures (malformed JS input) surface as thrown
+ *   JS errors too, mirroring the typed-vs-thrown split.
+ *
+ * # JS signature
+ *
+ * ```ts
+ * function verify(input: AgentRequest, ctx: ContextSpec): VerifyResult;
+ * ```
+ */
+export function verify(input_js: any, ctx_js: any): any;
+/**
+ * Cross-boundary handle to a compiled Cedar policy bundle.
+ *
+ * Wraps a [`CedarPolicyEvaluator`] so a JS host can compile a tenant
+ * policy once and authorize many requests against it. Construction
+ * compiles the bundle; each [`authorize`][Self::authorize] call evaluates
+ * a single owned request and never re-parses policy text.
+ */
+export class PolicyEvaluator {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Compile `policy_text` into a reusable evaluator.
+   *
+   * The Cedar policy bundle is parsed and compiled exactly once here;
+   * the resulting evaluator is held for the lifetime of the handle and
+   * reused by every [`authorize`][Self::authorize] call.
+   *
+   * # Errors
+   *
+   * Returns a thrown JS error whose message names the failure when
+   * `policy_text` is not syntactically valid Cedar
+   * ([`PolicyEvaluationError::Malformed`][crate::error::PolicyEvaluationError::Malformed]).
+   * A malformed bundle is an infrastructure fault surfaced at
+   * construction, never as a per-request deny.
+   */
+  constructor(policy_text: string);
+  /**
+   * Authorize one owned request against the compiled policy bundle.
+   *
+   * The JS host calls `evaluator.authorize(input)` with an
+   * [`AuthorizeInput`]-shaped object (camelCase keys); it gets back a
+   * [`Decision`][crate::types::Decision] JSON object. The evaluator owns
+   * the fail-closed posture — a request it cannot marshal, or one
+   * matching no `permit`, comes back as a
+   * [`Decision::Block`][crate::types::Decision::Block], not a thrown
+   * error.
+   *
+   * # Errors
+   *
+   * Returns a thrown JS error only for boundary faults: a malformed
+   * `input_js` that fails [`AuthorizeInput`] deserialisation, or a
+   * failure serialising the resulting `Decision`. Authorization
+   * *verdicts* never throw — they surface inside the returned value.
+   *
+   * # JS signature
+   *
+   * ```ts
+   * authorize(input: AuthorizeInput): Decision;
+   * ```
+   */
+  authorize(input_js: any): any;
+}