nextauthz 1.0.0

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "nextauthz",
+  "version": "1.0.0",
+  "description": "",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --watch"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "next": "^16.1.6",
+    "react-token-manager": "^1.0.6",
+    "tsup": "^8.5.1",
+    "zustand": "^5.0.11"
+  }
+}

package/readme.md

@@ -0,0 +1,180 @@
+## Auth System Documentation
+
+## Overview
+
+This authentication system provides:
+
+    ** Global auth state
+
+    ** Token persistence
+
+    ** Typed AuthProvider & useAuth
+
+    ** Route protection
+
+    ** Role-based access
+
+    ** Configurable storage system
+
+## Installation
+
+npm install nextauthz
+
+
+## AuthProvider & useAuth
+
+Purpose
+
+Wrap your application with AuthProvider to provide global auth state (user, loading, error) and helper functions (login, logout, setUser).
+
+```bash
+import { createAppAuth } from 'nextauthz'
+
+// Choose storage type
+const { AuthProvider } = createAppAuth('localStorage')
+// Options: 'localStorage' | 'sessionStorage' | 'cookie'
+
+
+If no storage is passed, default is:
+
+createAppAuth() // defaults to 'cookie'
+
+
+function App({ children }: { children: React.ReactNode }) {
+  return <AuthProvider>{children}</AuthProvider>
+}
+
+export default App
+
+```
+
+## Hook: useAuth
+
+```bash 
+import { useAuth } from 'nextauthz'
+
+const { user, login, logout, setUser, loading, error } = useAuth()
+```
+
+Available Properties
+
+| Name      | Type                     | Description                                  |                            |
+| --------- | ------------------------ | -------------------------------------------- | -------------------------- |
+| `user`    | `User                    | null`                                        | Current authenticated user |
+| `login`   | `(tokens, user) => void` | Login and save tokens + user                 |                            |
+| `logout`  | `() => void`             | Clear auth tokens and reset state            |                            |
+| `setUser` | `(user) => void`         | Update user state manually                   |                            |
+| `loading` | `boolean`                | True while restoring user from token storage |                            |
+| `error`   | `Error                   | null`                                        | Last auth error            |
+
+
+Example: Logging in
+
+```bash 
+const handleLogin = async () => {
+  const tokens = {
+    access_token: 'abc123',
+    refresh_token: 'xyz789',
+  }
+
+  const user = {
+    id: 1,
+    name: 'John',
+    role: 'admin',
+  }
+
+  login(tokens, user)
+}
+
+```
+
+## AuthGuard
+
+Purpose
+
+Protect routes/pages to ensure only authenticated users can access them.
+
+Props
+
+| Name           | Type                    | Default        | Description                            |
+| -------------- | ----------------------- | -------------- | -------------------------------------- |
+| `children`     | `ReactNode`             | required       | Components to render if authenticated  |
+| `redirectTo`   | `string`                | `/login`       | Page to redirect unauthenticated users |
+| `tokenKey`     | `string`                | `access_token` | Token key to validate                  |
+| `refreshToken` | `() => Promise<string>` | optional       | Function to refresh expired token      |
+
+
+## Usage Example
+
+```bash
+import AuthGuard from 'nextauthz'
+
+function DashboardPage() {
+  return (
+    <AuthGuard>
+      <h1>Dashboard</h1>
+    </AuthGuard>
+  )
+}
+```
+Behavior:
+
+    ** Redirects to /login if the user is not authenticated.
+
+    ** Supports token refresh with refreshToken callback.
+
+
+## RoleGuard
+
+Purpose
+
+Restrict access to specific roles after authentication.
+
+| Name           | Type        | Default         | Description                                  |
+| -------------- | ----------- | --------------- | -------------------------------------------- |
+| `children`     | `ReactNode` | required        | Components to render if user role is allowed |
+| `allowedRoles` | `string[]`  | required        | Roles allowed to access this page            |
+| `redirectTo`   | `string`    | `/unauthorized` | Redirect page for unauthorized roles         |
+
+
+Usage Example
+
+```bash
+import RoleGuard from '@/auth/RoleGuard'
+import { useAuth } from '@/auth'
+
+function AdminPage() {
+  return (
+    <RoleGuard allowedRoles={['admin']}>
+      <h1>Admin Dashboard</h1>
+    </RoleGuard>
+  )
+}
+```
+
+## Storage Options
+
+You can configure token storage:
+
+| Storage Type     | Description                     |
+| ---------------- | ------------------------------- |
+| `localStorage`   | Persists until manually cleared |
+| `sessionStorage` | Clears on tab close             |
+| `cookie`         | Cookie-based storage (default)  |
+
+
+## Why NextAuthZ?
+
+    ** Zero boilerplate
+
+    ** Fully typed
+
+    ** Storage configurable
+
+    ** Clean architecture
+
+    ** Works with Next.js App Router
+
+    ** Lightweight
+
+    ** No opinionated backend

package/src/AuthGuard.tsx

@@ -0,0 +1,67 @@
+'use client'
+
+import React, { useEffect, useState } from 'react'
+import { useRouter } from 'next/navigation'
+import { useTokenManager } from 'react-token-manager'
+import { useAuthStore } from '../store/useGuardStore'
+
+type AuthGuardProps = {
+  children: React.ReactNode
+  redirectTo?: string
+  tokenKey?: string
+  refreshToken?: () => Promise<string | null>
+}
+
+const AuthGuard = ({
+  children,
+  redirectTo = '/login',
+  tokenKey = 'access_token',
+  refreshToken,
+}: AuthGuardProps) => {
+  const manager = useTokenManager()
+  const router = useRouter()
+  const isAuthChecked = useAuthStore((state) => state.isAuthChecked)
+  const isAuthenticated = useAuthStore((state) => state.isAuthenticated)
+  const error = useAuthStore((state) => state.error)
+
+  useEffect(() => {
+    const checkAuth = async () => {
+      try {
+        let token = manager.getSingleToken(tokenKey)
+
+        if (!token || manager.isExpired(token)) {
+          if (refreshToken) {
+            const newToken = await refreshToken()
+            if (newToken) {
+              manager.setTokens({ [tokenKey]: newToken })
+              token = newToken
+            }
+          }
+        }
+
+        const isValid = token && !manager.isExpired(token)
+        useAuthStore.getState().setAuth(Boolean(isValid))
+
+        if (!isValid) {
+          router.replace(redirectTo)
+        }
+      } catch (err: any) {
+        useAuthStore.getState().setError(err instanceof Error ? err : new Error(String(err)))
+        useAuthStore.getState().setAuth(false)
+        router.replace(redirectTo)
+      } finally {
+        useAuthStore.getState().setAuthChecked(true)
+      }
+    }
+
+    checkAuth()
+  }, [manager, router, redirectTo, tokenKey, refreshToken])
+
+  if (!isAuthChecked) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+  if (!isAuthenticated) return null
+
+  return <>{children}</>
+}
+
+export default AuthGuard

package/src/AuthProvider.tsx

@@ -0,0 +1,89 @@
+'use client'
+
+import React, { createContext, useContext, ReactNode, useState, useEffect } from 'react'
+import { configureTokenManager, useTokenManager } from 'react-token-manager'
+import { useAuthStore } from '../store/useGuardStore'
+
+export type AuthContextType<UserType> = {
+  user: UserType | any
+  login: (tokens: Record<string, string>, user: UserType) => void
+  logout: () => void
+  setUser: (user: UserType) => void
+  loading: boolean
+  error: Error | null
+}
+
+export type AuthContextOptions = {
+  storage?: 'localStorage' | 'sessionStorage' | 'cookie'
+}
+
+/**
+ * Factory to create typed AuthProvider and useAuth hook
+ */
+export function createAuthContext<UserType>(options?: AuthContextOptions) {
+  const storageType = options?.storage || 'cookie'
+  configureTokenManager({ storage: storageType })
+  const manager = useTokenManager()
+
+  const AuthContext = createContext<AuthContextType<UserType> | null>(null)
+
+  const AuthProvider = ({ children }: { children: ReactNode }) => {
+    const [loading, setLoading] = useState(true)
+    const user = useAuthStore((state) => state.user)
+    const error = useAuthStore((state) => state.error)
+
+    // Restore user on mount
+    useEffect(() => {
+      const savedUser = manager.getSingleToken('user')
+      if (savedUser) {
+        try {
+          const parsedUser = JSON.parse(savedUser)
+          useAuthStore.getState().setUser(parsedUser)
+          useAuthStore.getState().setError(null)
+        } catch (err: any) {
+          useAuthStore.getState().resetAuth()
+          useAuthStore.getState().setError(new Error('Failed to parse saved user'))
+        }
+      }
+      setLoading(false)
+    }, [])
+
+    const setUser = (userData: any) => {
+      useAuthStore.getState().setUser(userData)
+      useAuthStore.getState().setError(null)
+      manager.setTokens({ user: JSON.stringify(userData) })
+    }
+
+    const login = (tokens: Record<string, string>, userData: UserType) => {
+      try {
+        manager.setTokens(tokens)
+        setUser(userData)
+      } catch (err: any) {
+        useAuthStore.getState().setError(err instanceof Error ? err : new Error(String(err)))
+      }
+    }
+
+    const logout = () => {
+      try {
+        manager.clearTokens()
+        useAuthStore.getState().resetAuth()
+      } catch (err: any) {
+        useAuthStore.getState().setError(err instanceof Error ? err : new Error(String(err)))
+      }
+    }
+
+    return (
+      <AuthContext.Provider value={{ user, login, logout, setUser, loading, error }}>
+        {children}
+      </AuthContext.Provider>
+    )
+  }
+
+  const useAuth = (): AuthContextType<UserType> => {
+    const ctx = useContext(AuthContext)
+    if (!ctx) throw new Error('useAuth must be used inside AuthProvider')
+    return ctx
+  }
+
+  return { AuthProvider, useAuth }
+}

package/src/RoleGuard.tsx

@@ -0,0 +1,37 @@
+'use client'
+
+import React, { useEffect, useState } from 'react'
+import { useRouter } from 'next/navigation'
+import { useAuth } from './myAuth'
+
+type RoleGuardProps = {
+  children: React.ReactNode
+  allowedRoles: string[]
+  redirectTo?: string
+}
+
+const RoleGuard = ({
+  children,
+  allowedRoles,
+  redirectTo = '/unauthorized',
+}: RoleGuardProps) => {
+  const { user, loading } = useAuth()
+  const router = useRouter()
+  const [isChecking, setIsChecking] = useState(true)
+
+  useEffect(() => {
+    if (!user) return
+
+    const hasAccess = allowedRoles.includes(user?.role)
+    if (!hasAccess) {
+      router.replace(redirectTo)
+    }
+    setIsChecking(false)
+  }, [user, allowedRoles, redirectTo, router])
+
+  if (loading || !user || isChecking) return <div>Loading...</div>
+
+  return <>{children}</>
+}
+
+export default RoleGuard

package/src/index.ts

@@ -0,0 +1,16 @@
+import { createAuthContext } from './AuthProvider'
+
+export type User = {
+  [key: string]: any
+}
+
+// Export factory instead of fixed instance
+export function createAppAuth(
+  storage: 'localStorage' | 'sessionStorage' | 'cookie' = 'cookie'
+) {
+  return createAuthContext<User>({ storage })
+}
+
+export { createAuthContext } from './AuthProvider'
+export { default as AuthGuard } from './AuthGuard'
+export { default as RoleGuard } from './RoleGuard'

package/src/myAuth.ts

@@ -0,0 +1,7 @@
+import { createAppAuth } from "."
+
+
+export type User = any
+
+// Create typed AuthProvider and useAuth hook
+export const { AuthProvider, useAuth } = createAppAuth()

package/store/useGuardStore.ts

@@ -0,0 +1,39 @@
+'use client'
+
+import { create } from 'zustand'
+
+export type User = {
+  [key: string]: any
+}
+
+type AuthState = {
+  user: User | null       // user can be null
+  isAuthenticated: boolean
+  isAuthChecked: boolean
+  error: Error | null
+  setUser: (user: User | null) => void
+  setAuth: (isAuth: boolean) => void
+  setAuthChecked: (checked: boolean) => void
+  setError: (err: Error | null) => void
+  resetAuth: () => void
+}
+
+export const useAuthStore = create<AuthState>((set) => ({
+  user: null,
+  isAuthenticated: false,
+  isAuthChecked: false,
+  error: null,
+
+  setUser: (user) => set({ user }),
+  setAuth: (isAuth) => set({ isAuthenticated: isAuth }),
+  setAuthChecked: (checked) => set({ isAuthChecked: checked }),
+  setError: (err) => set({ error: err }),
+
+  resetAuth: () =>
+    set({
+      user: null,
+      isAuthenticated: false,
+      isAuthChecked: false,
+      error: null,
+    }),
+}))

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "module": "esnext",
+    "jsx": "react-jsx", // important
+    "strict": true,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  }
+}