@bagelink/auth 1.4.182 → 1.4.184

package/dist/index.cjs

@@ -46,6 +46,17 @@ class EventEmitter {
     }
   }
 }
+function queryParams() {
+  if (typeof window === "undefined" || !window.location?.search) {
+    return {};
+  }
+  const params = new URLSearchParams(window.location.search);
+  const result = {};
+  params.forEach((value, key) => {
+    result[key] = value;
+  });
+  return result;
+}
 
 class AuthApi {
   api;
@@ -129,7 +140,8 @@ class AuthApi {
    */
   async linkSSOProvider(data) {
     return this.api.post(`/authentication/sso/${data.provider}/link`, {
-      code: data.code
+      code: data.code,
+      state: data.state
     });
   }
   /**
@@ -463,11 +475,20 @@ function createSSOProvider(config) {
         state
       });
     },
-    async link(code) {
+    async link(code, state) {
       const auth = getAuthApi();
+      if (typeof sessionStorage !== "undefined" && state) {
+        const storedState = sessionStorage.getItem(getStateKey());
+        sessionStorage.removeItem(getStateKey());
+        sessionStorage.removeItem(`oauth_provider:${state}`);
+        if (storedState && storedState !== state) {
+          throw new StateMismatchError();
+        }
+      }
       await auth.linkSSOProvider({
         provider: config.id,
-        code
+        code,
+        state
       });
     },
     async unlink() {
@@ -490,7 +511,7 @@ function createSSOProvider(config) {
     // Default, can be overridden per provider
   };
 }
-const sso = {
+const ssoProviders = {
   /**
    * Google OAuth Provider
    * https://developers.google.com/identity/protocols/oauth2
@@ -590,31 +611,59 @@ const sso = {
     }
   })
 };
-const ssoProviders = Object.values(sso);
+const sso = {
+  // All provider instances
+  ...ssoProviders,
+  /**
+   * Handle OAuth callback from URL automatically
+   * Detects provider from state and completes login
+   *
+   * @example
+   * // On /auth/callback page
+   * const result = await sso.handleCallback()
+   */
+  handleCallback: handleOAuthCallback,
+  /**
+   * Handle OAuth link callback from URL automatically
+   * Detects provider from state and completes linking
+   *
+   * @example
+   * // On /settings/link-callback page
+   * await sso.handleLinkCallback()
+   */
+  handleLinkCallback: handleOAuthLinkCallback
+};
+const ssoProvidersList = Object.values(ssoProviders);
 function getSSOProvider(provider) {
-  return sso[provider];
+  return ssoProviders[provider];
 }
 function getAllSSOProviders() {
-  return ssoProviders;
+  return ssoProvidersList;
 }
 function isSupportedProvider(provider) {
-  return provider in sso;
+  return provider in ssoProviders;
 }
-async function handleOAuthCallback() {
-  if (typeof window === "undefined") {
-    return null;
+function handleOAuthCallback() {
+  const { code, state } = queryParams();
+  if (!code || !state) {
+    return Promise.resolve(null);
   }
-  const urlParams = new URLSearchParams(window.location.search);
-  const code = urlParams.get("code");
-  const state = urlParams.get("state");
+  const provider = sessionStorage.getItem(`oauth_provider:${state}`);
+  if (!provider || !isSupportedProvider(provider)) {
+    throw new Error("Unable to determine OAuth provider. State may have expired.");
+  }
+  return ssoProviders[provider].callback(code, state);
+}
+function handleOAuthLinkCallback() {
+  const { code, state } = queryParams();
   if (!code || !state) {
-    return null;
+    throw new Error("Missing code or state parameter");
   }
   const provider = sessionStorage.getItem(`oauth_provider:${state}`);
   if (!provider || !isSupportedProvider(provider)) {
     throw new Error("Unable to determine OAuth provider. State may have expired.");
   }
-  return sso[provider].callback(code, state);
+  return ssoProviders[provider].link(code, state);
 }
 
 var AuthState = /* @__PURE__ */ ((AuthState2) => {
@@ -954,10 +1003,9 @@ exports.StateMismatchError = StateMismatchError;
 exports.accountToUser = accountToUser;
 exports.getAllSSOProviders = getAllSSOProviders;
 exports.getSSOProvider = getSSOProvider;
-exports.handleOAuthCallback = handleOAuthCallback;
 exports.initAuth = initAuth;
 exports.isSupportedProvider = isSupportedProvider;
 exports.setAuthContext = setAuthContext;
 exports.sso = sso;
-exports.ssoProviders = ssoProviders;
+exports.ssoProvidersList = ssoProvidersList;
 exports.useAuth = useAuth;

package/dist/index.d.cts

@@ -197,6 +197,7 @@ interface SSOCallbackRequest {
 interface SSOLinkRequest {
     provider: SSOProvider;
     code: string;
+    state: string;
 }
 interface SSOUnlinkRequest {
     provider: SSOProvider;
@@ -459,8 +460,9 @@ interface SSOProviderInstance extends SSOProviderConfig {
     callback: (code: string, state?: string) => Promise<AuthenticationResponse>;
     /**
      * Link this provider to the current logged-in user
+     * Call this after OAuth redirect completes on link callback page
      */
-    link: (code: string) => Promise<void>;
+    link: (code: string, state?: string) => Promise<void>;
     /**
      * Unlink this provider from the current user
      */
@@ -476,86 +478,26 @@ interface SSOProviderInstance extends SSOProviderConfig {
     supportsPopup?: boolean;
 }
 /**
- * SSO Provider Implementations
+ * SSO object type with providers and helper methods
  */
-declare const sso: {
-    /**
-     * Google OAuth Provider
-     * https://developers.google.com/identity/protocols/oauth2
-     */
+interface SSOObject {
     google: SSOProviderInstance;
-    /**
-     * Microsoft OAuth Provider (Azure AD / Microsoft Entra ID)
-     * https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow
-     */
     microsoft: SSOProviderInstance;
-    /**
-     * GitHub OAuth Provider
-     * https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps
-     */
     github: SSOProviderInstance;
-    /**
-     * Okta OAuth Provider
-     * https://developer.okta.com/docs/guides/implement-grant-type/authcode/main/
-     */
     okta: SSOProviderInstance;
-    /**
-     * Apple Sign In Provider
-     * https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api
-     * Note: Apple works best with redirect flow on web
-     */
-    apple: {
-        supportsPopup: boolean;
-        popup(options?: OAuthFlowOptions): Promise<any>;
-        /**
-         * Initiate OAuth flow with redirect (most common)
-         * User is redirected to provider's authorization page
-         */
-        redirect: (options?: OAuthFlowOptions) => Promise<void>;
-        /**
-         * Complete OAuth flow after callback
-         * Call this on your callback page
-         */
-        callback: (code: string, state?: string) => Promise<AuthenticationResponse>;
-        /**
-         * Link this provider to the current logged-in user
-         */
-        link: (code: string) => Promise<void>;
-        /**
-         * Unlink this provider from the current user
-         */
-        unlink: () => Promise<void>;
-        /**
-         * Get authorization URL without redirecting
-         */
-        getAuthUrl: (options?: OAuthFlowOptions) => Promise<string>;
-        /** Provider identifier */
-        id: SSOProvider;
-        /** Display name */
-        name: string;
-        /** Brand color (hex) */
-        color: string;
-        /** Icon identifier (for UI libraries) */
-        icon: string;
-        /** Default OAuth scopes */
-        defaultScopes: string[];
-        /** Provider-specific metadata */
-        metadata?: {
-            authDomain?: string;
-            buttonText?: string;
-            [key: string]: any;
-        };
-    };
-    /**
-     * Facebook OAuth Provider
-     * https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow
-     */
+    apple: SSOProviderInstance;
     facebook: SSOProviderInstance;
-};
+    handleCallback: () => Promise<AuthenticationResponse | null>;
+    handleLinkCallback: () => Promise<void>;
+}
+/**
+ * SSO object with providers and global helper methods
+ */
+declare const sso: SSOObject;
 /**
- * Array of all SSO providers
+ * Array of all SSO provider instances
  */
-declare const ssoProviders: readonly SSOProviderInstance[];
+declare const ssoProvidersList: readonly SSOProviderInstance[];
 /**
  * Get SSO provider instance by ID
  */
@@ -568,11 +510,6 @@ declare function getAllSSOProviders(): readonly SSOProviderInstance[];
  * Check if a provider is supported
  */
 declare function isSupportedProvider(provider: string): provider is SSOProvider;
-/**
- * Handle OAuth callback from URL
- * Call this on your callback page to automatically detect and process the callback
- */
-declare function handleOAuthCallback(): Promise<AuthenticationResponse | null>;
 
 declare function initAuth({ baseURL, }: {
     baseURL: string;
@@ -643,32 +580,7 @@ declare function useAuth(): {
             metadata?: Record<string, any> | undefined;
         } | undefined;
     } | null>;
-    sso: {
-        google: SSOProviderInstance;
-        microsoft: SSOProviderInstance;
-        github: SSOProviderInstance;
-        okta: SSOProviderInstance;
-        apple: {
-            supportsPopup: boolean;
-            popup(options?: OAuthFlowOptions): Promise<any>;
-            redirect: (options?: OAuthFlowOptions) => Promise<void>;
-            callback: (code: string, state?: string) => Promise<AuthenticationResponse>;
-            link: (code: string) => Promise<void>;
-            unlink: () => Promise<void>;
-            getAuthUrl: (options?: OAuthFlowOptions) => Promise<string>;
-            id: SSOProvider;
-            name: string;
-            color: string;
-            icon: string;
-            defaultScopes: string[];
-            metadata?: {
-                authDomain?: string;
-                buttonText?: string;
-                [key: string]: any;
-            };
-        };
-        facebook: SSOProviderInstance;
-    };
+    sso: SSOObject;
     getFullName: () => string;
     getIsLoggedIn: () => boolean;
     getEmail: () => string;
@@ -704,5 +616,5 @@ declare function useAuth(): {
     revokeAllSessions: (accountId?: string) => Promise<void>;
 };
 
-export { AuthApi, AuthState, PopupBlockedError, PopupClosedError, PopupTimeoutError, SSOError, StateMismatchError, accountToUser, getAllSSOProviders, getSSOProvider, handleOAuthCallback, initAuth, isSupportedProvider, setAuthContext, sso, ssoProviders, useAuth };
-export type { AccountInfo, ActivateAccountResponse, AuthEventHandler, AuthEventMap, AuthMethodInfo, AuthStatusResponse, AuthenticationAccount, AuthenticationAccountType, AuthenticationMethodType, AuthenticationResponse, AvailableMethodsResponse, ChangePasswordRequest, ChangePasswordResponse, CleanupSessionsResponse, DeactivateAccountResponse, DeleteAccountResponse, DeleteAllSessionsResponse, DeleteMeResponse, DeleteSessionResponse, EntityInfo, ForgotPasswordRequest, ForgotPasswordResponse, GetAccountResponse, GetMeResponse, GetMethodsResponse, GetSessionsResponse, LoginResponse, LogoutResponse, MessageResponse, NewUser, OAuthFlowOptions, OTPMetadata, PasswordLoginRequest, PersonInfo, PopupResult, RefreshSessionResponse, RegisterRequest, RegisterResponse, ResetPasswordRequest, ResetPasswordResponse, SSOCallbackRequest, SSOCallbackResponse, SSOInitiateRequest, SSOInitiateResponse, SSOLinkRequest, SSOLinkResponse, SSOMetadata, SSOProvider, SSOProviderConfig, SSOProviderInstance, SSOUnlinkRequest, SSOUnlinkResponse, SendVerificationRequest, SendVerificationResponse, SessionInfo, SessionListResponse, UpdateAccountRequest, UpdateAccountResponse, UpdateMeResponse, UpdatePasswordForm, User, VerifyEmailRequest, VerifyEmailResponse, VerifyResetTokenResponse };
+export { AuthApi, AuthState, PopupBlockedError, PopupClosedError, PopupTimeoutError, SSOError, StateMismatchError, accountToUser, getAllSSOProviders, getSSOProvider, initAuth, isSupportedProvider, setAuthContext, sso, ssoProvidersList, useAuth };
+export type { AccountInfo, ActivateAccountResponse, AuthEventHandler, AuthEventMap, AuthMethodInfo, AuthStatusResponse, AuthenticationAccount, AuthenticationAccountType, AuthenticationMethodType, AuthenticationResponse, AvailableMethodsResponse, ChangePasswordRequest, ChangePasswordResponse, CleanupSessionsResponse, DeactivateAccountResponse, DeleteAccountResponse, DeleteAllSessionsResponse, DeleteMeResponse, DeleteSessionResponse, EntityInfo, ForgotPasswordRequest, ForgotPasswordResponse, GetAccountResponse, GetMeResponse, GetMethodsResponse, GetSessionsResponse, LoginResponse, LogoutResponse, MessageResponse, NewUser, OAuthFlowOptions, OTPMetadata, PasswordLoginRequest, PersonInfo, PopupResult, RefreshSessionResponse, RegisterRequest, RegisterResponse, ResetPasswordRequest, ResetPasswordResponse, SSOCallbackRequest, SSOCallbackResponse, SSOInitiateRequest, SSOInitiateResponse, SSOLinkRequest, SSOLinkResponse, SSOMetadata, SSOObject, SSOProvider, SSOProviderConfig, SSOProviderInstance, SSOUnlinkRequest, SSOUnlinkResponse, SendVerificationRequest, SendVerificationResponse, SessionInfo, SessionListResponse, UpdateAccountRequest, UpdateAccountResponse, UpdateMeResponse, UpdatePasswordForm, User, VerifyEmailRequest, VerifyEmailResponse, VerifyResetTokenResponse };

package/dist/index.d.mts

@@ -197,6 +197,7 @@ interface SSOCallbackRequest {
 interface SSOLinkRequest {
     provider: SSOProvider;
     code: string;
+    state: string;
 }
 interface SSOUnlinkRequest {
     provider: SSOProvider;
@@ -459,8 +460,9 @@ interface SSOProviderInstance extends SSOProviderConfig {
     callback: (code: string, state?: string) => Promise<AuthenticationResponse>;
     /**
      * Link this provider to the current logged-in user
+     * Call this after OAuth redirect completes on link callback page
      */
-    link: (code: string) => Promise<void>;
+    link: (code: string, state?: string) => Promise<void>;
     /**
      * Unlink this provider from the current user
      */
@@ -476,86 +478,26 @@ interface SSOProviderInstance extends SSOProviderConfig {
     supportsPopup?: boolean;
 }
 /**
- * SSO Provider Implementations
+ * SSO object type with providers and helper methods
  */
-declare const sso: {
-    /**
-     * Google OAuth Provider
-     * https://developers.google.com/identity/protocols/oauth2
-     */
+interface SSOObject {
     google: SSOProviderInstance;
-    /**
-     * Microsoft OAuth Provider (Azure AD / Microsoft Entra ID)
-     * https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow
-     */
     microsoft: SSOProviderInstance;
-    /**
-     * GitHub OAuth Provider
-     * https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps
-     */
     github: SSOProviderInstance;
-    /**
-     * Okta OAuth Provider
-     * https://developer.okta.com/docs/guides/implement-grant-type/authcode/main/
-     */
     okta: SSOProviderInstance;
-    /**
-     * Apple Sign In Provider
-     * https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api
-     * Note: Apple works best with redirect flow on web
-     */
-    apple: {
-        supportsPopup: boolean;
-        popup(options?: OAuthFlowOptions): Promise<any>;
-        /**
-         * Initiate OAuth flow with redirect (most common)
-         * User is redirected to provider's authorization page
-         */
-        redirect: (options?: OAuthFlowOptions) => Promise<void>;
-        /**
-         * Complete OAuth flow after callback
-         * Call this on your callback page
-         */
-        callback: (code: string, state?: string) => Promise<AuthenticationResponse>;
-        /**
-         * Link this provider to the current logged-in user
-         */
-        link: (code: string) => Promise<void>;
-        /**
-         * Unlink this provider from the current user
-         */
-        unlink: () => Promise<void>;
-        /**
-         * Get authorization URL without redirecting
-         */
-        getAuthUrl: (options?: OAuthFlowOptions) => Promise<string>;
-        /** Provider identifier */
-        id: SSOProvider;
-        /** Display name */
-        name: string;
-        /** Brand color (hex) */
-        color: string;
-        /** Icon identifier (for UI libraries) */
-        icon: string;
-        /** Default OAuth scopes */
-        defaultScopes: string[];
-        /** Provider-specific metadata */
-        metadata?: {
-            authDomain?: string;
-            buttonText?: string;
-            [key: string]: any;
-        };
-    };
-    /**
-     * Facebook OAuth Provider
-     * https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow
-     */
+    apple: SSOProviderInstance;
     facebook: SSOProviderInstance;
-};
+    handleCallback: () => Promise<AuthenticationResponse | null>;
+    handleLinkCallback: () => Promise<void>;
+}
+/**
+ * SSO object with providers and global helper methods
+ */
+declare const sso: SSOObject;
 /**
- * Array of all SSO providers
+ * Array of all SSO provider instances
  */
-declare const ssoProviders: readonly SSOProviderInstance[];
+declare const ssoProvidersList: readonly SSOProviderInstance[];
 /**
  * Get SSO provider instance by ID
  */
@@ -568,11 +510,6 @@ declare function getAllSSOProviders(): readonly SSOProviderInstance[];
  * Check if a provider is supported
  */
 declare function isSupportedProvider(provider: string): provider is SSOProvider;
-/**
- * Handle OAuth callback from URL
- * Call this on your callback page to automatically detect and process the callback
- */
-declare function handleOAuthCallback(): Promise<AuthenticationResponse | null>;
 
 declare function initAuth({ baseURL, }: {
     baseURL: string;
@@ -643,32 +580,7 @@ declare function useAuth(): {
             metadata?: Record<string, any> | undefined;
         } | undefined;
     } | null>;
-    sso: {
-        google: SSOProviderInstance;
-        microsoft: SSOProviderInstance;
-        github: SSOProviderInstance;
-        okta: SSOProviderInstance;
-        apple: {
-            supportsPopup: boolean;
-            popup(options?: OAuthFlowOptions): Promise<any>;
-            redirect: (options?: OAuthFlowOptions) => Promise<void>;
-            callback: (code: string, state?: string) => Promise<AuthenticationResponse>;
-            link: (code: string) => Promise<void>;
-            unlink: () => Promise<void>;
-            getAuthUrl: (options?: OAuthFlowOptions) => Promise<string>;
-            id: SSOProvider;
-            name: string;
-            color: string;
-            icon: string;
-            defaultScopes: string[];
-            metadata?: {
-                authDomain?: string;
-                buttonText?: string;
-                [key: string]: any;
-            };
-        };
-        facebook: SSOProviderInstance;
-    };
+    sso: SSOObject;
     getFullName: () => string;
     getIsLoggedIn: () => boolean;
     getEmail: () => string;
@@ -704,5 +616,5 @@ declare function useAuth(): {
     revokeAllSessions: (accountId?: string) => Promise<void>;
 };
 
-export { AuthApi, AuthState, PopupBlockedError, PopupClosedError, PopupTimeoutError, SSOError, StateMismatchError, accountToUser, getAllSSOProviders, getSSOProvider, handleOAuthCallback, initAuth, isSupportedProvider, setAuthContext, sso, ssoProviders, useAuth };
-export type { AccountInfo, ActivateAccountResponse, AuthEventHandler, AuthEventMap, AuthMethodInfo, AuthStatusResponse, AuthenticationAccount, AuthenticationAccountType, AuthenticationMethodType, AuthenticationResponse, AvailableMethodsResponse, ChangePasswordRequest, ChangePasswordResponse, CleanupSessionsResponse, DeactivateAccountResponse, DeleteAccountResponse, DeleteAllSessionsResponse, DeleteMeResponse, DeleteSessionResponse, EntityInfo, ForgotPasswordRequest, ForgotPasswordResponse, GetAccountResponse, GetMeResponse, GetMethodsResponse, GetSessionsResponse, LoginResponse, LogoutResponse, MessageResponse, NewUser, OAuthFlowOptions, OTPMetadata, PasswordLoginRequest, PersonInfo, PopupResult, RefreshSessionResponse, RegisterRequest, RegisterResponse, ResetPasswordRequest, ResetPasswordResponse, SSOCallbackRequest, SSOCallbackResponse, SSOInitiateRequest, SSOInitiateResponse, SSOLinkRequest, SSOLinkResponse, SSOMetadata, SSOProvider, SSOProviderConfig, SSOProviderInstance, SSOUnlinkRequest, SSOUnlinkResponse, SendVerificationRequest, SendVerificationResponse, SessionInfo, SessionListResponse, UpdateAccountRequest, UpdateAccountResponse, UpdateMeResponse, UpdatePasswordForm, User, VerifyEmailRequest, VerifyEmailResponse, VerifyResetTokenResponse };
+export { AuthApi, AuthState, PopupBlockedError, PopupClosedError, PopupTimeoutError, SSOError, StateMismatchError, accountToUser, getAllSSOProviders, getSSOProvider, initAuth, isSupportedProvider, setAuthContext, sso, ssoProvidersList, useAuth };
+export type { AccountInfo, ActivateAccountResponse, AuthEventHandler, AuthEventMap, AuthMethodInfo, AuthStatusResponse, AuthenticationAccount, AuthenticationAccountType, AuthenticationMethodType, AuthenticationResponse, AvailableMethodsResponse, ChangePasswordRequest, ChangePasswordResponse, CleanupSessionsResponse, DeactivateAccountResponse, DeleteAccountResponse, DeleteAllSessionsResponse, DeleteMeResponse, DeleteSessionResponse, EntityInfo, ForgotPasswordRequest, ForgotPasswordResponse, GetAccountResponse, GetMeResponse, GetMethodsResponse, GetSessionsResponse, LoginResponse, LogoutResponse, MessageResponse, NewUser, OAuthFlowOptions, OTPMetadata, PasswordLoginRequest, PersonInfo, PopupResult, RefreshSessionResponse, RegisterRequest, RegisterResponse, ResetPasswordRequest, ResetPasswordResponse, SSOCallbackRequest, SSOCallbackResponse, SSOInitiateRequest, SSOInitiateResponse, SSOLinkRequest, SSOLinkResponse, SSOMetadata, SSOObject, SSOProvider, SSOProviderConfig, SSOProviderInstance, SSOUnlinkRequest, SSOUnlinkResponse, SendVerificationRequest, SendVerificationResponse, SessionInfo, SessionListResponse, UpdateAccountRequest, UpdateAccountResponse, UpdateMeResponse, UpdatePasswordForm, User, VerifyEmailRequest, VerifyEmailResponse, VerifyResetTokenResponse };

package/dist/index.d.ts

@@ -197,6 +197,7 @@ interface SSOCallbackRequest {
 interface SSOLinkRequest {
     provider: SSOProvider;
     code: string;
+    state: string;
 }
 interface SSOUnlinkRequest {
     provider: SSOProvider;
@@ -459,8 +460,9 @@ interface SSOProviderInstance extends SSOProviderConfig {
     callback: (code: string, state?: string) => Promise<AuthenticationResponse>;
     /**
      * Link this provider to the current logged-in user
+     * Call this after OAuth redirect completes on link callback page
      */
-    link: (code: string) => Promise<void>;
+    link: (code: string, state?: string) => Promise<void>;
     /**
      * Unlink this provider from the current user
      */
@@ -476,86 +478,26 @@ interface SSOProviderInstance extends SSOProviderConfig {
     supportsPopup?: boolean;
 }
 /**
- * SSO Provider Implementations
+ * SSO object type with providers and helper methods
  */
-declare const sso: {
-    /**
-     * Google OAuth Provider
-     * https://developers.google.com/identity/protocols/oauth2
-     */
+interface SSOObject {
     google: SSOProviderInstance;
-    /**
-     * Microsoft OAuth Provider (Azure AD / Microsoft Entra ID)
-     * https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow
-     */
     microsoft: SSOProviderInstance;
-    /**
-     * GitHub OAuth Provider
-     * https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps
-     */
     github: SSOProviderInstance;
-    /**
-     * Okta OAuth Provider
-     * https://developer.okta.com/docs/guides/implement-grant-type/authcode/main/
-     */
     okta: SSOProviderInstance;
-    /**
-     * Apple Sign In Provider
-     * https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api
-     * Note: Apple works best with redirect flow on web
-     */
-    apple: {
-        supportsPopup: boolean;
-        popup(options?: OAuthFlowOptions): Promise<any>;
-        /**
-         * Initiate OAuth flow with redirect (most common)
-         * User is redirected to provider's authorization page
-         */
-        redirect: (options?: OAuthFlowOptions) => Promise<void>;
-        /**
-         * Complete OAuth flow after callback
-         * Call this on your callback page
-         */
-        callback: (code: string, state?: string) => Promise<AuthenticationResponse>;
-        /**
-         * Link this provider to the current logged-in user
-         */
-        link: (code: string) => Promise<void>;
-        /**
-         * Unlink this provider from the current user
-         */
-        unlink: () => Promise<void>;
-        /**
-         * Get authorization URL without redirecting
-         */
-        getAuthUrl: (options?: OAuthFlowOptions) => Promise<string>;
-        /** Provider identifier */
-        id: SSOProvider;
-        /** Display name */
-        name: string;
-        /** Brand color (hex) */
-        color: string;
-        /** Icon identifier (for UI libraries) */
-        icon: string;
-        /** Default OAuth scopes */
-        defaultScopes: string[];
-        /** Provider-specific metadata */
-        metadata?: {
-            authDomain?: string;
-            buttonText?: string;
-            [key: string]: any;
-        };
-    };
-    /**
-     * Facebook OAuth Provider
-     * https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow
-     */
+    apple: SSOProviderInstance;
     facebook: SSOProviderInstance;
-};
+    handleCallback: () => Promise<AuthenticationResponse | null>;
+    handleLinkCallback: () => Promise<void>;
+}
+/**
+ * SSO object with providers and global helper methods
+ */
+declare const sso: SSOObject;
 /**
- * Array of all SSO providers
+ * Array of all SSO provider instances
  */
-declare const ssoProviders: readonly SSOProviderInstance[];
+declare const ssoProvidersList: readonly SSOProviderInstance[];
 /**
  * Get SSO provider instance by ID
  */
@@ -568,11 +510,6 @@ declare function getAllSSOProviders(): readonly SSOProviderInstance[];
  * Check if a provider is supported
  */
 declare function isSupportedProvider(provider: string): provider is SSOProvider;
-/**
- * Handle OAuth callback from URL
- * Call this on your callback page to automatically detect and process the callback
- */
-declare function handleOAuthCallback(): Promise<AuthenticationResponse | null>;
 
 declare function initAuth({ baseURL, }: {
     baseURL: string;
@@ -643,32 +580,7 @@ declare function useAuth(): {
             metadata?: Record<string, any> | undefined;
         } | undefined;
     } | null>;
-    sso: {
-        google: SSOProviderInstance;
-        microsoft: SSOProviderInstance;
-        github: SSOProviderInstance;
-        okta: SSOProviderInstance;
-        apple: {
-            supportsPopup: boolean;
-            popup(options?: OAuthFlowOptions): Promise<any>;
-            redirect: (options?: OAuthFlowOptions) => Promise<void>;
-            callback: (code: string, state?: string) => Promise<AuthenticationResponse>;
-            link: (code: string) => Promise<void>;
-            unlink: () => Promise<void>;
-            getAuthUrl: (options?: OAuthFlowOptions) => Promise<string>;
-            id: SSOProvider;
-            name: string;
-            color: string;
-            icon: string;
-            defaultScopes: string[];
-            metadata?: {
-                authDomain?: string;
-                buttonText?: string;
-                [key: string]: any;
-            };
-        };
-        facebook: SSOProviderInstance;
-    };
+    sso: SSOObject;
     getFullName: () => string;
     getIsLoggedIn: () => boolean;
     getEmail: () => string;
@@ -704,5 +616,5 @@ declare function useAuth(): {
     revokeAllSessions: (accountId?: string) => Promise<void>;
 };
 
-export { AuthApi, AuthState, PopupBlockedError, PopupClosedError, PopupTimeoutError, SSOError, StateMismatchError, accountToUser, getAllSSOProviders, getSSOProvider, handleOAuthCallback, initAuth, isSupportedProvider, setAuthContext, sso, ssoProviders, useAuth };
-export type { AccountInfo, ActivateAccountResponse, AuthEventHandler, AuthEventMap, AuthMethodInfo, AuthStatusResponse, AuthenticationAccount, AuthenticationAccountType, AuthenticationMethodType, AuthenticationResponse, AvailableMethodsResponse, ChangePasswordRequest, ChangePasswordResponse, CleanupSessionsResponse, DeactivateAccountResponse, DeleteAccountResponse, DeleteAllSessionsResponse, DeleteMeResponse, DeleteSessionResponse, EntityInfo, ForgotPasswordRequest, ForgotPasswordResponse, GetAccountResponse, GetMeResponse, GetMethodsResponse, GetSessionsResponse, LoginResponse, LogoutResponse, MessageResponse, NewUser, OAuthFlowOptions, OTPMetadata, PasswordLoginRequest, PersonInfo, PopupResult, RefreshSessionResponse, RegisterRequest, RegisterResponse, ResetPasswordRequest, ResetPasswordResponse, SSOCallbackRequest, SSOCallbackResponse, SSOInitiateRequest, SSOInitiateResponse, SSOLinkRequest, SSOLinkResponse, SSOMetadata, SSOProvider, SSOProviderConfig, SSOProviderInstance, SSOUnlinkRequest, SSOUnlinkResponse, SendVerificationRequest, SendVerificationResponse, SessionInfo, SessionListResponse, UpdateAccountRequest, UpdateAccountResponse, UpdateMeResponse, UpdatePasswordForm, User, VerifyEmailRequest, VerifyEmailResponse, VerifyResetTokenResponse };
+export { AuthApi, AuthState, PopupBlockedError, PopupClosedError, PopupTimeoutError, SSOError, StateMismatchError, accountToUser, getAllSSOProviders, getSSOProvider, initAuth, isSupportedProvider, setAuthContext, sso, ssoProvidersList, useAuth };
+export type { AccountInfo, ActivateAccountResponse, AuthEventHandler, AuthEventMap, AuthMethodInfo, AuthStatusResponse, AuthenticationAccount, AuthenticationAccountType, AuthenticationMethodType, AuthenticationResponse, AvailableMethodsResponse, ChangePasswordRequest, ChangePasswordResponse, CleanupSessionsResponse, DeactivateAccountResponse, DeleteAccountResponse, DeleteAllSessionsResponse, DeleteMeResponse, DeleteSessionResponse, EntityInfo, ForgotPasswordRequest, ForgotPasswordResponse, GetAccountResponse, GetMeResponse, GetMethodsResponse, GetSessionsResponse, LoginResponse, LogoutResponse, MessageResponse, NewUser, OAuthFlowOptions, OTPMetadata, PasswordLoginRequest, PersonInfo, PopupResult, RefreshSessionResponse, RegisterRequest, RegisterResponse, ResetPasswordRequest, ResetPasswordResponse, SSOCallbackRequest, SSOCallbackResponse, SSOInitiateRequest, SSOInitiateResponse, SSOLinkRequest, SSOLinkResponse, SSOMetadata, SSOObject, SSOProvider, SSOProviderConfig, SSOProviderInstance, SSOUnlinkRequest, SSOUnlinkResponse, SendVerificationRequest, SendVerificationResponse, SessionInfo, SessionListResponse, UpdateAccountRequest, UpdateAccountResponse, UpdateMeResponse, UpdatePasswordForm, User, VerifyEmailRequest, VerifyEmailResponse, VerifyResetTokenResponse };

package/dist/index.mjs

@@ -40,6 +40,17 @@ class EventEmitter {
     }
   }
 }
+function queryParams() {
+  if (typeof window === "undefined" || !window.location?.search) {
+    return {};
+  }
+  const params = new URLSearchParams(window.location.search);
+  const result = {};
+  params.forEach((value, key) => {
+    result[key] = value;
+  });
+  return result;
+}
 
 class AuthApi {
   api;
@@ -123,7 +134,8 @@ class AuthApi {
    */
   async linkSSOProvider(data) {
     return this.api.post(`/authentication/sso/${data.provider}/link`, {
-      code: data.code
+      code: data.code,
+      state: data.state
     });
   }
   /**
@@ -457,11 +469,20 @@ function createSSOProvider(config) {
         state
       });
     },
-    async link(code) {
+    async link(code, state) {
       const auth = getAuthApi();
+      if (typeof sessionStorage !== "undefined" && state) {
+        const storedState = sessionStorage.getItem(getStateKey());
+        sessionStorage.removeItem(getStateKey());
+        sessionStorage.removeItem(`oauth_provider:${state}`);
+        if (storedState && storedState !== state) {
+          throw new StateMismatchError();
+        }
+      }
       await auth.linkSSOProvider({
         provider: config.id,
-        code
+        code,
+        state
       });
     },
     async unlink() {
@@ -484,7 +505,7 @@ function createSSOProvider(config) {
     // Default, can be overridden per provider
   };
 }
-const sso = {
+const ssoProviders = {
   /**
    * Google OAuth Provider
    * https://developers.google.com/identity/protocols/oauth2
@@ -584,31 +605,59 @@ const sso = {
     }
   })
 };
-const ssoProviders = Object.values(sso);
+const sso = {
+  // All provider instances
+  ...ssoProviders,
+  /**
+   * Handle OAuth callback from URL automatically
+   * Detects provider from state and completes login
+   *
+   * @example
+   * // On /auth/callback page
+   * const result = await sso.handleCallback()
+   */
+  handleCallback: handleOAuthCallback,
+  /**
+   * Handle OAuth link callback from URL automatically
+   * Detects provider from state and completes linking
+   *
+   * @example
+   * // On /settings/link-callback page
+   * await sso.handleLinkCallback()
+   */
+  handleLinkCallback: handleOAuthLinkCallback
+};
+const ssoProvidersList = Object.values(ssoProviders);
 function getSSOProvider(provider) {
-  return sso[provider];
+  return ssoProviders[provider];
 }
 function getAllSSOProviders() {
-  return ssoProviders;
+  return ssoProvidersList;
 }
 function isSupportedProvider(provider) {
-  return provider in sso;
+  return provider in ssoProviders;
 }
-async function handleOAuthCallback() {
-  if (typeof window === "undefined") {
-    return null;
+function handleOAuthCallback() {
+  const { code, state } = queryParams();
+  if (!code || !state) {
+    return Promise.resolve(null);
   }
-  const urlParams = new URLSearchParams(window.location.search);
-  const code = urlParams.get("code");
-  const state = urlParams.get("state");
+  const provider = sessionStorage.getItem(`oauth_provider:${state}`);
+  if (!provider || !isSupportedProvider(provider)) {
+    throw new Error("Unable to determine OAuth provider. State may have expired.");
+  }
+  return ssoProviders[provider].callback(code, state);
+}
+function handleOAuthLinkCallback() {
+  const { code, state } = queryParams();
   if (!code || !state) {
-    return null;
+    throw new Error("Missing code or state parameter");
   }
   const provider = sessionStorage.getItem(`oauth_provider:${state}`);
   if (!provider || !isSupportedProvider(provider)) {
     throw new Error("Unable to determine OAuth provider. State may have expired.");
   }
-  return sso[provider].callback(code, state);
+  return ssoProviders[provider].link(code, state);
 }
 
 var AuthState = /* @__PURE__ */ ((AuthState2) => {
@@ -938,4 +987,4 @@ function useAuth() {
   };
 }
 
-export { AuthApi, AuthState, PopupBlockedError, PopupClosedError, PopupTimeoutError, SSOError, StateMismatchError, accountToUser, getAllSSOProviders, getSSOProvider, handleOAuthCallback, initAuth, isSupportedProvider, setAuthContext, sso, ssoProviders, useAuth };
+export { AuthApi, AuthState, PopupBlockedError, PopupClosedError, PopupTimeoutError, SSOError, StateMismatchError, accountToUser, getAllSSOProviders, getSSOProvider, initAuth, isSupportedProvider, setAuthContext, sso, ssoProvidersList, useAuth };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bagelink/auth",
   "type": "module",
-  "version": "1.4.182",
+  "version": "1.4.184",
   "description": "Bagelink auth package",
   "author": {
     "name": "Bagel Studio",

package/src/api.ts

@@ -136,6 +136,7 @@ export class AuthApi {
 	async linkSSOProvider(data: SSOLinkRequest): Promise<SSOLinkResponse> {
 		return this.api.post(`/authentication/sso/${data.provider}/link`, {
 			code: data.code,
+			state: data.state,
 		})
 	}
 

package/src/sso.ts

@@ -1,4 +1,5 @@
 import type { SSOProvider, AuthenticationResponse } from './types'
+import { queryParams } from './utils'
 
 // Global reference to auth API - will be set by setAuthContext
 let authApiRef: any = null
@@ -135,8 +136,9 @@ export interface SSOProviderInstance extends SSOProviderConfig {
 
 	/**
 	 * Link this provider to the current logged-in user
+	 * Call this after OAuth redirect completes on link callback page
 	 */
-	link: (code: string) => Promise<void>
+	link: (code: string, state?: string) => Promise<void>
 
 	/**
 	 * Unlink this provider from the current user
@@ -155,6 +157,23 @@ export interface SSOProviderInstance extends SSOProviderConfig {
 	supportsPopup?: boolean
 }
 
+/**
+ * SSO object type with providers and helper methods
+ */
+export interface SSOObject {
+	// Provider instances
+	google: SSOProviderInstance
+	microsoft: SSOProviderInstance
+	github: SSOProviderInstance
+	okta: SSOProviderInstance
+	apple: SSOProviderInstance
+	facebook: SSOProviderInstance
+
+	// Global helper methods
+	handleCallback: () => Promise<AuthenticationResponse | null>
+	handleLinkCallback: () => Promise<void>
+}
+
 /**
  * Helper to generate random state for CSRF protection
  * Uses 32 bytes (64 hex chars) for enhanced security
@@ -372,11 +391,25 @@ function createSSOProvider(config: SSOProviderConfig): SSOProviderInstance {
 			})
 		},
 
-		async link(code: string) {
+		async link(code: string, state?: string) {
 			const auth = getAuthApi()
+
+			// Verify state if it was stored (per-provider key)
+			if (typeof sessionStorage !== 'undefined' && state) {
+				const storedState = sessionStorage.getItem(getStateKey())
+				sessionStorage.removeItem(getStateKey())
+				// Clean up provider mapping
+				sessionStorage.removeItem(`oauth_provider:${state}`)
+
+				if (storedState && storedState !== state) {
+					throw new StateMismatchError()
+				}
+			}
+
 			await auth.linkSSOProvider({
 				provider: config.id,
 				code,
+				state,
 			})
 		},
 
@@ -404,9 +437,9 @@ function createSSOProvider(config: SSOProviderConfig): SSOProviderInstance {
 }
 
 /**
- * SSO Provider Implementations
+ * SSO Provider Implementations with global helpers
  */
-export const sso = {
+const ssoProviders = {
 	/**
 	 * Google OAuth Provider
 	 * https://developers.google.com/identity/protocols/oauth2
@@ -512,54 +545,96 @@ export const sso = {
 }
 
 /**
- * Array of all SSO providers
+ * SSO object with providers and global helper methods
  */
-export const ssoProviders = Object.values(sso) as readonly SSOProviderInstance[]
+export const sso: SSOObject = {
+	// All provider instances
+	...ssoProviders,
+
+	/**
+	 * Handle OAuth callback from URL automatically
+	 * Detects provider from state and completes login
+	 *
+	 * @example
+	 * // On /auth/callback page
+	 * const result = await sso.handleCallback()
+	 */
+	handleCallback: handleOAuthCallback,
+
+	/**
+	 * Handle OAuth link callback from URL automatically
+	 * Detects provider from state and completes linking
+	 *
+	 * @example
+	 * // On /settings/link-callback page
+	 * await sso.handleLinkCallback()
+	 */
+	handleLinkCallback: handleOAuthLinkCallback,
+}
+
+/**
+ * Array of all SSO provider instances
+ */
+export const ssoProvidersList = Object.values(ssoProviders) as readonly SSOProviderInstance[]
 
 /**
  * Get SSO provider instance by ID
  */
 export function getSSOProvider(provider: SSOProvider): SSOProviderInstance | undefined {
-	return sso[provider]
+	return ssoProviders[provider]
 }
 
 /**
  * Get all available SSO providers
  */
 export function getAllSSOProviders(): readonly SSOProviderInstance[] {
-	return ssoProviders
+	return ssoProvidersList
 }
 
 /**
  * Check if a provider is supported
  */
 export function isSupportedProvider(provider: string): provider is SSOProvider {
-	return provider in sso
+	return provider in ssoProviders
 }
 
 /**
  * Handle OAuth callback from URL
- * Call this on your callback page to automatically detect and process the callback
+ * Internal helper - use sso.handleCallback() instead
  */
-export async function handleOAuthCallback(): Promise<AuthenticationResponse | null> {
-	if (typeof window === 'undefined') {
-		return null
+function handleOAuthCallback(): Promise<AuthenticationResponse | null> {
+	const { code, state } = queryParams()
+	if (!code || !state) {
+		return Promise.resolve(null)
+	}
+
+	// Get the provider from sessionStorage (stored during redirect/popup)
+	const provider = sessionStorage.getItem(`oauth_provider:${state}`) as SSOProvider | null
+
+	if (!provider || !isSupportedProvider(provider)) {
+		throw new Error('Unable to determine OAuth provider. State may have expired.')
 	}
 
-	const urlParams = new URLSearchParams(window.location.search)
-	const code = urlParams.get('code')
-	const state = urlParams.get('state')
+	return ssoProviders[provider].callback(code, state)
+}
+
+/**
+ * Handle OAuth link callback from URL
+ * Internal helper - use sso.handleLinkCallback() instead
+ */
+function handleOAuthLinkCallback(): Promise<void> {
+	const { code, state } = queryParams()
 
 	if (!code || !state) {
-		return null
+		throw new Error('Missing code or state parameter')
 	}
 
-	// Get the provider from sessionStorage (stored during redirect/popup)
+	// Get the provider from sessionStorage (stored during redirect)
 	const provider = sessionStorage.getItem(`oauth_provider:${state}`) as SSOProvider | null
 
 	if (!provider || !isSupportedProvider(provider)) {
 		throw new Error('Unable to determine OAuth provider. State may have expired.')
 	}
 
-	return sso[provider].callback(code, state)
+	return ssoProviders[provider].link(code, state)
 }

package/src/types.ts

@@ -244,6 +244,7 @@ export interface SSOCallbackRequest {
 export interface SSOLinkRequest {
 	provider: SSOProvider
 	code: string
+	state: string
 }
 
 export interface SSOUnlinkRequest {

package/src/utils.ts

@@ -44,3 +44,15 @@ export class EventEmitter {
 		}
 	}
 }
+
+export function queryParams(): Record<string, string> {
+	if (typeof window === 'undefined' || !window.location?.search) {
+		return {}
+	}
+	const params = new URLSearchParams(window.location.search)
+	const result: Record<string, string> = {}
+	params.forEach((value, key) => {
+		result[key] = value
+	})
+	return result
+}