@veritera.ai/forge-mastra

Forge Verify middleware and tools for Mastra -- verify every agent action before execution.

Install

npm install @veritera.ai/forge-mastra @veritera.ai/forge-verify

@mastra/core is a peer dependency and must be installed in your project.

Quick Start

ForgeIntegration

Shared verification client for use across agents, tools, and middleware.

import { ForgeIntegration } from "@veritera.ai/forge-mastra";

const forge = new ForgeIntegration({
  apiKey: "vt_live_...",
  policy: "production-safety",
});

const result = await forge.verify("payment.create", { amount: 500 });
if (!result.verified) {
  console.log("Blocked:", result.reason);
}

forgeVerifyTool

A Mastra Tool that agents can call to explicitly verify an action.

import { Agent } from "@mastra/core";
import { forgeVerifyTool } from "@veritera.ai/forge-mastra";

const agent = new Agent({
  tools: {
    forge_verify: forgeVerifyTool({
      apiKey: "vt_live_...",
      policy: "finance-controls",
    }),
  },
});

forgeMiddleware

Middleware that verifies every tool call before execution. If verification fails, the tool is never called.

import { Agent } from "@mastra/core";
import { forgeMiddleware } from "@veritera.ai/forge-mastra";

const middleware = forgeMiddleware({
  apiKey: "vt_live_...",
  policy: "production-safety",
  failClosed: true,
});

const agent = new Agent({
  middleware: [middleware],
});

forgeWrapTool

Wraps any individual Mastra tool with Forge verification.

import { forgeWrapTool } from "@veritera.ai/forge-mastra";

const protectedTool = forgeWrapTool(myPaymentTool, {
  apiKey: "vt_live_...",
  policy: "finance-controls",
});

const agent = new Agent({
  tools: { payment: protectedTool },
});

Configuration

All exports accept the same ForgeConfig options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | VERITERA_API_KEY env | Forge API key (vt_live_... or vt_test_...) | | baseUrl | string | https://forge.veritera.ai | Forge API base URL | | agentId | string | "mastra-agent" | Agent identifier for audit trail | | policy | string | -- | Policy name to evaluate against | | failClosed | boolean | true | Block actions when verification service errors | | timeout | number | 10000 | Request timeout in milliseconds | | skipActions | string[] | [] | Actions that bypass verification | | onVerified | function | -- | Callback when an action is verified | | onBlocked | function | -- | Callback when an action is blocked |

Error Handling

When an action is blocked, a ForgeBlockedError is thrown:

import { ForgeBlockedError } from "@veritera.ai/forge-mastra";

try {
  await agent.execute(task);
} catch (err) {
  if (err instanceof ForgeBlockedError) {
    console.log("Action:", err.action);
    console.log("Reason:", err.reason);
    console.log("Verification ID:", err.verificationId);
  }
}

Environment Variable

Set VERITERA_API_KEY to avoid passing apiKey in every config:

export VERITERA_API_KEY=vt_live_...

License

MIT