@adonis-agora/authkit-react 0.19.1 → 0.20.1

package/build/index.d.ts

@@ -84,9 +84,9 @@ export { hasGlobalRole, hasAnyGlobalRole, hasAllGlobalRoles, } from './src/roles
 export type { AuthUser, AuthSharedProps, AuthState } from './src/types.js';
 export { createAuthkitClient, AuthkitClientError, } from './src/client/client.js';
 export type { AuthkitClient, AuthkitClientOptions, } from './src/client/client.js';
-export type { AdminUser, AdminUserListResult, CreateUserInput, UpdateUserInput, UserSessionsResult, RevokeSessionsResult, AdminSessionEntry, AdminGrantEntry, AdminClient, AdminClientListResult, CreatedClientResult, RegenerateSecretResult, CreateClientInput, UpdateClientInput, RoleCatalogEntry, RoleListResult, CreateRoleInput, UpdateRoleInput, AdminOrgEntry, AdminOrgMember, AdminOrgInvitation, AdminOrgDetail, AdminOrgListResult, CreateOrgInput, UpdateOrgInput, AuditEventEntry, AuditListResult, AuditListParams, SettingEntry, SettingListResult, ImpersonationPanel, DailyPoint, AdminOverview, AccountCapabilities, AccountMe, AccountSecurityOverview, AccountSessionEntry, AccountSessionsResult, RevokeSessionResult, RevokeOthersResult, RevokeAllResult, AccountAppEntry, AccountAppsResult, RevokeAppResult, PasskeySummaryEntry, AccountMfaStatus, AccountPasskeysResult, RemovePasskeyResult, PatEntry, CreatedPatResult, AccountTokensResult, CreateTokenInput, RevokeTokenResult, UpdateProfileInput, UpdateProfileResult, ChangePasswordInput, RequestEmailChangeInput, OkResult, EmailChangeResult, AccountOrgEntry, AccountOrgsResult, AccountOrgDetail, AccountOrgInvitationsResult, ApiErrorBody, KeysStatus, ManagedKeyInfo, KeysRotateInput, KeysRotateResult, } from './src/client/types.js';
+export type { AdminUser, AdminUserListResult, CreateUserInput, UpdateUserInput, UserSessionsResult, RevokeSessionsResult, AdminSessionEntry, AdminGrantEntry, AdminClient, AdminClientListResult, CreatedClientResult, RegenerateSecretResult, CreateClientInput, UpdateClientInput, RoleCatalogEntry, RoleListResult, CreateRoleInput, UpdateRoleInput, AdminOrgEntry, AdminOrgMember, AdminOrgInvitation, AdminOrgDetail, AdminOrgListResult, CreateOrgInput, UpdateOrgInput, AuditEventEntry, AuditListResult, AuditListParams, SettingEntry, SettingListResult, ImpersonationPanel, DailyPoint, AdminOverview, AccountCapabilities, AccountMe, AccountSecurityOverview, AccountSessionEntry, AccountSessionsResult, RevokeSessionResult, RevokeOthersResult, RevokeAllResult, AccountAppEntry, AccountAppsResult, RevokeAppResult, PasskeySummaryEntry, AccountMfaStatus, AccountPasskeysResult, RemovePasskeyResult, AccountLoginMethodsResult, UpdateLoginMethodsResult, UserLoginMethodsInput, PatEntry, CreatedPatResult, AccountTokensResult, CreateTokenInput, RevokeTokenResult, UpdateProfileInput, UpdateProfileResult, ChangePasswordInput, RequestEmailChangeInput, OkResult, EmailChangeResult, AccountOrgEntry, AccountOrgsResult, AccountOrgDetail, AccountOrgInvitationsResult, ApiErrorBody, KeysStatus, ManagedKeyInfo, KeysRotateInput, KeysRotateResult, } from './src/client/types.js';
 export { AuthkitClientProvider, useAuthkitClient, createAuthkitQueryClient, } from './src/client/context.js';
 export type { AuthkitClientProviderProps } from './src/client/context.js';
 export { authkitKeys } from './src/queries/keys.js';
 export { useOverviewQueryOptions, useUsersQueryOptions, useUserQueryOptions, useUserSessionsQueryOptions, useCreateUserMutationOptions, useUpdateUserMutationOptions, useDisableUserMutationOptions, useEnableUserMutationOptions, useResetPasswordMutationOptions, useDeleteUserMutationOptions, useRevokeUserSessionsMutationOptions, useSessionsQueryOptions, useRevokeAllSessionsMutationOptions, useClientsQueryOptions, useClientQueryOptions, useCreateClientMutationOptions, useUpdateClientMutationOptions, useDeleteClientMutationOptions, useRegenerateClientSecretMutationOptions, useRolesQueryOptions, useCreateRoleMutationOptions, useUpdateRoleMutationOptions, useDeleteRoleMutationOptions, useOrgsQueryOptions, useOrgQueryOptions, useCreateOrgMutationOptions, useUpdateOrgMutationOptions, useDeleteOrgMutationOptions, useAddOrgMemberMutationOptions, useRemoveOrgMemberMutationOptions, useUpdateOrgMemberRoleMutationOptions, useCreateOrgInvitationMutationOptions, useRevokeOrgInvitationMutationOptions, useAuditQueryOptions, useSettingsQueryOptions, useSetSettingMutationOptions, useRemoveSettingMutationOptions, useImpersonationQueryOptions, useKeysQueryOptions, useRotateKeysMutationOptions, } from './src/queries/admin/index.js';
-export { useMeQueryOptions, useSecurityQueryOptions, useUpdateProfileMutationOptions, useChangePasswordMutationOptions, useEmailChangeMutationOptions, useCancelEmailChangeMutationOptions, useAccountSessionsQueryOptions, useRevokeSessionMutationOptions, useRevokeOtherSessionsMutationOptions, useAccountRevokeAllSessionsMutationOptions, useAppsQueryOptions, useRevokeAppMutationOptions, useMfaQueryOptions, usePasskeysQueryOptions, useRemovePasskeyMutationOptions, useTokensQueryOptions, useCreateTokenMutationOptions, useRevokeTokenMutationOptions, useAccountOrgsQueryOptions, useAccountOrgQueryOptions, useAccountOrgInvitationsQueryOptions, } from './src/queries/account/index.js';
+export { useMeQueryOptions, useSecurityQueryOptions, useUpdateProfileMutationOptions, useChangePasswordMutationOptions, useEmailChangeMutationOptions, useCancelEmailChangeMutationOptions, useAccountSessionsQueryOptions, useRevokeSessionMutationOptions, useRevokeOtherSessionsMutationOptions, useAccountRevokeAllSessionsMutationOptions, useAppsQueryOptions, useRevokeAppMutationOptions, useMfaQueryOptions, useLoginMethodsQueryOptions, useUpdateLoginMethodsMutationOptions, usePasskeysQueryOptions, useRemovePasskeyMutationOptions, useTokensQueryOptions, useCreateTokenMutationOptions, useRevokeTokenMutationOptions, useAccountOrgsQueryOptions, useAccountOrgQueryOptions, useAccountOrgInvitationsQueryOptions, } from './src/queries/account/index.js';

package/build/index.js

@@ -45,4 +45,4 @@ export { createAuthkitClient, AuthkitClientError, } from './src/client/client.js
 export { AuthkitClientProvider, useAuthkitClient, createAuthkitQueryClient, } from './src/client/context.js';
 export { authkitKeys } from './src/queries/keys.js';
 export { useOverviewQueryOptions, useUsersQueryOptions, useUserQueryOptions, useUserSessionsQueryOptions, useCreateUserMutationOptions, useUpdateUserMutationOptions, useDisableUserMutationOptions, useEnableUserMutationOptions, useResetPasswordMutationOptions, useDeleteUserMutationOptions, useRevokeUserSessionsMutationOptions, useSessionsQueryOptions, useRevokeAllSessionsMutationOptions, useClientsQueryOptions, useClientQueryOptions, useCreateClientMutationOptions, useUpdateClientMutationOptions, useDeleteClientMutationOptions, useRegenerateClientSecretMutationOptions, useRolesQueryOptions, useCreateRoleMutationOptions, useUpdateRoleMutationOptions, useDeleteRoleMutationOptions, useOrgsQueryOptions, useOrgQueryOptions, useCreateOrgMutationOptions, useUpdateOrgMutationOptions, useDeleteOrgMutationOptions, useAddOrgMemberMutationOptions, useRemoveOrgMemberMutationOptions, useUpdateOrgMemberRoleMutationOptions, useCreateOrgInvitationMutationOptions, useRevokeOrgInvitationMutationOptions, useAuditQueryOptions, useSettingsQueryOptions, useSetSettingMutationOptions, useRemoveSettingMutationOptions, useImpersonationQueryOptions, useKeysQueryOptions, useRotateKeysMutationOptions, } from './src/queries/admin/index.js';
-export { useMeQueryOptions, useSecurityQueryOptions, useUpdateProfileMutationOptions, useChangePasswordMutationOptions, useEmailChangeMutationOptions, useCancelEmailChangeMutationOptions, useAccountSessionsQueryOptions, useRevokeSessionMutationOptions, useRevokeOtherSessionsMutationOptions, useAccountRevokeAllSessionsMutationOptions, useAppsQueryOptions, useRevokeAppMutationOptions, useMfaQueryOptions, usePasskeysQueryOptions, useRemovePasskeyMutationOptions, useTokensQueryOptions, useCreateTokenMutationOptions, useRevokeTokenMutationOptions, useAccountOrgsQueryOptions, useAccountOrgQueryOptions, useAccountOrgInvitationsQueryOptions, } from './src/queries/account/index.js';
+export { useMeQueryOptions, useSecurityQueryOptions, useUpdateProfileMutationOptions, useChangePasswordMutationOptions, useEmailChangeMutationOptions, useCancelEmailChangeMutationOptions, useAccountSessionsQueryOptions, useRevokeSessionMutationOptions, useRevokeOtherSessionsMutationOptions, useAccountRevokeAllSessionsMutationOptions, useAppsQueryOptions, useRevokeAppMutationOptions, useMfaQueryOptions, useLoginMethodsQueryOptions, useUpdateLoginMethodsMutationOptions, usePasskeysQueryOptions, useRemovePasskeyMutationOptions, useTokensQueryOptions, useCreateTokenMutationOptions, useRevokeTokenMutationOptions, useAccountOrgsQueryOptions, useAccountOrgQueryOptions, useAccountOrgInvitationsQueryOptions, } from './src/queries/account/index.js';

package/build/src/client/client.d.ts

@@ -1,4 +1,4 @@
-import type { AccountAppsResult, AccountMe, AccountMfaStatus, AccountOrgDetail, AccountOrgInvitationsResult, AccountOrgsResult, AccountPasskeysResult, AccountSecurityOverview, AccountSessionsResult, AccountTokensResult, AdminClient, AdminClientListResult, AdminOrgDetail, AdminOrgEntry, AdminOrgInvitation, AdminOrgListResult, AdminOverview, AdminUser, AdminUserListResult, AuditListParams, AuditListResult, ChangePasswordInput, CreateClientInput, CreateOrgInput, CreateRoleInput, CreateTokenInput, CreateUserInput, CreatedClientResult, CreatedPatResult, EmailChangeResult, ImpersonationPanel, KeysRotateInput, KeysRotateResult, KeysStatus, OkResult, RegenerateSecretResult, RemovePasskeyResult, RequestEmailChangeInput, RevokeAllResult, RevokeAppResult, RevokeOthersResult, RevokeSessionResult, RevokeSessionsResult, RevokeTokenResult, RoleCatalogEntry, RoleListResult, SettingEntry, SettingListResult, UpdateClientInput, UpdateOrgInput, UpdateProfileInput, UpdateProfileResult, UpdateRoleInput, UpdateUserInput, UserSessionsResult } from './types.js';
+import type { AccountAppsResult, AccountLoginMethodsResult, AccountMe, AccountMfaStatus, AccountOrgDetail, AccountOrgInvitationsResult, AccountOrgsResult, AccountPasskeysResult, AccountSecurityOverview, AccountSessionsResult, AccountTokensResult, AdminClient, AdminClientListResult, AdminOrgDetail, AdminOrgEntry, AdminOrgInvitation, AdminOrgListResult, AdminOverview, AdminUser, AdminUserListResult, AuditListParams, AuditListResult, ChangePasswordInput, CreateClientInput, CreateOrgInput, CreateRoleInput, CreateTokenInput, CreateUserInput, CreatedClientResult, CreatedPatResult, EmailChangeResult, ImpersonationPanel, KeysRotateInput, KeysRotateResult, KeysStatus, OkResult, RegenerateSecretResult, RemovePasskeyResult, RequestEmailChangeInput, RevokeAllResult, RevokeAppResult, RevokeOthersResult, RevokeSessionResult, RevokeSessionsResult, RevokeTokenResult, RoleCatalogEntry, RoleListResult, SettingEntry, SettingListResult, UpdateClientInput, UpdateLoginMethodsResult, UpdateOrgInput, UpdateProfileInput, UpdateProfileResult, UpdateRoleInput, UpdateUserInput, UserLoginMethodsInput, UserSessionsResult } from './types.js';
 export declare class AuthkitClientError extends Error {
     readonly status: number;
     readonly code?: string | undefined;
@@ -152,6 +152,12 @@ declare class AuthkitClient {
             readonly revoke: (clientId: string) => Promise<RevokeAppResult>;
         };
         readonly mfa: () => Promise<AccountMfaStatus>;
+        readonly loginMethods: {
+            readonly get: () => Promise<AccountLoginMethodsResult>;
+            readonly update: (data: {
+                methods: UserLoginMethodsInput;
+            }) => Promise<UpdateLoginMethodsResult>;
+        };
         readonly passkeys: {
             readonly list: () => Promise<AccountPasskeysResult>;
             readonly remove: (id: string) => Promise<RemovePasskeyResult>;

package/build/src/client/client.js

@@ -199,6 +199,10 @@ class AuthkitClient {
             revoke: (clientId) => this.delete(this.a(`/apps/${encodeURIComponent(clientId)}`)),
         },
         mfa: () => this.get(this.a('/mfa')),
+        loginMethods: {
+            get: () => this.get(this.a('/login-methods')),
+            update: (data) => this.put(this.a('/login-methods'), data),
+        },
         passkeys: {
             list: () => this.get(this.a('/passkeys')),
             remove: (id) => this.delete(this.a(`/passkeys/${encodeURIComponent(id)}`)),

package/build/src/client/types.d.ts

@@ -258,6 +258,33 @@ export interface AccountSecurityOverview {
         passkeysSupported: boolean;
     };
 }
+export interface UserLoginMethodsInput {
+    password?: boolean;
+    magicLink?: boolean;
+    passkey?: boolean;
+    social?: boolean;
+}
+export interface AccountLoginMethodsResult {
+    supported: boolean;
+    methods: UserLoginMethodsInput | null;
+    available: {
+        password: boolean;
+        magicLink: boolean;
+        passkey: boolean;
+        social: string[];
+        forgotPassword: boolean;
+    } | null;
+    locked: {
+        password: boolean;
+        magicLink: boolean;
+        passkey: boolean;
+        social: boolean;
+    } | null;
+}
+export interface UpdateLoginMethodsResult {
+    ok: boolean;
+    methods: UserLoginMethodsInput;
+}
 export interface AccountSessionsResult {
     supported: boolean;
     sessions: AccountSessionEntry[];

package/build/src/queries/account/index.d.ts

@@ -1,4 +1,4 @@
-import type { AccountAppsResult, AccountMe, AccountMfaStatus, AccountOrgDetail, AccountOrgInvitationsResult, AccountOrgsResult, AccountPasskeysResult, AccountSecurityOverview, AccountSessionsResult, AccountTokensResult, ChangePasswordInput, CreateTokenInput, CreatedPatResult, EmailChangeResult, OkResult, RemovePasskeyResult, RequestEmailChangeInput, RevokeAllResult, RevokeAppResult, RevokeOthersResult, RevokeSessionResult, RevokeTokenResult, UpdateProfileInput, UpdateProfileResult } from '../../client/types.js';
+import type { AccountAppsResult, AccountLoginMethodsResult, AccountMe, AccountMfaStatus, AccountOrgDetail, AccountOrgInvitationsResult, AccountOrgsResult, AccountPasskeysResult, AccountSecurityOverview, AccountSessionsResult, AccountTokensResult, ChangePasswordInput, CreateTokenInput, CreatedPatResult, EmailChangeResult, OkResult, RemovePasskeyResult, RequestEmailChangeInput, RevokeAllResult, RevokeAppResult, RevokeOthersResult, RevokeSessionResult, RevokeTokenResult, UpdateLoginMethodsResult, UpdateProfileInput, UpdateProfileResult, UserLoginMethodsInput } from '../../client/types.js';
 export declare function useMeQueryOptions(): {
     queryKey: readonly ["authkit", "account", "me"];
     queryFn: () => Promise<AccountMe>;
@@ -51,6 +51,16 @@ export declare function useMfaQueryOptions(): {
     queryKey: readonly ["authkit", "account", "mfa"];
     queryFn: () => Promise<AccountMfaStatus>;
 };
+export declare function useLoginMethodsQueryOptions(): {
+    queryKey: readonly ["authkit", "account", "login-methods"];
+    queryFn: () => Promise<AccountLoginMethodsResult>;
+};
+export declare function useUpdateLoginMethodsMutationOptions(): {
+    mutationKey: string[];
+    mutationFn: (data: {
+        methods: UserLoginMethodsInput;
+    }) => Promise<UpdateLoginMethodsResult>;
+};
 export declare function usePasskeysQueryOptions(): {
     queryKey: readonly ["authkit", "account", "passkeys"];
     queryFn: () => Promise<AccountPasskeysResult>;

package/build/src/queries/account/index.js

@@ -91,6 +91,20 @@ export function useMfaQueryOptions() {
         queryFn: () => client.account.mfa(),
     };
 }
+export function useLoginMethodsQueryOptions() {
+    const client = useAuthkitClient();
+    return {
+        queryKey: authkitKeys.account.loginMethods(),
+        queryFn: () => client.account.loginMethods.get(),
+    };
+}
+export function useUpdateLoginMethodsMutationOptions() {
+    const client = useAuthkitClient();
+    return {
+        mutationKey: ['authkit', 'account', 'login-methods', 'update'],
+        mutationFn: (data) => client.account.loginMethods.update(data),
+    };
+}
 export function usePasskeysQueryOptions() {
     const client = useAuthkitClient();
     return {

package/build/src/queries/keys.d.ts

@@ -46,5 +46,6 @@ export declare const authkitKeys: {
         readonly orgs: () => readonly ["authkit", "account", "orgs"];
         readonly org: (id: string) => readonly ["authkit", "account", "orgs", string];
         readonly orgInvitations: () => readonly ["authkit", "account", "orgs", "invitations"];
+        readonly loginMethods: () => readonly ["authkit", "account", "login-methods"];
     };
 };

package/build/src/queries/keys.js

@@ -30,5 +30,6 @@ export const authkitKeys = {
         orgs: () => ['authkit', 'account', 'orgs'],
         org: (id) => ['authkit', 'account', 'orgs', id],
         orgInvitations: () => ['authkit', 'account', 'orgs', 'invitations'],
+        loginMethods: () => ['authkit', 'account', 'login-methods'],
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-react",
-  "version": "0.19.1",
+  "version": "0.20.1",
   "description": "Frontend ergonomics over AuthKit for AdonisJS + Inertia + React apps: a typed useAuth() hook, role-gating hooks and gating components.",
   "license": "MIT",
   "author": "dudousxd",
@@ -20,7 +20,8 @@
     "authentication",
     "authkit",
     "rbac",
-    "authorization"
+    "authorization",
+    "tanstack-intent"
   ],
   "publishConfig": {
     "access": "public"
@@ -30,7 +31,8 @@
   "types": "./build/index.d.ts",
   "files": [
     "build",
-    "styles.css"
+    "styles.css",
+    "skills"
   ],
   "exports": {
     ".": "./build/index.js",
@@ -58,6 +60,7 @@
     "@japa/assert": "4.2.0",
     "@japa/runner": "5.3.0",
     "@poppinss/ts-exec": "1.4.4",
+    "@tanstack/intent": "^0.3.2",
     "@tanstack/react-query": "5.101.4",
     "@types/node": "25.9.1",
     "@types/react": "19.2.18",

package/skills/authkit-react-auth/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: authkit-react-auth
+description: >-
+  Frontend auth ergonomics with @adonis-agora/authkit-react in AdonisJS + Inertia +
+  React apps. Covers the shared-prop `authkit` contract (AuthSharedProps:
+  { user, globalRoles }), useAuth() semantics (never throws; AuthProvider context
+  precedence), role helpers hasGlobalRole/hasAnyGlobalRole/hasAllGlobalRoles,
+  Authenticated/Guest gating components with fallback, AuthkitProvider config
+  ({ csrfToken, endpoints, idp }) with headless hooks (useSignIn, useSignOut,
+  useProfile, useSessions, useAuthorizedApps) and ready components (SignInButton,
+  UserButton, UserProfile, AuthorizedApps), and the idp:'external' degradation rule.
+  Use when wiring the auth shared prop, gating UI by roles, adding sign-in/out
+  buttons or account components, or debugging an always-unauthenticated React app.
+license: MIT
+metadata:
+  type: core
+  library: "@adonis-agora/authkit-react"
+  library_version: "0.20.0"
+  framework: react
+sources:
+  - "DavideCarvalho/adonis-authkit:packages/authkit-react/README.md"
+  - "DavideCarvalho/adonis-authkit:packages/authkit-react/src/use_auth.ts"
+  - "DavideCarvalho/adonis-authkit:packages/authkit-react/src/config.ts"
+  - "DavideCarvalho/adonis-authkit:packages/authkit-react/index.ts"
+---
+
+# React auth ergonomics (Inertia)
+
+`@adonis-agora/authkit-react` never authenticates anything. It consumes auth state
+the AdonisJS host already resolved (via `@adonis-agora/authkit-client`) and shares
+with Inertia as a page prop — then gives you typed hooks, role helpers, gating
+components and ready-made account UI on top.
+
+## Setup
+
+Share the `authkit` prop from the host, typically in `config/inertia.ts`:
+
+```ts
+// config/inertia.ts
+import { defineConfig } from '@adonisjs/inertia'
+
+export default defineConfig({
+  sharedData: {
+    authkit: async (ctx) => {
+      const auth = ctx.authkit // your Authenticator instance
+      const user = await auth.getUser() // same shape as identityToUser/resolveUser
+      return {
+        user: user ?? null,
+        globalRoles: auth.identity?.globalRoles ?? [],
+      }
+    },
+  },
+})
+```
+
+Then consume it in any component:
+
+```tsx
+import { useAuth } from '@adonis-agora/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>
+  )
+}
+```
+
+Source: `packages/authkit-react/README.md` §§ 1–2.
+
+## Core patterns
+
+### Pattern 1 — role gating with `Authenticated` / `Guest`
+
+```tsx
+import { Authenticated, Guest } from '@adonis-agora/authkit-react'
+
+<Authenticated fallback={<LoginButton />}>
+  <Dashboard />
+</Authenticated>
+
+<Guest>
+  <MarketingBanner />
+</Guest>
+```
+
+For pure functions outside components:
+
+```ts
+import { hasGlobalRole, hasAnyGlobalRole, hasAllGlobalRoles } from '@adonis-agora/authkit-react'
+
+hasGlobalRole(user, 'ADMIN')
+hasAnyGlobalRole(user, ['ADMIN', 'TEACHER'])
+```
+
+Source: `packages/authkit-react/README.md` §§ 3 and "Helpers puros".
+
+### Pattern 2 — `AuthProvider` outside Inertia
+
+In tests or Storybook there are no page props; inject state manually. Context takes
+precedence over Inertia props when present:
+
+```tsx
+import { AuthProvider } from '@adonis-agora/authkit-react'
+
+<AuthProvider value={{ user, globalRoles: user.globalRoles }}>
+  <App />
+</AuthProvider>
+```
+
+Source: `packages/authkit-react/README.md` § 4.
+
+### Pattern 3 — `AuthkitProvider` + ready components
+
+Wrap the app once to configure URLs/CSRF, then use headless hooks and prebuilt
+components that talk to the host-kit's JSON endpoints:
+
+```tsx
+import '@adonis-agora/authkit-react/styles.css'
+import {
+  AuthkitProvider,
+  useSignIn, useSignOut,
+  UserButton, UserProfile, AuthorizedApps,
+} from '@adonis-agora/authkit-react'
+
+<AuthkitProvider config={{ csrfToken: page.props.csrfToken }}>
+  <UserButton />
+  <UserProfile />
+  <AuthorizedApps />
+</AuthkitProvider>
+```
+
+Endpoint defaults point at real host-kit routes (`/auth/login`, `/account/logout`,
+`/account/security/profile`, `/account/apps`, …). In a *client-app* topology point
+them at local routes that redirect/proxy to the IdP; theming via CSS vars
+`--authkit-*`.
+
+Source: `packages/authkit-react/README.md` § 5, `src/config.ts` (`DEFAULT_CONFIG`,
+`AuthkitConfig`).
+
+### Pattern 4 — third-party IdP mode
+
+When the backend authenticates against another IdP (via
+`@adonis-agora/authkit-client`), declare it so data-dependent components degrade
+instead of calling endpoints that do not exist:
+
+```tsx
+<AuthkitProvider config={{ idp: 'external' }}>
+  {/* works: SignInButton, SignOutButton, useAuth, Avatar */}
+  {/* degrades to null: UserProfile, OrganizationSwitcher, AuthorizedApps */}
+</AuthkitProvider>
+```
+
+Source: `src/config.ts` (`AuthkitIdpMode` JSDoc).
+
+## Common mistakes
+
+### HIGH — Never sharing the `authkit` prop from the host
+
+```ts
+// Wrong — no sharedData; every page renders unauthenticated
+export default defineConfig({ sharedData: {} })
+```
+
+```ts
+// Correct — share { user, globalRoles } under the `authkit` key
+sharedData: {
+  authkit: async (ctx) => {
+    const auth = ctx.authkit
+    return {
+      user: (await auth.getUser()) ?? null,
+      globalRoles: auth.identity?.globalRoles ?? [],
+    }
+  },
+}
+```
+
+`useAuth()` deliberately never throws on a missing prop — it falls back to
+unauthenticated state (`user: null`, empty lists, dev-only console.warn), so a host
+that forgot the prop ships a UI where nobody ever appears logged in.
+
+Source: `src/use_auth.ts` (fallback + warn), README § 1.
+
+### MEDIUM — Feeding a user object that does not match `AuthUser`
+
+```ts
+// Wrong — raw token claims passed as the user
+sharedData: { authkit: async (ctx) => ({ user: await ctx.authkit.getIdentity() }) }
+```
+
+```ts
+// Correct — resolveUser/identityToUser output satisfies AuthUser
+const user = await ctx.authkit.getUser()
+return { user: user ?? null, globalRoles: ctx.authkit.identity?.globalRoles ?? [] }
+```
+
+The prop's `user` must match `{ id, email, name?, avatarUrl?, globalRoles }` —
+exactly what `identityToUser`/`resolveUser` produce. Raw identity claims lack that
+shape and break typed consumers downstream.
+
+Source: `packages/authkit-react/README.md` § 1 ("O objeto `user` deve corresponder ao
+tipo `AuthUser`").
+
+### MEDIUM — Expecting `<Can>` / permission gating here
+
+```tsx
+// Wrong — looking for app-permission gating in authkit-react
+import { Can } from '@adonis-agora/authkit-react' // not exported
+```
+
+```tsx
+// Correct — global-role gates come from authkit; permissions live in authz-react
+import { Authenticated } from '@adonis-agora/authkit-react'
+import { CanPermission } from '@adonis-agora/authz-react' // consults the Authz service
+```
+
+App-role/permission gating migrated to `@adonis-agora/authz-react`; this package
+gates only on authentication and token-level `globalRoles`. (`useCan`/
+`CanPermission` exist here only as thin callers of the `/authz/can` endpoint.)
+
+Source: `packages/authkit-react/README.md` § 3 callout, `index.ts`
+(`useCan`, `CanPermission`, `canPath` endpoint).
+
+See also: `authkit-rp-client/SKILL.md` — the host-side resolver choices decide what
+reaches the `authkit` prop.