@k3-universe/react-kit 0.0.28 → 0.0.30

package/src/kit/builder/auth/utils/client-adapters/urql-exchange.ts

@@ -0,0 +1,76 @@
+export function createUrqlAuthExchange(
+  getToken: () => string | null,
+  options?: {
+    tokenType?: string
+    refreshToken?: () => Promise<void>
+    onTokenExpired?: () => void
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    willAuthError?: (params: { authState: any; operation: any }) => boolean
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    didAuthError?: (params: { error: any; operation: any }) => boolean
+  },
+) {
+  const tokenType = options?.tokenType ?? 'Bearer'
+
+  // Avoid direct dependency on @urql/exchange-auth. Return a factory that accepts it.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (authExchange: any) =>
+    authExchange({
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      addAuthToOperation: ({ authState, operation }: any) => {
+        const token = authState?.token ?? getToken()
+        if (!token) return operation
+
+        const fetchOptions =
+          typeof operation.context.fetchOptions === 'function'
+            ? operation.context.fetchOptions()
+            : operation.context.fetchOptions || {}
+
+        return {
+          ...operation,
+          context: {
+            ...operation.context,
+            fetchOptions: {
+              ...fetchOptions,
+              headers: {
+                ...fetchOptions.headers,
+                Authorization: `${tokenType} ${token}`,
+              },
+            },
+          },
+        }
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      getAuth: async ({ authState }: any) => {
+        if (!authState) {
+          const token = getToken()
+          if (token) return { token }
+          return null
+        }
+
+        if (options?.refreshToken) {
+          try {
+            await options.refreshToken()
+            const token = getToken()
+            if (token) return { token }
+          } catch (_e) {
+            options.onTokenExpired?.()
+            return null
+          }
+        }
+        return null
+      },
+      willAuthError: options?.willAuthError,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      didAuthError: (params: { error: any; operation: any }) => {
+        if (options?.didAuthError) return options.didAuthError(params)
+        const { error } = params
+        return (
+          error?.graphQLErrors?.some(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (e: any) => e.extensions?.code === 'UNAUTHENTICATED',
+          ) || error?.response?.status === 401
+        )
+      },
+    })
+}

package/src/kit/builder/auth/utils/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;
+}

package/src/kit/builder/auth/utils/storage/browser.ts

@@ -0,0 +1,99 @@
+import type { AuthStorage } from '../../types'
+import { isBrowser } from './env'
+import { createMemoryStorage } from './memory'
+import { SimpleEncryption } from './encryption'
+
+export type BrowserStorageOptions<T> = {
+  key: string
+  serialize?: (value: T | null) => Promise<string | null> | string | null
+  deserialize?: (value: string | null) => Promise<T | null> | T | null
+  storage?: Storage
+  encrypt?: boolean
+  encryptionKey?: string
+}
+
+export const createBrowserStorage = <T>(
+  options: BrowserStorageOptions<T>,
+): AuthStorage<T> => {
+  const fallback = createMemoryStorage<T>()
+  const targetStorage =
+    options.storage ?? (isBrowser ? window.localStorage : undefined)
+
+  const encryption =
+    options.encrypt && options.encryptionKey
+      ? new SimpleEncryption(options.encryptionKey)
+      : null
+
+  const defaultSerialize = async (value: T | null): Promise<string | null> => {
+    if (value === null) return null
+    const json = JSON.stringify(value)
+    return encryption ? await encryption.encrypt(json) : json
+  }
+
+  const defaultDeserialize = async (
+    value: string | null,
+  ): Promise<T | null> => {
+    if (!value) return null
+    try {
+      const decrypted = encryption ? await encryption.decrypt(value) : value
+      return JSON.parse(decrypted) as T
+    } catch {
+      return null
+    }
+  }
+
+  const serialize = options.serialize
+    ? async (value: T | null) => {
+        const result = await options.serialize?.(value)
+        return result ?? null
+      }
+    : defaultSerialize
+
+  const deserialize = options.deserialize
+    ? async (value: string | null) => {
+        const result = await options.deserialize?.(value)
+        return result ?? null
+      }
+    : defaultDeserialize
+
+  if (!targetStorage) {
+    return fallback
+  }
+
+  return {
+    get: async () => {
+      try {
+        const raw = targetStorage.getItem(options.key)
+        const value = await deserialize(raw)
+        fallback.set(value)
+        return value
+      } catch (error) {
+        console.warn('[auth2][storage] Failed to read from storage', error)
+        return fallback.get()
+      }
+    },
+    set: async (value) => {
+      try {
+        const serialized = await serialize(value)
+        if (serialized === null) {
+          targetStorage.removeItem(options.key)
+        } else {
+          targetStorage.setItem(options.key, serialized)
+        }
+        fallback.set(value)
+      } catch (error) {
+        console.warn('[auth2][storage] Failed to write to storage', error)
+        fallback.set(value)
+      }
+    },
+    clear: () => {
+      try {
+        targetStorage.removeItem(options.key)
+      } catch (error) {
+        console.warn('[auth2][storage] Failed to clear storage', error)
+      } finally {
+        fallback.clear()
+      }
+    },
+  }
+}

package/src/kit/builder/auth/utils/storage/cookie.ts

@@ -0,0 +1,116 @@
+import type { AuthStorage, StorageOptions } from '../../types'
+import { isBrowser } from './env'
+import { createMemoryStorage } from './memory'
+import { SimpleEncryption } from './encryption'
+
+export const createCookieStorage = <T>(
+  options: StorageOptions,
+): AuthStorage<T> => {
+  const key = options.key ?? 'auth2_session'
+  const cookieOpts = options.cookieOptions ?? {}
+  const fallback = createMemoryStorage<T>()
+  const encryption =
+    options.encrypt && options.encryptionKey
+      ? new SimpleEncryption(options.encryptionKey)
+      : null
+  const cookieSetter =
+    typeof Document !== 'undefined'
+      ? Object.getOwnPropertyDescriptor(Document.prototype, 'cookie')?.set
+      : undefined
+
+  const assignCookie = (value: string) => {
+    if (!isBrowser || typeof document === 'undefined') return
+    if (cookieSetter) {
+      cookieSetter.call(document, value)
+      return
+    }
+    Reflect.set(document, 'cookie', value)
+  }
+
+  const serialize = async (value: T | null): Promise<string | null> => {
+    if (value === null) return null
+    const json = JSON.stringify(value)
+    return encryption ? await encryption.encrypt(json) : json
+  }
+
+  const deserialize = async (value: string | null): Promise<T | null> => {
+    if (!value) return null
+    try {
+      const decrypted = encryption ? await encryption.decrypt(value) : value
+      return JSON.parse(decrypted) as T
+    } catch {
+      return null
+    }
+  }
+
+  const getCookie = (name: string): string | null => {
+    if (!isBrowser) return null
+    const matches = document.cookie.match(
+      new RegExp(
+        `(?:^|; )${name.replace(/([.$?*|{}()\[\]\\/+^])/g, '\\$1')}=([^;]*)`,
+      ),
+    )
+    return matches ? decodeURIComponent(matches[1]) : null
+  }
+
+  const setCookie = (
+    name: string,
+    value: string,
+    opts: typeof cookieOpts = {},
+  ) => {
+    if (!isBrowser) return
+
+    let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`
+
+    if (opts.maxAge) cookie += `; max-age=${opts.maxAge}`
+    if (opts.domain) cookie += `; domain=${opts.domain}`
+    if (opts.path !== undefined) cookie += `; path=${opts.path}`
+    else cookie += '; path=/'
+    if (opts.secure) cookie += '; secure'
+    if (opts.sameSite) cookie += `; samesite=${opts.sameSite}`
+
+    assignCookie(cookie)
+  }
+
+  const deleteCookie = (name: string) => {
+    if (!isBrowser) return
+    assignCookie(`${name}=; max-age=0; path=/`)
+  }
+
+  return {
+    get: async () => {
+      try {
+        const raw = getCookie(key)
+        const value = await deserialize(raw)
+        fallback.set(value)
+        return value
+      } catch (error) {
+        console.warn('[auth2][storage] Failed to read from cookie', error)
+        return fallback.get()
+      }
+    },
+    set: async (value) => {
+      try {
+        const serialized = await serialize(value)
+        if (serialized === null) {
+          deleteCookie(key)
+        } else {
+          setCookie(key, serialized, cookieOpts)
+        }
+        fallback.set(value)
+      } catch (error) {
+        console.warn('[auth2][storage] Failed to write to cookie', error)
+        fallback.set(value)
+      }
+    },
+    clear: () => {
+      try {
+        deleteCookie(key)
+      } catch (error) {
+        console.warn('[auth2][storage] Failed to clear cookie', error)
+      } finally {
+        fallback.clear()
+      }
+    },
+  }
+}

package/src/kit/builder/auth/utils/storage/encryption.ts

@@ -0,0 +1,80 @@
+export class SimpleEncryption {
+  private key: string
+
+  constructor(key: string) {
+    this.key = key
+  }
+
+  async encrypt(text: string): Promise<string> {
+    if (!crypto?.subtle) {
+      console.warn('[auth2][storage] Crypto API not available, storing unencrypted')
+      return text
+    }
+
+    try {
+      const encoder = new TextEncoder()
+      const data = encoder.encode(text)
+      const keyData = encoder.encode(this.key.padEnd(32, '0').slice(0, 32))
+
+      const cryptoKey = await crypto.subtle.importKey(
+        'raw',
+        keyData,
+        { name: 'AES-GCM', length: 256 },
+        false,
+        ['encrypt'],
+      )
+
+      const iv = crypto.getRandomValues(new Uint8Array(12))
+      const encrypted = await crypto.subtle.encrypt(
+        { name: 'AES-GCM', iv },
+        cryptoKey,
+        data,
+      )
+
+      const result = new Uint8Array(iv.length + encrypted.byteLength)
+      result.set(iv, 0)
+      result.set(new Uint8Array(encrypted), iv.length)
+
+      return btoa(String.fromCharCode(...result))
+    } catch (error) {
+      console.error('[auth2][storage] Encryption failed:', error)
+      return text
+    }
+  }
+
+  async decrypt(encrypted: string): Promise<string> {
+    if (!crypto?.subtle) {
+      console.warn('[auth2][storage] Crypto API not available, reading unencrypted')
+      return encrypted
+    }
+
+    try {
+      const encoder = new TextEncoder()
+      const decoder = new TextDecoder()
+      const keyData = encoder.encode(this.key.padEnd(32, '0').slice(0, 32))
+
+      const cryptoKey = await crypto.subtle.importKey(
+        'raw',
+        keyData,
+        { name: 'AES-GCM', length: 256 },
+        false,
+        ['decrypt'],
+      )
+
+      const data = Uint8Array.from(atob(encrypted), (c) => c.charCodeAt(0))
+      const iv = data.slice(0, 12)
+      const encryptedData = data.slice(12)
+
+      const decrypted = await crypto.subtle.decrypt(
+        { name: 'AES-GCM', iv },
+        cryptoKey,
+        encryptedData,
+      )
+
+      return decoder.decode(decrypted)
+    } catch (error) {
+      console.error('[auth2][storage] Decryption failed:', error)
+      return encrypted
+    }
+  }
+}

package/src/kit/builder/auth/utils/storage/env.ts

@@ -0,0 +1,2 @@
+export const isBrowser =
+  typeof window !== "undefined" && typeof window.localStorage !== "undefined";

package/src/kit/builder/auth/utils/storage/factory.ts

@@ -0,0 +1,37 @@
+import type { AuthStorage, StorageOptions } from '../../types'
+import { isBrowser } from './env'
+import { createMemoryStorage } from './memory'
+import { createCookieStorage } from './cookie'
+import { createBrowserStorage } from './browser'
+
+/**
+ * Creates appropriate storage based on options
+ */
+export function createStorage<T>(options: StorageOptions = {}): AuthStorage<T> {
+  const storageType = options.storage ?? 'local'
+  const key = options.key ?? 'auth2_session'
+
+  switch (storageType) {
+    case 'cookie':
+      return createCookieStorage<T>(options)
+
+    case 'session':
+      return createBrowserStorage<T>({
+        key,
+        storage: isBrowser ? window.sessionStorage : undefined,
+        encrypt: options.encrypt,
+        encryptionKey: options.encryptionKey,
+      })
+
+    case 'local':
+      return createBrowserStorage<T>({
+        key,
+        storage: isBrowser ? window.localStorage : undefined,
+        encrypt: options.encrypt,
+        encryptionKey: options.encryptionKey,
+      })
+
+    default:
+      return createMemoryStorage<T>()
+  }
+}

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

@@ -0,0 +1,6 @@
+export * from './env'
+export * from './encryption'
+export * from './memory'
+export * from './cookie'
+export * from './browser'
+export * from './factory'

package/src/kit/builder/auth/utils/storage/memory.ts

@@ -0,0 +1,15 @@
+import type { AuthStorage } from '../../types'
+
+export const createMemoryStorage = <T>(): AuthStorage<T> => {
+  let value: T | null = null
+
+  return {
+    get: () => value,
+    set: (next) => {
+      value = next
+    },
+    clear: () => {
+      value = null
+    },
+  }
+}

package/src/kit/builder/auth/utils/token-manager.ts

@@ -0,0 +1,55 @@
+import type { TokenManager } from '../types';
+
+/**
+ * Default token manager implementation
+ * Handles token expiration checks and refresh scheduling
+ */
+export function createTokenManager(config?: {
+  refreshThreshold?: number; // seconds before expiry to trigger refresh
+}): TokenManager {
+  const refreshThreshold = config?.refreshThreshold ?? 300; // default 5 minutes
+
+  const isExpired = (expiresAt?: number | null): boolean => {
+    if (!expiresAt) return false;
+    return Date.now() >= expiresAt;
+  };
+
+  const shouldRefresh = (
+    expiresAt?: number | null,
+    threshold?: number,
+  ): boolean => {
+    if (!expiresAt) return false;
+    const thresholdMs = (threshold ?? refreshThreshold) * 1000;
+    return Date.now() >= expiresAt - thresholdMs;
+  };
+
+  const getTimeUntilExpiry = (expiresAt?: number | null): number => {
+    if (!expiresAt) return Infinity;
+    const timeLeft = expiresAt - Date.now();
+    return Math.max(0, timeLeft);
+  };
+
+  const scheduleRefresh = (
+    callback: () => void,
+    expiresAt?: number | null,
+  ): (() => void) => {
+    if (!expiresAt) return () => {};
+
+    const timeUntilRefresh = expiresAt - Date.now() - refreshThreshold * 1000;
+
+    if (timeUntilRefresh <= 0) {
+      callback();
+      return () => {};
+    }
+
+    const timeoutId = setTimeout(callback, timeUntilRefresh);
+    return () => clearTimeout(timeoutId);
+  };
+
+  return {
+    isExpired,
+    shouldRefresh,
+    getTimeUntilExpiry,
+    scheduleRefresh,
+  };
+}