@cirvix_ai/agent-control 0.1.3 → 0.2.0

package/src/core/referral.mjs

@@ -0,0 +1,187 @@
+/**
+ * Referrals.
+ *
+ * Separate from invitations on purpose. An invitation says "join MY
+ * organisation" and grants membership; a referral says "try this product" and
+ * grants nothing. Building them as one thing is how a referral link quietly
+ * becomes an access-control decision.
+ *
+ * DELIBERATELY BORING
+ * -------------------
+ * A code, a signup attributed to it, a qualification event, one reward. No
+ * tiers, no multi-level anything, no balances that can be spent. Every rewards
+ * economy starts simple and the complicated ones are complicated because
+ * somebody gamed the simple one; there is no reason to arrive there early.
+ *
+ * ABUSE IS THE DESIGN CONSTRAINT
+ * ------------------------------
+ * The three attacks that matter on a referral system, and what stops each:
+ *
+ *   · self-referral — refused at attribution; the referrer cannot be the
+ *     referred, checked on user AND on org, because one person owning two
+ *     orgs is the cheap version of the same attack
+ *   · replay — one referred party is attributed once, ever, even if the link
+ *     is clicked a hundred times
+ *   · reward-before-value — a signup earns nothing. Only a QUALIFYING event
+ *     does, and qualification is defined by the product, not by the referrer
+ *
+ * None of that needs a fraud engine. It needs the rules to be in one place
+ * with tests on them, which is what this file is.
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+
+export const REFERRAL_VERSION = 1;
+
+/** What a referred org must do before anything is earned. */
+export const QUALIFY = Object.freeze({
+  VERIFIED: "email_verified",
+  FIRST_DECISION: "first_decision_recorded",
+  SUBSCRIBED: "subscription_started",
+});
+
+/** The one reward. Usage, not money — it cannot be cashed out or transferred. */
+export const REWARD = Object.freeze({
+  kind: "decision_allowance",
+  amount: 5_000,
+  note: "5,000 additional recorded decisions, one time, per qualified referral.",
+});
+
+/**
+ * A referral code for an org.
+ *
+ * Derived, not random, so the same org always presents the same code and a
+ * lost code is recoverable without a database lookup. Salted with the issuing
+ * secret so codes cannot be enumerated from org ids, which are not secret.
+ */
+export function codeFor(orgId, { secret = "cirvix", length = 8 } = {}) {
+  if (!orgId) throw new Error("A referral code needs an org.");
+  const h = createHash("sha256").update(`${secret}:${orgId}`).digest("base64url");
+  return h.replace(/[^a-zA-Z0-9]/g, "").slice(0, length).toUpperCase();
+}
+
+export function linkFor(orgId, { base = "https://www.cirvix.com", secret } = {}) {
+  return `${base}/?ref=${codeFor(orgId, secret ? { secret } : {})}`;
+}
+
+/**
+ * The ledger.
+ *
+ * In-memory here; the control plane persists the same shape. Kept as a class
+ * so the rules live with the data rather than being re-implemented by whoever
+ * writes the SQL.
+ */
+export class ReferralLedger {
+  #byReferred = new Map();  // referred org -> attribution
+  #records = [];
+  #events = [];
+
+  constructor({ secret = "cirvix", onEvent = () => {} } = {}) {
+    this.secret = secret;
+    this.onEvent = onEvent;
+  }
+
+  /**
+   * Attributes a new org to a referrer.
+   *
+   * Returns a reason on refusal rather than throwing: a bad referral code is
+   * an ordinary thing for a signup to carry, and a signup must never fail
+   * because the marketing attribution did not work out.
+   */
+  attribute({ code, referredOrg, referredUser = null, referrerOrg = null, referrerUser = null, at = new Date().toISOString() }) {
+    if (!referredOrg) return { ok: false, reason: "no_referred_org" };
+    if (!code) return { ok: false, reason: "no_code" };
+
+    if (this.#byReferred.has(referredOrg)) {
+      return { ok: false, reason: "already_attributed", existing: this.#byReferred.get(referredOrg).referrerOrg };
+    }
+    /*
+     * A code must resolve to a referrer, and the check is unconditional.
+     *
+     * It was guarded by `if (referrerOrg && …)`, so a caller that could not
+     * resolve the code simply omitted the referrer and every check below was
+     * skipped — an arbitrary string was attributed to nobody and counted as a
+     * referral. Attribution without a verifiable referrer is not attribution,
+     * so it is refused here rather than recorded as a fact.
+     */
+    if (!referrerOrg) return { ok: false, reason: "unresolved_code" };
+    if (codeFor(referrerOrg, { secret: this.secret }) !== String(code).toUpperCase()) {
+      return { ok: false, reason: "code_mismatch" };
+    }
+    /* Self-referral, on both axes. One person holding two orgs is the cheap
+       version of the same attack, so the user check is not optional. */
+    if (referrerOrg && referrerOrg === referredOrg) return { ok: false, reason: "self_referral" };
+    if (referrerUser && referredUser && referrerUser === referredUser) return { ok: false, reason: "self_referral" };
+
+    const rec = {
+      v: REFERRAL_VERSION, code: String(code).toUpperCase(), referrerOrg, referrerUser,
+      referredOrg, referredUser, attributedAt: at, qualifiedAt: null, qualifyingEvent: null,
+      rewarded: false, reward: null,
+    };
+    this.#byReferred.set(referredOrg, rec);
+    this.#records.push(rec);
+    this.#emit("referral.attributed", rec, at);
+    return { ok: true, record: rec };
+  }
+
+  /**
+   * Marks a referred org as qualified, which is what earns the reward.
+   *
+   * A signup earns nothing. That is the whole anti-abuse position: creating
+   * accounts is free, and anything rewarded on account creation will be.
+   */
+  qualify({ referredOrg, event, at = new Date().toISOString() }) {
+    const rec = this.#byReferred.get(referredOrg);
+    if (!rec) return { ok: false, reason: "not_attributed" };
+    if (!Object.values(QUALIFY).includes(event)) return { ok: false, reason: "unknown_qualifying_event" };
+    if (rec.qualifiedAt) return { ok: false, reason: "already_qualified" };
+
+    rec.qualifiedAt = at;
+    rec.qualifyingEvent = event;
+    rec.rewarded = true;
+    rec.reward = { ...REWARD };
+    this.#emit("referral.qualified", rec, at);
+    return { ok: true, record: rec, reward: rec.reward };
+  }
+
+  /** What one org has earned, and from whom. Never exposes the referred org's users. */
+  forReferrer(orgId) {
+    const mine = this.#records.filter((r) => r.referrerOrg === orgId);
+    return {
+      code: codeFor(orgId, { secret: this.secret }),
+      link: linkFor(orgId, { secret: this.secret }),
+      invited: mine.length,
+      qualified: mine.filter((r) => r.qualifiedAt).length,
+      rewardTotal: mine.filter((r) => r.rewarded).length * REWARD.amount,
+      rewardKind: REWARD.kind,
+      referrals: mine.map((r) => ({
+        referredOrg: r.referredOrg,
+        attributedAt: r.attributedAt,
+        qualifiedAt: r.qualifiedAt,
+        qualifyingEvent: r.qualifyingEvent,
+        rewarded: r.rewarded,
+      })),
+    };
+  }
+
+  /** Every referral event, for the audit trail. */
+  events() {
+    return [...this.#events];
+  }
+
+  #emit(kind, rec, at) {
+    const ev = {
+      kind, at,
+      referrerOrg: rec.referrerOrg, referredOrg: rec.referredOrg,
+      qualifyingEvent: rec.qualifyingEvent ?? null,
+      reward: rec.rewarded ? REWARD.kind : null,
+    };
+    this.#events.push(ev);
+    this.onEvent(ev);
+  }
+}
+
+/** A fresh secret for deriving codes. */
+export function newReferralSecret() {
+  return randomBytes(32).toString("hex");
+}

package/src/core/sandbox.mjs

@@ -0,0 +1,139 @@
+/**
+ * Universal Agent Sandbox Abstraction.
+ *
+ * Provides isolation boundaries for agent executions across:
+ * - Filesystem root confinement
+ * - Process memory and timeout limits
+ * - Network destination allowlisting / link-local blocking
+ * - Adapter interfaces for Claude Code, Cursor, LangChain, CrewAI, MCP
+ */
+
+import { spawn } from "node:child_process";
+import { resolve, relative, isAbsolute } from "node:path";
+
+export const SANDBOX_ADAPTERS = {
+  CLAUDE_CODE: "claude_code",
+  CURSOR: "cursor",
+  LANGCHAIN: "langchain",
+  CREWAI: "crewai",
+  MCP: "mcp",
+  GENERIC_PROCESS: "generic_process",
+};
+
+export class AgentSandbox {
+  constructor({
+    adapter = SANDBOX_ADAPTERS.GENERIC_PROCESS,
+    fsRoot = process.cwd(),
+    timeoutMs = 30000,
+    maxMemoryMb = 512,
+    allowedDomains = [],
+    env = {},
+  } = {}) {
+    this.adapter = adapter;
+    this.fsRoot = resolve(fsRoot);
+    this.timeoutMs = timeoutMs;
+    this.maxMemoryMb = maxMemoryMb;
+    this.allowedDomains = new Set(allowedDomains.map((d) => d.toLowerCase()));
+    this.env = { ...env };
+    this.status = "ready";
+  }
+
+  /**
+   * Validates whether a file access is strictly within the sandbox filesystem boundary.
+   */
+  checkPathAccess(filePath) {
+    const target = isAbsolute(filePath) ? resolve(filePath) : resolve(this.fsRoot, filePath);
+    const rel = relative(this.fsRoot, target);
+    const isEscaped = rel.startsWith("..") || isAbsolute(rel);
+    return {
+      allowed: !isEscaped,
+      resolvedPath: target,
+      reason: isEscaped ? `Path '${filePath}' escapes sandbox boundary '${this.fsRoot}'` : "Path inside sandbox boundary",
+    };
+  }
+
+  /**
+   * Validates whether a network destination is permitted.
+   */
+  checkNetworkAccess(destinationUrl) {
+    try {
+      const url = new URL(destinationUrl);
+      const host = url.hostname.toLowerCase();
+
+      // Block link-local and cloud metadata by default
+      if (
+        host === "169.254.169.254" ||
+        host === "metadata.google.internal" ||
+        host === "100.100.100.200"
+      ) {
+        return {
+          allowed: false,
+          reason: "Access to cloud metadata endpoints is strictly blocked in sandbox",
+        };
+      }
+
+      // If allowedDomains is specified, enforce allowlist
+      if (this.allowedDomains.size > 0 && !this.allowedDomains.has(host)) {
+        return {
+          allowed: false,
+          reason: `Host '${host}' is not in sandbox allowed network destinations`,
+        };
+      }
+
+      return { allowed: true, reason: "Network destination permitted" };
+    } catch {
+      return { allowed: false, reason: `Malformed destination URL '${destinationUrl}'` };
+    }
+  }
+
+  /**
+   * Executes a command within the configured sandbox bounds.
+   */
+  async execute(command, args = [], { cwd = this.fsRoot } = {}) {
+    const pathCheck = this.checkPathAccess(cwd);
+    if (!pathCheck.allowed) {
+      throw new Error(`Execution cwd rejected: ${pathCheck.reason}`);
+    }
+
+    return new Promise((resolveResult, reject) => {
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        proc.kill("SIGKILL");
+        reject(new Error(`Sandbox execution exceeded timeout of ${this.timeoutMs}ms`));
+      }, this.timeoutMs);
+
+      const proc = spawn(command, args, {
+        cwd: pathCheck.resolvedPath,
+        env: {
+          ...process.env,
+          ...this.env,
+          CIRVIX_SANDBOX_ACTIVE: "1",
+        },
+        shell: false, // Prevents shell injection by default
+      });
+
+      let stdout = "";
+      let stderr = "";
+
+      proc.stdout?.on("data", (d) => (stdout += d.toString()));
+      proc.stderr?.on("data", (d) => (stderr += d.toString()));
+
+      proc.on("error", (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+
+      proc.on("close", (code) => {
+        clearTimeout(timer);
+        if (timedOut) return;
+        resolveResult({
+          code,
+          stdout,
+          stderr,
+          ok: code === 0,
+        });
+      });
+    });
+  }
+}

package/src/core/session.mjs

@@ -0,0 +1,172 @@
+/**
+ * Stateful Session Security & Action Chain Reasoning.
+ *
+ * Prevents multi-step attacks where each individual call may appear innocuous
+ * in isolation, but the sequence forms an exfiltration or reconnaissance attack.
+ *
+ * Example:
+ *   READ customer.csv (allowed)
+ *          ↓
+ *   compress / encode data (allowed)
+ *          ↓
+ *   POST external endpoint (BLOCKED: Data Exfiltration Chain)
+ */
+
+import { RISK } from "./risk.mjs";
+
+export const CHAIN_TYPES = {
+  EXFILTRATION: "DATA_EXFILTRATION",
+  RECONNAISSANCE: "RECONNAISSANCE",
+  PRIVILEGE_ESCALATION: "PRIVILEGE_ESCALATION",
+};
+
+/**
+ * Tracks session state, action history, taint propagation, and risk accumulation.
+ */
+export class SessionTracker {
+  constructor(sessionId, { agentId = null, maxHistory = 100 } = {}) {
+    this.sessionId = sessionId;
+    this.agentId = agentId;
+    this.history = [];
+    this.maxHistory = maxHistory;
+    this.cumulativeRisk = 0;
+    this.taint = {
+      readSensitiveData: false,
+      readSecrets: false,
+      encodedData: false,
+      accessedInternalNetwork: false,
+    };
+    this.status = "active"; // 'active' | 'quarantined' | 'terminated'
+    this.quarantineReason = null;
+    this.detectedChains = [];
+  }
+
+  /**
+   * Records a step in the session and analyzes emerging action chains.
+   *
+   * @param {Object} step
+   * @param {string} step.action - e.g. "fs:read", "net:post", "exec:run"
+   * @param {string} step.resource - Target path or URL
+   * @param {string} step.tool - Tool name
+   * @param {string} step.decision - ALLOW, DENY, etc.
+   * @param {string} step.risk - LOW, MEDIUM, HIGH, CRITICAL
+   * @returns {{ suspicious: boolean, chainDetected?: string, reason?: string, risk: number }}
+   */
+  recordStep({ action, resource = "", tool = "", decision = "ALLOW", risk = RISK.LOW }) {
+    const ts = new Date().toISOString();
+    const entry = { action, resource, tool, decision, risk, ts };
+
+    this.history.push(entry);
+    if (this.history.length > this.maxHistory) {
+      this.history.shift();
+    }
+
+    // Accumulate risk based on severity
+    const rLower = String(risk ?? "low").toLowerCase();
+    const riskPoints = {
+      low: 1,
+      medium: 5,
+      high: 15,
+      critical: 40,
+    }[rLower] ?? 1;
+
+    this.cumulativeRisk = Math.min(100, this.cumulativeRisk + riskPoints);
+
+    // Update taint flags
+    const resLower = String(resource).toLowerCase();
+    const actLower = String(action).toLowerCase();
+
+    if (
+      actLower.includes("read") &&
+      (resLower.includes("customer") ||
+        resLower.includes(".env") ||
+        resLower.includes("secret") ||
+        resLower.includes("token") ||
+        resLower.includes("credential") ||
+        resLower.includes("users") ||
+        resLower.includes("passwd"))
+    ) {
+      this.taint.readSensitiveData = true;
+    }
+
+    if (actLower.includes("secret") || resLower.includes("secret") || resLower.includes("key")) {
+      this.taint.readSecrets = true;
+    }
+
+    if (
+      actLower.includes("compress") ||
+      actLower.includes("encode") ||
+      resLower.includes(".tar") ||
+      resLower.includes(".zip") ||
+      resLower.includes("base64")
+    ) {
+      this.taint.encodedData = true;
+    }
+
+    if (actLower.includes("net") || resLower.startsWith("http://") || resLower.startsWith("https://")) {
+      if (resLower.includes("169.254.") || resLower.includes("10.") || resLower.includes("192.168.")) {
+        this.taint.accessedInternalNetwork = true;
+      }
+    }
+
+    // Check for exfiltration chain:
+    // Session previously read sensitive data/secrets -> now attempting external egress
+    const isEgress = actLower.includes("net") || actLower.includes("egress") || actLower.includes("post") || actLower.includes("curl");
+    const isExternalDest = resLower.startsWith("http://") || resLower.startsWith("https://");
+
+    if ((this.taint.readSensitiveData || this.taint.readSecrets) && isEgress && isExternalDest) {
+      const chain = {
+        type: CHAIN_TYPES.EXFILTRATION,
+        detectedAt: ts,
+        reason: `Exfiltration sequence detected: Agent read sensitive resources earlier in session and is now egressing to '${resource}'`,
+      };
+      this.detectedChains.push(chain);
+      return {
+        suspicious: true,
+        chainDetected: CHAIN_TYPES.EXFILTRATION,
+        reason: chain.reason,
+        risk: this.cumulativeRisk,
+      };
+    }
+
+    // Check for reconnaissance chain:
+    // Rapid multiple reads of environment/user tables followed by command execution
+    if (this.history.length >= 3) {
+      const last3 = this.history.slice(-3);
+      const isReconSequence =
+        last3[0].action.includes("read") &&
+        last3[1].action.includes("read") &&
+        last3[2].action.includes("exec");
+
+      if (isReconSequence && (this.taint.readSecrets || this.taint.readSensitiveData)) {
+        const chain = {
+          type: CHAIN_TYPES.RECONNAISSANCE,
+          detectedAt: ts,
+          reason: "Reconnaissance sequence: Probing sensitive files followed by shell command execution",
+        };
+        this.detectedChains.push(chain);
+        return {
+          suspicious: true,
+          chainDetected: CHAIN_TYPES.RECONNAISSANCE,
+          reason: chain.reason,
+          risk: this.cumulativeRisk,
+        };
+      }
+    }
+
+    return {
+      suspicious: false,
+      risk: this.cumulativeRisk,
+    };
+  }
+
+  quarantine(reason) {
+    this.status = "quarantined";
+    this.quarantineReason = reason;
+  }
+
+  terminate(reason) {
+    this.status = "terminated";
+    this.quarantineReason = reason;
+  }
+}

package/src/core/shadow.mjs

@@ -0,0 +1,95 @@
+/**
+ * Shadow Mode Evaluator.
+ *
+ * Non-blocking policy evaluation allowing real agent actions to proceed
+ * while recording counterfactual decisions ("Would Allow", "Would Block",
+ * "Would Require Approval", "Would Quarantine") for safe policy rollout.
+ */
+
+import { DECISION } from "./decisions.mjs";
+
+export class ShadowEngine {
+  constructor({ logSink = () => {} } = {}) {
+    this.logSink = logSink;
+    this.metrics = {
+      total: 0,
+      wouldAllow: 0,
+      wouldBlock: 0,
+      wouldRequireApproval: 0,
+      wouldQuarantine: 0,
+      policiesTriggered: new Map(),
+    };
+    this.shadowLog = [];
+  }
+
+  /**
+   * Evaluates what Cirvix WOULD have decided without blocking execution.
+   *
+   * @param {Object} callParams - Request details
+   * @param {Function} policyEvaluator - Underlying evaluator function returning decision
+   * @returns {Object} Hypothetical decision record
+   */
+  evaluateShadow(callParams, policyEvaluator) {
+    const ts = new Date().toISOString();
+    let hypotheticalDecision = DECISION.ALLOW;
+    let ruleMatched = null;
+    let riskLevel = "LOW";
+    let reason = "Hypothetical shadow evaluation";
+
+    try {
+      const evaluation = policyEvaluator(callParams);
+      hypotheticalDecision = evaluation.verdict ?? evaluation.decision ?? DECISION.ALLOW;
+      ruleMatched = evaluation.rule ?? null;
+      riskLevel = evaluation.risk ?? "LOW";
+      reason = evaluation.reason ?? reason;
+    } catch (err) {
+      hypotheticalDecision = DECISION.DENY;
+      reason = `Shadow evaluation error: ${err.message}`;
+    }
+
+    this.metrics.total += 1;
+    if (hypotheticalDecision === DECISION.ALLOW) {
+      this.metrics.wouldAllow += 1;
+    } else if (hypotheticalDecision === DECISION.DENY) {
+      this.metrics.wouldBlock += 1;
+    } else if (hypotheticalDecision === DECISION.REQUIRE_APPROVAL) {
+      this.metrics.wouldRequireApproval += 1;
+    } else if (hypotheticalDecision === DECISION.QUARANTINE) {
+      this.metrics.wouldQuarantine += 1;
+    }
+
+    if (ruleMatched) {
+      const count = this.metrics.policiesTriggered.get(ruleMatched) ?? 0;
+      this.metrics.policiesTriggered.set(ruleMatched, count + 1);
+    }
+
+    const record = {
+      ts,
+      call: callParams,
+      hypotheticalDecision,
+      ruleMatched,
+      riskLevel,
+      reason,
+    };
+
+    this.shadowLog.push(record);
+    if (this.shadowLog.length > 500) {
+      this.shadowLog.shift();
+    }
+
+    this.logSink(record);
+    return record;
+  }
+
+  getSummary() {
+    return {
+      totalEvaluated: this.metrics.total,
+      wouldAllow: this.metrics.wouldAllow,
+      wouldBlock: this.metrics.wouldBlock,
+      wouldRequireApproval: this.metrics.wouldRequireApproval,
+      wouldQuarantine: this.metrics.wouldQuarantine,
+      triggeredPolicies: Object.fromEntries(this.metrics.policiesTriggered),
+      logSnippet: this.shadowLog.slice(-10),
+    };
+  }
+}