@nauth-toolkit/client 0.1.89 → 0.1.90

package/dist/index.mjs

@@ -136,11 +136,45 @@ var defaultEndpoints = {
   auditHistory: "/audit/history",
   updateProfile: "/profile"
 };
+var defaultAdminEndpoints = {
+  signup: "/signup",
+  signupSocial: "/signup-social",
+  getUsers: "/users",
+  getUser: "/users/:sub",
+  deleteUser: "/users/:sub",
+  disableUser: "/users/:sub/disable",
+  enableUser: "/users/:sub/enable",
+  forcePasswordChange: "/users/:sub/force-password-change",
+  setPassword: "/set-password",
+  resetPasswordInitiate: "/reset-password/initiate",
+  getUserSessions: "/users/:sub/sessions",
+  logoutAll: "/users/:sub/logout-all",
+  getMfaStatus: "/users/:sub/mfa/status",
+  setPreferredMfaMethod: "/mfa/preferred-method",
+  removeMfaDevices: "/mfa/remove-devices",
+  setMfaExemption: "/mfa/exemption",
+  getAuditHistory: "/audit/history"
+};
 var resolveConfig = (config, defaultAdapter) => {
   const resolvedEndpoints = {
     ...defaultEndpoints,
     ...config.endpoints ?? {}
   };
+  let resolvedAdmin;
+  if (config.admin) {
+    const resolvedAdminEndpoints = {
+      ...defaultAdminEndpoints,
+      ...config.admin.endpoints ?? {}
+    };
+    resolvedAdmin = {
+      pathPrefix: config.admin.pathPrefix ?? "/admin",
+      endpoints: resolvedAdminEndpoints,
+      headers: {
+        ...config.headers,
+        ...config.admin.headers ?? {}
+      }
+    };
+  }
   return {
     ...config,
     csrf: {
@@ -155,7 +189,8 @@ var resolveConfig = (config, defaultAdapter) => {
     timeout: config.timeout ?? 3e4,
     endpoints: resolvedEndpoints,
     storage: config.storage,
-    httpAdapter: config.httpAdapter ?? defaultAdapter
+    httpAdapter: config.httpAdapter ?? defaultAdapter,
+    admin: resolvedAdmin
   };
 };
 
@@ -528,8 +563,9 @@ var FetchAdapter = class {
 // src/core/challenge-router.ts
 var OAUTH_STATE_KEY = "nauth_oauth_state";
 var ChallengeRouter = class {
-  constructor(config) {
+  constructor(config, oauthStorage) {
     this.config = config;
+    this.oauthStorage = oauthStorage;
   }
   /**
    * Handle auth response - either call callback or auto-navigate.
@@ -545,10 +581,39 @@ var ChallengeRouter = class {
     if (response.challengeName) {
       await this.navigateToChallenge(response);
     } else {
-      const queryParams = await this.getStoredOauthState();
-      await this.navigateToSuccess(queryParams);
+      const queryParams = context.appState ? { appState: context.appState } : await this.getStoredOauthState();
+      await this.navigateToSuccess(queryParams, context);
     }
   }
+  /**
+   * 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
+   */
+  resolveSuccessUrl(context) {
+    const redirects = this.config.redirects;
+    if (!redirects) {
+      return "/";
+    }
+    const isSignup = context?.source === "signup";
+    if (isSignup) {
+      if (redirects.signupSuccess === null) return null;
+      if (typeof redirects.signupSuccess === "string") return redirects.signupSuccess;
+    }
+    if (!isSignup) {
+      if (redirects.loginSuccess === null) return null;
+      if (typeof redirects.loginSuccess === "string") return redirects.loginSuccess;
+    }
+    if (redirects.success === null) return null;
+    if (typeof redirects.success === "string") return redirects.success;
+    return "/";
+  }
   /**
    * Navigate to appropriate challenge route.
    *
@@ -562,14 +627,19 @@ var ChallengeRouter = class {
    * 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' });
    * ```
    */
-  async navigateToSuccess(queryParams) {
-    let url = this.config.redirects?.success || "/";
+  async navigateToSuccess(queryParams, context) {
+    const resolved = this.resolveSuccessUrl(context);
+    if (resolved === null) {
+      return;
+    }
+    let url = resolved;
     if (queryParams && Object.keys(queryParams).length > 0) {
       const searchParams = new URLSearchParams();
       Object.entries(queryParams).forEach(([key, value]) => {
@@ -583,15 +653,18 @@ var ChallengeRouter = class {
     await this.navigate(url);
   }
   /**
-   * 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
    */
   async getStoredOauthState() {
     try {
-      const stored = await this.config.storage.getItem(OAUTH_STATE_KEY);
+      const stored = await this.oauthStorage.getItem(OAUTH_STATE_KEY);
       if (stored) {
-        await this.config.storage.removeItem(OAUTH_STATE_KEY);
         return { appState: stored };
       }
     } catch {
@@ -604,7 +677,12 @@ var ChallengeRouter = class {
    * @param type - Type of error (oauth or session)
    */
   async navigateToError(type) {
-    const url = type === "oauth" ? this.config.redirects?.oauthError || "/login" : this.config.redirects?.sessionExpired || "/login";
+    const redirects = this.config.redirects;
+    const raw = type === "oauth" ? redirects?.oauthError : redirects?.sessionExpired;
+    if (raw === null) {
+      return;
+    }
+    const url = raw ?? "/login";
     await this.navigate(url);
   }
   /**
@@ -709,13 +787,625 @@ var ChallengeRouter = class {
   }
 };
 
+// src/core/admin-operations.ts
+var hasWindow = () => typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
+var AdminOperations = class {
+  /**
+   * Create admin operations instance.
+   *
+   * @param config - Resolved client configuration
+   */
+  constructor(config) {
+    __publicField(this, "config");
+    __publicField(this, "adminEndpoints");
+    __publicField(this, "adminPathPrefix");
+    __publicField(this, "adminHeaders");
+    if (!config.admin) {
+      throw new Error("Admin operations require admin configuration");
+    }
+    this.config = config;
+    this.adminEndpoints = config.admin.endpoints;
+    this.adminPathPrefix = config.admin.pathPrefix;
+    this.adminHeaders = config.admin.headers;
+  }
+  // ============================================================================
+  // User Management
+  // ============================================================================
+  /**
+   * 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);
+   * ```
+   */
+  async createUser(request) {
+    const path = this.buildAdminUrl(this.adminEndpoints.signup);
+    return this.post(path, request);
+  }
+  /**
+   * 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',
+   * });
+   * ```
+   */
+  async importSocialUser(request) {
+    const path = this.buildAdminUrl(this.adminEndpoints.signupSocial);
+    return this.post(path, request);
+  }
+  /**
+   * 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',
+   * });
+   * ```
+   */
+  async getUsers(params = {}) {
+    const path = this.buildAdminUrl(this.adminEndpoints.getUsers);
+    const queryString = this.buildQueryString(params);
+    return this.get(`${path}${queryString}`);
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async getUser(sub) {
+    const path = this.buildAdminUrl(this.adminEndpoints.getUser, { sub });
+    return this.get(path);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async deleteUser(sub) {
+    const path = this.buildAdminUrl(this.adminEndpoints.deleteUser, { sub });
+    return this.delete(path);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async disableUser(sub, reason) {
+    const path = this.buildAdminUrl(this.adminEndpoints.disableUser, { sub });
+    return this.post(path, { reason });
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async enableUser(sub) {
+    const path = this.buildAdminUrl(this.adminEndpoints.enableUser, { sub });
+    return this.post(path, {});
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async forcePasswordChange(sub) {
+    const path = this.buildAdminUrl(this.adminEndpoints.forcePasswordChange, { sub });
+    return this.post(path, {});
+  }
+  // ============================================================================
+  // Password Management
+  // ============================================================================
+  /**
+   * 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!');
+   * ```
+   */
+  async setPassword(identifier, newPassword) {
+    const path = this.buildAdminUrl(this.adminEndpoints.setPassword);
+    return this.post(path, { identifier, newPassword });
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async initiatePasswordReset(request) {
+    const path = this.buildAdminUrl(this.adminEndpoints.resetPasswordInitiate);
+    return this.post(path, request);
+  }
+  // ============================================================================
+  // Session Management
+  // ============================================================================
+  /**
+   * 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);
+   * ```
+   */
+  async getUserSessions(sub) {
+    const path = this.buildAdminUrl(this.adminEndpoints.getUserSessions, { sub });
+    return this.get(path);
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async logoutAllSessions(sub, forgetDevices = false) {
+    const path = this.buildAdminUrl(this.adminEndpoints.logoutAll, { sub });
+    return this.post(path, { forgetDevices });
+  }
+  // ============================================================================
+  // MFA Management
+  // ============================================================================
+  /**
+   * 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);
+   * ```
+   */
+  async getMfaStatus(sub) {
+    const path = this.buildAdminUrl(this.adminEndpoints.getMfaStatus, { sub });
+    return this.get(path);
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async setPreferredMfaMethod(sub, method) {
+    const path = this.buildAdminUrl(this.adminEndpoints.setPreferredMfaMethod);
+    return this.post(path, { sub, method });
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async removeMfaDevices(sub, method) {
+    const path = this.buildAdminUrl(this.adminEndpoints.removeMfaDevices);
+    return this.post(path, { sub, method });
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async setMfaExemption(sub, exempt, reason) {
+    const path = this.buildAdminUrl(this.adminEndpoints.setMfaExemption);
+    return this.post(path, { sub, exempt, reason });
+  }
+  // ============================================================================
+  // Audit
+  // ============================================================================
+  /**
+   * 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',
+   * });
+   * ```
+   */
+  async getAuditHistory(params) {
+    const path = this.buildAdminUrl(this.adminEndpoints.getAuditHistory);
+    const queryString = this.buildQueryString(params);
+    return this.get(`${path}${queryString}`);
+  }
+  // ============================================================================
+  // Private Helper Methods
+  // ============================================================================
+  /**
+   * 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
+   */
+  buildAdminUrl(endpointPath, pathParams) {
+    let path = endpointPath;
+    if (pathParams) {
+      Object.entries(pathParams).forEach(([key, value]) => {
+        path = path.replace(`:${key}`, encodeURIComponent(value));
+      });
+    }
+    const prefix = this.adminPathPrefix.startsWith("/") ? this.adminPathPrefix : `/${this.adminPathPrefix}`;
+    path = `${prefix}${path.startsWith("/") ? "" : "/"}${path}`;
+    if (this.config.authPathPrefix) {
+      const authPrefix = this.config.authPathPrefix.startsWith("/") ? this.config.authPathPrefix : `/${this.config.authPathPrefix}`;
+      path = `${authPrefix}${path}`;
+    }
+    const normalizedBase = this.config.baseUrl.endsWith("/") ? this.config.baseUrl.slice(0, -1) : this.config.baseUrl;
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    return `${normalizedBase}${normalizedPath}`;
+  }
+  /**
+   * 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
+   */
+  buildQueryString(params) {
+    const searchParams = new URLSearchParams();
+    for (const [key, rawValue] of Object.entries(params)) {
+      if (rawValue === void 0 || rawValue === null) {
+        continue;
+      }
+      if (Array.isArray(rawValue)) {
+        for (const item of rawValue) {
+          searchParams.append(key, String(item));
+        }
+        continue;
+      }
+      if (typeof rawValue === "object" && rawValue !== null && !(rawValue instanceof Date)) {
+        const nestedObj = rawValue;
+        for (const [nestedKey, nestedValue] of Object.entries(nestedObj)) {
+          const nestedParamKey = `${key}[${nestedKey}]`;
+          const valueToAppend = nestedValue instanceof Date ? nestedValue.toISOString() : String(nestedValue);
+          searchParams.append(nestedParamKey, valueToAppend);
+        }
+        continue;
+      }
+      if (rawValue instanceof Date) {
+        searchParams.append(key, rawValue.toISOString());
+        continue;
+      }
+      searchParams.append(key, String(rawValue));
+    }
+    const query = searchParams.toString();
+    return query ? `?${query}` : "";
+  }
+  /**
+   * Build request headers for authentication
+   *
+   * @param auth - Whether to include authentication headers
+   * @param method - HTTP method
+   * @returns Headers object
+   * @private
+   */
+  async buildHeaders(auth, method = "GET") {
+    const headers = {
+      ...this.config.headers,
+      ...this.adminHeaders
+    };
+    if (method !== "GET") {
+      headers["Content-Type"] = "application/json";
+    }
+    if (auth && this.config.tokenDelivery === "json") {
+      try {
+        const ACCESS_TOKEN_KEY2 = "nauth_access_token";
+        const token = await this.config.storage.getItem(ACCESS_TOKEN_KEY2);
+        if (token) {
+          headers["Authorization"] = `Bearer ${token}`;
+        }
+      } catch {
+      }
+    }
+    if (this.config.tokenDelivery === "json") {
+      try {
+        const deviceToken = await this.config.storage.getItem(this.config.deviceTrust.storageKey);
+        if (deviceToken) {
+          headers[this.config.deviceTrust.headerName] = deviceToken;
+        }
+      } catch {
+      }
+    }
+    const mutatingMethods = [
+      "POST",
+      "PUT",
+      "PATCH",
+      "DELETE"
+    ];
+    if (this.config.tokenDelivery === "cookies" && hasWindow() && mutatingMethods.includes(method)) {
+      const csrfToken = this.getCsrfToken();
+      if (csrfToken) {
+        headers[this.config.csrf.headerName] = csrfToken;
+      }
+    }
+    return headers;
+  }
+  /**
+   * Get CSRF token from cookie (browser only)
+   *
+   * @returns CSRF token or null
+   * @private
+   */
+  getCsrfToken() {
+    if (!hasWindow() || typeof document === "undefined") return null;
+    const match = document.cookie.match(
+      new RegExp(`(^| )${this.config.csrf.cookieName}=([^;]+)`)
+    );
+    return match ? decodeURIComponent(match[2]) : null;
+  }
+  /**
+   * Execute GET request
+   *
+   * @param path - Full URL path
+   * @returns Response data
+   * @private
+   */
+  async get(path) {
+    const headers = await this.buildHeaders(true, "GET");
+    const credentials = this.config.tokenDelivery === "cookies" ? "include" : "omit";
+    try {
+      const response = await this.config.httpAdapter.request({
+        method: "GET",
+        url: path,
+        headers,
+        credentials
+      });
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+  /**
+   * Execute POST request
+   *
+   * @param path - Full URL path
+   * @param body - Request body
+   * @returns Response data
+   * @private
+   */
+  async post(path, body) {
+    const headers = await this.buildHeaders(true, "POST");
+    const credentials = this.config.tokenDelivery === "cookies" ? "include" : "omit";
+    try {
+      const response = await this.config.httpAdapter.request({
+        method: "POST",
+        url: path,
+        headers,
+        body,
+        credentials
+      });
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+  /**
+   * Execute DELETE request
+   *
+   * @param path - Full URL path
+   * @returns Response data
+   * @private
+   */
+  async delete(path) {
+    const headers = await this.buildHeaders(true, "DELETE");
+    const credentials = this.config.tokenDelivery === "cookies" ? "include" : "omit";
+    try {
+      const response = await this.config.httpAdapter.request({
+        method: "DELETE",
+        url: path,
+        headers,
+        credentials
+      });
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+  /**
+   * Handle HTTP errors and convert to NAuthClientError
+   *
+   * @param error - Error from HTTP adapter
+   * @returns NAuthClientError
+   * @private
+   */
+  handleError(error) {
+    if (error instanceof NAuthClientError) {
+      return error;
+    }
+    if (error && typeof error === "object" && "response" in error) {
+      const httpError = error;
+      const status = httpError.response?.status ?? 500;
+      const errorData = typeof httpError.response?.data === "object" && httpError.response.data !== null ? httpError.response.data : {};
+      const code = typeof errorData["code"] === "string" ? errorData["code"] : "INTERNAL_ERROR" /* INTERNAL_ERROR */;
+      const message = typeof errorData["message"] === "string" ? errorData["message"] : `Request failed with status ${status}`;
+      return new NAuthClientError(code, message, {
+        statusCode: status,
+        details: errorData
+      });
+    }
+    return new NAuthClientError(
+      "INTERNAL_ERROR" /* INTERNAL_ERROR */,
+      error instanceof Error ? error.message : "Unknown error"
+    );
+  }
+};
+
 // src/core/client.ts
 var USER_KEY2 = "nauth_user";
 var CHALLENGE_KEY2 = "nauth_challenge_session";
 var OAUTH_STATE_KEY2 = "nauth_oauth_state";
-var hasWindow = () => typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
+var hasWindow2 = () => typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
+var getOauthStorage = (mainStorage) => {
+  if (hasWindow2() && typeof window.sessionStorage !== "undefined") {
+    return new BrowserStorage(window.sessionStorage);
+  }
+  return mainStorage;
+};
 var defaultStorage = () => {
-  if (hasWindow() && typeof window.localStorage !== "undefined") {
+  if (hasWindow2() && typeof window.localStorage !== "undefined") {
     return new BrowserStorage();
   }
   return new InMemoryStorage();
@@ -731,7 +1421,34 @@ var NAuthClient = class {
     __publicField(this, "tokenManager");
     __publicField(this, "eventEmitter");
     __publicField(this, "challengeRouter");
+    __publicField(this, "oauthStorage");
     __publicField(this, "currentUser", null);
+    /**
+     * 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');
+     * ```
+     */
+    __publicField(this, "admin");
     /**
      * Handle cross-tab storage updates.
      */
@@ -749,8 +1466,12 @@ var NAuthClient = class {
     this.config = resolveConfig({ ...userConfig, storage }, defaultAdapter);
     this.tokenManager = new TokenManager(storage);
     this.eventEmitter = new EventEmitter();
-    this.challengeRouter = new ChallengeRouter(this.config);
-    if (hasWindow()) {
+    this.oauthStorage = getOauthStorage(storage);
+    this.challengeRouter = new ChallengeRouter(this.config, this.oauthStorage);
+    if (this.config.admin) {
+      this.admin = new AdminOperations(this.config);
+    }
+    if (hasWindow2()) {
       window.addEventListener("storage", this.handleStorageEvent);
     }
   }
@@ -758,7 +1479,7 @@ var NAuthClient = class {
    * Clean up resources.
    */
   dispose() {
-    if (hasWindow()) {
+    if (hasWindow2()) {
       window.removeEventListener("storage", this.handleStorageEvent);
     }
   }
@@ -1206,11 +1927,12 @@ var NAuthClient = class {
    */
   async loginWithSocial(provider, options) {
     this.eventEmitter.emit({ type: "oauth:started", data: { provider }, timestamp: Date.now() });
-    if (hasWindow()) {
+    if (hasWindow2()) {
       const startPath = this.config.endpoints.socialRedirectStart.replace(":provider", provider);
       const fullUrl = this.buildUrl(startPath);
       const startUrl = new URL(fullUrl);
-      const returnTo = options?.returnTo ?? this.config.redirects?.success ?? "/";
+      const redirects = this.config.redirects;
+      const returnTo = options?.returnTo ?? redirects?.loginSuccess ?? redirects?.success ?? "/";
       startUrl.searchParams.set("returnTo", returnTo);
       if (options?.action === "link") {
         startUrl.searchParams.set("action", "link");
@@ -1237,7 +1959,11 @@ var NAuthClient = class {
     }
     const result = await this.post(this.config.endpoints.socialExchange, { exchangeToken: token });
     await this.handleAuthResponse(result);
-    await this.challengeRouter.handleAuthResponse(result, { source: "social" });
+    const appState = await this.oauthStorage.getItem(OAUTH_STATE_KEY2);
+    await this.challengeRouter.handleAuthResponse(result, {
+      source: "social",
+      appState: appState ?? void 0
+    });
     return result;
   }
   /**
@@ -1523,7 +2249,7 @@ var NAuthClient = class {
       }
     }
     const mutatingMethods = ["POST", "PUT", "PATCH", "DELETE"];
-    if (this.config.tokenDelivery === "cookies" && hasWindow() && mutatingMethods.includes(method)) {
+    if (this.config.tokenDelivery === "cookies" && hasWindow2() && mutatingMethods.includes(method)) {
       const csrfToken = this.getCsrfToken();
       if (csrfToken) {
         headers[this.config.csrf.headerName] = csrfToken;
@@ -1536,7 +2262,7 @@ var NAuthClient = class {
    * @private
    */
   getCsrfToken() {
-    if (!hasWindow() || typeof document === "undefined") return null;
+    if (!hasWindow2() || typeof document === "undefined") return null;
     const match = document.cookie.match(new RegExp(`(^| )${this.config.csrf.cookieName}=([^;]+)`));
     return match ? decodeURIComponent(match[2]) : null;
   }
@@ -1628,6 +2354,8 @@ var NAuthClient = class {
    * 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
@@ -1637,7 +2365,7 @@ var NAuthClient = class {
    */
   async storeOauthState(appState) {
     if (appState && appState.trim() !== "") {
-      await this.config.storage.setItem(OAUTH_STATE_KEY2, appState);
+      await this.oauthStorage.setItem(OAUTH_STATE_KEY2, appState);
     }
   }
   /**
@@ -1648,6 +2376,7 @@ var NAuthClient = class {
    * 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
    *
@@ -1661,9 +2390,9 @@ var NAuthClient = class {
    * ```
    */
   async getLastOauthState() {
-    const stored = await this.config.storage.getItem(OAUTH_STATE_KEY2);
+    const stored = await this.oauthStorage.getItem(OAUTH_STATE_KEY2);
     if (stored) {
-      await this.config.storage.removeItem(OAUTH_STATE_KEY2);
+      await this.oauthStorage.removeItem(OAUTH_STATE_KEY2);
       return stored;
     }
     return null;
@@ -1712,6 +2441,7 @@ function isOTPChallenge(challenge) {
   return challengeName === "VERIFY_EMAIL" /* VERIFY_EMAIL */ || challengeName === "VERIFY_PHONE" /* VERIFY_PHONE */ || challengeName === "MFA_REQUIRED" /* MFA_REQUIRED */;
 }
 export {
+  AdminOperations,
   AuthAuditEventType,
   AuthChallenge,
   BrowserStorage,
@@ -1722,6 +2452,7 @@ export {
   NAuthClient,
   NAuthClientError,
   NAuthErrorCode,
+  defaultAdminEndpoints,
   defaultEndpoints,
   getChallengeInstructions,
   getMFAMethod,