dauth-context-react 5.0.0 → 6.0.0

package/README.md

@@ -1,54 +1,52 @@
 # dauth-context-react
 
-React context provider and hook for token-based authentication with the [Dauth](https://dauth.ovh) service. Provides `DauthProvider` and `useDauth()` hook for seamless integration of Dauth tenant authentication into React applications.
+React context provider and hook for passwordless authentication with the [dauth](https://dauth.ovh) service. Uses the BFF (Backend-for-Frontend) pattern with httpOnly cookies -- no tokens are exposed to the browser. Provides `DauthProvider` and `useDauth()` for seamless integration of dauth tenant authentication into React applications.
 
 ## Installation
 
 ```bash
 npm install dauth-context-react
 # or
-yarn add dauth-context-react
+pnpm add dauth-context-react
 ```
 
-### Peer Dependencies
+Peer dependency: `react` >= 16.
 
-- `react` >= 16
+## Tech Stack
 
-## Quick Start
+| Technology | Version | Purpose |
+|---|---|---|
+| React | >= 16 | Peer dependency |
+| TypeScript | 5.9 | Type safety |
+| tsup | 8 | Build tool (CJS + ESM bundles) |
+| vitest | 4 | Testing framework |
+| size-limit | 12 | Bundle size budget (10KB per entry) |
+
+## Usage
 
 ### 1. Wrap your app with `DauthProvider`
 
 ```tsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { RouterProvider } from 'react-router-dom';
 import { DauthProvider } from 'dauth-context-react';
+import { RouterProvider } from 'react-router-dom';
 import router from './router/router';
 
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <DauthProvider
-    domainName="your-domain-name"
-    tsk="your-tenant-secret-key"
-  >
-    <RouterProvider router={router} fallbackElement={<></>} />
-  </DauthProvider>
-);
+function App() {
+  return (
+    <DauthProvider domainName="your-domain-name">
+      <RouterProvider router={router} fallbackElement={<></>} />
+    </DauthProvider>
+  );
+}
 ```
 
-### 2. Use the `useDauth()` hook in your components
+### 2. Use the `useDauth()` hook
 
 ```tsx
 import { useDauth } from 'dauth-context-react';
 
 function MyComponent() {
-  const {
-    isAuthenticated,
-    isLoading,
-    user,
-    loginWithRedirect,
-    logout,
-    getAccessToken,
-  } = useDauth();
+  const { isAuthenticated, isLoading, user, loginWithRedirect, logout } = useDauth();
 
   if (isLoading) return <div>Loading...</div>;
 
@@ -65,230 +63,105 @@ function MyComponent() {
 }
 ```
 
-## API
-
-### `<DauthProvider>`
-
-| Prop | Type | Description |
-|---|---|---|
-| `domainName` | `string` | Your Dauth domain name (used for API routing and tenant resolution) |
-| `tsk` | `string` | Tenant Secret Key for JWT verification |
-| `children` | `React.ReactNode` | Child components |
-
-### `useDauth()` Hook
-
-Returns the current authentication state and action methods:
-
-| Property | Type | Description |
-|---|---|---|
-| `user` | `IDauthUser` | Authenticated user object |
-| `domain` | `IDauthDomainState` | Domain configuration (name, loginRedirect, allowedOrigins) |
-| `isLoading` | `boolean` | `true` while initial auth check is in progress |
-| `isAuthenticated` | `boolean` | `true` if user is authenticated |
-| `loginWithRedirect` | `() => void` | Redirects to the Dauth tenant sign-in page |
-| `logout` | `() => void` | Clears token and resets auth state |
-| `getAccessToken` | `() => Promise<string>` | Returns a fresh access token (refreshes if needed) |
-| `updateUser` | `(fields: Partial<IDauthUser>) => Promise<boolean>` | Updates user profile fields |
-| `updateUserWithRedirect` | `() => void` | Redirects to the Dauth user update page |
-| `sendEmailVerification` | `() => Promise<boolean>` | Sends a verification email to the user |
-| `sendEmailVerificationStatus` | `{ status: IActionStatus, isLoading: boolean }` | Status of the email verification request |
-
-### `IDauthUser`
-
-```typescript
-interface IDauthUser {
-  _id: string;
-  name: string;
-  lastname: string;
-  nickname: string;
-  email: string;
-  isVerified: boolean;
-  language: string;
-  avatar: { id: string; url: string };
-  role: string;
-  telPrefix: string;
-  telSuffix: string;
-  birthDate?: Date;
-  country?: string;
-  metadata?: any;
-  createdAt: Date;
-  updatedAt: Date;
-  lastLogin: Date;
-}
-```
-
-## Real-World Integration Example
-
-This is the pattern used in `easymediacloud-frontend-react`, which delegates all user authentication to Dauth.
-
-### 1. Provider hierarchy in `App.tsx`
-
-```tsx
-// src/App.tsx
-import { DauthProvider } from 'dauth-context-react';
-import { LicensesProvider } from './context/licenses/LicensesProvider';
-import { RouterProvider } from 'react-router-dom';
-import router from './router/router';
-import config from './config/config';
-
-function App() {
-  return (
-    <DauthProvider
-      domainName={config.services.dauth.DOMAIN_NAME as string}
-      tsk={config.services.dauth.TSK as string}
-    >
-      <LicensesProvider>
-        <RouterProvider router={router} fallbackElement={<></>} />
-      </LicensesProvider>
-    </DauthProvider>
-  );
-}
-```
-
-Environment variables (`.env.development`):
-```
-REACT_APP_DAUTH_DOMAIN_NAME=your-domain-name
-REACT_APP_DAUTH_TSK=your-tenant-secret-key
-```
-
-### 2. Route protection with `EnsureAuthenticated`
-
-```tsx
-// src/router/middlewares.tsx
-import { useEffect } from 'react';
-import { useNavigate } from 'react-router-dom';
-import { useDauth } from 'dauth-context-react';
-import { routes } from './routes';
-
-export function EnsureAuthenticated({ children }: { children: React.ReactNode }) {
-  const { isAuthenticated, isLoading } = useDauth();
-  const navigate = useNavigate();
-
-  useEffect(() => {
-    if (!isAuthenticated && !isLoading) {
-      navigate(routes.home);
-    }
-  }, [isAuthenticated, isLoading, navigate]);
-
-  return <>{children}</>;
-}
-
-// In router config:
-{
-  path: '/license/:id',
-  element: (
-    <EnsureAuthenticated>
-      <LicenseDetail />
-    </EnsureAuthenticated>
-  ),
-}
-```
-
-### 3. Passing tokens to API calls from a context provider
-
-```tsx
-// src/context/licenses/LicensesProvider.tsx
-import { useCallback, useReducer } from 'react';
-import { useDauth } from 'dauth-context-react';
+### 3. Implement the backend proxy
 
-function LicensesProvider({ children }: { children: React.ReactNode }) {
-  const [state, dispatch] = useReducer(licenseReducer, initialState);
-  const { getAccessToken } = useDauth();
+Your backend must implement 6 endpoints at `authProxyPath` (default `/api/auth`) that proxy requests to the dauth backend and manage httpOnly session cookies. The [`dauth-md-node`](https://www.npmjs.com/package/dauth-md-node) package provides a ready-made Express router for this.
 
-  const getLicenses = useCallback(async () => {
-    const token = await getAccessToken();
-    const { data } = await fetchLicenses(token);
-    dispatch({ type: 'SET_LICENSES', payload: data });
-  }, [getAccessToken]);
+### Authentication flow
 
-  const createLicense = useCallback(async (name: string) => {
-    const token = await getAccessToken();
-    await postLicense({ name, token });
-  }, [getAccessToken]);
-
-  return (
-    <LicensesContext.Provider value={{ ...state, getLicenses, createLicense }}>
-      {children}
-    </LicensesContext.Provider>
-  );
-}
-```
+1. **On mount**: checks for `?code=` in the URL. If present, exchanges the code for a session via `POST {authProxyPath}/exchange-code`. If absent, checks for an existing session via `GET {authProxyPath}/session`.
+2. **Login**: `loginWithRedirect()` navigates to `{dauthUrl}/{domainName}/signin`. After authentication, dauth redirects back with `?code=`.
+3. **Logout**: calls `POST {authProxyPath}/logout` and resets context state.
+4. **CSRF**: mutating requests read the CSRF token from cookie and send it as `X-CSRF-Token` header.
+5. **Localhost detection**: auto-routes to `localhost:5185` in development, `https://dauth.ovh` in production. Override with `dauthUrl` prop.
 
-### 4. Using `useDauth()` in components
+## API Reference
 
-```tsx
-// src/views/components/ProfileIcon.tsx
-import { useDauth } from 'dauth-context-react';
+### `<DauthProvider>` props
 
-function ProfileIcon() {
-  const { user, isAuthenticated, loginWithRedirect, logout, updateUserWithRedirect } = useDauth();
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `domainName` | `string` | yes | - | Tenant identifier used in the signin redirect URL |
+| `children` | `React.ReactNode` | yes | - | Child components |
+| `authProxyPath` | `string` | no | `'/api/auth'` | Base path of the auth proxy on the consumer's backend |
+| `onError` | `(error: Error) => void` | no | `console.error` | Error callback for failed auth operations |
+| `env` | `string` | no | - | Environment name appended as `?env=` to the signin redirect URL |
+| `dauthUrl` | `string` | no | auto-detected | Override the dauth frontend URL (e.g. `'https://dev.dauth.ovh'` for staging) |
 
-  return (
-    <Popover title={user.email}>
-      {isAuthenticated ? (
-        <>
-          <Avatar src={user.avatar?.url} />
-          <button onClick={updateUserWithRedirect}>My Profile</button>
-          <button onClick={logout}>Logout</button>
-        </>
-      ) : (
-        <button onClick={loginWithRedirect}>Login</button>
-      )}
-    </Popover>
-  );
-}
-```
+### `useDauth()` return value
 
-### 5. Language sync from dauth user
+| Property | Type | Description |
+|---|---|---|
+| `user` | `IDauthUser` | Authenticated user object |
+| `domain` | `IDauthDomainState` | Domain configuration (name, loginRedirect, allowedOrigins, authMethods) |
+| `isLoading` | `boolean` | `true` while the initial auth check is in progress |
+| `isAuthenticated` | `boolean` | `true` if the user has a valid session |
+| `loginWithRedirect` | `() => void` | Redirects to the dauth tenant sign-in page |
+| `logout` | `() => void` | Clears the session (server-side + context reset) |
+| `updateUser` | `(fields: Partial<IDauthUser>) => Promise<boolean>` | Updates user profile fields via the proxy |
+| `updateUserWithRedirect` | `() => void` | Redirects to the dauth profile editing page |
+| `deleteAccount` | `() => Promise<boolean>` | Deletes the user account |
 
-```tsx
-// src/views/layouts/LayoutBasic.tsx
-import { useDauth } from 'dauth-context-react';
-import i18n from 'i18next';
+### Backend proxy endpoints
 
-function LayoutMain() {
-  const { user } = useDauth();
+Your backend must implement these at `authProxyPath`:
 
-  useEffect(() => {
-    i18n.changeLanguage(user.language);
-  }, [user.language]);
+| Method | Path | Purpose |
+|---|---|---|
+| `POST` | `/exchange-code` | Exchange authorization code for tokens, set httpOnly cookies |
+| `GET` | `/session` | Verify session cookie, return user + domain data |
+| `POST` | `/logout` | Clear session cookies |
+| `PATCH` | `/user` | Forward user profile updates to dauth |
+| `DELETE` | `/user` | Forward account deletion to dauth |
+| `GET` | `/profile-redirect` | Return redirect URL to the dauth profile page |
+
+### Exported types
+
+- `IDauthUser` -- user object (name, email, avatar, role, language, etc.)
+- `IDauthDomainState` -- domain config (name, environments, loginRedirect, allowedOrigins, authMethods)
+- `IDauthState` -- full context value
+- `IDauthProviderProps` -- provider props
+- `IDauthAuthMethods` -- auth methods config (`magicLink`, `passkey`)
+- `IActionStatus` -- status object (type, message)
+
+## Scripts
+
+| Script | Description |
+|---|---|
+| `pnpm start` | Watch mode (tsup --watch) |
+| `pnpm build` | Production build (CJS + ESM + types) |
+| `pnpm test` | Run vitest tests (80 tests) |
+| `pnpm test:coverage` | Coverage report (v8, 70% threshold) |
+| `pnpm typecheck` | TypeScript type checking |
+| `pnpm size` | Check bundle size (10KB budget per entry) |
+| `pnpm format` | Prettier formatting |
+
+## Testing
+
+80 tests across 6 files using vitest 4 with @testing-library/react (jsdom environment).
 
-  return <Outlet />;
-}
+```bash
+pnpm test
+pnpm test:coverage
 ```
 
-## How It Works
+## Publishing
 
-1. **On mount:** Checks the URL for a redirect token (`?dauth_state=...`), then attempts auto-login from localStorage.
-2. **Token refresh:** Proactively refreshes the access token before expiry (5 minutes before). Falls back to periodic refresh every 5 minutes if decode fails.
-3. **Localhost detection:** Automatically routes API calls to `localhost:4012` during development (detects `localhost`, `127.0.0.1`, `[::1]`, and `192.168.x.x`) and to `https://dauth.ovh` in production.
-4. **Token storage:** Access token stored in localStorage under `dauth_state`, refresh token under `dauth_refresh_token`.
-
-## Development
+Automated via GitHub Actions. Push a `v*` tag to trigger build, test, and `npm publish`.
 
 ```bash
-pnpm start         # Watch mode (tsdx watch)
-pnpm build         # Production build (CJS + ESM)
-pnpm test          # Run Jest tests
-pnpm lint          # ESLint via tsdx
-pnpm size          # Check bundle size (10KB budget per entry)
-pnpm analyze       # Bundle size analysis with visualization
+# 1. Bump version in package.json
+# 2. Commit and tag
+git tag v5.0.1
+git push origin main --tags
+# 3. GitHub Actions publishes to npm automatically
 ```
 
-### Bundle Outputs
-
-- **CJS:** `dist/index.js` (with `.development.js` and `.production.min.js` variants)
-- **ESM:** `dist/dauth-context-react.esm.js`
-- **Types:** `dist/index.d.ts`
-
-### CI/CD
-
-- **CI**: GitHub Actions runs lint, test, and build on push to `main` and PRs. Self-hosted runner, Node 22.
-- **Publish**: Automated npm publish on `v*` tags via GitHub Actions.
+Requires `NPM_TOKEN` secret configured in the GitHub repo.
 
-## Author
+## Code Style
 
-David T. Pizarro Frick
+Prettier: 80 char width, single quotes, semicolons, trailing commas (es5), 2-space indent.
 
 ## License
 

package/dist/index.d.mts

@@ -30,12 +30,17 @@ interface IDauthAuthMethods {
     magicLink: boolean;
     passkey: boolean;
 }
+interface IFormField {
+    field: string;
+    required: boolean;
+}
 interface IDauthDomainState {
     name: string;
     environments?: IDauthDomainEnvironment[];
     loginRedirect: string;
     allowedOrigins: string[];
     authMethods?: IDauthAuthMethods;
+    formFields?: IFormField[];
 }
 interface IDauthState {
     user: IDauthUser;
@@ -45,9 +50,12 @@ interface IDauthState {
     loginWithRedirect: () => void;
     logout: () => void;
     updateUser: (fields: Partial<IDauthUser>) => Promise<boolean>;
-    updateUserWithRedirect: () => void;
     deleteAccount: () => Promise<boolean>;
 }
+interface DauthProfileModalProps {
+    open: boolean;
+    onClose: () => void;
+}
 interface IDauthProviderProps {
     domainName: string;
     children: React.ReactNode;
@@ -59,7 +67,9 @@ interface IDauthProviderProps {
     dauthUrl?: string;
 }
 
+declare function DauthProfileModal({ open, onClose }: DauthProfileModalProps): React$1.ReactPortal | null;
+
 declare const DauthProvider: React$1.FC<IDauthProviderProps>;
 declare const useDauth: () => IDauthState;
 
-export { DauthProvider, type IDauthAuthMethods, type IDauthProviderProps, useDauth };
+export { DauthProfileModal, type DauthProfileModalProps, DauthProvider, type IDauthAuthMethods, type IDauthProviderProps, type IFormField, useDauth };

package/dist/index.d.ts

@@ -30,12 +30,17 @@ interface IDauthAuthMethods {
     magicLink: boolean;
     passkey: boolean;
 }
+interface IFormField {
+    field: string;
+    required: boolean;
+}
 interface IDauthDomainState {
     name: string;
     environments?: IDauthDomainEnvironment[];
     loginRedirect: string;
     allowedOrigins: string[];
     authMethods?: IDauthAuthMethods;
+    formFields?: IFormField[];
 }
 interface IDauthState {
     user: IDauthUser;
@@ -45,9 +50,12 @@ interface IDauthState {
     loginWithRedirect: () => void;
     logout: () => void;
     updateUser: (fields: Partial<IDauthUser>) => Promise<boolean>;
-    updateUserWithRedirect: () => void;
     deleteAccount: () => Promise<boolean>;
 }
+interface DauthProfileModalProps {
+    open: boolean;
+    onClose: () => void;
+}
 interface IDauthProviderProps {
     domainName: string;
     children: React.ReactNode;
@@ -59,7 +67,9 @@ interface IDauthProviderProps {
     dauthUrl?: string;
 }
 
+declare function DauthProfileModal({ open, onClose }: DauthProfileModalProps): React$1.ReactPortal | null;
+
 declare const DauthProvider: React$1.FC<IDauthProviderProps>;
 declare const useDauth: () => IDauthState;
 
-export { DauthProvider, type IDauthAuthMethods, type IDauthProviderProps, useDauth };
+export { DauthProfileModal, type DauthProfileModalProps, DauthProvider, type IDauthAuthMethods, type IDauthProviderProps, type IFormField, useDauth };