najm-auth 2.0.14 → 3.0.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
 
@@ -727,52 +849,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-D2fSvQ_H.d.ts}

@@ -50,6 +50,34 @@ interface TokenPair {
     accessTokenExpiresAt?: number;
     refreshTokenExpiresAt?: number;
 }
+/**
+ * Login credentials. `identifier` accepts an email address or a phone number;
+ * `email` stays supported for existing callers.
+ */
+interface LoginCredentials {
+    identifier?: string;
+    email?: string;
+    password: string;
+    /** Persist the auth cookies past the browser closing. */
+    rememberMe?: boolean;
+    [key: string]: unknown;
+}
+/** The account must replace its credential before it gets a session. */
+interface CredentialSetupPending {
+    nextStep: 'credential_setup';
+    setupRequired: true;
+    purpose: string;
+    expiresAt: string;
+}
+interface AuthenticatedLogin {
+    nextStep: 'authenticated';
+    user: AuthUser;
+}
+/**
+ * Login answer. Branch on `nextStep`: `credential_setup` carries no tokens and
+ * leaves the client unauthenticated.
+ */
+type LoginResult = AuthenticatedLogin | CredentialSetupPending;
 /**
  * Retry configuration
  */
@@ -182,10 +210,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 +280,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 { type AuthClientConfig as A, type CredentialSetupPending as C, type DecodedToken as D, FetchClient as F, type HydrateSession as H, type LoginCredentials as L, 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 AuthenticatedLogin as g, type LoginResult as h, type OAuthProvider as i, type RetryConfig as j, type ServerResponse as k, type TokenPair as l, createAuthClient as m };

package/dist/client/index.d.ts

@@ -1,5 +1,5 @@
-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';
+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';
 
 /**
  * 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,7 @@
 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, 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';
 
 interface AuthProviderProps {
     client: NajmAuthClient;
@@ -79,14 +79,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");

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

@@ -1,4 +1,4 @@
-import { f as AuthUser, F as FetchClient, N as NajmAuthClient, h as RetryConfig } from '../../NajmAuthClient-Cn9bObLB.js';
+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 'next/server';
@@ -169,6 +169,16 @@ interface DefineAuthConfig {
     loginRoute?: string;
     /** Route to redirect after login (default: '/dashboard') */
     afterLoginRoute?: string;
+    /**
+     * Where an *authenticated* user goes when their role is not allowed
+     * (default: '/forbidden').
+     *
+     * Distinct from `loginRoute` on purpose. Sending them to the login form says
+     * "prove who you are" to someone who already has; they log in again, land
+     * back on the same page, and get bounced again. A forbidden page is the only
+     * response that terminates.
+     */
+    forbiddenRoute?: string;
     /** Routes that are always public (glob patterns) */
     publicRoutes?: string[];
     /** Routes that require authentication (glob patterns) */
@@ -212,6 +222,15 @@ interface AuthKit {
     getSession: (opts?: Pick<GetSessionConfig, 'mode'>) => Promise<ServerSession | null>;
     /** Require session — throws if unauthenticated */
     requireSession: () => Promise<ServerSession>;
+    /**
+     * Require one of `roles` — redirects to `loginRoute` when unauthenticated and
+     * to `forbiddenRoute` when authenticated as the wrong role.
+     *
+     * ```ts
+     * const session = await auth.requireRole(['admin', 'operator']);
+     * ```
+     */
+    requireRole: (roles: string[]) => Promise<ServerSession>;
     /** Generated Next.js middleware function */
     middleware: (request: Request) => Promise<Response>;
     /** Next.js middleware config with matcher */
@@ -232,4 +251,85 @@ interface AuthKit {
 }
 declare function defineAuth(authConfig?: DefineAuthConfig): AuthKit;
 
-export { AuthConfigError, type AuthKit, AuthTransportError, type DefineAuthConfig, type GetSessionConfig, NoSessionError, type ServerSession, SessionRecoveryFailure, type WithAuthOptions, type WithAuthProps, createServerClient, defineAuth, getServerSession, getSession, withAuth };
+interface SafeRedirectOptions {
+    /** Where to send anything rejected. Defaults to `/dashboard`. */
+    fallback?: string;
+    /**
+     * Path prefixes that are never a valid destination. Defaults to `/api`,
+     * `/login` and `/_next`.
+     *
+     * `/login` is on the list because bouncing back to it is the redirect loop
+     * this parameter causes most often: a user who just authenticated is sent
+     * straight back to the form they came from.
+     */
+    blockedPrefixes?: string[];
+}
+/**
+ * Reduces an untrusted `?next=` value to a path that is safe to redirect to.
+ *
+ * Only same-origin *paths* survive. An absolute URL is rejected outright rather
+ * than parsed and compared, because the comparison is where this goes wrong:
+ * `//evil.test` is a protocol-relative URL that browsers resolve off-site while
+ * a naive `startsWith('/')` check reads it as local. Anything that is not a
+ * single leading slash followed by a path is refused.
+ *
+ * ```ts
+ * redirect(getSafeRedirectPath(searchParams.next, { fallback: '/home' }));
+ * ```
+ */
+declare function getSafeRedirectPath(value: string | string[] | undefined | null, options?: SafeRedirectOptions | string): string;
+
+type RequestHandler = (request: Request) => Promise<Response>;
+interface AuthCookiePersistenceOptions {
+    /**
+     * Cookies whose lifetime this rewrites. Defaults to the two najm-auth issues.
+     * Anything not named here is passed through untouched.
+     */
+    authCookieNames?: string[];
+    /** Where the one-bit choice is stored. Defaults to `najm.remember`. */
+    rememberCookieName?: string;
+    /** How long a remembered choice lasts. Defaults to 7 days. */
+    maxAgeSeconds?: number;
+    /** Paths whose JSON body carries `rememberMe`. Defaults to `/api/auth/login`. */
+    loginPaths?: string[];
+    /** Paths that end a session and clear the choice. Defaults to `/api/auth/logout`. */
+    logoutPaths?: string[];
+    /** Paths that reissue cookies and must reapply the stored choice. */
+    refreshPaths?: string[];
+    /**
+     * Paths that finish credential setup. The stored choice is cleared there:
+     * the login it was recorded for never produced a session.
+     */
+    setupCompletionPaths?: string[];
+    /**
+     * Recognizes a response that has *not* issued a usable session because the
+     * user must still set up credentials.
+     *
+     * Najm's own setup response is recognized without this — supply it only to
+     * cover an application-specific shape. Such a response may carry auth
+     * cookies anyway, and persisting them would leave a half-authenticated
+     * browser that skips the setup step on reload. Returning `true` strips them
+     * and clears the stored choice.
+     */
+    isSetupResponse?: (payload: unknown) => boolean;
+}
+/**
+ * Strips the lifetime attributes so the browser drops the cookie when it closes.
+ *
+ * Only the named auth cookies are touched — rewriting an unrelated `Set-Cookie`
+ * from the same response would be a silent side effect on someone else's state.
+ */
+declare function makeSessionCookie(setCookie: string, authCookieNames?: string[]): string;
+/**
+ * Wraps a request handler so the auth cookies it issues match the user's
+ * "remember me" choice.
+ *
+ * ```ts
+ * // app/api/[...route]/route.ts
+ * const handler = withAuthCookiePersistence((req) => server.fetch(req));
+ * export { handler as GET, handler as POST };
+ * ```
+ */
+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 };