@ory/mastra 0.10.0

package/README.md

@@ -0,0 +1,42 @@
+# @ory/mastra
+
+Ory Agent Security for [Mastra](https://mastra.ai).
+
+Authorizes every tool call against Ory Permissions, traces invocations, and propagates
+user → agent → sub-agent identity — built on [`@ory/argus`](../core).
+
+```bash
+npm install @ory/mastra
+```
+
+Recommended — agent tool-call hooks (gates every tool, including agent-/workflow-as-tools):
+
+```ts
+import { Agent } from "@mastra/core/agent";
+import { oryAgentHooks } from "@ory/mastra";
+
+const agent = new Agent({
+  name: "assistant",
+  instructions: "…",
+  model,
+  tools: { search, sendEmail },
+  hooks: oryAgentHooks(),
+});
+```
+
+`beforeToolCall` authorizes each call; in **enforce** mode (`ORY_PERMISSION_MODE=enforce`) a
+denied tool is skipped via `{ proceed: false, output }` and the model receives the denial. In
+**observe** mode (default) the tool runs and a `permission.observe_deny` span is recorded.
+`afterToolCall` records `tool.complete`.
+
+Alternatively, wrap tool `execute` directly (deny → throw):
+
+```ts
+import { withOry } from "@ory/mastra";
+const tools = withOry({ search, sendEmail });
+```
+
+This package depends only on `@ory/argus` — not `@mastra/core`; tools and hook contexts are
+duck-typed so any Mastra v1 version works. Credentials come from the shared
+`~/.config/ory-agent-plugins/config.json`. See
+[docs/sdk-integrations.md](../../docs/sdk-integrations.md).

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Ory Agent Security for Mastra.
+ *
+ * Two interchangeable wiring points, both on the shared `@ory/argus` adapters:
+ *
+ *   - {@link oryAgentHooks} (recommended) — agent tool-call hooks for `new Agent({ hooks })`.
+ *     `beforeToolCall` authorizes every tool (incl. agent-/workflow-as-tools); a deny returns
+ *     `{ proceed: false, output }` so Mastra skips the tool. `afterToolCall` traces completion.
+ *   - {@link withOry} — wraps each tool's `execute` directly (deny → throw), for callers who
+ *     prefer per-tool wrapping or are on a Mastra version without the hooks API.
+ *
+ * The package has no `@mastra/core` dependency — tools/hook contexts are duck-typed.
+ */
+import { OryAgentClient } from "@ory/argus";
+import type { OryMastraHooks, ToolSet } from "./types.js";
+export interface OryMastraOptions {
+    /** Client to use. Defaults to `OryAgentClient.fromEnv("mastra")` (reads the shared config). */
+    client?: OryAgentClient;
+    /** Override the Ory project URL for the session gates. */
+    projectUrl?: string;
+    /** Whether a denied tool is hard-blocked. Default true. */
+    canBlock?: boolean;
+}
+/**
+ * Build the `{ beforeToolCall, afterToolCall }` hooks object for `new Agent({ hooks })`.
+ */
+export declare function oryAgentHooks(options?: OryMastraOptions): OryMastraHooks;
+/**
+ * Wrap each tool's `execute` with the Ory gate. On a hard deny it throws (Mastra surfaces
+ * the error to the model); otherwise the tool runs and `tool.complete` is recorded. Tools
+ * without an `execute` are passed through untouched.
+ */
+export declare function withOry(tools: ToolSet, options?: OryMastraOptions): ToolSet;
+export { OryAgentClient, OryDenialError } from "@ory/argus";
+export type { OryMastraHooks, ToolSet, MastraTool, ToolHookBeforeContext, ToolHookAfterContext } from "./types.js";

package/dist/index.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * Ory Agent Security for Mastra.
+ *
+ * Two interchangeable wiring points, both on the shared `@ory/argus` adapters:
+ *
+ *   - {@link oryAgentHooks} (recommended) — agent tool-call hooks for `new Agent({ hooks })`.
+ *     `beforeToolCall` authorizes every tool (incl. agent-/workflow-as-tools); a deny returns
+ *     `{ proceed: false, output }` so Mastra skips the tool. `afterToolCall` traces completion.
+ *   - {@link withOry} — wraps each tool's `execute` directly (deny → throw), for callers who
+ *     prefer per-tool wrapping or are on a Mastra version without the hooks API.
+ *
+ * The package has no `@mastra/core` dependency — tools/hook contexts are duck-typed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OryDenialError = exports.OryAgentClient = void 0;
+exports.oryAgentHooks = oryAgentHooks;
+exports.withOry = withOry;
+const argus_1 = require("@ory/argus");
+const HARNESS = "mastra";
+function lazySession(client, projectUrl) {
+    let started = false;
+    return async () => {
+        if (started)
+            return;
+        started = true;
+        try {
+            await (0, argus_1.sessionStart)(client, { harness: HARNESS, projectUrl });
+        }
+        catch (err) {
+            client.logger.warn("session_start.failed", {
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    };
+}
+/**
+ * Build the `{ beforeToolCall, afterToolCall }` hooks object for `new Agent({ hooks })`.
+ */
+function oryAgentHooks(options = {}) {
+    const client = options.client ?? argus_1.OryAgentClient.fromEnv(HARNESS);
+    const canBlock = options.canBlock ?? true;
+    const ensureSession = lazySession(client, options.projectUrl);
+    return {
+        beforeToolCall: async (ctx) => {
+            await ensureSession();
+            const toolName = ctx.toolName;
+            // Sub-agent delegation: agent-/workflow-as-tools surface as `agent-*` / `workflow-*`.
+            if (toolName.startsWith("agent-") || toolName.startsWith("workflow-")) {
+                await (0, argus_1.registerSubagent)(client, {
+                    harness: HARNESS,
+                    subAgentType: toolName,
+                    projectUrl: options.projectUrl,
+                }).catch(() => undefined);
+            }
+            const result = await (0, argus_1.gate)(client, {
+                harness: HARNESS,
+                toolName,
+                toolArgs: ctx.input,
+                canBlock,
+            });
+            if (result.kind === "deny" && result.blocked) {
+                return { proceed: false, output: result.denialMessage ?? "Ory: permission denied" };
+            }
+            return undefined; // allow / observe / fail-open / interactive → proceed
+        },
+        afterToolCall: async (ctx) => {
+            (0, argus_1.complete)(client, { toolName: ctx.toolName, output: ctx.output });
+        },
+    };
+}
+/**
+ * Wrap each tool's `execute` with the Ory gate. On a hard deny it throws (Mastra surfaces
+ * the error to the model); otherwise the tool runs and `tool.complete` is recorded. Tools
+ * without an `execute` are passed through untouched.
+ */
+function withOry(tools, options = {}) {
+    const client = options.client ?? argus_1.OryAgentClient.fromEnv(HARNESS);
+    const canBlock = options.canBlock ?? true;
+    const ensureSession = lazySession(client, options.projectUrl);
+    const wrapped = {};
+    for (const [key, tool] of Object.entries(tools)) {
+        if (!tool || typeof tool.execute !== "function") {
+            wrapped[key] = tool;
+            continue;
+        }
+        const toolName = tool.id ?? key;
+        const originalExecute = tool.execute.bind(tool);
+        wrapped[key] = {
+            ...tool,
+            execute: async (inputData, context) => {
+                await ensureSession();
+                const result = await (0, argus_1.gate)(client, {
+                    harness: HARNESS,
+                    toolName,
+                    toolArgs: inputData,
+                    canBlock,
+                });
+                if (result.blocked) {
+                    throw new argus_1.OryDenialError({
+                        tool: toolName,
+                        subjectId: result.subject,
+                        namespace: result.namespace,
+                    });
+                }
+                const output = await originalExecute(inputData, context);
+                (0, argus_1.complete)(client, { toolName, output });
+                return output;
+            },
+        };
+    }
+    return wrapped;
+}
+var argus_2 = require("@ory/argus");
+Object.defineProperty(exports, "OryAgentClient", { enumerable: true, get: function () { return argus_2.OryAgentClient; } });
+Object.defineProperty(exports, "OryDenialError", { enumerable: true, get: function () { return argus_2.OryDenialError; } });

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal Mastra shapes. Defined here (not imported from `@mastra/core`) so the package has
+ * no SDK dependency — same policy as the other integrations. These mirror Mastra v1's
+ * agent tool-call hooks and tool `execute` contract closely enough to wire the gate.
+ */
+/** Context passed to `beforeToolCall`. */
+export interface ToolHookBeforeContext {
+    toolName: string;
+    input?: unknown;
+    context?: unknown;
+    metadata?: unknown;
+}
+/** Context passed to `afterToolCall`. */
+export interface ToolHookAfterContext extends ToolHookBeforeContext {
+    output?: unknown;
+    error?: unknown;
+}
+/** `beforeToolCall` returns this to skip the tool; the `output` becomes the tool result. */
+export interface ToolBeforeHookResult {
+    proceed: false;
+    output: unknown;
+}
+/** The object passed to `new Agent({ hooks })`. */
+export interface OryMastraHooks {
+    beforeToolCall: (ctx: ToolHookBeforeContext) => Promise<void | ToolBeforeHookResult> | void | ToolBeforeHookResult;
+    afterToolCall: (ctx: ToolHookAfterContext) => Promise<void> | void;
+}
+/** A Mastra tool — duck-typed. `execute` takes `(inputData, context)` in v1. */
+export interface MastraTool {
+    id?: string;
+    execute?: (inputData: unknown, context?: unknown) => unknown;
+    [key: string]: unknown;
+}
+export type ToolSet = Record<string, MastraTool>;

package/dist/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Minimal Mastra shapes. Defined here (not imported from `@mastra/core`) so the package has
+ * no SDK dependency — same policy as the other integrations. These mirror Mastra v1's
+ * agent tool-call hooks and tool `execute` contract closely enough to wire the gate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ory/mastra",
+  "version": "0.10.0",
+  "description": "Ory Agent Security for Mastra — per-tool authorization, tracing, and identity propagation via agent tool-call hooks (or wrapping tool execute). Built on @ory/argus.",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "keywords": [
+    "ory",
+    "mastra",
+    "authorization",
+    "agent",
+    "ai",
+    "permissions"
+  ],
+  "dependencies": {
+    "@ory/argus": "0.10.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "vitest": "4.1.4"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}