authentication

Authentication Architecture

Auth Method Selection

Default is email/password + anonymous guest. Only add other methods when the user explicitly asks:

User Says	Auth Methods
(nothing specified)	email/password + anonymous guest
"Apple Sign In" / "Sign in with Apple"	Apple Sign In
"Google Sign In"	Google Sign In (requires GoogleSignIn package)
"social login"	Apple + Google
"guest mode" / "browse without account"	anonymous only

Methods combine — a user can request email + Apple + anonymous together.

Service Architecture

AuthService is @Observable @MainActor — it owns all auth state and lives in Services/Auth/, never inside Features/.

// ViewModels consume AuthService via init injection
@Observable @MainActor
class ProfileViewModel {
    private let authService: AuthService
    init(authService: AuthService) { self.authService = authService }
}

// Views access AuthService through @Environment
@Environment(AuthService.self) private var authService

When the Supabase skill is also loaded, AuthService delegates to SupabaseService.shared.client.auth for all backend calls. Without a backend skill, AuthService uses a placeholder implementation.

Auth Modes

Gate mode (default): AuthGuardView sits at the app root. Users must authenticate before accessing any content.

Optional mode (when user says "auth is optional" or "browse without login"): No root gate. Individual features check authService.isAuthenticated and prompt login when needed.

Key Rules

• Services live in Services/Auth/ — never inside Features/
• ViewModels consume AuthService via init injection, never call auth APIs directly
• Never manage tokens manually — the backend SDK handles token storage and refresh
• Always restore session on app launch
• Always handle sign-out gracefully — clear local state even if the server call fails

References

• Auth Methods — email, guest, Apple, Google patterns with Swift code
• Auth Architecture — AuthService, directory structure, environment injection
• Auth Guard — gate mode vs optional mode patterns
• Session Security — token lifecycle, sign out, account deletion