@danielblomma/cortex-mcp 1.7.2 → 2.0.3

package/scaffold/mcp/src/daemon/heartbeat-tracker.ts

@@ -0,0 +1,223 @@
+import { writeFileSync, existsSync, unlinkSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { hostname } from "node:os";
+import type { HeartbeatPayload, HeartbeatResult } from "./protocol.js";
+import { writeHostAuditEvent } from "./ungoverned-scanner.js";
+
+/**
+ * Hook heartbeat tracker for Phase 6 tamper-detection.
+ *
+ * Each hook invocation pings the daemon. The daemon tracks per-session
+ * "last seen any hook" timestamps. A session is considered active from
+ * the first SessionStart heartbeat until SessionEnd (or auto-cleanup
+ * after a long stale interval).
+ *
+ * Tamper detection (periodic): if an active session has had at least
+ * one non-SessionStart heartbeat (so we know hooks were genuinely
+ * firing) and then nothing within `missingThresholdSeconds`, we flag
+ * it. Pure idle sessions where the user just left Claude open without
+ * doing anything do not match the "had-activity-then-silence" pattern.
+ */
+
+export type SessionState = {
+  cli: HeartbeatPayload["cli"];
+  cwd: string;
+  started_at: string;
+  last_heartbeat: string;
+  hook_count: number;
+  ended: boolean;
+  ended_at?: string;
+};
+
+export type TamperLockEntry = {
+  version: 1;
+  detected_at: string;
+  cli: HeartbeatPayload["cli"];
+  session_id: string;
+  hook_name: string;
+  last_seen: string;
+  missing_seconds: number;
+  host_id: string;
+  cwd: string;
+};
+
+export const TAMPER_LOCK_FILENAME = ".cortex-tamper.lock";
+
+export type TamperCheckOptions = {
+  cwds: string[];
+  missingThresholdSeconds: number;
+  now?: Date;
+  onTamperDetected?: (entry: TamperLockEntry) => void;
+};
+
+export class HeartbeatTracker {
+  private sessions = new Map<string, SessionState>();
+  private hostId: string;
+  private cleanupAfterMs: number;
+
+  constructor(
+    options: { hostId?: string; cleanupAfterMs?: number } = {},
+  ) {
+    this.hostId = options.hostId ?? hostname();
+    // Sessions with no heartbeat for this long are auto-removed (covers
+    // crashes that never sent SessionEnd). Default 12h.
+    this.cleanupAfterMs = options.cleanupAfterMs ?? 12 * 60 * 60 * 1000;
+  }
+
+  recordHeartbeat(payload: HeartbeatPayload): HeartbeatResult {
+    const existing = this.sessions.get(payload.session_id);
+    const now = payload.ts;
+
+    if (payload.hook === "SessionStart") {
+      this.sessions.set(payload.session_id, {
+        cli: payload.cli,
+        cwd: payload.cwd,
+        started_at: now,
+        last_heartbeat: now,
+        hook_count: 1,
+        ended: false,
+      });
+    } else if (payload.hook === "SessionEnd") {
+      if (existing) {
+        existing.last_heartbeat = now;
+        existing.ended = true;
+        existing.ended_at = now;
+        existing.hook_count += 1;
+      } else {
+        // SessionEnd without prior SessionStart — register a closed session
+        // so the tamper-checker doesn't flag it later.
+        this.sessions.set(payload.session_id, {
+          cli: payload.cli,
+          cwd: payload.cwd,
+          started_at: now,
+          last_heartbeat: now,
+          hook_count: 1,
+          ended: true,
+          ended_at: now,
+        });
+      }
+    } else {
+      if (existing) {
+        existing.last_heartbeat = now;
+        existing.hook_count += 1;
+      } else {
+        // Heartbeat from a session we never saw start (daemon was restarted
+        // mid-session). Register it as active.
+        this.sessions.set(payload.session_id, {
+          cli: payload.cli,
+          cwd: payload.cwd,
+          started_at: now,
+          last_heartbeat: now,
+          hook_count: 1,
+          ended: false,
+        });
+      }
+    }
+
+    const tamperLockActive = existsSync(
+      join(payload.cwd, ".context", TAMPER_LOCK_FILENAME),
+    );
+    return { recorded: true, tamper_lock_active: tamperLockActive };
+  }
+
+  getActiveSessions(): Array<[string, SessionState]> {
+    return Array.from(this.sessions.entries()).filter(
+      ([, state]) => !state.ended,
+    );
+  }
+
+  detectTamper(options: TamperCheckOptions): TamperLockEntry[] {
+    const now = options.now ?? new Date();
+    const thresholdMs = options.missingThresholdSeconds * 1000;
+    const flagged: TamperLockEntry[] = [];
+
+    for (const [sessionId, state] of this.sessions) {
+      // Cleanup sessions that have been silent forever — they crashed.
+      const lastMs = new Date(state.last_heartbeat).getTime();
+      if (Number.isFinite(lastMs) && now.getTime() - lastMs > this.cleanupAfterMs) {
+        this.sessions.delete(sessionId);
+        continue;
+      }
+
+      if (state.ended) continue;
+      // Need at least 2 heartbeats for the "had-activity-then-silence"
+      // signal — a single SessionStart followed by silence may just be a
+      // user opening Claude and walking away.
+      if (state.hook_count < 2) continue;
+
+      const elapsedMs = now.getTime() - lastMs;
+      if (elapsedMs <= thresholdMs) continue;
+
+      const entry: TamperLockEntry = {
+        version: 1,
+        detected_at: now.toISOString(),
+        cli: state.cli,
+        session_id: sessionId,
+        hook_name: "any",
+        last_seen: state.last_heartbeat,
+        missing_seconds: Math.round(elapsedMs / 1000),
+        host_id: this.hostId,
+        cwd: state.cwd,
+      };
+      flagged.push(entry);
+      // Mark ended so we don't re-flag the same session every tick.
+      state.ended = true;
+      state.ended_at = now.toISOString();
+      options.onTamperDetected?.(entry);
+    }
+
+    return flagged;
+  }
+
+  // For tests:
+  _forceState(sessionId: string, state: SessionState): void {
+    this.sessions.set(sessionId, state);
+  }
+  _size(): number {
+    return this.sessions.size;
+  }
+}
+
+export function writeTamperLock(cwd: string, entry: TamperLockEntry): string {
+  const dir = join(cwd, ".context");
+  const path = join(dir, TAMPER_LOCK_FILENAME);
+  writeFileSync(path, JSON.stringify(entry, null, 2) + "\n", "utf8");
+  return path;
+}
+
+export function readTamperLock(cwd: string): TamperLockEntry | null {
+  const path = join(cwd, ".context", TAMPER_LOCK_FILENAME);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as TamperLockEntry;
+  } catch {
+    return null;
+  }
+}
+
+export function removeTamperLock(cwd: string): boolean {
+  const path = join(cwd, ".context", TAMPER_LOCK_FILENAME);
+  if (!existsSync(path)) return false;
+  try {
+    unlinkSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function emitTamperAudit(
+  cwd: string,
+  entry: TamperLockEntry,
+): Promise<void> {
+  await writeHostAuditEvent(cwd, {
+    event_type: "hook_tamper_detected",
+    timestamp: entry.detected_at,
+    host_id: entry.host_id,
+    cli: entry.cli,
+    session_id: entry.session_id,
+    hook_name: entry.hook_name,
+    last_seen: entry.last_seen,
+    missing_seconds: entry.missing_seconds,
+  });
+}

package/scaffold/mcp/src/daemon/host-events-pusher.ts

@@ -0,0 +1,285 @@
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+  mkdirSync,
+  statSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { loadEnterpriseConfig } from "../core/config.js";
+
+/**
+ * Phase 7 sync flow — host-events pusher.
+ *
+ * The daemon writes ungoverned-session and hook-tamper events to
+ * .context/audit/host-events-YYYY-MM-DD.jsonl. This pusher batches
+ * unpushed events and POSTs them to the cortex-web govern endpoints.
+ *
+ * State (.context/.cortex-host-events-cursor.json) tracks the last
+ * pushed timestamp per event_type so we don't double-push or skip.
+ */
+
+const CURSOR_FILENAME = ".cortex-host-events-cursor.json";
+
+type Cursor = {
+  ungoverned_last_ts?: string;
+  tamper_last_ts?: string;
+};
+
+/**
+ * Cursor format is `${ISO_TIMESTAMP}#${stable_id}` where stable_id is
+ * the pid for ungoverned events and the session_id for tamper events.
+ * The composite suffix breaks ties when two writers emit at the exact
+ * same millisecond (clock resolution / two daemon producers).
+ *
+ * For backward compatibility, a persisted value with no `#` is treated
+ * as `${ts}#~`: `~` sorts after every printable ASCII character we
+ * actually emit, so an old cursor still skips all events at-or-before
+ * its timestamp on the first read after upgrade.
+ */
+function readCursor(cwd: string): Cursor {
+  const path = join(cwd, ".context", CURSOR_FILENAME);
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as Cursor;
+  } catch {
+    return {};
+  }
+}
+
+function normalizeCursor(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  return value.includes("#") ? value : `${value}#~`;
+}
+
+function stableIdFor(evt: HostEvent): string {
+  if (evt.event_type === "ungoverned_ai_session_detected") {
+    const pid = evt.pid;
+    if (typeof pid === "number") return String(pid);
+    if (typeof pid === "string" && pid.length > 0) return pid;
+    return "0";
+  }
+  if (evt.event_type === "hook_tamper_detected") {
+    const sid = evt.session_id;
+    if (typeof sid === "string" && sid.length > 0) return sid;
+    return "";
+  }
+  return "";
+}
+
+function compositeKey(evt: HostEvent): string | null {
+  const ts = eventTimestamp(evt);
+  if (!ts) return null;
+  return `${ts}#${stableIdFor(evt)}`;
+}
+
+function sortByTs<T extends HostEvent>(arr: T[]): T[] {
+  return arr.sort((a, b) => {
+    const ka = compositeKey(a) ?? "";
+    const kb = compositeKey(b) ?? "";
+    if (ka < kb) return -1;
+    if (ka > kb) return 1;
+    return 0;
+  });
+}
+
+function writeCursor(cwd: string, cursor: Cursor): void {
+  const path = join(cwd, ".context", CURSOR_FILENAME);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(cursor, null, 2) + "\n", "utf8");
+}
+
+type HostEvent = Record<string, unknown> & { event_type?: string; timestamp?: string };
+
+function listHostEventFiles(cwd: string): string[] {
+  const dir = join(cwd, ".context", "audit");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.startsWith("host-events-") && name.endsWith(".jsonl"))
+    .sort()
+    .map((name) => join(dir, name));
+}
+
+function readEventsFrom(file: string): HostEvent[] {
+  if (!existsSync(file)) return [];
+  const stat = statSync(file);
+  if (!stat.isFile()) return [];
+  const raw = readFileSync(file, "utf8");
+  const out: HostEvent[] = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line) as HostEvent);
+    } catch {
+      // skip malformed lines
+    }
+  }
+  return out;
+}
+
+function eventTimestamp(e: HostEvent): string | null {
+  const ts = e.timestamp ?? e.detected_at;
+  return typeof ts === "string" ? ts : null;
+}
+
+function isAfterComposite(evt: HostEvent, cursor: string | undefined): boolean {
+  if (!cursor) return true;
+  const key = compositeKey(evt);
+  if (!key) return false;
+  return key > cursor;
+}
+
+export type PushOutcome = {
+  ungoverned_pushed: number;
+  tamper_pushed: number;
+  errors: string[];
+};
+
+export async function pushHostEvents(cwd: string): Promise<PushOutcome> {
+  const outcome: PushOutcome = {
+    ungoverned_pushed: 0,
+    tamper_pushed: 0,
+    errors: [],
+  };
+
+  const config = loadEnterpriseConfig(join(cwd, ".context"));
+  const apiKey = config.enterprise.api_key.trim();
+  const baseUrl = (config.enterprise.base_url || config.enterprise.endpoint).trim();
+  if (!apiKey || !baseUrl) {
+    outcome.errors.push("enterprise not configured");
+    return outcome;
+  }
+
+  const cursor = readCursor(cwd);
+  const ungovernedCursor = normalizeCursor(cursor.ungoverned_last_ts);
+  const tamperCursor = normalizeCursor(cursor.tamper_last_ts);
+  const ungoverned: HostEvent[] = [];
+  const tamper: HostEvent[] = [];
+
+  for (const file of listHostEventFiles(cwd)) {
+    for (const evt of readEventsFrom(file)) {
+      const ts = eventTimestamp(evt);
+      if (!ts) continue;
+      if (evt.event_type === "ungoverned_ai_session_detected" && isAfterComposite(evt, ungovernedCursor)) {
+        ungoverned.push(evt);
+      } else if (evt.event_type === "hook_tamper_detected" && isAfterComposite(evt, tamperCursor)) {
+        tamper.push(evt);
+      }
+    }
+  }
+
+  sortByTs(ungoverned);
+  sortByTs(tamper);
+
+  if (ungoverned.length > 0) {
+    const result = await pushBatch(
+      `${baseUrl.replace(/\/$/, "")}/api/v1/govern/ungoverned`,
+      apiKey,
+      {
+        events: ungoverned.map(toUngovernedPayload),
+      },
+    );
+    if (result.ok) {
+      outcome.ungoverned_pushed = ungoverned.length;
+      const last = ungoverned[ungoverned.length - 1];
+      cursor.ungoverned_last_ts = compositeKey(last) ?? cursor.ungoverned_last_ts;
+    } else {
+      outcome.errors.push(`ungoverned: ${result.error}`);
+    }
+  }
+
+  if (tamper.length > 0) {
+    const result = await pushBatch(
+      `${baseUrl.replace(/\/$/, "")}/api/v1/govern/tamper`,
+      apiKey,
+      {
+        events: tamper.map(toTamperPayload),
+      },
+    );
+    if (result.ok) {
+      outcome.tamper_pushed = tamper.length;
+      const last = tamper[tamper.length - 1];
+      cursor.tamper_last_ts = compositeKey(last) ?? cursor.tamper_last_ts;
+    } else {
+      outcome.errors.push(`tamper: ${result.error}`);
+    }
+  }
+
+  if (outcome.ungoverned_pushed > 0 || outcome.tamper_pushed > 0) {
+    writeCursor(cwd, cursor);
+  }
+
+  return outcome;
+}
+
+function toUngovernedPayload(e: HostEvent): Record<string, unknown> {
+  return {
+    detected_at: e.timestamp,
+    host_id: e.host_id,
+    cli: e.cli,
+    binary_path: e.binary,
+    args: e.args,
+    sys_user: e.user,
+    parent_pid: e.ppid,
+    pid: e.pid,
+    action_taken: e.action ?? "logged",
+  };
+}
+
+function toTamperPayload(e: HostEvent): Record<string, unknown> {
+  return {
+    detected_at: e.timestamp,
+    host_id: e.host_id,
+    cli: e.cli,
+    hook_name: e.hook_name ?? "any",
+    session_id: e.session_id,
+    last_seen: e.last_seen ?? null,
+    missing_seconds: e.missing_seconds,
+  };
+}
+
+async function pushBatch(
+  url: string,
+  apiKey: string,
+  payload: unknown,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify(payload),
+    });
+    if (!res.ok) {
+      return { ok: false, error: `HTTP ${res.status} ${res.statusText}` };
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export type PusherHandle = {
+  stop(): void;
+};
+
+export function startHostEventsPusher(cwd: string, intervalMs: number): PusherHandle {
+  const tick = () => {
+    void pushHostEvents(cwd).catch((err) => {
+      process.stderr.write(
+        `[cortex-daemon] host-events push failed: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+    });
+  };
+  void Promise.resolve().then(tick);
+  const handle = setInterval(tick, intervalMs);
+  if (typeof handle.unref === "function") handle.unref();
+  return {
+    stop() {
+      clearInterval(handle);
+    },
+  };
+}