Authentication & Authorization

Relevant source files

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

• backend/src/infrastructure/services/JwtService.ts
• backend/src/interfaces/http/middleware/auth.middleware.ts
• backend/src/interfaces/controllers/AuthController.ts
• src/middleware/auth.js
• backend/src/shared/types/index.ts
• backend/src/infrastructure/database/prisma/schema.prisma

Authentication and Authorization in AtlasCleanAI Enterprise provides a secure mechanism for verifying user identities and controlling access to platform resources. The system employs a dual-layered approach: JSON Web Tokens (JWT) for standard user sessions and API key-based validation for specific internal or developer-facing services.

The platform manages several distinct user roles including CUSTOMER, ADMIN, CLEANER, and MANAGER, ensuring that actions like booking management, workforce oversight, and AI interactions are restricted to authorized personnel. Sources: backend/src/infrastructure/database/prisma/schema.prisma:14-19, backend/src/shared/types/index.ts:3

JWT-Based Authentication

The core authentication flow uses short-lived access tokens and longer-lived refresh tokens. The JwtService handles token generation and verification, embedding specific user metadata into the token payload to support downstream authorization decisions.

Token Architecture

The system issues JWTs containing specific claims:

• sub: The unique identifier of the user.
• email: The user's registered email address.
• role: The assigned permission level.
• tokenVersion: An integer used to invalidate tokens globally or per user.

Sources: backend/src/infrastructure/services/JwtService.ts, backend/src/shared/types/index.ts:10-15

Authentication Flow

When a user accesses a protected route, the authMiddleware intercepts the request. It extracts the Bearer token from the Authorization header and validates it via the JwtService.

The diagram shows the interceptor logic for validating user identity before allowing access to API resources. Sources: backend/src/interfaces/http/middleware/auth.middleware.ts:9-24

Authorization & Role Management

Authorization is enforced by checking the role and status fields stored in the database and echoed in the JWT payload. The system defines a hierarchy of access across the application's core models.

User Roles and Statuses

Role	Description
CUSTOMER	Standard user for booking cleaning services.
CLEANER	Field staff managing jobs and availability.
MANAGER	Operations staff overseeing workforce and routing.
ADMIN	Full system access and configuration.

Status	Effect
ACTIVE	Normal access granted.
PENDING_VERIFICATION	Restricted access until email or identity is confirmed.
SUSPENDED	All access revoked.

Sources: backend/src/infrastructure/database/prisma/schema.prisma:14-27, backend/src/shared/types/index.ts:3-4

Request Context

Authenticated requests are cast to the AuthenticatedRequest type, which includes an optional user object. This object allows controllers to identify the caller and apply business logic specific to their role. Sources: backend/src/shared/types/index.ts:22-24

API Key Authentication

For specialized endpoints, such as the Atlas AI chat interface, the system supports simple API key authentication. This is primarily used to protect AI resources from unauthorized external consumption.

Implementation Details

The apiKeyAuth middleware compares the x-api-key header against the ATLAS_API_KEY environment variable. It uses timingSafeEqual to prevent timing attacks during key comparison.

// src/middleware/auth.js:15-20
  const provided = req.headers['x-api-key'];
  const providedBuffer = typeof provided === 'string' ? Buffer.from(provided) : null;
  const configuredBuffer = Buffer.from(configuredKey);
  const matches =
    providedBuffer &&
    providedBuffer.length === configuredBuffer.length &&
    timingSafeEqual(providedBuffer, configuredBuffer);

Sources: src/middleware/auth.js:9-30

Token Refresh Mechanism

To maintain security without compromising user experience, the system implements a refresh token pattern.

1. Login: User provides credentials and receives an accessToken and a refreshToken.
2. Access: The accessToken is used for API calls until it expires.
3. Refresh: The client sends the refreshToken to the /auth/refresh-token endpoint.
4. Rotation: The AuthController invokes RefreshTokenUseCase to validate the refresh token and issue a new token pair.

Sources: backend/src/interfaces/controllers/AuthController.ts:34-42, backend/src/infrastructure/services/JwtService.ts

Summary

Authentication and Authorization in AtlasCleanAI Enterprise ensure robust security through JWT lifecycle management and role-based access control. By separating identity verification (JWT) from resource-specific protection (API keys), the platform secures transactional cleaning data and AI capabilities independently while maintaining a unified user context across the system.