nucleus-core-ts 0.9.76 → 0.9.77

package/dist/fe/components/AuthGuard/LoginChecker.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from 'react';
+import type { AuthGuardConfig } from './types';
+type LoginCheckerProps = {
+    config: AuthGuardConfig;
+    pathname: string;
+    onNavigate: (path: string) => void;
+    children: ReactNode;
+};
+export declare function LoginChecker({ config, pathname, onNavigate, children }: LoginCheckerProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/fe/components/AuthGuard/LoginChecker.js

@@ -0,0 +1,72 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useEffectEvent, useRef } from 'react';
+import { useAuthGuardStore } from './store';
+// ─── Path Matching ──────────────────────────────────────────────────────────
+function matchesAnyPath(pathname, paths) {
+    return paths.some((p)=>pathname === p || pathname.startsWith(`${p}/`));
+}
+// ─── LoginChecker ───────────────────────────────────────────────────────────
+// Wraps the application tree. Determines whether the current path requires
+// authentication and, if so, fetches the user via the ME endpoint.
+// - unauthPaths: login/register pages — skip checks, render children
+// - publicPaths: public content — skip checks, render children
+// - All other paths: require authenticated user in store
+//
+// The component calls `config.fetchUser` exactly once per session bootstrap.
+// Subsequent navigations reuse the hydrated store. A full re-fetch only
+// happens after logout (store.reset) or hard refresh.
+const MAX_RETRIES = 2;
+const RETRY_DELAY_MS = 1000;
+export function LoginChecker({ config, pathname, onNavigate, children }) {
+    const store = useAuthGuardStore();
+    const isCheckingRef = useRef(false);
+    const retryCountRef = useRef(0);
+    const isUnauth = matchesAnyPath(pathname, config.unauthPaths);
+    const isPublic = matchesAnyPath(pathname, config.publicPaths);
+    const requiresAuth = !isUnauth && !isPublic;
+    const performAuthCheck = useEffectEvent(()=>{
+        if (isCheckingRef.current) return;
+        isCheckingRef.current = true;
+        store.setLoading(true);
+        config.fetchUser({
+            onSuccess: (data)=>{
+                store.hydrate(data);
+                isCheckingRef.current = false;
+                retryCountRef.current = 0;
+            },
+            onError: (_error, _code)=>{
+                isCheckingRef.current = false;
+                if (retryCountRef.current < MAX_RETRIES) {
+                    retryCountRef.current++;
+                    setTimeout(()=>performAuthCheck(), RETRY_DELAY_MS);
+                    return;
+                }
+                store.setLoginChecked(true);
+                store.setLoading(false);
+                retryCountRef.current = 0;
+                onNavigate(config.loginPath);
+            }
+        });
+    });
+    useEffect(()=>{
+        if (!requiresAuth) return;
+        if (store.user) return;
+        if (isCheckingRef.current) return;
+        performAuthCheck();
+    }, [
+        requiresAuth,
+        store.user,
+        pathname
+    ]);
+    if (!requiresAuth) return /*#__PURE__*/ _jsx(_Fragment, {
+        children: children
+    });
+    const showLoader = !store.isLoginChecked || !store.user;
+    if (showLoader) return /*#__PURE__*/ _jsx(_Fragment, {
+        children: config.loadingComponent ?? null
+    });
+    return /*#__PURE__*/ _jsx(_Fragment, {
+        children: children
+    });
+}

package/dist/fe/components/AuthGuard/RoleChecker.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+import type { AuthGuardConfig } from './types';
+type RoleCheckerProps = {
+    config: AuthGuardConfig;
+    pathname: string;
+    children: ReactNode;
+};
+export declare function RoleChecker({ config, pathname, children }: RoleCheckerProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/fe/components/AuthGuard/RoleChecker.js

@@ -0,0 +1,80 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useEffectEvent, useState } from 'react';
+import { useAuthGuardStore } from './store';
+// ─── Path Matching ──────────────────────────────────────────────────────────
+function matchesAnyPath(pathname, paths) {
+    return paths.some((p)=>pathname === p || pathname.startsWith(`${p}/`));
+}
+function getRouteRequirement(pathname, requirements) {
+    if (requirements[pathname]) return requirements[pathname];
+    for (const [configPath, req] of Object.entries(requirements)){
+        if (pathname.startsWith(`${configPath}/`)) return req;
+    }
+    return null;
+}
+export function RoleChecker({ config, pathname, children }) {
+    const store = useAuthGuardStore();
+    const [state, setState] = useState('idle');
+    const evaluateAccess = useEffectEvent(()=>{
+        if (matchesAnyPath(pathname, config.unauthPaths) || matchesAnyPath(pathname, config.publicPaths)) {
+            setState('authorized');
+            return;
+        }
+        if (!store.isLoginChecked || !store.user) {
+            setState('checking');
+            return;
+        }
+        if (store.isGodmin()) {
+            setState('authorized');
+            return;
+        }
+        if (config.globalRoleGate && config.globalRoleGate.length > 0) {
+            const passesGate = store.hasAnyRole(config.globalRoleGate);
+            if (!passesGate) {
+                setState('forbidden');
+                return;
+            }
+        }
+        const requirement = config.routeRequirements ? getRouteRequirement(pathname, config.routeRequirements) : null;
+        if (!requirement) {
+            setState('authorized');
+            return;
+        }
+        const hasRequiredRoles = !requirement.roles || requirement.roles.length === 0 || (requirement.requireAll ? store.hasAllRoles(requirement.roles) : store.hasAnyRole(requirement.roles));
+        const hasRequiredClaims = !requirement.claims || requirement.claims.length === 0 || (requirement.requireAll ? store.hasAllClaims(requirement.claims, requirement.scope) : store.hasAnyClaim(requirement.claims, requirement.scope));
+        if (requirement.roles?.length && requirement.claims?.length) {
+            if (hasRequiredRoles || hasRequiredClaims) {
+                setState('authorized');
+                return;
+            }
+            setState('forbidden');
+            return;
+        }
+        if (requirement.roles?.length && !hasRequiredRoles) {
+            setState('forbidden');
+            return;
+        }
+        if (requirement.claims?.length && !hasRequiredClaims) {
+            setState('forbidden');
+            return;
+        }
+        setState('authorized');
+    });
+    useEffect(()=>{
+        evaluateAccess();
+    }, [
+        pathname,
+        store.user,
+        store.isLoginChecked,
+        store.roles,
+        store.claims
+    ]);
+    if (state === 'checking' || state === 'idle') return null;
+    if (state === 'forbidden') return /*#__PURE__*/ _jsx(_Fragment, {
+        children: config.forbiddenComponent ?? null
+    });
+    return /*#__PURE__*/ _jsx(_Fragment, {
+        children: children
+    });
+}

package/dist/fe/components/AuthGuard/index.d.ts

@@ -0,0 +1,5 @@
+export { LoginChecker } from './LoginChecker';
+export { RoleChecker } from './RoleChecker';
+export { useAuthGuardStore } from './store';
+export { usePermission } from './permissions';
+export type { AuthActions, AuthClaim, AuthFile, AuthGuardConfig, AuthProfile, AuthRole, AuthState, AuthUser, MeResponseData, PermissionCheckMode, PermissionCheckOptions, RouteRequirement, ScopeFilter, } from './types';

package/dist/fe/components/AuthGuard/index.js

@@ -0,0 +1,4 @@
+export { LoginChecker } from './LoginChecker';
+export { RoleChecker } from './RoleChecker';
+export { useAuthGuardStore } from './store';
+export { usePermission } from './permissions';

package/dist/fe/components/AuthGuard/permissions.d.ts

@@ -0,0 +1,14 @@
+import type { PermissionCheckOptions, ScopeFilter } from './types';
+export declare function usePermission(): {
+    checkPermission: (roles: string[], claims: string[], options?: PermissionCheckOptions) => boolean;
+    hasRole: (roleName: string) => boolean;
+    hasAnyRole: (roleNames: string[]) => boolean;
+    hasClaim: (claimAction: string, scope?: ScopeFilter) => boolean;
+    hasAnyClaim: (claimActions: string[], scope?: ScopeFilter) => boolean;
+    hasAllClaims: (claimActions: string[], scope?: ScopeFilter) => boolean;
+    isGodmin: () => boolean;
+    user: import("./types").AuthUser | null;
+    roles: import("./types").AuthRole[];
+    claims: import("./types").AuthClaim[];
+    isAuthenticated: boolean;
+};

package/dist/fe/components/AuthGuard/permissions.js

@@ -0,0 +1,47 @@
+'use client';
+import { useAuthGuardStore } from './store';
+// ─── Hook-based Permission Check ────────────────────────────────────────────
+// Returns a reactive `checkUserPermission` function bound to the current
+// auth state. Use in components for granular visibility/disabled control.
+//
+// Usage:
+//   const { checkPermission, hasClaim, hasRole } = usePermission()
+//   <Button disabled={!checkPermission(["supervisor"], ["create.orders"])} />
+//   <section hidden={!hasClaim("get.analytics", { orgId: currentOrg })} />
+export function usePermission() {
+    const store = useAuthGuardStore();
+    const checkPermission = (roles, claims, options)=>{
+        return store.checkPermission(roles, claims, options);
+    };
+    const hasRole = (roleName)=>{
+        return store.hasRole(roleName);
+    };
+    const hasAnyRole = (roleNames)=>{
+        return store.hasAnyRole(roleNames);
+    };
+    const hasClaim = (claimAction, scope)=>{
+        return store.hasClaim(claimAction, scope);
+    };
+    const hasAnyClaim = (claimActions, scope)=>{
+        return store.hasAnyClaim(claimActions, scope);
+    };
+    const hasAllClaims = (claimActions, scope)=>{
+        return store.hasAllClaims(claimActions, scope);
+    };
+    const isGodmin = ()=>{
+        return store.isGodmin();
+    };
+    return {
+        checkPermission,
+        hasRole,
+        hasAnyRole,
+        hasClaim,
+        hasAnyClaim,
+        hasAllClaims,
+        isGodmin,
+        user: store.user,
+        roles: store.roles,
+        claims: store.claims,
+        isAuthenticated: store.isLoginChecked && store.user !== null
+    };
+}

package/dist/fe/components/AuthGuard/store.d.ts

@@ -0,0 +1,2 @@
+import type { AuthActions, AuthState } from './types';
+export declare const useAuthGuardStore: () => import("h-state").StoreType<AuthState, AuthActions>;

package/dist/fe/components/AuthGuard/store.js

@@ -0,0 +1,147 @@
+'use client';
+import { batch, createStore } from 'h-state';
+// ─── Integrity ──────────────────────────────────────────────────────────────
+// Runtime-generated key lives in closure scope — not accessible via DevTools
+// state inspection. This is defense-in-depth; server middleware is the real guard.
+const _runtimeKey = crypto.getRandomValues(new Uint8Array(32)).join('');
+function computeIntegrityHash(roles, claims) {
+    const payload = JSON.stringify({
+        r: roles.map((r)=>r.name).sort(),
+        c: claims.map((c)=>`${c.action}|${c.scope ?? ''}`).sort()
+    });
+    let hash = 0;
+    const combined = _runtimeKey + payload;
+    for(let i = 0; i < combined.length; i++){
+        hash = (hash << 5) - hash + combined.charCodeAt(i) | 0;
+    }
+    return hash.toString(36);
+}
+// ─── Claim Matching ─────────────────────────────────────────────────────────
+// Mirrors nucleus-core backend's claimMatches logic:
+// "get.users" matches "get.users.firstName" (prefix/hierarchical match)
+function claimMatches(userClaim, requiredPattern) {
+    if (userClaim === requiredPattern) return true;
+    const userParts = userClaim.split('.');
+    const requiredParts = requiredPattern.split('.');
+    if (userParts.length > requiredParts.length) return false;
+    for(let i = 0; i < userParts.length; i++){
+        if (userParts[i] !== requiredParts[i]) return false;
+    }
+    return true;
+}
+function scopeMatches(claimScope, requiredScope) {
+    if (!requiredScope || Object.keys(requiredScope).length === 0) return true;
+    if (!claimScope) return true;
+    const parsed = new URLSearchParams(claimScope);
+    for (const [key, value] of Object.entries(requiredScope)){
+        const scopeVal = parsed.get(key);
+        if (scopeVal && scopeVal !== value && !scopeVal.startsWith('self:')) return false;
+    }
+    return true;
+}
+function userHasClaim(claims, claimAction, scope) {
+    return claims.some((c)=>claimMatches(c.action, claimAction) && scopeMatches(c.scope, scope ?? {}));
+}
+// ─── Store ──────────────────────────────────────────────────────────────────
+const INITIAL_STATE = {
+    user: null,
+    profile: null,
+    files: [],
+    roles: [],
+    claims: [],
+    isLoginChecked: false,
+    isLoading: false,
+    _integrityHash: ''
+};
+export const { useStore: useAuthGuardStore } = createStore({
+    ...INITIAL_STATE
+}, {
+    hydrate: (store)=>(data)=>{
+            const roles = data.roles ?? [];
+            const claims = data.claims ?? [];
+            batch(()=>{
+                store.user = data.user;
+                store.profile = data.profile ?? null;
+                store.files = data.files ?? [];
+                store.roles = roles;
+                store.claims = claims;
+                store.isLoginChecked = true;
+                store.isLoading = false;
+                store._integrityHash = computeIntegrityHash(roles, claims);
+            });
+        },
+    setLoading: (store)=>(loading)=>{
+            store.isLoading = loading;
+        },
+    setLoginChecked: (store)=>(checked)=>{
+            store.isLoginChecked = checked;
+        },
+    reset: (store)=>()=>{
+            batch(()=>{
+                store.user = INITIAL_STATE.user;
+                store.profile = INITIAL_STATE.profile;
+                store.files = [
+                    ...INITIAL_STATE.files
+                ];
+                store.roles = [
+                    ...INITIAL_STATE.roles
+                ];
+                store.claims = [
+                    ...INITIAL_STATE.claims
+                ];
+                store.isLoginChecked = false;
+                store.isLoading = false;
+                store._integrityHash = '';
+            });
+        },
+    getEffectiveUserId: (store)=>()=>{
+            return store.user?.id;
+        },
+    isGodmin: (store)=>()=>{
+            if (store.user?.isGod) return true;
+            return store.roles.some((r)=>r.name === 'godmin');
+        },
+    hasRole: (store)=>(roleName)=>{
+            if (store.user?.isGod) return true;
+            return store.roles.some((r)=>r.name === roleName);
+        },
+    hasAnyRole: (store)=>(roleNames)=>{
+            if (store.user?.isGod) return true;
+            return roleNames.some((name)=>store.roles.some((r)=>r.name === name));
+        },
+    hasAllRoles: (store)=>(roleNames)=>{
+            if (store.user?.isGod) return true;
+            return roleNames.every((name)=>store.roles.some((r)=>r.name === name));
+        },
+    hasClaim: (store)=>(claimAction, scope)=>{
+            if (store.user?.isGod) return true;
+            if (!store.verifyIntegrity()) return false;
+            return userHasClaim(store.claims, claimAction, scope);
+        },
+    hasAnyClaim: (store)=>(claimActions, scope)=>{
+            if (store.user?.isGod) return true;
+            if (!store.verifyIntegrity()) return false;
+            return claimActions.some((action)=>userHasClaim(store.claims, action, scope));
+        },
+    hasAllClaims: (store)=>(claimActions, scope)=>{
+            if (store.user?.isGod) return true;
+            if (!store.verifyIntegrity()) return false;
+            return claimActions.every((action)=>userHasClaim(store.claims, action, scope));
+        },
+    checkPermission: (store)=>(roles, claims, options)=>{
+            if (store.user?.isGod) return true;
+            if (!store.verifyIntegrity()) return false;
+            const mode = options?.mode ?? 'any';
+            const scope = options?.scope;
+            const rolePass = roles.length === 0 ? false : roles.some((name)=>store.roles.some((r)=>r.name === name));
+            const claimPass = claims.length === 0 ? false : mode === 'any' ? claims.some((action)=>userHasClaim(store.claims, action, scope)) : claims.every((action)=>userHasClaim(store.claims, action, scope));
+            if (roles.length === 0) return claimPass;
+            if (claims.length === 0) return rolePass;
+            return rolePass || claimPass;
+        },
+    verifyIntegrity: (store)=>()=>{
+            if (!store._integrityHash) return true;
+            const expected = computeIntegrityHash(store.roles, store.claims);
+            return expected === store._integrityHash;
+        }
+});

package/dist/fe/components/AuthGuard/types.d.ts

@@ -0,0 +1,91 @@
+import type { ReactNode } from 'react';
+export type AuthUser = {
+    id: string;
+    email: string | null;
+    isGod?: boolean;
+    [key: string]: unknown;
+};
+export type AuthProfile = {
+    id: string;
+    userId: string;
+    firstName?: string;
+    lastName?: string;
+    [key: string]: unknown;
+};
+export type AuthFile = {
+    id: string;
+    type: string | null;
+    updatedAt: string | Date;
+    [key: string]: unknown;
+};
+export type AuthRole = {
+    id: string;
+    name: string;
+    [key: string]: unknown;
+};
+export type AuthClaim = {
+    action: string;
+    scope: string | null;
+};
+export type ScopeFilter = Record<string, string>;
+export type PermissionCheckMode = 'any' | 'all';
+export type PermissionCheckOptions = {
+    mode?: PermissionCheckMode;
+    scope?: ScopeFilter;
+};
+export type RouteRequirement = {
+    roles?: string[];
+    claims?: string[];
+    requireAll?: boolean;
+    scope?: ScopeFilter;
+};
+export type AuthGuardConfig = {
+    unauthPaths: string[];
+    publicPaths: string[];
+    loginPath: string;
+    forbiddenPath?: string;
+    routeRequirements?: Record<string, RouteRequirement>;
+    globalRoleGate?: string[];
+    fetchUser: (options: {
+        onSuccess: (data: MeResponseData) => void;
+        onError: (error: unknown, code?: number) => void;
+    }) => void;
+    onLogout?: () => void;
+    loadingComponent?: ReactNode;
+    forbiddenComponent?: ReactNode;
+};
+export type MeResponseData = {
+    user: AuthUser;
+    profile?: AuthProfile | null;
+    files?: AuthFile[];
+    roles?: AuthRole[];
+    claims?: AuthClaim[];
+    addresses?: Record<string, unknown>[];
+    phones?: Record<string, unknown>[];
+};
+export type AuthState = {
+    user: AuthUser | null;
+    profile: AuthProfile | null;
+    files: AuthFile[];
+    roles: AuthRole[];
+    claims: AuthClaim[];
+    isLoginChecked: boolean;
+    isLoading: boolean;
+    _integrityHash: string;
+};
+export type AuthActions = {
+    hydrate: (data: MeResponseData) => void;
+    setLoading: (loading: boolean) => void;
+    setLoginChecked: (checked: boolean) => void;
+    reset: () => void;
+    getEffectiveUserId: () => string | undefined;
+    isGodmin: () => boolean;
+    hasRole: (roleName: string) => boolean;
+    hasAnyRole: (roleNames: string[]) => boolean;
+    hasAllRoles: (roleNames: string[]) => boolean;
+    hasClaim: (claimAction: string, scope?: ScopeFilter) => boolean;
+    hasAnyClaim: (claimActions: string[], scope?: ScopeFilter) => boolean;
+    hasAllClaims: (claimActions: string[], scope?: ScopeFilter) => boolean;
+    checkPermission: (roles: string[], claims: string[], options?: PermissionCheckOptions) => boolean;
+    verifyIntegrity: () => boolean;
+};

package/dist/fe/components/AuthGuard/types.js

@@ -0,0 +1 @@
+export { };

package/dist/fe/index.d.ts

@@ -1,3 +1,5 @@
+export { LoginChecker, RoleChecker, useAuthGuardStore, usePermission } from './components/AuthGuard';
+export type { AuthActions, AuthClaim, AuthFile, AuthGuardConfig, AuthProfile, AuthRole, AuthState, AuthUser, MeResponseData as AuthGuardMeResponse, PermissionCheckMode, PermissionCheckOptions, RouteRequirement, ScopeFilter, } from './components/AuthGuard';
 export { AbstractAnimatedBackground } from './components/AbstractAnimatedBackground';
 export type { AuthorizationPageProps, AuthorizationPageTheme, ClaimListProps, RoleClaimEditorProps, RoleListProps, } from './components/AuthorizationPage';
 export { AuthorizationPage, authorizationPageTheme, ClaimList, extendAuthorizationPageTheme, RoleClaimEditor, RoleList, useAuthorizationStore, } from './components/AuthorizationPage';

package/dist/fe/index.js

@@ -1,3 +1,5 @@
+// Auth Guard
+export { LoginChecker, RoleChecker, useAuthGuardStore, usePermission } from './components/AuthGuard';
 // UI Components
 export { AbstractAnimatedBackground } from './components/AbstractAnimatedBackground';
 export { AuthorizationPage, authorizationPageTheme, ClaimList, extendAuthorizationPageTheme, RoleClaimEditor, RoleList, useAuthorizationStore } from './components/AuthorizationPage';