\n\n```\n\n### Available Store Getters\n\n| Getter | Type | Description |\n|--------|------|-------------|\n| `isAuthenticated` | `boolean` | Whether the user is currently signed in |\n| `isReady` | `boolean` | Whether the auth state has been initialized |\n| `current_user` | `object \\| null` | Current Firebase user object |\n| `uid` | `string \\| null` | Current user's UID |\n| `email` | `string \\| null` | Current user's email |\n| `displayName` | `string \\| null` | Current user's display name |\n| `photoURL` | `string \\| null` | Current user's photo URL |\n| `emailVerified` | `boolean` | Whether the user's email is verified |\n| `is_loading` | `boolean` | Whether an auth operation is in progress |\n| `getError` | `object \\| null` | Last authentication error |\n\n### Available Store Methods\n\n| Method | Description |\n|--------|-------------|\n| `signOut()` | Sign out the current user |\n| `loginWithEmail(email, password, rememberMe)` | Sign in with email/password |\n| `registerUser(displayName, email, password)` | Register a new user |\n| `loginWithGoogle()` | Sign in with Google |\n| `loginWithFacebook()` | Sign in with Facebook |\n| `emailPasswordResetLink(email)` | Send password reset email |\n| `toggleAuthDialog(value?)` | Programmatically show/hide the auth dialog |\n\n### Programmatic Auth Dialog Control\n\nYou can trigger the authentication dialog programmatically from any component:\n\n```typescript\nimport { useAuthStore } from \"@nerd305/firebase-vuetify-auth\"\n\nconst authStore = useAuthStore()\n\n// Show the login dialog\nauthStore.toggleAuthDialog(true)\n\n// Or set directly\nauthStore.is_authguard_dialog_shown = true\n```\n\n### Protecting Route Content with AuthRouterView\n\nWhen a user signs out while on a protected route, you may want to show fallback content while keeping the URL intact. The package provides an `AuthRouterView` component:\n\n```vue\n\n \n \n \n \n \n \n\n\n\n```\n\nThe `AuthRouterView` component:\n- Shows the actual route component when authenticated\n- Shows fallback route content when unauthenticated on a protected route\n- Keeps the URL unchanged\n- Automatically switches back when user signs in\n\n**Props:**\n- `fallback-route` (optional): The route path for fallback content. Defaults to `'/'`\n\n### Integration Checklist\n\n- [ ] **Auth plugin file created** (`src/plugins/auth.ts`) with Firebase app instance and settings\n- [ ] **Plugin registered in `main.ts`** — `app.use(AuthGuard, authGuardSettings)`\n- [ ] **`` added to `App.vue`** inside ``\n- [ ] **`AuthMiddleware` applied to router** — `router.beforeEach(AuthMiddleware)`\n- [ ] **Protected routes marked** with `meta: { requiresAuth: true }`\n\n**Common Integration Issues:**\n1. **Missing ``** — The auth dialog won't appear\n2. **Missing `AuthMiddleware`** — Routes won't be protected\n3. **Content flash** — Gate `` behind `v-if=\"isAuthenticated\"` to prevent flash of protected content before auth state resolves\n4. **Wrong component placement** — Place `` at the same level as ``\n\n### Authentication Methods (Popup vs Redirect)\n\nThe package supports both popup and redirect authentication flows for OAuth providers (Google, Facebook, SAML):\n\n**Popup Method:**\n- Opens authentication in a popup window\n- Better for desktop browsers\n- May be blocked by popup blockers\n- Provides immediate feedback\n\n**Redirect Method:**\n- Redirects the entire page to the auth provider\n- Better for mobile devices\n- Requires additional setup for modern browsers (Chrome 115+, Firefox 109+, Safari 16.1+)\n- See [Firebase's redirect best practices](https://firebase.google.com/docs/auth/web/redirect-best-practices) for setup\n\n**Auto Mode (Default):**\n- Automatically selects popup for desktop and redirect for mobile\n- Provides the best user experience across devices\n- Falls back to the opposite method if the primary fails (configurable)\n\n## How It Works\n\nThis section provides an overview of the internal mechanism of the `firebase-vuetify-auth` package.\n\n### 1. Plugin Initialization (`src/wrapper.ts`)\nWhen you install the plugin using `app.use(AuthGuard, authGuardSettings)`:\n- The `authGuardSettings` are merged with default settings and stored in the Pinia store (`useAuthStore`).\n- Firebase Authentication is initialized (`getAuth`).\n- The **default session persistence** (e.g., \"local\", \"browser\") is set on the Firebase `auth` object based on the `session` property in `authGuardSettings`. This default applies to all sign-in methods unless overridden (e.g., by the \"Remember me\" checkbox for email/password).\n- An `onAuthStateChanged` listener is attached to Firebase. This listener is crucial for reacting to changes in the user's authentication state.\n\n### 2. Core UI Component: `` (`src/components/AuthGuard.vue`)\n- This component should be added to your main `App.vue`.\n- It renders the main authentication dialog (`v-dialog`).\n- The visibility of this dialog (`is_authguard_dialog_shown` state in Pinia) is controlled by the authentication logic.\n- The dialog contains tabs for Sign In, Register, Reset Password, and also houses the Email Verification screen.\n- Its internal state (like active tab) and the display of different forms (login, register, phone, email verification) are managed by the Pinia store.\n\n### 3. State Management (Pinia - `useAuthStore`)\nA dedicated Pinia store (`useAuthStore`) is the central hub for authentication-related state:\n- **`config`**: Stores the `authGuardSettings` provided during initialization.\n- **`current_user`**: Holds the Firebase user object when a user is authenticated.\n- **`is_loading`**, **`error`**: Manage loading states for asynchronous operations (like login attempts) and store any errors that occur.\n- **UI States**:\n - `is_authguard_dialog_shown`: Boolean, controls the visibility of the main authentication dialog.\n - `is_authguard_dialog_persistent`: Boolean, determines if the dialog can be closed by clicking outside or pressing Escape.\n - `is_email_verification_screen_shown`: Boolean, controls the visibility of the email verification prompt.\n - `tab`: Number, manages the active tab within the authentication dialog (Sign In, Register, Reset Password).\n - Other states related to phone login steps, password reset confirmation, etc.\n- **Actions**:\n - Functions like `loginWithEmail`, `registerUser`, `signOut`, `loginWithGoogle`, etc.\n - These actions typically call the corresponding Firebase SDK methods to perform authentication operations.\n - They update `is_loading` and `error` states and, upon success, Firebase's `onAuthStateChanged` listener (see below) will update the `current_user`.\n\n### 4. Firebase `onAuthStateChanged` Listener\n- Set up in `src/wrapper.ts`.\n- This listener fires whenever a user signs in or out of Firebase.\n- **Primary Action**: It updates the `authStore.current_user` with the new Firebase user object (or `null` if signed out).\n- **Triggers `authcheck()`**: After updating the user state, it calls the `authcheck()` function (see below) to re-evaluate route access permissions and dialog visibility based on the new authentication status.\n- **Email Verification Check**: If a user is authenticated but their email is not verified (and email verification is required by the configuration), this listener also sets up an interval to periodically reload the user's Firebase profile to check if their email has been verified. If verification occurs, the page is reloaded.\n\n### 5. Routing and Navigation Guard (`AuthMiddleware` from `src/components/authguard.ts`)\n- This middleware is intended to be registered globally with Vue Router using `router.beforeEach(AuthMiddleware)`.\n- **On Each Navigation**:\n - It inspects the target route (`to`) to see if it requires authentication (via `to.meta.requiresAuth: true`).\n - It determines if the navigation is from a public route to a protected route.\n - It updates two key states in the Pinia store:\n - `is_route_public`: Set to `true` if the target route does not require authentication, `false` otherwise.\n - `is_from_public_to_auth`: Set to `true` if navigating from a public page to a protected one, `false` otherwise. This influences dialog persistence.\n - **Calls `authcheck()`**: After updating these store states, it calls the `authcheck()` function to make the final decision on allowing or blocking the navigation.\n\n### 6. Core Logic Decider (`authcheck.ts` from `src/components/authcheck.ts`)\nThis function is the heart of the access control and dialog management logic. It is called in two main scenarios:\n1. By the `AuthMiddleware` during every route navigation.\n2. By the `onAuthStateChanged` listener whenever the Firebase authentication state changes.\n\n**`authcheck()` performs the following checks:**\n- **Is the route public?** (`store.is_route_public`): If yes, access is allowed, and the auth dialog is hidden.\n- **Is the user authenticated?** (checks `firebase.auth().currentUser`):\n - If **not authenticated** and trying to access a protected route:\n - The auth dialog (`is_authguard_dialog_shown`) is shown.\n - If navigating from a public route (`store.is_from_public_to_auth` is true), the dialog is made non-persistent (`is_authguard_dialog_persistent = false`), allowing the user to close it and stay on the public page.\n - Otherwise (e.g., initial load on a protected route), the dialog is persistent.\n - Navigation is blocked.\n - If **authenticated**:\n - **Email Verification Check**:\n - It checks `currentUser.emailVerified` against the `config.verification` rules (is verification required for all, or for specific domains?).\n - If verification is required and the user's email is not verified:\n - Access to the protected route is blocked.\n - The auth dialog is shown and made persistent.\n - The specific email verification screen is displayed (`is_email_verification_screen_shown = true`).\n - If email is verified, or verification is not required for this user:\n - Access to the protected route is allowed.\n - The auth dialog is hidden.\n- **Anonymous Users**: If email verification is active, anonymous users are generally blocked from protected resources that would require a verified email, as they cannot verify an email.\n- **Returns**: `true` if navigation/access is allowed, `false` otherwise. The `AuthMiddleware` uses this return value to call `next()` or `next(false)`.\n\n### 7. Email Verification Flow\n- If `authGuardSettings.verification` is enabled (either `true` for all or an array of domains):\n - When an authenticated but unverified user (matching the verification rules) attempts to access a protected route, `authcheck()` will:\n - Block access.\n - Show the auth dialog (`is_authguard_dialog_shown = true`).\n - Make the dialog persistent (`is_authguard_dialog_persistent = true`).\n - Display the email verification screen (`is_email_verification_screen_shown = true`) within the dialog. This screen prompts the user to check their email and provides an option to resend the verification email.\n - The `onAuthStateChanged` listener in `src/wrapper.ts` includes logic to periodically reload the user's Firebase profile. If `currentUser.emailVerified` becomes `true`, it reloads the entire page to reflect the verified state and grant access.\n\n### 8. Dialog Persistence\nThe authentication dialog's persistence (whether it can be closed by clicking outside or pressing Escape) is dynamically managed:\n- **Persistent**:\n - Typically when the user initially lands on a protected route and is not authenticated.\n - When email verification is required and the user's email is not yet verified.\n- **Non-Persistent (Closable)**:\n - When a user navigates from a public page to a protected page. This allows them to close the dialog and remain on the public page if they choose not to sign in.\n\nThis mechanism ensures that users are appropriately prompted for authentication or verification while providing a user-friendly experience for different navigation scenarios.\n\n## Testing Scenarios\n\nFor detailed examples of expected behavior under various conditions (user signed off, signed in with unconfirmed email, different verification settings, etc.), please refer to the manual test scenarios outlined in:\n[`src/tests/README.md`](./src/tests/README.md)\n\nThis document provides a structured way to test the core functionalities and edge cases of the package.\n\n## Phone Authentication (reCAPTCHA)\n\nIf you enable phone authentication (`phone: true` in `authGuardSettings`), you must:\n\n1. **Enable Phone Authentication in Firebase Console**:\n - Go to Firebase Console → Authentication → Sign-in method\n - Enable \"Phone\" as a sign-in provider\n - Add your testing phone numbers if in development\n\n2. **Include reCAPTCHA container**: Add an empty `div` with ID `recaptcha-container` in your main application template:\n\nExample in `App.vue`:\n```html\n\n \n \n\n \n \n\n \n \n\n```\n\n3. **Common Issues**:\n - If you see \"appVerificationDisabledForTesting\" error, ensure phone auth is enabled in Firebase Console\n - The reCAPTCHA verifier requires a valid Firebase project with phone authentication enabled\n - In development, add test phone numbers in Firebase Console to bypass SMS verification\n\n## Security Note\n\nThis package facilitates client-side authentication flows with Firebase. **It is crucial to understand that client-side code, including Firebase API keys and configuration, is publicly accessible.**\n\n**True security for your application's data and backend resources must be enforced through Firebase Security Rules** (for Firestore, Realtime Database, and Cloud Storage) and by correctly configuring your Firebase Authentication providers in the Firebase console. This package helps manage the user's authentication state on the client but does not, by itself, secure your backend. Always ensure your Firebase Security Rules are robust and properly tested.\n\n## Troubleshooting\n\n### Authentication Dialog Shows a Loading State\nDuring initial page load or after a page refresh, you may briefly see a loading state in the authentication dialog. This is normal behavior as the package waits for Firebase to restore the authentication state. The loading state ensures that:\n- Previously authenticated users are not incorrectly shown the login form\n- The authentication state is fully initialized before making navigation decisions\n- Firebase has time to check for redirect results from OAuth providers\n\n### Protected Routes and Direct URL Access\nWhen accessing a protected route directly (e.g., by entering the URL in the browser):\n- If authenticated: The route loads immediately\n- If not authenticated: Navigation is blocked, and the authentication dialog appears as a persistent modal\n- After successful authentication: You are automatically redirected to the originally requested route\n\n### That's it!\n\nAfter following implementation instruction requests to protected views, should render a login / registration view, unless user is already logged into the application.\n\nFor more usage examples (how to log in/sign out and so on) please check the package source code\n\n## Demo Application\n\nThe included demo application (`npm run dev`) features an interactive settings panel that allows you to:\n- Toggle authentication providers (Email, Phone, Google, Facebook, SAML) on/off\n- Enable/disable user registration\n- Toggle email verification requirements\n- See real-time which providers are active\n- All settings are persisted in localStorage\n\nThis makes it easy to test different authentication configurations without modifying code. Simply toggle the settings you want to test and refresh the page to apply the changes.\n\n## Available Settings\n\n| Prop | Type | Default | Description |\n| ------------ | ---------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| `router` | Vue Router Instance | `null` | **Required.** Your Vue Router instance. |\n| `firebase` | Firebase App Instance | `null` | **Required.** Your initialized Firebase app instance (from `initializeApp()`). |\n| `session` | String | `\"local\"` | Default Firebase auth state session persistence for all auth methods. Options: `\"local\"`, `\"browser\"` (or `\"session\"`), `\"none\"`. The \"Remember me\" checkbox for email/password login overrides this for that specific login. See [Firebase Docs](https://firebase.google.com/docs/auth/web/auth-state-persistence). |\n| `verification` | Boolean or Array | `false` | Requires email verification. `true` for all new accounts, or an array of specific email domains (e.g., `['yourdomain.com']`) to target. |\n| `registration` | Boolean | `true` | `true` to allow new user registrations through the UI, `false` to disable. |\n| `debug` | Boolean | `false` | `true` to enable verbose console logging from the package, `false` to disable. |\n| `email` | Boolean | `true` | `true` to enable email/password authentication method. |\n| `phone` | Boolean | `false` | `true` to enable phone number authentication method. (Requires reCAPTCHA setup, see above). |\n| `google` | Boolean | `true` | `true` to enable Google Sign-In authentication method. |\n| `facebook` | Boolean | `false` | `true` to enable Facebook Sign-In authentication method. |\n| `saml` | Boolean | `false` | `true` to enable SAML-based authentication. |\n| `saml_text` | String | `\"Login with OKTA\"` | Custom text for the SAML login button (if `saml` is `true` and it's the only 3rd party provider). |\n| `saml_provider_id` | String | `\"saml.okta\"` | Your Firebase SAML Provider ID (e.g., `\"saml.myprovider\"`) (if `saml` is `true`). |\n| `title` | String | `\"Authenticate\"` | Title displayed on the authentication dialog. |\n| `subtitle` | String | `\"Firebase Vuetify Authentication NPM package\"` | Subtitle displayed on the authentication dialog. |\n| `icon` | String | `\"mdi-brightness-7\"` | MDI icon class for the icon displayed on the authentication dialog. |\n| `iconColor` | String | `\"orange\"` | Color of the icon on the authentication dialog. |\n","readmeFilename":"README.md"}