@mastra/auth-workos 1.1.2 → 1.2.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @mastra/auth-workos
 
+## 1.2.0-alpha.0
+
+### Minor Changes
+
+- Added `MastraFGAWorkos` provider for Fine-Grained Authorization using the WorkOS Authorization API. Implements `IFGAManager` interface with support for: ([#15410](https://github.com/mastra-ai/mastra/pull/15410))
+  - Authorization checks (`check()`, `require()`, `filterAccessible()`)
+  - Resource management (`createResource()`, `getResource()`, `listResources()`, `updateResource()`, `deleteResource()`)
+  - Role assignments (`assignRole()`, `removeRole()`, `listRoleAssignments()`)
+  - `resourceMapping` and `permissionMapping` for translating Mastra resource types and permissions to WorkOS resource type slugs and permission slugs
+  - Organization scoping that denies access when the user is not a member of the configured organization
+  - Bearer-token / verified JWT support that carries service-token FGA context such as organization membership IDs, while ignoring JWT-derived memberships unless organization claims are trusted
+  - Membership caching and batched accessible-resource discovery for lower per-request latency
+  - Tenant inference and parent-resource filtering for scoped access checks
+  - Paginated organization membership lookup and limited concurrent FGA checks when filtering accessible resources
+  - Typed permission constants accepted in `permissionMapping`
+
+  ```typescript
+  import { MastraFGAWorkos } from '@mastra/auth-workos';
+
+  const fga = new MastraFGAWorkos({
+    organizationId: 'org_abc123',
+    resourceMapping: {
+      agent: { fgaResourceType: 'team', deriveId: ctx => ctx.user.teamId },
+    },
+    permissionMapping: {
+      'agents:execute': 'manage-workflows',
+    },
+  });
+
+  // Check whether a user can execute an agent
+  const allowed = await fga.check(user, {
+    resource: { type: 'agent', id: 'my-agent' },
+    permission: 'agents:execute',
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`86c0298`](https://github.com/mastra-ai/mastra/commit/86c0298e647306423c842f9d5ac827bd616bd13d), [`7fce309`](https://github.com/mastra-ai/mastra/commit/7fce30912b14170bfc41f0ac736cca0f39fe0cd4), [`7997c2e`](https://github.com/mastra-ai/mastra/commit/7997c2e55ddd121562a4098cd8d2b89c68433bf1), [`e97ccb9`](https://github.com/mastra-ai/mastra/commit/e97ccb900f8b7a390ce82c9f8eb8d6eb2c5e3777), [`c5daf48`](https://github.com/mastra-ai/mastra/commit/c5daf48556e98c46ae06caf00f92c249912007e9), [`cd96779`](https://github.com/mastra-ai/mastra/commit/cd9677937f113b2856dc8b9f3d4bdabcee58bb2e)]:
+  - @mastra/core@1.32.0-alpha.2
+  - @mastra/auth@1.0.2
+
 ## 1.1.2
 
 ### Patch Changes

package/README.md

@@ -1,13 +1,14 @@
 # @mastra/auth-workos
 
-A WorkOS authentication provider for Mastra, enabling seamless integration of WorkOS authentication and authorization in your applications.
+A WorkOS integration for Mastra that supports authentication, role-based access control (RBAC), and Fine-Grained Authorization (FGA).
 
 ## Features
 
 - 🔐 WorkOS authentication integration
 - 👥 User management and organization membership support
 - 🔑 JWT token verification using WorkOS JWKS
-- 👮‍♂️ Role-based authorization with admin role support
+- 👮 Role-based authorization with `MastraRBACWorkos`
+- 🔒 Fine-Grained Authorization with `MastraFGAWorkos`
 
 ## Installation
 
@@ -23,7 +24,8 @@ pnpm add @mastra/auth-workos
 
 ```typescript
 import { Mastra } from '@mastra/core/mastra';
-import { MastraAuthWorkos } from '@mastra/auth-workos';
+import { MastraFGAPermissions } from '@mastra/core/auth/ee';
+import { MastraAuthWorkos, MastraFGAWorkos } from '@mastra/auth-workos';
 
 // Initialize with environment variables
 const auth = new MastraAuthWorkos();
@@ -32,6 +34,7 @@ const auth = new MastraAuthWorkos();
 const auth = new MastraAuthWorkos({
   apiKey: 'your_workos_api_key',
   clientId: 'your_workos_client_id',
+  redirectUri: 'https://your-app.com/auth/callback',
 });
 
 // Enable auth in Mastra
@@ -43,6 +46,36 @@ const mastra = new Mastra({
 });
 ```
 
+`MastraAuthWorkos` authorizes any authenticated WorkOS user by default.
+
+If you also use `MastraFGAWorkos`, set `fetchMemberships: true` so Mastra loads organization memberships during authentication:
+
+```typescript
+const auth = new MastraAuthWorkos({
+  apiKey: 'your_workos_api_key',
+  clientId: 'your_workos_client_id',
+  redirectUri: 'https://your-app.com/auth/callback',
+  fetchMemberships: true,
+});
+
+const fga = new MastraFGAWorkos({
+  apiKey: 'your_workos_api_key',
+  clientId: 'your_workos_client_id',
+  resourceMapping: {
+    thread: {
+      fgaResourceType: 'workspace-thread',
+      deriveId: ({ resourceId, user }) => resourceId ?? user.id,
+    },
+  },
+  permissionMapping: {
+    [MastraFGAPermissions.MEMORY_READ]: 'read',
+    [MastraFGAPermissions.MEMORY_WRITE]: 'update',
+  },
+});
+```
+
+`thread` is the canonical Mastra resource key for memory authorization. `MastraFGAWorkos` also accepts the legacy alias `memory` for backward compatibility.
+
 ## Configuration
 
 The package requires the following configuration:
@@ -51,6 +84,7 @@ The package requires the following configuration:
 
 - `WORKOS_API_KEY`: Your WorkOS API key
 - `WORKOS_CLIENT_ID`: Your WorkOS client ID
+- `WORKOS_REDIRECT_URI`: Your WorkOS redirect URI when you use the built-in AuthKit session flow
 
 ### Options
 
@@ -60,15 +94,45 @@ You can also provide these values directly when initializing the provider:
 interface MastraAuthWorkosOptions {
   apiKey?: string;
   clientId?: string;
+  redirectUri?: string;
+  fetchMemberships?: boolean;
+  trustJwtClaims?: boolean;
+  jwtClaims?: {
+    userId?: string;
+    workosId?: string;
+    email?: string;
+    name?: string;
+    organizationId?: string;
+    organizationMembershipId?: string;
+  };
 }
 ```
 
+### Service tokens and custom JWT claims
+
+If your WorkOS JWT template includes custom claims for service principals or pre-resolved FGA context, you can map them directly into the authenticated `WorkOSUser`:
+
+```typescript
+const auth = new MastraAuthWorkos({
+  apiKey: 'your_workos_api_key',
+  clientId: 'your_workos_client_id',
+  redirectUri: 'https://your-app.com/auth/callback',
+  trustJwtClaims: true,
+  jwtClaims: {
+    organizationMembershipId: 'urn:mastra:organization_membership_id',
+    organizationId: 'org_id',
+  },
+});
+```
+
+With `trustJwtClaims: true`, Mastra can authenticate verified bearer tokens from a WorkOS custom JWT template even when `workos.userManagement.getUser()` is not the right lookup path, such as machine-to-machine or service-account tokens.
+
 ## API
 
-### `authenticateToken(token: string): Promise<WorkosUser | null>`
+### `authenticateToken(token: string, request): Promise<WorkOSUser | null>`
 
 Verifies a JWT token using WorkOS JWKS and returns the user information if valid.
 
-### `authorizeUser(user: WorkosUser): Promise<boolean>`
+### `authorizeUser(user: WorkOSUser, request): Promise<boolean>`
 
-Checks if a user has admin privileges by verifying their organization memberships and roles.
+Authorizes an authenticated WorkOS user. By default, this returns `true` when the user has the required identifiers. Override this method in a subclass if you need stricter authorization.

package/dist/auth-provider.d.ts

@@ -10,7 +10,9 @@ import { MastraAuthProvider } from '@mastra/core/server';
 import { AuthService } from '@workos/authkit-session';
 import type { AuthKitConfig } from '@workos/authkit-session';
 import { WorkOS } from '@workos-inc/node';
+import type { OrganizationMembership } from '@workos-inc/node';
 import type { HonoRequest } from 'hono';
+import { LRUCache } from 'lru-cache';
 import type { WorkOSUser, MastraAuthWorkosOptions } from './types.js';
 /**
  * Mastra authentication provider for WorkOS.
@@ -37,6 +39,11 @@ export declare class MastraAuthWorkos extends MastraAuthProvider<WorkOSUser> imp
     protected ssoConfig: MastraAuthWorkosOptions['sso'];
     protected authService: AuthService<Request, Response>;
     protected config: AuthKitConfig;
+    protected fetchMemberships: boolean;
+    protected trustJwtClaims: boolean;
+    protected jwtClaimOptions?: MastraAuthWorkosOptions['jwtClaims'];
+    protected mapJwtPayloadToUser?: MastraAuthWorkosOptions['mapJwtPayloadToUser'];
+    protected membershipCache: LRUCache<string, OrganizationMembership[]>;
     constructor(options?: MastraAuthWorkosOptions);
     /**
      * Authenticate a bearer token or session cookie.
@@ -61,6 +68,13 @@ export declare class MastraAuthWorkos extends MastraAuthProvider<WorkOSUser> imp
      * Get the URL to the user's profile page.
      */
     getUserProfileUrl(user: EEUser): string;
+    private getMemberships;
+    private attachMembershipsIfNeeded;
+    private getSingleMembershipOrganizationId;
+    private resolveJwtPayloadUser;
+    private buildUserFromJwtClaims;
+    private mergeJwtPayloadUser;
+    private readJwtClaim;
     /**
      * Get the URL to redirect users to for SSO login.
      */

package/dist/auth-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-provider.d.ts","sourceRoot":"","sources":["../src/auth-provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth-provider.d.ts","sourceRoot":"","sources":["../src/auth-provider.ts"],"names":[],"mappings":"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"}

package/dist/fga-provider.d.ts

@@ -0,0 +1,158 @@
+/**
+ * WorkOS FGA provider for Mastra.
+ *
+ * Integrates WorkOS Authorization API with Mastra's FGA interface
+ * for permission-based, resource-level authorization.
+ *
+ * @license Mastra Enterprise License - see ee/LICENSE
+ */
+import type { IFGAManager, FGACheckParams, FGAResource, FGACreateResourceParams, FGAUpdateResourceParams, FGADeleteResourceParams, FGAListResourcesOptions, FGARoleAssignment, FGARoleParams, FGAListRoleAssignmentsOptions, MastraFGAPermissionInput } from '@mastra/core/auth/ee';
+import type { MastraFGAWorkosOptions, WorkOSUser } from './types.js';
+export declare class WorkOSFGAResourceNotFoundError extends Error {
+    readonly status = 404;
+    readonly resourceType: string;
+    readonly resourceId: string;
+    constructor(resourceType: string, resourceId: string);
+}
+export declare class WorkOSFGAMembershipResolutionError extends Error {
+    readonly status = 500;
+    readonly userId?: string;
+    constructor(user: WorkOSUser);
+}
+/**
+ * WorkOS FGA provider using the new Authorization API.
+ *
+ * Uses `resourceMapping` to translate Mastra resource types to WorkOS FGA resource types
+ * and `permissionMapping` to translate Mastra permissions to WorkOS permission slugs.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { MastraFGAWorkos } from '@mastra/auth-workos';
+ * import { MastraFGAPermissions } from '@mastra/core/auth/ee';
+ *
+ * const fga = new MastraFGAWorkos({
+ *   resourceMapping: {
+ *     agent: { fgaResourceType: 'team', deriveId: (ctx) => ctx.user.teamId },
+ *     workflow: { fgaResourceType: 'team', deriveId: (ctx) => ctx.user.teamId },
+ *     thread: { fgaResourceType: 'workspace-thread', deriveId: ({ resourceId }) => resourceId },
+ *   },
+ *   permissionMapping: {
+ *     [MastraFGAPermissions.AGENTS_EXECUTE]: 'manage-workflows',
+ *     [MastraFGAPermissions.WORKFLOWS_EXECUTE]: 'manage-workflows',
+ *     [MastraFGAPermissions.MEMORY_READ]: 'read',
+ *     [MastraFGAPermissions.MEMORY_WRITE]: 'update',
+ *   },
+ * });
+ * ```
+ *
+ * @example With Mastra server config
+ * ```typescript
+ * const mastra = new Mastra({
+ *   server: {
+ *     auth: new MastraAuthWorkos({ ... }),
+ *     fga: new MastraFGAWorkos({
+ *       resourceMapping: { ... },
+ *       permissionMapping: { ... },
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+export declare class MastraFGAWorkos implements IFGAManager<WorkOSUser> {
+    private workos;
+    private organizationId?;
+    private resourceMapping;
+    private permissionMapping;
+    constructor(options: MastraFGAWorkosOptions);
+    /**
+     * Check if a user has permission on a resource.
+     *
+     * Resolves the user's organization membership ID, maps the permission
+     * via `permissionMapping`, and delegates to `workos.authorization.check()`.
+     */
+    check(user: WorkOSUser, params: FGACheckParams): Promise<boolean>;
+    /**
+     * Require that a user has permission, throwing FGADeniedError if not.
+     */
+    require(user: WorkOSUser, params: FGACheckParams): Promise<void>;
+    /**
+     * Filter resources to only those the user has permission to access.
+     *
+     * Uses WorkOS `listResourcesForMembership()` when the resource mapping can
+     * resolve a parent resource from user context. This avoids one check per
+     * resource for list endpoints like agents/workflows/tools.
+     *
+     * Falls back to per-resource `check()` calls when no parent resource can be
+     * resolved from the configured mapping.
+     */
+    filterAccessible<T extends {
+        id: string;
+    }>(user: WorkOSUser, resources: T[], resourceType: string, permission: MastraFGAPermissionInput): Promise<T[]>;
+    /**
+     * Create an authorization resource in WorkOS.
+     */
+    createResource(params: FGACreateResourceParams): Promise<FGAResource>;
+    /**
+     * Get an authorization resource by ID.
+     */
+    getResource(resourceId: string): Promise<FGAResource>;
+    /**
+     * List authorization resources with optional filters.
+     */
+    listResources(options?: FGAListResourcesOptions): Promise<FGAResource[]>;
+    /**
+     * Update an authorization resource.
+     */
+    updateResource(params: FGAUpdateResourceParams): Promise<FGAResource>;
+    /**
+     * Delete an authorization resource.
+     */
+    deleteResource(params: FGADeleteResourceParams): Promise<void>;
+    /**
+     * Assign a role to an organization membership on a resource.
+     */
+    assignRole(params: FGARoleParams): Promise<FGARoleAssignment>;
+    /**
+     * Remove a role assignment.
+     */
+    removeRole(params: FGARoleParams): Promise<void>;
+    /**
+     * List role assignments for an organization membership.
+     */
+    listRoleAssignments(options: FGAListRoleAssignmentsOptions): Promise<FGARoleAssignment[]>;
+    /**
+     * Resolve the organization membership ID from a user object.
+     * Looks for organizationMembershipId, then finds membership matching
+     * configured organizationId, then falls back to first membership.
+     *
+     * Returns undefined if no membership can be resolved, which causes
+     * authorization checks to deny access. Enable `fetchMemberships: true`
+     * on MastraAuthWorkos to populate the memberships field.
+     */
+    private resolveOrganizationMembershipId;
+    /**
+     * Map a Mastra permission string to a WorkOS permission slug via permissionMapping.
+     * Falls back to the original permission if no mapping is found.
+     */
+    private resolvePermission;
+    /**
+     * Resolve the parent resource context needed for WorkOS resource discovery.
+     */
+    private resolveParentResource;
+    /**
+     * Resolve the FGA resource ID using resourceMapping's deriveId function.
+     * Falls back to the original resource ID if no mapping is found.
+     */
+    private resolveResourceId;
+    private buildCheckOptions;
+    private getResourceMapping;
+    /**
+     * List accessible child resources for a membership, following pagination.
+     */
+    private listAccessibleResourceExternalIds;
+    /**
+     * Map a WorkOS AuthorizationResource to Mastra's FGAResource type.
+     */
+    private mapAuthorizationResource;
+}
+//# sourceMappingURL=fga-provider.d.ts.map

package/dist/fga-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fga-provider.d.ts","sourceRoot":"","sources":["../src/fga-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EACjB,aAAa,EACb,6BAA6B,EAC7B,wBAAwB,EACzB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,KAAK,EAAE,sBAAsB,EAA2B,UAAU,EAAE,MAAM,SAAS,CAAC;AAI3F,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,QAAQ,CAAC,MAAM,OAAO;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAWrD;AAED,qBAAa,kCAAmC,SAAQ,KAAK;IAC3D,QAAQ,CAAC,MAAM,OAAO;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,IAAI,EAAE,UAAU;CAQ7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,eAAgB,YAAW,WAAW,CAAC,UAAU,CAAC;IAC7D,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAC,CAAS;IAChC,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,iBAAiB,CAAyB;gBAEtC,OAAO,EAAE,sBAAsB;IAqB3C;;;;;OAKG;IACG,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAcvE;;OAEG;IACG,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBtE;;;;;;;;;OASG;IACG,gBAAgB,CAAC,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAC7C,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,CAAC,EAAE,EACd,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,wBAAwB,GACnC,OAAO,CAAC,CAAC,EAAE,CAAC;IAuDf;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC;IAkB3E;;OAEG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAK3D;;OAEG;IACG,aAAa,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAa9E;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC;IAS3E;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpE;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAuBnE;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IActD;;OAEG;IACG,mBAAmB,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAsB/F;;;;;;;;OAQG;IACH,OAAO,CAAC,+BAA+B;IAgCvC;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAiB7B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,iBAAiB;IAgCzB,OAAO,CAAC,kBAAkB;IAsB1B;;OAEG;YACW,iCAAiC;IAgC/C;;OAEG;IACH,OAAO,CAAC,wBAAwB;CAWjC"}