@nauth-toolkit/client 0.1.89 → 0.1.91

package/dist/index.d.mts

@@ -223,6 +223,9 @@ interface ForceChangePasswordResponse extends BaseChallengeResponse {
 
 /**
  * Full user profile returned from profile endpoints.
+ *
+ * Matches UserResponseDto structure from backend.
+ * Used for both user-level and admin-level responses.
  */
 interface AuthUser {
     sub: string;
@@ -233,8 +236,17 @@ interface AuthUser {
     phone?: string | null;
     isEmailVerified: boolean;
     isPhoneVerified: boolean;
-    isActive?: boolean;
-    mfaEnabled?: boolean;
+    isActive: boolean;
+    /**
+     * Account lock status
+     * Locked accounts cannot login until unlocked
+     */
+    isLocked: boolean;
+    mfaEnabled: boolean;
+    /**
+     * MFA exemption status (admin-granted bypass of MFA at login)
+     */
+    mfaExempt?: boolean;
     socialProviders?: string[] | null;
     hasPasswordHash: boolean;
     /**
@@ -244,8 +256,8 @@ interface AuthUser {
      * Use `hasPasswordHash` and `socialProviders` to determine what login methods the account supports.
      */
     sessionAuthMethod?: string | null;
-    createdAt?: string | Date;
-    updatedAt?: string | Date;
+    createdAt: string | Date;
+    updatedAt: string | Date;
 }
 /**
  * Profile update request.
@@ -322,7 +334,7 @@ type SocialProvider = 'google' | 'apple' | 'facebook';
 interface SocialLoginOptions {
     /**
      * Frontend route (recommended) or URL to redirect to after the backend callback completes.
-     * Default: config.redirects.success || '/'
+     * Default: config.redirects.loginSuccess || config.redirects.success || '/'
      */
     returnTo?: string;
     /**
@@ -575,6 +587,45 @@ interface NAuthEndpoints {
     auditHistory: string;
     updateProfile: string;
 }
+/**
+ * Admin endpoint paths for administrative operations.
+ */
+interface NAuthAdminEndpoints {
+    /** POST /signup - Create user */
+    signup: string;
+    /** POST /signup-social - Import social user */
+    signupSocial: string;
+    /** GET /users - List users with filters */
+    getUsers: string;
+    /** GET /users/:sub - Get user by sub */
+    getUser: string;
+    /** DELETE /users/:sub - Delete user */
+    deleteUser: string;
+    /** POST /users/:sub/disable - Disable user account */
+    disableUser: string;
+    /** POST /users/:sub/enable - Enable user account */
+    enableUser: string;
+    /** POST /users/:sub/force-password-change - Force password change */
+    forcePasswordChange: string;
+    /** POST /set-password - Set password for user */
+    setPassword: string;
+    /** POST /reset-password/initiate - Initiate password reset */
+    resetPasswordInitiate: string;
+    /** GET /users/:sub/sessions - Get user sessions */
+    getUserSessions: string;
+    /** POST /users/:sub/logout-all - Logout all sessions */
+    logoutAll: string;
+    /** GET /users/:sub/mfa/status - Get MFA status */
+    getMfaStatus: string;
+    /** POST /mfa/preferred-method - Set preferred MFA method */
+    setPreferredMfaMethod: string;
+    /** POST /mfa/remove-devices - Remove MFA devices */
+    removeMfaDevices: string;
+    /** POST /mfa/exemption - Set MFA exemption */
+    setMfaExemption: string;
+    /** GET /audit/history - Get audit history */
+    getAuditHistory: string;
+}
 /**
  * Context provided to onAuthResponse callback.
  */
@@ -585,6 +636,11 @@ interface AuthResponseContext {
     provider?: string;
     /** Whether this was triggered from a guard */
     fromGuard?: boolean;
+    /**
+     * OAuth appState from social redirect callback.
+     * Only present when source is 'social' and appState was provided in the OAuth flow.
+     */
+    appState?: string;
 }
 /**
  * MFA-specific route configuration.
@@ -604,10 +660,40 @@ interface MfaRoutesConfig {
  */
 interface NAuthRedirectsConfig {
     /**
-     * URL to redirect to after successful authentication (login, signup, or OAuth).
+     * URL to redirect to after successful login (and most non-signup successes).
+     *
+     * Set to `null` to disable SDK auto-navigation.
+     * This is useful when you want to handle routing manually via framework adapters
+     * (e.g., Angular `authEvents$`) without using `onAuthResponse`.
+     *
      * @default '/'
      */
-    success?: string;
+    loginSuccess?: string | null;
+    /**
+     * URL to redirect to after successful signup (when no challenge is returned).
+     *
+     * Notes:
+     * - Challenges (MFA, verify-email, etc.) still route to challenge pages.
+     * - After a challenge completes, the context source becomes `'challenge'`, so
+     *   `loginSuccess` is used for the final success navigation.
+     *
+     * Set to `null` to disable SDK auto-navigation.
+     *
+     * @example Custom onboarding after signup
+     * ```typescript
+     * redirects: {
+     *   loginSuccess: '/dashboard',
+     *   signupSuccess: '/onboarding',
+     * }
+     * ```
+     */
+    signupSuccess?: string | null;
+    /**
+     * Legacy alias for `loginSuccess`.
+     *
+     * @deprecated Use `redirects.loginSuccess` instead.
+     */
+    success?: string | null;
     /**
      * URL to redirect to when session expires (refresh fails with 401).
      * @default '/login'
@@ -815,6 +901,47 @@ interface NAuthClientConfig {
      * ```
      */
     httpAdapter?: HttpAdapter;
+    /**
+     * Admin operations configuration (optional).
+     * If provided, enables client.admin.* methods.
+     *
+     * @example
+     * ```typescript
+     * const client = new NAuthClient({
+     *   baseUrl: 'https://api.example.com/auth',
+     *   tokenDelivery: 'cookies',
+     *   admin: {
+     *     pathPrefix: '/admin',
+     *     endpoints: {
+     *       getUsers: '/users/list',  // Override specific endpoint
+     *     },
+     *     headers: {
+     *       'X-Admin-Context': 'dashboard',
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    admin?: {
+        /**
+         * Path prefix for admin endpoints.
+         * Prepended to all admin endpoint paths.
+         * @default '/admin'
+         * @example '/admin' -> /auth/admin/users
+         */
+        pathPrefix?: string;
+        /**
+         * Custom admin endpoint overrides.
+         * Merged with default admin endpoints.
+         */
+        endpoints?: Partial<NAuthAdminEndpoints>;
+        /**
+         * Additional headers specific to admin requests.
+         * Merged with main client headers.
+         * @example { 'X-Admin-Role': 'super-admin' }
+         */
+        headers?: Record<string, string>;
+    };
 }
 
 /**
@@ -883,14 +1010,634 @@ interface AuthAuditEvent {
     createdAt: string | Date;
 }
 /**
- * Paginated audit history response.
+ * Paginated audit history response.
+ */
+interface AuditHistoryResponse {
+    data: AuthAuditEvent[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+
+/**
+ * Admin user creation request
+ *
+ * Allows administrators to create user accounts with override capabilities:
+ * - Bypass email/phone verification requirements
+ * - Force password change on first login
+ * - Auto-generate secure passwords
+ *
+ * @example
+ * ```typescript
+ * // Create user with pre-verified email
+ * const request: AdminSignupRequest = {
+ *   email: 'user@example.com',
+ *   password: 'SecurePass123!',
+ *   isEmailVerified: true,
+ *   mustChangePassword: false,
+ * };
+ *
+ * // Create user with auto-generated password
+ * const request: AdminSignupRequest = {
+ *   email: 'user@example.com',
+ *   generatePassword: true,
+ *   isEmailVerified: true,
+ *   mustChangePassword: true,
+ * };
+ * ```
+ */
+interface AdminSignupRequest {
+    /**
+     * User email address
+     */
+    email: string;
+    /**
+     * User password
+     * Required unless generatePassword is true
+     */
+    password?: string;
+    /**
+     * Optional username
+     */
+    username?: string;
+    /**
+     * Optional first name
+     */
+    firstName?: string;
+    /**
+     * Optional last name
+     */
+    lastName?: string;
+    /**
+     * Optional phone number (E.164 format)
+     */
+    phone?: string;
+    /**
+     * Optional metadata (custom fields)
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Bypass email verification requirement
+     * Default: false
+     */
+    isEmailVerified?: boolean;
+    /**
+     * Bypass phone verification requirement
+     * Default: false
+     */
+    isPhoneVerified?: boolean;
+    /**
+     * Force password change on first login
+     * Default: false
+     */
+    mustChangePassword?: boolean;
+    /**
+     * Auto-generate secure password
+     * Default: false
+     */
+    generatePassword?: boolean;
+}
+
+/**
+ * Admin user creation response
+ *
+ * Returns the created user object (sanitized, excludes sensitive fields like passwordHash)
+ * and optionally the generated password (only if generatePassword was true in the request).
+ */
+interface AdminSignupResponse {
+    /**
+     * Created user object (same structure as AuthUser)
+     */
+    user: AuthUser;
+    /**
+     * Generated password (only present if generatePassword was true)
+     * Security: This is returned once and never stored in plain text.
+     */
+    generatedPassword?: string;
+}
+/**
+ * Admin social user import request
+ *
+ * Allows administrators to import existing social users from external platforms
+ * (e.g., Cognito, Auth0) with social account linkage.
+ *
+ * @example
+ * ```typescript
+ * // Import social-only user from Cognito
+ * const request: AdminSignupSocialRequest = {
+ *   email: 'user@example.com',
+ *   provider: 'google',
+ *   providerId: 'google_12345',
+ *   providerEmail: 'user@gmail.com',
+ *   socialMetadata: { sub: 'google_12345', given_name: 'John' },
+ * };
+ *
+ * // Import hybrid user with password + social
+ * const request: AdminSignupSocialRequest = {
+ *   email: 'user@example.com',
+ *   password: 'SecurePass123!',
+ *   provider: 'apple',
+ *   providerId: 'apple_67890',
+ * };
+ * ```
+ */
+interface AdminSignupSocialRequest {
+    /**
+     * User email address
+     */
+    email: string;
+    /**
+     * Social provider name
+     */
+    provider: 'google' | 'apple' | 'facebook';
+    /**
+     * Provider's unique user identifier
+     */
+    providerId: string;
+    /**
+     * Provider's email address (optional)
+     */
+    providerEmail?: string;
+    /**
+     * Optional username
+     */
+    username?: string;
+    /**
+     * Optional first name
+     */
+    firstName?: string;
+    /**
+     * Optional last name
+     */
+    lastName?: string;
+    /**
+     * Optional phone number (E.164 format)
+     */
+    phone?: string;
+    /**
+     * Optional password for hybrid social+password accounts
+     */
+    password?: string;
+    /**
+     * Bypass phone verification requirement
+     * Default: false
+     */
+    isPhoneVerified?: boolean;
+    /**
+     * Force password change on first login
+     * Default: false
+     */
+    mustChangePassword?: boolean;
+    /**
+     * Raw OAuth profile data from provider
+     */
+    socialMetadata?: Record<string, unknown>;
+    /**
+     * Optional metadata (custom fields)
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Admin social user import response
+ *
+ * Returns the created user object and social account information for confirmation.
+ */
+interface AdminSignupSocialResponse {
+    /**
+     * Created user object (same structure as AuthUser)
+     */
+    user: AuthUser;
+    /**
+     * Social account information
+     */
+    socialAccount: {
+        /**
+         * Social provider name
+         */
+        provider: string;
+        /**
+         * Provider's unique user identifier
+         */
+        providerId: string;
+        /**
+         * Provider's email address (if available)
+         */
+        providerEmail: string | null;
+    };
+}
+/**
+ * Date filter with operator support
+ *
+ * Supports gt (greater than), gte (greater than or equal), lt (less than),
+ * lte (less than or equal), eq (equal) operators for date comparisons.
+ */
+interface DateFilter {
+    /**
+     * Comparison operator
+     */
+    operator: 'gt' | 'gte' | 'lt' | 'lte' | 'eq';
+    /**
+     * Date value to compare against
+     */
+    value: Date | string;
+}
+/**
+ * Get users request with filters
+ *
+ * Supports pagination, boolean filters, exact match filters,
+ * date filters with operators, and flexible sorting.
+ *
+ * @example
+ * ```typescript
+ * const request: GetUsersRequest = {
+ *   page: 1,
+ *   limit: 20,
+ *   isEmailVerified: true,
+ *   hasSocialAuth: true,
+ *   createdAt: { operator: 'gte', value: new Date('2024-01-01') },
+ *   sortBy: 'email',
+ *   sortOrder: 'ASC',
+ * };
+ * ```
+ */
+interface GetUsersRequest {
+    /**
+     * Page number (1-indexed)
+     * Default: 1
+     */
+    page?: number;
+    /**
+     * Number of records per page
+     * Default: 10, Max: 100
+     */
+    limit?: number;
+    /**
+     * Filter by email address (partial match)
+     */
+    email?: string;
+    /**
+     * Filter by phone number (partial match)
+     */
+    phone?: string;
+    /**
+     * Filter by email verification status
+     */
+    isEmailVerified?: boolean;
+    /**
+     * Filter by phone verification status
+     */
+    isPhoneVerified?: boolean;
+    /**
+     * Filter by social auth presence
+     */
+    hasSocialAuth?: boolean;
+    /**
+     * Filter by account lock status
+     */
+    isLocked?: boolean;
+    /**
+     * Filter by MFA enabled status
+     */
+    mfaEnabled?: boolean;
+    /**
+     * Filter by account creation date
+     */
+    createdAt?: DateFilter;
+    /**
+     * Filter by last update date
+     */
+    updatedAt?: DateFilter;
+    /**
+     * Field to sort by
+     * Default: createdAt
+     */
+    sortBy?: 'email' | 'createdAt' | 'updatedAt' | 'username' | 'phone';
+    /**
+     * Sort order
+     * Default: DESC
+     */
+    sortOrder?: 'ASC' | 'DESC';
+}
+/**
+ * Get users response with pagination
+ *
+ * Uses AuthUser type - admin endpoints return the same sanitized user object as user endpoints.
+ */
+interface GetUsersResponse {
+    /**
+     * Array of sanitized user objects (same as AuthUser)
+     */
+    users: AuthUser[];
+    /**
+     * Pagination metadata
+     */
+    pagination: {
+        /**
+         * Current page number
+         */
+        page: number;
+        /**
+         * Number of records per page
+         */
+        limit: number;
+        /**
+         * Total number of records matching the query
+         */
+        total: number;
+        /**
+         * Total number of pages
+         */
+        totalPages: number;
+    };
+}
+/**
+ * Delete user response
+ *
+ * Returns deletion confirmation with cascade cleanup information.
+ */
+interface DeleteUserResponse {
+    /**
+     * Success indicator
+     */
+    success: boolean;
+    /**
+     * Deleted user ID
+     */
+    deletedUserId: string;
+    /**
+     * Number of related records deleted
+     */
+    deletedRecords: {
+        /**
+         * Number of sessions deleted
+         */
+        sessions: number;
+        /**
+         * Number of verification tokens deleted
+         */
+        verificationTokens: number;
+        /**
+         * Number of MFA devices deleted
+         */
+        mfaDevices: number;
+        /**
+         * Number of trusted devices deleted
+         */
+        trustedDevices: number;
+        /**
+         * Number of social accounts deleted
+         */
+        socialAccounts: number;
+        /**
+         * Number of login attempts deleted
+         */
+        loginAttempts: number;
+        /**
+         * Number of challenge sessions deleted
+         */
+        challengeSessions: number;
+        /**
+         * Number of audit logs deleted
+         */
+        auditLogs: number;
+    };
+}
+/**
+ * Disable user response
+ *
+ * Returns disable confirmation with updated user and revoked session count.
+ */
+interface DisableUserResponse {
+    /**
+     * Success indicator
+     */
+    success: boolean;
+    /**
+     * Updated user object (same as AuthUser)
+     */
+    user: AuthUser;
+    /**
+     * Number of sessions revoked
+     */
+    revokedSessions: number;
+}
+/**
+ * Enable user response
+ *
+ * Returns enable confirmation with updated user.
+ */
+interface EnableUserResponse {
+    /**
+     * Success indicator
+     */
+    success: boolean;
+    /**
+     * Updated user object (same as AuthUser)
+     */
+    user: AuthUser;
+}
+/**
+ * Admin password reset request
+ *
+ * Request for admin-initiated password reset workflow.
+ * Allows resetting a user's password by sub (UUID).
+ *
+ * @example
+ * ```typescript
+ * // With link for consumer app custom UI
+ * const request: AdminResetPasswordRequest = {
+ *   sub: 'a21b654c-2746-4168-acee-c175083a65cd',
+ *   baseUrl: 'https://myapp.com/reset-password',
+ *   deliveryMethod: 'email',
+ *   revokeSessions: true,
+ * };
+ *
+ * // Code only (no link)
+ * const request: AdminResetPasswordRequest = {
+ *   sub: 'a21b654c-2746-4168-acee-c175083a65cd',
+ *   deliveryMethod: 'email',
+ * };
+ * ```
+ */
+interface AdminResetPasswordRequest {
+    /**
+     * User sub (UUID v4)
+     */
+    sub: string;
+    /**
+     * Delivery method for reset code
+     * Default: 'email'
+     */
+    deliveryMethod?: 'email' | 'sms';
+    /**
+     * Base URL for building reset link
+     * Optional: Allows consumer apps to build custom reset UI
+     */
+    baseUrl?: string;
+    /**
+     * Code expiry in seconds
+     * Default: 3600 (1 hour)
+     * Min: 300 (5 minutes), Max: 86400 (24 hours)
+     */
+    codeExpiresIn?: number;
+    /**
+     * Revoke all active sessions immediately (before sending email)
+     * Default: false
+     */
+    revokeSessions?: boolean;
+    /**
+     * Reason for admin-initiated reset (for audit trail)
+     * Max: 500 characters
+     */
+    reason?: string;
+}
+/**
+ * Admin password reset response
+ *
+ * Response for admin-initiated password reset request.
+ */
+interface AdminResetPasswordResponse {
+    /**
+     * Success indicator
+     */
+    success: boolean;
+    /**
+     * Masked destination where code was sent
+     * Example: "u***r@example.com" | "***-***-5678"
+     */
+    destination?: string;
+    /**
+     * Delivery medium used
+     */
+    deliveryMedium?: 'email' | 'sms';
+    /**
+     * Code expiry in seconds
+     */
+    expiresIn?: number;
+    /**
+     * Number of sessions revoked (if revokeSessions was true)
+     */
+    sessionsRevoked?: number;
+}
+/**
+ * Session information in user sessions response
+ */
+interface UserSessionInfo {
+    /**
+     * Session ID
+     */
+    sessionId: string;
+    /**
+     * Device ID
+     */
+    deviceId: string | null;
+    /**
+     * Device name
+     */
+    deviceName: string | null;
+    /**
+     * Device type
+     */
+    deviceType: string | null;
+    /**
+     * Platform
+     */
+    platform: string | null;
+    /**
+     * Browser
+     */
+    browser: string | null;
+    /**
+     * IP address
+     */
+    ipAddress: string | null;
+    /**
+     * IP country
+     */
+    ipCountry: string | null;
+    /**
+     * IP city
+     */
+    ipCity: string | null;
+    /**
+     * Last activity timestamp
+     */
+    lastActivityAt: Date | string;
+    /**
+     * Session creation timestamp
+     */
+    createdAt: Date | string;
+    /**
+     * Session expiration timestamp
+     */
+    expiresAt: Date | string;
+    /**
+     * Whether session is remembered
+     */
+    isRemembered: boolean;
+    /**
+     * Whether this is the current session
+     */
+    isCurrent: boolean;
+    /**
+     * Authentication method used for this session
+     * Examples: 'password', 'social', 'admin', 'admin-social'
+     */
+    authMethod: string | null;
+    /**
+     * OAuth provider name (only present for social logins)
+     * Examples: 'google', 'facebook', 'github', 'apple'
+     */
+    authProvider: string | null;
+}
+/**
+ * Get user sessions response
+ */
+interface GetUserSessionsResponse {
+    /**
+     * Array of user sessions
+     */
+    sessions: UserSessionInfo[];
+}
+/**
+ * Admin audit history request
+ *
+ * Request for getting user authentication history (admin-only).
+ *
+ * @example
+ * ```typescript
+ * const request: AdminAuditHistoryRequest = {
+ *   sub: 'user-uuid',
+ *   page: 1,
+ *   limit: 50,
+ *   eventType: 'LOGIN_SUCCESS',
+ *   eventStatus: 'SUCCESS',
+ * };
+ * ```
  */
-interface AuditHistoryResponse {
-    data: AuthAuditEvent[];
-    total: number;
-    page: number;
-    limit: number;
-    totalPages: number;
+interface AdminAuditHistoryRequest {
+    /**
+     * User's unique identifier (UUID v4)
+     * Required for admin operations
+     */
+    sub: string;
+    /**
+     * Page number (1-indexed)
+     */
+    page?: number;
+    /**
+     * Number of records per page
+     */
+    limit?: number;
+    /**
+     * Filter by event type
+     */
+    eventType?: string;
+    /**
+     * Filter by event status
+     */
+    eventStatus?: string;
 }
 
 /**
@@ -1177,11 +1924,20 @@ type ResolvedNAuthClientConfig = Omit<NAuthClientConfig, 'endpoints' | 'storage'
     };
     headers: Record<string, string>;
     timeout: number;
+    admin?: {
+        pathPrefix: string;
+        endpoints: NAuthAdminEndpoints;
+        headers: Record<string, string>;
+    };
 };
 /**
  * Default endpoint paths matching backend controller.
  */
 declare const defaultEndpoints: NAuthEndpoints;
+/**
+ * Default admin endpoint paths matching backend admin controller.
+ */
+declare const defaultAdminEndpoints: NAuthAdminEndpoints;
 /**
  * Normalize user config with defaults.
  *
@@ -1233,7 +1989,8 @@ declare const resolveConfig: (config: NAuthClientConfig, defaultAdapter: HttpAda
  */
 declare class ChallengeRouter {
     private config;
-    constructor(config: ResolvedNAuthClientConfig);
+    private oauthStorage;
+    constructor(config: ResolvedNAuthClientConfig, oauthStorage: NAuthStorageAdapter);
     /**
      * Handle auth response - either call callback or auto-navigate.
      *
@@ -1241,6 +1998,18 @@ declare class ChallengeRouter {
      * @param context - Context about the auth operation
      */
     handleAuthResponse(response: AuthResponse, context: AuthResponseContext): Promise<void>;
+    /**
+     * Resolve the configured success URL based on context and explicit override keys.
+     *
+     * IMPORTANT:
+     * - `null` explicitly disables auto-navigation (caller should rely on framework events / custom routing).
+     * - `undefined` / missing keys fall back to other configured values or defaults.
+     * - Falls back to legacy `redirects.success` when new keys are not set.
+     *
+     * @param context - Auth response context
+     * @returns URL string, or null when auto-navigation is disabled
+     */
+    private resolveSuccessUrl;
     /**
      * Navigate to appropriate challenge route.
      *
@@ -1251,15 +2020,20 @@ declare class ChallengeRouter {
      * Navigate to success URL.
      *
      * @param queryParams - Optional query parameters to append to the success URL
+     * @param context - Optional auth context for selecting the success route
      *
      * @example
      * ```typescript
      * await router.navigateToSuccess({ appState: 'invite-code-123' });
      * ```
      */
-    navigateToSuccess(queryParams?: Record<string, string>): Promise<void>;
+    navigateToSuccess(queryParams?: Record<string, string | null | undefined>, context?: AuthResponseContext): Promise<void>;
     /**
-     * Retrieve stored OAuth appState from storage.
+     * Retrieve stored OAuth appState from sessionStorage.
+     *
+     * NOTE: This method does NOT clear the storage. Only the public getLastOauthState() API clears it.
+     * This allows the SDK to read appState for auto-navigation while still making it available to
+     * consumers via the public API.
      *
      * @returns Query params object with appState if present, undefined otherwise
      */
@@ -1313,6 +2087,429 @@ declare class ChallengeRouter {
     getChallengeUrl(response: AuthResponse): string;
 }
 
+/**
+ * Admin operations for user and system management.
+ * Accessed via client.admin.*
+ *
+ * Provides admin-level operations including:
+ * - User CRUD operations
+ * - Password management (set, reset)
+ * - Session management
+ * - MFA management
+ * - Audit history
+ *
+ * @example
+ * ```typescript
+ * const client = new NAuthClient({
+ *   baseUrl: 'https://api.example.com/auth',
+ *   tokenDelivery: 'cookies',
+ *   admin: {
+ *     pathPrefix: '/admin'
+ *   }
+ * });
+ *
+ * // User management
+ * const user = await client.admin.createUser({
+ *   email: 'user@example.com',
+ *   password: 'SecurePass123!',
+ *   isEmailVerified: true,
+ * });
+ *
+ * // Get users with filters
+ * const users = await client.admin.getUsers({
+ *   page: 1,
+ *   limit: 20,
+ *   mfaEnabled: false
+ * });
+ *
+ * // Delete user (handles :sub path param)
+ * await client.admin.deleteUser('user-uuid');
+ * ```
+ */
+declare class AdminOperations {
+    private readonly config;
+    private readonly adminEndpoints;
+    private readonly adminPathPrefix;
+    private readonly adminHeaders;
+    /**
+     * Create admin operations instance.
+     *
+     * @param config - Resolved client configuration
+     */
+    constructor(config: ResolvedNAuthClientConfig);
+    /**
+     * Create a new user (admin operation)
+     *
+     * Allows creating users with:
+     * - Pre-verified email/phone
+     * - Auto-generated passwords
+     * - Force password change flag
+     *
+     * @param request - User creation request
+     * @returns Created user and optional generated password
+     * @throws {NAuthClientError} If creation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.createUser({
+     *   email: 'user@example.com',
+     *   password: 'SecurePass123!',
+     *   isEmailVerified: true,
+     * });
+     *
+     * // With auto-generated password
+     * const result = await client.admin.createUser({
+     *   email: 'user@example.com',
+     *   generatePassword: true,
+     *   mustChangePassword: true,
+     * });
+     * console.log('Generated password:', result.generatedPassword);
+     * ```
+     */
+    createUser(request: AdminSignupRequest): Promise<AdminSignupResponse>;
+    /**
+     * Import social user (admin operation)
+     *
+     * Imports existing social users from external platforms (e.g., Cognito, Auth0)
+     * with social account linkage.
+     *
+     * @param request - Social user import request
+     * @returns Created user and social account info
+     * @throws {NAuthClientError} If import fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.importSocialUser({
+     *   email: 'user@example.com',
+     *   provider: 'google',
+     *   providerId: 'google_12345',
+     *   providerEmail: 'user@gmail.com',
+     * });
+     * ```
+     */
+    importSocialUser(request: AdminSignupSocialRequest): Promise<AdminSignupSocialResponse>;
+    /**
+     * Get users with filters and pagination
+     *
+     * @param params - Filter and pagination params
+     * @returns Paginated user list
+     * @throws {NAuthClientError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.getUsers({
+     *   page: 1,
+     *   limit: 20,
+     *   isEmailVerified: true,
+     *   mfaEnabled: false,
+     *   sortBy: 'createdAt',
+     *   sortOrder: 'DESC',
+     * });
+     * ```
+     */
+    getUsers(params?: GetUsersRequest): Promise<GetUsersResponse>;
+    /**
+     * Get user by sub (UUID)
+     *
+     * @param sub - User UUID
+     * @returns User object
+     * @throws {NAuthClientError} If user not found
+     *
+     * @example
+     * ```typescript
+     * const user = await client.admin.getUser('a21b654c-2746-4168-acee-c175083a65cd');
+     * ```
+     */
+    getUser(sub: string): Promise<AuthUser>;
+    /**
+     * Delete user with cascade cleanup
+     *
+     * @param sub - User UUID
+     * @returns Deletion confirmation with cascade counts
+     * @throws {NAuthClientError} If deletion fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.deleteUser('user-uuid');
+     * console.log('Deleted records:', result.deletedRecords);
+     * ```
+     */
+    deleteUser(sub: string): Promise<DeleteUserResponse>;
+    /**
+     * Disable user account (permanent lock)
+     *
+     * @param sub - User UUID
+     * @param reason - Optional reason for disabling
+     * @returns Disable confirmation with revoked session count
+     * @throws {NAuthClientError} If operation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.disableUser(
+     *   'user-uuid',
+     *   'Account compromised'
+     * );
+     * console.log('Revoked sessions:', result.revokedSessions);
+     * ```
+     */
+    disableUser(sub: string, reason?: string): Promise<DisableUserResponse>;
+    /**
+     * Enable (unlock) user account
+     *
+     * @param sub - User UUID
+     * @returns Enable confirmation with updated user
+     * @throws {NAuthClientError} If operation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.enableUser('user-uuid');
+     * console.log('User enabled:', result.user);
+     * ```
+     */
+    enableUser(sub: string): Promise<EnableUserResponse>;
+    /**
+     * Force password change on next login
+     *
+     * @param sub - User UUID
+     * @returns Success confirmation
+     * @throws {NAuthClientError} If operation fails
+     *
+     * @example
+     * ```typescript
+     * await client.admin.forcePasswordChange('user-uuid');
+     * ```
+     */
+    forcePasswordChange(sub: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Set password for any user (admin operation)
+     *
+     * @param identifier - User email, username, or phone
+     * @param newPassword - New password
+     * @returns Success confirmation
+     * @throws {NAuthClientError} If operation fails
+     *
+     * @example
+     * ```typescript
+     * await client.admin.setPassword('user@example.com', 'NewSecurePass123!');
+     * ```
+     */
+    setPassword(identifier: string, newPassword: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Initiate password reset workflow (sends code/link to user)
+     *
+     * @param request - Password reset request
+     * @returns Reset confirmation with delivery details
+     * @throws {NAuthClientError} If operation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.initiatePasswordReset({
+     *   sub: 'user-uuid',
+     *   deliveryMethod: 'email',
+     *   baseUrl: 'https://myapp.com/reset-password',
+     *   reason: 'User requested password reset',
+     * });
+     * console.log('Code sent to:', result.destination);
+     * ```
+     */
+    initiatePasswordReset(request: AdminResetPasswordRequest): Promise<AdminResetPasswordResponse>;
+    /**
+     * Get all sessions for a user
+     *
+     * @param sub - User UUID
+     * @returns User sessions
+     * @throws {NAuthClientError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.getUserSessions('user-uuid');
+     * console.log('Active sessions:', result.sessions);
+     * ```
+     */
+    getUserSessions(sub: string): Promise<GetUserSessionsResponse>;
+    /**
+     * Logout all sessions for a user (admin-initiated)
+     *
+     * @param sub - User UUID
+     * @param forgetDevices - If true, also revokes all trusted devices
+     * @returns Number of sessions revoked
+     * @throws {NAuthClientError} If operation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.admin.logoutAllSessions('user-uuid', true);
+     * console.log(`Revoked ${result.revokedCount} sessions`);
+     * ```
+     */
+    logoutAllSessions(sub: string, forgetDevices?: boolean): Promise<{
+        revokedCount: number;
+    }>;
+    /**
+     * Get MFA status for a user
+     *
+     * @param sub - User UUID
+     * @returns MFA status
+     * @throws {NAuthClientError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const status = await client.admin.getMfaStatus('user-uuid');
+     * console.log('MFA enabled:', status.enabled);
+     * ```
+     */
+    getMfaStatus(sub: string): Promise<MFAStatus>;
+    /**
+     * Set preferred MFA method for a user
+     *
+     * @param sub - User UUID
+     * @param method - MFA method to set as preferred
+     * @returns Success message
+     * @throws {NAuthClientError} If operation fails
+     *
+     * @example
+     * ```typescript
+     * await client.admin.setPreferredMfaMethod('user-uuid', 'totp');
+     * ```
+     */
+    setPreferredMfaMethod(sub: string, method: 'totp' | 'sms' | 'email' | 'passkey'): Promise<{
+        message: string;
+    }>;
+    /**
+     * Remove MFA devices for a user
+     *
+     * @param sub - User UUID
+     * @param method - MFA method to remove
+     * @returns Success message
+     * @throws {NAuthClientError} If operation fails
+     *
+     * @example
+     * ```typescript
+     * await client.admin.removeMfaDevices('user-uuid', 'sms');
+     * ```
+     */
+    removeMfaDevices(sub: string, method: 'totp' | 'sms' | 'email' | 'passkey'): Promise<{
+        message: string;
+    }>;
+    /**
+     * Grant or revoke MFA exemption for a user
+     *
+     * @param sub - User UUID
+     * @param exempt - True to exempt from MFA, false to require
+     * @param reason - Optional reason for exemption
+     * @returns Success message
+     * @throws {NAuthClientError} If operation fails
+     *
+     * @example
+     * ```typescript
+     * await client.admin.setMfaExemption('user-uuid', true, 'Service account');
+     * ```
+     */
+    setMfaExemption(sub: string, exempt: boolean, reason?: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * Get audit history for a user
+     *
+     * @param params - Audit history request params
+     * @returns Paginated audit events
+     * @throws {NAuthClientError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const history = await client.admin.getAuditHistory({
+     *   sub: 'user-uuid',
+     *   page: 1,
+     *   limit: 50,
+     *   eventType: 'LOGIN_SUCCESS',
+     * });
+     * ```
+     */
+    getAuditHistory(params: AdminAuditHistoryRequest): Promise<AuditHistoryResponse>;
+    /**
+     * Build admin endpoint URL with path parameter replacement
+     *
+     * Path construction order:
+     * 1. Start with endpoint: '/users/:sub'
+     * 2. Replace params: '/users/uuid-123'
+     * 3. Apply adminPathPrefix: '/admin/users/uuid-123'
+     * 4. Apply authPathPrefix if exists: '/auth/admin/users/uuid-123'
+     * 5. Combine with baseUrl: 'https://api.example.com/auth/admin/users/uuid-123'
+     *
+     * @param endpointPath - Endpoint path (may contain :sub, :provider, etc.)
+     * @param pathParams - Path parameters to replace
+     * @returns Full URL
+     * @private
+     */
+    private buildAdminUrl;
+    /**
+     * Build query string from params object
+     *
+     * Handles:
+     * - Simple values (string, number, boolean)
+     * - Arrays (multiple values for same key)
+     * - Nested objects (e.g., createdAt[operator], createdAt[value])
+     * - Dates (converted to ISO string)
+     *
+     * @param params - Query parameters
+     * @returns Query string (e.g., '?page=1&limit=20')
+     * @private
+     */
+    private buildQueryString;
+    /**
+     * Build request headers for authentication
+     *
+     * @param auth - Whether to include authentication headers
+     * @param method - HTTP method
+     * @returns Headers object
+     * @private
+     */
+    private buildHeaders;
+    /**
+     * Get CSRF token from cookie (browser only)
+     *
+     * @returns CSRF token or null
+     * @private
+     */
+    private getCsrfToken;
+    /**
+     * Execute GET request
+     *
+     * @param path - Full URL path
+     * @returns Response data
+     * @private
+     */
+    private get;
+    /**
+     * Execute POST request
+     *
+     * @param path - Full URL path
+     * @param body - Request body
+     * @returns Response data
+     * @private
+     */
+    private post;
+    /**
+     * Execute DELETE request
+     *
+     * @param path - Full URL path
+     * @returns Response data
+     * @private
+     */
+    private delete;
+    /**
+     * Handle HTTP errors and convert to NAuthClientError
+     *
+     * @param error - Error from HTTP adapter
+     * @returns NAuthClientError
+     * @private
+     */
+    private handleError;
+}
+
 /**
  * Primary client for interacting with nauth-toolkit backend.
  */
@@ -1321,7 +2518,34 @@ declare class NAuthClient {
     private readonly tokenManager;
     private readonly eventEmitter;
     private readonly challengeRouter;
+    private readonly oauthStorage;
     private currentUser;
+    /**
+     * Admin operations (available if admin config provided).
+     *
+     * Provides admin-level user management methods:
+     * - User CRUD operations
+     * - Password management
+     * - Session management
+     * - MFA management
+     * - Audit history
+     *
+     * @example
+     * ```typescript
+     * const client = new NAuthClient({
+     *   baseUrl: 'https://api.example.com/auth',
+     *   tokenDelivery: 'cookies',
+     *   admin: {
+     *     pathPrefix: '/admin',
+     *   },
+     * });
+     *
+     * // Use admin operations
+     * const users = await client.admin.getUsers({ page: 1 });
+     * await client.admin.deleteUser('user-uuid');
+     * ```
+     */
+    readonly admin?: AdminOperations;
     /**
      * Create a new client instance.
      *
@@ -1777,6 +3001,8 @@ declare class NAuthClient {
      * when appState is present in the callback URL. The stored state can
      * be retrieved using getLastOauthState().
      *
+     * Stores in sessionStorage (ephemeral) for better security.
+     *
      * @param appState - OAuth appState value from callback URL
      *
      * @example
@@ -1793,6 +3019,7 @@ declare class NAuthClient {
      * applying invite codes, or tracking referral information.
      *
      * The state is automatically cleared after retrieval to prevent reuse.
+     * Stored in sessionStorage (ephemeral) for better security.
      *
      * @returns The stored appState, or null if none exists
      *
@@ -1950,4 +3177,4 @@ declare class FetchAdapter implements HttpAdapter {
     request<T>(config: HttpRequest): Promise<HttpResponse<T>>;
 }
 
-export { type AuditHistoryResponse, type AuthAuditEvent, type AuthAuditEventStatus, AuthAuditEventType, AuthChallenge, type AuthChallengeEvent, type AuthErrorEvent, type AuthEvent, type AuthEventListener, type AuthEventType, type AuthLoginEvent, type AuthLogoutEvent, type AuthRefreshEvent, type AuthResponse, type AuthResponseContext, type AuthSignupEvent, type AuthSuccessEvent, type AuthUser, type AuthUserSummary, type BackupCodesResponse, type BaseChallengeResponse, BrowserStorage, type ChallengeResponse, ChallengeRouter, type ChangePasswordRequest, type ConfirmForgotPasswordRequest, type ConfirmForgotPasswordResponse, EventEmitter, FetchAdapter, type ForceChangePasswordResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetChallengeDataRequest, type GetChallengeDataResponse, type GetSetupDataRequest, type GetSetupDataResponse, type HttpAdapter, type HttpRequest, type HttpResponse, InMemoryStorage, type LinkedAccountsResponse, type LoginRequest, type LogoutAllRequest, type LogoutRequest, type MFAChallengeMethod, type MFACodeResponse, type MFADevice, type MFADeviceMethod, type MFAMethod, type MFAPasskeyResponse, type MFASetupData, type MFASetupResponse, type MFAStatus, type MfaRoutesConfig, NAuthClient, type NAuthClientConfig, NAuthClientError, type NAuthEndpoints, type NAuthError, NAuthErrorCode, type NAuthRedirectsConfig, type NAuthStorageAdapter, type OAuthCallbackEvent, type OAuthCompletedEvent, type OAuthErrorEvent, type OAuthStartedEvent, type ResendCodeRequest, type ResetPasswordWithCodeRequest, type ResetPasswordWithCodeResponse, type ResolvedNAuthClientConfig, type SignupRequest, type SocialLoginOptions, type SocialProvider, type SocialVerifyRequest, type TokenDeliveryMode, type TokenResponse, type UpdateProfileRequest, type VerifyEmailResponse, type VerifyPhoneCodeResponse, type VerifyPhoneCollectResponse, defaultEndpoints, getChallengeInstructions, getMFAMethod, getMaskedDestination, isOTPChallenge, requiresPhoneCollection, resolveConfig };
+export { type AdminAuditHistoryRequest, AdminOperations, type AdminResetPasswordRequest, type AdminResetPasswordResponse, type AdminSignupRequest, type AdminSignupResponse, type AdminSignupSocialRequest, type AdminSignupSocialResponse, type AuditHistoryResponse, type AuthAuditEvent, type AuthAuditEventStatus, AuthAuditEventType, AuthChallenge, type AuthChallengeEvent, type AuthErrorEvent, type AuthEvent, type AuthEventListener, type AuthEventType, type AuthLoginEvent, type AuthLogoutEvent, type AuthRefreshEvent, type AuthResponse, type AuthResponseContext, type AuthSignupEvent, type AuthSuccessEvent, type AuthUser, type AuthUserSummary, type BackupCodesResponse, type BaseChallengeResponse, BrowserStorage, type ChallengeResponse, ChallengeRouter, type ChangePasswordRequest, type ConfirmForgotPasswordRequest, type ConfirmForgotPasswordResponse, type DateFilter, type DeleteUserResponse, type DisableUserResponse, type EnableUserResponse, EventEmitter, FetchAdapter, type ForceChangePasswordResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetChallengeDataRequest, type GetChallengeDataResponse, type GetSetupDataRequest, type GetSetupDataResponse, type GetUserSessionsResponse, type GetUsersRequest, type GetUsersResponse, type HttpAdapter, type HttpRequest, type HttpResponse, InMemoryStorage, type LinkedAccountsResponse, type LoginRequest, type LogoutAllRequest, type LogoutRequest, type MFAChallengeMethod, type MFACodeResponse, type MFADevice, type MFADeviceMethod, type MFAMethod, type MFAPasskeyResponse, type MFASetupData, type MFASetupResponse, type MFAStatus, type MfaRoutesConfig, type NAuthAdminEndpoints, NAuthClient, type NAuthClientConfig, NAuthClientError, type NAuthEndpoints, type NAuthError, NAuthErrorCode, type NAuthRedirectsConfig, type NAuthStorageAdapter, type OAuthCallbackEvent, type OAuthCompletedEvent, type OAuthErrorEvent, type OAuthStartedEvent, type ResendCodeRequest, type ResetPasswordWithCodeRequest, type ResetPasswordWithCodeResponse, type ResolvedNAuthClientConfig, type SignupRequest, type SocialLoginOptions, type SocialProvider, type SocialVerifyRequest, type TokenDeliveryMode, type TokenResponse, type UpdateProfileRequest, type UserSessionInfo, type VerifyEmailResponse, type VerifyPhoneCodeResponse, type VerifyPhoneCollectResponse, defaultAdminEndpoints, defaultEndpoints, getChallengeInstructions, getMFAMethod, getMaskedDestination, isOTPChallenge, requiresPhoneCollection, resolveConfig };