@maka/maka-cli 5.3.1 → 5.3.2

package/bundle/typescript/src/generators/kits/auth/auth0-meteor.auth.gen.js

@@ -0,0 +1,894 @@
+import path from 'path';
+import fs from 'fs';
+import { Generator } from '../../../generator.js';
+import { Log } from '../../../tools/log/log.class.js';
+import AuthGen from './auth.generator.js';
+import MakaGen from '../../../generators/maka.gen.js';
+import { ClientEngines, } from '../../../tools/fsi/fsi.interfaces.js';
+Generator.create({
+    name: 'auth0',
+    aliases: ['a0'],
+    usage: 'maka {generate, g}:{kit, k}:{auth, a}:{auth0, a0}',
+    shortDesc: 'Generate Auth0 authentication integration with Meteor accounts',
+    validOpts: [{
+            name: 'force',
+            boolFlag: true,
+            description: 'Overwrite existing files'
+        }],
+    isPro: true,
+    resourceNameRequired: false,
+    mustBeInMakaProject: true,
+    requiredEngines: {
+        client: ClientEngines.REACT,
+    },
+    description: `
+    This kit generates an Auth0 authentication integration for your Meteor application.
+
+    It includes:
+    - Auth0 client SDK configuration
+    - Server-side JWT token validation with JWKS
+    - Account linking between Auth0 and Meteor
+    - Seamless integration with existing authentication provider
+  `
+}, async function (args, opts) {
+    const { fsi, pkg, scaffold, projectConfig } = this;
+    try {
+        const shouldForce = opts.force || false;
+        const projectDirectory = fsi.findProjectDirectory();
+        const isSsr = projectConfig.engines.ssr === 'meteor';
+        const jsEngine = projectConfig.engines.js;
+        Log.info('Setting up Auth0 authentication...');
+        // Install required npm packages
+        Log.info('Installing Auth0 dependencies...');
+        await pkg.checkNpmPackage(['@auth0/auth0-spa-js', 'jsonwebtoken', 'jwks-rsa'], { shouldInstall: true });
+        // Ensure auth provider exists
+        await MakaGen.processAndRunGenerator('kit:auth:provider', [], { force: shouldForce, cwd: projectDirectory, config: projectConfig });
+        // Ensure auth/roles publish exists
+        await MakaGen.processAndRunGenerator('publish', ['auth/roles'], { force: shouldForce, globalPublish: true, cwd: projectDirectory, config: projectConfig });
+        const resourceTopLevelPathLib = '/imports/startup/lib';
+        const resourceTopLevelPathClient = isSsr ? '/imports/startup/lib' : '/imports/startup/client';
+        const resourceTopLevelPathServer = '/imports/startup/server';
+        // ===================================================================================
+        // 1. Generate Auth0 Configuration (Shared)
+        // ===================================================================================
+        const pathToAuth0Config = scaffold.pathFromApp({
+            pathParts: [
+                resourceTopLevelPathLib,
+                '',
+                '',
+                'auth0-config'
+            ]
+        });
+        await scaffold.template({
+            srcPath: `kit/auth/service/auth0-config.js`,
+            destPath: `${pathToAuth0Config}.${jsEngine}`,
+            framework: 'react',
+            context: {},
+            config: projectConfig,
+            force: shouldForce,
+            ignore: false
+        });
+        // ===================================================================================
+        // 2. Generate Auth0 Client (Client-side)
+        // ===================================================================================
+        const pathToAuth0Client = scaffold.pathFromApp({
+            pathParts: [
+                resourceTopLevelPathClient,
+                '',
+                '',
+                'auth0-client'
+            ]
+        });
+        await scaffold.template({
+            srcPath: `kit/auth/service/auth0-client.js`,
+            destPath: `${pathToAuth0Client}.${jsEngine}`,
+            framework: 'react',
+            context: {},
+            config: projectConfig,
+            force: shouldForce,
+            ignore: false
+        });
+        // ===================================================================================
+        // 3. Generate Auth0 Validator (Server-side)
+        // ===================================================================================
+        const pathToAuth0Validator = scaffold.pathFromApp({
+            pathParts: [
+                resourceTopLevelPathServer,
+                '',
+                '',
+                'auth0-validator'
+            ]
+        });
+        await scaffold.template({
+            srcPath: `kit/auth/service/auth0-validator.js`,
+            destPath: `${pathToAuth0Validator}.${jsEngine}`,
+            framework: 'react',
+            context: {},
+            config: projectConfig,
+            force: shouldForce,
+            ignore: false
+        });
+        // ===================================================================================
+        // 4. Generate Auth0 Methods (Server-side)
+        // ===================================================================================
+        const pathToAuth0Methods = scaffold.pathFromApp({
+            pathParts: [
+                resourceTopLevelPathServer,
+                'methods',
+                '',
+                'auth0-methods'
+            ]
+        });
+        await scaffold.template({
+            srcPath: `kit/auth/service/auth0-methods.js`,
+            destPath: `${pathToAuth0Methods}.${jsEngine}`,
+            framework: 'react',
+            context: {},
+            config: projectConfig,
+            force: shouldForce,
+            ignore: false
+        });
+        // ===================================================================================
+        // 5. Update authentication-service with Auth0 methods
+        // ===================================================================================
+        const pathToAuthService = scaffold.pathFromApp({
+            pathParts: [
+                resourceTopLevelPathClient,
+                '',
+                '',
+                'authentication-service'
+            ]
+        });
+        // Import Auth0 client functions
+        await scaffold.injectAtBeginningOfFile({
+            filePath: `${pathToAuthService}.${jsEngine}`,
+            content: `import {
+  loginWithAuth0Redirect,
+  loginWithAuth0Popup,
+  handleAuth0Callback,
+  logoutAuth0,
+  getAuth0IdToken,
+  getAuth0AccessToken,
+  refreshAuth0Token,
+} from './auth0-client';
+`
+        });
+        // Add Auth0 methods to AuthService class
+        const auth0Methods = `
+  // ============================================================================
+  // Auth0 Authentication Methods
+  // ============================================================================
+
+  /**
+   * Login with Auth0 using redirect flow
+   * User will be redirected to Auth0 login page
+   */
+  static async loginWithAuth0Redirect() {
+    try {
+      await loginWithAuth0Redirect();
+    } catch (error) {
+      console.error('Auth0 redirect login failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Login with Auth0 using popup flow
+   * Returns the authenticated Meteor user
+   */
+  static async loginWithAuth0Popup() {
+    try {
+      // Open Auth0 login popup and get tokens
+      const { idToken, accessToken } = await loginWithAuth0Popup();
+
+      // Call Meteor method to validate token and create/link user
+      const result = await Meteor.callAsync('auth0.login', idToken, accessToken);
+
+      // Login to Meteor with the generated token
+      return new Promise((resolve, reject) => {
+        Meteor.loginWithToken(result.token, (error) => {
+          if (error) {
+            reject(error);
+          } else {
+            resolve(Meteor.user());
+          }
+        });
+      });
+    } catch (error) {
+      console.error('Auth0 popup login failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Handle Auth0 callback after redirect
+   * Call this method on your callback page
+   */
+  static async handleAuth0Callback() {
+    try {
+      // Handle the redirect and get tokens
+      const { idToken, accessToken } = await handleAuth0Callback();
+
+      // Call Meteor method to validate token and create/link user
+      const result = await Meteor.callAsync('auth0.login', idToken, accessToken);
+
+      // Login to Meteor with the generated token
+      return new Promise((resolve, reject) => {
+        Meteor.loginWithToken(result.token, (error) => {
+          if (error) {
+            reject(error);
+          } else {
+            resolve(Meteor.user());
+          }
+        });
+      });
+    } catch (error) {
+      console.error('Auth0 callback handling failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Link Auth0 account to currently logged in Meteor user
+   */
+  static async linkAuth0Account() {
+    try {
+      // Get current Auth0 tokens
+      const idToken = await getAuth0IdToken();
+      const accessToken = await getAuth0AccessToken();
+
+      // Call Meteor method to link accounts
+      await Meteor.callAsync('auth0.linkAccount', idToken, accessToken);
+
+      return true;
+    } catch (error) {
+      console.error('Auth0 account linking failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Unlink Auth0 account from current user
+   */
+  static async unlinkAuth0Account() {
+    try {
+      await Meteor.callAsync('auth0.unlinkAccount');
+      return true;
+    } catch (error) {
+      console.error('Auth0 account unlinking failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Logout from both Auth0 and Meteor
+   */
+  static async logoutAuth0() {
+    try {
+      // Logout from Meteor first
+      await this.deauthenticateUser();
+
+      // Then logout from Auth0
+      await logoutAuth0();
+    } catch (error) {
+      console.error('Auth0 logout failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Silently refresh the Auth0 token and update Meteor session
+   * This is called automatically when the token is about to expire
+   * Returns the updated expiry time
+   */
+  static async refreshAuth0Token() {
+    try {
+      // Get fresh tokens from Auth0 silently (using refresh token)
+      const { idToken, accessToken } = await refreshAuth0Token();
+
+      // Call Meteor method to validate and update tokens
+      const result = await Meteor.callAsync('auth0.refreshToken', idToken, accessToken);
+
+      return result;
+    } catch (error) {
+      console.error('Auth0 token refresh failed:', error);
+      throw error;
+    }
+  }
+`;
+        await scaffold.injectIntoFile({
+            filePath: `${pathToAuthService}.${jsEngine}`,
+            content: auth0Methods,
+            begin: 'static async resetPasswordWithToken',
+            end: '}\n\nexport default AuthService',
+            replace: false
+        });
+        // ===================================================================================
+        // 6. Update authentication-provider with Auth0 context methods
+        // ===================================================================================
+        const pathToAuthProvider = scaffold.pathFromApp({
+            pathParts: [
+                resourceTopLevelPathClient,
+                '',
+                '',
+                'authentication-provider'
+            ]
+        });
+        // Import AuthService if not already imported
+        await scaffold.injectAtBeginningOfFile({
+            filePath: `${pathToAuthProvider}.${jsEngine}`,
+            content: `import AuthService from './authentication-service';
+`
+        });
+        // Add Auth0 methods to context value
+        const auth0ProviderMethods = `    loginWithAuth0Redirect: AuthService.loginWithAuth0Redirect,
+    loginWithAuth0Popup: AuthService.loginWithAuth0Popup,
+    linkAuth0Account: AuthService.linkAuth0Account,
+    unlinkAuth0Account: AuthService.unlinkAuth0Account,
+`;
+        await scaffold.injectIntoFile({
+            filePath: `${pathToAuthProvider}.${jsEngine}`,
+            content: auth0ProviderMethods,
+            begin: 'const contextValue = useMemo\\(\\(\\) => \\(\\{',
+            end: '\\}\\), \\[',
+            replace: false
+        });
+        // Update the authentication-provider to delegate to AuthService
+        const authProviderFilePath = `${pathToAuthProvider}.${jsEngine}`;
+        let authProviderContent = fs.readFileSync(authProviderFilePath, 'utf8');
+        // Replace placeholder auth functions with AuthService delegations
+        authProviderContent = authProviderContent
+            // Replace authenticateUser function
+            .replace(/const authenticateUser = async \(username[^}]*\{[\s\S]*?throw new Error\('Invalid credentials'\);[\s\S]*?\};/, `const authenticateUser = async (username, password) => {
+  return AuthService.authenticateUser(username, password);
+};`)
+            // Replace authenticateToken function
+            .replace(/const authenticateToken = async \(\)[^}]*\{[\s\S]*?throw new Error\('Invalid token'\);[\s\S]*?\};/, `const authenticateToken = async () => {
+  return AuthService.authenticateToken();
+};`)
+            // Replace getUserAuthorizations function
+            .replace(/const getUserAuthorizations = async \(user[^}]*\{[\s\S]*?return \[\];[\s\S]*?\};/, `const getUserAuthorizations = async (user) => {
+  return AuthService.getUserAuthorizations(user?._id);
+};`)
+            // Replace deauthenticateUser function
+            .replace(/const deauthenticateUser = async \(\)[^}]*\{[\s\S]*?return true;[\s\S]*?\};/, `const deauthenticateUser = async () => {
+  return AuthService.deauthenticateUser();
+};`)
+            // Replace sendForgotPasswordEmail function
+            .replace(/const sendForgotPasswordEmail = async \(email[^}]*\{[\s\S]*?return true;[\s\S]*?\};/, `const sendForgotPasswordEmail = async (email) => {
+  return AuthService.sendForgotPasswordEmail(email);
+};`)
+            // Replace registerNewUser function
+            .replace(/const registerNewUser = async \(email, password[^}]*\{[\s\S]*?return true;[\s\S]*?\};/, `const registerNewUser = async (email, password) => {
+  return AuthService.registerNewUser(email, password);
+};`)
+            // Replace resetPasswordWithToken function
+            .replace(/const resetPasswordWithToken = async \(token, password[^}]*\{[\s\S]*?return true;[\s\S]*?\};/, `const resetPasswordWithToken = async (token, password) => {
+  return AuthService.resetPasswordWithToken(token, password);
+};`);
+        fs.writeFileSync(authProviderFilePath, authProviderContent, 'utf8');
+        // Add automatic Auth0 token refresh monitoring
+        const auth0TokenRefreshHook = jsEngine === 'tsx' ? `
+  // Auth0 automatic token refresh
+  // This hook monitors the Auth0 token expiration and refreshes it 15 seconds before expiry
+  useEffect(() => {
+    if (!currentUser) return;
+
+    let refreshTimer: NodeJS.Timeout;
+
+    const scheduleTokenRefresh = async () => {
+      try {
+        // Check if user has Auth0 account linked
+        const user = Meteor.user();
+        if (!user?.services?.auth0) return;
+
+        // Get token expiry from server
+        const tokenInfo = await Meteor.callAsync('auth0.checkTokenValidity');
+
+        if (!tokenInfo.isValid) {
+          // Token already expired, refresh immediately
+          await AuthService.refreshAuth0Token();
+          scheduleTokenRefresh(); // Schedule next refresh
+        } else if (tokenInfo.expiresAt) {
+          // Calculate time until 15 seconds before expiry
+          const expiresAt = new Date(tokenInfo.expiresAt).getTime();
+          const now = Date.now();
+          const refreshIn = expiresAt - now - 15000; // Refresh 15 seconds before expiry
+
+          if (refreshIn > 0) {
+            // Schedule refresh
+            refreshTimer = setTimeout(async () => {
+              try {
+                await AuthService.refreshAuth0Token();
+                scheduleTokenRefresh(); // Schedule next refresh after successful refresh
+              } catch (error) {
+                console.error('Failed to refresh Auth0 token:', error);
+                // If refresh fails, user will be logged out when token expires
+              }
+            }, refreshIn);
+          } else {
+            // Less than 15 seconds until expiry, refresh now
+            await AuthService.refreshAuth0Token();
+            scheduleTokenRefresh();
+          }
+        }
+      } catch (error) {
+        console.error('Error scheduling token refresh:', error);
+      }
+    };
+
+    scheduleTokenRefresh();
+
+    return () => {
+      if (refreshTimer) {
+        clearTimeout(refreshTimer);
+      }
+    };
+  }, [currentUser]);
+` : `
+  // Auth0 automatic token refresh
+  // This hook monitors the Auth0 token expiration and refreshes it 15 seconds before expiry
+  useEffect(() => {
+    if (!currentUser) return;
+
+    let refreshTimer;
+
+    const scheduleTokenRefresh = async () => {
+      try {
+        // Check if user has Auth0 account linked
+        const user = Meteor.user();
+        if (!user?.services?.auth0) return;
+
+        // Get token expiry from server
+        const tokenInfo = await Meteor.callAsync('auth0.checkTokenValidity');
+
+        if (!tokenInfo.isValid) {
+          // Token already expired, refresh immediately
+          await AuthService.refreshAuth0Token();
+          scheduleTokenRefresh(); // Schedule next refresh
+        } else if (tokenInfo.expiresAt) {
+          // Calculate time until 15 seconds before expiry
+          const expiresAt = new Date(tokenInfo.expiresAt).getTime();
+          const now = Date.now();
+          const refreshIn = expiresAt - now - 15000; // Refresh 15 seconds before expiry
+
+          if (refreshIn > 0) {
+            // Schedule refresh
+            refreshTimer = setTimeout(async () => {
+              try {
+                await AuthService.refreshAuth0Token();
+                scheduleTokenRefresh(); // Schedule next refresh after successful refresh
+              } catch (error) {
+                console.error('Failed to refresh Auth0 token:', error);
+                // If refresh fails, user will be logged out when token expires
+              }
+            }, refreshIn);
+          } else {
+            // Less than 15 seconds until expiry, refresh now
+            await AuthService.refreshAuth0Token();
+            scheduleTokenRefresh();
+          }
+        }
+      } catch (error) {
+        console.error('Error scheduling token refresh:', error);
+      }
+    };
+
+    scheduleTokenRefresh();
+
+    return () => {
+      if (refreshTimer) {
+        clearTimeout(refreshTimer);
+      }
+    };
+  }, [currentUser]);
+`;
+        await scaffold.injectIntoFile({
+            filePath: authProviderFilePath,
+            content: auth0TokenRefreshHook,
+            begin: 'useEffect\\(\\(\\) => \\{[\\s\\S]*?clearTimeout\\(logoutTimer\\);[\\s\\S]*?\\};[\\s\\S]*?\\}, \\[currentUser, timeoutDuration\\]\\);',
+            end: 'const contextValue = useMemo',
+            replace: false
+        });
+        // ===================================================================================
+        // 7. Import auth0-methods on server startup
+        // ===================================================================================
+        const serverIndexFilePath = scaffold.pathFromApp({
+            pathParts: [
+                'imports',
+                'startup',
+                'server',
+                'index'
+            ]
+        });
+        await scaffold.injectAtEndOfFile({
+            filePath: `${serverIndexFilePath}.${jsEngine}`,
+            content: `import './methods/auth0-methods';
+`
+        });
+        // ===================================================================================
+        // 8. Create settings.json example file
+        // ===================================================================================
+        const settingsExamplePath = path.join(projectDirectory, 'settings.auth0.json');
+        const settingsExample = {
+            public: {
+                auth0: {
+                    domain: 'YOUR_AUTH0_DOMAIN.auth0.com',
+                    clientId: 'YOUR_AUTH0_CLIENT_ID',
+                    audience: 'https://YOUR_AUTH0_DOMAIN.auth0.com/api/v2/',
+                    redirectUri: 'http://localhost:3000/auth/callback',
+                    scope: 'openid profile email'
+                }
+            },
+            auth0: {
+                domain: 'YOUR_AUTH0_DOMAIN.auth0.com',
+                clientId: 'YOUR_AUTH0_CLIENT_ID',
+                clientSecret: 'YOUR_AUTH0_CLIENT_SECRET',
+                audience: 'https://YOUR_AUTH0_DOMAIN.auth0.com/api/v2/',
+                redirectUri: 'http://localhost:3000/auth/callback',
+                scope: 'openid profile email'
+            }
+        };
+        if (!fsi.isFile(settingsExamplePath) || shouldForce) {
+            fsi.writeToFile({
+                filePath: settingsExamplePath,
+                data: JSON.stringify(settingsExample, null, 2)
+            });
+        }
+        // ===================================================================================
+        // 9. Create .env.example file
+        // ===================================================================================
+        const envExamplePath = path.join(projectDirectory, '.env.auth0.example');
+        const envExample = `# Auth0 Configuration
+# Copy this to your settings.json or .env file and fill in your Auth0 credentials
+
+AUTH0_DOMAIN=your-domain.auth0.com
+AUTH0_CLIENT_ID=your_client_id
+AUTH0_CLIENT_SECRET=your_client_secret
+AUTH0_AUDIENCE=https://your-domain.auth0.com/api/v2/
+AUTH0_REDIRECT_URI=http://localhost:3000/auth/callback
+AUTH0_SCOPE=openid profile email
+`;
+        if (!fsi.isFile(envExamplePath) || shouldForce) {
+            fsi.writeToFile({
+                filePath: envExamplePath,
+                data: envExample
+            });
+        }
+        // ===================================================================================
+        // 10. Create README documentation
+        // ===================================================================================
+        const readmePath = path.join(projectDirectory, 'README.auth0.md');
+        const readmeContent = `# Auth0 Authentication Integration
+
+This document explains how Auth0 authentication has been integrated into your Meteor application.
+
+## Overview
+
+This integration provides a complete Auth0 authentication solution that:
+
+- ✅ Supports both redirect and popup login flows
+- ✅ Validates JWT tokens server-side using JWKS
+- ✅ Automatically creates or links Meteor user accounts
+- ✅ Allows account linking for existing users
+- ✅ Provides seamless integration with your existing AuthContext
+
+## Architecture
+
+### Client-Side Components
+
+**\`${resourceTopLevelPathLib}/auth0-config.${jsEngine}\`**
+- Centralized Auth0 configuration
+- Reads settings from \`Meteor.settings.public.auth0\`
+- Provides configuration for both client and server
+
+**\`${resourceTopLevelPathClient}/auth0-client.${jsEngine}\`**
+- Auth0 SDK wrapper functions
+- Handles login redirects and popups
+- Manages Auth0 client instance
+- Retrieves ID tokens
+
+**\`${resourceTopLevelPathClient}/authentication-service.${jsEngine}\`**
+- Extended with Auth0 authentication methods
+- Bridges Auth0 with Meteor accounts
+- Provides static methods for all Auth0 operations
+
+**\`${resourceTopLevelPathClient}/authentication-provider.${jsEngine}\`**
+- Context updated with Auth0 methods
+- Makes Auth0 functions available throughout your app
+
+### Server-Side Components
+
+**\`${resourceTopLevelPathServer}/auth0-validator.${jsEngine}\`**
+- JWT token validation using JWKS
+- Verifies token signature and claims
+- Creates/updates user accounts from Auth0 data
+
+**\`${resourceTopLevelPathServer}/methods/auth0-methods.${jsEngine}\`**
+- Meteor methods for Auth0 operations
+- \`auth0.login\` - Authenticates with ID token
+- \`auth0.linkAccount\` - Links Auth0 to existing user
+- \`auth0.unlinkAccount\` - Removes Auth0 link
+
+## Setup Instructions
+
+### 1. Configure Auth0 Application
+
+1. Go to [Auth0 Dashboard](https://manage.auth0.com/)
+2. Create a new application (Single Page Application)
+3. Configure the following settings:
+   - **Allowed Callback URLs**: \`http://localhost:3000/auth/callback\`
+   - **Allowed Logout URLs**: \`http://localhost:3000\`
+   - **Allowed Web Origins**: \`http://localhost:3000\`
+   - **Allowed Origins (CORS)**: \`http://localhost:3000\`
+
+### 2. Update Configuration
+
+Edit \`settings.auth0.json\` with your Auth0 credentials:
+
+\`\`\`json
+{
+  "public": {
+    "auth0": {
+      "domain": "your-domain.auth0.com",
+      "clientId": "your_client_id",
+      "audience": "https://your-domain.auth0.com/api/v2/",
+      "redirectUri": "http://localhost:3000/auth/callback",
+      "scope": "openid profile email"
+    }
+  },
+  "auth0": {
+    "domain": "your-domain.auth0.com",
+    "clientId": "your_client_id",
+    "clientSecret": "your_client_secret",
+    "audience": "https://your-domain.auth0.com/api/v2/",
+    "redirectUri": "http://localhost:3000/auth/callback",
+    "scope": "openid profile email"
+  }
+}
+\`\`\`
+
+### 3. Start Your Application
+
+\`\`\`bash
+cd app
+meteor --settings ../settings.auth0.json
+\`\`\`
+
+## Usage
+
+### Using Auth0 in Components
+
+The Auth0 methods are available through the AuthContext:
+
+\`\`\`${jsEngine === 'tsx' ? 'typescript' : 'javascript'}
+import React, { useContext } from 'react';
+import { AuthContext } from '${resourceTopLevelPathClient}/authentication-provider';
+
+function LoginButton() {
+  const auth = useContext(AuthContext);
+
+  const handleLogin = async () => {
+    try {
+      // Option 1: Redirect flow (recommended)
+      await auth.loginWithAuth0Redirect?.();
+
+      // Option 2: Popup flow
+      // const user = await auth.loginWithAuth0Popup?.();
+      // console.log('Logged in user:', user);
+    } catch (error) {
+      console.error('Login failed:', error);
+    }
+  };
+
+  return <button onClick={handleLogin}>Login with Auth0</button>;
+}
+\`\`\`
+
+### Using AuthService Directly
+
+You can also use the AuthService static methods:
+
+\`\`\`${jsEngine === 'tsx' ? 'typescript' : 'javascript'}
+import AuthService from '${resourceTopLevelPathClient}/authentication-service';
+
+// Redirect login
+await AuthService.loginWithAuth0Redirect();
+
+// Popup login
+const user = await AuthService.loginWithAuth0Popup();
+
+// Handle callback (use in callback page)
+const user = await AuthService.handleAuth0Callback();
+
+// Link Auth0 to logged-in user
+await AuthService.linkAuth0Account();
+
+// Unlink Auth0 account
+await AuthService.unlinkAuth0Account();
+
+// Logout from both Auth0 and Meteor
+await AuthService.logoutAuth0();
+\`\`\`
+
+## Authentication Flow
+
+### Redirect Flow
+
+1. User clicks login button
+2. \`loginWithAuth0Redirect()\` redirects to Auth0 login page
+3. User authenticates with Auth0
+4. Auth0 redirects back to \`/auth/callback\`
+5. Callback page calls \`handleAuth0Callback()\`
+6. Server validates JWT and creates/links Meteor user
+7. User is logged into Meteor and redirected to home page
+
+### Popup Flow
+
+1. User clicks login button
+2. \`loginWithAuth0Popup()\` opens Auth0 login in popup
+3. User authenticates with Auth0
+4. Popup closes and ID token is returned
+5. Server validates JWT and creates/links Meteor user
+6. User is logged into Meteor
+7. Component receives user object
+
+## Account Linking
+
+Users can link their Auth0 account to an existing Meteor account:
+
+\`\`\`${jsEngine === 'tsx' ? 'typescript' : 'javascript'}
+// User must be logged in first
+const auth = useContext(AuthContext);
+await auth.linkAuth0Account?.();
+\`\`\`
+
+This allows users to:
+- Login with either Meteor credentials or Auth0
+- Maintain a single user account with multiple login methods
+- Unlink Auth0 if they no longer want to use it
+
+## User Data Structure
+
+When a user logs in with Auth0, their Meteor user document includes:
+
+\`\`\`javascript
+{
+  _id: "userId",
+  emails: [{ address: "user@example.com", verified: true }],
+  profile: { name: "John Doe" },
+  services: {
+    auth0: {
+      id: "auth0|123456789",
+      email: "user@example.com",
+      name: "John Doe",
+      picture: "https://...",
+      email_verified: true
+    }
+  }
+}
+\`\`\`
+
+## Security Features
+
+- **JWT Validation**: Tokens are verified using Auth0's JWKS endpoint
+- **Token Expiration**: Tokens are checked for expiration
+- **Issuer Verification**: Ensures tokens come from your Auth0 domain
+- **Audience Verification**: Validates tokens are for your application
+- **Account Linking Protection**: Prevents duplicate account linking
+
+## Troubleshooting
+
+### "Login failed: Invalid token" Error After Successful Login
+
+If you see this error message even though you're logged in, it's because the placeholder token validation code is still running. The Auth0 kit automatically comments out this code, but if you see this error:
+
+1. Check your \`authentication-provider.${jsEngine}\` file
+2. Look for the \`loginUserWithToken\` call in the \`useEffect\` hook
+3. Ensure it's commented out (the generator does this automatically)
+4. Meteor's authentication system handles token validation automatically
+
+### "Invalid token" Error During Login
+
+- Check that your Auth0 domain and clientId are correct
+- Verify the token hasn't expired
+- Ensure your Auth0 application settings are configured correctly
+- Make sure the domain in settings.json doesn't include \`https://\` (the kit handles this automatically)
+
+### "Auth0 configuration missing" Error
+
+- Make sure you're starting Meteor with \`--settings ../settings.auth0.json\`
+- Verify the settings file contains all required Auth0 configuration
+
+### Callback URL Mismatch
+
+- Ensure the callback URL in Auth0 dashboard matches your \`redirectUri\`
+- For production, update the callback URL to your production domain
+
+### CORS Errors
+
+- Add your domain to "Allowed Web Origins" in Auth0 dashboard
+- Ensure "Allowed Origins (CORS)" includes your domain
+
+## API Reference
+
+### AuthService Methods
+
+#### \`loginWithAuth0Redirect()\`
+Redirects user to Auth0 login page. User will leave your application.
+
+**Returns**: Promise<void>
+
+#### \`loginWithAuth0Popup()\`
+Opens Auth0 login in a popup window. User stays on your application.
+
+**Returns**: Promise<User>
+
+#### \`handleAuth0Callback()\`
+Handles the OAuth callback after redirect. Call this on your callback page.
+
+**Returns**: Promise<User>
+
+#### \`linkAuth0Account()\`
+Links Auth0 account to currently logged-in Meteor user.
+
+**Returns**: Promise<boolean>
+
+**Throws**: Error if user not logged in or account already linked
+
+#### \`unlinkAuth0Account()\`
+Removes Auth0 link from current user.
+
+**Returns**: Promise<boolean>
+
+**Throws**: Error if Auth0 is the only login method
+
+#### \`logoutAuth0()\`
+Logs out from both Meteor and Auth0.
+
+**Returns**: Promise<void>
+
+## Next Steps
+
+1. **Generate UI Components**: Run \`maka g:k:m:auth0\` to generate MUI login components
+2. **Customize User Profile**: Add additional user fields from Auth0 token
+3. **Add Roles**: Integrate with \`alanning:roles\` for authorization
+4. **Production Setup**: Update callback URLs for production domain
+5. **Social Connections**: Enable social login providers in Auth0 dashboard
+
+## Additional Resources
+
+- [Auth0 Documentation](https://auth0.com/docs)
+- [Auth0 SPA SDK](https://auth0.com/docs/libraries/auth0-spa-js)
+- [Meteor Accounts](https://docs.meteor.com/api/accounts.html)
+- [JWT.io](https://jwt.io/) - Debug JWT tokens
+
+## Support
+
+For issues specific to this integration, please check:
+- Auth0 dashboard for application configuration
+- Browser console for client-side errors
+- Meteor server logs for server-side errors
+- Network tab to inspect Auth0 API calls
+`;
+        if (!fsi.isFile(readmePath) || shouldForce) {
+            fsi.writeToFile({
+                filePath: readmePath,
+                data: readmeContent
+            });
+            Log.success('✓ Created README.auth0.md documentation');
+        }
+        Log.success('\n✓ Auth0 authentication integration generated successfully!');
+        Log.info('\nNext steps:');
+        Log.info('1. Configure your Auth0 application at https://manage.auth0.com/');
+        Log.info('2. Update settings.auth0.json with your Auth0 credentials');
+        Log.info('3. Start your app with: meteor --settings ../settings.auth0.json');
+        Log.info('4. Use AuthService.loginWithAuth0Redirect() or AuthService.loginWithAuth0Popup() in your components');
+        Log.info('\n📖 For detailed documentation, see README.auth0.md');
+    }
+    catch (e) {
+        Log.error(e);
+        process.exit(1);
+    }
+}, async function () { }, AuthGen);
+//# sourceMappingURL=auth0-meteor.auth.gen.js.map