Accounts & Identity Context

Relevant source files

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

• ARCHITECTURE.md
• AGENTS.md
• mobile/schema.graphql
• README.md
• assets/js/app.js

The Accounts context is a primary domain boundary within the LiveCanvas modular monolith responsible for managing the lifecycle of users, their authentication methods, and their digital identities. It serves as the authoritative source for account state, credential linkage, and session management, ensuring that users can securely access the platform via multiple providers while maintaining a single, unified account presence.

This context is strictly separated from social interactions, content creation, and live session management. Its primary objective is to resolve presented credentials (such as emails, phone numbers, or OAuth subjects) into a normalized identity that maps to a unique User entity.

Sources: ARCHITECTURE.md:126-136, ARCHITECTURE.md:237-245

Core Architecture & Data Model

The architecture follows a normalized approach where user profiles are decoupled from specific login methods. Instead of storing email or phone data directly on the User record, the system uses join tables to link users to unique, normalized identity records.

Entity Relationship Mapping

The following diagram illustrates the relationship between the core account entities:

Primary Components

Component	Responsibility
User	The canonical account row storing privacy modes, moderation flags, and basic timestamps.
User Identity	Represents login-capable credentials including Password, Magic Link, OAuth (Google/Apple), and Passkeys.
Normalized Tables	email_addresses and phone_numbers store unique values globally to prevent duplication.
User Tokens	Manages sessions, refresh tokens, and verification codes using SHA3-based hashing for secrets.

Sources: ARCHITECTURE.md:191-228, AGENTS.md:11-13

Authentication & Identity Flows

Authentication in LiveCanvas is multi-modal. A single user can have multiple identities linked to their account, such as an Apple OAuth identity and a traditional email/password identity.

Authentication Process

The system utilizes a challenge-response pattern for complex providers (like Passkeys) and direct token exchange for standard providers.

Identity Linkage Rules

• One user can have multiple linked identities across different providers.
• Linking must be explicit; the system does not silently attach new credentials to existing users without policy-driven verification.
• Passwords must be stored as strong hashes, and OAuth tokens must be encrypted at rest.

Sources: ARCHITECTURE.md:247-263

GraphQL API Interface

The RootQueryType and RootMutationType provide the primary interface for account management. All refetchable IDs are governed by viewer authorization to prevent Insecure Direct Object Reference (IDOR) vulnerabilities.

Key Account Mutations

Mutation	Description
beginAuthChallenge	Starts a multi-step auth process (e.g., for Passkeys or Magic Links).
signUp / logIn	Primary entry points for account creation and session establishment.
issueViewerAuthTokens	Generates new access and refresh tokens for the current session.
refreshAuthTokens	Rotates expired access tokens using a valid refresh token.
unlinkViewerIdentity	Removes a specific login method from the user's account.

Sources: mobile/schema.graphql:27-55, ARCHITECTURE.md:83-85, AGENTS.md:15-18

Identity Providers

The system supports the following AuthProvider types:

• PASSWORD
• MAGIC_LINK
• GOOGLE
• APPLE
• PASSKEY (WebAuthn)

Sources: mobile/schema.graphql:439-445

Security & Implementation Conventions

The context adheres to strict backend conventions to ensure data integrity and security.

1. Token Hashing: Secrets for user_tokens are never stored in raw form. They are hashed using SHA3 before persistence.
2. IDOR Protection: GraphQL node fetchers and child field resolvers must re-apply viewer authorization to ensure global IDs do not bypass ownership rules.
3. Timestamp Precision: All timestamps use :utc_datetime_usec for microsecond precision.
4. Token Identifiers: While most tables use bigint PKs, user_tokens are permitted to use pure UUIDv7 identifiers.

Sources: AGENTS.md:8-18, ARCHITECTURE.md:265-270

Summary

The Accounts & Identity Context provides a robust foundation for user management in LiveCanvas. By decoupling users from their login methods and enforcing strict hashing and authorization rules, it enables a secure, multi-provider authentication system. Its implementation as a modular monolith boundary ensures that identity logic remains independent of transport layers (GraphQL/WebSockets) and other domain logic like social graphs or live streaming.

Sources: ARCHITECTURE.md:41-45, ARCHITECTURE.md:126-136