Authentication & Entitlements

LV.AI manages user access and resource permissions through a centralized authentication system. The system protects sensitive construction project data, including Leistungsverzeichnisse (LV), bids, and pricing information, while providing flexible access levels for regular and guest users.

The project implements Auth.js (v5) to handle session management and identity verification. During the current MVP phase, the system enforces a global password gate for administrative access alongside a restricted guest mode.

Sources: CLAUDE.md:18, README.md:23

Authentication Architecture

The authentication layer identifies users and issues JSON Web Tokens (JWT) for session persistence. It operates primarily through the NextAuth configuration in the auth module.

User Identity Types

The system categorizes users into two distinct types, which determines their baseline capabilities:

Sources: app/(auth)/auth.ts:10-28

Authentication Flow

The system uses the Credentials provider to validate users. It checks submitted passwords against a secure environment variable.

This diagram illustrates the logic flow within the credentials authorization process.
Sources: app/(auth)/auth.ts:40-80

Credential Management and Security

LV.AI secures access using a global password gate defined in environment configurations.

Password Gate Logic

The system retrieves the gate password from process.env.LV_PASSWORD. If the variable is missing, it defaults to LV2026!!. Users entering this password are automatically associated with the identity admin@lv-ai.local.

Steps for regular authentication:

1. The user provides a password in the login interface.
2. The authorize function compares the input to the LV_GATE_PASSWORD.
3. If valid, the system retrieves the administrative user record from the database.
4. If no administrative user exists, the system executes a fallback to a newly created user record.

Sources: app/(auth)/auth.ts:36-61, README.md:54

Session Callbacks

The authentication module uses JWT and session callbacks to persist user metadata across requests.

• JWT Callback: Attaches the user id and type to the encrypted token whenever a token is created or updated.
• Session Callback: Extracts the id and type from the token and injects them into the session object accessible by the client and server.

Sources: app/(auth)/auth.ts:83-100

Resource Entitlements

Entitlements control access to specific data objects, such as project documents and GAEB files. The system enforces ownership checks at the API level.

Ownership Verification

API routes for documents (text, code, sheets, images) verify that the requesting user owns the resource before allowing any operation.

This diagram shows the ownership validation process for document retrieval.
Sources: app/(chat)/api/document/route.ts:25-48

Server Action Protection

Internal server actions, such as the LV import engine, implement manual auth guards. The requireSession function throws a ChatbotError if a valid user ID is missing from the session, preventing unauthorized file processing.

Sources: app/(chat)/lv/import-actions.ts:10-18

Database Schema Integration

The database stores user identity and links projects to specific users.

• User Table: Contains user IDs, email, and authentication metadata.
• Project Linkage: Every Chat and Project record contains a reference to a userId, enabling the filtering of data by owner.
• Enums: The schema uses landEnum (DE, AT, CH) which may be used in the future to apply regional compliance-based entitlements.

Sources: lib/db/schema.test.ts:85-115

Conclusion

The Authentication & Entitlements system in LV.AI provides a robust foundation for multi-user construction project management. By combining Auth.js session handling with strict ownership checks in API routes and server actions, the platform ensures that sensitive AVA data remains accessible only to authorized personnel. Future development plans include expanding this model into full role-based access control (RBAC) and multi-tenant scaling.

Sources: CLAUDE.md:95