mnfst 0.5.136 → 0.5.138

package/lib/manifest.appwrite.auth.js

@@ -69,12 +69,14 @@ async function getAppwriteConfig() {
     // Get auth methods from config (defaults to ["magic", "oauth"] if not specified)
     const authMethods = appwriteConfig.auth?.methods || ["magic", "oauth"];
 
-    // Guest session support: "guest-auto" = automatic, "guest-manual" = manual only
-    const guestAuto = authMethods.includes("guest-auto");
+    // Guest session support: "guest"/"guest-auto" = automatic, "guest-manual" = manual only.
+    // ("guest" is the schema's documented spelling; "guest-auto" is accepted as a synonym.)
+    const guestAuto = authMethods.includes("guest") || authMethods.includes("guest-auto");
     const guestManual = authMethods.includes("guest-manual");
     const hasGuest = guestAuto || guestManual;
 
     const magicEnabled = authMethods.includes("magic");
+    const otpEnabled = authMethods.includes("otp");
     const oauthEnabled = authMethods.includes("oauth");
 
     // Teams support: presence of teams object enables it
@@ -82,6 +84,15 @@ async function getAppwriteConfig() {
     const permanentTeams = appwriteConfig.auth?.teams?.permanent || null; // Array of team names (immutable)
     const templateTeams = appwriteConfig.auth?.teams?.template || null; // Array of team names (can be deleted and reapplied)
     const teamsPollInterval = appwriteConfig.auth?.teams?.pollInterval || null; // Polling interval in milliseconds (null = disabled)
+    const guestTeams = !!appwriteConfig.auth?.teams?.guests; // Seed default teams for guest (anonymous) sessions
+
+    // Guest upgrade: preserve the anonymous account (and its teams) when a guest signs in,
+    // rather than discarding it and minting a fresh user. Supported by magic links and OAuth;
+    // email OTP cannot convert anonymous accounts (Appwrite limitation). Defaults to guestTeams,
+    // since orphaning guest-created teams on signup is the failure mode guest teams introduce.
+    const guestUpgrade = appwriteConfig.auth?.guestUpgrade !== undefined
+        ? !!appwriteConfig.auth.guestUpgrade
+        : guestTeams;
 
     // Default roles: permanent (cannot be deleted) and template (can be deleted)
     // These are objects mapping role names to permissions: { "Admin": ["inviteMembers", ...] }
@@ -97,6 +108,11 @@ async function getAppwriteConfig() {
     // Creator role: string reference to a role in memberRoles (role creator gets by default)
     const creatorRole = appwriteConfig.auth?.creatorRole || null;
 
+    // Guest migration: id of the deployed guest-migration Appwrite Function. When set,
+    // a guest's teams are carried over to the account they sign into via OTP (which
+    // Appwrite can't convert in place). See templates/guest-migration-function.
+    const guestMigrationFunctionId = appwriteConfig.auth?.guestMigration?.functionId || null;
+
     return {
         endpoint,
         projectId,
@@ -107,11 +123,15 @@ async function getAppwriteConfig() {
         guestManual: guestManual,
         anonymous: guestAuto, // For backwards compatibility with existing code
         magic: magicEnabled,
+        otp: otpEnabled, // Email one-time-passcode authentication
         oauth: oauthEnabled,
         teams: teamsEnabled,
         permanentTeams: permanentTeams, // Array of team names (cannot be deleted)
         templateTeams: templateTeams, // Array of team names (can be deleted and reapplied)
         teamsPollInterval: teamsPollInterval, // Polling interval in milliseconds (null = disabled)
+        guestTeams: guestTeams, // Seed default teams for guest (anonymous) sessions
+        guestUpgrade: guestUpgrade, // Preserve guest account + teams on sign-in (magic/oauth)
+        guestMigrationFunctionId: guestMigrationFunctionId, // Carry guest teams to the OTP account via this function
         memberRoles: memberRoles, // Role definitions: { "RoleName": ["permission1", "permission2"] }
         permanentRoles: permanentRoles, // Object: { "RoleName": ["permission1", ...] } (cannot be deleted)
         templateRoles: templateRoles, // Object: { "RoleName": ["permission1", ...] } (can be deleted)
@@ -161,6 +181,7 @@ async function getAppwriteClient() {
         account: appwriteAccount,
         teams: appwriteTeams,
         users: appwriteUsers, // Add users service for fetching user details
+        functions: window.Appwrite?.Functions ? new window.Appwrite.Functions(appwriteClient) : null, // For guest-migration function calls
         realtime: window.Appwrite?.Realtime ? new window.Appwrite.Realtime(appwriteClient) : null // Realtime service for subscriptions
     };
 }
@@ -223,6 +244,8 @@ function initializeAuthStore() {
                     store.session = state.session;
                     store.magicLinkSent = state.magicLinkSent || false;
                     store.magicLinkExpired = state.magicLinkExpired || false;
+                    store.otpSent = state.otpSent || false;
+                    store.otpExpired = state.otpExpired || false;
                     store.error = state.error;
                 }
             } catch (error) {
@@ -241,6 +264,8 @@ function initializeAuthStore() {
                 session: sanitizeSessionForStorage(store.session),
                 magicLinkSent: store.magicLinkSent,
                 magicLinkExpired: store.magicLinkExpired,
+                otpSent: store.otpSent,
+                otpExpired: store.otpExpired,
                 error: store.error
             };
             localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
@@ -258,6 +283,10 @@ function initializeAuthStore() {
         error: null,
         magicLinkSent: false,
         magicLinkExpired: false,
+        otpSent: false, // Email OTP: a code has been emailed and is awaiting entry
+        otpExpired: false, // Email OTP: the entered code was wrong/expired
+        otpPhrase: null, // Email OTP: security phrase to display (when enabled)
+        _otpUserId: null, // Email OTP: userId returned by createEmailToken, used by verifyOTP
         teams: [], // List of user's teams
         currentTeam: null, // Currently selected/active team
         _teamsPollInterval: null, // Interval ID for teams polling (deprecated, use realtime instead)
@@ -390,15 +419,20 @@ function initializeAuthStore() {
             return null;
         },
 
-        // Get authentication method (oauth, magic, anonymous)
+        // Get authentication method (anonymous, magic, otp, phone, oauth)
         getMethod() {
             if (!this.session) return null;
-            const provider = this.session.provider;
-            if (provider === 'anonymous') return 'anonymous';
-            if (provider === 'magic-url') return 'magic';
-            // OAuth providers return their name (google, github, etc.)
-            if (provider && provider !== 'anonymous' && provider !== 'magic-url') return 'oauth';
-            return null;
+            // Appwrite session.provider: anonymous | magic-url | email (OTP) |
+            // token (OTP, some versions) | phone | oauth2 (or a specific provider).
+            switch (this.session.provider) {
+                case 'anonymous': return 'anonymous';
+                case 'magic-url': return 'magic';
+                case 'email':     return 'otp';   // this plugin uses email tokens for OTP
+                case 'token':     return 'otp';
+                case 'phone':     return 'phone';
+                case 'oauth2':    return 'oauth';
+                default:          return this.session.provider ? 'oauth' : null;
+            }
         },
 
         // Get OAuth provider name (google, github, etc.) or null for non-OAuth methods
@@ -411,8 +445,10 @@ function initializeAuthStore() {
             const sessionProvider = this.session.provider;
 
             // For OAuth, return the stored provider name (google, github, etc.)
-            // session.provider returns "oauth2" generically, so we use _oauthProvider
-            if (sessionProvider && sessionProvider !== 'anonymous' && sessionProvider !== 'magic-url') {
+            // session.provider returns "oauth2" generically, so we use _oauthProvider.
+            // Only OAuth sessions have a provider name — magic/otp/phone/anonymous don't,
+            // so gate on getMethod() to avoid a pointless identities lookup for those.
+            if (this.getMethod() === 'oauth') {
                 // Try to get from store first, then localStorage, then sessionStorage
                 let provider = this._oauthProvider;
                 if (!provider) {
@@ -548,16 +584,17 @@ function initializeAuthStore() {
                         this.isAnonymous = false;
                     }
 
-                    // Load teams if enabled and user is authenticated
-                    if (this.isAuthenticated && appwriteConfig?.teams && this.listTeams) {
+                    // Load teams if enabled and user is authenticated. Guests (anonymous)
+                    // only seed default teams when auth.teams.guests is enabled.
+                    // Note: do NOT gate on this.listTeams here — _loadTeamsAndSeed waits
+                    // for the teams module to attach (it can lose the startup race to init).
+                    if (this.isAuthenticated && appwriteConfig?.teams
+                        && (!this.isAnonymous || appwriteConfig.guestTeams)) {
                         try {
-                            await this.listTeams();
-                            // Auto-create default teams if enabled
-                            if ((appwriteConfig.permanentTeams || appwriteConfig.templateTeams) && window.ManifestAppwriteAuthTeamsDefaults?.ensureDefaultTeams) {
-                                await window.ManifestAppwriteAuthTeamsDefaults.ensureDefaultTeams(this);
-                            }
+                            await this._loadTeamsAndSeed(appwriteConfig);
                         } catch (teamsError) {
-                            // Don't fail initialization if teams fail to load
+                            // Don't fail initialization if teams fail to load, but surface why
+                            console.warn('[Manifest Appwrite Auth] Failed to load/seed teams on restore:', teamsError);
                         }
                     }
                 } catch (error) {
@@ -589,6 +626,72 @@ function initializeAuthStore() {
             }
         },
 
+        // Clear all team-related state. Used when the active identity changes to a
+        // DIFFERENT user — e.g. a guest replaced by a fresh account on OTP sign-in
+        // (Appwrite can't convert anonymous → OTP). Without this, the previous user's
+        // currentTeam/teams leak into the new session and listTeams queries teams the
+        // new user can't access, producing 404s on prefs/memberships.
+        _resetTeamsState() {
+            this.teams = [];
+            this.currentTeam = null;
+            this.currentTeamMemberships = [];
+            this.deletedTemplateTeams = [];
+            this.deletedTemplateRoles = [];
+            this._teamImmutableCache = {};
+            if (this.stopTeamsRealtime) {
+                try { this.stopTeamsRealtime(); } catch (e) { /* ignore */ }
+            }
+        },
+
+        // Call the deployed guest-migration function (templates/guest-migration-function).
+        // The current Appwrite session authenticates the call — Appwrite forwards the
+        // user id to the function. Returns the parsed JSON response, or null on any
+        // failure (migration is best-effort: a failure must never block sign-in).
+        async _callGuestMigration(path, body) {
+            const appwriteConfig = await config.getAppwriteConfig();
+            const fnId = appwriteConfig?.guestMigrationFunctionId;
+            if (!fnId || !this._appwrite?.functions) {
+                return null;
+            }
+            try {
+                const exec = await this._appwrite.functions.createExecution(
+                    fnId, JSON.stringify(body || {}), false, path, 'POST'
+                );
+                const raw = exec?.responseBody ?? exec?.response ?? '';
+                try { return JSON.parse(raw); } catch (e) { return null; }
+            } catch (e) {
+                console.warn(`[Manifest Appwrite Auth] Guest migration ${path} failed:`, e.message);
+                return null;
+            }
+        },
+
+        // Load the user's teams and seed any configured default (permanent/template)
+        // teams. Shared by the guest, magic-link, OAuth, and init/restore paths.
+        async _loadTeamsAndSeed(appwriteConfig) {
+            const cfg = appwriteConfig || await config.getAppwriteConfig();
+            if (!cfg?.teams) {
+                return;
+            }
+            // Startup race: init() (and an early requestGuest) can reach here before
+            // teams.core.js / teams.defaults.js have finished wiring listTeams +
+            // ensureDefaultTeams onto the store. Wait briefly for them rather than
+            // silently skipping (which left guests with no teams on reload).
+            const needsSeed = !!(cfg.permanentTeams || cfg.templateTeams);
+            const ready = () => typeof this.listTeams === 'function'
+                && (!needsSeed || typeof window.ManifestAppwriteAuthTeamsDefaults?.ensureDefaultTeams === 'function');
+            for (let i = 0; i < 40 && !ready(); i++) {
+                await new Promise(r => setTimeout(r, 50));
+            }
+            if (typeof this.listTeams !== 'function') {
+                console.warn('[Manifest Appwrite Auth] Teams module never became ready; skipping team load/seed.');
+                return;
+            }
+            await this.listTeams();
+            if (needsSeed && window.ManifestAppwriteAuthTeamsDefaults?.ensureDefaultTeams) {
+                await window.ManifestAppwriteAuthTeamsDefaults.ensureDefaultTeams(this);
+            }
+        },
+
         // Manually create guest session (only works if guest-manual is enabled)
         async createGuest() {
             if (!this._guestManual) {
@@ -632,9 +735,16 @@ function initializeAuthStore() {
                     // Ignore
                 }
 
-                // Clear teams for guest sessions (guests don't have teams)
-                this.teams = [];
-                this.currentTeam = null;
+                // Guests are full Appwrite sessions, so they can own teams. When
+                // auth.teams.guests is enabled, seed their default teams just like a
+                // signed-in user; otherwise keep the historical behavior (no teams).
+                const cfg = await config.getAppwriteConfig();
+                if (cfg?.guestTeams) {
+                    await this._loadTeamsAndSeed(cfg);
+                } else {
+                    this.teams = [];
+                    this.currentTeam = null;
+                }
 
                 syncStateToStorage(this);
                 window.dispatchEvent(new CustomEvent('manifest:auth:anonymous', {
@@ -698,6 +808,12 @@ function initializeAuthStore() {
                 this.magicLinkSent = false;
                 this.magicLinkExpired = false;
 
+                // Clear email OTP flags
+                this.otpSent = false;
+                this.otpExpired = false;
+                this.otpPhrase = null;
+                this._otpUserId = null;
+
                 // Stop teams realtime subscription if active
                 if (this.stopTeamsRealtime) {
                     this.stopTeamsRealtime();
@@ -2601,9 +2717,11 @@ async function ensureDefaultTeams(store) {
 
                 if (result.success) {
                     createdTeams.push(result.team);
+                } else {
+                    console.warn(`[Manifest Appwrite Auth] Could not seed permanent team "${teamName}":`, result.error);
                 }
             } catch (error) {
-                // Error creating permanent team
+                console.warn(`[Manifest Appwrite Auth] Error seeding permanent team "${teamName}":`, error);
             }
         }
     }
@@ -2643,9 +2761,11 @@ async function ensureDefaultTeams(store) {
 
                 if (result.success) {
                     createdTeams.push(result.team);
+                } else {
+                    console.warn(`[Manifest Appwrite Auth] Could not seed template team "${teamName}":`, result.error);
                 }
             } catch (error) {
-                // Error creating template team
+                console.warn(`[Manifest Appwrite Auth] Error seeding template team "${teamName}":`, error);
             }
         }
     }
@@ -4031,6 +4151,11 @@ window.ManifestAppwriteAuthTeamsUserRoles = {
 
 /* Auth teams - Membership operations */
 
+// The Users service is server-only (node-appwrite); it is never present on the
+// browser SDK, so member-email enrichment degrades gracefully. Warn once rather
+// than on every membership lookup to avoid flooding the console.
+let _usersServiceWarned = false;
+
 // Add membership methods to auth store
 function initializeTeamsMembers() {
     if (typeof Alpine === 'undefined') {
@@ -4176,7 +4301,10 @@ function initializeTeamsMembers() {
                                     try {
                                         // Check if users service is available
                                         if (!this._appwrite || !this._appwrite.users || typeof this._appwrite.users.get !== 'function') {
-                                            console.warn('[Manifest Appwrite Auth] Users service not available on Appwrite client');
+                                            if (!_usersServiceWarned) {
+                                                _usersServiceWarned = true;
+                                                console.warn('[Manifest Appwrite Auth] Users service unavailable on the browser SDK — member emails will not be enriched. (This is expected; logged once.)');
+                                            }
                                         } else {
                                             const user = await this._appwrite.users.get({ userId: membership.userId });
                                             if (user && user.email) {
@@ -4211,7 +4339,10 @@ function initializeTeamsMembers() {
                                             try {
                                                 // Check if users service is available
                                                 if (!this._appwrite || !this._appwrite.users || typeof this._appwrite.users.get !== 'function') {
-                                                    console.warn('[Manifest Appwrite Auth] Users service not available for pending invite lookup');
+                                                    if (!_usersServiceWarned) {
+                                                        _usersServiceWarned = true;
+                                                        console.warn('[Manifest Appwrite Auth] Users service unavailable on the browser SDK — member emails will not be enriched. (This is expected; logged once.)');
+                                                    }
                                                 } else {
                                                     const user = await this._appwrite.users.get({ userId: membership.userId });
                                                     if (user && user.email) {
@@ -5503,6 +5634,17 @@ function initializeAnonymous() {
                     this.isAuthenticated = true;
                     this.isAnonymous = true;
 
+                    // Seed default teams for the guest when auth.teams.guests is enabled
+                    const appwriteConfig = await config.getAppwriteConfig();
+                    if (appwriteConfig?.guestTeams && this._loadTeamsAndSeed) {
+                        try {
+                            await this._loadTeamsAndSeed(appwriteConfig);
+                        } catch (teamsError) {
+                            // Don't fail guest creation if teams fail to load, but surface why
+                            console.warn('[Manifest Appwrite Auth] Failed to seed guest teams:', teamsError);
+                        }
+                    }
+
                     // Sync state to localStorage for cross-tab synchronization
                     if (this._syncStateToStorage) {
                         this._syncStateToStorage(this);
@@ -5601,9 +5743,17 @@ function initializeMagicLinks() {
 
                     const account = this._appwrite.account;
 
+                    // Guest upgrade: when enabled and we're currently a guest, pass the
+                    // anonymous user's own id so Appwrite links the email to that same
+                    // account (preserving its teams) rather than minting a fresh user.
+                    // Otherwise generate a unique id for a brand-new account.
+                    const magicUserId = (appwriteConfig?.guestUpgrade && this.isAnonymous && this.user?.$id)
+                        ? this.user.$id
+                        : ((window.Appwrite?.ID?.unique) ? window.Appwrite.ID.unique() : 'unique()');
+
                     // Try createMagicURLSession first (standard method)
                     if (typeof account.createMagicURLSession === 'function') {
-                        const token = await account.createMagicURLSession('unique()', email, cleanRedirectUrl);
+                        const token = await account.createMagicURLSession(magicUserId, email, cleanRedirectUrl);
                         this.magicLinkSent = true;
                         this.magicLinkExpired = false;
                         this.error = null;
@@ -5615,7 +5765,7 @@ function initializeMagicLinks() {
 
                     // Fallback: try createMagicURLToken (alternative method name)
                     if (typeof account.createMagicURLToken === 'function') {
-                        const token = await account.createMagicURLToken('unique()', email, redirectUrl);
+                        const token = await account.createMagicURLToken(magicUserId, email, redirectUrl);
                         this.magicLinkSent = true;
                         this.magicLinkExpired = false;
                         this.error = null;
@@ -5758,8 +5908,18 @@ function initializeMagicLinks() {
                 this.magicLinkSent = false;
 
                 try {
-                    // Delete any existing anonymous sessions first
-                    if (this.session && this.isAnonymous) {
+                    const appwriteConfig = await config.getAppwriteConfig();
+                    const upgradingGuest = !!(appwriteConfig?.guestUpgrade && this.isAnonymous);
+                    // A guest being replaced (not upgraded) by a different account — its
+                    // team state must be cleared before loading the new user's teams.
+                    const replacingGuest = this.isAnonymous && !upgradingGuest;
+
+                    // Delete the existing anonymous session first — UNLESS we're upgrading
+                    // the guest in place. For an upgrade the magic token was created against
+                    // the anonymous user's own id, so createSession converts that same
+                    // account (keeping its teams); deleting it first would orphan the teams
+                    // and force a brand-new user.
+                    if (this.session && this.isAnonymous && !upgradingGuest) {
                         try {
                             await this._appwrite.account.deleteSession(this.session.$id);
                         } catch (deleteError) {
@@ -5767,8 +5927,20 @@ function initializeMagicLinks() {
                         }
                     }
 
-                    // Create session from magic link credentials
-                    const session = await this._appwrite.account.createSession(userId, secret);
+                    // Create session from magic link credentials. When upgrading a guest the
+                    // anonymous session may still be active; Appwrite can reject the duplicate
+                    // with a "prohibited" error, in which case the account is already upgraded
+                    // and we just reuse the current session.
+                    let session;
+                    try {
+                        session = await this._appwrite.account.createSession(userId, secret);
+                    } catch (createError) {
+                        if (upgradingGuest && createError.message?.includes('prohibited')) {
+                            session = await this._appwrite.account.getSession('current');
+                        } else {
+                            throw createError;
+                        }
+                    }
                     this.session = session;
                     this.user = await this._appwrite.account.get();
                     this.isAuthenticated = true;
@@ -5784,20 +5956,21 @@ function initializeMagicLinks() {
                         // Ignore
                     }
 
+                    // Replacing a guest with a different account: drop the guest's stale
+                    // team state so listTeams doesn't query teams the new user can't access.
+                    if (replacingGuest && this._resetTeamsState) {
+                        this._resetTeamsState();
+                    }
+
                     // Sync state
                     if (this._syncStateToStorage) {
                         this._syncStateToStorage(this);
                     }
 
-                    // Load teams if enabled
-                    const appwriteConfig = await config.getAppwriteConfig();
+                    // Load teams if enabled (and seed any configured default teams)
                     if (appwriteConfig?.teams && this.listTeams) {
                         try {
-                            await this.listTeams();
-                            // Auto-create default teams if enabled
-                            if ((appwriteConfig.permanentTeams || appwriteConfig.templateTeams) && window.ManifestAppwriteAuthTeamsDefaults?.ensureDefaultTeams) {
-                                await window.ManifestAppwriteAuthTeamsDefaults.ensureDefaultTeams(this);
-                            }
+                            await this._loadTeamsAndSeed(appwriteConfig);
                         } catch (teamsError) {
                             console.warn('[Manifest Appwrite Auth] Failed to load teams after magic link login:', teamsError);
                             // Don't fail login if teams fail to load
@@ -5981,6 +6154,334 @@ window.ManifestAppwriteAuthMagicLinks = {
     handleCallbacks: handleMagicLinkCallbacks
 };
 
+/* Auth email OTP (one-time passcode) */
+
+// Email OTP is a two-step, in-page flow (no redirect, unlike magic links):
+//   1. createEmailOTP(email)  -> Appwrite emails a 6-digit code, returns a userId
+//   2. verifyOTP(code)        -> createSession(userId, code) completes login
+// Because there is no URL round-trip, this module never touches users.callbacks.js.
+//
+// NOTE: Appwrite does NOT support converting an anonymous (guest) session via email
+// OTP — only magic links, phone, email/password, and OAuth can do that. So when a
+// guest verifies an OTP we mint a fresh account (the anonymous session is deleted),
+// which discards any guest-created teams. Use magic links if you need guest upgrade.
+
+function initializeEmailOTP() {
+    if (typeof Alpine === 'undefined') {
+        return;
+    }
+
+    const config = window.ManifestAppwriteAuthConfig;
+    if (!config) {
+        return;
+    }
+
+    // Resolve an email string from the same range of inputs sendMagicLink accepts:
+    // an input element, a selector, an Alpine { email } object, a bare string, or
+    // nothing (auto-find the nearest email input). Returns { email, inputEl, dataObj }.
+    function resolveEmailInput(emailInputOrRef) {
+        let email = null;
+        let inputEl = null;
+        let dataObj = null;
+
+        if (emailInputOrRef === undefined || emailInputOrRef === null) {
+            let eventTarget = (typeof window !== 'undefined' && window.event) ? window.event.target : null;
+            if (eventTarget) {
+                const form = eventTarget.closest('form');
+                const scope = form || eventTarget.parentElement;
+                if (scope) {
+                    inputEl = scope.querySelector('input[type="email"]');
+                    if (inputEl) email = inputEl.value;
+                }
+            }
+            if (!inputEl) {
+                inputEl = document.querySelector('input[type="email"]');
+                if (inputEl) email = inputEl.value;
+            }
+        } else if (typeof emailInputOrRef === 'string') {
+            try {
+                const element = document.querySelector(emailInputOrRef);
+                if (element && element.tagName === 'INPUT' && element.type === 'email') {
+                    inputEl = element;
+                    email = element.value;
+                } else {
+                    email = emailInputOrRef; // Treat as a direct email string
+                }
+            } catch (e) {
+                email = emailInputOrRef; // Invalid selector -> treat as email string
+            }
+        } else if (emailInputOrRef && typeof emailInputOrRef === 'object') {
+            if (emailInputOrRef.tagName === 'INPUT' || emailInputOrRef.matches?.('input[type="email"]')) {
+                inputEl = emailInputOrRef;
+                email = inputEl.value;
+            } else if ('email' in emailInputOrRef) {
+                email = emailInputOrRef.email;
+                dataObj = emailInputOrRef;
+            }
+        }
+
+        return { email, inputEl, dataObj };
+    }
+
+    const waitForStore = () => {
+        const store = Alpine.store('auth');
+        if (store && !store.createEmailOTP) {
+            // Step 1: request a one-time passcode by email.
+            // Pass { phrase: true } to enable Appwrite's security phrase (anti-phishing);
+            // when enabled the phrase is stored on the store as `otpPhrase` for display.
+            store.createEmailOTP = async function (email, options = {}) {
+                if (!this._appwrite) {
+                    this._appwrite = await config.getAppwriteClient();
+                }
+                if (!this._appwrite) {
+                    return { success: false, error: 'Appwrite not configured' };
+                }
+
+                // Don't allow OTP request if already signed in (non-anonymous)
+                if (this.isAuthenticated && !this.isAnonymous) {
+                    return { success: false, error: 'Already signed in. Please logout first.' };
+                }
+
+                const appwriteConfig = await config.getAppwriteConfig();
+                if (appwriteConfig && !appwriteConfig.otp) {
+                    return { success: false, error: 'Email OTP authentication is not enabled' };
+                }
+
+                // Appwrite can't convert an anonymous account via OTP. Warn (once) so guest
+                // teams aren't silently lost; the login still proceeds as a fresh account.
+                if (this.isAnonymous && appwriteConfig?.guestUpgrade) {
+                    console.warn('[Manifest Appwrite Auth] Email OTP cannot upgrade a guest account (Appwrite limitation); the guest session and any guest-created teams will be replaced. Use magic links for guest upgrade.');
+                }
+
+                const account = this._appwrite.account;
+                if (typeof account.createEmailToken !== 'function') {
+                    return {
+                        success: false,
+                        error: 'Email OTP method not available. Please ensure you are using a recent Appwrite SDK.'
+                    };
+                }
+
+                this.inProgress = true;
+                this.error = null;
+                this.otpExpired = false;
+
+                try {
+                    const uniqueId = (window.Appwrite?.ID?.unique) ? window.Appwrite.ID.unique() : 'unique()';
+                    // Third arg toggles Appwrite's security phrase feature.
+                    const token = await account.createEmailToken(uniqueId, email, options.phrase === true);
+
+                    // Stash the userId Appwrite assigned; verifyOTP needs it to complete login.
+                    this._otpUserId = token.userId;
+                    this.otpPhrase = token.phrase || null;
+                    this.otpSent = true;
+                    this.otpExpired = false;
+                    this.error = null;
+
+                    window.dispatchEvent(new CustomEvent('manifest:auth:otp-sent', {
+                        detail: { email, phrase: this.otpPhrase }
+                    }));
+
+                    return { success: true, message: 'OTP sent to email', phrase: this.otpPhrase };
+                } catch (error) {
+                    // Appwrite returns 501 Not Implemented when Email OTP isn't enabled
+                    // for the project. Surface an actionable message instead of the raw error.
+                    const code = error.code || error.statusCode;
+                    const notEnabled = code === 501 || /not implemented/i.test(error.message || '');
+                    this.error = notEnabled
+                        ? 'Email OTP is not enabled for this Appwrite project. Enable it under Auth → Settings.'
+                        : error.message;
+                    this.otpSent = false;
+                    this.otpExpired = false;
+                    return { success: false, error: this.error };
+                } finally {
+                    this.inProgress = false;
+                }
+            };
+
+            // Convenience: resolve the email from an input/selector/object/string and send.
+            // Clears the email input on success (mirrors sendMagicLink).
+            store.sendEmailOTP = async function (emailInputOrRef, options = {}) {
+                const { email, inputEl, dataObj } = resolveEmailInput(emailInputOrRef);
+
+                if (!email || !email.trim()) {
+                    return { success: false, error: 'Email is required' };
+                }
+
+                const result = await this.createEmailOTP(email.trim(), options);
+
+                if (result.success) {
+                    Promise.resolve().then(() => {
+                        if (inputEl) {
+                            inputEl.value = '';
+                            inputEl.dispatchEvent(new Event('input', { bubbles: true }));
+                        } else if (dataObj) {
+                            dataObj.email = '';
+                        }
+                    });
+                }
+
+                return result;
+            };
+
+            // Step 2: verify the code and create the session.
+            store.verifyOTP = async function (code) {
+                if (!this._appwrite) {
+                    this._appwrite = await config.getAppwriteClient();
+                }
+                if (!this._appwrite) {
+                    return { success: false, error: 'Appwrite not configured' };
+                }
+                if (!this._otpUserId) {
+                    return { success: false, error: 'Request a code first' };
+                }
+                if (!code || !String(code).trim()) {
+                    return { success: false, error: 'Code is required' };
+                }
+
+                this.inProgress = true;
+                this.error = null;
+
+                try {
+                    const appwriteConfig = await config.getAppwriteConfig();
+                    const wasGuest = this.isAnonymous;
+
+                    // Guest team carryover: OTP can't convert the anonymous account, so we
+                    // migrate its teams to the new account instead. Issue the migration
+                    // ticket NOW, while the guest session is still authenticated — it's
+                    // redeemed after the new session exists. Best-effort; never blocks login.
+                    let migrationTicket = null;
+                    if (wasGuest && appwriteConfig?.guestMigrationFunctionId && this._callGuestMigration) {
+                        const prep = await this._callGuestMigration('/prepare', {});
+                        if (prep?.ok && prep.ticket) migrationTicket = prep.ticket;
+                    }
+
+                    // Appwrite can't convert anonymous accounts via OTP, so delete the
+                    // guest session first to avoid a "session prohibited" conflict.
+                    if (this.session && this.isAnonymous) {
+                        try {
+                            await this._appwrite.account.deleteSession(this.session.$id);
+                        } catch (deleteError) {
+                            // Could not delete anonymous session
+                        }
+                    }
+
+                    const session = await this._appwrite.account.createSession(this._otpUserId, String(code).trim());
+                    this.session = session;
+                    this.user = await this._appwrite.account.get();
+                    this.isAuthenticated = true;
+                    this.isAnonymous = false;
+                    this.otpSent = false;
+                    this.otpExpired = false;
+                    this.otpPhrase = null;
+                    this._otpUserId = null;
+                    this.error = null;
+
+                    // OTP replaces any prior guest with a different account (no conversion),
+                    // so clear the guest's team state before loading the new user's teams —
+                    // otherwise the stale currentTeam triggers 404s in listTeams.
+                    if (this._resetTeamsState) {
+                        this._resetTeamsState();
+                    }
+
+                    // Redeem the migration ticket as the new account: carries the guest's
+                    // teams over. Best-effort — a failure leaves the guest's teams for GC
+                    // but never blocks the (already successful) sign-in.
+                    if (migrationTicket && this._callGuestMigration) {
+                        await this._callGuestMigration('/commit', { ticket: migrationTicket });
+                    }
+
+                    if (this._syncStateToStorage) {
+                        this._syncStateToStorage(this);
+                    }
+
+                    // Load teams + seed any configured default teams for the new account
+                    if (appwriteConfig?.teams && this.listTeams) {
+                        try {
+                            await this._loadTeamsAndSeed(appwriteConfig);
+                        } catch (teamsError) {
+                            console.warn('[Manifest Appwrite Auth] Failed to load teams after OTP login:', teamsError);
+                        }
+                    }
+
+                    window.dispatchEvent(new CustomEvent('manifest:auth:login', {
+                        detail: { user: this.user }
+                    }));
+
+                    return { success: true, user: this.user };
+                } catch (error) {
+                    const errorMessage = error.message || '';
+                    const errorCode = error.code || error.statusCode || '';
+                    const isExpiredOrInvalid = errorMessage && (
+                        errorMessage.includes('expired') ||
+                        errorMessage.includes('Invalid token') ||
+                        errorMessage.includes('invalid') ||
+                        errorMessage.includes('not found') ||
+                        errorCode === 401 || errorCode === 404
+                    );
+
+                    this.otpExpired = !!isExpiredOrInvalid;
+                    this.error = isExpiredOrInvalid ? null : error.message;
+                    this.isAuthenticated = false;
+                    this.isAnonymous = false;
+
+                    if (this._syncStateToStorage) {
+                        this._syncStateToStorage(this);
+                    }
+
+                    return { success: false, error: error.message };
+                } finally {
+                    this.inProgress = false;
+                }
+            };
+
+            // Convenience: resolve the code from an input/selector/object/string and verify.
+            store.submitOTP = async function (codeInputOrRef) {
+                let code = null;
+                if (codeInputOrRef === undefined || codeInputOrRef === null) {
+                    const el = document.querySelector('input[name="otp"], input[autocomplete="one-time-code"], input[inputmode="numeric"]');
+                    if (el) code = el.value;
+                } else if (typeof codeInputOrRef === 'string') {
+                    try {
+                        const el = document.querySelector(codeInputOrRef);
+                        code = (el && el.tagName === 'INPUT') ? el.value : codeInputOrRef;
+                    } catch (e) {
+                        code = codeInputOrRef;
+                    }
+                } else if (codeInputOrRef && typeof codeInputOrRef === 'object') {
+                    if (codeInputOrRef.tagName === 'INPUT') {
+                        code = codeInputOrRef.value;
+                    } else if ('code' in codeInputOrRef) {
+                        code = codeInputOrRef.code;
+                    } else if ('otp' in codeInputOrRef) {
+                        code = codeInputOrRef.otp;
+                    }
+                }
+
+                return await this.verifyOTP(code);
+            };
+        } else if (!store) {
+            setTimeout(waitForStore, 50);
+        }
+    };
+
+    setTimeout(waitForStore, 100);
+}
+
+// Initialize when Alpine is ready
+document.addEventListener('alpine:init', () => {
+    try {
+        initializeEmailOTP();
+    } catch (error) {
+        // Failed to initialize email OTP
+    }
+});
+
+// Export email OTP interface
+window.ManifestAppwriteAuthEmailOTP = {
+    initialize: initializeEmailOTP
+};
+
+
 /* Auth OAuth */
 
 // Add OAuth methods to auth store
@@ -6022,8 +6523,10 @@ function initializeOAuth() {
 
                 // Delete any existing anonymous sessions before OAuth
                 // This prevents conflicts where anonymous sessions might interfere with OAuth
-                // Appwrite will create a new account for OAuth if needed
-                if (this.isAnonymous && this.session) {
+                // Appwrite will create a new account for OAuth if needed.
+                // EXCEPTION: when guest upgrade is enabled we keep the anonymous session
+                // active so Appwrite can link the OAuth identity to it (preserving teams).
+                if (this.isAnonymous && this.session && !appwriteConfig?.guestUpgrade) {
                     try {
                         await this._appwrite.account.deleteSession(this.session.$id);
                         this.session = null;
@@ -6175,8 +6678,16 @@ function handleOAuthCallbacks() {
         store.magicLinkSent = false;
 
         try {
-            // Delete any existing anonymous sessions first
-            if (store.session && store.isAnonymous) {
+            const appwriteConfig = await window.ManifestAppwriteAuthConfig.getAppwriteConfig();
+            const upgradingGuest = !!(appwriteConfig?.guestUpgrade && store.isAnonymous);
+            // A guest being replaced (not upgraded) by a different account — its team
+            // state must be cleared before loading the new user's teams.
+            const replacingGuest = store.isAnonymous && !upgradingGuest;
+
+            // Delete the existing anonymous session first — UNLESS we're upgrading the
+            // guest in place, in which case Appwrite linked the OAuth identity to that
+            // account and the "prohibited" branch below reuses the upgraded session.
+            if (store.session && store.isAnonymous && !upgradingGuest) {
                 try {
                     await store._appwrite.account.deleteSession(store.session.$id);
                 } catch (deleteError) {
@@ -6223,20 +6734,21 @@ function handleOAuthCallbacks() {
                 }
             }
 
+            // Replacing a guest with a different account: drop the guest's stale team
+            // state so listTeams doesn't query teams the new user can't access.
+            if (replacingGuest && store._resetTeamsState) {
+                store._resetTeamsState();
+            }
+
             // Sync state
             if (store._syncStateToStorage) {
                 store._syncStateToStorage(store);
             }
 
-            // Load teams if enabled
-            const appwriteConfig = await window.ManifestAppwriteAuthConfig.getAppwriteConfig();
+            // Load teams if enabled (and seed any configured default teams)
             if (appwriteConfig?.teams && store.listTeams) {
                 try {
-                    await store.listTeams();
-                    // Auto-create default teams if enabled
-                    if ((appwriteConfig.permanentTeams || appwriteConfig.templateTeams) && window.ManifestAppwriteAuthTeamsDefaults?.ensureDefaultTeams) {
-                        await window.ManifestAppwriteAuthTeamsDefaults.ensureDefaultTeams(store);
-                    }
+                    await store._loadTeamsAndSeed(appwriteConfig);
                 } catch (teamsError) {
                     console.warn('[Manifest Appwrite Auth] Failed to load teams after OAuth login:', teamsError);
                     // Don't fail login if teams fail to load