@dudousxd/adonis-authkit-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davi de Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# @dudousxd/adonis-authkit-react
+
+Ergonomia de frontend sobre o AuthKit para apps **AdonisJS + Inertia + React**:
+um `useAuth()` tipado, helpers de papéis e componentes de gating.
+
+Este pacote **não** faz autenticação — ele consome o estado de auth que o host
+AdonisJS já resolveu (via `@dudousxd/adonis-authkit-client`) e compartilhou como
+uma shared-prop do Inertia.
+
+## Instalação
+
+```bash
+pnpm add @dudousxd/adonis-authkit-react
+```
+
+`react`, `react-dom` e `@inertiajs/react` são **peer dependencies** (o app os fornece).
+
+## 1. No host AdonisJS: compartilhar a prop `authkit`
+
+A shared-prop tem o formato `AuthSharedProps`. Use `auth.getUser()` /
+`auth.identity` do `@dudousxd/adonis-authkit-client` para preenchê-la — tipicamente
+num middleware ou no `config/inertia.ts` (`sharedData`):
+
+```ts
+// config/inertia.ts
+import { defineConfig } from '@adonisjs/inertia'
+
+export default defineConfig({
+  sharedData: {
+    authkit: async (ctx) => {
+      const auth = ctx.authkit // sua instância do Authenticator
+      const user = await auth.getUser() // mesmo shape de identityToUser/resolveUser
+      return {
+        user: user ?? null,
+        globalRoles: auth.identity?.globalRoles ?? [],
+        // appRoles opcional, se o host resolver papéis de app
+      }
+    },
+  },
+})
+```
+
+O objeto `user` deve corresponder ao tipo `AuthUser`:
+`{ id, email, name?, avatarUrl?, globalRoles, appRoles? }` — exatamente a saída de
+`identityToUser`/`resolveUser` do client.
+
+## 2. No frontend: `useAuth()`
+
+```tsx
+import { useAuth } from '@dudousxd/adonis-authkit-react'
+
+function Header() {
+  const { user, isAuthenticated, hasGlobalRole } = useAuth()
+
+  if (!isAuthenticated) return <a href="/login">Entrar</a>
+
+  return (
+    <div>
+      Olá, {user!.name ?? user!.email}
+      {hasGlobalRole('ADMIN') && <a href="/admin">Admin</a>}
+    </div>
+  )
+}
+```
+
+`useAuth()` nunca lança quando a prop está ausente: retorna estado
+não-autenticado (`user: null`, listas vazias).
+
+## 3. Componentes de gating
+
+```tsx
+import { Authenticated, Guest, Can } from '@dudousxd/adonis-authkit-react'
+
+<Authenticated fallback={<LoginButton />}>
+  <Dashboard />
+</Authenticated>
+
+<Guest>
+  <MarketingBanner />
+</Guest>
+
+{/* papel global único */}
+<Can role="ADMIN">
+  <AdminPanel />
+</Can>
+
+{/* exige todos os papéis */}
+<Can roles={['ADMIN', 'BILLING']} mode="all" fallback={<NoAccess />}>
+  <BillingSettings />
+</Can>
+
+{/* papel específico do app */}
+<Can role="EDITOR" appRole>
+  <EditButton />
+</Can>
+```
+
+## 4. `AuthProvider` (opcional)
+
+Fora do Inertia (testes, Storybook), injete o valor manualmente. O contexto tem
+precedência sobre as page props quando presente:
+
+```tsx
+import { AuthProvider } from '@dudousxd/adonis-authkit-react'
+
+<AuthProvider value={{ user, globalRoles: user.globalRoles }}>
+  <App />
+</AuthProvider>
+```
+
+## Helpers puros
+
+Para uso fora de componentes, as funções de papéis são exportadas e livres de React:
+
+```ts
+import { hasGlobalRole, hasAnyGlobalRole, hasAllGlobalRoles, hasAppRole } from '@dudousxd/adonis-authkit-react'
+
+hasGlobalRole(user, 'ADMIN')
+hasAnyGlobalRole(user, ['ADMIN', 'TEACHER'])
+```

package/build/index.d.ts

@@ -0,0 +1,9 @@
+export { useAuth } from './src/use_auth.js';
+export { AuthProvider, AuthContext } from './src/provider.js';
+export type { AuthProviderProps } from './src/provider.js';
+export { Authenticated, Guest } from './src/components/authenticated.js';
+export type { AuthenticatedProps, GuestProps } from './src/components/authenticated.js';
+export { Can } from './src/components/can.js';
+export type { CanProps } from './src/components/can.js';
+export { hasGlobalRole, hasAnyGlobalRole, hasAllGlobalRoles, hasAppRole, hasAnyAppRole, hasAllAppRoles, } from './src/roles.js';
+export type { AuthUser, AuthSharedProps, AuthState } from './src/types.js';

package/build/index.js

@@ -0,0 +1,5 @@
+export { useAuth } from './src/use_auth.js';
+export { AuthProvider, AuthContext } from './src/provider.js';
+export { Authenticated, Guest } from './src/components/authenticated.js';
+export { Can } from './src/components/can.js';
+export { hasGlobalRole, hasAnyGlobalRole, hasAllGlobalRoles, hasAppRole, hasAnyAppRole, hasAllAppRoles, } from './src/roles.js';

package/build/src/components/authenticated.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from 'react';
+export interface AuthenticatedProps {
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+export declare function Authenticated({ children, fallback }: AuthenticatedProps): import("react").FunctionComponentElement<import("react").FragmentProps>;
+export interface GuestProps {
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+export declare function Guest({ children, fallback }: GuestProps): import("react").FunctionComponentElement<import("react").FragmentProps>;

package/build/src/components/authenticated.js

@@ -0,0 +1,10 @@
+import { createElement, Fragment } from 'react';
+import { useAuth } from '../use_auth.js';
+export function Authenticated({ children, fallback = null }) {
+    const { isAuthenticated } = useAuth();
+    return createElement(Fragment, null, isAuthenticated ? children : fallback);
+}
+export function Guest({ children, fallback = null }) {
+    const { isAuthenticated } = useAuth();
+    return createElement(Fragment, null, isAuthenticated ? fallback : children);
+}

package/build/src/components/can.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from 'react';
+export interface CanProps {
+    children: ReactNode;
+    role?: string;
+    roles?: string[];
+    mode?: 'any' | 'all';
+    appRole?: boolean;
+    fallback?: ReactNode;
+}
+export declare function Can({ children, role, roles, mode, appRole, fallback, }: CanProps): import("react").FunctionComponentElement<import("react").FragmentProps>;

package/build/src/components/can.js

@@ -0,0 +1,19 @@
+import { createElement, Fragment } from 'react';
+import { useAuth } from '../use_auth.js';
+import { hasAllAppRoles, hasAllGlobalRoles, hasAnyAppRole, hasAnyGlobalRole, hasAppRole, hasGlobalRole, } from '../roles.js';
+export function Can({ children, role, roles, mode = 'any', appRole = false, fallback = null, }) {
+    const { user } = useAuth();
+    let allowed = false;
+    if (role !== undefined) {
+        allowed = appRole ? hasAppRole(user, role) : hasGlobalRole(user, role);
+    }
+    else if (roles !== undefined) {
+        if (appRole) {
+            allowed = mode === 'all' ? hasAllAppRoles(user, roles) : hasAnyAppRole(user, roles);
+        }
+        else {
+            allowed = mode === 'all' ? hasAllGlobalRoles(user, roles) : hasAnyGlobalRole(user, roles);
+        }
+    }
+    return createElement(Fragment, null, allowed ? children : fallback);
+}

package/build/src/provider.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from 'react';
+import type { AuthSharedProps } from './types.js';
+export declare const AuthContext: import("react").Context<{
+    user: import("./types.js").AuthUser | null;
+    globalRoles: string[];
+    appRoles?: string[];
+} | undefined>;
+export interface AuthProviderProps {
+    value: AuthSharedProps['authkit'];
+    children: ReactNode;
+}
+export declare function AuthProvider({ value, children }: AuthProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<{
+    user: import("./types.js").AuthUser | null;
+    globalRoles: string[];
+    appRoles?: string[];
+} | undefined>>;

package/build/src/provider.js

@@ -0,0 +1,5 @@
+import { createContext, createElement } from 'react';
+export const AuthContext = createContext(undefined);
+export function AuthProvider({ value, children }) {
+    return createElement(AuthContext.Provider, { value }, children);
+}

package/build/src/roles.d.ts

@@ -0,0 +1,7 @@
+import type { AuthUser } from './types.js';
+export declare function hasGlobalRole(user: AuthUser | null | undefined, role: string): boolean;
+export declare function hasAnyGlobalRole(user: AuthUser | null | undefined, roles: string[]): boolean;
+export declare function hasAllGlobalRoles(user: AuthUser | null | undefined, roles: string[]): boolean;
+export declare function hasAppRole(user: AuthUser | null | undefined, role: string): boolean;
+export declare function hasAnyAppRole(user: AuthUser | null | undefined, roles: string[]): boolean;
+export declare function hasAllAppRoles(user: AuthUser | null | undefined, roles: string[]): boolean;

package/build/src/roles.js

@@ -0,0 +1,32 @@
+export function hasGlobalRole(user, role) {
+    if (!user)
+        return false;
+    return user.globalRoles.includes(role);
+}
+export function hasAnyGlobalRole(user, roles) {
+    if (!user)
+        return false;
+    return roles.some((role) => user.globalRoles.includes(role));
+}
+export function hasAllGlobalRoles(user, roles) {
+    if (!user)
+        return false;
+    return roles.every((role) => user.globalRoles.includes(role));
+}
+export function hasAppRole(user, role) {
+    if (!user || !user.appRoles)
+        return false;
+    return user.appRoles.includes(role);
+}
+export function hasAnyAppRole(user, roles) {
+    if (!user || !user.appRoles)
+        return false;
+    const appRoles = user.appRoles;
+    return roles.some((role) => appRoles.includes(role));
+}
+export function hasAllAppRoles(user, roles) {
+    if (!user || !user.appRoles)
+        return false;
+    const appRoles = user.appRoles;
+    return roles.every((role) => appRoles.includes(role));
+}

package/build/src/types.d.ts

@@ -0,0 +1,27 @@
+export interface AuthUser {
+    id: string;
+    email: string;
+    name?: string;
+    avatarUrl?: string;
+    globalRoles: string[];
+    appRoles?: string[];
+    [key: string]: unknown;
+}
+export interface AuthSharedProps {
+    authkit: {
+        user: AuthUser | null;
+        globalRoles: string[];
+        appRoles?: string[];
+    };
+    [key: string]: unknown;
+}
+export interface AuthState {
+    user: AuthUser | null;
+    isAuthenticated: boolean;
+    globalRoles: string[];
+    appRoles: string[];
+    hasGlobalRole(role: string): boolean;
+    hasAnyGlobalRole(roles: string[]): boolean;
+    hasAllGlobalRoles(roles: string[]): boolean;
+    hasAppRole(role: string): boolean;
+}

package/build/src/types.js

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

package/build/src/use_auth.d.ts

@@ -0,0 +1,2 @@
+import type { AuthState } from './types.js';
+export declare function useAuth(): AuthState;

package/build/src/use_auth.js

@@ -0,0 +1,29 @@
+import { useContext, useMemo } from 'react';
+import { usePage } from '@inertiajs/react';
+import { AuthContext } from './provider.js';
+import { hasAllGlobalRoles as hasAllGlobalRolesPure, hasAnyGlobalRole as hasAnyGlobalRolePure, hasAppRole as hasAppRolePure, hasGlobalRole as hasGlobalRolePure, } from './roles.js';
+const UNAUTHENTICATED = {
+    user: null,
+    globalRoles: [],
+    appRoles: undefined,
+};
+export function useAuth() {
+    const contextValue = useContext(AuthContext);
+    const pageProps = usePage().props;
+    const authkit = contextValue ?? pageProps?.authkit ?? UNAUTHENTICATED;
+    return useMemo(() => {
+        const user = authkit.user ?? null;
+        const globalRoles = authkit.globalRoles ?? user?.globalRoles ?? [];
+        const appRoles = authkit.appRoles ?? user?.appRoles ?? [];
+        return {
+            user,
+            isAuthenticated: user !== null,
+            globalRoles,
+            appRoles,
+            hasGlobalRole: (role) => hasGlobalRolePure(user, role),
+            hasAnyGlobalRole: (roles) => hasAnyGlobalRolePure(user, roles),
+            hasAllGlobalRoles: (roles) => hasAllGlobalRolesPure(user, roles),
+            hasAppRole: (role) => hasAppRolePure(user, role),
+        };
+    }, [authkit]);
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@dudousxd/adonis-authkit-react",
+  "version": "0.1.0",
+  "description": "Frontend ergonomics over AuthKit for AdonisJS + Inertia + React apps: a typed useAuth() hook, role-gating hooks and gating components.",
+  "license": "MIT",
+  "author": "dudousxd",
+  "homepage": "https://github.com/DavideCarvalho/streaming-educacao/tree/main/packages/authkit-react#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DavideCarvalho/streaming-educacao.git",
+    "directory": "packages/authkit-react"
+  },
+  "bugs": {
+    "url": "https://github.com/DavideCarvalho/streaming-educacao/issues"
+  },
+  "keywords": [
+    "adonisjs",
+    "inertia",
+    "react",
+    "authentication",
+    "authkit",
+    "rbac",
+    "authorization"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "files": [
+    "build"
+  ],
+  "exports": {
+    ".": "./build/index.js",
+    "./types": "./build/index.js"
+  },
+  "peerDependencies": {
+    "@inertiajs/react": "3.3.0",
+    "react": "19.2.6",
+    "react-dom": "19.2.6"
+  },
+  "dependencies": {
+    "@dudousxd/adonis-authkit-core": "0.1.0"
+  },
+  "devDependencies": {
+    "@adonisjs/tsconfig": "2.0.0",
+    "@inertiajs/react": "3.3.0",
+    "@japa/assert": "4.2.0",
+    "@japa/runner": "5.3.0",
+    "@poppinss/ts-exec": "1.4.4",
+    "@types/node": "25.9.1",
+    "@types/react": "19.2.15",
+    "@types/react-dom": "19.2.3",
+    "react": "19.2.6",
+    "react-dom": "19.2.6",
+    "typescript": "6.0.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import=@poppinss/ts-exec bin/test.ts"
+  }
+}