najm-auth 3.0.0 → 3.1.1

package/README.md

@@ -198,13 +198,13 @@ All routes are prefixed with `/auth` and auto-registered by the plugin.
 
 ### 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.
+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.
@@ -249,10 +249,10 @@ await authService.provisionUser({
 });
 ```
 
-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.
+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:
 
@@ -743,6 +743,174 @@ 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.
+
+### `auth.ts` and `session.ts` cannot be merged
+
+Two files looks like one too many until you try it. Both directions fail, for
+the same reason in mirror image:
+
+| Module | Must be reachable from | Must never be reachable from |
+|---|---|---|
+| the `defineAuth()` module | browser, Edge, server | — |
+| the `createReactServerAuth()` module | server only | browser, Edge |
+
+`auth.client` and `auth.api` are what Client Components call, and
+`auth.middleware` is what the Edge proxy calls, so the `defineAuth()` module is
+always in the browser and Edge graphs. The adapter must never be. Putting both
+in one file puts the adapter everywhere `auth` already is, and the `browser`
+export condition — which exists precisely to catch this — resolves to a module
+that throws:
+
+```text
+The export createReactServerAuth was not found in module
+  …/najm-auth/dist/client/server/reactClientGuard.js [app-client]
+
+Import traces:
+  Middleware:               ./src/lib/auth.ts → ./src/proxy.ts
+  Client Component Browser: ./src/lib/auth.ts → … → ./src/app/dashboard/page.tsx
+  Client Component SSR:     ./src/lib/auth.ts → … → ./src/app/dashboard/page.tsx
+  Server Component:         ./src/lib/auth.ts → ./src/lib/session.ts → layout.tsx
+```
+
+Renaming the files changes nothing; there simply have to be two. This is a
+property of the runtime boundary, not of the package.
+
+### Protected trees must opt out of prerendering
+
+`requireSession()` reads a per-request cookie. A route Next.js tries to
+prerender has no request, so the read fails and the guard reports a
+configuration error — correct behavior, wrong context. Mark the protected
+segment dynamic:
+
+```tsx
+// src/app/(dashboard)/layout.tsx
+export const dynamic = 'force-dynamic';
+
+export default async function DashboardLayout({ children }) {
+  await serverAuth.requireSession();
+  return <Shell>{children}</Shell>;
+}
+```
+
+`getSession()` needs no such opt-out — it returns `null` rather than throwing,
+so a prerendered public page renders anonymous. Do not "fix" a prerender failure
+by wrapping a strict guard in `.catch(() => null)`; that turns a real outage
+into a silently anonymous page.
+
+### What the app owns, what the package owns
+
+| App, via `defineAuth()` | Package |
+|---|---|
+| `loginRoute`, `forbiddenRoute`, route matchers, `roleRoutes` | when to redirect where |
+| cookie names, `apiBaseURL`, `authPrefix`, recovery URL | request memoization |
+| `refreshThreshold`, `tabSync`, `verifyAlways` | strict vs optional semantics |
+| — | `session.roles` / `user.role` fallback |
+| — | error classification |
+
+If a new app has to copy anything beyond the three files above, that logic
+belongs in the package instead.
+
+### What a new app must prove
+
+At its real Next.js production boundary, not with mocks:
+
+- two concurrent renders never observe each other's session;
+- root layout, nested layout, and page resolve once per render — measurable by
+  counting recovery round trips;
+- anonymous navigation to a protected route redirects to `loginRoute`;
+- an authenticated role mismatch reaches `forbiddenRoute` without a login loop;
+- an unset session secret or an unreachable recovery endpoint stays a visible
+  failure rather than a login redirect;
+- the Edge/proxy bundle builds without pulling in React.
+
+---
+
 ## TypeScript Types
 
 ```typescript

package/dist/NajmAuthClient-DqGucYXi.d.ts

@@ -0,0 +1,120 @@
+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;
+    credentials?: RequestCredentials;
+    timeout?: number;
+    getToken?: () => string | null;
+    onUnauthorized?: () => Promise<string | null>;
+    retry?: RetryConfig;
+    defaultHeaders?: Record<string, string>;
+}
+declare class FetchClient {
+    private config;
+    constructor(config: FetchClientConfig);
+    get<T>(path: string, opts?: RequestOptions): Promise<T>;
+    post<T>(path: string, opts?: RequestOptions): Promise<T>;
+    put<T>(path: string, opts?: RequestOptions): Promise<T>;
+    patch<T>(path: string, opts?: RequestOptions): Promise<T>;
+    delete<T>(path: string, opts?: RequestOptions): Promise<T>;
+    private request;
+    private execute;
+    private doFetch;
+    private parseBody;
+}
+
+interface HydrateSession {
+    user: AuthUser | null;
+    accessToken?: string | null;
+    roles?: string[];
+    permissions?: string[];
+}
+declare class NajmAuthClient {
+    private config;
+    private static readonly MAX_REFRESH_FAILURES;
+    private static readonly CIRCUIT_RESET_MS;
+    private state;
+    private refreshTimer;
+    private refreshCircuitTimer;
+    private refreshPromise;
+    private fetchUserPromise;
+    private refreshFailures;
+    private _hydrated;
+    private listeners;
+    private eventListeners;
+    private tabSync;
+    api: FetchClient;
+    private readonly prefix;
+    private readonly threshold;
+    constructor(config: AuthClientConfig);
+    login(credentials: LoginCredentials): Promise<LoginResult>;
+    register(data: Record<string, unknown>): Promise<AuthUser>;
+    getOAuthLoginUrl(provider: OAuthProvider, options?: OAuthLoginOptions): string;
+    loginWithOAuth(provider: OAuthProvider, options?: OAuthLoginOptions): void;
+    loginWithGoogle(options?: OAuthLoginOptions): void;
+    linkOAuthAccount(provider: OAuthProvider, options?: OAuthLoginOptions): Promise<void>;
+    completeOAuthLogin(): Promise<AuthUser>;
+    logout(): Promise<void>;
+    refresh(): Promise<void>;
+    fetchUser(): Promise<AuthUser | null>;
+    private _doFetchUser;
+    forgotPassword(data: {
+        email: string;
+    }): Promise<void>;
+    changePassword(data: {
+        currentPassword: string;
+        newPassword: string;
+    }): Promise<void>;
+    resetPassword(data: {
+        token: string;
+        newPassword: string;
+    }): Promise<void>;
+    can(permission: string): boolean;
+    hasRole(role: string): boolean;
+    hasAnyRole(roles: string[]): boolean;
+    hasPermission(permission: string): boolean;
+    getUser(): AuthUser | null;
+    getAccessToken(): string | null;
+    isAuthenticated(): boolean;
+    getState(): AuthState;
+    /**
+     * Hydrate the client with a session resolved server-side.
+     * Use to skip the initial loading flicker on SSR-rendered pages.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    hydrate(session: HydrateSession | null): void;
+    isHydrated(): boolean;
+    /**
+     * A fresh client with the same config — unhydrated, and without tab sync.
+     *
+     * Server rendering needs one client per request. A single process serves
+     * every user, so the hydration latch on a shared client would otherwise pin
+     * every later render to the first request's session.
+     */
+    fork(): NajmAuthClient;
+    on<K extends AuthEvent>(event: K, handler: AuthEventHandler<K>): void;
+    off<K extends AuthEvent>(event: K, handler: AuthEventHandler<K>): void;
+    subscribe(listener: (state: AuthState) => void): () => void;
+    destroy(): void;
+    private _refreshWithCircuit;
+    private _doRefresh;
+    private handleUnauthorized;
+    private applyTokens;
+    private scheduleRefresh;
+    private clearRefreshTimer;
+    private clearRefreshCircuitTimer;
+    private resetRefreshFailures;
+    private registerRefreshFailure;
+    private resetState;
+    private getSyncPayload;
+    private handleTabMessage;
+    private notify;
+    private emit;
+    private validateReturnTo;
+}
+/**
+ * Factory function to create an auth client.
+ */
+declare function createAuthClient(config: AuthClientConfig): NajmAuthClient;
+
+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-D2fSvQ_H.js';
-export { A as AuthClientConfig, a as AuthError, b as AuthEvent, c as AuthEventHandler, d as AuthEventMap, e as AuthState, f as AuthUser, g as AuthenticatedLogin, C as CredentialSetupPending, F as FetchClient, H as HydrateSession, L as LoginCredentials, h as LoginResult, N as NajmAuthClient, O as OAuthLoginOptions, i as OAuthProvider, R as RequestOptions, j as RetryConfig, k as ServerResponse, l as TokenPair, m as createAuthClient } from '../NajmAuthClient-D2fSvQ_H.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/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, h as LoginResult, a as AuthError, L as LoginCredentials, O as OAuthLoginOptions, b as AuthEvent, d as AuthEventMap } from '../../NajmAuthClient-D2fSvQ_H.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;

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

@@ -1,6 +1,10 @@
-import { f as AuthUser, F as FetchClient, N as NajmAuthClient, j as RetryConfig } from '../../NajmAuthClient-D2fSvQ_H.js';
-import { SessionRecoveryFailure } from '../edge.js';
-export { SessionRecoveryErrorDetails, SessionRecoveryFailureReason, withAuthMiddleware } from '../edge.js';
+import { A as AuthUser, R as RetryConfig } from '../../types-BaSfgxqE.js';
+import { F as FetchClient, N as NajmAuthClient } from '../../NajmAuthClient-DqGucYXi.js';
+export { withAuthMiddleware } from '../edge.js';
+import { G as GetSessionConfig, S as ServerSession$1 } from '../../getSession-BthP85UA.js';
+export { A as AuthConfigError, a as AuthTransportError, N as NoSessionError, g as getSession } from '../../getSession-BthP85UA.js';
+import { S as SessionRecoveryFailure } from '../../sessionRecovery-D5Fa0yZ1.js';
+export { a as SessionRecoveryErrorDetails, b as SessionRecoveryFailureReason } from '../../sessionRecovery-D5Fa0yZ1.js';
 import 'next/server';
 
 interface GetServerSessionOptions {
@@ -11,7 +15,7 @@ interface GetServerSessionOptions {
     /** Additional headers to forward (e.g., Authorization) */
     headers?: Record<string, string>;
 }
-interface ServerSession$1 {
+interface ServerSession {
     user: AuthUser;
 }
 /**
@@ -35,7 +39,7 @@ interface ServerSession$1 {
  * }
  * ```
  */
-declare function getServerSession(opts: GetServerSessionOptions): Promise<ServerSession$1 | null>;
+declare function getServerSession(opts: GetServerSessionOptions): Promise<ServerSession | null>;
 
 interface ServerClientConfig {
     /** API base URL (e.g., 'http://localhost:3000/api') */
@@ -65,70 +69,6 @@ interface ServerClientConfig {
  */
 declare function createServerClient(config: ServerClientConfig): FetchClient;
 
-interface ServerSession {
-    user: AuthUser;
-    roles?: string[];
-    permissions?: string[];
-}
-interface GetSessionConfig {
-    /**
-     * Base URL for auth endpoints.
-     * Defaults to `NEXT_PUBLIC_API_URL` or the same-origin `/api` path.
-     */
-    baseURL?: string;
-    /** Auth route prefix appended to baseURL (default: '/auth'). */
-    authPrefix?: string;
-    /** Refresh token cookie name (default: 'refreshToken'). */
-    cookieName?: string;
-    /** Signed session cookie name (default: 'najm.session'). */
-    sessionCookieName?: string;
-    /**
-     * Secret used to verify the session cookie HMAC signature.
-     * Falls back to NAJM_SESSION_SECRET or JWT_ACCESS_SECRET env vars.
-     */
-    sessionSecret?: string;
-    /**
-     * Maximum accepted session-cookie age in seconds.
-     * Must match the auth plugin's `session.maxAge`. Default: 300.
-     */
-    sessionMaxAge?: number;
-    /**
-     * Session-recovery endpoint. Defaults to
-     * `${baseURL}${authPrefix}/session/recover`. Set to false to disable fallback.
-     */
-    recoveryURL?: string | false;
-    /** Loopback-only recovery endpoint for self-hosted reverse-proxy setups. */
-    internalRecoveryURL?: string;
-    /**
-     * Error handling mode:
-     * - 'nullable' (default): returns null on any failure
-     * - 'strict': throws typed errors for debugging
-     */
-    mode?: 'nullable' | 'strict';
-    /** Secret-free diagnostic hook for failed recovery attempts. */
-    onRecoveryFailure?: (failure: SessionRecoveryFailure) => void;
-}
-declare class NoSessionError extends Error {
-    readonly code = "NO_SESSION";
-    constructor(message?: string);
-}
-declare class AuthConfigError extends Error {
-    readonly code = "AUTH_CONFIG_ERROR";
-    constructor(message: string);
-}
-declare class AuthTransportError extends Error {
-    readonly status?: number;
-    readonly code = "AUTH_TRANSPORT_ERROR";
-    constructor(message: string, status?: number);
-}
-/**
- * Resolve a session in a Next.js Server Component, Route Handler, or Server
- * Action. Recovery returns claims for the current render but cannot persist
- * response cookies during Server Component rendering; middleware performs that
- * persistence for protected navigation.
- */
-declare function getSession(config?: GetSessionConfig): Promise<ServerSession | null>;
-
 interface WithAuthOptions extends GetSessionConfig {
     /** Where to redirect unauthenticated requests (default: '/login') */
     redirectTo?: string;
@@ -138,7 +78,7 @@ interface WithAuthOptions extends GetSessionConfig {
     permission?: string;
 }
 interface WithAuthProps<P> {
-    session: ServerSession;
+    session: ServerSession$1;
     props: P;
 }
 /**
@@ -219,9 +159,9 @@ interface AuthKit {
     /** Shortcut for `client.api` — the underlying FetchClient with auth attached. */
     readonly api: FetchClient;
     /** Resolve session — signed-cookie first, then non-rotating recovery. */
-    getSession: (opts?: Pick<GetSessionConfig, 'mode'>) => Promise<ServerSession | null>;
+    getSession: (opts?: Pick<GetSessionConfig, 'mode'>) => Promise<ServerSession$1 | null>;
     /** Require session — throws if unauthenticated */
-    requireSession: () => Promise<ServerSession>;
+    requireSession: () => Promise<ServerSession$1>;
     /**
      * Require one of `roles` — redirects to `loginRoute` when unauthenticated and
      * to `forbiddenRoute` when authenticated as the wrong role.
@@ -230,7 +170,7 @@ interface AuthKit {
      * const session = await auth.requireRole(['admin', 'operator']);
      * ```
      */
-    requireRole: (roles: string[]) => Promise<ServerSession>;
+    requireRole: (roles: string[]) => Promise<ServerSession$1>;
     /** Generated Next.js middleware function */
     middleware: (request: Request) => Promise<Response>;
     /** Next.js middleware config with matcher */
@@ -242,7 +182,7 @@ interface AuthKit {
      * Passes session to the wrapped component.
      */
     protect: <P extends Record<string, unknown> = Record<string, unknown>>(Page: (args: {
-        session: ServerSession;
+        session: ServerSession$1;
         children?: unknown;
     } & P) => Promise<unknown> | unknown, options?: {
         role?: string;
@@ -332,4 +272,4 @@ declare function makeSessionCookie(setCookie: string, authCookieNames?: string[]
  */
 declare function withAuthCookiePersistence(handler: RequestHandler, options?: AuthCookiePersistenceOptions): RequestHandler;
 
-export { AuthConfigError, type AuthCookiePersistenceOptions, type AuthKit, AuthTransportError, type DefineAuthConfig, type GetSessionConfig, NoSessionError, type SafeRedirectOptions, type ServerSession, SessionRecoveryFailure, type WithAuthOptions, type WithAuthProps, createServerClient, defineAuth, getSafeRedirectPath, getServerSession, getSession, makeSessionCookie, withAuth, withAuthCookiePersistence };
+export { type AuthCookiePersistenceOptions, type AuthKit, type DefineAuthConfig, GetSessionConfig, type SafeRedirectOptions, ServerSession$1 as ServerSession, SessionRecoveryFailure, type WithAuthOptions, type WithAuthProps, createServerClient, defineAuth, getSafeRedirectPath, getServerSession, makeSessionCookie, withAuth, withAuthCookiePersistence };