Backend: User Authentication & Accounts

Relevant source files

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

• server/common/account/index.ts
• server/common/auth/index.ts
• server/common/oauth/oauth.ts
• server/common/account/account.endpoints.ts
• deployment/cdk/server/v2/accountLambdaFunctions.ts

The Nucleus backend provides a comprehensive system for user authentication and account management. It is built as a serverless application using Node.js and is designed to be deployed on AWS Lambda. The system leverages the Hono web framework for routing and the Lucia library for auth and session management.

This architecture supports multiple authentication strategies, including traditional email/password, magic links, One-Time Passwords (OTP), and OAuth 2.0 with external providers like Google and GitHub. The core logic is separated into distinct modules for handling account operations, authentication flows, and OAuth integrations, all deployed as individual Lambda functions for scalability and separation of concerns.

Serverless Architecture

The account and authentication services are deployed as a set of AWS Lambda functions, defined and configured using the AWS Cloud Development Kit (CDK). This serverless approach allows for a scalable, event-driven backend. Three primary Lambda functions handle all account-related traffic.

Sources: deployment/cdk/server/v2/accountLambdaFunctions.ts

Lambda Functions

The following diagram illustrates the high-level architecture, where client requests are routed to specific Lambda functions.

The table below details the purpose and configuration of each Lambda function.

Function Name	Entry Point	Description
accountV2Fn	server/main.ts	Handles primary account management endpoints like login, session management, magic links, and OTP.
accountV2AuthFn	server/auth.ts	Manages core authentication setup and session validation middleware. Likely used by other services.
accountV2OAuthFn	server/oauth.ts	Manages the entire OAuth 2.0 flow, including redirects to providers and handling callbacks.

Sources: deployment/cdk/server/v2/accountLambdaFunctions.ts:22-77

Authentication Core & Session Management

The core of the authentication system is built using the Lucia library. It is responsible for creating, managing, and validating user sessions. The configuration is centralized in server/common/auth/index.ts.

Lucia Configuration

The system uses a D1Adapter to connect Lucia with a Cloudflare D1 database, which stores user and session data. The auth instance is configured with specific attributes for both users and sessions.

Sources: server/common/auth/index.ts:10-23

Data Models

The following class diagram shows the structure of the User and Session entities as defined by the Lucia configuration.

• User Attributes: email, github_username, name, and avatar are stored directly on the user object.
• Session Attributes: No custom attributes are defined for the session; it uses Lucia's defaults.

Account API Endpoints

The account-related API endpoints are defined using the Hono framework. The routes handle various authentication methods and session operations.

Sources: server/common/account/account.endpoints.ts

Method	Path	Description
POST	/	Creates a new user account.
GET	/session	Retrieves the current user's session information.
POST	/session	Creates a new session (logs the user in) using credentials.
DELETE	/session	Deletes the current session (logs the user out).
POST	/magic	Initiates a magic link login flow by sending an email to the user.
POST	/otp	Initiates a One-Time Password (OTP) login flow.
POST	/password	Allows a user to set or reset their password.

Sources: server/common/account/account.endpoints.ts:10-16

Authentication Flows

The system supports several distinct authentication flows, from traditional passwords to modern OAuth and passwordless methods.

Password, Magic Link, and OTP

The logic for these authentication methods resides in the accountController.

• Password Login: The /session endpoint validates user credentials and, upon success, calls auth.createSession() to generate a session cookie.
• Magic Link Login: The /magic endpoint generates a token and sends a login link to the user's email. The user clicks the link to complete authentication.
• OTP Login: The /otp endpoint handles a similar flow but with a one-time code.

Sources: server/common/account/index.ts:20-104

OAuth 2.0 Flow (Google & GitHub)

The backend provides built-in support for OAuth 2.0 with Google and GitHub, managed by the accountV2OAuthFn Lambda.

Sources: server/common/oauth/oauth.ts

The process involves two main steps:

1. Redirect: The client calls an endpoint like /login/github or /login/google, which generates a state cookie and redirects the user to the provider's authorization page.
2. Callback: After the user authorizes the application, the provider redirects back to a callback URL (e.g., /login/github/callback). The backend validates the state, exchanges the received code for an access token, and fetches the user's profile from the provider.

The callback logic then either finds an existing user linked to that provider account or creates a new user in the database before creating a new session.

The sequence diagram below details the OAuth 2.0 login flow with GitHub as an example.

Conclusion

The Nucleus backend authentication system is a robust, modern, and scalable solution. Its serverless architecture using AWS Lambda ensures high availability and cost-efficiency. By leveraging powerful open-source libraries like Lucia for auth and Hono for routing, it provides a secure and flexible platform that supports a wide array of authentication methods, catering to diverse user preferences while maintaining a clean and maintainable codebase. The clear separation of concerns across different Lambda functions and modules makes the system easy to extend and manage.