feat(core): support system actor direct FGA calls

Author: graysonhicks

.changeset/crisp-llamas-happen.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': minor
+---
+
+Added direct workflow, tool, and memory FGA support for trusted system actor invocations.

packages/core/src/memory/memory-config.test.ts

@@ -1,9 +1,34 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 
+import { MastraFGAPermissions } from '../auth/ee';
+import { RequestContext } from '../request-context';
 import { InMemoryStore } from '../storage';
 
 import { MockMemory } from './mock';
 
+describe('MastraMemory FGA', () => {
+  it('bypasses thread membership resolution for a tenant-scoped system actor', async () => {
+    const fgaProvider = {
+      require: vi.fn().mockResolvedValue(undefined),
+    };
+    const requestContext = new RequestContext();
+    requestContext.set('organizationId', 'org-1');
+
+    await MockMemory.checkThreadFGA({
+      mastra: {
+        getServer: () => ({ fga: fgaProvider }),
+      } as any,
+      threadId: 'thread-1',
+      resourceId: 'tenant-1',
+      requestContext,
+      permission: MastraFGAPermissions.MEMORY_READ,
+      systemActor: { actorKind: 'system', sourceWorkflow: 'nightly-workflow' },
+    });
+
+    expect(fgaProvider.require).not.toHaveBeenCalled();
+  });
+});
+
 describe('MastraMemory config serialization', () => {
   it('should serialize observational memory retrieval config for thread scope', () => {
     const memory = new MockMemory({

packages/core/src/memory/memory.ts

@@ -1,7 +1,7 @@
 import type { AssistantContent, UserContent, CoreMessage } from '@internal/ai-sdk-v4';
 import type { MastraDBMessage } from '../agent/message-list';
 import { MastraFGAPermissions } from '../auth/ee';
-import type { MastraFGAPermissionInput } from '../auth/ee';
+import type { MastraFGAPermissionInput, SystemActorSignal } from '../auth/ee';
 import { MastraBase } from '../base';
 import { ErrorDomain, MastraError } from '../error';
 import { ModelRouterEmbeddingModel } from '../llm/model';
@@ -591,11 +591,12 @@ https://mastra.ai/en/docs/memory/overview`,
    */
   static async checkThreadFGA(options: {
     mastra?: Mastra;
-    user: Record<string, unknown>;
+    user?: Record<string, unknown>;
     threadId: string;
     resourceId?: string;
     requestContext?: RequestContext;
     permission?: MastraFGAPermissionInput;
+    systemActor?: SystemActorSignal;
   }): Promise<void> {
     const {
       mastra,
@@ -604,6 +605,7 @@ https://mastra.ai/en/docs/memory/overview`,
       resourceId,
       requestContext,
       permission = MastraFGAPermissions.MEMORY_READ,
+      systemActor,
     } = options;
     const fgaProvider = mastra?.getServer()?.fga;
     if (!fgaProvider) return;
@@ -615,6 +617,7 @@ https://mastra.ai/en/docs/memory/overview`,
       resource: { type: 'thread', id: threadId },
       permission,
       requestContext,
+      systemActor,
       context:
         resourceId || requestContext
           ? {

packages/core/src/tools/tool-builder/builder.test.ts

@@ -146,6 +146,51 @@ describe('CoreToolBuilder FGA', () => {
     expect(fgaProvider.require).not.toHaveBeenCalled();
     expect(execute).not.toHaveBeenCalled();
   });
+
+  it('bypasses membership resolution for a tenant-scoped system actor', async () => {
+    const execute = vi.fn().mockResolvedValue({ result: 'ok' });
+    const testTool = createTool({
+      id: 'search',
+      description: 'Search',
+      inputSchema: z.object({ query: z.string() }),
+      execute,
+    });
+    const requestContext = new RequestContext();
+    requestContext.set('organizationId', 'org-1');
+    const fgaProvider = {
+      require: vi.fn().mockResolvedValue(undefined),
+    };
+
+    const builder = new CoreToolBuilder({
+      originalTool: testTool,
+      options: {
+        name: 'search',
+        logger: {
+          debug: vi.fn(),
+          warn: vi.fn(),
+          error: vi.fn(),
+          trackException: vi.fn(),
+        } as any,
+        requestContext,
+        mastra: {
+          getServer: () => ({ fga: fgaProvider }),
+        } as any,
+      },
+    });
+
+    const builtTool = builder.build();
+    await builtTool.execute!(
+      { query: 'docs' },
+      {
+        toolCallId: 'call-1',
+        messages: [],
+        systemActor: { actorKind: 'system', sourceWorkflow: 'nightly-workflow' },
+      },
+    );
+
+    expect(fgaProvider.require).not.toHaveBeenCalled();
+    expect(execute).toHaveBeenCalled();
+  });
 });
 
 describe('MCP Tool Tracing', () => {

packages/core/src/tools/tool-builder/builder.ts

@@ -743,6 +743,7 @@ export class CoreToolBuilder extends MastraBase {
           resource: { type: 'tool', id: toolResourceId },
           permission: MastraFGAPermissions.TOOLS_EXECUTE,
           requestContext: toolRequestContext,
+          systemActor: execOptions?.systemActor,
           context: {
             resourceId: options.resourceId,
           },

packages/core/src/tools/types.ts

@@ -12,6 +12,7 @@ import type { ElicitRequest, ElicitResult } from '@modelcontextprotocol/sdk/type
 
 import type { MastraPrimitives, MastraUnion } from '../action';
 export type { MastraPrimitives, MastraUnion };
+import type { SystemActorSignal } from '../auth/ee';
 import type { ToolBackgroundConfig } from '../background-tasks';
 import type { MastraBrowser } from '../browser/browser';
 import type { Mastra } from '../mastra';
@@ -240,6 +241,8 @@ export type MastraToolInvocationOptions = ToolInvocationOptions &
      * their requestContext (e.g., authenticated API clients, feature flags) to tools.
      */
     requestContext?: RequestContext;
+    /** Trusted server-side signal for this tool FGA check. */
+    systemActor?: SystemActorSignal;
     /**
      * Flushes the parent stream's pending messages to persistent storage.
      *

packages/core/src/workflows/workflow.test.ts

@@ -782,6 +782,42 @@ describe('Workflow (Default Engine Specifics)', () => {
       ).rejects.toThrow('authenticated user is required');
       expect(fgaProvider.require).not.toHaveBeenCalled();
     });
+
+    it('bypasses membership resolution for a tenant-scoped system actor', async () => {
+      const fgaProvider = {
+        require: vi.fn().mockResolvedValue(undefined),
+        check: vi.fn(),
+        filterAccessible: vi.fn(),
+      };
+      const workflow = createFGAWorkflow();
+      const mastra = new Mastra({
+        logger: false,
+        server: { fga: fgaProvider },
+      });
+      workflow.__registerMastra(mastra);
+
+      const requestContext = new RequestContext();
+      requestContext.set('organizationId', 'org-1');
+
+      const result = await (workflow as any).execute({
+        runId: 'run-3',
+        inputData: { value: 'ok' },
+        state: {},
+        setState: vi.fn(),
+        suspend: vi.fn(),
+        [PUBSUB_SYMBOL]: new EventEmitterPubSub(),
+        mastra,
+        requestContext,
+        systemActor: { actorKind: 'system', sourceWorkflow: 'nightly-workflow' },
+        abort: vi.fn(),
+        abortSignal: new AbortController().signal,
+        engine: 'default',
+        bail: vi.fn(),
+      });
+
+      expect(result).toEqual({ value: 'ok' });
+      expect(fgaProvider.require).not.toHaveBeenCalled();
+    });
   });
 
   describe('Nested workflow abort listener cleanup (issue #16125)', () => {

packages/core/src/workflows/workflow.ts

@@ -12,6 +12,7 @@ import type { SubAgent } from '../agent/subagent';
 import { TripWire } from '../agent/trip-wire';
 import type { AgentStreamOptions } from '../agent/types';
 import { MastraFGAPermissions } from '../auth/ee';
+import type { SystemActorSignal } from '../auth/ee';
 import { MastraBase } from '../base';
 import { RequestContext } from '../di';
 import { ErrorCategory, ErrorDomain, MastraError } from '../error';
@@ -2536,6 +2537,7 @@ export class Workflow<
     outputWriter,
     validateInputs,
     perStep,
+    systemActor,
     engine: _engine,
     bail: _bail,
     ...rest
@@ -2572,6 +2574,7 @@ export class Workflow<
     outputWriter?: OutputWriter;
     validateInputs?: boolean;
     perStep?: boolean;
+    systemActor?: SystemActorSignal;
   } & Partial<ObservabilityContext>): Promise<TOutput | undefined> {
     const observabilityContext = resolveObservabilityContext(rest);
     this.__registerMastra(mastra);
@@ -2587,6 +2590,7 @@ export class Workflow<
         resource: { type: 'workflow', id: getWorkflowFGAResourceId(this.id) },
         permission: MastraFGAPermissions.WORKFLOWS_EXECUTE,
         requestContext,
+        systemActor,
         context: {
           resourceId,
         },