@mastra/auth-supabase 1.1.6 → 1.2.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/dist/_types/{@internal_auth/dist/_types/@internal_core → @internal_auth@0.0.36/dist/_types/@internal_core@0.1.4}/dist/base/index.d.ts +1 -1
  2. package/dist/_types/{@internal_auth/dist/_types/@internal_core/dist/index-TNVgGNjs.d.ts → @internal_auth@0.0.36/dist/_types/@internal_core@0.1.4/dist/index-Diz1p9N7.d.ts} +3 -2
  3. package/dist/_types/@internal_auth@0.0.36/dist/ee/capabilities.d.ts +142 -0
  4. package/dist/_types/@internal_auth@0.0.36/dist/ee/defaults/index.d.ts +8 -0
  5. package/dist/_types/@internal_auth@0.0.36/dist/ee/defaults/rbac/index.d.ts +7 -0
  6. package/dist/_types/@internal_auth@0.0.36/dist/ee/defaults/rbac/static.d.ts +106 -0
  7. package/dist/_types/@internal_auth@0.0.36/dist/ee/defaults/roles.d.ts +92 -0
  8. package/dist/_types/@internal_auth@0.0.36/dist/ee/fga-check.d.ts +59 -0
  9. package/dist/_types/@internal_auth@0.0.36/dist/ee/index.d.ts +15 -0
  10. package/dist/_types/@internal_auth@0.0.36/dist/ee/interfaces/acl.d.ts +140 -0
  11. package/dist/_types/@internal_auth@0.0.36/dist/ee/interfaces/fga.d.ts +408 -0
  12. package/dist/_types/@internal_auth@0.0.36/dist/ee/interfaces/index.d.ts +15 -0
  13. package/dist/_types/@internal_auth@0.0.36/dist/ee/interfaces/permissions.generated.d.ts +551 -0
  14. package/dist/_types/@internal_auth@0.0.36/dist/ee/interfaces/rbac.d.ts +207 -0
  15. package/dist/_types/@internal_auth@0.0.36/dist/ee/interfaces/user.d.ts +18 -0
  16. package/dist/_types/@internal_auth@0.0.36/dist/ee/license.d.ts +171 -0
  17. package/dist/_types/@internal_auth@0.0.36/dist/index.d.ts +358 -0
  18. package/dist/_types/{@internal_auth → @internal_auth@0.0.36}/dist/provider/index.d.ts +74 -2
  19. package/dist/_types/@internal_auth@0.0.36/dist/session/cookie.d.ts +82 -0
  20. package/dist/_types/@internal_auth@0.0.36/dist/session/index.d.ts +39 -0
  21. package/dist/_types/@internal_auth@0.0.36/dist/session/memory.d.ts +60 -0
  22. package/dist/_types/{@internal_auth → @internal_auth@0.0.36}/dist/types/index.d.ts +7 -0
  23. package/dist/index.cjs +73 -0
  24. package/dist/index.cjs.map +1 -1
  25. package/dist/index.d.ts +13 -2
  26. package/dist/index.d.ts.map +1 -1
  27. package/dist/index.js +73 -0
  28. package/dist/index.js.map +1 -1
  29. package/package.json +7 -7
  30. package/LICENSE.md +0 -32
  31. /package/dist/_types/{@internal_auth → @internal_auth@0.0.36}/package.json +0 -0
@@ -1,4 +1,4 @@
1
- import { i as IMastraLogger, u as RegisteredLogger } from "../index-TNVgGNjs.js";
1
+ import { i as IMastraLogger, u as RegisteredLogger } from "../index-Diz1p9N7.js";
2
2
  export declare class MastraBase {
3
3
  #private;
4
4
  component: RegisteredLogger;
@@ -90,6 +90,7 @@ declare function exportTrackedException(ctx: LoggerAdapterContext | undefined, e
90
90
  * so the derived record preserves all context from the native call.
91
91
  */
92
92
  declare function buildLogRecordData(args: unknown[]): Record<string, unknown> | undefined;
93
+ declare const noopLogger: IMastraLogger;
93
94
  declare const RegisteredLogger: {
94
95
  readonly AGENT: 'AGENT';
95
96
  readonly OBSERVABILITY: 'OBSERVABILITY';
@@ -311,5 +312,5 @@ declare class ConsoleLogger extends MastraLogger {
311
312
  hasMore: boolean;
312
313
  }>;
313
314
  }
314
- export { buildLogRecordData as _, LogFilter as a, LoggerTransport as c, createCustomTransport as d, AdaptableLogger as f, TraceFields as g, LoggerAdapterOptions as h, IMastraLogger as i, MastraLogger as l, LoggerAdapterContext as m, ConsoleLogger as n, LogFilterContext as o, AdapterLogSink as p, ConsoleLoggerOptions as r, LogLevel as s, BaseLogMessage as t, RegisteredLogger as u, exportTrackedException as v, isAdaptableLogger as y };
315
- //# sourceMappingURL=index-TNVgGNjs.d.ts.map
315
+ export { TraceFields as _, LogFilter as a, isAdaptableLogger as b, LoggerTransport as c, createCustomTransport as d, noopLogger as f, LoggerAdapterOptions as g, LoggerAdapterContext as h, IMastraLogger as i, MastraLogger as l, AdapterLogSink as m, ConsoleLogger as n, LogFilterContext as o, AdaptableLogger as p, ConsoleLoggerOptions as r, LogLevel as s, BaseLogMessage as t, RegisteredLogger as u, buildLogRecordData as v, exportTrackedException as y };
316
+ //# sourceMappingURL=index-Diz1p9N7.d.ts.map
@@ -0,0 +1,142 @@
1
+ /**
2
+ * Capabilities detection and response building for EE authentication.
3
+ */
4
+ import type { MastraAuthProvider } from '../provider/index.js';
5
+ import type { IFGAProvider } from './interfaces/fga.js';
6
+ import type { IRBACProvider } from './interfaces/rbac.js';
7
+ import type { EEUser } from './interfaces/user.js';
8
+ /**
9
+ * Public capabilities response (no authentication required).
10
+ * Contains just enough info to render the login page.
11
+ */
12
+ export interface PublicAuthCapabilities {
13
+ /** Whether auth is enabled */
14
+ enabled: boolean;
15
+ /** Login configuration (null if no auth or no SSO) */
16
+ login: {
17
+ /** Type of login available */
18
+ type: 'sso' | 'credentials' | 'both';
19
+ /** Whether sign-up is enabled (defaults to true) */
20
+ signUpEnabled?: boolean;
21
+ /** Optional description explaining the auth requirement and what credentials to use */
22
+ description?: string;
23
+ /** SSO configuration */
24
+ sso?: {
25
+ /** Provider name */
26
+ provider: string;
27
+ /** Button text */
28
+ text: string;
29
+ /** Icon URL */
30
+ icon?: string;
31
+ /** Description of the auth requirement */
32
+ description?: string;
33
+ /** Login URL */
34
+ url: string;
35
+ };
36
+ } | null;
37
+ }
38
+ /**
39
+ * User info for authenticated response.
40
+ */
41
+ export interface AuthenticatedUser {
42
+ /** User ID */
43
+ id: string;
44
+ /** User email */
45
+ email?: string;
46
+ /** Display name */
47
+ name?: string;
48
+ /** Avatar URL */
49
+ avatarUrl?: string;
50
+ }
51
+ /**
52
+ * Capability flags indicating which EE features are available.
53
+ */
54
+ export interface CapabilityFlags {
55
+ /** IUserProvider is implemented and licensed */
56
+ user: boolean;
57
+ /** ISessionProvider is implemented and licensed */
58
+ session: boolean;
59
+ /** ISSOProvider is implemented and licensed */
60
+ sso: boolean;
61
+ /** IRBACProvider is implemented and licensed */
62
+ rbac: boolean;
63
+ /** IACLProvider is implemented and licensed */
64
+ acl: boolean;
65
+ /** IFGAProvider is implemented and licensed */
66
+ fga: boolean;
67
+ }
68
+ /**
69
+ * User's access (roles and permissions).
70
+ */
71
+ export interface UserAccess {
72
+ /** User's roles */
73
+ roles: string[];
74
+ /** User's resolved permissions */
75
+ permissions: string[];
76
+ }
77
+ /**
78
+ * Authenticated capabilities response.
79
+ * Extends public capabilities with user context and feature flags.
80
+ */
81
+ export interface AuthenticatedCapabilities extends PublicAuthCapabilities {
82
+ /** Current authenticated user */
83
+ user: AuthenticatedUser;
84
+ /** Available EE capabilities */
85
+ capabilities: CapabilityFlags;
86
+ /** User's access (if RBAC available) */
87
+ access: UserAccess | null;
88
+ /** Available roles in the system (only present for admin users) */
89
+ availableRoles?: {
90
+ id: string;
91
+ name: string;
92
+ }[];
93
+ }
94
+ /**
95
+ * Type guard to check if response is authenticated.
96
+ */
97
+ export declare function isAuthenticated(caps: PublicAuthCapabilities | AuthenticatedCapabilities): caps is AuthenticatedCapabilities;
98
+ /**
99
+ * Options for building capabilities.
100
+ */
101
+ export interface BuildCapabilitiesOptions {
102
+ /**
103
+ * RBAC provider for role-based access control (EE feature).
104
+ * Separate from the auth provider to allow mixing different providers.
105
+ *
106
+ * @example
107
+ * ```typescript
108
+ * const rbac = new StaticRBACProvider({
109
+ * roles: DEFAULT_ROLES,
110
+ * getUserRoles: (user) => [user.role],
111
+ * });
112
+ *
113
+ * buildCapabilities(auth, request, { rbac });
114
+ * ```
115
+ */
116
+ rbac?: IRBACProvider<EEUser>;
117
+ /**
118
+ * FGA provider for fine-grained authorization (EE feature).
119
+ * Separate from the auth provider to allow mixing different providers.
120
+ */
121
+ fga?: IFGAProvider<EEUser>;
122
+ /**
123
+ * API route prefix used to construct SSO login URLs.
124
+ * Defaults to `/api` when not provided.
125
+ *
126
+ * @example `/mastra` results in SSO URL `/mastra/auth/sso/login`
127
+ */
128
+ apiPrefix?: string;
129
+ }
130
+ /**
131
+ * Build capabilities response based on auth configuration and request state.
132
+ *
133
+ * This function determines what capabilities are available and, if the user
134
+ * is authenticated, includes their user info and access permissions.
135
+ *
136
+ * @param auth - Auth provider (or null if no auth configured)
137
+ * @param request - Incoming HTTP request
138
+ * @param options - Optional configuration (roleMapping, etc.)
139
+ * @returns Capabilities response (public or authenticated)
140
+ */
141
+ export declare function buildCapabilities(auth: MastraAuthProvider | null, request: Request, options?: BuildCapabilitiesOptions): Promise<PublicAuthCapabilities | AuthenticatedCapabilities>;
142
+ //# sourceMappingURL=capabilities.d.ts.map
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Default implementations for EE authentication.
3
+ *
4
+ * @license Mastra Enterprise License - see ee/LICENSE
5
+ */
6
+ export { DEFAULT_ROLES, type Permission, type PermissionPattern, type RoleMapping, getDefaultRole, resolvePermissions, resolvePermissionsFromMapping, matchesPermission, hasPermission, } from './roles.js';
7
+ export { StaticRBACProvider, type StaticRBACProviderOptions } from './rbac/index.js';
8
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,7 @@
1
+ /**
2
+ * RBAC provider implementations.
3
+ *
4
+ * @license Mastra Enterprise License - see ee/LICENSE
5
+ */
6
+ export { StaticRBACProvider, type StaticRBACProviderOptions } from './static.js';
7
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,106 @@
1
+ /**
2
+ * Static RBAC provider with config-based roles.
3
+ */
4
+ import type { RoleDefinition, RoleMapping, IRBACProvider } from '../../interfaces/index.js';
5
+ /**
6
+ * Options for StaticRBACProvider.
7
+ *
8
+ * Use ONE of the following approaches:
9
+ * - `roles`: Define role structures with permissions (Mastra's native role system)
10
+ * - `roleMapping`: Map provider roles directly to permissions (simpler for external providers)
11
+ */
12
+ export type StaticRBACProviderOptions<TUser = unknown> = {
13
+ /** Role definitions (Mastra's native role system) */
14
+ roles: RoleDefinition[];
15
+ /** Function to get user's role IDs */
16
+ getUserRoles: (user: TUser) => string[] | Promise<string[]>;
17
+ roleMapping?: never;
18
+ } | {
19
+ /**
20
+ * Role mapping for translating provider roles to permissions.
21
+ * Use this when your identity provider has roles that need to be
22
+ * mapped to Mastra permissions.
23
+ */
24
+ roleMapping: RoleMapping;
25
+ /** Function to get user's role IDs from the provider */
26
+ getUserRoles: (user: TUser) => string[] | Promise<string[]>;
27
+ roles?: never;
28
+ };
29
+ /**
30
+ * Static RBAC provider.
31
+ *
32
+ * Supports two modes:
33
+ * 1. **Role definitions**: Use Mastra's native role system with structured roles
34
+ * 2. **Role mapping**: Directly map provider roles to permissions
35
+ *
36
+ * @example Using role definitions (Mastra's native system)
37
+ * ```typescript
38
+ * const rbac = new StaticRBACProvider({
39
+ * roles: DEFAULT_ROLES,
40
+ * getUserRoles: (user) => [user.role],
41
+ * });
42
+ * ```
43
+ *
44
+ * @example Using role mapping (for external providers)
45
+ * ```typescript
46
+ * const rbac = new StaticRBACProvider({
47
+ * roleMapping: {
48
+ * "Engineering": ["agents:*", "workflows:*"],
49
+ * "Product": ["agents:read", "workflows:read"],
50
+ * "_default": [],
51
+ * },
52
+ * getUserRoles: (user) => user.providerRoles,
53
+ * });
54
+ * ```
55
+ *
56
+ * @example Async role lookup
57
+ * ```typescript
58
+ * const rbac = new StaticRBACProvider({
59
+ * roles: DEFAULT_ROLES,
60
+ * getUserRoles: async (user) => {
61
+ * return db.getUserRoles(user.id);
62
+ * },
63
+ * });
64
+ * ```
65
+ */
66
+ export declare class StaticRBACProvider<TUser = unknown> implements IRBACProvider<TUser> {
67
+ private roles?;
68
+ private _roleMapping?;
69
+ private getUserRolesFn;
70
+ private permissionCache;
71
+ /** Expose roleMapping for middleware access */
72
+ get roleMapping(): RoleMapping | undefined;
73
+ constructor(options: StaticRBACProviderOptions<TUser>);
74
+ getRoles(user: TUser): Promise<string[]>;
75
+ hasRole(user: TUser, role: string): Promise<boolean>;
76
+ getPermissions(user: TUser): Promise<string[]>;
77
+ hasPermission(user: TUser, permission: string): Promise<boolean>;
78
+ hasAllPermissions(user: TUser, permissions: string[]): Promise<boolean>;
79
+ hasAnyPermission(user: TUser, permissions: string[]): Promise<boolean>;
80
+ /**
81
+ * Clear the permission cache.
82
+ */
83
+ clearCache(): void;
84
+ /**
85
+ * Get all role definitions.
86
+ * Only available when using role definitions mode (not role mapping).
87
+ */
88
+ getRoleDefinitions(): RoleDefinition[];
89
+ /**
90
+ * Get a specific role definition.
91
+ * Only available when using role definitions mode (not role mapping).
92
+ */
93
+ getRoleDefinition(roleId: string): RoleDefinition | undefined;
94
+ /**
95
+ * Get all available roles in the system.
96
+ */
97
+ getAvailableRoles(): Promise<{
98
+ id: string;
99
+ name: string;
100
+ }[]>;
101
+ /**
102
+ * Get the resolved permissions for a specific role.
103
+ */
104
+ getPermissionsForRole(roleId: string): Promise<string[]>;
105
+ }
106
+ //# sourceMappingURL=static.d.ts.map
@@ -0,0 +1,92 @@
1
+ /**
2
+ * Default roles and permissions for Mastra Studio.
3
+ */
4
+ import type { RoleDefinition, RoleMapping } from '../interfaces/index.js';
5
+ export type { RoleMapping };
6
+ /**
7
+ * Default role definitions for Studio.
8
+ *
9
+ * These roles provide a sensible starting point for most applications:
10
+ * - **owner**: Full access to everything
11
+ * - **admin**: Manage agents, workflows, and users
12
+ * - **member**: Execute agents and workflows, read-only settings
13
+ * - **viewer**: Read-only access
14
+ *
15
+ * Permission patterns:
16
+ * - `*` - Full access to everything
17
+ * - `resource:*` - All actions on a specific resource
18
+ * - `*:action` - An action across all resources (e.g., `*:read` for read-only)
19
+ */
20
+ export declare const DEFAULT_ROLES: RoleDefinition[];
21
+ export type { Permission, PermissionPattern } from '../interfaces/permissions.generated.js';
22
+ /**
23
+ * Get role by ID from default roles.
24
+ *
25
+ * @param roleId - Role ID to find
26
+ * @returns Role definition or undefined
27
+ */
28
+ export declare function getDefaultRole(roleId: string): RoleDefinition | undefined;
29
+ /**
30
+ * Resolve all permissions for a set of role IDs.
31
+ *
32
+ * Handles role inheritance and deduplication.
33
+ *
34
+ * @param roleIds - Role IDs to resolve
35
+ * @param roles - Role definitions (defaults to DEFAULT_ROLES)
36
+ * @returns Array of resolved permissions
37
+ */
38
+ export declare function resolvePermissions(roleIds: string[], roles?: RoleDefinition[]): string[];
39
+ /**
40
+ * Check if a permission matches (including wildcard support).
41
+ *
42
+ * Permission format: `{resource}:{action}[:{resource-id}]`
43
+ *
44
+ * Examples:
45
+ * - `*` matches everything
46
+ * - `agents:*` matches `agents:read`, `agents:read:my-agent`
47
+ * - `*:read` matches `agents:read`, `workflows:read` (action across all resources)
48
+ * - `agents:read` matches `agents:read`, `agents:read:my-agent`
49
+ * - `agents:read:my-agent` matches only `agents:read:my-agent`
50
+ * - `agents:*:my-agent` matches `agents:read:my-agent`, `agents:write:my-agent`
51
+ *
52
+ * @param userPermission - Permission the user has
53
+ * @param requiredPermission - Permission being checked
54
+ * @returns True if permission matches
55
+ */
56
+ export declare function matchesPermission(userPermission: string, requiredPermission: string): boolean;
57
+ /**
58
+ * Check if a user has a specific permission.
59
+ *
60
+ * @param userPermissions - Permissions the user has
61
+ * @param requiredPermission - Permission being checked
62
+ * @returns True if user has the permission
63
+ */
64
+ export declare function hasPermission(userPermissions: string[], requiredPermission: string): boolean;
65
+ /**
66
+ * Resolve permissions from user roles using a role mapping.
67
+ *
68
+ * This function translates provider-defined roles (from WorkOS, Okta, etc.)
69
+ * to Mastra permissions using a configurable mapping.
70
+ *
71
+ * @example
72
+ * ```typescript
73
+ * const roleMapping = {
74
+ * "Engineering": ["agents:*", "workflows:*"],
75
+ * "Product": ["agents:read"],
76
+ * "_default": [],
77
+ * };
78
+ *
79
+ * // User has "Engineering" and "QA" roles
80
+ * const permissions = resolvePermissionsFromMapping(
81
+ * ["Engineering", "QA"],
82
+ * roleMapping
83
+ * );
84
+ * // Result: ["agents:*", "workflows:*"] (QA is unmapped, gets _default)
85
+ * ```
86
+ *
87
+ * @param roles - User's roles from the identity provider
88
+ * @param mapping - Role to permission mapping
89
+ * @returns Array of resolved permissions
90
+ */
91
+ export declare function resolvePermissionsFromMapping(roles: string[], mapping: RoleMapping): string[];
92
+ //# sourceMappingURL=roles.d.ts.map
@@ -0,0 +1,59 @@
1
+ /**
2
+ * FGA enforcement utility for checking fine-grained authorization.
3
+ *
4
+ * @license Mastra Enterprise License - see ee/LICENSE
5
+ */
6
+ import type { ActorSignal, FGACheckContext, IFGAProvider } from './interfaces/fga.js';
7
+ import type { MastraFGAPermissionInput } from './interfaces/permissions.generated.js';
8
+ export type { ActorSignal };
9
+ export interface CheckFGAOptions {
10
+ fgaProvider: IFGAProvider | undefined;
11
+ user: any;
12
+ resource: {
13
+ type: string;
14
+ id: string;
15
+ };
16
+ permission: MastraFGAPermissionInput | MastraFGAPermissionInput[];
17
+ context?: FGACheckContext;
18
+ requestContext?: FGACheckContext['requestContext'];
19
+ actor?: ActorSignal;
20
+ }
21
+ export interface RequireFGAOptions extends CheckFGAOptions {
22
+ metadata?: Record<string, unknown>;
23
+ }
24
+ export declare function getAgentFGAResourceId(agentId: string): string;
25
+ export declare function getWorkflowFGAResourceId(workflowId: string): string;
26
+ export declare function getStandaloneToolFGAResourceId(toolName: string): string;
27
+ export declare function getAgentToolFGAResourceId(agentId: string, toolName: string): string;
28
+ export declare function getMCPToolFGAResourceId(serverName: string, toolName: string): string;
29
+ /**
30
+ * Check fine-grained authorization for a resource.
31
+ *
32
+ * No-op if no FGA provider is configured (backward compatibility).
33
+ * Delegates to fgaProvider.require() which throws FGADeniedError if denied.
34
+ */
35
+ export declare function checkFGA(options: CheckFGAOptions): Promise<void>;
36
+ /**
37
+ * Require fine-grained authorization for a resource.
38
+ *
39
+ * No-op if no FGA provider is configured. When FGA is configured, a missing
40
+ * user fails closed.
41
+ */
42
+ export declare function requireFGA(options: RequireFGAOptions): Promise<void>;
43
+ /**
44
+ * Error thrown when an FGA authorization check is denied.
45
+ */
46
+ export declare class FGADeniedError extends Error {
47
+ readonly user: any;
48
+ readonly resource: {
49
+ type: string;
50
+ id: string;
51
+ };
52
+ readonly permission: MastraFGAPermissionInput | MastraFGAPermissionInput[];
53
+ readonly status: number;
54
+ constructor(user: any, resource: {
55
+ type: string;
56
+ id: string;
57
+ }, permission: MastraFGAPermissionInput | MastraFGAPermissionInput[], reason?: string);
58
+ }
59
+ //# sourceMappingURL=fga-check.d.ts.map
@@ -0,0 +1,15 @@
1
+ /**
2
+ * @mastra/core/auth/ee
3
+ *
4
+ * Enterprise authentication capabilities for Mastra.
5
+ * This code is licensed under the Mastra Enterprise License - see ee/LICENSE.
6
+ *
7
+ * @license Mastra Enterprise License - see ee/LICENSE
8
+ * @packageDocumentation
9
+ */
10
+ export * from './interfaces/index.js';
11
+ export * from './capabilities.js';
12
+ export { validateLicense, isLicenseValid, isEELicenseValid, isFeatureEnabled, isDevEnvironment, isEEEnabled, startLicenseValidation, getSafeLicenseSummary, warnIfDevEENeedsLicense, clearLicenseCache, type LicenseInfo, } from './license.js';
13
+ export { checkFGA, requireFGA, FGADeniedError, getAgentFGAResourceId, getWorkflowFGAResourceId, getStandaloneToolFGAResourceId, getAgentToolFGAResourceId, getMCPToolFGAResourceId, type ActorSignal, type CheckFGAOptions, type RequireFGAOptions, } from './fga-check.js';
14
+ export * from './defaults/index.js';
15
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,140 @@
1
+ /**
2
+ * ACL provider interface for EE authentication.
3
+ * Enables resource-level access control in Studio.
4
+ */
5
+ /**
6
+ * Identifier for a resource.
7
+ */
8
+ export interface ResourceIdentifier {
9
+ /** Resource type (e.g., 'agent', 'workflow', 'thread') */
10
+ type: string;
11
+ /** Resource ID */
12
+ id: string;
13
+ }
14
+ /**
15
+ * An access control grant.
16
+ */
17
+ export interface ACLGrant {
18
+ /** Subject of the grant (user or role) */
19
+ subject: {
20
+ type: 'user' | 'role';
21
+ id: string;
22
+ };
23
+ /** Resource the grant applies to */
24
+ resource: ResourceIdentifier;
25
+ /** Actions granted */
26
+ actions: string[];
27
+ /** When the grant was created */
28
+ grantedAt: Date;
29
+ /** Who created the grant */
30
+ grantedBy?: string;
31
+ }
32
+ /**
33
+ * Provider interface for access control lists (read-only).
34
+ *
35
+ * Implement this interface to enable:
36
+ * - Resource-level permission checks
37
+ * - Filtered resource lists based on access
38
+ * - ACL display in resource settings
39
+ *
40
+ * @example
41
+ * ```typescript
42
+ * class DatabaseACLProvider implements IACLProvider {
43
+ * async canAccess(user, resource, action) {
44
+ * const grants = await this.db.query(
45
+ * `SELECT * FROM acl_grants
46
+ * WHERE (subject_type = 'user' AND subject_id = $1)
47
+ * OR (subject_type = 'role' AND subject_id = ANY($2))
48
+ * AND resource_type = $3 AND resource_id = $4
49
+ * AND $5 = ANY(actions)`,
50
+ * [user.id, user.roles, resource.type, resource.id, action]
51
+ * );
52
+ * return grants.length > 0;
53
+ * }
54
+ *
55
+ * async filterAccessible(user, resources, resourceType, action) {
56
+ * const accessible = await this.listAccessible(user, resourceType, action);
57
+ * return resources.filter(r => accessible.includes(r.id));
58
+ * }
59
+ * }
60
+ * ```
61
+ */
62
+ export interface IACLProvider<TUser = unknown> {
63
+ /**
64
+ * Check if user can perform action on resource.
65
+ *
66
+ * @param user - User making the request
67
+ * @param resource - Resource to check access for
68
+ * @param action - Action to check (e.g., 'read', 'write', 'execute', 'delete')
69
+ * @returns True if access is granted
70
+ */
71
+ canAccess(user: TUser, resource: ResourceIdentifier, action: string): Promise<boolean>;
72
+ /**
73
+ * Get list of resource IDs user can access.
74
+ *
75
+ * @param user - User to check access for
76
+ * @param resourceType - Type of resources to list
77
+ * @param action - Action to filter by
78
+ * @returns Array of accessible resource IDs
79
+ */
80
+ listAccessible(user: TUser, resourceType: string, action: string): Promise<string[]>;
81
+ /**
82
+ * Filter array of resources to only those user can access.
83
+ *
84
+ * @param user - User to check access for
85
+ * @param resources - Resources to filter
86
+ * @param resourceType - Type of the resources
87
+ * @param action - Action to filter by
88
+ * @returns Filtered array of accessible resources
89
+ */
90
+ filterAccessible<T extends {
91
+ id: string;
92
+ }>(user: TUser, resources: T[], resourceType: string, action: string): Promise<T[]>;
93
+ }
94
+ /**
95
+ * Extended interface for managing ACLs (write operations).
96
+ *
97
+ * Implement this in addition to IACLProvider to enable ACL management.
98
+ */
99
+ export interface IACLManager<TUser = unknown> extends IACLProvider<TUser> {
100
+ /**
101
+ * Grant access to a resource.
102
+ *
103
+ * @param subject - User or role to grant access to
104
+ * @param resource - Resource to grant access to
105
+ * @param actions - Actions to grant
106
+ */
107
+ grant(subject: {
108
+ type: 'user' | 'role';
109
+ id: string;
110
+ }, resource: ResourceIdentifier, actions: string[]): Promise<void>;
111
+ /**
112
+ * Revoke access to a resource.
113
+ *
114
+ * @param subject - User or role to revoke access from
115
+ * @param resource - Resource to revoke access to
116
+ * @param actions - Actions to revoke (omit to revoke all)
117
+ */
118
+ revoke(subject: {
119
+ type: 'user' | 'role';
120
+ id: string;
121
+ }, resource: ResourceIdentifier, actions?: string[]): Promise<void>;
122
+ /**
123
+ * List all grants for a resource.
124
+ *
125
+ * @param resource - Resource to list grants for
126
+ * @returns Array of grants
127
+ */
128
+ listGrants(resource: ResourceIdentifier): Promise<ACLGrant[]>;
129
+ /**
130
+ * List all grants for a subject.
131
+ *
132
+ * @param subject - User or role to list grants for
133
+ * @returns Array of grants
134
+ */
135
+ listGrantsForSubject(subject: {
136
+ type: 'user' | 'role';
137
+ id: string;
138
+ }): Promise<ACLGrant[]>;
139
+ }
140
+ //# sourceMappingURL=acl.d.ts.map