@k3-universe/react-kit 0.0.27 → 0.0.29

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

@@ -0,0 +1,393 @@
+import type { ReactNode } from 'react';
+
+// ============================================================================
+// Core Status & Session Types
+// ============================================================================
+
+export type AuthStatus =
+  | 'idle'
+  | 'loading'
+  | 'authenticated'
+  | 'unauthenticated'
+  | 'error';
+
+export type TokenType = 'bearer' | 'jwt' | 'custom';
+
+export type RefreshStrategy = 'auto' | 'manual' | 'sliding';
+
+export type AuthSession<
+  TUser = unknown,
+  TRole = string,
+  TPermission = string,
+> = {
+  user?: TUser | null;
+  accessToken?: string | null;
+  refreshToken?: string | null;
+  tokenType?: TokenType;
+  roles?: TRole[] | null;
+  permissions?: TPermission[] | null;
+  expiresAt?: number | null;
+  refreshExpiresAt?: number | null;
+  issuedAt?: number | null;
+  meta?: Record<string, unknown> | null;
+};
+
+// ============================================================================
+// Permission System Types
+// ============================================================================
+
+export type PermissionOperator = 'AND' | 'OR';
+
+export type PermissionPolicy<TPermission extends string = string> = {
+  operator?: PermissionOperator;
+  permissions: TPermission[];
+};
+
+export type PermissionRule<
+  TRole extends string = string,
+  TPermission extends string = string,
+> = {
+  roles?: TRole | TRole[];
+  permissions?: TPermission | TPermission[] | PermissionPolicy<TPermission>;
+  requireAll?: boolean;
+};
+
+export type PermissionHierarchy<TPermission extends string = string> = {
+  [key in TPermission]?: TPermission[];
+};
+
+export type RoleHierarchy<TRole extends string = string> = {
+  [key in TRole]?: TRole[];
+};
+
+// ============================================================================
+// State Types
+// ============================================================================
+
+export type AuthAdapterState<TSession, TUser, TRole, TPermission> = {
+  status: AuthStatus;
+  session: TSession | null;
+  user: TUser | null;
+  roles: TRole[];
+  permissions: TPermission[];
+  error?: unknown;
+  lastRefresh?: number;
+  tokenExpiresIn?: number;
+};
+
+export type AuthAdapterSubscriber<TSession, TUser, TRole, TPermission> = (
+  state: AuthAdapterState<TSession, TUser, TRole, TPermission>,
+) => void;
+
+// ============================================================================
+// Storage Types
+// ============================================================================
+
+export type AuthStorage<TSession> = {
+  get: () => Promise<TSession | null> | TSession | null;
+  set: (value: TSession | null) => Promise<void> | void;
+  clear: () => Promise<void> | void;
+};
+
+export type StorageType = 'local' | 'session' | 'cookie' | 'memory';
+
+export type StorageOptions = {
+  key?: string;
+  encrypt?: boolean;
+  encryptionKey?: string;
+  storage?: StorageType;
+  cookieOptions?: {
+    domain?: string;
+    path?: string;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    maxAge?: number;
+  };
+};
+
+// ============================================================================
+// Middleware Types
+// ============================================================================
+
+export type AuthMiddleware<
+  TSession = unknown,
+  TUser = unknown,
+  TRole extends string = string,
+  TPermission extends string = string,
+> = {
+  onBeforeLogin?: (credentials: unknown) => Promise<void> | void;
+  onAfterLogin?: (
+    state: AuthAdapterState<TSession, TUser, TRole, TPermission>,
+  ) => Promise<void> | void;
+  onBeforeLogout?: () => Promise<void> | void;
+  onAfterLogout?: () => Promise<void> | void;
+  onRefresh?: (
+    state: AuthAdapterState<TSession, TUser, TRole, TPermission>,
+  ) => Promise<void> | void;
+  onError?: (error: unknown) => Promise<void> | void;
+  onSessionExpired?: () => Promise<void> | void;
+};
+
+// ============================================================================
+// Token Management Types
+// ============================================================================
+
+export type TokenManager = {
+  isExpired: (expiresAt?: number | null) => boolean;
+  shouldRefresh: (expiresAt?: number | null, threshold?: number) => boolean;
+  getTimeUntilExpiry: (expiresAt?: number | null) => number;
+  scheduleRefresh?: (
+    callback: () => void,
+    expiresAt?: number | null,
+  ) => () => void;
+};
+
+// ============================================================================
+// Adapter Configuration Types
+// ============================================================================
+
+export type AuthAdapterConfig<
+  TUser = unknown,
+  TRole extends string = string,
+  TPermission extends string = string,
+  TSession extends AuthSession<TUser, TRole, TPermission> = AuthSession<
+    TUser,
+    TRole,
+    TPermission
+  >,
+  TCredentials = unknown,
+> = {
+  storage?: AuthStorage<TSession>;
+  loadSession?: () => Promise<TSession | null>;
+  login?: (credentials: TCredentials) => Promise<TSession>;
+  logout?: (session: TSession | null) => Promise<void> | void;
+  refresh?: (session: TSession) => Promise<TSession>;
+  resolveUser?: (session: TSession | null) => TUser | null;
+  resolveRoles?: (session: TSession | null) => TRole[];
+  resolvePermissions?: (session: TSession | null) => TPermission[];
+  shouldRefresh?: (session: TSession) => boolean;
+  onStateChange?: (
+    state: AuthAdapterState<TSession, TUser, TRole, TPermission>,
+  ) => void;
+
+  // Enhanced features
+  refreshStrategy?: RefreshStrategy;
+  refreshThreshold?: number; // seconds before expiry to trigger refresh
+  autoRefresh?: boolean;
+  permissionHierarchy?: PermissionHierarchy<TPermission>;
+  roleHierarchy?: RoleHierarchy<TRole>;
+  middleware?: AuthMiddleware<TSession, TUser, TRole, TPermission>[];
+  tokenManager?: TokenManager;
+  retryConfig?: {
+    maxRetries?: number;
+    retryDelay?: number;
+    retryOn?: (error: unknown) => boolean;
+  };
+};
+
+// ============================================================================
+// Adapter API Types
+// ============================================================================
+
+export type AuthAdapter<
+  TUser = unknown,
+  TRole extends string = string,
+  TPermission extends string = string,
+  TSession extends AuthSession<TUser, TRole, TPermission> = AuthSession<
+    TUser,
+    TRole,
+    TPermission
+  >,
+  TCredentials = unknown,
+> = {
+  getState: () => AuthAdapterState<TSession, TUser, TRole, TPermission>;
+  subscribe: (
+    listener: AuthAdapterSubscriber<TSession, TUser, TRole, TPermission>,
+  ) => () => void;
+  sync: () => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+  login?: (
+    credentials: TCredentials,
+  ) => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+  logout: () => Promise<void>;
+  refresh: () => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+  setSession: (
+    session: TSession | null,
+  ) => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+  hasRole: (
+    target: TRole | TRole[],
+    options?: { requireAll?: boolean },
+  ) => boolean;
+  hasPermission: (
+    target: TPermission | TPermission[] | PermissionPolicy<TPermission>,
+    options?: { requireAll?: boolean },
+  ) => boolean;
+  can: (rule: PermissionRule<TRole, TPermission>) => boolean;
+
+  // Token management
+  getToken: () => string | null;
+  isTokenExpired: () => boolean;
+  getTimeUntilExpiry: () => number;
+  scheduleAutoRefresh?: () => () => void;
+};
+
+// ============================================================================
+// Context Types
+// ============================================================================
+
+export type AuthContextValue<
+  TUser = unknown,
+  TRole extends string = string,
+  TPermission extends string = string,
+  TSession extends AuthSession<TUser, TRole, TPermission> = AuthSession<
+    TUser,
+    TRole,
+    TPermission
+  >,
+  TCredentials = unknown,
+> = {
+  state: AuthAdapterState<TSession, TUser, TRole, TPermission>;
+  status: AuthStatus;
+  session: TSession | null;
+  user: TUser | null;
+  roles: TRole[];
+  permissions: TPermission[];
+  error?: unknown;
+
+  // Actions
+  login?: (
+    credentials: TCredentials,
+  ) => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+  logout: () => Promise<void>;
+  refresh: () => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+  setSession: (
+    session: TSession | null,
+  ) => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+
+  // Permission checks
+  hasRole: (
+    target: TRole | TRole[],
+    options?: { requireAll?: boolean },
+  ) => boolean;
+  hasPermission: (
+    target: TPermission | TPermission[] | PermissionPolicy<TPermission>,
+    options?: { requireAll?: boolean },
+  ) => boolean;
+  can: (rule: PermissionRule<TRole, TPermission>) => boolean;
+
+  // Token management
+  getToken: () => string | null;
+  isTokenExpired: () => boolean;
+  getTimeUntilExpiry: () => number;
+};
+
+// ============================================================================
+// Component Props Types
+// ============================================================================
+
+export type RequireAuthProps<
+  TRole extends string = string,
+  TPermission extends string = string,
+> = {
+  children: ReactNode;
+  fallback?: ReactNode;
+  loadingFallback?: ReactNode;
+  roles?: TRole | TRole[];
+  permissions?: TPermission | TPermission[] | PermissionPolicy<TPermission>;
+  requireAll?: boolean;
+};
+
+export type CanProps<
+  TRole extends string = string,
+  TPermission extends string = string,
+> = {
+  children: ReactNode;
+  fallback?: ReactNode;
+  roles?: TRole | TRole[];
+  permissions?: TPermission | TPermission[] | PermissionPolicy<TPermission>;
+  requireAll?: boolean;
+};
+
+export type WithPermissionOptions<
+  TRole extends string = string,
+  TPermission extends string = string,
+> = {
+  roles?: TRole | TRole[];
+  permissions?: TPermission | TPermission[] | PermissionPolicy<TPermission>;
+  requireAll?: boolean;
+};
+
+// ============================================================================
+// Client Adapter Types (GraphQL/REST)
+// ============================================================================
+
+export type GraphQLAuthClient<TSession = unknown, TCredentials = unknown> = {
+  login: (credentials: TCredentials) => Promise<TSession>;
+  logout?: () => Promise<void>;
+  refresh?: (refreshToken: string) => Promise<TSession>;
+  getCurrentUser?: () => Promise<TSession>;
+};
+
+export type RESTAuthClient<TSession = unknown, TCredentials = unknown> = {
+  login: (credentials: TCredentials) => Promise<TSession>;
+  logout?: () => Promise<void>;
+  refresh?: (refreshToken: string) => Promise<TSession>;
+  getCurrentUser?: () => Promise<TSession>;
+};
+
+export type ClientAdapter<TSession = unknown, TCredentials = unknown> =
+  | GraphQLAuthClient<TSession, TCredentials>
+  | RESTAuthClient<TSession, TCredentials>;
+
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+export type InferSession<T> = T extends AuthAdapter<
+  infer _User,
+  infer _Role extends string,
+  infer _Permission extends string,
+  infer TSession,
+  infer _Credentials
+>
+  ? TSession
+  : never;
+
+export type InferUser<T> = T extends AuthAdapter<
+  infer TUser,
+  infer _Role extends string,
+  infer _Permission extends string,
+  infer _Session,
+  infer _Credentials
+>
+  ? TUser
+  : never;
+
+export type InferRole<T> = T extends AuthAdapter<
+  infer _User,
+  infer TRole extends string,
+  infer _Permission extends string,
+  infer _Session,
+  infer _Credentials
+>
+  ? TRole
+  : never;
+
+export type InferPermission<T> = T extends AuthAdapter<
+  infer _User,
+  infer _Role extends string,
+  infer TPermission extends string,
+  infer _Session,
+  infer _Credentials
+>
+  ? TPermission
+  : never;
+
+export type InferCredentials<T> = T extends AuthAdapter<
+  infer _User,
+  infer _Role extends string,
+  infer _Permission extends string,
+  infer _Session,
+  infer TCredentials
+>
+  ? TCredentials
+  : never;