Authentication Strategies

Relevant source files

The following files were used as context for generating this wiki page:

• ARCHITECTURE.md
• AGENTS.md
• mobile/schema.graphql
• mobile/app/(auth)/sign-in.tsx
• assets/js/app.js

Introduction

Authentication in LiveCanvas is managed by the Accounts context, which serves as the central authority for user identity and session lifecycle management. The system is designed as a modular monolith where the authentication layer resolves presented credentials to a normalized identity, which is then mapped to a single user account. This approach allows a single user to link multiple authentication methods, such as email/password, OAuth providers, and passkeys, to a single canonical record.

Sources: ARCHITECTURE.md:129-140, ARCHITECTURE.md:231-236

The scope of the authentication system covers account creation, multi-provider login, and session persistence using hashed tokens. While the current V1 implementation focuses on these core flows, advanced features like two-factor authentication (2FA) and profile customization are explicitly deferred to later phases.

Sources: ARCHITECTURE.md:27-38, ARCHITECTURE.md:286-292

Multi-Provider Support

LiveCanvas supports a wide range of authentication providers. The system distinguishes between the physical identity (email or phone) and the credential used to access it.

Supported Providers

The system implements the following authentication methods:

• Traditional: Email + Password, Phone + Password.
• Passwordless: Email/Phone magic links and one-time codes.
• OAuth: Google and Apple integration.
• Modern: WebAuthn-based passkeys.

Sources: ARCHITECTURE.md:231-236, mobile/schema.graphql:525-533

Authentication Challenge Flow

For modern or passwordless flows, the system uses a challenge-response mechanism. This is initiated via the beginAuthChallenge mutation, which generates a challenge token for the client to sign or verify.

The diagram above illustrates the typical multi-step authentication process for challenge-based providers.
Sources: mobile/schema.graphql:32-34, mobile/schema.graphql:665-671, mobile/schema.graphql:715-725

Token and Session Management

LiveCanvas utilizes a dual-token system (Access and Refresh tokens) for session management. Tokens are managed within the user_tokens table.

Security Implementation

• Hashing: Token secrets are never stored in raw form. The system uses SHA3-based hashing for persisted token secrets.
• Identifiers: user_tokens use pure UUIDv7 identifiers as primary keys.
• Revocation: Tokens can be explicitly revoked, and the system supports tracking the last-used or revoked status.

Sources: AGENTS.md:8-11, ARCHITECTURE.md:195-207, ARCHITECTURE.md:261-263

Token Data Structures

Field	Type	Description
id	UUIDv7	Primary key for the token record.
secret_hash	Binary	SHA3 hash of the token secret.
context	String	Purpose of the token (e.g., session, refresh, reset).
user_id	Bigint	Reference to the canonical user.

Sources: ARCHITECTURE.md:195-207, AGENTS.md:10

User Identity Modeling

The system avoids denormalizing sensitive data like primary emails into the main users table. Instead, it uses a normalized join-table approach.

This ER diagram shows the relationship between users and their various authentication and identity components.
Sources: ARCHITECTURE.md:155-207, AGENTS.md:8-10

API Implementation

GraphQL Mutations

The primary interface for authentication is the GraphQL API, providing specific mutations for various stages of the lifecycle.

Mutation	Input Type	Description
signUp	SignUpInput	Creates a new user and returns initial tokens.
logIn	LogInInput	Validates credentials and issues tokens.
refreshAuthTokens	RefreshAuthTokensInput	Exchanges a refresh token for a new pair.
revokeRefreshToken	RevokeRefreshTokenInput	Invalidates a specific refresh token session.
unlinkViewerIdentity	UnlinkViewerIdentityInput	Removes a specific login method from the account.

Sources: mobile/schema.graphql:32-52

Web and Realtime Auth

• CSRF Protection: For web-based LiveViews, a CSRF token is required and passed via the Socket params.
• Channel Security: Phoenix Channel joins must be authenticated and authorized per topic, validating viewer eligibility and participation roles.

Sources: assets/js/app.js:27-32, ARCHITECTURE.md:255-260

Conclusion

The authentication strategy in LiveCanvas prioritizes modularity and security. By decoupling identities from the core user record and enforcing SHA3 hashing for all token secrets, the architecture ensures that multiple login methods can be safely managed while maintaining a single user profile. The system is designed to scale from simple password logins to complex WebAuthn and OAuth flows through its flexible challenge-response API.

Sources: ARCHITECTURE.md:129-140, ARCHITECTURE.md:231-240, AGENTS.md:10