@magnet-cms/core 1.0.3 → 3.0.0

package/dist/permission.guard-B8HLjHP2.d.ts

@@ -0,0 +1,912 @@
+import * as _magnet_cms_common from '@magnet-cms/common';
+import { LogMetadata, EventName, EventHandler, EventHandlerOptions, EventPayload, BaseEventPayload, EventHistoryEntry, PluginMetadata, PluginFrontendManifest, Model, AuthConfig, AuthStrategy, ControllerMetadata, MethodMetadata, SchemaMetadata, PluginConfig, EnrichedPluginManifest, RegisteredPluginInfo, PermissionSource, PermissionDefinition, PermissionGroup, CategorizedPermissions, RoleWithPermissions } from '@magnet-cms/common';
+import { LoggerService, OnModuleDestroy, Type, OnModuleInit, CanActivate, ExecutionContext } from '@nestjs/common';
+import { ModulesContainer, Reflector } from '@nestjs/core';
+import { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper';
+
+/**
+ * Structured logger for Magnet CMS.
+ *
+ * Implements NestJS LoggerService with JSON/pretty output, log level
+ * filtering, sensitive field redaction, and automatic request context
+ * enrichment from EventContext (AsyncLocalStorage).
+ *
+ * @example
+ * ```typescript
+ * constructor(private readonly logger: MagnetLogger) {
+ *   this.logger.setContext(MyService.name)
+ * }
+ *
+ * doWork() {
+ *   this.logger.log('Starting work', { operation: 'doWork' })
+ * }
+ * ```
+ */
+declare class MagnetLogger implements LoggerService {
+    private context;
+    private cachedConfig;
+    /** Create a standalone logger instance (for use before DI is available). */
+    static create(context?: string): MagnetLogger;
+    /** Set the logger context (service name). Call in constructor. */
+    setContext(context: string): void;
+    /** Return a child logger with a namespaced context (parent:child). */
+    child(context: string): MagnetLogger;
+    log(message: string, metadata?: LogMetadata): void;
+    error(message: string, trace?: unknown, metadata?: LogMetadata): void;
+    warn(message: string, metadata?: LogMetadata): void;
+    debug(message: string, metadata?: LogMetadata): void;
+    verbose(message: string, metadata?: LogMetadata): void;
+    private getConfig;
+    private write;
+    private formatJson;
+    private formatPretty;
+}
+
+/**
+ * Type-safe event service for decoupled communication between modules.
+ *
+ * Features:
+ * - Type-safe events with payload validation
+ * - Priority-based handler execution
+ * - Async handlers that don't block the request
+ * - Error isolation (one handler failure doesn't affect others)
+ * - Event history for debugging
+ *
+ * @example
+ * ```typescript
+ * // Emitting events
+ * await this.eventService.emit('content.created', {
+ *   schema: 'posts',
+ *   documentId: '123',
+ * }, getEventContext())
+ *
+ * // Registering handlers programmatically
+ * const unsubscribe = this.eventService.on('content.created', async (payload) => {
+ *   console.log('Content created:', payload.documentId)
+ * })
+ *
+ * // Or use the @OnEvent decorator
+ * @OnEvent('content.created')
+ * async handleContentCreated(payload: EventPayload<'content.created'>): Promise<void> {
+ *   // ...
+ * }
+ * ```
+ */
+declare class EventService implements OnModuleDestroy {
+    private readonly logger;
+    private readonly handlers;
+    private readonly eventHistory;
+    private readonly maxHistorySize;
+    constructor(logger: MagnetLogger);
+    /**
+     * Register an event handler
+     *
+     * @param event - The event name to listen for
+     * @param handler - The handler function
+     * @param options - Handler options (priority, async, name)
+     * @returns Unsubscribe function
+     */
+    on<E extends EventName>(event: E, handler: EventHandler<E>, options?: EventHandlerOptions): () => void;
+    /**
+     * Unregister an event handler
+     *
+     * @param event - The event name
+     * @param handler - The handler function to remove
+     */
+    off<E extends EventName>(event: E, handler: EventHandler<E>): void;
+    /**
+     * Emit an event
+     *
+     * Executes sync handlers sequentially (awaiting each), then fires async
+     * handlers in parallel without waiting for them.
+     *
+     * @param event - The event name
+     * @param payload - The event payload (without base fields)
+     * @param context - Optional context (userId, requestId, ipAddress)
+     */
+    emit<E extends EventName>(event: E, payload: Omit<EventPayload<E>, keyof BaseEventPayload>, context?: Partial<BaseEventPayload>): Promise<void>;
+    /**
+     * Emit multiple events
+     *
+     * Events are emitted sequentially in the order provided.
+     *
+     * @param events - Array of event objects with event name and payload
+     * @param context - Optional shared context for all events
+     */
+    emitBatch(events: Array<{
+        event: EventName;
+        payload: Record<string, unknown>;
+    }>, context?: Partial<BaseEventPayload>): Promise<void>;
+    /**
+     * Get recent event history (for debugging)
+     *
+     * @param limit - Maximum number of events to return (default 100)
+     * @returns Array of recent events
+     */
+    getHistory(limit?: number): EventHistoryEntry[];
+    /**
+     * Get all registered handlers (for debugging)
+     *
+     * @returns Map of event names to handler info
+     */
+    getHandlers(): Map<EventName, Array<{
+        name: string;
+        priority: number;
+        async: boolean;
+    }>>;
+    /**
+     * Check if an event has any handlers registered
+     *
+     * @param event - The event name to check
+     * @returns True if at least one handler is registered
+     */
+    hasHandlers(event: EventName): boolean;
+    /**
+     * Get the number of handlers for an event
+     *
+     * @param event - The event name
+     * @returns Number of registered handlers
+     */
+    getHandlerCount(event: EventName): number;
+    /**
+     * Clear all handlers (for testing)
+     */
+    clearAllHandlers(): void;
+    /**
+     * Clear event history (for testing)
+     */
+    clearHistory(): void;
+    private addToHistory;
+    private logHandlerError;
+    onModuleDestroy(): void;
+}
+
+interface PluginDecoratorOptions extends Omit<PluginMetadata, 'module'> {
+    /** Frontend manifest for this plugin */
+    frontend?: Omit<PluginFrontendManifest, 'pluginName'>;
+    /**
+     * NestJS module containing controllers/services (auto-imported).
+     * Use a getter () => MyModule to defer loading until after DatabaseModule.register().
+     */
+    module?: Type<unknown> | (() => Type<unknown>);
+}
+/**
+ * Decorator to mark a class as a Magnet plugin
+ *
+ * @example
+ * ```ts
+ * @Plugin({
+ *   name: 'playground',
+ *   description: 'Visual schema builder',
+ *   version: '1.0.0',
+ *   frontend: {
+ *     routes: [{ path: 'playground', componentId: 'PlaygroundIndex' }],
+ *     sidebar: [{ id: 'playground', title: 'Playground', url: '/playground', icon: 'Boxes' }]
+ *   }
+ * })
+ * export class PlaygroundPlugin {}
+ * ```
+ */
+declare function Plugin(options: PluginDecoratorOptions): ClassDecorator;
+
+declare function Hook(hookName: string): MethodDecorator;
+
+/**
+ * Decorator to inject plugin options using standardized token.
+ *
+ * @param pluginName - The plugin name (e.g., 'playground')
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class MyService {
+ *   constructor(
+ *     @InjectPluginOptions('playground')
+ *     private readonly options: PlaygroundPluginOptions
+ *   ) {}
+ * }
+ * ```
+ */
+declare function InjectPluginOptions(pluginName: string): ParameterDecorator;
+
+declare class CreateUserDto {
+    id?: string;
+    email: string;
+    password?: string | null;
+    name: string;
+    role?: string;
+    provider?: string | null;
+    providerId?: string | null;
+}
+
+declare class User {
+    email: string;
+    /** Null for OAuth-only users who have never set a local password */
+    password?: string | null;
+    name: string;
+    role?: string;
+    /** OAuth provider name (e.g. 'google', 'github'). Null for local-only users. */
+    provider?: string | null;
+    /** OAuth provider user ID. Null for local-only users. */
+    providerId?: string | null;
+    isActive?: boolean;
+    emailVerified?: boolean;
+    lastLogin?: Date;
+    createdAt?: Date;
+    hashPassword(): Promise<void>;
+}
+
+interface PaginatedUserResult {
+    users: User[];
+    total: number;
+    page: number;
+    limit: number;
+}
+declare class UserService {
+    private readonly userModel;
+    constructor(userModel: Model<User>);
+    findAll(): Promise<_magnet_cms_common.BaseSchema<User>[]>;
+    findAllPaginated(page?: number, limit?: number): Promise<PaginatedUserResult>;
+    findOne(query: Partial<User>): Promise<_magnet_cms_common.BaseSchema<User> | null>;
+    findOneById(id: string): Promise<_magnet_cms_common.BaseSchema<User> | null>;
+    create(userData: CreateUserDto): Promise<_magnet_cms_common.BaseSchema<User>>;
+    update(id: string, updateUserDto: Partial<User>): Promise<_magnet_cms_common.BaseSchema<User>>;
+    remove(id: string): Promise<boolean>;
+    resetPassword(id: string, newPassword: string): Promise<{
+        message: string;
+    }>;
+}
+
+type AuthStrategyConstructor = new (config: AuthConfig, userService: UserService) => AuthStrategy;
+/**
+ * Factory for creating auth strategy instances.
+ *
+ * The JWT strategy is built-in. Other strategies (supabase, clerk)
+ * register themselves via their adapter's `.forRoot()` method.
+ *
+ * @example
+ * ```typescript
+ * // Strategies are auto-registered by adapter forRoot():
+ * MagnetModule.forRoot([
+ *   SupabaseAuthAdapter.forRoot(), // registers 'supabase' strategy internally
+ * ])
+ * ```
+ */
+declare class AuthStrategyFactory {
+    private static cachedStrategy;
+    private static cachedConfig;
+    private static customStrategies;
+    /**
+     * Register a custom auth strategy class.
+     * Called internally by auth adapter `.forRoot()` methods.
+     *
+     * @param name - Unique name for the strategy (used in config.strategy)
+     * @param strategyClass - Class constructor implementing AuthStrategy
+     */
+    static registerStrategy(name: string, strategyClass: AuthStrategyConstructor): void;
+    /**
+     * Get or create an auth strategy based on configuration.
+     * Called internally by AuthModule.forRoot().
+     *
+     * @param config - Auth configuration
+     * @param userService - UserService for database operations
+     * @param jwtSecret - JWT secret (fallback from global options)
+     */
+    static getStrategy(config: AuthConfig | undefined, userService: UserService, jwtSecret: string): AuthStrategy;
+    /** Clear the cached strategy (useful for testing) */
+    static clearCache(): void;
+    /** Clear all registered custom strategies (useful for testing) */
+    static clearStrategies(): void;
+    /** Check if a strategy is registered */
+    static hasStrategy(name: string): boolean;
+    private static configMatches;
+}
+
+/**
+ * DTO for creating a new role
+ */
+declare class CreateRoleDto {
+    /**
+     * Role slug (lowercase, no spaces)
+     * Must start with a letter, can contain letters, numbers, and hyphens
+     */
+    name: string;
+    /**
+     * Human-readable display name
+     */
+    displayName: string;
+    /**
+     * Optional description
+     */
+    description?: string;
+    /**
+     * Initial permissions to assign
+     */
+    permissions?: string[];
+}
+
+/**
+ * DTO for duplicating a role
+ */
+declare class DuplicateRoleDto {
+    /**
+     * Name for the new role (slug)
+     */
+    name: string;
+    /**
+     * Optional display name for the new role
+     * If not provided, defaults to "Copy of [original]"
+     */
+    displayName?: string;
+}
+
+/**
+ * DTO for updating a role
+ */
+declare class UpdateRoleDto {
+    /**
+     * Updated display name
+     */
+    displayName?: string;
+    /**
+     * Updated description
+     */
+    description?: string;
+}
+
+/**
+ * Role schema for storing user roles and their permissions.
+ *
+ * Roles contain:
+ * - A unique name (slug) for programmatic access
+ * - A display name for UI
+ * - An array of permission IDs
+ * - System flag for protecting default roles
+ */
+declare class Role {
+    /**
+     * Unique role identifier (slug)
+     * Used for programmatic access (e.g., 'admin', 'editor', 'authenticated')
+     */
+    name: string;
+    /**
+     * Human-readable display name
+     */
+    displayName: string;
+    /**
+     * Role description for admin UI
+     */
+    description?: string;
+    /**
+     * Array of permission IDs assigned to this role
+     * Use '*' for wildcard (all permissions)
+     * Use 'content.*' for category wildcard
+     */
+    permissions: string[];
+    /**
+     * Whether this is a system role (cannot be deleted)
+     * System roles: admin, authenticated, public
+     */
+    isSystem: boolean;
+    /**
+     * User count (computed, not stored)
+     * Populated when listing roles
+     */
+    userCount?: number;
+    /**
+     * When this role was created
+     */
+    createdAt: Date;
+    /**
+     * When this role was last updated
+     */
+    updatedAt?: Date;
+}
+
+declare class MetadataExtractorService {
+    extractControllerMetadata(wrapper: InstanceWrapper<object>): ControllerMetadata;
+    extractMethodMetadata(instance: object, method: string): MethodMetadata | null;
+    extractSchemaMetadata(wrapper: InstanceWrapper<unknown>): SchemaMetadata | null;
+    /**
+     * Build schema properties from Field metadata, Setting Field metadata, and legacy Prop/UI metadata.
+     * Priority: Field metadata > Setting Field metadata > legacy Prop/UI metadata
+     */
+    private buildProperties;
+    /**
+     * Get the type name from field metadata
+     */
+    private getTypeNameFromFieldMetadata;
+    /**
+     * Get type name from a type constructor or design type
+     */
+    private getTypeName;
+    /**
+     * Check if a field is an array type
+     */
+    private isArrayField;
+    /**
+     * Build UI options from field metadata
+     */
+    private buildUIFromFieldMetadata;
+    /**
+     * Convert select/enum options to UI format
+     */
+    private convertSelectOptions;
+    /**
+     * Get ref (relationship reference) from field metadata
+     */
+    private getRefFromFieldMetadata;
+    /**
+     * Get the type name from setting field metadata
+     */
+    private getTypeNameFromSettingFieldMetadata;
+    /**
+     * Build UI options from setting field metadata
+     */
+    private buildUIFromSettingFieldMetadata;
+    /**
+     * Convert setting select options to UI format
+     */
+    private convertSettingSelectOptions;
+    getParamDetails(controller: Function, methodName: string): {
+        arg: string;
+        type: string;
+        name: string;
+    }[];
+    private getValidationMetadata;
+}
+
+declare class ControllerDiscoveryService {
+    private readonly modulesContainer;
+    private readonly metadataExtractor;
+    constructor(modulesContainer: ModulesContainer, metadataExtractor: MetadataExtractorService);
+    discoverControllers(): ControllerMetadata[];
+}
+
+declare class MethodDiscoveryService {
+    private readonly modulesContainer;
+    private readonly metadataExtractor;
+    constructor(modulesContainer: ModulesContainer, metadataExtractor: MetadataExtractorService);
+    getMethodDetails(path: string, methodName: string, controllers: ControllerMetadata[]): MethodMetadata | {
+        error: string;
+    };
+}
+
+declare class SchemaDiscoveryService {
+    private readonly modulesContainer;
+    private readonly metadataExtractor;
+    constructor(modulesContainer: ModulesContainer, metadataExtractor: MetadataExtractorService);
+    discoverSchemas(): {
+        schemas: SchemaMetadata[];
+        settings: SchemaMetadata[];
+    };
+}
+
+declare class DiscoveryService implements OnModuleInit {
+    private readonly controllerDiscovery;
+    private readonly schemaDiscovery;
+    private readonly methodDiscovery;
+    private controllers;
+    private schemas;
+    private settingsSchemas;
+    constructor(controllerDiscovery: ControllerDiscoveryService, schemaDiscovery: SchemaDiscoveryService, methodDiscovery: MethodDiscoveryService);
+    onModuleInit(): void;
+    getDiscoveredSchemas(): string[];
+    getAllDiscoveredSchemas(): SchemaMetadata[];
+    getDiscoveredSchema(name: string): SchemaMetadata | {
+        error: string;
+    };
+    getDiscoveredSettingsSchemas(): string[];
+    getAllDiscoveredSettingsSchemas(): SchemaMetadata[];
+    getDiscoveredSettingsSchemaNames(): string[];
+    getDiscoveredSettingsSchema(name: string): SchemaMetadata | {
+        error: string;
+    };
+    getDiscoveredControllers(): string[];
+    getDiscoveredController(name: string): ControllerMetadata | {
+        error: string;
+    };
+    getMethodDetails(path: string, methodName: string): MethodMetadata | {
+        error: string;
+    };
+}
+
+interface RegisteredPlugin {
+    metadata: PluginMetadata;
+    instance: unknown;
+    frontendManifest?: PluginFrontendManifest;
+    config: PluginConfig;
+}
+declare class PluginRegistryService implements OnModuleInit {
+    private readonly modulesContainer;
+    private readonly logger;
+    private readonly pluginsConfig;
+    private plugins;
+    constructor(modulesContainer: ModulesContainer, logger: MagnetLogger, pluginsConfig?: PluginConfig[]);
+    onModuleInit(): void;
+    private discoverPlugins;
+    /**
+     * Get a registered plugin by name
+     */
+    getPlugin(name: string): RegisteredPlugin | undefined;
+    /**
+     * Get all registered plugins
+     */
+    getAllPlugins(): RegisteredPlugin[];
+    /**
+     * Get metadata for all plugins
+     */
+    getPluginMetadata(): PluginMetadata[];
+    /**
+     * Get frontend manifests for all plugins with bundle URLs
+     * Used by admin UI to dynamically load plugin frontends at runtime
+     */
+    getFrontendManifests(): EnrichedPluginManifest[];
+    /**
+     * Get full plugin info for API response
+     */
+    getPluginInfo(name: string): RegisteredPluginInfo | null;
+    /**
+     * Get all plugins info for API response
+     */
+    getAllPluginsInfo(): RegisteredPluginInfo[];
+}
+
+/**
+ * Permission schema for persisting discovered permissions.
+ *
+ * Permissions are auto-registered from:
+ * - Schema definitions (CRUD)
+ * - Controller methods (@RequirePermission)
+ * - Plugins
+ * - System definitions
+ *
+ * Used for validation when assigning permissions to roles.
+ */
+declare class Permission {
+    /**
+     * Unique permission identifier (e.g., 'content.cat.create', 'roles.find')
+     * This is the key used when assigning permissions to roles.
+     */
+    permissionId: string;
+    /**
+     * Human-readable name for the admin UI
+     */
+    name: string;
+    /**
+     * Description for the admin UI
+     */
+    description?: string;
+    /**
+     * Group for organization (e.g., 'Content', 'Users', 'Settings')
+     */
+    group?: string;
+    /**
+     * API identifier (e.g., 'api::posts', 'plugin::playground', 'system::users')
+     */
+    apiId?: string;
+    /**
+     * Source of this permission
+     */
+    source?: PermissionSource;
+    /**
+     * Controller name if discovered from controller
+     */
+    controller?: string;
+    /**
+     * Method name if discovered from controller
+     */
+    method?: string;
+    /**
+     * Plugin name if from plugin
+     */
+    plugin?: string;
+    /**
+     * Schema name if auto-generated from schema
+     */
+    schema?: string;
+    /**
+     * When this permission was first registered
+     */
+    createdAt: Date;
+    /**
+     * When this permission was last updated
+     */
+    updatedAt?: Date;
+}
+
+interface ValidatePermissionIdsResult {
+    valid: string[];
+    invalid: string[];
+}
+/**
+ * Service for persisting and validating permissions.
+ *
+ * Permissions are synced from PermissionDiscoveryService on startup
+ * and used to validate role permission assignments.
+ */
+declare class PermissionService {
+    private readonly permissionModel;
+    private readonly logger;
+    constructor(permissionModel: Model<Permission>, logger: MagnetLogger);
+    /**
+     * Upsert a single permission from a definition
+     */
+    upsertFromDefinition(def: PermissionDefinition): Promise<void>;
+    /**
+     * Batch upsert permissions from definitions
+     */
+    upsertMany(definitions: PermissionDefinition[]): Promise<void>;
+    /**
+     * Find a permission by ID
+     */
+    findById(permissionId: string): Promise<Permission | null>;
+    /**
+     * Get all registered permission IDs
+     */
+    findAllIds(): Promise<string[]>;
+    /**
+     * Validate that all permission IDs exist (in DB or can be matched by wildcard)
+     * Returns valid and invalid IDs.
+     */
+    validatePermissionIds(ids: string[], knownIds?: string[]): Promise<ValidatePermissionIdsResult>;
+    private definitionToPermissionData;
+}
+
+/**
+ * Service for discovering all permissions in the system.
+ *
+ * Permissions are discovered from:
+ * 1. Schema definitions - auto-generated CRUD permissions
+ * 2. Controller methods - @RequirePermission decorated methods
+ * 3. Plugins - permissions defined in plugin manifests
+ */
+declare class PermissionDiscoveryService implements OnModuleInit {
+    private readonly discoveryService;
+    private readonly modulesContainer;
+    private readonly pluginRegistry;
+    private readonly permissionService;
+    private permissions;
+    private initialized;
+    constructor(discoveryService: DiscoveryService, modulesContainer: ModulesContainer, pluginRegistry: PluginRegistryService, permissionService: PermissionService);
+    onModuleInit(): Promise<void>;
+    /**
+     * Discover all permissions from schemas, controllers, and plugins
+     */
+    private discoverPermissions;
+    /**
+     * Auto-generate CRUD permissions for each discovered schema
+     */
+    private discoverSchemaPermissions;
+    /**
+     * Discover @RequirePermission decorated methods from controllers
+     */
+    private discoverControllerPermissions;
+    /**
+     * Extract permissions from a controller's methods
+     */
+    private extractControllerPermissions;
+    /**
+     * Discover permissions from registered plugins
+     */
+    private discoverPluginPermissions;
+    /**
+     * Add system-level permissions
+     */
+    private discoverSystemPermissions;
+    /**
+     * Get all discovered permissions
+     */
+    getAll(): PermissionDefinition[];
+    /**
+     * Get a specific permission by ID
+     */
+    get(id: string): PermissionDefinition | undefined;
+    /**
+     * Check if a permission exists
+     */
+    has(id: string): boolean;
+    /**
+     * Get permissions grouped for UI display
+     */
+    getGrouped(): PermissionGroup[];
+    /**
+     * Get permissions categorized by type (for admin UI)
+     * - collectionTypes: schema-based (api::*), each schema = one accordion
+     * - controllers: from @RequirePermission, each controller = one accordion
+     * - plugins: plugin::*
+     * - system: system::*
+     */
+    getCategorized(): CategorizedPermissions;
+    /**
+     * Group controller permissions by controller (each = one accordion)
+     */
+    private groupByController;
+    /**
+     * Get permissions for a specific schema
+     */
+    getSchemaPermissions(schemaName: string): PermissionDefinition[];
+    /**
+     * Get permissions for a specific plugin
+     */
+    getPluginPermissions(pluginName: string): PermissionDefinition[];
+    /**
+     * Mark permissions as checked/unchecked based on role's permissions
+     */
+    markPermissions(groups: PermissionGroup[], rolePermissions: string[]): PermissionGroup[];
+    /**
+     * Check if a permission is enabled (including wildcard matching)
+     */
+    private isPermissionEnabled;
+    /**
+     * Get human-readable action label
+     */
+    private getActionLabel;
+    /**
+     * Format permission ID into a readable name
+     */
+    private formatPermissionName;
+}
+
+/**
+ * Service for managing roles and checking permissions
+ */
+declare class RoleService implements OnModuleInit {
+    private readonly roleModel;
+    private readonly permissionDiscovery;
+    private readonly permissionService;
+    private readonly eventService;
+    private readonly userService;
+    private readonly logger;
+    private permissionCache;
+    private cacheEnabled;
+    private cacheTTL;
+    constructor(roleModel: Model<Role>, permissionDiscovery: PermissionDiscoveryService, permissionService: PermissionService, eventService: EventService, userService: UserService, logger: MagnetLogger);
+    onModuleInit(): Promise<void>;
+    /**
+     * Ensure default system roles exist
+     */
+    private ensureDefaultRoles;
+    /**
+     * Get all roles
+     */
+    findAll(): Promise<Role[]>;
+    /**
+     * Get all roles with user counts
+     */
+    findAllWithCounts(): Promise<(Role & {
+        userCount: number;
+    })[]>;
+    /**
+     * Get a role by ID
+     */
+    findById(id: string): Promise<Role | null>;
+    /**
+     * Get a role by name
+     */
+    findByName(name: string): Promise<Role | null>;
+    /**
+     * Get a role with all permissions resolved
+     */
+    findByIdWithPermissions(id: string): Promise<RoleWithPermissions>;
+    /**
+     * Get a role by name with all permissions resolved
+     */
+    findByNameWithPermissions(name: string): Promise<RoleWithPermissions>;
+    /**
+     * Create a new role
+     */
+    create(dto: CreateRoleDto): Promise<Role>;
+    /**
+     * Update a role
+     */
+    update(id: string, dto: UpdateRoleDto): Promise<Role>;
+    /**
+     * Update role permissions
+     */
+    updatePermissions(id: string, permissions: string[]): Promise<Role>;
+    /**
+     * Delete a role (non-system roles only)
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Duplicate a role
+     */
+    duplicate(id: string, dto: DuplicateRoleDto): Promise<Role>;
+    /**
+     * Check if a user has a specific permission
+     */
+    hasPermission(userId: string, permission: string): Promise<boolean>;
+    /**
+     * Check if a role has a specific permission
+     */
+    roleHasPermission(roleName: string, permission: string): Promise<boolean>;
+    /**
+     * Check if a permission list includes a permission (with wildcard support)
+     */
+    checkPermission(rolePermissions: string[], permissionId: string): boolean;
+    /**
+     * Get all permissions a user has
+     */
+    getUserPermissions(userId: string): Promise<string[]>;
+    /**
+     * Assign a role to a user
+     */
+    assignRoleToUser(userId: string, roleName: string): Promise<void>;
+    /**
+     * Get all discovered permissions
+     */
+    getAllPermissions(): CategorizedPermissions;
+    /**
+     * Enable or disable permission caching
+     */
+    setCacheEnabled(enabled: boolean): void;
+    /**
+     * Set cache TTL
+     */
+    setCacheTTL(ttlMs: number): void;
+    /**
+     * Clear the permission cache
+     */
+    clearCache(): void;
+    /**
+     * Invalidate cache for a specific role
+     */
+    private invalidateRoleCache;
+    private getCachedPermission;
+    private setCachedPermission;
+    /**
+     * Resolve a role with all permissions marked
+     */
+    private resolveRolePermissions;
+    /**
+     * Get role ID (handles both string ID and _id from MongoDB)
+     */
+    private getRoleId;
+    /**
+     * Check if a role name is a system role
+     */
+    isSystemRole(roleName: string): boolean;
+}
+
+/**
+ * Guard that checks if the authenticated user has the required permission.
+ *
+ * Usage:
+ * ```typescript
+ * @Get()
+ * @UseGuards(DynamicAuthGuard, PermissionGuard)
+ * @RequirePermission({
+ *   id: 'content.posts.find',
+ *   name: 'List Posts',
+ *   description: 'View list of posts',
+ * })
+ * async findAll() { ... }
+ * ```
+ *
+ * Supports dynamic permission IDs with placeholders:
+ * ```typescript
+ * @RequirePermission({
+ *   id: 'content.{schema}.find',
+ *   name: 'Find',
+ * })
+ * async find(@Param('schema') schema: string) { ... }
+ * ```
+ */
+declare class PermissionGuard implements CanActivate {
+    private readonly reflector;
+    private readonly roleService;
+    private readonly logger;
+    constructor(reflector: Reflector, roleService: RoleService, logger: MagnetLogger);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    /**
+     * Get permission options from decorator or resolved permission
+     */
+    private getPermissionOptions;
+    /**
+     * Resolve dynamic permission placeholders
+     */
+    private resolvePermission;
+}
+
+export { AuthStrategyFactory as A, CreateUserDto as C, DiscoveryService as D, EventService as E, Hook as H, InjectPluginOptions as I, MagnetLogger as M, Plugin as P, RoleService as R, UserService as U, type ValidatePermissionIdsResult as V, type PluginDecoratorOptions as a, PermissionGuard as b, User as c, type PaginatedUserResult as d, PluginRegistryService as e, PermissionDiscoveryService as f, PermissionService as g, CreateRoleDto as h, DuplicateRoleDto as i, UpdateRoleDto as j, Role as k };