@k3-universe/react-kit 0.0.28 → 0.0.29

package/src/kit/builder/auth/hooks.ts

@@ -0,0 +1,237 @@
+import type {
+  AuthSession,
+  PermissionPolicy,
+  PermissionRule,
+  WithPermissionOptions,
+} from './types';
+import { useAuthContext } from './AuthProvider';
+
+// ============================================================================
+// Core Hooks
+// ============================================================================
+
+/**
+ * Hook to access the entire auth context
+ */
+export function useAuth() {
+  return useAuthContext();
+}
+
+/**
+ * Hook to get the current auth status
+ */
+export function useAuthStatus() {
+  const { status } = useAuthContext();
+  return status;
+}
+
+/**
+ * Hook to check if user is authenticated
+ */
+export function useIsAuthenticated() {
+  const { status } = useAuthContext();
+  return status === 'authenticated';
+}
+
+/**
+ * Hook to get the current session
+ */
+export function useAuthSession<TSession extends AuthSession>() {
+  const { session } = useAuthContext();
+  return session as TSession | null;
+}
+
+/**
+ * Hook to get the current user
+ */
+export function useAuthUser<TUser>() {
+  const { user } = useAuthContext();
+  return user as TUser | null;
+}
+
+/**
+ * Hook to get user roles
+ */
+export function useAuthRoles<TRole extends string = string>() {
+  const { roles } = useAuthContext();
+  return roles as TRole[];
+}
+
+/**
+ * Hook to get user permissions
+ */
+export function useAuthPermissions<TPermission extends string = string>() {
+  const { permissions } = useAuthContext();
+  return permissions as TPermission[];
+}
+
+/**
+ * Hook to get authentication error
+ */
+export function useAuthError() {
+  const { error } = useAuthContext();
+  return error;
+}
+
+// ============================================================================
+// Permission Hooks
+// ============================================================================
+
+/**
+ * Hook to check if user has specific permission(s)
+ * Supports permission policies with AND/OR operators
+ *
+ * @example
+ * ```tsx
+ * // Check single permission
+ * const canEdit = usePermission('post:edit');
+ *
+ * // Check multiple permissions (all required by default)
+ * const canManage = usePermission(['post:edit', 'post:delete']);
+ *
+ * // Check multiple permissions (any one required)
+ * const canModify = usePermission(['post:edit', 'post:delete'], { requireAll: false });
+ *
+ * // Check with policy
+ * const canAccess = usePermission({
+ *   operator: 'OR',
+ *   permissions: ['admin:access', 'moderator:access']
+ * });
+ * ```
+ */
+export function usePermission<TPermission extends string = string>(
+  permission: TPermission | TPermission[] | PermissionPolicy<TPermission>,
+  options?: { requireAll?: boolean },
+) {
+  const { hasPermission } = useAuthContext();
+  return hasPermission(permission, options);
+}
+
+/**
+ * Hook to check if user has specific role(s)
+ *
+ * @example
+ * ```tsx
+ * // Check single role
+ * const isAdmin = useRole('admin');
+ *
+ * // Check multiple roles (all required by default)
+ * const isSuperAdmin = useRole(['admin', 'super']);
+ *
+ * // Check multiple roles (any one required)
+ * const isStaff = useRole(['admin', 'moderator'], { requireAll: false });
+ * ```
+ */
+export function useRole<TRole extends string = string>(
+  roles: TRole | TRole[],
+  options?: { requireAll?: boolean },
+) {
+  const { hasRole } = useAuthContext();
+  return hasRole(roles, options);
+}
+
+/**
+ * Hook to check complex permission rules
+ * Combines role and permission checks with flexible logic
+ *
+ * @example
+ * ```tsx
+ * // Check if user has admin role AND edit permission
+ * const canAdminEdit = useCan({
+ *   roles: 'admin',
+ *   permissions: 'post:edit',
+ *   requireAll: true
+ * });
+ *
+ * // Check if user has admin role OR edit permission
+ * const canAccess = useCan({
+ *   roles: 'admin',
+ *   permissions: 'post:edit',
+ *   requireAll: false
+ * });
+ *
+ * // Complex policy
+ * const canManage = useCan({
+ *   roles: ['admin', 'moderator'],
+ *   permissions: {
+ *     operator: 'OR',
+ *     permissions: ['post:edit', 'post:delete']
+ *   }
+ * });
+ * ```
+ */
+export function useCan<
+  TRole extends string = string,
+  TPermission extends string = string,
+>(
+  rule:
+    | WithPermissionOptions<TRole, TPermission>
+    | PermissionRule<TRole, TPermission>,
+) {
+  const { can } = useAuthContext();
+  return can(rule as PermissionRule<TRole, TPermission>);
+}
+
+// ============================================================================
+// Token Hooks
+// ============================================================================
+
+/**
+ * Hook to get the current auth token
+ */
+export function useAuthToken() {
+  const { getToken } = useAuthContext();
+  return getToken();
+}
+
+/**
+ * Hook to check if token is expired
+ */
+export function useIsTokenExpired() {
+  const { isTokenExpired } = useAuthContext();
+  return isTokenExpired();
+}
+
+/**
+ * Hook to get time until token expiry in milliseconds
+ */
+export function useTimeUntilExpiry() {
+  const { getTimeUntilExpiry } = useAuthContext();
+  return getTimeUntilExpiry();
+}
+
+// ============================================================================
+// Action Hooks
+// ============================================================================
+
+/**
+ * Hook to get the login function
+ */
+export function useLogin<TCredentials = unknown>() {
+  const { login } = useAuthContext();
+  return login as ((credentials: TCredentials) => Promise<unknown>) | undefined;
+}
+
+/**
+ * Hook to get the logout function
+ */
+export function useLogout() {
+  const { logout } = useAuthContext();
+  return logout;
+}
+
+/**
+ * Hook to get the refresh function
+ */
+export function useRefresh() {
+  const { refresh } = useAuthContext();
+  return refresh;
+}
+
+/**
+ * Hook to get the setSession function
+ */
+export function useSetSession<TSession extends AuthSession>() {
+  const { setSession } = useAuthContext();
+  return setSession as (session: TSession | null) => Promise<unknown>;
+}

package/src/kit/builder/auth/index.ts

@@ -0,0 +1,134 @@
+// ============================================================================
+// Core
+// ============================================================================
+
+export { createAuthAdapter } from './adapter';
+export { AuthProvider, useAuthContext } from './AuthProvider';
+
+// ============================================================================
+// Storage
+// ============================================================================
+
+export {
+  createStorage,
+  createMemoryStorage,
+  createBrowserStorage,
+  createCookieStorage,
+} from './storage';
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+export { createTokenManager } from './token-manager';
+export {
+  expandPermissions,
+  expandRoles,
+  checkPermissions,
+  checkRoles,
+  evaluatePermissionRule,
+} from './permission-checker';
+
+// ============================================================================
+// Client Adapters
+// ============================================================================
+
+export {
+  createGraphQLAuthAdapter,
+  createRESTAuthAdapter,
+  createAxiosAuthInterceptor,
+  createAuthFetch,
+  createApolloAuthLink,
+} from './client-adapters';
+
+export type {
+  GraphQLClientAdapterOptions,
+  RESTClientAdapterOptions,
+} from './client-adapters';
+
+// ============================================================================
+// Hooks
+// ============================================================================
+
+export {
+  useAuth,
+  useAuthStatus,
+  useIsAuthenticated,
+  useAuthSession,
+  useAuthUser,
+  useAuthRoles,
+  useAuthPermissions,
+  useAuthError,
+  usePermission,
+  useRole,
+  useCan,
+  useAuthToken,
+  useIsTokenExpired,
+  useTimeUntilExpiry,
+  useLogin,
+  useLogout,
+  useRefresh,
+  useSetSession,
+} from './hooks';
+
+// ============================================================================
+// Components
+// ============================================================================
+
+export {
+  RequireAuth,
+  Can,
+  withPermission,
+  ShowWhenAuthenticated,
+  ShowWhenUnauthenticated,
+  ShowWhenLoading,
+  ShowWhenError,
+} from './components';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type {
+  // Core types
+  AuthStatus,
+  TokenType,
+  RefreshStrategy,
+  AuthSession,
+  // Permission types
+  PermissionOperator,
+  PermissionPolicy,
+  PermissionRule,
+  PermissionHierarchy,
+  RoleHierarchy,
+  // State types
+  AuthAdapterState,
+  AuthAdapterSubscriber,
+  // Storage types
+  AuthStorage,
+  StorageType,
+  StorageOptions,
+  // Middleware types
+  AuthMiddleware,
+  // Token manager types
+  TokenManager,
+  // Adapter types
+  AuthAdapterConfig,
+  AuthAdapter,
+  // Context types
+  AuthContextValue,
+  // Component prop types
+  RequireAuthProps,
+  CanProps,
+  WithPermissionOptions,
+  // Client adapter types
+  GraphQLAuthClient,
+  RESTAuthClient,
+  ClientAdapter,
+  // Utility types
+  InferSession,
+  InferUser,
+  InferRole,
+  InferPermission,
+  InferCredentials,
+} from './types';

package/src/kit/builder/auth/permission-checker.ts

@@ -0,0 +1,150 @@
+import type {
+  PermissionHierarchy,
+  PermissionPolicy,
+  PermissionRule,
+  RoleHierarchy,
+} from './types';
+
+/**
+ * Expands permissions based on hierarchy
+ * e.g., if user has 'admin' and hierarchy defines admin: ['read', 'write'],
+ * user effectively has ['admin', 'read', 'write']
+ */
+export function expandPermissions<T extends string>(
+  permissions: T[],
+  hierarchy?: PermissionHierarchy<T>,
+): T[] {
+  if (!hierarchy) return permissions;
+
+  const expanded = new Set<T>(permissions);
+  const queue = [...permissions];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) continue;
+    const children = hierarchy[current];
+
+    if (children) {
+      for (const child of children) {
+        if (!expanded.has(child)) {
+          expanded.add(child);
+          queue.push(child);
+        }
+      }
+    }
+  }
+
+  return Array.from(expanded);
+}
+
+/**
+ * Expands roles based on hierarchy
+ * e.g., if user has 'admin' and hierarchy defines admin: ['moderator', 'user'],
+ * user effectively has ['admin', 'moderator', 'user']
+ */
+export function expandRoles<T extends string>(
+  roles: T[],
+  hierarchy?: RoleHierarchy<T>,
+): T[] {
+  if (!hierarchy) return roles;
+
+  const expanded = new Set<T>(roles);
+  const queue = [...roles];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) continue;
+    const children = hierarchy[current];
+
+    if (children) {
+      for (const child of children) {
+        if (!expanded.has(child)) {
+          expanded.add(child);
+          queue.push(child);
+        }
+      }
+    }
+  }
+
+  return Array.from(expanded);
+}
+
+/**
+ * Checks if target permissions match against user permissions
+ * Supports both array of permissions and permission policies (AND/OR operations)
+ */
+export function checkPermissions<T extends string>(
+  userPermissions: T[],
+  target: T | T[] | PermissionPolicy<T>,
+  options?: { requireAll?: boolean },
+): boolean {
+  // Handle permission policy (with AND/OR operator)
+  if (typeof target === 'object' && 'permissions' in target) {
+    const policy = target as PermissionPolicy<T>;
+    const operator = policy.operator ?? 'AND';
+
+    if (operator === 'AND') {
+      return policy.permissions.every((p) => userPermissions.includes(p));
+    } else {
+      return policy.permissions.some((p) => userPermissions.includes(p));
+    }
+  }
+
+  // Handle simple string or array
+  const targets = Array.isArray(target) ? target : [target];
+  const requireAll = options?.requireAll ?? true;
+
+  if (targets.length === 0) return true;
+
+  return requireAll
+    ? targets.every((p) => userPermissions.includes(p))
+    : targets.some((p) => userPermissions.includes(p));
+}
+
+/**
+ * Checks if target roles match against user roles
+ */
+export function checkRoles<T extends string>(
+  userRoles: T[],
+  target: T | T[],
+  options?: { requireAll?: boolean },
+): boolean {
+  const targets = Array.isArray(target) ? target : [target];
+  const requireAll = options?.requireAll ?? true;
+
+  if (targets.length === 0) return true;
+
+  return requireAll
+    ? targets.every((r) => userRoles.includes(r))
+    : targets.some((r) => userRoles.includes(r));
+}
+
+/**
+ * Evaluates a permission rule (combination of roles and permissions)
+ */
+export function evaluatePermissionRule<
+  TRole extends string = string,
+  TPermission extends string = string,
+>(
+  userRoles: TRole[],
+  userPermissions: TPermission[],
+  rule: PermissionRule<TRole, TPermission>,
+): boolean {
+  if (!rule.roles && !rule.permissions) {
+    return true;
+  }
+
+  const requireAll = rule.requireAll ?? true;
+
+  const roleAllowed = rule.roles
+    ? checkRoles(userRoles, rule.roles, { requireAll })
+    : true;
+
+  const permissionAllowed = rule.permissions
+    ? checkPermissions(userPermissions, rule.permissions, { requireAll })
+    : true;
+
+  return requireAll
+    ? roleAllowed && permissionAllowed
+    : roleAllowed || permissionAllowed;
+}