mnfst 0.5.162 → 0.5.164

package/lib/manifest.appwrite.auth.js

@@ -1,19 +1,9 @@
-/*  Manifest Appwrite Auth
+/*  Manifest Appwrite Auth — config resolution
 /*  By Andrew Matlock under MIT license
-/*  https://github.com/andrewmatlock/Manifest
-/*
-/*  Supports authentication with an Appwrite project
-/*  Requires Alpine JS (alpinejs.dev) to operate
 */
 
-/* Auth config */
-
-// Refuse strings that still contain an unresolved ${VAR} reference. The loader
-// runs window.ManifestDataConfig.interpolateManifest at manifest-load time, so
-// by the time we read these fields the env-var substitution has already been
-// applied. Anything still matching ${VAR} is an undefined env var — passing it
-// to Appwrite would either silently fail or, worse, be sent verbatim as an
-// HTTP header value, leaking the env var name. Loud-fail instead.
+// Reject strings still holding an unresolved ${VAR} — an undefined env var that
+// would leak verbatim into an Appwrite HTTP header. Loud-fail instead.
 function resolvedOrNull(value, fieldName) {
     if (typeof value !== 'string') return value;
     if (/\$\{[^}]+\}/.test(value)) {
@@ -23,7 +13,7 @@ function resolvedOrNull(value, fieldName) {
     return value;
 }
 
-// Load manifest if not already loaded (loader may set __manifestLoaded / registry.manifest)
+// Load manifest if not already loaded
 async function ensureManifest() {
     if (window.ManifestComponentsRegistry?.manifest) {
         return window.ManifestComponentsRegistry.manifest;
@@ -35,7 +25,10 @@ async function ensureManifest() {
     try {
         const manifestUrl = (document.querySelector('link[rel="manifest"]')?.getAttribute('href')) || '/manifest.json';
         const response = await fetch(manifestUrl);
-        return await response.json();
+        const manifest = await response.json();
+        // No-loader path: resolve ${VAR} placeholders the dynamic loader would have.
+        window.ManifestDataConfig?.interpolateManifest?.(manifest);
+        return manifest;
     } catch (error) {
         return null;
     }
@@ -51,26 +44,21 @@ async function getAppwriteConfig() {
     const appwriteConfig = manifest.appwrite;
     const endpoint = resolvedOrNull(appwriteConfig.endpoint, 'endpoint');
     const projectId = resolvedOrNull(appwriteConfig.projectId, 'projectId');
-    // Optional dev key to bypass rate limits in development. The schema
-    // documents `${VAR_NAME}` interpolation for this field specifically —
-    // refuse to forward a literal placeholder as an HTTP header.
+    // Optional dev key to bypass rate limits in development.
     const devKey = appwriteConfig.devKey ? resolvedOrNull(appwriteConfig.devKey, 'devKey') : undefined;
 
     if (!endpoint || !projectId) {
         return null;
     }
-    // devKey is optional: if the user supplied one but it failed to resolve,
-    // resolvedOrNull returned null (and logged) — drop the field rather than
-    // initialize Appwrite with a literal `${VAR}` header.
+    // Supplied-but-unresolved devKey: drop the config rather than send a literal ${VAR} header.
     if (appwriteConfig.devKey && devKey === null) {
         return null;
     }
 
-    // Get auth methods from config (defaults to ["magic", "oauth"] if not specified)
+    // Auth methods (defaults to magic + oauth)
     const authMethods = appwriteConfig.auth?.methods || ["magic", "oauth"];
 
-    // 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.)
+    // Guest sessions: "guest"/"guest-auto" = automatic, "guest-manual" = manual only.
     const guestAuto = authMethods.includes("guest") || authMethods.includes("guest-auto");
     const guestManual = authMethods.includes("guest-manual");
     const hasGuest = guestAuto || guestManual;
@@ -79,41 +67,34 @@ async function getAppwriteConfig() {
     const otpEnabled = authMethods.includes("otp");
     const oauthEnabled = authMethods.includes("oauth");
 
-    // Teams support: presence of teams object enables it
+    // Teams (presence of teams object enables it)
     const teamsEnabled = !!appwriteConfig.auth?.teams;
-    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 permanentTeams = appwriteConfig.auth?.teams?.permanent || null; // immutable
+    const templateTeams = appwriteConfig.auth?.teams?.template || null; // deletable + reappliable
+    const teamsPollInterval = appwriteConfig.auth?.teams?.pollInterval || null; // ms, null = disabled
+    const guestTeams = !!appwriteConfig.auth?.teams?.guests; // seed default teams for guests
+
+    // Guest upgrade: preserve the anonymous account + teams on sign-in (magic/oauth;
+    // OTP can't convert anonymous accounts). Defaults to guestTeams.
     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", ...] }
-    const permanentRoles = appwriteConfig.auth?.roles?.permanent || null; // Object: { "RoleName": ["permission1", ...] }
-    const templateRoles = appwriteConfig.auth?.roles?.template || null; // Object: { "RoleName": ["permission1", ...] }
+    // Default roles: { "RoleName": ["permission", ...] }
+    const permanentRoles = appwriteConfig.auth?.roles?.permanent || null; // not deletable
+    const templateRoles = appwriteConfig.auth?.roles?.template || null; // deletable
 
-    // Member roles: derived from permanent and template roles (merged)
-    // This is used for role normalization, permission checking, and creatorRole logic
+    // Member roles: permanent + template merged (fallback to legacy memberRoles)
     const memberRoles = permanentRoles || templateRoles
         ? { ...(permanentRoles || {}), ...(templateRoles || {}) }
-        : (appwriteConfig.auth?.memberRoles || null); // Fallback to legacy memberRoles if roles not defined
+        : (appwriteConfig.auth?.memberRoles || null);
 
-    // Creator role: string reference to a role in memberRoles (role creator gets by default)
+    // Creator role: memberRoles key the creator gets by default (legacy singular)
     const creatorRole = appwriteConfig.auth?.creatorRole || null;
 
-    // Creator roles (plural): the custom role(s) the team creator is assigned, atomically,
-    // at team creation. Accepts string | string[] | null. An explicit null / [] means
-    // "no template role — creator holds only Appwrite's intrinsic owner". Takes precedence
-    // over the legacy singular `creatorRole`. When NEITHER is set, createTeam keeps its
-    // historical default (first defined role). Resolved to: array (configured, [] = owner-only)
-    // or null (unconfigured → use the historical default).
+    // Creator roles (plural): role(s) assigned to the team creator atomically at creation.
+    // string | string[] | null; explicit null/[] = owner-only. Wins over creatorRole.
+    // Resolves to array (configured) or null (use historical default of first role).
     let creatorRoles = null;
     if (appwriteConfig.auth && Object.prototype.hasOwnProperty.call(appwriteConfig.auth, 'creatorRoles')) {
         const raw = appwriteConfig.auth.creatorRoles;
@@ -122,35 +103,34 @@ async function getAppwriteConfig() {
         creatorRoles = [creatorRole];
     }
 
-    // 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.
+    // Guest migration: deployed Appwrite Function id that carries guest teams to
+    // the OTP account (which Appwrite can't convert in place).
     const guestMigrationFunctionId = appwriteConfig.auth?.guestMigration?.functionId || null;
 
     return {
         endpoint,
         projectId,
-        devKey, // Optional dev key for development
+        devKey,
         authMethods,
         guest: hasGuest,
         guestAuto: guestAuto,
         guestManual: guestManual,
-        anonymous: guestAuto, // For backwards compatibility with existing code
+        anonymous: guestAuto, // back-compat alias
         magic: magicEnabled,
-        otp: otpEnabled, // Email one-time-passcode authentication
+        otp: otpEnabled,
         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)
-        creatorRole: creatorRole, // String reference to memberRoles key (legacy singular)
-        creatorRoles: creatorRoles // array (configured; [] = owner-only) or null (use historical default)
+        permanentTeams: permanentTeams,
+        templateTeams: templateTeams,
+        teamsPollInterval: teamsPollInterval,
+        guestTeams: guestTeams,
+        guestUpgrade: guestUpgrade,
+        guestMigrationFunctionId: guestMigrationFunctionId,
+        memberRoles: memberRoles,
+        permanentRoles: permanentRoles,
+        templateRoles: templateRoles,
+        creatorRole: creatorRole,
+        creatorRoles: creatorRoles
     };
 }
 
@@ -161,7 +141,6 @@ let appwriteTeams = null;
 let appwriteUsers = null;
 
 async function getAppwriteClient() {
-    // Check if Appwrite SDK is loaded
     if (!window.Appwrite || !window.Appwrite.Client || !window.Appwrite.Account) {
         return null;
     }
@@ -176,8 +155,7 @@ async function getAppwriteClient() {
             .setEndpoint(config.endpoint)
             .setProject(config.projectId);
 
-        // Add dev key header if provided (bypasses rate limits in development)
-        // See: https://appwrite.io/docs/advanced/platform/rate-limits#dev-keys
+        // Dev key header bypasses rate limits in development.
         if (config.devKey) {
             appwriteClient.headers['X-Appwrite-Dev-Key'] = config.devKey;
         }
@@ -185,7 +163,6 @@ async function getAppwriteClient() {
         appwriteAccount = new window.Appwrite.Account(appwriteClient);
         appwriteTeams = new window.Appwrite.Teams(appwriteClient);
 
-        // Initialize Users service if available (for fetching user details)
         if (window.Appwrite.Users) {
             appwriteUsers = new window.Appwrite.Users(appwriteClient);
         }
@@ -195,9 +172,9 @@ async function getAppwriteClient() {
         client: appwriteClient,
         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
+        users: appwriteUsers,
+        functions: window.Appwrite?.Functions ? new window.Appwrite.Functions(appwriteClient) : null,
+        realtime: window.Appwrite?.Realtime ? new window.Appwrite.Realtime(appwriteClient) : null
     };
 }
 
@@ -224,12 +201,8 @@ function initializeAuthStore() {
     // Cross-tab synchronization using localStorage events
     const STORAGE_KEY = 'manifest:auth:state';
 
-    // Whitelist of Appwrite Session fields safe to mirror across tabs.
-    // CRITICALLY excludes `secret` (the bearer credential), `providerAccessToken`,
-    // `providerRefreshToken`, and `providerAccessTokenExpiry`. The cookie set
-    // on the Appwrite domain is the actual auth of record; this localStorage
-    // copy only supports UI cross-tab sync ("someone just logged in here").
-    // An XSS on this origin must not be able to lift session secrets out.
+    // Session fields safe to mirror across tabs. Excludes `secret` and provider
+    // tokens — this copy is only for UI cross-tab sync, not the auth of record.
     const SAFE_SESSION_FIELDS = [
         '$id', 'userId', 'provider', 'expire', 'current',
         'clientName', 'osName', 'osCode', 'deviceName',
@@ -429,8 +402,7 @@ function initializeAuthStore() {
 
         // Get personal team (convenience getter - returns first default team)
         get personalTeam() {
-            // This is async, so we can't use a getter directly
-            // Return null and let users call getPersonalTeam() or getDefaultTeams() directly
+            // Lookup is async; use getPersonalTeam()/getDefaultTeams() instead
             return null;
         },
 
@@ -450,19 +422,16 @@ function initializeAuthStore() {
             }
         },
 
-        // Get OAuth provider name (google, github, etc.) or null for non-OAuth methods
-        // Uses stored provider from loginOAuth() call, or falls back to session.provider
-        // For existing sessions without stored provider, triggers async fetch from Appwrite identities
+        // OAuth provider name (google, github, …), or null for non-OAuth methods.
+        // Reads stored provider, else falls back to session.provider / identities fetch.
         getProvider() {
             if (!this.session) {
                 return null;
             }
             const sessionProvider = this.session.provider;
 
-            // For OAuth, return the stored provider name (google, github, etc.)
-            // 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.
+            // session.provider is generically "oauth2", so use _oauthProvider. Gate on
+            // getMethod() so non-OAuth sessions skip the pointless identities lookup.
             if (this.getMethod() === 'oauth') {
                 // Try to get from store first, then localStorage, then sessionStorage
                 let provider = this._oauthProvider;
@@ -568,8 +537,7 @@ function initializeAuthStore() {
                         this.isAuthenticated = true;
                         this.isAnonymous = currentSession.provider === 'anonymous';
 
-                        // Restore OAuth provider from localStorage if available (persists across redirects)
-                        // This ensures provider name persists across page refreshes
+                        // Restore OAuth provider from storage (persists across redirects/refresh)
                         if (!this.isAnonymous && currentSession.provider !== 'magic-url') {
                             try {
                                 // Try localStorage first (persists across redirects), fallback to sessionStorage
@@ -602,10 +570,8 @@ function initializeAuthStore() {
                         this.isAnonymous = false;
                     }
 
-                    // NOTE: team loading is intentionally NOT awaited here — it runs in
-                    // the background after manifest:auth:initialized fires (see below),
-                    // so a session gate (app splash) isn't held up by team listing +
-                    // member hydration.
+                    // Team loading is deferred (not awaited) — runs in the background after
+                    // manifest:auth:initialized so a session gate isn't held up by it.
                 } catch (error) {
                     // No existing session - this is expected
                     this.isAuthenticated = false;
@@ -617,11 +583,8 @@ function initializeAuthStore() {
                 // Sync state to localStorage
                 syncStateToStorage(this);
             } catch (error) {
-                // init() is a passive lifecycle step (session restore / setup), not a
-                // user action. Resolve to a clean signed-out state and log — do NOT park
-                // the raw message in $auth.error, which is reserved for sign-in/action
-                // failures the user can act on (a sign-in card binding $auth.error must
-                // never show benign "no session" / "blocked account" scope errors).
+                // Passive lifecycle step: resolve to signed-out and log. Don't set
+                // $auth.error — that's reserved for user-actionable sign-in failures.
                 console.warn('[Manifest Appwrite Auth] Session restore failed (treating as signed out):', error?.message || error);
                 this.isAuthenticated = false;
                 this.isAnonymous = false;
@@ -630,9 +593,8 @@ function initializeAuthStore() {
                 this._initialized = true;
                 this._initializing = false;
 
-                // Dispatch initialized event - let callback handlers process after.
-                // Fires as soon as identity is known (one round-trip), NOT after teams
-                // load — so a session gate / splash clears in a few hundred ms.
+                // Fire as soon as identity is known, before teams load, so a session
+                // gate / splash clears in a few hundred ms.
                 window.dispatchEvent(new CustomEvent('manifest:auth:initialized', {
                     detail: {
                         isAuthenticated: this.isAuthenticated,
@@ -641,9 +603,8 @@ function initializeAuthStore() {
                 }));
             }
 
-            // Background, non-blocking: load + seed teams AFTER initialized fired.
-            // $auth.teams / currentTeam populate reactively when ready; a
-            // manifest:auth:teams-loaded event fires for anything that needs the full set.
+            // Background load + seed teams after init. Populates reactively; fires
+            // manifest:auth:teams-loaded for anything needing the full set.
             if (appwriteConfig && this.isAuthenticated && appwriteConfig.teams
                 && (!this.isAnonymous || appwriteConfig.guestTeams)) {
                 this._loadTeamsAndSeed(appwriteConfig)
@@ -654,11 +615,8 @@ 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.
+        // Clear team state when the identity changes to a different user (e.g. guest
+        // replaced on OTP sign-in). Otherwise stale currentTeam/teams cause 404s.
         _resetTeamsState() {
             this.teams = [];
             this.currentTeam = null;
@@ -671,10 +629,8 @@ function initializeAuthStore() {
             }
         },
 
-        // 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).
+        // Call the deployed guest-migration function; the current session authenticates it.
+        // Returns parsed JSON, or null on failure (best-effort — never blocks sign-in).
         async _callGuestMigration(path, body) {
             const appwriteConfig = await config.getAppwriteConfig();
             const fnId = appwriteConfig?.guestMigrationFunctionId;
@@ -693,17 +649,15 @@ function initializeAuthStore() {
             }
         },
 
-        // Load the user's teams and seed any configured default (permanent/template)
-        // teams. Shared by the guest, magic-link, OAuth, and init/restore paths.
+        // Load the user's teams and seed configured defaults. 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).
+            // Startup race: we can arrive before teams.core/defaults wire listTeams +
+            // ensureDefaultTeams onto the store. Wait briefly rather than skip.
             const needsSeed = !!(cfg.permanentTeams || cfg.templateTeams);
             const ready = () => typeof this.listTeams === 'function'
                 && (!needsSeed || typeof window.ManifestAppwriteAuthTeamsDefaults?.ensureDefaultTeams === 'function');
@@ -763,9 +717,8 @@ function initializeAuthStore() {
                     // Ignore
                 }
 
-                // 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).
+                // Guests are full sessions and can own teams: seed defaults when
+                // guestTeams is enabled, otherwise none.
                 const cfg = await config.getAppwriteConfig();
                 if (cfg?.guestTeams) {
                     await this._loadTeamsAndSeed(cfg);
@@ -856,18 +809,8 @@ function initializeAuthStore() {
                 this.teams = [];
                 this.currentTeam = null;
 
-                // Clear deleted teams tracking for this user (optional - uncomment if you want to clear on logout)
-                // try {
-                //     const userId = this.user?.$id;
-                //     if (userId) {
-                //         localStorage.removeItem(`manifest:deleted-teams:${userId}`);
-                //     }
-                // } catch (e) {
-                //     // Ignore
-                // }
-
-                // Restore to guest state after logout (if guest-auto is enabled)
-                // This only applies to non-guest sessions - if logging out from guest, don't create a new guest
+                // Restore to guest state after logout (guest-auto only, and not when
+                // already a guest — don't mint a new guest on top).
                 if (!this.isAnonymous && this._guestAuto && this._createAnonymousSession) {
                     await this._createAnonymousSession();
                 } else {
@@ -4773,19 +4716,8 @@ function initializeTeamsConvenience() {
     const waitForStore = () => {
         const store = Alpine.store('auth');
         if (store) {
-            // Decide whether to (re)attach convenience methods. Use a sentinel
-            // that ONLY this module defines — `createTeamFromName`. The earlier
-            // sentinel (`isCreatingTeam`) was unreliable: the store itself
-            // defines an `isCreatingTeam()` stub at init (see manifest.appwrite
-            // .auth.store.js — the "Stub team convenience methods" block), so
-            // `typeof store.isCreatingTeam === 'function'` is true BEFORE this
-            // module runs. The check then fired false-positive and skipped the
-            // whole `if (needsReinitialization)` block below, leaving the real
-            // convenience methods (startEditingMember, createTeamFromName,
-            // cancelEditingMember, saveEditingMember, deleteMember, leaveTeam,
-            // toggleInviteRole, etc.) unattached — surfacing as
-            // "$auth.startEditingMember is not a function" the moment a user
-            // clicked an edit-member button.
+            // Sentinel must be a method ONLY this module defines. isCreatingTeam
+            // won't do — the store stubs it at init, so it reads present too early.
             const needsReinitialization = typeof store.createTeamFromName !== 'function';
             
             // Ensure cache properties are initialized (methods are already in store)
@@ -4867,8 +4799,7 @@ function initializeTeamsConvenience() {
                 };
             }
 
-            // CRITICAL: Check if convenience methods exist - use isCreatingTeam as the key check
-            // This ensures methods are re-added if the store was replaced or methods were lost after idle
+            // Re-attach methods if the store was replaced or methods were lost after idle
             if (needsReinitialization) {
                 // Convenience method: create team using newTeamName property
                 store.createTeamFromName = async function () {
@@ -5398,9 +5329,8 @@ function initializeTeamsConvenience() {
                     const allRoles = this.allTeamRoles({ $id: teamId });
                     const permissions = allRoles && allRoles[roleName] ? [...allRoles[roleName]] : [];
 
-                    // Set editing state SYNCHRONOUSLY — before the async dropdown fetch
-                    // below — so a caller that mutates editingRole.permissions immediately
-                    // after this isn't racing (and getting overwritten by) that fetch.
+                    // Set state synchronously, before the async fetch below, so a caller
+                    // mutating editingRole.permissions right after isn't overwritten.
                     this.editingRole = {
                         teamId: teamId,
                         oldRoleName: roleName,
@@ -5419,12 +5349,8 @@ function initializeTeamsConvenience() {
                     // The UI will use editingRole.permissions or pendingPermissions for existing roles
                 };
 
-                // Reactive-safe role-permission write. Takes a plain array and persists
-                // straight to team prefs via updateUserRole — WITHOUT going through the
-                // reactive editingRole object. Use this for programmatic edits; mutating
-                // $auth.editingRole.permissions directly is fragile under Alpine (the
-                // $auth proxy wraps the already-reactive editingRole and can recurse on
-                // get). updateUserRole refreshes the role cache, so allTeamRoles() re-reads.
+                // Reactive-safe write: persist via updateUserRole, bypassing the reactive
+                // editingRole (mutating $auth.editingRole.permissions directly recurses).
                 store.updateRolePermissions = async function (teamId, roleName, permissions) {
                     if (!this.updateUserRole) {
                         return { success: false, error: 'Roles module not ready' };
@@ -5435,9 +5361,8 @@ function initializeTeamsConvenience() {
                     return await this.updateUserRole(teamId, roleName, plain);
                 };
 
-                // Safely set the permissions on the in-progress edit (replaces editingRole
-                // with a fresh object holding a plain array, rather than mutating the
-                // reactive nested array). Pair with saveEditingRole().
+                // Set permissions on the in-progress edit by replacing editingRole with a
+                // fresh object (not mutating the reactive nested array). Pair with saveEditingRole().
                 store.setEditingPermissions = function (permissions) {
                     if (!this.editingRole) {
                         return;
@@ -5541,10 +5466,8 @@ function initializeTeamsConvenience() {
                     return userRoles.includes('owner');
                 };
 
-                // Synchronous version for Alpine.js bindings (x-show / :disabled).
-                // Resolves from the cached role definitions (allTeamRoles) so it matches
-                // the async hasTeamPermission() — including custom permission keys, not
-                // just the six built-ins the permission cache pre-computes.
+                // Sync version for Alpine bindings. Resolves from cached allTeamRoles so it
+                // matches async hasTeamPermission, including custom (non-built-in) keys.
                 store.hasTeamPermissionSync = function (permission) {
                     if (!this.currentTeam || !this.currentTeamMemberships || !this.user) {
                         return false;
@@ -5616,12 +5539,9 @@ function initializeTeamsConvenience() {
                     return userRoles;
                 };
 
-            } // End of if (!store.isCreatingTeam || typeof store.isCreatingTeam !== 'function')
-
-            // Note: hasPermission from roles module takes (userRoles, permission, teamId)
-            // hasTeamPermission is the convenience wrapper for current team
+            } // End needsReinitialization
 
-            // Update cache when team is viewed (wrap existing viewTeam if it exists)
+            // Wrap viewTeam to refresh permission cache after a team is viewed
             if (store.viewTeam && !store._viewTeamWrapped) {
                 const originalViewTeam = store.viewTeam;
                 store.viewTeam = async function (team) {
@@ -6232,15 +6152,10 @@ window.ManifestAppwriteAuthMagicLinks = {
 
 /* 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.
+// Two-step in-page flow (no redirect): createEmailOTP(email) emails a code + returns
+// a userId, verifyOTP(code) creates the session.
+// Gotcha: Appwrite can't convert an anonymous guest via OTP — a guest verifying an OTP
+// gets a fresh account (guest teams lost). Use magic links for guest upgrade.
 
 function initializeEmailOTP() {
     if (typeof Alpine === 'undefined') {
@@ -6252,9 +6167,8 @@ function initializeEmailOTP() {
         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 }.
+    // Resolve an email from an input/selector/{ email } object/string, or auto-find
+    // the nearest email input. Returns { email, inputEl, dataObj }.
     function resolveEmailInput(emailInputOrRef) {
         let email = null;
         let inputEl = null;
@@ -6302,9 +6216,8 @@ function initializeEmailOTP() {
     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.
+            // Step 1: email a passcode. { phrase: true } enables Appwrite's anti-phishing
+            // security phrase, surfaced on the store as `otpPhrase`.
             store.createEmailOTP = async function (email, options = {}) {
                 if (!this._appwrite) {
                     this._appwrite = await config.getAppwriteClient();
@@ -6323,8 +6236,7 @@ function initializeEmailOTP() {
                     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.
+                // OTP can't convert a guest — warn so lost guest teams aren't a surprise.
                 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.');
                 }
@@ -6359,8 +6271,8 @@ function initializeEmailOTP() {
 
                     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.
+                    // Appwrite returns 501 when Email OTP isn't enabled — surface an
+                    // actionable message rather than the raw error.
                     const code = error.code || error.statusCode;
                     const notEnabled = code === 501 || /not implemented/i.test(error.message || '');
                     this.error = notEnabled
@@ -6421,10 +6333,8 @@ function initializeEmailOTP() {
                     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.
+                    // Guest team carryover: issue the migration ticket now, while the guest
+                    // session is still authenticated; redeemed after the new session exists.
                     let migrationTicket = null;
                     if (wasGuest && appwriteConfig?.guestMigrationFunctionId && this._callGuestMigration) {
                         const prep = await this._callGuestMigration('/prepare', {});
@@ -6452,16 +6362,14 @@ function initializeEmailOTP() {
                     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.
+                    // Clear the guest's team state before loading the new user's teams,
+                    // else 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.
+                    // Redeem the migration ticket as the new account to carry teams over.
+                    // Best-effort; failure never blocks the already-successful sign-in.
                     if (migrationTicket && this._callGuestMigration) {
                         await this._callGuestMigration('/commit', { ticket: migrationTicket });
                     }

package/lib/manifest.appwrite.data.js

@@ -1214,9 +1214,7 @@ window.ManifestDataQueries = {
 };
 
 
-/* Manifest Data Sources - Pagination */
-
-// Pagination helper functions for Appwrite data sources
+/* Manifest Data Sources - Pagination (Appwrite) */
 
 /**
  * Get first page of results (cursor-based)