AgentHub/server/lib/audit.js

/**
 * @file audit.js
 * @description Server mode's audit trail (docs/SERVER-MODE.md): every read by
 * an admin or analyst of a session that a MEMBER owns — the session page, its
 * transcript, its events, its cost — is written to `audit_log` with who read
 * it, whose it was and which path. `auditGuard` runs on `/api` after the
 * scope guard; it never blocks a request, and it is a no-op in local mode and
 * for a member (who can only read their own). An admin's account change on
 * the Users page is written here too (`recordAccountChange`), and so is an
 * admin's look into another user's home (`recordHomeRead`, File Explorer).
 * Entries are kept `AGENTHUB_AUDIT_DAYS` days (default 180; `0` keeps them
 * all): older ones are deleted as new ones are written, at most once an hour.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

const sql = (q) => require("../db").db.prepare(q);

const DEFAULT_KEEP_DAYS = 180;
const PRUNE_EVERY_MS = 60 * 60 * 1000;
let lastPrune = 0;

/** Days of audit history kept; 0 = forever. */
function keepDays() {
  const v = process.env.AGENTHUB_AUDIT_DAYS;
  if (v === undefined || v === "") return DEFAULT_KEEP_DAYS;
  const n = Number(v);
  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : DEFAULT_KEEP_DAYS;
}

/** Deletes entries older than `keepDays()`; returns how many. `force` skips the hourly gate. */
function pruneAudit({ force = false } = {}) {
  const days = keepDays();
  if (!days || (!force && Date.now() - lastPrune < PRUNE_EVERY_MS)) return 0;
  lastPrune = Date.now();
  const cutoff = new Date(Date.now() - days * 864e5).toISOString();
  try {
    return sql("DELETE FROM audit_log WHERE at < ?").run(cutoff).changes;
  } catch (err) {
    console.warn("[audit] could not prune:", err.message);
    return 0;
  }
}

/** Writes one entry, then prunes when it is time. */
function insertEntry(userId, ownerId, sessionId, method, path) {
  sql(
    "INSERT INTO audit_log (user_id, owner_id, session_id, method, path) VALUES (?, ?, ?, ?, ?)"
  ).run(userId, ownerId, sessionId, method, path);
  pruneAudit();
}

// Paths that name one session's content.
const SESSION_PATHS = [
  /^\/sessions\/(?!facets\/?$)([^/]+)/i,
  /^\/pricing\/cost\/([^/]+)/i,
  /^\/workflows\/session\/([^/]+)/i,
];

function auditGuard(req, res, next) {
  const u = req.user;
  if (!u || u.role === "developer" || (req.method !== "GET" && req.method !== "HEAD"))
    return next();
  const p = require("./auth").apiPath(req);
  for (const re of SESSION_PATHS) {
    const m = re.exec(p);
    if (!m) continue;
    try {
      const { sessionOwners } = require("./scope");
      const id = m[1];
      for (const owner of sessionOwners(id)) {
        if (owner === u.id) continue;
        const ownerRole = sql("SELECT role FROM users WHERE id = ?").get(owner)?.role;
        if (ownerRole !== "developer") continue;
        insertEntry(u.id, owner, id, req.method, req.originalUrl.slice(0, 500));
      }
    } catch (err) {
      console.warn("[audit] could not record:", err.message);
    }
    break;
  }
  return next();
}

/** The newest entries, with user names. */
function listAudit(limit = 100) {
  const n = Math.min(Math.max(Number(limit) || 100, 1), 1000);
  return sql(
    `SELECT a.id, a.at, a.method, a.path, a.session_id,
            r.username AS reader, o.username AS owner,
            r.display_name AS reader_display, o.display_name AS owner_display
       FROM audit_log a
       LEFT JOIN users r ON r.id = a.user_id
       LEFT JOIN users o ON o.id = a.owner_id
      ORDER BY a.id DESC LIMIT ?`
  ).all(n);
}

/** An admin's account change from the Users page: who, on whom, what (never
 *  a password). `owner_id` is the account changed; `path` carries the action. */
function recordAccountChange(actorId, targetId, method, action) {
  insertEntry(actorId, targetId, null, method, String(action).slice(0, 500));
}

/** An admin opening another user's home in the File Explorer (read-only). */
function recordHomeRead(actorId, ownerId, method, what) {
  try {
    insertEntry(actorId, ownerId, null, method, String(what).slice(0, 500));
  } catch (err) {
    console.warn("[audit] could not record:", err.message);
  }
}

module.exports = { auditGuard, listAudit, recordAccountChange, recordHomeRead, pruneAudit };