najm-auth 2.0.15 → 3.1.0

package/README.md

@@ -9,6 +9,8 @@ Production-ready authentication and authorization library for the Najm framework
 - ✅ Permission-based access control (PBAC) with wildcards
 - ✅ Row-level ownership scoping for multi-tenant apps
 - ✅ Built-in password reset flow with email support
+- ✅ Forced first-login credential setup for provisioned accounts
+- ✅ Country identity presets so `06…` and `+2126…` resolve to one account
 - ✅ Multi-dialect support (PostgreSQL, SQLite)
 - ✅ Type-safe decorators with TypeScript
 - ✅ Rate limiting on auth endpoints
@@ -45,7 +47,7 @@ export const products = sqliteTable('products', {
 
 // Combined schema (always include authSchema)
 export const schema = {
-  ...authSchema,  // includes users, tokens, and credentialSetupSessions
+  ...authSchema,  // includes users, tokens, and credentialSetupSessions
   products,
 };
 
@@ -134,6 +136,21 @@ auth({
   // Frontend
   frontendUrl?: string                     // Password reset link base URL
 
+  // Login identifier normalization (see "Identity presets")
+  identity?: {
+    preset?: 'ma' | 'tn' | IdentityPreset | null   // Default: 'ma'
+    extend?: IdentityNormalizer[]                  // Runs before the preset
+  }
+
+  // Credential setup policy overrides (the flow itself is always on)
+  credentialSetup?: {
+    password?: {
+      passwordSchema?: ZodType<string>     // Default: 8-72 bytes, a letter and a digit
+      ttlMs?: number                       // Default: 600000 (10 minutes)
+      cookieName?: string                  // Default: 'najm.credential-setup'
+    }
+  }
+
   // Optional Google OpenID Connect
   oauth?: {
     google?: true | {
@@ -175,6 +192,89 @@ All routes are prefixed with `/auth` and auto-registered by the plugin.
 | `GET` | `/auth/oauth/google/start` | Start Google sign-in | None |
 | `GET` | `/auth/oauth/google/callback` | Verify Google callback and create Najm session | None |
 | `POST` | `/auth/oauth/google/link` | Link Google to the current user | ✅ Required |
+| `GET` | `/auth/credential-setup/setup` | Read the pending setup session | Setup cookie |
+| `POST` | `/auth/credential-setup/change` | Replace the temporary credential | Setup cookie |
+| `POST` | `/auth/credential-setup/cancel` | Abandon the setup session | Setup cookie |
+
+### Identity presets
+
+Login lookup, lockout accounting, and rate-limit bucketing all normalize the
+submitted identifier the same way. The pipeline is: email (lowercased) →
+project extensions → the country preset → generic E.164.
+
+The resolved pipeline belongs to the specific `auth()` plugin/server instance.
+Multiple isolated Najm servers can therefore use different country presets in
+one process without replacing each other's login or rate-limit behavior.
+
+Morocco is the default, so `0612345678`, `212612345678`, and `+212612345678`
+all resolve to `+212612345678` with no configuration.
+
+```typescript
+auth();                                                  // preset: 'ma'
+auth({ identity: { extend: [employeeNumberNormalizer] } });
+auth({ identity: { preset: 'tn' } });                    // replaces Morocco
+auth({ identity: { preset: null, extend: [custom] } });  // generic only
+```
+
+Local numbers are country-ambiguous, so presets **replace** each other rather
+than stacking — two presets claiming `06…` would resolve one raw input to two
+different accounts.
+
+### First-login credential setup
+
+Provision an account with a temporary credential and Najm refuses it a normal
+session until the holder replaces it:
+
+```typescript
+import { moroccanCinTemporaryCredential } from 'najm-auth/identity/ma';
+
+await authService.provisionUser({
+  email: guardian.email,
+  phone: guardian.phone,
+  role: 'family',
+  temporaryCredential: moroccanCinTemporaryCredential(guardian.cin),
+  requireCredentialSetup: 'password',
+});
+```
+
+`temporaryCredential` also accepts a plain string, compared exactly and
+case-sensitively — enough for a student or registration number:
+
+```typescript
+await authService.provisionUser({
+  email: student.schoolEmail,
+  role: 'student',
+  temporaryCredential: student.registrationNumber,
+  requireCredentialSetup: 'password',
+});
+```
+
+Supplying both `password` and `temporaryCredential` is rejected, so an account
+can never hold a permanent password that something also treats as temporary.
+Typed helpers such as `moroccanCinTemporaryCredential()` validate their value,
+and every temporary credential remains limited to bcrypt's 72-byte boundary.
+
+Login then answers a discriminated result instead of a token pair:
+
+```typescript
+const result = await auth.client.login({ identifier, password, rememberMe });
+
+if (result.nextStep === 'credential_setup') {
+  router.push('/change-password');   // no tokens were issued
+} else {
+  router.push('/dashboard');
+}
+```
+
+The requirement is enforced at every session-establishment path — password
+login, `AuthSessionService.establish()`, Google OAuth (which redirects with
+`oauthError=oauth_credential_setup_required`), refresh, and signed-session
+recovery — so verified-email OAuth linking cannot skip it. Marking a new
+requirement also revokes the user's current sessions.
+
+`withAuthCookiePersistence` recognizes the setup response on its own: it drops
+any session cookies the response carried, clears the remembered preference, and
+leaves the opaque setup cookie alone.
 
 ### Google Sign-In
 
@@ -502,12 +602,34 @@ oauth_accounts
 ├── providerAccountId (Google `sub`)
 ├── unique(provider, providerAccountId)
 └── unique(userId, provider)
+
+credential_setup_sessions
+├── id (string, primary key)
+├── userId (string, FK → users.id, cascade delete)
+├── purpose (string)
+├── tokenHash (string, unique — SHA-256 of the browser cookie)
+├── expiresAt (timestamp)
+├── consumedAt (timestamp, nullable)
+└── revokedAt (timestamp, nullable)
+
+credential_setup_requirements
+├── userId (string, FK → users.id, cascade delete)
+├── purpose (string; `password` for the built-in flow)
+├── temporaryCredentialKind (string, nullable; `exact` or `ma-cin`)
+├── required (boolean, default: true)
+├── completedAt (timestamp, nullable)
+└── primary key (userId, purpose)
 ```
 
+`credential_setup_requirements` is keyed on `(userId, purpose)` rather than
+`userId` alone, so one user can owe more than one future setup purpose.
+
 Existing databases must generate and run a migration after upgrading so the
-new `oauth_accounts` table exists. Custom `AuthSchema` objects may omit
-`oauthAccounts` while OAuth is disabled, but Google configuration fails fast
-unless the custom schema supplies it.
+new `oauth_accounts`, `credential_setup_sessions`, and
+`credential_setup_requirements` tables exist. Custom `AuthSchema` objects may
+omit `oauthAccounts` while OAuth is disabled, but Google configuration fails
+fast unless the custom schema supplies it. Both credential-setup tables are
+required of a custom schema, because the setup flow is always mounted.
 
 ### ID Strategy
 
@@ -621,6 +743,95 @@ auth({
 
 ---
 
+## Next.js App Router Structure
+
+Every App Router application keeps the same three files. Copying more than this
+between apps means logic that belongs in the package has leaked into them.
+
+```text
+src/lib/auth.ts     defineAuth() configuration — browser, server, and proxy safe
+src/lib/session.ts  one createReactServerAuth() instance for Server Components
+src/proxy.ts        imports auth.ts only, and exports auth.middleware
+```
+
+```typescript
+// src/lib/auth.ts
+import { defineAuth } from 'najm-auth/client/server';
+
+export const auth = defineAuth({
+  apiBaseURL: '/api',
+  loginRoute: '/login',
+  forbiddenRoute: '/forbidden',
+  publicRoutes: ['/', '/login'],
+  protectedRoutes: ['/dashboard/:path*', '/admin/:path*'],
+  roleRoutes: { '/admin/:path*': ['admin'] },
+});
+```
+
+```typescript
+// src/lib/session.ts
+import 'server-only';
+
+import { createReactServerAuth } from 'najm-auth/client/server/react';
+
+import { auth } from './auth';
+
+export const serverAuth = createReactServerAuth(auth);
+```
+
+```typescript
+// src/proxy.ts
+import { auth } from './lib/auth';
+
+export default auth.middleware;
+export const config = auth.config;
+```
+
+### Why `session.ts` exists
+
+A Next.js page is not one function. The root layout, each nested layout, and the
+page render separately, and each one that asks for the session pays for its own
+cookie verification and possibly its own recovery round trip. React's `cache()`
+collapses those into one — but only for callers that go through the *same*
+memoized function, which means the application has to own one module that
+creates it. `session.ts` is that module and nothing else; strictness, redirect
+targets, role fallback, and error classification all stay in the package.
+
+```tsx
+// Root layout, nested layout, and page: one resolution between them.
+const session = await serverAuth.getSession();      // null when anonymous
+const session = await serverAuth.requireSession();  // redirects to loginRoute
+const session = await serverAuth.requireRole(['admin', 'operator']);
+```
+
+- `requireSession()` redirects to `loginRoute` when the visitor is missing,
+  invalid, or revoked. An unreachable recovery endpoint or an unset session
+  secret is an operational fault, not an anonymous visitor: those stay visible
+  errors instead of becoming a login redirect that hides the outage.
+- `requireRole()` redirects to `forbiddenRoute`, never to login — the visitor is
+  already authenticated, so signing in again cannot change the answer.
+- `session.roles` is authoritative when present, with `user.role` as the
+  single-role fallback.
+
+### Scope and limits
+
+- **React Server Components only.** Route handlers, server actions, proxy/Edge
+  code, and scripts keep using `auth.getSession()`, `auth.requireSession()`, and
+  `auth.requireRole()`. Outside a render there is no request cache for `cache()`
+  to write to, so the adapter would resolve the session again on every call.
+- **Call the factory once, at module scope.** Calling it inside a layout, page,
+  or component builds a fresh memoized resolver per call and shares nothing.
+- **The snapshot is stable for one render.** Code that mutates authentication
+  must redirect or refresh into a new render to observe the result.
+- **Requests never share.** The cache is React's per-request cache — no module
+  map, no global, no Redis, no `unstable_cache`, no `"use cache"`.
+- **Requires React 18.3 or newer** (the first version exporting `cache()`); the
+  factory throws a named error on older versions. The subpath is opt-in, so
+  non-React consumers of `najm-auth` are unaffected. Importing it from a Client
+  Component or the Edge runtime fails at build time.
+
+---
+
 ## TypeScript Types
 
 ```typescript
@@ -727,52 +938,52 @@ async resetPassword(token: string, newPassword: string) {
 }
 ```
 
-### Purpose-Bound Credential Setup
-
-Use `CredentialSetupService` when valid credentials should open only a
-short-lived setup flow, not a complete application session. The default auth
-schema includes the durable `credential_setup_sessions` table for PostgreSQL
-and SQLite; generate and apply a consumer migration after upgrading.
-
-```typescript
-import { AuthService, CredentialSetupService } from 'najm-auth';
-
-const options = {
-  purpose: 'password-setup',
-  cookieName: 'my-app.password-setup',
-  ttlMs: 10 * 60 * 1000,
-};
-
-// Verify the password without minting access/refresh tokens.
-const user = await authService.verifyCredentials({ identifier, password });
-
-// Or narrowly accept only an unverified pending account with one exact role.
-const pendingSponsor = await authService.verifyPendingCredentials(
-  { identifier, password },
-  'sponsor',
-);
-
-if (await appRequiresPasswordSetup(user.id)) {
-  // Revokes normal sessions and writes only an HttpOnly, SameSite=Strict,
-  // browser-session cookie. The database stores only its SHA-256 hash.
-  return credentialSetup.begin(user.id, options);
-}
-
-return authService.establishSession(user);
-
-// Complete an app-owned mutation in the same transaction as one-time
-// consumption. If the callback fails, token consumption rolls back.
-await credentialSetup.consume(options, async ({ userId }) => {
-  await replaceApplicationCredential(userId, newCredential);
-});
-```
-
-Setup tokens are bound to a server-owned purpose, expire automatically, are
-replaced when the same user starts that purpose again, and can be cancelled or
-consumed exactly once. `require()` validates the current setup cookie without
-consuming it; `cancel()` revokes it and clears the cookie.
-
-### Session Management
+### Purpose-Bound Credential Setup
+
+Use `CredentialSetupService` when valid credentials should open only a
+short-lived setup flow, not a complete application session. The default auth
+schema includes the durable `credential_setup_sessions` table for PostgreSQL
+and SQLite; generate and apply a consumer migration after upgrading.
+
+```typescript
+import { AuthService, CredentialSetupService } from 'najm-auth';
+
+const options = {
+  purpose: 'password-setup',
+  cookieName: 'my-app.password-setup',
+  ttlMs: 10 * 60 * 1000,
+};
+
+// Verify the password without minting access/refresh tokens.
+const user = await authService.verifyCredentials({ identifier, password });
+
+// Or narrowly accept only an unverified pending account with one exact role.
+const pendingSponsor = await authService.verifyPendingCredentials(
+  { identifier, password },
+  'sponsor',
+);
+
+if (await appRequiresPasswordSetup(user.id)) {
+  // Revokes normal sessions and writes only an HttpOnly, SameSite=Strict,
+  // browser-session cookie. The database stores only its SHA-256 hash.
+  return credentialSetup.begin(user.id, options);
+}
+
+return authService.establishSession(user);
+
+// Complete an app-owned mutation in the same transaction as one-time
+// consumption. If the callback fails, token consumption rolls back.
+await credentialSetup.consume(options, async ({ userId }) => {
+  await replaceApplicationCredential(userId, newCredential);
+});
+```
+
+Setup tokens are bound to a server-owned purpose, expire automatically, are
+replaced when the same user starts that purpose again, and can be cancelled or
+consumed exactly once. `require()` validates the current setup cookie without
+consuming it; `cancel()` revokes it and clears the cookie.
+
+### Session Management
 
 - Sessions are multi-device: the token table stores one refresh row per login session (keyed by a unique `tokenFamily`), so a user can stay logged in on several devices at once. Logout and rotation are scoped to the current session; password change/reset revoke every session
 - A stale refresh token presented after the 120-second rotation grace window revokes only that session's family as reuse protection

package/dist/{NajmAuthClient-Cn9bObLB.d.ts → NajmAuthClient-DqGucYXi.d.ts}

@@ -1,139 +1,4 @@
-/**
- * User data from the auth server
- */
-interface AuthUser {
-    id: string;
-    email: string;
-    name?: string;
-    role?: string | null;
-    permissions?: string[];
-    [key: string]: unknown;
-}
-/**
- * Full auth state snapshot
- */
-interface AuthState {
-    user: AuthUser | null;
-    accessToken: string | null;
-    isAuthenticated: boolean;
-    isLoading: boolean;
-    roles: string[];
-    permissions: string[];
-}
-/**
- * Decoded JWT payload (client-side, no verification)
- */
-interface DecodedToken {
-    userId: string;
-    jti?: string;
-    sessionVersion?: number;
-    roles?: string[];
-    permissions?: string[];
-    exp?: number;
-    iat?: number;
-    [key: string]: unknown;
-}
-/**
- * Server response envelope
- */
-interface ServerResponse<T = unknown> {
-    data: T;
-    message?: string;
-    status?: string;
-}
-/**
- * Token pair from login/refresh (internal — refresh token is httpOnly cookie)
- */
-interface TokenPair {
-    accessToken: string;
-    refreshToken?: string;
-    accessTokenExpiresAt?: number;
-    refreshTokenExpiresAt?: number;
-}
-/**
- * Retry configuration
- */
-interface RetryConfig {
-    maxRetries?: number;
-    backoff?: 'exponential' | 'linear';
-    baseDelay?: number;
-}
-/**
- * Auth client configuration
- */
-interface AuthClientConfig {
-    /** API base URL (e.g., '/api' or 'https://api.example.com') */
-    baseURL: string;
-    /** Auth endpoints prefix (default: '/auth') */
-    authPrefix?: string;
-    /** Proactive refresh at this fraction of token lifetime (default: 0.8) */
-    refreshThreshold?: number;
-    /** Enable multi-tab sync via BroadcastChannel (default: true) */
-    tabSync?: boolean;
-    /** BroadcastChannel name (default: 'najm-auth') */
-    channelName?: string;
-    /** Network retry configuration */
-    retry?: RetryConfig;
-    /** Request timeout in milliseconds (default: 30000) */
-    timeout?: number;
-}
-type OAuthProvider = 'google';
-interface OAuthLoginOptions {
-    /** Same-origin frontend path after OAuth completes. */
-    returnTo?: string;
-}
-/**
- * Auth event types
- */
-interface AuthEventMap {
-    login: AuthUser;
-    logout: null;
-    /** Emitted when server-side logout invalidation fails (state was already cleared) */
-    logoutError: unknown;
-    tokenRefresh: null;
-    sessionExpired: null;
-    stateChange: AuthState;
-    userUpdated: AuthUser;
-}
-type AuthEvent = keyof AuthEventMap;
-type AuthEventHandler<K extends AuthEvent = AuthEvent> = (data: AuthEventMap[K]) => void;
-/**
- * Tab sync message types
- */
-type TabSyncMessage = {
-    type: 'logout';
-} | {
-    type: 'sync';
-    state: SyncPayload;
-};
-interface SyncPayload {
-    accessToken: string | null;
-    user: AuthUser | null;
-    roles: string[];
-    permissions: string[];
-    isAuthenticated: boolean;
-}
-/**
- * FetchClient request options
- */
-interface RequestOptions {
-    body?: unknown;
-    headers?: Record<string, string>;
-    signal?: AbortSignal;
-    timeout?: number;
-    /** Skip auth header attachment (for public endpoints like /login, /register) */
-    skipAuth?: boolean;
-    /** @internal Prevents 401-refresh loop after a single retry */
-    _retried?: boolean;
-}
-/**
- * Auth error thrown by the client
- */
-declare class AuthError extends Error {
-    status: number;
-    body?: unknown;
-    constructor(status: number, message: string, body?: unknown);
-}
+import { R as RetryConfig, a as RequestOptions, A as AuthUser, b as AuthClientConfig, L as LoginCredentials, c as LoginResult, O as OAuthProvider, d as OAuthLoginOptions, e as AuthState, f as AuthEvent, g as AuthEventHandler } from './types-BaSfgxqE.js';
 
 interface FetchClientConfig {
     baseURL: string;
@@ -182,10 +47,7 @@ declare class NajmAuthClient {
     private readonly prefix;
     private readonly threshold;
     constructor(config: AuthClientConfig);
-    login(credentials: {
-        email: string;
-        password: string;
-    }): Promise<AuthUser>;
+    login(credentials: LoginCredentials): Promise<LoginResult>;
     register(data: Record<string, unknown>): Promise<AuthUser>;
     getOAuthLoginUrl(provider: OAuthProvider, options?: OAuthLoginOptions): string;
     loginWithOAuth(provider: OAuthProvider, options?: OAuthLoginOptions): void;
@@ -255,4 +117,4 @@ declare class NajmAuthClient {
  */
 declare function createAuthClient(config: AuthClientConfig): NajmAuthClient;
 
-export { type AuthClientConfig as A, type DecodedToken as D, FetchClient as F, type HydrateSession as H, NajmAuthClient as N, type OAuthLoginOptions as O, type RequestOptions as R, type SyncPayload as S, type TabSyncMessage as T, AuthError as a, type AuthEvent as b, type AuthEventHandler as c, type AuthEventMap as d, type AuthState as e, type AuthUser as f, type OAuthProvider as g, type RetryConfig as h, type ServerResponse as i, type TokenPair as j, createAuthClient as k };
+export { FetchClient as F, type HydrateSession as H, NajmAuthClient as N, createAuthClient as c };

package/dist/client/edge.d.ts

@@ -1,21 +1,6 @@
 import * as next_server from 'next/server';
-
-type SessionRecoveryFailureReason = 'invalid-cookie-name' | 'invalid-refresh-cookie' | 'invalid-endpoint' | 'fetch-error' | 'http-status' | 'missing-set-cookie' | 'session-cookie-parse' | 'session-cookie-hmac' | 'session-cookie-payload';
-interface SessionRecoveryErrorDetails {
-    name: string;
-    message: string;
-    code?: string;
-    cause?: {
-        name: string;
-        message: string;
-        code?: string;
-    };
-}
-interface SessionRecoveryFailure {
-    reason: SessionRecoveryFailureReason;
-    httpStatus?: number;
-    error?: SessionRecoveryErrorDetails;
-}
+import { S as SessionRecoveryFailure } from '../sessionRecovery-D5Fa0yZ1.js';
+export { a as SessionRecoveryErrorDetails, b as SessionRecoveryFailureReason } from '../sessionRecovery-D5Fa0yZ1.js';
 
 interface AuthMiddlewareConfig {
     /** Routes that require authentication (glob patterns) */
@@ -82,4 +67,4 @@ interface AuthMiddlewareConfig {
  */
 declare function withAuthMiddleware(config: AuthMiddlewareConfig): (request: Request) => Promise<next_server.NextResponse<unknown>>;
 
-export { type AuthMiddlewareConfig, type SessionRecoveryErrorDetails, type SessionRecoveryFailure, type SessionRecoveryFailureReason, withAuthMiddleware };
+export { type AuthMiddlewareConfig, SessionRecoveryFailure, withAuthMiddleware };

package/dist/client/index.d.ts

@@ -1,5 +1,6 @@
-import { D as DecodedToken, T as TabSyncMessage, S as SyncPayload } from '../NajmAuthClient-Cn9bObLB.js';
-export { A as AuthClientConfig, a as AuthError, b as AuthEvent, c as AuthEventHandler, d as AuthEventMap, e as AuthState, f as AuthUser, F as FetchClient, H as HydrateSession, N as NajmAuthClient, O as OAuthLoginOptions, g as OAuthProvider, R as RequestOptions, h as RetryConfig, i as ServerResponse, j as TokenPair, k as createAuthClient } from '../NajmAuthClient-Cn9bObLB.js';
+export { F as FetchClient, H as HydrateSession, N as NajmAuthClient, c as createAuthClient } from '../NajmAuthClient-DqGucYXi.js';
+import { D as DecodedToken, T as TabSyncMessage, S as SyncPayload } from '../types-BaSfgxqE.js';
+export { b as AuthClientConfig, h as AuthError, f as AuthEvent, g as AuthEventHandler, i as AuthEventMap, e as AuthState, A as AuthUser, j as AuthenticatedLogin, C as CredentialSetupPending, L as LoginCredentials, c as LoginResult, d as OAuthLoginOptions, O as OAuthProvider, a as RequestOptions, R as RetryConfig, k as ServerResponse, l as TokenPair } from '../types-BaSfgxqE.js';
 
 /**
  * Decode a JWT token payload without verification.

package/dist/client/index.js

@@ -191,6 +191,10 @@ var TabSync = class {
 };
 
 // src/client/NajmAuthClient.ts
+function isCredentialSetupPending(payload) {
+  return typeof payload === "object" && payload !== null && payload.nextStep === "credential_setup";
+}
+__name(isCredentialSetupPending, "isCredentialSetupPending");
 var INITIAL_STATE = {
   user: null,
   accessToken: null,
@@ -242,20 +246,23 @@ var NajmAuthClient = class _NajmAuthClient {
   // Auth Operations
   // =========================================================================
   async login(credentials) {
-    const res = await this.api.post(
-      `${this.prefix}/login`,
-      { body: credentials, skipAuth: true }
-    );
-    this.applyTokens(res.data);
-    if (res.data.user) {
-      this.state = { ...this.state, user: res.data.user };
+    const res = await this.api.post(`${this.prefix}/login`, { body: credentials, skipAuth: true });
+    this.resetRefreshFailures();
+    const setup = isCredentialSetupPending(res) ? res : isCredentialSetupPending(res.data) ? res.data : null;
+    if (setup) {
+      return { ...setup };
+    }
+    const authenticated = res.data;
+    this.applyTokens(authenticated);
+    if (authenticated.user) {
+      this.state = { ...this.state, user: authenticated.user };
       this.notify();
     } else {
       await this.fetchUser();
     }
     this.tabSync?.broadcastSync(this.getSyncPayload());
     this.emit("login", this.state.user);
-    return this.state.user;
+    return { nextStep: "authenticated", user: this.state.user };
   }
   async register(data) {
     const res = await this.api.post(

package/dist/client/react/index.d.ts

@@ -1,7 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode, CSSProperties, ReactElement } from 'react';
-import { N as NajmAuthClient, H as HydrateSession, e as AuthState, f as AuthUser, a as AuthError, O as OAuthLoginOptions, b as AuthEvent, d as AuthEventMap } from '../../NajmAuthClient-Cn9bObLB.js';
+import { N as NajmAuthClient, H as HydrateSession } from '../../NajmAuthClient-DqGucYXi.js';
+import { e as AuthState, A as AuthUser, c as LoginResult, h as AuthError, L as LoginCredentials, d as OAuthLoginOptions, f as AuthEvent, i as AuthEventMap } from '../../types-BaSfgxqE.js';
 
 interface AuthProviderProps {
     client: NajmAuthClient;
@@ -79,14 +80,18 @@ interface UsePermissionsReturn {
 declare function usePermissions(): UsePermissionsReturn;
 
 interface UseLoginOptions {
-    onSuccess?: (user: AuthUser) => void;
+    /** Fires for both branches — check `result.nextStep` before routing. */
+    onSuccess?: (result: LoginResult) => void;
+    /** Fires only for a completed session. */
+    onAuthenticated?: (user: AuthUser) => void;
+    /** Fires when the account must replace its credential first. */
+    onCredentialSetup?: (setup: Extract<LoginResult, {
+        nextStep: 'credential_setup';
+    }>) => void;
     onError?: (error: AuthError | Error) => void;
 }
 interface UseLoginReturn {
-    login: (credentials: {
-        email: string;
-        password: string;
-    }) => Promise<void>;
+    login: (credentials: LoginCredentials) => Promise<LoginResult | undefined>;
     isLoading: boolean;
     error: AuthError | Error | null;
 }

package/dist/client/react/index.js

@@ -157,16 +157,23 @@ function useLogin(opts) {
     setIsLoading(true);
     setError(null);
     try {
-      const user = await client.login(credentials);
-      opts?.onSuccess?.(user);
+      const result = await client.login(credentials);
+      opts?.onSuccess?.(result);
+      if (result.nextStep === "credential_setup") {
+        opts?.onCredentialSetup?.(result);
+      } else {
+        opts?.onAuthenticated?.(result.user);
+      }
+      return result;
     } catch (err) {
       const e = err instanceof Error ? err : new Error(String(err));
       setError(e);
       opts?.onError?.(e);
+      return void 0;
     } finally {
       setIsLoading(false);
     }
-  }, [client, opts?.onSuccess, opts?.onError]);
+  }, [client, opts?.onSuccess, opts?.onAuthenticated, opts?.onCredentialSetup, opts?.onError]);
   return { login, isLoading, error };
 }
 __name(useLogin, "useLogin");