Authentication & Session Management
Relevant source files
The following files were used as context for generating this wiki page:
Authentication and session management in Opificia provide the mechanism for users to securely access the software factory, manage their identity, and organize work within multi-tenant structures called organizations. The system currently utilizes Better Auth as its core authentication library within a stack that includes NestJS and PostgreSQL. Sources: AGENTS.md:14, apps/web/src/pages/auth.tsx:7
System Overview
Opificia supports multiple authentication methods, including email/password credentials and social providers like GitHub. The system organizes users into organizations, which serve as the primary containers for repositories, runs, and members. Sources: apps/web/src/pages/auth.tsx:21-65, apps/web/src/pages/auth.tsx:107-110
The diagram above shows the high-level flow of authentication and organization selection. Sources: apps/web/src/pages/auth.tsx:7-133
Authentication Methods
Users can authenticate through two primary flows: traditional email-based registration/login or third-party OAuth through GitHub.
Email and Password
The system enforces a minimum password length of 12 characters to ensure credential strength. The web interface provides a unified form for both signing in and creating new accounts. Sources: apps/web/src/pages/auth.tsx:39-50
| Feature | Requirement | Description |
|---|---|---|
| Password Length | 12 characters | Minimum length enforced on the sign-up form. |
| Fields (Sign-in) | Email, Password | Required fields for existing users. |
| Fields (Sign-up) | Name, Email, Password | Required fields for new account creation. |
Sources: apps/web/src/pages/auth.tsx:43-52
Social Authentication
Social authentication is implemented using GitHub. The client initiates this via a redirect to a callback URL, typically the root path. Sources: apps/web/src/pages/auth.tsx:58-64
Organization Management
Authentication is tightly coupled with organization management. An organization holds the collaborative assets of the user, and a user must select or create an organization during the onboarding process. Sources: apps/web/src/pages/auth.tsx:107-110
Onboarding Flow
If a person has no active organization, the system presents the Onboarding Page. This page allows the user to:
- List existing organizations associated with their account.
- Select an active organization to begin work.
- Create a new organization by providing a name, which the system automatically "slugifies" (converts to a URL-friendly format).
Sources: apps/web/src/pages/auth.tsx:81-115
The sequence diagram illustrates the creation and activation of a new organization. Sources: apps/web/src/pages/auth.tsx:86-104
Security and Compliance
The authentication system is governed by strict security policies and sovereignty commitments to protect user data and maintain control.
- Credential Handling: The system prioritizes preventing credential exposure in logs, prompts, or pull requests. Sources: SECURITY.md:46-47
- Data Sovereignty: All session data, logs, and traces are stored only where the operator configures, ensuring data stays within the operator's control. Sources: SOVEREIGNTY.md:65-68
- Audit Logging: Changes to human approval requirements or sensitive settings are recorded in an audit log. Sources: SOVEREIGNTY.md:73-75
- Input Sanitization: The web interface uses a Markdown component that prevents the rendering of raw HTML, scripts, or external images within plans or messages, mitigating potential data exfiltration or XSS via authentication-related displays. Sources: apps/web/src/markdown.test.tsx:16-30
Implementation Details
The authentication client is initialized as authClient and used throughout the React frontend to interact with the backend auth services. Sources: apps/web/src/pages/auth.tsx:7
Key Functions
authClient.signIn.email: Authenticates a user with email and password. Sources: apps/web/src/pages/auth.tsx:27authClient.signUp.email: Registers a new user. Sources: apps/web/src/pages/auth.tsx:28authClient.signIn.social: Initiates GitHub OAuth flow. Sources: apps/web/src/pages/auth.tsx:61authClient.organization.create: Provisions a new organization entry. Sources: apps/web/src/pages/auth.tsx:90authClient.organization.setActive: Updates the current session to use a specific organization. Sources: apps/web/src/pages/auth.tsx:92slugify: Converts a string to a lowercase, alphanumeric-only format with hyphens for use as an organization identifier. Sources: apps/web/src/pages/auth.tsx:73-78
Authentication and session management are currently in a "Foundations" (Phase 0) status, with further hardening for credential handling and audit logging planned for Phase 2. Sources: ROADMAP.md:14-25, ROADMAP.md:38-40