Merge branch 'main' into docs

* Adding rate limiting docs

* update rate limiting docs

* Resolve conflict

---------

Co-authored-by: Wayne <5291640+ringoinca@users.noreply.github.com>

.env.example

@@ -54,17 +54,19 @@ STORAGE_S3_FORCE_PATH_STYLE=false
 
 # --- Security & Authentication ---
 
+# Rate Limiting
+# The window in milliseconds for which API requests are checked. Defaults to 60000 (1 minute).
+RATE_LIMIT_WINDOW_MS=60000
+# The maximum number of API requests allowed from an IP within the window. Defaults to 100.
+RATE_LIMIT_MAX_REQUESTS=100
+
 # JWT
 # IMPORTANT: Change this to a long, random, and secret string in your .env file
 JWT_SECRET=a-very-secret-key-that-you-should-change
 JWT_EXPIRES_IN="7d"
 
-# Set the credentials for the initial admin user.
-SUPER_API_KEY=
 
 # Master Encryption Key for sensitive data (Such as Ingestion source credentials and passwords)
 # IMPORTANT: Generate a secure, random 32-byte hex string for this
 # You can use `openssl rand -hex 32` to generate a key.
 ENCRYPTION_KEY=
-
-

README.md

@@ -78,7 +78,7 @@ Open Archiver is built on a modern, scalable, and maintainable technology stack:
 
     ```bash
     git clone https://github.com/LogicLabs-OU/OpenArchiver.git
-    cd open-archiver
+    cd OpenArchiver
     ```
 
 2.  **Configure your environment:**

docs/.vitepress/config.mts

@@ -71,6 +71,7 @@ export default defineConfig({
 				items: [
 					{ text: 'Overview', link: '/api/' },
 					{ text: 'Authentication', link: '/api/authentication' },
+					{ text: 'Rate Limiting', link: '/api/rate-limiting' },
 					{ text: 'Auth', link: '/api/auth' },
 					{ text: 'Archived Email', link: '/api/archived-email' },
 					{ text: 'Dashboard', link: '/api/dashboard' },

docs/api/authentication.md

@@ -1,60 +1,25 @@
 # API Authentication
 
-To access protected API endpoints, you need to include a JSON Web Token (JWT) in the `Authorization` header of your requests.
+To access protected API endpoints, you need to include a user-generated API key in the `X-API-KEY` header of your requests.
 
-## Obtaining a JWT
+## 1. Creating an API Key
 
-First, you need to authenticate with the `/api/v1/auth/login` endpoint by providing your email and password. If the credentials are correct, the API will return an `accessToken`.
+You can create, manage, and view your API keys through the application's user interface.
 
-**Request:**
+1.  Navigate to **Settings > API Keys** in the dashboard.
+2.  Click the **"Generate API Key"** button.
+3.  Provide a descriptive name for your key and select an expiration period.
+4.  The new API key will be displayed. **Copy this key immediately and store it in a secure location. You will not be able to see it again.**
 
-```http
-POST /api/v1/auth/login
-Content-Type: application/json
+## 2. Making Authenticated Requests
 
-{
-  "email": "user@example.com",
-  "password": "your-password"
-}
-```
-
-**Successful Response:**
-
-```json
-{
-	"accessToken": "your.jwt.token",
-	"user": {
-		"id": "user-id",
-		"email": "user@example.com",
-		"role": "user"
-	}
-}
-```
-
-## Making Authenticated Requests
-
-Once you have the `accessToken`, you must include it in the `Authorization` header of all subsequent requests to protected endpoints, using the `Bearer` scheme.
+Once you have your API key, you must include it in the `X-API-KEY` header of all subsequent requests to protected API endpoints.
 
 **Example:**
 
 ```http
 GET /api/v1/dashboard/stats
-Authorization: Bearer your.jwt.token
+X-API-KEY: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
 ```
 
-If the token is missing, expired, or invalid, the API will respond with a `401 Unauthorized` status code.
-
-## Using a Super API Key
-
-Alternatively, for server-to-server communication or scripts, you can use a super API key. This key provides unrestricted access to the API and should be kept secret.
-
-You can set the `SUPER_API_KEY` in your `.env` file.
-
-To authenticate using the super API key, include it in the `Authorization` header as a Bearer token.
-
-**Example:**
-
-```http
-GET /api/v1/dashboard/stats
-Authorization: Bearer your-super-secret-api-key
-```
+If the API key is missing, expired, or invalid, the API will respond with a `401 Unauthorized` status code.

docs/api/rate-limiting.md

@@ -0,0 +1,51 @@
+# Rate Limiting
+
+The API implements rate limiting as a security measure to protect your instance from denial-of-service (DoS) and brute-force attacks. This is a crucial feature for maintaining the security and stability of the application.
+
+## How It Works
+
+The rate limiter restricts the number of requests an IP address can make within a specific time frame. These limits are configurable via environment variables to suit your security needs.
+
+By default, the limits are:
+
+- **100 requests** per **1 minute** per IP address.
+
+If this limit is exceeded, the API will respond with an HTTP `429 Too Many Requests` status code.
+
+### Response Body
+
+When an IP address is rate-limited, the API will return a JSON response with the following format:
+
+```json
+{
+	"status": 429,
+	"message": "Too many requests from this IP, please try again after 15 minutes"
+}
+```
+
+## Configuration
+
+You can customize the rate-limiting settings by setting the following environment variables in your `.env` file:
+
+- `RATE_LIMIT_WINDOW_MS`: The time window in milliseconds. Defaults to `60000` (1 minute).
+- `RATE_LIMIT_MAX_REQUESTS`: The maximum number of requests allowed per IP address within the time window. Defaults to `100`.
+
+## Handling Rate Limits
+
+If you are developing a client that interacts with the API, you should handle rate limiting gracefully:
+
+1.  **Check the Status Code**: Monitor for a `429` HTTP status code in responses.
+2.  **Implement a Retry Mechanism**: When you receive a `429` response, it is best practice to wait before retrying the request. Implementing an exponential backoff strategy is recommended.
+3.  **Check Headers**: The response will include the following standard headers to help you manage your request rate:
+    - `RateLimit-Limit`: The maximum number of requests allowed in the current window.
+    - `RateLimit-Remaining`: The number of requests you have left in the current window.
+    - `RateLimit-Reset`: The time when the rate limit window will reset, in UTC epoch seconds.
+
+## Excluded Endpoints
+
+Certain essential endpoints are excluded from rate limiting to ensure the application's UI remains responsive. These are:
+
+- `/auth/status`
+- `/settings/system`
+
+These endpoints can be called as needed without affecting your rate limit count.

docs/user-guides/installation.md

@@ -105,12 +105,14 @@ These variables are used by `docker-compose.yml` to configure the services.
 
 #### Security & Authentication
 
-| Variable         | Description                                                         | Default Value                              |
-| ---------------- | ------------------------------------------------------------------- | ------------------------------------------ |
-| `JWT_SECRET`     | A secret key for signing JWT tokens.                                | `a-very-secret-key-that-you-should-change` |
-| `JWT_EXPIRES_IN` | The expiration time for JWT tokens.                                 | `7d`                                       |
-| `SUPER_API_KEY`  | An API key with super admin privileges.                             |                                            |
-| `ENCRYPTION_KEY` | A 32-byte hex string for encrypting sensitive data in the database. |                                            |
+| Variable                         | Description                                                                                                                                    | Default Value                              |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `JWT_SECRET`                     | A secret key for signing JWT tokens.                                                                                                           | `a-very-secret-key-that-you-should-change` |
+| `JWT_EXPIRES_IN`                 | The expiration time for JWT tokens.                                                                                                            | `7d`                                       |
+| ~~`SUPER_API_KEY`~~ (Deprecated) | An API key with super admin privileges. (The SUPER_API_KEY is deprecated since v0.3.0 after we roll out the role-based access control system.) |                                            |
+| `RATE_LIMIT_WINDOW_MS`           | The window in milliseconds for which API requests are checked.                                                                                 | `900000` (15 minutes)                      |
+| `RATE_LIMIT_MAX_REQUESTS`        | The maximum number of API requests allowed from an IP within the window.                                                                       | `100`                                      |
+| `ENCRYPTION_KEY`                 | A 32-byte hex string for encrypting sensitive data in the database.                                                                            |                                            |
 
 ## 3. Run the Application
 

packages/backend/package.json

@@ -60,7 +60,8 @@
 		"sqlite3": "^5.1.7",
 		"tsconfig-paths": "^4.2.0",
 		"xlsx": "^0.18.5",
-		"yauzl": "^3.2.0"
+		"yauzl": "^3.2.0",
+		"zod": "^4.1.5"
 	},
 	"devDependencies": {
 		"@bull-board/api": "^6.11.0",

packages/backend/src/api/controllers/api-key.controller.ts

@@ -0,0 +1,66 @@
+import { Request, Response } from 'express';
+import { ApiKeyService } from '../../services/ApiKeyService';
+import { z } from 'zod';
+import { config } from '../../config';
+
+const generateApiKeySchema = z.object({
+	name: z
+		.string()
+		.min(1, 'API kay name must be more than 1 characters')
+		.max(255, 'API kay name must not be more than 255 characters'),
+	expiresInDays: z
+		.number()
+		.int()
+		.positive('Only positive number is allowed')
+		.max(730, 'The API key must expire within 2 years / 730 days.'),
+});
+
+export class ApiKeyController {
+	public async generateApiKey(req: Request, res: Response) {
+		if (config.app.isDemo) {
+			return res.status(403).json({ message: req.t('errors.demoMode') });
+		}
+		try {
+			const { name, expiresInDays } = generateApiKeySchema.parse(req.body);
+			if (!req.user || !req.user.sub) {
+				return res.status(401).json({ message: 'Unauthorized' });
+			}
+			const userId = req.user.sub;
+
+			const key = await ApiKeyService.generate(userId, name, expiresInDays);
+
+			res.status(201).json({ key });
+		} catch (error) {
+			if (error instanceof z.ZodError) {
+				return res
+					.status(400)
+					.json({ message: req.t('api.requestBodyInvalid'), errors: error.message });
+			}
+			res.status(500).json({ message: req.t('errors.internalServerError') });
+		}
+	}
+
+	public async getApiKeys(req: Request, res: Response) {
+		if (!req.user || !req.user.sub) {
+			return res.status(401).json({ message: 'Unauthorized' });
+		}
+		const userId = req.user.sub;
+		const keys = await ApiKeyService.getKeys(userId);
+
+		res.status(200).json(keys);
+	}
+
+	public async deleteApiKey(req: Request, res: Response) {
+		if (config.app.isDemo) {
+			return res.status(403).json({ message: req.t('errors.demoMode') });
+		}
+		const { id } = req.params;
+		if (!req.user || !req.user.sub) {
+			return res.status(401).json({ message: 'Unauthorized' });
+		}
+		const userId = req.user.sub;
+		await ApiKeyService.deleteKey(id, userId);
+
+		res.status(204).send({ message: req.t('apiKeys.deleteSuccess') });
+	}
+}

packages/backend/src/api/controllers/auth.controller.ts

@@ -121,7 +121,7 @@ export class AuthController {
 				);
 				return res.status(200).json({ needsSetup: false });
 			}
-			return res.status(200).json({ needsSetupUser });
+			return res.status(200).json({ needsSetup: needsSetupUser });
 		} catch (error) {
 			console.error('Status check error:', error);
 			return res.status(500).json({ message: req.t('errors.internalServerError') });

packages/backend/src/api/controllers/settings.controller.ts

@@ -4,9 +4,9 @@ import { config } from '../../config';
 
 const settingsService = new SettingsService();
 
-export const getSettings = async (req: Request, res: Response) => {
+export const getSystemSettings = async (req: Request, res: Response) => {
 	try {
-		const settings = await settingsService.getSettings();
+		const settings = await settingsService.getSystemSettings();
 		res.status(200).json(settings);
 	} catch (error) {
 		// A more specific error could be logged here
@@ -14,13 +14,13 @@ export const getSettings = async (req: Request, res: Response) => {
 	}
 };
 
-export const updateSettings = async (req: Request, res: Response) => {
+export const updateSystemSettings = async (req: Request, res: Response) => {
 	try {
 		// Basic validation can be performed here if necessary
 		if (config.app.isDemo) {
 			return res.status(403).json({ message: req.t('errors.demoMode') });
 		}
-		const updatedSettings = await settingsService.updateSettings(req.body);
+		const updatedSettings = await settingsService.updateSystemSettings(req.body);
 		res.status(200).json(updatedSettings);
 	} catch (error) {
 		// A more specific error could be logged here

packages/backend/src/api/middleware/rateLimiter.ts

@@ -1,10 +1,16 @@
 import rateLimit from 'express-rate-limit';
+import { config } from '../../config';
 
-// Rate limiter to prevent brute-force attacks on the login endpoint
-export const loginRateLimiter = rateLimit({
-	windowMs: 15 * 60 * 1000, // 15 minutes
-	max: 10, // Limit each IP to 10 login requests per windowMs
-	message: 'Too many login attempts from this IP, please try again after 15 minutes',
-	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
-	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+const windowInMinutes = Math.ceil(config.api.rateLimit.windowMs / 60000);
+
+export const rateLimiter = rateLimit({
+	windowMs: config.api.rateLimit.windowMs,
+	max: config.api.rateLimit.max,
+	message: {
+		status: 429,
+		message: `Too many requests from this IP, please try again after ${windowInMinutes} minutes`,
+	},
+	statusCode: 429,
+	standardHeaders: true,
+	legacyHeaders: false,
 });

packages/backend/src/api/middleware/requireAuth.ts

@@ -2,6 +2,9 @@ import type { Request, Response, NextFunction } from 'express';
 import type { AuthService } from '../../services/AuthService';
 import type { AuthTokenPayload } from '@open-archiver/types';
 import 'dotenv/config';
+import { ApiKeyService } from '../../services/ApiKeyService';
+import { UserService } from '../../services/UserService';
+
 // By using module augmentation, we can add our custom 'user' property
 // to the Express Request interface in a type-safe way.
 declare global {
@@ -15,16 +18,30 @@ declare global {
 export const requireAuth = (authService: AuthService) => {
 	return async (req: Request, res: Response, next: NextFunction) => {
 		const authHeader = req.headers.authorization;
+		const apiKeyHeader = req.headers['x-api-key'];
+
+		if (apiKeyHeader) {
+			const userId = await ApiKeyService.validateKey(apiKeyHeader as string);
+			if (!userId) {
+				return res.status(401).json({ message: 'Unauthorized: Invalid API key' });
+			}
+			const user = await new UserService().findById(userId);
+			if (!user) {
+				return res.status(401).json({ message: 'Unauthorized: Invalid user' });
+			}
+			req.user = {
+				sub: user.id,
+				email: user.email,
+				roles: user.role ? [user.role.name] : [],
+			};
+			return next();
+		}
+
 		if (!authHeader || !authHeader.startsWith('Bearer ')) {
 			return res.status(401).json({ message: 'Unauthorized: No token provided' });
 		}
 		const token = authHeader.split(' ')[1];
 		try {
-			// use a SUPER_API_KEY for all authentications. add process.env.SUPER_API_KEY conditional check in case user didn't set a SUPER_API_KEY.
-			if (process.env.SUPER_API_KEY && token === process.env.SUPER_API_KEY) {
-				next();
-				return;
-			}
 			const payload = await authService.verifyToken(token);
 			if (!payload) {
 				return res.status(401).json({ message: 'Unauthorized: Invalid token' });

packages/backend/src/api/routes/api-key.routes.ts

@@ -0,0 +1,15 @@
+import { Router } from 'express';
+import { ApiKeyController } from '../controllers/api-key.controller';
+import { requireAuth } from '../middleware/requireAuth';
+import { AuthService } from '../../services/AuthService';
+
+export const apiKeyRoutes = (authService: AuthService) => {
+	const router = Router();
+	const controller = new ApiKeyController();
+
+	router.post('/', requireAuth(authService), controller.generateApiKey);
+	router.get('/', requireAuth(authService), controller.getApiKeys);
+	router.delete('/:id', requireAuth(authService), controller.deleteApiKey);
+
+	return router;
+};

packages/backend/src/api/routes/auth.routes.ts

@@ -1,5 +1,4 @@
 import { Router } from 'express';
-import { loginRateLimiter } from '../middleware/rateLimiter';
 import type { AuthController } from '../controllers/auth.controller';
 
 export const createAuthRouter = (authController: AuthController): Router => {
@@ -10,14 +9,14 @@ export const createAuthRouter = (authController: AuthController): Router => {
 	 * @description Creates the initial administrator user.
 	 * @access Public
 	 */
-	router.post('/setup', loginRateLimiter, authController.setup);
+	router.post('/setup', authController.setup);
 
 	/**
 	 * @route POST /api/v1/auth/login
 	 * @description Authenticates a user and returns a JWT.
 	 * @access Public
 	 */
-	router.post('/login', loginRateLimiter, authController.login);
+	router.post('/login', authController.login);
 
 	/**
 	 * @route GET /api/v1/auth/status

packages/backend/src/api/routes/settings.routes.ts

@@ -11,14 +11,14 @@ export const createSettingsRouter = (authService: AuthService): Router => {
 	/**
 	 * @returns SystemSettings
 	 */
-	router.get('/', settingsController.getSettings);
+	router.get('/system', settingsController.getSystemSettings);
 
 	// Protected route to update settings
 	router.put(
-		'/',
+		'/system',
 		requireAuth(authService),
 		requirePermission('manage', 'settings', 'settings.noPermissionToUpdate'),
-		settingsController.updateSettings
+		settingsController.updateSystemSettings
 	);
 
 	return router;

packages/backend/src/config/api.ts

@@ -0,0 +1,12 @@
+import 'dotenv/config';
+
+export const apiConfig = {
+	rateLimit: {
+		windowMs: process.env.RATE_LIMIT_WINDOW_MS
+			? parseInt(process.env.RATE_LIMIT_WINDOW_MS, 10)
+			: 1 * 60 * 1000, // 1 minutes
+		max: process.env.RATE_LIMIT_MAX_REQUESTS
+			? parseInt(process.env.RATE_LIMIT_MAX_REQUESTS, 10)
+			: 100, // limit each IP to 100 requests per windowMs
+	},
+};

packages/backend/src/config/index.ts

@@ -2,10 +2,12 @@ import { storage } from './storage';
 import { app } from './app';
 import { searchConfig } from './search';
 import { connection as redisConfig } from './redis';
+import { apiConfig } from './api';
 
 export const config = {
 	storage,
 	app,
 	search: searchConfig,
 	redis: redisConfig,
+	api: apiConfig,
 };

packages/backend/src/database/migrations/0018_flawless_owl.sql

@@ -0,0 +1,11 @@
+CREATE TABLE "api_keys" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"user_id" uuid NOT NULL,
+	"key" text NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "api_keys" ADD CONSTRAINT "api_keys_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;

packages/backend/src/database/migrations/0019_confused_scream.sql

@@ -0,0 +1 @@
+ALTER TABLE "api_keys" ADD COLUMN "key_hash" text NOT NULL;

packages/backend/src/database/migrations/meta/_journal.json

@@ -127,6 +127,20 @@
 			"when": 1755961566627,
 			"tag": "0017_tranquil_shooting_star",
 			"breakpoints": true
+		},
+		{
+			"idx": 18,
+			"version": "7",
+			"when": 1756911118035,
+			"tag": "0018_flawless_owl",
+			"breakpoints": true
+		},
+		{
+			"idx": 19,
+			"version": "7",
+			"when": 1756937533843,
+			"tag": "0019_confused_scream",
+			"breakpoints": true
 		}
 	]
 }

packages/backend/src/database/schema.ts

@@ -6,3 +6,4 @@ export * from './schema/custodians';
 export * from './schema/ingestion-sources';
 export * from './schema/users';
 export * from './schema/system-settings';
+export * from './schema/api-keys';

packages/backend/src/database/schema/api-keys.ts

@@ -0,0 +1,15 @@
+import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
+import { users } from './users';
+
+export const apiKeys = pgTable('api_keys', {
+	id: uuid('id').primaryKey().defaultRandom(),
+	name: text('name').notNull(),
+	userId: uuid('user_id')
+		.notNull()
+		.references(() => users.id, { onDelete: 'cascade' }),
+	key: text('key').notNull(), // Encrypted API key
+	keyHash: text('key_hash').notNull(),
+	expiresAt: timestamp('expires_at', { withTimezone: true, mode: 'date' }).notNull(),
+	createdAt: timestamp('created_at').defaultNow().notNull(),
+	updatedAt: timestamp('updated_at').defaultNow().notNull(),
+});

packages/backend/src/index.ts

@@ -17,6 +17,7 @@ import { createDashboardRouter } from './api/routes/dashboard.routes';
 import { createUploadRouter } from './api/routes/upload.routes';
 import { createUserRouter } from './api/routes/user.routes';
 import { createSettingsRouter } from './api/routes/settings.routes';
+import { apiKeyRoutes } from './api/routes/api-key.routes';
 import { AuthService } from './services/AuthService';
 import { UserService } from './services/UserService';
 import { IamService } from './services/IamService';
@@ -28,6 +29,7 @@ import FsBackend from 'i18next-fs-backend';
 import i18nextMiddleware from 'i18next-http-middleware';
 import path from 'path';
 import { logger } from './config/logger';
+import { rateLimiter } from './api/middleware/rateLimiter';
 
 // Load environment variables
 dotenv.config();
@@ -43,7 +45,7 @@ if (!PORT_BACKEND || !JWT_SECRET || !JWT_EXPIRES_IN) {
 
 // --- i18next Initialization ---
 const initializeI18next = async () => {
-	const systemSettings = await settingsService.getSettings();
+	const systemSettings = await settingsService.getSystemSettings();
 	const defaultLanguage = systemSettings?.language || 'en';
 	logger.info({ language: defaultLanguage }, 'Default language');
 	await i18next.use(FsBackend).init({
@@ -86,10 +88,21 @@ const iamRouter = createIamRouter(iamController, authService);
 const uploadRouter = createUploadRouter(authService);
 const userRouter = createUserRouter(authService);
 const settingsRouter = createSettingsRouter(authService);
+const apiKeyRouter = apiKeyRoutes(authService);
 // upload route is added before middleware because it doesn't use the json middleware.
 app.use('/v1/upload', uploadRouter);
 
 // Middleware for all other routes
+app.use((req, res, next) => {
+	// exclude certain API endpoints from the rate limiter, for example status, system settings
+	const excludedPatterns = [/^\/v\d+\/auth\/status$/, /^\/v\d+\/settings\/system$/];
+	for (const pattern of excludedPatterns) {
+		if (pattern.test(req.path)) {
+			return next();
+		}
+	}
+	rateLimiter(req, res, next);
+});
 app.use(express.json());
 app.use(express.urlencoded({ extended: true }));
 
@@ -105,6 +118,7 @@ app.use('/v1/search', searchRouter);
 app.use('/v1/dashboard', dashboardRouter);
 app.use('/v1/users', userRouter);
 app.use('/v1/settings', settingsRouter);
+app.use('/v1/api-keys', apiKeyRouter);
 
 // Example of a protected route
 app.get('/v1/protected', requireAuth(authService), (req, res) => {

packages/backend/src/locales/en/translation.json

@@ -58,5 +58,12 @@
 		"invalidFilePath": "Invalid file path",
 		"fileNotFound": "File not found",
 		"downloadError": "Error downloading file"
+	},
+	"apiKeys": {
+		"generateSuccess": "API key generated successfully.",
+		"deleteSuccess": "API key deleted successfully."
+	},
+	"api": {
+		"requestBodyInvalid": "Invalid request body."
 	}
 }

packages/backend/src/services/ApiKeyService.ts

@@ -0,0 +1,72 @@
+import { randomBytes, createHash } from 'crypto';
+import { db } from '../database';
+import { apiKeys } from '../database/schema/api-keys';
+import { CryptoService } from './CryptoService';
+import { and, eq } from 'drizzle-orm';
+import { ApiKey } from '@open-archiver/types';
+
+export class ApiKeyService {
+	public static async generate(
+		userId: string,
+		name: string,
+		expiresInDays: number
+	): Promise<string> {
+		const key = randomBytes(32).toString('hex');
+		const expiresAt = new Date();
+		expiresAt.setDate(expiresAt.getDate() + expiresInDays);
+		const keyHash = createHash('sha256').update(key).digest('hex');
+
+		await db.insert(apiKeys).values({
+			userId,
+			name,
+			key: CryptoService.encrypt(key),
+			keyHash,
+			expiresAt,
+		});
+
+		return key;
+	}
+
+	public static async getKeys(userId: string): Promise<ApiKey[]> {
+		const keys = await db.select().from(apiKeys).where(eq(apiKeys.userId, userId));
+
+		return keys
+			.map((apiKey) => {
+				const decryptedKey = CryptoService.decrypt(apiKey.key);
+				if (!decryptedKey) {
+					return null;
+				}
+				return {
+					...apiKey,
+					key: decryptedKey.slice(0, 5) + '*****',
+					expiresAt: apiKey.expiresAt.toISOString(),
+					createdAt: apiKey.createdAt.toISOString(),
+				};
+			})
+			.filter((k): k is NonNullable<typeof k> => k !== null);
+	}
+
+	public static async deleteKey(id: string, userId: string) {
+		await db.delete(apiKeys).where(and(eq(apiKeys.id, id), eq(apiKeys.userId, userId)));
+	}
+	/**
+	 *
+	 * @param key API key
+	 * @returns The owner user ID or null. null means the API key is not found.
+	 */
+	public static async validateKey(key: string): Promise<string | null> {
+		const keyHash = createHash('sha256').update(key).digest('hex');
+		const [apiKey] = await db.select().from(apiKeys).where(eq(apiKeys.keyHash, keyHash));
+		if (!apiKey || apiKey.expiresAt < new Date()) {
+			return null;
+		}
+
+		const decryptedKey = CryptoService.decrypt(apiKey.key);
+		if (decryptedKey !== key) {
+			// This should not happen if the hash matches, but as a security measure, we double-check.
+			return null;
+		}
+
+		return apiKey.userId;
+	}
+}

packages/backend/src/services/SettingsService.ts

@@ -15,11 +15,11 @@ export class SettingsService {
 	 * If no settings exist, it initializes and returns the default settings.
 	 * @returns The system settings.
 	 */
-	public async getSettings(): Promise<SystemSettings> {
+	public async getSystemSettings(): Promise<SystemSettings> {
 		const settings = await db.select().from(systemSettings).limit(1);
 
 		if (settings.length === 0) {
-			return this.createDefaultSettings();
+			return this.createDefaultSystemSettings();
 		}
 
 		return settings[0].config;
@@ -30,8 +30,8 @@ export class SettingsService {
 	 * @param newConfig - A partial object of the new settings configuration.
 	 * @returns The updated system settings.
 	 */
-	public async updateSettings(newConfig: Partial<SystemSettings>): Promise<SystemSettings> {
-		const currentConfig = await this.getSettings();
+	public async updateSystemSettings(newConfig: Partial<SystemSettings>): Promise<SystemSettings> {
+		const currentConfig = await this.getSystemSettings();
 		const mergedConfig = { ...currentConfig, ...newConfig };
 
 		// Since getSettings ensures a record always exists, we can directly update.
@@ -45,7 +45,7 @@ export class SettingsService {
 	 * This is called internally when no settings are found.
 	 * @returns The newly created default settings.
 	 */
-	private async createDefaultSettings(): Promise<SystemSettings> {
+	private async createDefaultSystemSettings(): Promise<SystemSettings> {
 		const [result] = await db
 			.insert(systemSettings)
 			.values({ config: DEFAULT_SETTINGS })

packages/frontend/src/lib/translations/en.json

@@ -222,8 +222,36 @@
 			"system": "System",
 			"users": "Users",
 			"roles": "Roles",
+			"api_keys": "API Keys",
 			"logout": "Logout"
 		},
+		"api_keys_page": {
+			"title": "API Keys",
+			"header": "API Keys",
+			"generate_new_key": "Generate New Key",
+			"name": "Name",
+			"key": "Key",
+			"expires_at": "Expires At",
+			"created_at": "Created At",
+			"actions": "Actions",
+			"delete": "Delete",
+			"no_keys_found": "No API keys found.",
+			"generate_modal_title": "Generate New API Key",
+			"generate_modal_description": "Please provide a name and expiration for your new API key.",
+			"expires_in": "Expires In",
+			"select_expiration": "Select an expiration",
+			"30_days": "30 Days",
+			"60_days": "60 Days",
+			"6_months": "6 Months",
+			"12_months": "12 Months",
+			"24_months": "24 Months",
+			"generate": "Generate",
+			"new_api_key": "New API Key",
+			"failed_to_delete": "Failed to delete API key",
+			"api_key_deleted": "API key deleted",
+			"generated_title": "API Key Generated",
+			"generated_message": "Your API key is generated, please copy and save it in a secure place. This key will only be shown once."
+		},
 		"archived_emails_page": {
 			"title": "Archived emails",
 			"header": "Archived Emails",

packages/frontend/src/routes/+layout.server.ts

@@ -6,8 +6,9 @@ import type { SystemSettings } from '@open-archiver/types';
 
 export const load: LayoutServerLoad = async (event) => {
 	const { locals, url } = event;
-	try {
-		const response = await api('/auth/status', event);
+	const response = await api('/auth/status', event);
+
+	if (response.ok) {
 		const { needsSetup } = await response.json();
 
 		if (needsSetup && url.pathname !== '/setup') {
@@ -17,19 +18,24 @@ export const load: LayoutServerLoad = async (event) => {
 		if (!needsSetup && url.pathname === '/setup') {
 			throw redirect(307, '/signin');
 		}
-	} catch (error) {
-		throw error;
+	} else {
+		// if auth status check fails, we can't know if the setup is complete,
+		// so we redirect to signin page as a safe fallback.
+		if (url.pathname !== '/signin') {
+			console.error('Failed to get auth status:', await response.text());
+			throw redirect(307, '/signin');
+		}
 	}
 
-	const settingsResponse = await api('/settings', event);
-	const settings: SystemSettings | null = settingsResponse.ok
-		? await settingsResponse.json()
+	const systemSettingsResponse = await api('/settings/system', event);
+	const systemSettings: SystemSettings | null = systemSettingsResponse.ok
+		? await systemSettingsResponse.json()
 		: null;
 
 	return {
 		user: locals.user,
 		accessToken: locals.accessToken,
 		isDemo: process.env.IS_DEMO === 'true',
-		settings,
+		systemSettings,
 	};
 };

packages/frontend/src/routes/+layout.svelte

@@ -18,7 +18,7 @@
 			let finalTheme = $theme;
 
 			if (finalTheme === 'system') {
-				finalTheme = data.settings?.theme || 'system';
+				finalTheme = data.systemSettings?.theme || 'system';
 			}
 
 			const isDark =

packages/frontend/src/routes/+layout.ts

@@ -8,8 +8,8 @@ export const load: LayoutLoad = async ({ url, data }) => {
 
 	let initLocale: SupportedLanguage = 'en'; // Default fallback
 
-	if (data.settings?.language) {
-		initLocale = data.settings.language;
+	if (data.systemSettings?.language) {
+		initLocale = data.systemSettings.language;
 	}
 
 	console.log(initLocale);

packages/frontend/src/routes/dashboard/+layout.svelte

@@ -33,6 +33,10 @@
 					href: '/dashboard/settings/roles',
 					label: $t('app.layout.roles'),
 				},
+				{
+					href: '/dashboard/settings/api-keys',
+					label: $t('app.layout.api_keys'),
+				},
 			],
 		},
 	];

packages/frontend/src/routes/dashboard/settings/api-keys/+page.server.ts

@@ -0,0 +1,49 @@
+import { api } from '$lib/server/api';
+import type { Actions, PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async (event) => {
+	const response = await api('/api-keys', event);
+	const apiKeys = await response.json();
+
+	return {
+		apiKeys,
+	};
+};
+
+export const actions: Actions = {
+	generate: async (event) => {
+		const data = await event.request.formData();
+		const name = data.get('name') as string;
+		const expiresInDays = Number(data.get('expiresInDays'));
+
+		const response = await api('/api-keys', event, {
+			method: 'POST',
+			body: JSON.stringify({ name, expiresInDays }),
+		});
+
+		const responseBody = await response.json();
+
+		if (!response.ok) {
+			return {
+				message: responseBody.message || '',
+				errors: responseBody.errors,
+			};
+		}
+
+		return {
+			newApiKey: responseBody.key,
+		};
+	},
+	delete: async (event) => {
+		const data = await event.request.formData();
+		const id = data.get('id') as string;
+
+		await api(`/api-keys/${id}`, event, {
+			method: 'DELETE',
+		});
+
+		return {
+			success: true,
+		};
+	},
+};

packages/frontend/src/routes/dashboard/settings/api-keys/+page.svelte

@@ -0,0 +1,266 @@
+<script lang="ts">
+	import { Button } from '$lib/components/ui/button';
+	import * as Dialog from '$lib/components/ui/dialog';
+	import { Input } from '$lib/components/ui/input';
+	import { Label } from '$lib/components/ui/label';
+	import * as Select from '$lib/components/ui/select';
+	import * as Table from '$lib/components/ui/table';
+	import type { ActionData, PageData } from './$types';
+	import { t } from '$lib/translations';
+	import { MoreHorizontal, Trash } from 'lucide-svelte';
+	import * as DropdownMenu from '$lib/components/ui/dropdown-menu';
+	import { setAlert } from '$lib/components/custom/alert/alert-state.svelte';
+	import * as Card from '$lib/components/ui/card/index.js';
+	import { api } from '$lib/api.client';
+
+	// Temporary type definition based on the backend schema
+	type ApiKey = {
+		id: string;
+		name: string;
+		userId: string;
+		key: string;
+		expiresAt: Date;
+		createdAt: Date;
+		updatedAt: Date;
+	};
+
+	let { data, form }: { data: PageData; form: ActionData } = $props();
+	let apiKeys = $state<ApiKey[]>(data.apiKeys);
+
+	let isDeleteDialogOpen = $state(false);
+	let newAPIKeyDialogOpen = $state(false);
+	let keyToDelete = $state<ApiKey | null>(null);
+	let isDeleting = $state(false);
+	let selectedExpiration = $state('30');
+	const expirationOptions = [
+		{ value: '30', label: $t('app.api_keys_page.30_days') },
+		{ value: '60', label: $t('app.api_keys_page.60_days') },
+		{ value: '180', label: $t('app.api_keys_page.6_months') },
+		{ value: '365', label: $t('app.api_keys_page.12_months') },
+		{ value: '730', label: $t('app.api_keys_page.24_months') },
+	];
+	const triggerContent = $derived(
+		expirationOptions.find((p) => p.value === selectedExpiration)?.label ??
+			$t('app.api_keys_page.select_expiration')
+	);
+
+	const openDeleteDialog = (apiKey: ApiKey) => {
+		keyToDelete = apiKey;
+		isDeleteDialogOpen = true;
+	};
+
+	const confirmDelete = async () => {
+		if (!keyToDelete) return;
+		isDeleting = true;
+		try {
+			const res = await api(`/api-keys/${keyToDelete.id}`, { method: 'DELETE' });
+			if (!res.ok) {
+				const errorBody = await res.json();
+				setAlert({
+					type: 'error',
+					title: $t('app.api_keys_page.failed_to_delete'),
+					message: errorBody.message || JSON.stringify(errorBody),
+					duration: 5000,
+					show: true,
+				});
+				return;
+			}
+			apiKeys = apiKeys.filter((k) => k.id !== keyToDelete!.id);
+			isDeleteDialogOpen = false;
+			keyToDelete = null;
+			setAlert({
+				type: 'success',
+				title: $t('app.api_keys_page.api_key_deleted'),
+				message: $t('app.api_keys_page.api_key_deleted'),
+				duration: 3000,
+				show: true,
+			});
+		} finally {
+			isDeleting = false;
+		}
+	};
+
+	$effect(() => {
+		if (form?.newApiKey) {
+			setAlert({
+				type: 'success',
+				title: $t('app.api_keys_page.generated_title'),
+				message: $t('app.api_keys_page.generated_message'),
+				duration: 3000, // Keep it on screen longer for copying
+				show: true,
+			});
+		}
+		if (form?.errors) {
+			setAlert({
+				type: 'error',
+				title: form.message,
+				message: form.errors || '',
+				duration: 3000, // Keep it on screen longer for copying
+				show: true,
+			});
+		}
+	});
+</script>
+
+<svelte:head>
+	<title>{$t('app.api_keys_page.title')} - Open Archiver</title>
+</svelte:head>
+
+<div class="">
+	<div class="mb-4 flex items-center justify-between">
+		<h1 class="text-2xl font-bold">{$t('app.api_keys_page.title')}</h1>
+		<Dialog.Root bind:open={newAPIKeyDialogOpen}>
+			<Dialog.Trigger>
+				<Button>{$t('app.api_keys_page.generate_new_key')}</Button>
+			</Dialog.Trigger>
+			<Dialog.Content>
+				<Dialog.Header>
+					<Dialog.Title>{$t('app.api_keys_page.generate_modal_title')}</Dialog.Title>
+					<Dialog.Description>
+						{$t('app.api_keys_page.generate_modal_description')}
+					</Dialog.Description>
+				</Dialog.Header>
+				<form
+					method="POST"
+					action="?/generate"
+					onsubmit={() => {
+						newAPIKeyDialogOpen = false;
+					}}
+				>
+					<div class="grid gap-4 py-4">
+						<div class="grid grid-cols-4 items-center gap-4">
+							<Label for="name" class="text-right"
+								>{$t('app.api_keys_page.name')}</Label
+							>
+							<Input id="name" name="name" class="col-span-3" />
+						</div>
+						<div class="grid grid-cols-4 items-center gap-4">
+							<Label for="expiresInDays" class="text-right"
+								>{$t('app.api_keys_page.expires_in')}</Label
+							>
+							<Select.Root
+								name="expiresInDays"
+								bind:value={selectedExpiration}
+								type="single"
+							>
+								<Select.Trigger class="col-span-3">
+									{triggerContent}
+								</Select.Trigger>
+								<Select.Content>
+									{#each expirationOptions as option}
+										<Select.Item value={option.value}
+											>{option.label}</Select.Item
+										>
+									{/each}
+								</Select.Content>
+							</Select.Root>
+						</div>
+					</div>
+					<Dialog.Footer>
+						<Button type="submit">{$t('app.api_keys_page.generate')}</Button>
+					</Dialog.Footer>
+				</form>
+			</Dialog.Content>
+		</Dialog.Root>
+	</div>
+	{#if form?.newApiKey}
+		<Card.Root class="mb-4 border-0 bg-green-200 text-green-600 shadow-none">
+			<Card.Header>
+				<Card.Title>{$t('app.api_keys_page.generated_title')}</Card.Title>
+				<Card.Description class=" text-green-600"
+					>{$t('app.api_keys_page.generated_message')}</Card.Description
+				>
+			</Card.Header>
+			<Card.Content>
+				<p>{form?.newApiKey}</p>
+			</Card.Content>
+		</Card.Root>
+	{/if}
+
+	<div class="rounded-md border">
+		<Table.Root>
+			<Table.Header>
+				<Table.Row>
+					<Table.Head>{$t('app.api_keys_page.name')}</Table.Head>
+					<Table.Head>{$t('app.api_keys_page.key')}</Table.Head>
+					<Table.Head>{$t('app.api_keys_page.expires_at')}</Table.Head>
+					<Table.Head>{$t('app.api_keys_page.created_at')}</Table.Head>
+					<Table.Head class="text-right">{$t('app.users.actions')}</Table.Head>
+				</Table.Row>
+			</Table.Header>
+			<Table.Body>
+				{#if apiKeys.length > 0}
+					{#each apiKeys as apiKey (apiKey.id)}
+						<Table.Row>
+							<Table.Cell>{apiKey.name}</Table.Cell>
+							<Table.Cell>{apiKey.key.substring(0, 8)}</Table.Cell>
+							<Table.Cell
+								>{new Date(apiKey.expiresAt).toLocaleDateString()}</Table.Cell
+							>
+							<Table.Cell
+								>{new Date(apiKey.createdAt).toLocaleDateString()}</Table.Cell
+							>
+							<Table.Cell class="text-right">
+								<DropdownMenu.Root>
+									<DropdownMenu.Trigger>
+										<Button variant="ghost" class="h-8 w-8 p-0">
+											<span class="sr-only">{$t('app.users.open_menu')}</span>
+											<MoreHorizontal class="h-4 w-4" />
+										</Button>
+									</DropdownMenu.Trigger>
+									<DropdownMenu.Content>
+										<DropdownMenu.Label
+											>{$t('app.users.actions')}</DropdownMenu.Label
+										>
+										<DropdownMenu.Separator />
+										<DropdownMenu.Item
+											class="text-destructive cursor-pointer"
+											onclick={() => openDeleteDialog(apiKey)}
+										>
+											<Trash class="mr-2 h-4 w-4" />
+											{$t('app.users.delete')}
+										</DropdownMenu.Item>
+									</DropdownMenu.Content>
+								</DropdownMenu.Root>
+							</Table.Cell>
+						</Table.Row>
+					{/each}
+				{:else}
+					<Table.Row>
+						<Table.Cell colspan={5} class="h-24 text-center"
+							>{$t('app.api_keys_page.no_keys_found')}</Table.Cell
+						>
+					</Table.Row>
+				{/if}
+			</Table.Body>
+		</Table.Root>
+	</div>
+</div>
+
+<Dialog.Root bind:open={isDeleteDialogOpen}>
+	<Dialog.Content class="sm:max-w-lg">
+		<Dialog.Header>
+			<Dialog.Title>{$t('app.users.delete_confirmation_title')}</Dialog.Title>
+			<Dialog.Description>
+				{$t('app.users.delete_confirmation_description')}
+			</Dialog.Description>
+		</Dialog.Header>
+		<Dialog.Footer class="sm:justify-start">
+			<Button
+				type="button"
+				variant="destructive"
+				onclick={confirmDelete}
+				disabled={isDeleting}
+			>
+				{#if isDeleting}
+					{$t('app.users.deleting')}...
+				{:else}
+					{$t('app.users.confirm')}
+				{/if}
+			</Button>
+			<Dialog.Close>
+				<Button type="button" variant="secondary">{$t('app.users.cancel')}</Button>
+			</Dialog.Close>
+		</Dialog.Footer>
+	</Dialog.Content>
+</Dialog.Root>

packages/frontend/src/routes/dashboard/settings/system/+page.server.ts

@@ -4,16 +4,16 @@ import { error, fail } from '@sveltejs/kit';
 import type { Actions, PageServerLoad } from './$types';
 
 export const load: PageServerLoad = async (event) => {
-	const response = await api('/settings', event);
+	const response = await api('/settings/system', event);
 
 	if (!response.ok) {
 		const { message } = await response.json();
 		throw error(response.status, message || 'Failed to fetch system settings');
 	}
 
-	const settings: SystemSettings = await response.json();
+	const systemSettings: SystemSettings = await response.json();
 	return {
-		settings,
+		systemSettings,
 	};
 };
 
@@ -30,7 +30,7 @@ export const actions: Actions = {
 			supportEmail: supportEmail ? String(supportEmail) : null,
 		};
 
-		const response = await api('/settings', event, {
+		const response = await api('/settings/system', event, {
 			method: 'PUT',
 			body: JSON.stringify(body),
 		});

packages/frontend/src/routes/dashboard/settings/system/+page.svelte

@@ -11,7 +11,7 @@
 	import { t } from '$lib/translations';
 
 	let { data, form }: { data: PageData; form: any } = $props();
-	let settings = $state(data.settings);
+	let settings = $state(data.systemSettings);
 	let isSaving = $state(false);
 
 	const languageOptions: { value: SupportedLanguage; label: string }[] = [

packages/types/src/user.types.ts

@@ -35,3 +35,11 @@ export interface Role {
 	createdAt: Date;
 	updatedAt: Date;
 }
+
+export interface ApiKey {
+	id: string;
+	name: string;
+	key: string;
+	expiresAt: string;
+	createdAt: string;
+}

pnpm-lock.yaml

@@ -156,6 +156,9 @@ importers:
       yauzl:
         specifier: ^3.2.0
         version: 3.2.0
+      zod:
+        specifier: ^4.1.5
+        version: 4.1.5
     devDependencies:
       '@bull-board/api':
         specifier: ^6.11.0
@@ -4801,6 +4804,9 @@ packages:
     resolution: {integrity: sha512-zK7YHHz4ZXpW89AHXUPbQVGKI7uvkd3hzusTdotCg1UxyaVtg0zFJSTfW/Dq5f7OBBVnq6cZIaC8Ti4hb6dtCA==}
     engines: {node: '>= 14'}
 
+  zod@4.1.5:
+    resolution: {integrity: sha512-rcUUZqlLJgBC33IT3PNMgsCq6TzLQEG/Ei/KTCU0PedSWRMAXoOUN+4t/0H+Q8bdnLPdqUYnvboJT0bn/229qg==}
+
   zwitch@2.0.4:
     resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==}
 
@@ -9765,4 +9771,6 @@ snapshots:
       compress-commons: 6.0.2
       readable-stream: 4.7.0
 
+  zod@4.1.5: {}
+
   zwitch@2.0.4: {}