Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

22.9 KB
Raw Blame
import { describe, expect, it, vi } from "vitest";
import { TradeGuard } from "../src/core/TradeGuard.js";
import {
  GUARD_LAYER_ORDER,
  GuardChain,
  analyzeGuardCoverage,
  guardLayerLabel,
  guardLayerWeight
} from "../src/core/GuardChain.js";
import { SpendGuard } from "../src/core/SpendGuard.js";
import { createX402Hook } from "../src/core/X402Hook.js";
const FIXED_NOW = 17e11;
function tickingClock() {
  let t = 0;
  return () => t += 1;
}
function makeChain(options = {}) {
  return new GuardChain({ clock: tickingClock(), now: () => FIXED_NOW, ...options });
}
function req(overrides = {}) {
  return {
    apiName: "executeSwap",
    arguments: { chainId: 1, fromToken: "ETH", toToken: "USDC" },
    identifier: "solana_swap",
    ...overrides
  };
}
function layer(verdict, id) {
  return verdict.layers.find((l) => l.layer === id);
}
describe("GuardChain", () => {
  describe("trace", () => {
    it("emits one result per layer, in declared order", async () => {
      const verdict = await makeChain().evaluate(req());
      expect(verdict.layers.map((l) => l.layer)).toEqual(GUARD_LAYER_ORDER);
    });
    it("runs every layer to completion rather than short-circuiting on a block", async () => {
      const chain = makeChain({
        checkCapability: async () => ({ allowed: false, reason: "no token" }),
        defiGuard: new TradeGuard(),
        spendGuard: new SpendGuard({ perTxMaxUsd: 10 })
      });
      const verdict = await chain.evaluate(req({ valueUsd: 5e3 }));
      expect(layer(verdict, "capability").status).toBe("block");
      expect(layer(verdict, "spend_guard").status).toBe("block");
      expect(layer(verdict, "spend_guard").code).toBe("CAP_PER_TX");
    });
    it("labels every layer with a renderable name", async () => {
      const verdict = await makeChain().evaluate(req());
      for (const result of verdict.layers) {
        expect(result.label).toBe(guardLayerLabel(result.layer));
        expect(result.label.length).toBeGreaterThan(0);
        expect(result.reason.length).toBeGreaterThan(0);
      }
    });
    it("stamps evaluatedAt from the injected clock", async () => {
      const verdict = await makeChain().evaluate(req());
      expect(verdict.evaluatedAt).toBe(FIXED_NOW);
    });
  });
  describe("verdict", () => {
    it("allows a call that clears every applicable layer", async () => {
      const chain = makeChain({
        checkCapability: async () => ({ allowed: true }),
        checkPermission: async () => ({ allowed: true, level: "autonomous" }),
        defiGuard: new TradeGuard(),
        spendGuard: new SpendGuard({ perTxMaxUsd: 1e5 })
      });
      const verdict = await chain.evaluate(req({ valueUsd: 500 }));
      expect(verdict.decision).toBe("allow");
      expect(verdict.blockedBy).toBeUndefined();
    });
    it("escalates to block when any layer blocks, naming the layer", async () => {
      const chain = makeChain({ spendGuard: new SpendGuard({ perTxMaxUsd: 100 }) });
      const verdict = await chain.evaluate(req({ valueUsd: 5e3 }));
      expect(verdict.decision).toBe("block");
      expect(verdict.blockedBy).toBe("spend_guard");
      expect(verdict.code).toBe("CAP_PER_TX");
      expect(verdict.reason).toContain("Spend Envelope");
    });
    it("prefers a block over a concurrent approval_required", async () => {
      const chain = makeChain({
        checkPermission: async () => ({ allowed: false, level: "approval-required" }),
        spendGuard: new SpendGuard({ perTxMaxUsd: 100 })
      });
      const verdict = await chain.evaluate(req({ valueUsd: 5e3 }));
      expect(verdict.decision).toBe("block");
      expect(verdict.blockedBy).toBe("spend_guard");
    });
    it("reports require_approval when the strongest outcome is an approval gate", async () => {
      const chain = makeChain({
        checkPermission: async () => ({ allowed: false, level: "approval-required" })
      });
      const verdict = await chain.evaluate(req({ valueUsd: 100 }));
      expect(verdict.decision).toBe("require_approval");
      expect(verdict.blockedBy).toBeUndefined();
    });
    it("breaks ties toward the earlier layer, matching runtime firing order", async () => {
      const chain = makeChain({
        checkCapability: async () => ({ allowed: false, reason: "capability first" }),
        checkPermission: async () => ({ allowed: false, level: "forbidden" })
      });
      const verdict = await chain.evaluate(req());
      expect(verdict.blockedBy).toBe("capability");
    });
  });
  describe("intervention layers", () => {
    it("blocks on the runtime default blacklist when none is supplied", async () => {
      const verdict = await makeChain().evaluate(
        req({ apiName: "bash", arguments: { command: "rm -rf /" }, identifier: "bash" })
      );
      expect(layer(verdict, "security_blacklist").status).toBe("block");
      expect(layer(verdict, "security_blacklist").code).toBe("SECURITY_BLACKLIST");
      expect(verdict.decision).toBe("block");
    });
    it("honours an explicitly supplied blacklist", async () => {
      const verdict = await makeChain().evaluate(
        req({
          apiName: "transferAll",
          arguments: { destination: "0xdeadbeef" },
          identifier: "agent-wallet",
          securityBlacklist: [
            { description: "Known drainer address", match: { destination: "0xdead*" } }
          ]
        })
      );
      expect(layer(verdict, "security_blacklist").status).toBe("block");
      expect(layer(verdict, "security_blacklist").reason).toContain("drainer");
    });
    it("notes that headless mode skips blacklisted tools instead of surfacing them", async () => {
      const verdict = await makeChain().evaluate(
        req({
          apiName: "bash",
          approvalMode: "headless",
          arguments: { command: "rm -rf /" },
          identifier: "bash"
        })
      );
      expect(layer(verdict, "security_blacklist").reason).toContain("headless");
    });
    it("lets auto-run downgrade a `required` policy", async () => {
      const manual = await makeChain().evaluate(req({ interventionConfig: "required" }));
      const auto = await makeChain().evaluate(
        req({ approvalMode: "auto-run", interventionConfig: "required" })
      );
      expect(layer(manual, "intervention").status).toBe("approval_required");
      expect(layer(auto, "intervention").status).toBe("pass");
    });
    it("never lets an approval mode downgrade an `always` policy", async () => {
      for (const mode of ["auto-run", "headless", "allow-list"]) {
        const verdict = await makeChain().evaluate(
          req({ approvalMode: mode, interventionConfig: "always" })
        );
        expect(layer(verdict, "intervention").status).toBe("approval_required");
      }
    });
    it("honours the session allow list under allow-list mode", async () => {
      const listed = await makeChain().evaluate(
        req({
          allowList: ["solana_swap/executeSwap"],
          approvalMode: "allow-list",
          interventionConfig: "required"
        })
      );
      const absent = await makeChain().evaluate(
        req({ allowList: [], approvalMode: "allow-list", interventionConfig: "required" })
      );
      expect(layer(listed, "intervention").status).toBe("pass");
      expect(layer(absent, "intervention").status).toBe("approval_required");
    });
  });
  describe("capability and permission guards", () => {
    it("marks both as skipped for batched dispatch", async () => {
      const chain = makeChain({
        checkCapability: async () => ({ allowed: true }),
        checkPermission: async () => ({ allowed: true })
      });
      const verdict = await chain.evaluate(req({ executionPath: "batch" }));
      expect(layer(verdict, "capability").status).toBe("skipped");
      expect(layer(verdict, "capability").code).toBe("BATCH_BYPASS");
      expect(layer(verdict, "permission").status).toBe("skipped");
    });
    it("does not invoke the injected checkers when batching", async () => {
      const checkCapability = vi.fn().mockResolvedValue({ allowed: true });
      const chain = makeChain({ checkCapability });
      await chain.evaluate(req({ executionPath: "batch" }));
      expect(checkCapability).not.toHaveBeenCalled();
    });
    it("treats notify-and-proceed as a passing warning", async () => {
      const chain = makeChain({
        checkPermission: async () => ({ allowed: true, level: "notify-and-proceed" })
      });
      const verdict = await chain.evaluate(req());
      expect(layer(verdict, "permission").status).toBe("warn");
      expect(verdict.decision).toBe("allow");
      expect(verdict.warnings.some((w) => w.includes("Agent Permission"))).toBe(true);
    });
    it("fails closed when a checker throws", async () => {
      const chain = makeChain({
        checkPermission: async () => {
          throw new Error("permissions service unreachable");
        }
      });
      const verdict = await chain.evaluate(req());
      expect(layer(verdict, "permission").status).toBe("error");
      expect(verdict.decision).toBe("block");
      expect(verdict.reason).toContain("permissions service unreachable");
    });
  });
  describe("defi guard layer", () => {
    it("skips unregistered identifiers and says so explicitly", async () => {
      const chain = makeChain({ defiGuard: new TradeGuard() });
      const verdict = await chain.evaluate(
        req({ identifier: "some-new-tool", valueUsd: 1e3 })
      );
      expect(layer(verdict, "defi_guard").status).toBe("skipped");
      expect(layer(verdict, "defi_guard").code).toBe("NOT_REGISTERED");
    });
    it("requires approval above the auto-execute ceiling", async () => {
      const chain = makeChain({ defiGuard: new TradeGuard() });
      const verdict = await chain.evaluate(req({ userTier: "pro", valueUsd: 5e4 }));
      expect(layer(verdict, "defi_guard").status).toBe("approval_required");
      expect(verdict.decision).toBe("require_approval");
    });
    it("blocks above the tier transaction ceiling", async () => {
      const chain = makeChain({ defiGuard: new TradeGuard() });
      const verdict = await chain.evaluate(req({ userTier: "free", valueUsd: 25e3 }));
      expect(layer(verdict, "defi_guard").status).toBe("block");
      expect(verdict.blockedBy).toBe("defi_guard");
    });
    it("surfaces guard warnings and MEV parameter adjustments on the verdict", async () => {
      const chain = makeChain({ defiGuard: new TradeGuard() });
      const verdict = await chain.evaluate(
        req({ arguments: { chainId: 1, slippage: 3 }, userTier: "pro", valueUsd: 5e4 })
      );
      expect(verdict.warnings.some((w) => w.includes("Slippage reduced"))).toBe(true);
      expect(verdict.modifiedArguments).toMatchObject({ slippage: 1 });
    });
    it("flags an unregistered protocol as unverifiable", async () => {
      const chain = makeChain({ defiGuard: new TradeGuard() });
      const verdict = await chain.evaluate(
        req({ protocol: "uniswap", userTier: "pro", valueUsd: 5e3 })
      );
      expect(verdict.blindSpots.some((s) => s.code === "PROTOCOL_UNVERIFIED")).toBe(true);
    });
  });
  describe("spend envelope layer", () => {
    it("exempts inflow operations from spend caps", async () => {
      const chain = makeChain({ spendGuard: new SpendGuard({ perTxMaxUsd: 1 }) });
      const verdict = await chain.evaluate(
        req({ apiName: "withdraw", identifier: "lending-tool", valueUsd: 5e5 })
      );
      expect(layer(verdict, "spend_guard").status).toBe("skipped");
      expect(layer(verdict, "spend_guard").reason).toContain("exempt");
    });
    it("gates approvals so the firewall can vet the grantee", async () => {
      const chain = makeChain({
        spendGuard: new SpendGuard({
          firewall: { denyDestinations: ["0xbad"] }
        })
      });
      const verdict = await chain.evaluate(
        req({
          apiName: "approve",
          destination: "0xBAD",
          identifier: "token-approvals",
          valueUsd: 0
        })
      );
      expect(layer(verdict, "spend_guard").status).toBe("block");
      expect(layer(verdict, "spend_guard").code).toBe("FIREWALL_DENY_DEST");
    });
    it("skips read-only APIs with a distinct reason", async () => {
      const chain = makeChain({ spendGuard: new SpendGuard({ perTxMaxUsd: 1 }) });
      const verdict = await chain.evaluate(
        req({ apiName: "getQuote", identifier: "solana_swap" })
      );
      expect(layer(verdict, "spend_guard").reason).toContain("Read-only");
    });
  });
  describe("x402 layer", () => {
    const requirements = {
      accepts: [
        {
          asset: "0x1111111111111111111111111111111111111111",
          description: "API access",
          maxAmountRequired: "2000000",
          network: "eip155:8453",
          payTo: "0xfeed",
          resource: "https://api.example.com/data",
          scheme: "exact"
        }
      ],
      x402Version: 1
    };
    it("is skipped when the call is not x402-metered", async () => {
      const chain = makeChain({ x402Hook: createX402Hook() });
      const verdict = await chain.evaluate(req());
      expect(layer(verdict, "x402").status).toBe("skipped");
    });
    it("passes a payment inside the hourly budget", async () => {
      const chain = makeChain({ x402Hook: createX402Hook(5) });
      const verdict = await chain.evaluate(
        req({
          x402: {
            amountSpentThisHourUsdc: 0,
            currentBalanceUsdc: 100,
            requirements,
            url: "https://api.example.com/data"
          }
        })
      );
      expect(layer(verdict, "x402").status).toBe("pass");
    });
    it("queues a payment that would exceed the hourly budget", async () => {
      const chain = makeChain({ x402Hook: createX402Hook(5) });
      const verdict = await chain.evaluate(
        req({
          x402: {
            amountSpentThisHourUsdc: 4.5,
            currentBalanceUsdc: 100,
            requirements,
            url: "https://api.example.com/data"
          }
        })
      );
      expect(layer(verdict, "x402").status).toBe("approval_required");
      expect(verdict.decision).toBe("require_approval");
    });
    it("blocks a payment the wallet cannot cover", async () => {
      const chain = makeChain({ x402Hook: createX402Hook(5) });
      const verdict = await chain.evaluate(
        req({
          x402: {
            amountSpentThisHourUsdc: 0,
            currentBalanceUsdc: 0.5,
            requirements,
            url: "https://api.example.com/data"
          }
        })
      );
      expect(layer(verdict, "x402").status).toBe("block");
    });
  });
  describe("blind spots", () => {
    it("flags a registered mutating call with no resolved USD value", async () => {
      const chain = makeChain({ defiGuard: new TradeGuard() });
      const verdict = await chain.evaluate(req({ arguments: { amount: "0.5" } }));
      const spot = verdict.blindSpots.find((s) => s.code === "VALUE_UNRESOLVED");
      expect(spot).toBeDefined();
      expect(spot.severity).toBe("critical");
    });
    it("does not flag VALUE_UNRESOLVED once a value is supplied", async () => {
      const chain = makeChain({ defiGuard: new TradeGuard() });
      const verdict = await chain.evaluate(req({ valueUsd: 1200 }));
      expect(verdict.blindSpots.some((s) => s.code === "VALUE_UNRESOLVED")).toBe(false);
    });
    it("flags a fund-moving tool absent from the DeFi registry", async () => {
      const chain = makeChain({ defiGuard: new TradeGuard() });
      const verdict = await chain.evaluate(
        req({ apiName: "executeSwap", identifier: "community-dex-tool", valueUsd: 9e3 })
      );
      const spot = verdict.blindSpots.find((s) => s.code === "TOOL_UNREGISTERED");
      expect(spot).toBeDefined();
      expect(spot.remediation).toContain("community-dex-tool");
    });
    it("flags batched dispatch as bypassing the decorator guards", async () => {
      const verdict = await makeChain().evaluate(req({ executionPath: "batch" }));
      expect(verdict.blindSpots.some((s) => s.code === "BATCH_BYPASS")).toBe(true);
    });
    it("flags an outflow with no spend envelope attached", async () => {
      const verdict = await makeChain().evaluate(req({ valueUsd: 4e3 }));
      const spot = verdict.blindSpots.find((s) => s.code === "SPEND_UNSCOPED");
      expect(spot).toBeDefined();
      expect(spot.severity).toBe("critical");
    });
    it("does not flag SPEND_UNSCOPED when an envelope is configured", async () => {
      const chain = makeChain({ spendGuard: new SpendGuard({ perTxMaxUsd: 1e5 }) });
      const verdict = await chain.evaluate(req({ valueUsd: 4e3 }));
      expect(verdict.blindSpots.some((s) => s.code === "SPEND_UNSCOPED")).toBe(false);
    });
    it("flags unwired capability and permission checkers", async () => {
      const verdict = await makeChain().evaluate(req());
      expect(verdict.blindSpots.some((s) => s.code === "CAPABILITY_UNWIRED")).toBe(true);
      expect(verdict.blindSpots.some((s) => s.code === "PERMISSION_UNWIRED")).toBe(true);
    });
    it("reports read-only DeFi calls as unanalyzed at info severity", async () => {
      const chain = makeChain({ defiGuard: new TradeGuard() });
      const verdict = await chain.evaluate(req({ apiName: "getQuote" }));
      const spot = verdict.blindSpots.find((s) => s.code === "READONLY_UNANALYZED");
      expect(spot).toBeDefined();
      expect(spot.severity).toBe("info");
    });
    it("orders findings critical-first", async () => {
      const chain = makeChain({ defiGuard: new TradeGuard() });
      const verdict = await chain.evaluate(req({ executionPath: "batch" }));
      const rank = { critical: 0, info: 2, warning: 1 };
      const seq = verdict.blindSpots.map((s) => rank[s.severity]);
      expect(seq).toEqual([...seq].sort((a, b) => a - b));
    });
    it("reports no critical findings for a fully-wired evaluation", async () => {
      const chain = makeChain({
        checkCapability: async () => ({ allowed: true }),
        checkPermission: async () => ({ allowed: true, level: "autonomous" }),
        defiGuard: new TradeGuard(),
        spendGuard: new SpendGuard({ perTxMaxUsd: 1e5 })
      });
      const verdict = await chain.evaluate(req({ valueUsd: 2500 }));
      expect(verdict.blindSpots.filter((s) => s.severity === "critical")).toEqual([]);
    });
  });
  describe("coverage score", () => {
    it("reports 100 when every applicable layer evaluated the call", async () => {
      const chain = makeChain({
        checkCapability: async () => ({ allowed: true }),
        checkPermission: async () => ({ allowed: true, level: "autonomous" }),
        defiGuard: new TradeGuard(),
        spendGuard: new SpendGuard({ perTxMaxUsd: 1e5 })
      });
      const verdict = await chain.evaluate(req({ valueUsd: 2500 }));
      expect(verdict.coverageScore).toBe(100);
    });
    it("drops when guards are missing, even though the verdict is allow", async () => {
      const verdict = await makeChain().evaluate(req({ valueUsd: 2500 }));
      expect(verdict.decision).toBe("allow");
      expect(verdict.coverageScore).toBeLessThan(50);
    });
    it("does not penalise a read-only call for skipping the spend envelope", async () => {
      const readOnly = makeChain({
        checkCapability: async () => ({ allowed: true }),
        checkPermission: async () => ({ allowed: true }),
        defiGuard: new TradeGuard()
      });
      const verdict = await readOnly.evaluate(req({ apiName: "getQuote" }));
      expect(verdict.coverageScore).toBe(100);
      expect(verdict.blindSpots.some((s) => s.code === "READONLY_UNANALYZED")).toBe(true);
    });
    it('separates "the layer ran" from "the layer checked something"', async () => {
      const chain = makeChain({
        checkCapability: async () => ({ allowed: true }),
        checkPermission: async () => ({ allowed: true, level: "autonomous" }),
        defiGuard: new TradeGuard(),
        spendGuard: new SpendGuard({ perTxMaxUsd: 1e5 })
      });
      const verdict = await chain.evaluate(req({ arguments: { amount: "0.5" } }));
      expect(verdict.coverageScore).toBe(100);
      expect(verdict.decision).toBe("allow");
      expect(verdict.blindSpots.some((s) => s.code === "VALUE_UNRESOLVED")).toBe(true);
    });
    it("falls when batching removes the decorator guards from the surface", async () => {
      const options = {
        checkCapability: async () => ({ allowed: true }),
        checkPermission: async () => ({ allowed: true, level: "autonomous" }),
        defiGuard: new TradeGuard(),
        spendGuard: new SpendGuard({ perTxMaxUsd: 1e5 })
      };
      const single = await makeChain(options).evaluate(req({ valueUsd: 2500 }));
      const batched = await makeChain(options).evaluate(
        req({ executionPath: "batch", valueUsd: 2500 })
      );
      expect(batched.coverageScore).toBeLessThan(single.coverageScore);
    });
  });
  describe("determinism", () => {
    it("returns an identical verdict for identical input", async () => {
      const build = () => makeChain({
        defiGuard: new TradeGuard(),
        spendGuard: new SpendGuard({ perTxMaxUsd: 1e5 })
      });
      const a = await build().evaluate(req({ userTier: "pro", valueUsd: 42e3 }));
      const b = await build().evaluate(req({ userTier: "pro", valueUsd: 42e3 }));
      const strip = (v) => ({
        ...v,
        layers: v.layers.map(({ elapsedMs: _e, detail: _d, ...rest }) => rest),
        totalElapsedMs: 0
      });
      expect(strip(a)).toEqual(strip(b));
    });
  });
});
describe("analyzeGuardCoverage", () => {
  it("reports the registry itself as fully covered when given no argument", () => {
    const report = analyzeGuardCoverage();
    expect(report.coveragePercent).toBe(100);
    expect(report.unregistered).toEqual([]);
    expect(report.registered.length).toBeGreaterThan(0);
  });
  it("separates registered from unregistered identifiers", () => {
    const report = analyzeGuardCoverage(["solana_swap", "unknown-tool"]);
    expect(report.registered.map((e) => e.identifier)).toEqual(["solana_swap"]);
    expect(report.unregistered.map((e) => e.identifier)).toEqual(["unknown-tool"]);
    expect(report.coveragePercent).toBe(50);
  });
  it("deduplicates the supplied identifiers", () => {
    const report = analyzeGuardCoverage(["solana_swap", "solana_swap"]);
    expect(report.registered).toHaveLength(1);
    expect(report.coveragePercent).toBe(100);
  });
  it("lists the mutating API registry", () => {
    const report = analyzeGuardCoverage();
    expect(report.mutatingApis).toContain("executeSwap");
    expect(report.mutatingApis).toEqual([...report.mutatingApis].sort());
  });
  it("treats an empty deployment as fully covered rather than dividing by zero", () => {
    expect(analyzeGuardCoverage([]).coveragePercent).toBe(100);
  });
});
describe("layer metadata", () => {
  it("exposes a label and a positive weight for every layer", () => {
    for (const id of GUARD_LAYER_ORDER) {
      expect(guardLayerLabel(id)).toBeTruthy();
      expect(guardLayerWeight(id)).toBeGreaterThan(0);
    }
  });
  it("weights sum to 100 so the coverage score reads as a percentage", () => {
    const total = GUARD_LAYER_ORDER.reduce((sum, id) => sum + guardLayerWeight(id), 0);
    expect(total).toBe(100);
  });
});