@frank-auth/react
Version:
Flexible and customizable React UI components for Frank Authentication
250 lines (249 loc) • 8.43 kB
TypeScript
'use client';
import { UserPermissionAssignment, UserRoleAssignment } from '@frank-auth/client';
import { AuthError, PermissionContext } from '../provider/types';
export interface UsePermissionsReturn {
permissions: string[];
roles: string[];
roleAssignments: UserRoleAssignment[];
permissionAssignments: UserPermissionAssignment[];
isLoaded: boolean;
isLoading: boolean;
error: AuthError | null;
hasPermission: (permission: string, context?: PermissionContext) => boolean;
hasRole: (role: string, context?: PermissionContext) => boolean;
hasAnyPermission: (permissions: string[], context?: PermissionContext) => boolean;
hasAllPermissions: (permissions: string[], context?: PermissionContext) => boolean;
can: (action: string, resource: string, context?: PermissionContext) => boolean;
canInOrganization: (permission: string, organizationId?: string) => boolean;
canInApplication: (permission: string, applicationId: string) => boolean;
hasSystemPermission: (permission: string) => boolean;
isSystemAdmin: boolean;
isOrganizationOwner: (organizationId?: string) => boolean;
isOrganizationAdmin: (organizationId?: string) => boolean;
isOrganizationMember: (organizationId?: string) => boolean;
refreshPermissions: () => Promise<void>;
requirePermission: (permission: string, context?: PermissionContext) => void;
requireRole: (role: string, context?: PermissionContext) => void;
requireAnyPermission: (permissions: string[], context?: PermissionContext) => void;
requireAllPermissions: (permissions: string[], context?: PermissionContext) => void;
currentContext: PermissionContext;
setContext: (context: PermissionContext) => void;
}
export declare const PERMISSION_ACTIONS: {
readonly CREATE: "create";
readonly READ: "read";
readonly UPDATE: "update";
readonly DELETE: "delete";
readonly INVITE: "invite";
readonly REMOVE: "remove";
readonly SUSPEND: "suspend";
readonly ACTIVATE: "activate";
readonly MANAGE: "manage";
readonly CONFIGURE: "configure";
readonly AUDIT: "audit";
readonly TRANSFER: "transfer";
readonly EXPORT: "export";
readonly IMPORT: "import";
};
export declare const PERMISSION_RESOURCES: {
readonly USER: "user";
readonly USER_PROFILE: "user:profile";
readonly USER_SESSION: "user:session";
readonly USER_MFA: "user:mfa";
readonly ORGANIZATION: "organization";
readonly ORGANIZATION_SETTINGS: "organization:settings";
readonly ORGANIZATION_MEMBERS: "organization:members";
readonly ORGANIZATION_INVITATIONS: "organization:invitations";
readonly ORGANIZATION_BILLING: "organization:billing";
readonly ORGANIZATION_AUDIT: "organization:audit";
readonly APPLICATION: "application";
readonly APPLICATION_SETTINGS: "application:settings";
readonly APPLICATION_USERS: "application:users";
readonly APPLICATION_SESSIONS: "application:sessions";
readonly SYSTEM: "system";
readonly SYSTEM_USERS: "system:users";
readonly SYSTEM_ORGANIZATIONS: "system:organizations";
readonly SYSTEM_SETTINGS: "system:settings";
readonly SYSTEM_BILLING: "system:billing";
readonly SYSTEM_AUDIT: "system:audit";
};
export declare const SYSTEM_ROLES: {
readonly SUPER_ADMIN: "system:super_admin";
readonly ADMIN: "system:admin";
readonly SUPPORT: "system:support";
};
export declare const ORGANIZATION_ROLES: {
readonly OWNER: "organization:owner";
readonly ADMIN: "organization:admin";
readonly MEMBER: "organization:member";
readonly BILLING: "organization:billing";
readonly SUPPORT: "organization:support";
};
/**
* Comprehensive permissions hook for role-based access control
*
* @example Basic permission checking
* ```tsx
* import { usePermissions } from '@frank-auth/react';
*
* function UserManagement() {
* const {
* hasPermission,
* canInOrganization,
* isOrganizationAdmin,
* requirePermission
* } = usePermissions();
*
* // Simple permission check
* if (!hasPermission('organization:members:manage')) {
* return <div>Access denied</div>;
* }
*
* // Organization-specific check
* const canManageMembers = canInOrganization('members:manage');
*
* // Role-based check
* const isAdmin = isOrganizationAdmin();
*
* const handleDeleteUser = () => {
* // Throws if permission not granted
* requirePermission('organization:members:delete');
* // Delete user logic...
* };
*
* return (
* <div>
* {canManageMembers && (
* <button onClick={handleDeleteUser}>Delete User</button>
* )}
* {isAdmin && (
* <button>Admin Actions</button>
* )}
* </div>
* );
* }
* ```
*
* @example Context-aware permissions
* ```tsx
* function MultiContextComponent() {
* const {
* can,
* hasSystemPermission,
* canInApplication,
* setContext
* } = usePermissions();
*
* // Action-resource based checking
* const canCreateUsers = can('create', 'user');
* const canDeleteOrg = can('delete', 'organization');
*
* // System-level permissions
* const canManageSystem = hasSystemPermission('system:manage');
*
* // Application-specific permissions
* const canConfigureApp = canInApplication('configure', 'app_123');
*
* // Switch context
* const switchToOrgContext = () => {
* setContext({
* type: 'organization',
* organizationId: 'org_456'
* });
* };
*
* return (
* <div>
* {canCreateUsers && <button>Create User</button>}
* {canDeleteOrg && <button>Delete Organization</button>}
* {canManageSystem && <button>System Settings</button>}
* {canConfigureApp && <button>App Configuration</button>}
* <button onClick={switchToOrgContext}>Switch Context</button>
* </div>
* );
* }
* ```
*
* @example Permission guards
* ```tsx
* function PermissionGuardExample() {
* const { hasAnyPermission, hasAllPermissions } = usePermissions();
*
* // User needs at least one of these permissions
* const canAccess = hasAnyPermission([
* 'organization:read',
* 'organization:members:read'
* ]);
*
* // User needs all of these permissions
* const canFullyManage = hasAllPermissions([
* 'organization:manage',
* 'organization:members:manage',
* 'organization:billing:manage'
* ]);
*
* if (!canAccess) {
* return <div>You don't have access to this section</div>;
* }
*
* return (
* <div>
* <h1>Organization Dashboard</h1>
* {canFullyManage && (
* <div>Full management controls available</div>
* )}
* </div>
* );
* }
* ```
*/
export declare function usePermissions(): UsePermissionsReturn;
/**
* Hook for organization-specific permissions
*/
export declare function useOrganizationPermissions(organizationId?: string): {
organizationId: any;
isOwner: boolean;
isAdmin: boolean;
isMember: boolean;
canManageMembers: boolean;
canInviteMembers: boolean;
canRemoveMembers: boolean;
canManageSettings: boolean;
canManageBilling: boolean;
canViewAudit: boolean;
canDeleteOrganization: boolean;
hasOrganizationRole: (role: string) => boolean;
};
/**
* Hook for system-level permissions
*/
export declare function useSystemPermissions(): {
canAccessSystem: boolean;
isSystemAdmin: boolean;
canManageUsers: boolean;
canManageOrganizations: boolean;
canManageSystem: boolean;
canViewSystemAudit: boolean;
canManageBilling: boolean;
hasSystemRole: (role: string) => boolean;
isSuperAdmin: boolean;
isSupport: boolean;
};
/**
* Hook for permission-based conditional rendering
*/
export declare function usePermissionGuard(): {
PermissionGuard: ({ permission, role, anyPermissions, allPermissions, context, fallback, children, }: {
permission?: string;
role?: string;
anyPermissions?: string[];
allPermissions?: string[];
context?: PermissionContext;
fallback?: React.ReactNode;
children: React.ReactNode;
}) => import("react/jsx-runtime").JSX.Element;
requirePermission: (permission: string, context?: PermissionContext) => void;
requireRole: (role: string, context?: PermissionContext) => void;
};
//# sourceMappingURL=use-permissions.d.ts.map