@remnic/core 1.1.12 → 1.1.13

package/src/access-audit.test.ts

@@ -0,0 +1,178 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { AccessAuditAdapter } from "./access-audit.js";
+import type { RecallAuditEntry } from "./recall-audit.js";
+
+function makeEntry(q: string, ts = new Date().toISOString()): RecallAuditEntry {
+  return {
+    ts,
+    sessionKey: "session-a",
+    agentId: "agent-a",
+    trigger: "test",
+    queryText: q,
+    candidateMemoryIds: [],
+    summary: null,
+    injectedChars: 0,
+    toggleState: "enabled",
+  };
+}
+
+test("adapter with audit off and detection off is a no-op", async () => {
+  const adapter = new AccessAuditAdapter({
+    audit: { enabled: false, rootDir: "/dev/null" },
+    detection: { enabled: false },
+  });
+  const r = await adapter.record("p1", makeEntry("hi"));
+  assert.equal(r.appendedAt, undefined);
+  assert.equal(r.anomalies, undefined);
+});
+
+test("adapter runs detector in-memory when detection-only is enabled", async () => {
+  const adapter = new AccessAuditAdapter({
+    audit: { enabled: false, rootDir: "/dev/null" },
+    detection: {
+      enabled: true,
+      windowMs: 60_000,
+      repeatQueryLimit: 2,
+      namespaceWalkLimit: 1_000,
+      highCardinalityReturnLimit: 1_000,
+      rapidFireLimit: 1_000,
+    },
+  });
+  const now = Date.now();
+  for (let i = 0; i < 5; i++) {
+    await adapter.record(
+      "p1",
+      makeEntry("ALEX", new Date(now + i).toISOString()),
+      now + i,
+    );
+  }
+  const final = await adapter.record(
+    "p1",
+    makeEntry("ALEX", new Date(now + 100).toISOString()),
+    now + 100,
+  );
+  assert.ok(final.anomalies);
+  const repeat = final.anomalies.flags.find((f) => f.kind === "repeat-query");
+  assert.ok(repeat, "repeat-query flag should fire");
+});
+
+test("adapter buckets tail per-principal so bursts do not cross principals", async () => {
+  const adapter = new AccessAuditAdapter({
+    audit: { enabled: false, rootDir: "/dev/null" },
+    detection: {
+      enabled: true,
+      windowMs: 60_000,
+      repeatQueryLimit: 2,
+      namespaceWalkLimit: 1_000,
+      highCardinalityReturnLimit: 1_000,
+      rapidFireLimit: 1_000,
+    },
+  });
+  const now = Date.now();
+  // Alice bursts.
+  for (let i = 0; i < 5; i++) {
+    await adapter.record(
+      "alice",
+      makeEntry("x", new Date(now + i).toISOString()),
+      now + i,
+    );
+  }
+  // Bob issues a single query. The detector must not see Alice's entries
+  // in Bob's tail.
+  const bob = await adapter.record(
+    "bob",
+    makeEntry("x", new Date(now + 10).toISOString()),
+    now + 10,
+  );
+  assert.ok(bob.anomalies);
+  assert.equal(bob.anomalies.windowEntryCount, 1);
+  assert.equal(bob.anomalies.flags.length, 0);
+});
+
+test("adapter writes JSONL when audit is enabled and tolerates write failures", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "access-audit-"));
+  try {
+    const adapter = new AccessAuditAdapter({
+      audit: { enabled: true, rootDir: dir },
+      detection: { enabled: false },
+    });
+    const r = await adapter.record("p1", makeEntry("hi"));
+    assert.ok(r.appendedAt, "audit file path should be returned");
+    assert.ok(r.appendedAt.startsWith(dir));
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("audit write failure does not throw — the enclosing recall continues", async () => {
+  // Point at a path we expect to be unwritable — a file path used as a
+  // directory. appendRecallAuditEntry will ENOTDIR on mkdir; the adapter
+  // must swallow.
+  const adapter = new AccessAuditAdapter({
+    audit: { enabled: true, rootDir: "/dev/null/not-a-dir" },
+    detection: { enabled: false },
+  });
+  const r = await adapter.record("p1", makeEntry("hi"));
+  assert.equal(r.appendedAt, undefined);
+});
+
+test("trail buffer respects trailBufferSize", async () => {
+  const adapter = new AccessAuditAdapter({
+    audit: { enabled: false, rootDir: "/dev/null" },
+    detection: {
+      enabled: true,
+      windowMs: 60_000,
+      repeatQueryLimit: 1_000,
+      namespaceWalkLimit: 1_000,
+      highCardinalityReturnLimit: 1_000,
+      rapidFireLimit: 1_000,
+    },
+    trailBufferSize: 3,
+  });
+  const now = Date.now();
+  for (let i = 0; i < 10; i++) {
+    await adapter.record(
+      "p1",
+      makeEntry(`q-${i}`, new Date(now + i).toISOString()),
+      now + i,
+    );
+  }
+  const final = await adapter.record(
+    "p1",
+    makeEntry("final", new Date(now + 20).toISOString()),
+    now + 20,
+  );
+  assert.ok(final.anomalies);
+  assert.equal(final.anomalies.windowEntryCount, 3);
+});
+
+test("reset clears all tails", async () => {
+  const adapter = new AccessAuditAdapter({
+    audit: { enabled: false, rootDir: "/dev/null" },
+    detection: {
+      enabled: true,
+      windowMs: 60_000,
+      repeatQueryLimit: 1,
+      namespaceWalkLimit: 1_000,
+      highCardinalityReturnLimit: 1_000,
+      rapidFireLimit: 1_000,
+    },
+  });
+  const now = Date.now();
+  await adapter.record("p1", makeEntry("x", new Date(now).toISOString()), now);
+  await adapter.record("p1", makeEntry("x", new Date(now + 1).toISOString()), now + 1);
+  adapter.reset();
+  const r = await adapter.record(
+    "p1",
+    makeEntry("x", new Date(now + 2).toISOString()),
+    now + 2,
+  );
+  assert.ok(r.anomalies);
+  assert.equal(r.anomalies.windowEntryCount, 1);
+  assert.equal(r.anomalies.flags.length, 0);
+});

package/src/access-audit.ts

@@ -0,0 +1,125 @@
+/**
+ * Access-layer audit adapter (issue #565 PR 5/5).
+ *
+ * Wraps `appendRecallAuditEntry` + `detectRecallAnomalies` into a single
+ * entry point that MCP (`access-mcp.ts`) and HTTP (`access-http.ts`)
+ * surfaces can call once per recall. Closes the gap called out in the
+ * memory-extraction threat model §5: recall-audit previously only ran
+ * on the Openclaw hook, so MCP/HTTP callers bypassed the trail entirely.
+ *
+ * The adapter is a per-instance class so the tail-of-trail buffer
+ * (used by the anomaly detector) is scoped per-service, not global.
+ *
+ * No I/O unless `audit.enabled` is true; no detector invocation unless
+ * `detection.enabled` is true. Either flag may be enabled independently.
+ */
+
+import {
+  appendRecallAuditEntry,
+  type RecallAuditEntry,
+} from "./recall-audit.js";
+import {
+  detectRecallAnomalies,
+  type AnomalyDetectorConfig,
+  type AnomalyDetectorResult,
+} from "./recall-audit-anomaly.js";
+
+export interface AccessAuditConfig {
+  audit: {
+    enabled: boolean;
+    /** Root directory the audit adapter writes JSONL shards into. */
+    rootDir: string;
+  };
+  detection: AnomalyDetectorConfig;
+  /**
+   * How many entries the adapter retains in memory for the detector.
+   * Defaults to 256 — enough to cover the threat model's default 5-minute
+   * window at high recall rates without unbounded growth.
+   */
+  trailBufferSize?: number;
+}
+
+export interface AccessAuditResult {
+  /** Path of the JSONL shard the entry was appended to (only when audit enabled). */
+  appendedAt?: string;
+  /** Result of the anomaly detector (only when detection enabled). */
+  anomalies?: AnomalyDetectorResult;
+}
+
+/**
+ * Per-principal tail buffer. Distinct principals do not pollute each
+ * other's detection windows — otherwise one noisy legitimate client
+ * could mask an actual attacker.
+ */
+interface PrincipalTail {
+  entries: RecallAuditEntry[];
+}
+
+export class AccessAuditAdapter {
+  private readonly trails = new Map<string, PrincipalTail>();
+  private readonly trailBufferSize: number;
+
+  constructor(private readonly config: AccessAuditConfig) {
+    const n = config.trailBufferSize;
+    if (typeof n === "number" && Number.isFinite(n) && n > 0) {
+      const floored = Math.floor(n);
+      // Guard against fractional inputs (e.g. 0.5) that floor to 0.
+      this.trailBufferSize = floored >= 1 ? floored : 256;
+    } else {
+      this.trailBufferSize = 256;
+    }
+  }
+
+  /**
+   * Record an audit entry and (when enabled) run the anomaly detector
+   * over the principal's tail of entries. The principal key is used
+   * purely for tail-buffer bucketing — it need not match the production
+   * namespace resolver; sessionKey is the safe default.
+   */
+  async record(
+    principalKey: string,
+    entry: RecallAuditEntry,
+    now: number = Date.now(),
+  ): Promise<AccessAuditResult> {
+    const result: AccessAuditResult = {};
+
+    // Update the in-memory tail BEFORE the async audit write so a failed
+    // append never leaves the tail in a stale state. The detector must see
+    // every record regardless of whether the JSONL shard accepted it.
+    if (this.config.detection.enabled) {
+      const key = principalKey.length > 0 ? principalKey : "__anonymous__";
+      const tail = this.trails.get(key) ?? { entries: [] };
+      tail.entries.push(entry);
+      if (tail.entries.length > this.trailBufferSize) {
+        tail.entries.splice(0, tail.entries.length - this.trailBufferSize);
+      }
+      this.trails.set(key, tail);
+
+      result.anomalies = detectRecallAnomalies({
+        entries: tail.entries,
+        now,
+        config: this.config.detection,
+      });
+    }
+
+    if (this.config.audit.enabled) {
+      try {
+        result.appendedAt = await appendRecallAuditEntry(
+          this.config.audit.rootDir,
+          entry,
+        );
+      } catch {
+        // Audit write failures must never crash the enclosing recall.
+        // Swallow — operators can surface the ENOSPC / permission error
+        // via the usual filesystem monitoring.
+      }
+    }
+
+    return result;
+  }
+
+  /** Clear all in-memory tail state. Intended for tests / before_reset. */
+  reset(): void {
+    this.trails.clear();
+  }
+}