+
+ {selectedEndpoint.method}
+
+
+ )}
+
+ {/* Request bar */}
+ {selectedEndpoint.path}
+ {' — '}
+ {selectedEndpoint.description}
+ {selectedEndpoint.auth && (
+
+
+
-
+
+
+ setUrl(e.target.value)}
+ placeholder="/api/endpoint"
+ className="flex-1 px-3 py-2 rounded bg-gray-800 border border-gray-700 text-sm focus:outline-none focus:ring-1 focus:ring-indigo-500 font-mono"
+ />
+
+
+
+
+ {/* Auth token */}
+
+
-
+ )}
- {/* Response Panel */}
- {response && (
-
-
+ {/* Request body */}
+ {method !== 'GET' && (
+
-
+ setHeaders(value || '{}')}
+ value={body}
+ onChange={v => setBody(v ?? '{}')}
theme="vs-dark"
- options={{ minimap: { enabled: false } }}
+ options={{ minimap: { enabled: false }, fontSize: 12, lineNumbers: 'off', scrollBeyondLastLine: false }}
/>
-
- {method !== 'GET' && (
-
+ Request Body (JSON)
+
-
- setBody(value || '{}')}
- theme="vs-dark"
- options={{ minimap: { enabled: false } }}
- />
-
- )}
-
- = {
+ green: 'bg-green-900/40 text-green-300 border-green-800',
+ yellow: 'bg-yellow-900/40 text-yellow-300 border-yellow-800',
+ red: 'bg-red-900/40 text-red-300 border-red-800',
+ blue: 'bg-blue-900/40 text-blue-300 border-blue-800',
+ gray: 'bg-gray-800 text-gray-300 border-gray-700',
+ };
+ return (
+
+ {children}
+
+ );
+}
+
+function Collapsible({ title, children }: { title: string; children: React.ReactNode }) {
+ const [open, setOpen] = useState(false);
+ return (
+ ;
+ let res: Partial;
+ let next: NextFunction;
+ let jsonMock: jest.Mock;
+
+ beforeEach(() => {
+ jsonMock = jest.fn();
+ req = {
+ body: {},
+ query: {},
+ params: {}
+ };
+ res = {
+ status: jest.fn(() => ({ json: jsonMock })),
+ };
+ next = jest.fn();
+ });
+
+ it('should detect XSS attempts with script tags', () => {
+ req.body = {
+ name: ''
+ };
+
+ detectSuspiciousPatterns(req as Request, res as Response, next);
+
+ expect(res.status).toHaveBeenCalledWith(403);
+ expect(jsonMock).toHaveBeenCalled();
+ });
+
+ it('should detect SQL injection attempts', () => {
+ req.body = {
+ id: "1' OR '1'='1"
+ };
+
+ detectSuspiciousPatterns(req as Request, res as Response, next);
+
+ expect(res.status).toHaveBeenCalledWith(403);
+ });
+
+ it('should detect NoSQL injection attempts', () => {
+ req.body = {
+ $gt: 0
+ };
+
+ detectSuspiciousPatterns(req as Request, res as Response, next);
+
+ expect(res.status).toHaveBeenCalledWith(403);
+ });
+
+ it('should let normal requests pass', () => {
+ req.body = {
+ name: 'John Doe',
+ email: 'john@example.com'
+ };
+
+ detectSuspiciousPatterns(req as Request, res as Response, next);
+
+ expect(next).toHaveBeenCalled();
+ });
+ });
+
+ describe('sanitizeInput', () => {
+ let req: Partial;
+ let res: Partial;
+ let next: NextFunction;
+
+ beforeEach(() => {
+ req = {
+ body: {},
+ query: {},
+ params: {}
+ };
+ res = {};
+ next = jest.fn();
+ });
+
+ it('should strip HTML tags', () => {
+ req.body = {
+ name: 'John Doe',
+ bio: 'Hello'
+ };
+
+ sanitizeInput(req as Request, res as Response, next);
+
+ expect(req.body.name).not.toContain('');
+ expect(req.body.bio).not.toContain('
-
-
);
diff --git a/backend/portal/src/components/Playground/EndpointList.tsx b/backend/portal/src/components/Playground/EndpointList.tsx
new file mode 100644
index 00000000..e69de29b
diff --git a/backend/portal/src/components/Playground/RequestBuilder.tsx b/backend/portal/src/components/Playground/RequestBuilder.tsx
new file mode 100644
index 00000000..e69de29b
diff --git a/backend/portal/src/components/Playground/ResponseViewer.tsx b/backend/portal/src/components/Playground/ResponseViewer.tsx
new file mode 100644
index 00000000..e69de29b
diff --git a/backend/portal/src/pages/auth-docs.tsx b/backend/portal/src/pages/auth-docs.tsx
new file mode 100644
index 00000000..dac81322
--- /dev/null
+++ b/backend/portal/src/pages/auth-docs.tsx
@@ -0,0 +1,412 @@
+'use client';
+
+import { useState } from 'react';
+import { Lock, Key, RefreshCw, Shield, ChevronDown, ChevronRight, Copy, Check } from 'lucide-react';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+interface Section {
+ id: string;
+ title: string;
+ icon: React.ReactNode;
+}
+
+const SECTIONS: Section[] = [
+ { id: 'overview', title: 'Overview', icon: Response
- + {/* Response */} + {response && ( +
+
-
-
+
+ Response
+ {response.status && (
+
+ {response.status}
+
+ )}
+
+
+
+
-
Generate Code:
+ {/* Code snippet */} +
+
+
- )}
+
- {['javascript', 'python', 'curl'].map((lang) => (
+ {(['javascript', 'python', 'curl'] as const).map(lang => (
))}
+
+
+ );
+}
+
+function Badge({ children, color = 'gray' }: { children: React.ReactNode; color?: string }) {
+ const colors: Record
+ {language}
+
+
+
+ {code}
+
+
+
+ {open &&
+ );
+}
+
+// ─── Page ─────────────────────────────────────────────────────────────────────
+
+export default function AuthDocsPage() {
+ const [activeSection, setActiveSection] = useState('overview');
+
+ const scrollTo = (id: string) => {
+ setActiveSection(id);
+ document.getElementById(id)?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+ };
+
+ return (
+ {children}
}
+
+ {/* Header */}
+
+
+
+
+ );
+}
diff --git a/backend/scripts/smoke-test.mjs b/backend/scripts/smoke-test.mjs
new file mode 100644
index 00000000..d773cd07
--- /dev/null
+++ b/backend/scripts/smoke-test.mjs
@@ -0,0 +1,107 @@
+// Post-deploy smoke test for the AetherMint backend.
+// Dependency-free Node ESM script. Run with: node scripts/smoke-test.mjs
+//
+// Environment variables:
+// SMOKE_BASE_URL Base URL to test (falls back to BASE_URL, then http://localhost:3001)
+// SMOKE_TIMEOUT_MS Per-request timeout in milliseconds (default 5000)
+
+const BASE_URL =
+ process.env.SMOKE_BASE_URL ||
+ process.env.BASE_URL ||
+ "http://localhost:3001";
+
+const TIMEOUT_MS = Number(process.env.SMOKE_TIMEOUT_MS) || 5000;
+
+async function request(path) {
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+ const started = Date.now();
+ try {
+ const response = await fetch(BASE_URL + path, {
+ signal: controller.signal,
+ headers: { accept: "application/json" },
+ });
+ const latencyMs = Date.now() - started;
+ const contentType = response.headers.get("content-type") || "";
+ const isJson = contentType.includes("application/json");
+ const body = isJson ? await response.json() : await response.text();
+ return { status: response.status, contentType, body, latencyMs };
+ } finally {
+ clearTimeout(timer);
+ }
+}
+
+const checks = [
+ {
+ name: "GET /api/health returns healthy",
+ run: async () => {
+ const res = await request("/api/health");
+ if (res.status !== 200) {
+ throw new Error("expected status 200 but got " + res.status);
+ }
+ if (!res.body || res.body.status !== "healthy") {
+ throw new Error("expected body status to be healthy");
+ }
+ return res.latencyMs;
+ },
+ },
+ {
+ name: "GET / returns running",
+ run: async () => {
+ const res = await request("/");
+ if (res.status !== 200) {
+ throw new Error("expected status 200 but got " + res.status);
+ }
+ if (!res.body || res.body.status !== "running") {
+ throw new Error("expected body status to be running");
+ }
+ return res.latencyMs;
+ },
+ },
+ {
+ name: "GET /api/docs/json returns OpenAPI JSON",
+ run: async () => {
+ const res = await request("/api/docs/json");
+ if (res.status !== 200) {
+ throw new Error("expected status 200 but got " + res.status);
+ }
+ if (!res.contentType.includes("application/json")) {
+ throw new Error("expected an application/json content type");
+ }
+ return res.latencyMs;
+ },
+ },
+];
+
+async function main() {
+ console.log("Smoke test target: " + BASE_URL);
+ console.log("Per-request timeout: " + TIMEOUT_MS + "ms");
+ console.log("");
+
+ let failures = 0;
+ for (const check of checks) {
+ try {
+ const latencyMs = await check.run();
+ console.log("PASS " + check.name + " (" + latencyMs + "ms)");
+ } catch (error) {
+ failures = failures + 1;
+ const message = error && error.message ? error.message : String(error);
+ console.log("FAIL " + check.name + " -> " + message);
+ }
+ }
+
+ console.log("");
+ const total = checks.length;
+ const passed = total - failures;
+ console.log("Summary: " + passed + "/" + total + " checks passed");
+
+ if (failures > 0) {
+ process.exit(1);
+ }
+}
+
+main().catch((error) => {
+ const message = error && error.message ? error.message : String(error);
+ console.error("Smoke test crashed: " + message);
+ process.exit(1);
+});
\ No newline at end of file
diff --git a/backend/src/__tests__/auditService.test.ts b/backend/src/__tests__/auditService.test.ts
new file mode 100644
index 00000000..a78b7a13
--- /dev/null
+++ b/backend/src/__tests__/auditService.test.ts
@@ -0,0 +1,44 @@
+import { AuditAction } from '../models/AuditLog';
+import { auditService } from '../services/auditService';
+
+describe('AuditService', () => {
+ describe('create', () => {
+ it('should create an audit log entry with success result', async () => {
+ await auditService.create('test-user', AuditAction.USER_ROLE_CHANGE, 'user', {
+ resourceId: 'userId-123',
+ details: { role: 'admin' },
+ ipAddress: '127.0.0.1',
+ });
+ });
+ });
+
+ describe('query', () => {
+ it('should return paginated results structure', async () => {
+ const result = await auditService.query({ actor: 'test-user' });
+ expect(result).toHaveProperty('entries');
+ expect(result).toHaveProperty('total');
+ expect(result).toHaveProperty('page');
+ expect(result).toHaveProperty('totalPages');
+ });
+
+ it('should filter by date range', async () => {
+ const dateFrom = new Date('2024-01-01');
+ const dateTo = new Date('2024-12-31');
+
+ const result = await auditService.query({ dateFrom, dateTo });
+ expect(result).toHaveProperty('entries');
+ });
+ });
+
+ describe('getStatistics', () => {
+ it('should return statistics for audit logs', async () => {
+ const result = await auditService.getStatistics();
+
+ expect(result).toHaveProperty('totalEntries');
+ expect(result).toHaveProperty('successCount');
+ expect(result).toHaveProperty('failureCount');
+ expect(result).toHaveProperty('actionCounts');
+ expect(result).toHaveProperty('topActors');
+ });
+ });
+});
\ No newline at end of file
diff --git a/backend/src/__tests__/cache.test.ts b/backend/src/__tests__/cache.test.ts
new file mode 100644
index 00000000..d5f1b7c4
--- /dev/null
+++ b/backend/src/__tests__/cache.test.ts
@@ -0,0 +1,224 @@
+// Isolate test from index.ts compilation errors
+jest.mock('../utils/migrate', () => ({
+ Migrator: jest.fn(),
+}));
+
+import * as cache from '../utils/cache';
+import { CacheKeys, CacheTTL } from '../utils/cache';
+
+// Mock redis config
+jest.mock('../config/redis');
+jest.mock('../utils/logger', () => {
+ const mock = {
+ debug: jest.fn(),
+ info: jest.fn(),
+ warn: jest.fn(),
+ error: jest.fn(),
+ };
+ return { default: mock, ...mock };
+});
+
+import * as cache from '../utils/cache';
+import { CacheKeys, CacheTTL } from '../utils/cache';
+import redisConfig from '../config/redis';
+
+const mockRedisClient = {
+ get: jest.fn(),
+ set: jest.fn(),
+ del: jest.fn(),
+ keys: jest.fn(),
+};
+
+beforeAll(() => {
+ (redisConfig.getRawClient as jest.Mock).mockReturnValue(mockRedisClient);
+});
+
+describe('Cache Utility', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ describe('get()', () => {
+ it('returns parsed value on cache hit', async () => {
+ mockRedisClient.get.mockResolvedValueOnce(JSON.stringify({ id: '1', name: 'Test' }));
+
+ const result = await cache.get<{ id: string; name: string }>('test:key');
+
+ expect(result).toEqual({ id: '1', name: 'Test' });
+ expect(mockRedisClient.get).toHaveBeenCalledWith('test:key');
+ });
+
+ it('returns null on cache miss', async () => {
+ mockRedisClient.get.mockResolvedValueOnce(null);
+
+ const result = await cache.get('test:missing');
+
+ expect(result).toBeNull();
+ });
+
+ it('returns null when bypass is true', async () => {
+ const result = await cache.get('test:key', true);
+
+ expect(result).toBeNull();
+ expect(mockRedisClient.get).not.toHaveBeenCalled();
+ });
+
+ it('returns null when redis is unavailable', async () => {
+ jest.spyOn(require('../config/redis').default, 'getRawClient').mockReturnValueOnce(null);
+
+ const result = await cache.get('test:key');
+ expect(result).toBeNull();
+ });
+
+ it('returns null on redis error', async () => {
+ mockRedisClient.get.mockRejectedValueOnce(new Error('Connection error'));
+
+ const result = await cache.get('test:key');
+ expect(result).toBeNull();
+ });
+ });
+
+ describe('set()', () => {
+ it('sets value with default TTL', async () => {
+ mockRedisClient.set.mockResolvedValueOnce('OK');
+
+ await cache.set('test:key', { data: 'value' });
+
+ expect(mockRedisClient.set).toHaveBeenCalledWith(
+ 'test:key',
+ JSON.stringify({ data: 'value' }),
+ 'EX',
+ 300,
+ );
+ });
+
+ it('sets value with custom TTL', async () => {
+ mockRedisClient.set.mockResolvedValueOnce('OK');
+
+ await cache.set('test:key', { data: 'value' }, 3600);
+
+ expect(mockRedisClient.set).toHaveBeenCalledWith(
+ 'test:key',
+ JSON.stringify({ data: 'value' }),
+ 'EX',
+ 3600,
+ );
+ });
+
+ it('handles redis error gracefully', async () => {
+ mockRedisClient.set.mockRejectedValueOnce(new Error('Redis error'));
+
+ await expect(cache.set('test:key', 'value')).resolves.not.toThrow();
+ });
+ });
+
+ describe('del()', () => {
+ it('deletes a cache key', async () => {
+ mockRedisClient.del.mockResolvedValueOnce(1);
+
+ await cache.del('test:key');
+
+ expect(mockRedisClient.del).toHaveBeenCalledWith('test:key');
+ });
+
+ it('handles redis error gracefully', async () => {
+ mockRedisClient.del.mockRejectedValueOnce(new Error('Redis error'));
+
+ await expect(cache.del('test:key')).resolves.not.toThrow();
+ });
+ });
+
+ describe('invalidatePattern()', () => {
+ it('deletes all keys matching pattern', async () => {
+ mockRedisClient.keys.mockResolvedValueOnce(['course:1', 'course:2', 'course:3']);
+ mockRedisClient.del.mockResolvedValueOnce(3);
+
+ await cache.invalidatePattern('course:*');
+
+ expect(mockRedisClient.keys).toHaveBeenCalledWith('course:*');
+ expect(mockRedisClient.del).toHaveBeenCalledWith('course:1', 'course:2', 'course:3');
+ });
+
+ it('does nothing when no keys match', async () => {
+ mockRedisClient.keys.mockResolvedValueOnce([]);
+
+ await cache.invalidatePattern('empty:*');
+
+ expect(mockRedisClient.del).not.toHaveBeenCalled();
+ });
+
+ it('handles redis error gracefully', async () => {
+ mockRedisClient.keys.mockRejectedValueOnce(new Error('Redis error'));
+
+ await expect(cache.invalidatePattern('test:*')).resolves.not.toThrow();
+ });
+ });
+
+ describe('getOrSet()', () => {
+ it('returns cached value without calling loader', async () => {
+ mockRedisClient.get.mockResolvedValueOnce(JSON.stringify({ cached: true }));
+ const loader = jest.fn();
+
+ const result = await cache.getOrSet('test:key', loader);
+
+ expect(result).toEqual({ cached: true });
+ expect(loader).not.toHaveBeenCalled();
+ });
+
+ it('calls loader and caches result on miss', async () => {
+ mockRedisClient.get.mockResolvedValueOnce(null);
+ mockRedisClient.set.mockResolvedValueOnce('OK');
+ const loader = jest.fn().mockResolvedValueOnce({ fresh: true });
+
+ const result = await cache.getOrSet('test:key', loader, 600);
+
+ expect(result).toEqual({ fresh: true });
+ expect(loader).toHaveBeenCalledTimes(1);
+ expect(mockRedisClient.set).toHaveBeenCalledWith(
+ 'test:key',
+ JSON.stringify({ fresh: true }),
+ 'EX',
+ 600,
+ );
+ });
+
+ it('bypasses cache and calls loader when bypass=true', async () => {
+ const loader = jest.fn().mockResolvedValueOnce({ bypass: true });
+ mockRedisClient.set.mockResolvedValueOnce('OK');
+
+ const result = await cache.getOrSet('test:key', loader, 300, true);
+
+ expect(result).toEqual({ bypass: true });
+ expect(loader).toHaveBeenCalledTimes(1);
+ expect(mockRedisClient.get).not.toHaveBeenCalled();
+ });
+ });
+
+ describe('CacheKeys', () => {
+ it('generates correct course key', () => {
+ expect(CacheKeys.course('123')).toBe('course:listing:123');
+ });
+
+ it('generates correct user key', () => {
+ expect(CacheKeys.user('user-1')).toBe('user:profile:user-1');
+ });
+
+ it('generates correct recommendation key', () => {
+ expect(CacheKeys.recommendation('user-1')).toBe('recommendation:user:user-1');
+ });
+
+ it('generates correct search key', () => {
+ const key = CacheKeys.search('machine learning');
+ expect(key).toContain('search:results:');
+ });
+ });
+
+ describe('CacheTTL', () => {
+ it('has correct TTL values', () => {
+ expect(CacheTTL.SHORT).toBe(60);
+ expect(CacheTTL.MEDIUM).toBe(300);
+ expect(CacheTTL.LONG).toBe(3600);
+ expect(CacheTTL.DAY).toBe(86400);
+ });
+ });
+});
\ No newline at end of file
diff --git a/backend/src/__tests__/rateLimiter.test.js b/backend/src/__tests__/rateLimiter.test.js
new file mode 100644
index 00000000..f123b066
--- /dev/null
+++ b/backend/src/__tests__/rateLimiter.test.js
@@ -0,0 +1,129 @@
+jest.mock('../utils/redis', () => ({
+ incrementRateLimitCounter: jest.fn(),
+ decrementRateLimitCounter: jest.fn(),
+ resetRateLimitCounter: jest.fn(),
+}));
+
+jest.mock('../services/securityService', () => ({
+ logSecurityEvent: jest.fn().mockResolvedValue(undefined),
+}));
+
+const {
+ incrementRateLimitCounter,
+} = require('../utils/redis');
+const {
+ createRateLimiter,
+ tieredRateLimiter,
+} = require('../middleware/rateLimiter');
+
+const createResponse = () => {
+ const headers = {};
+ return {
+ headers,
+ statusCode: 200,
+ body: undefined,
+ setHeader: jest.fn((name, value) => {
+ headers[name] = value;
+ }),
+ status: jest.fn(function status(code) {
+ this.statusCode = code;
+ return this;
+ }),
+ json: jest.fn(function json(body) {
+ this.body = body;
+ return this;
+ }),
+ };
+};
+
+const request = (overrides = {}) => ({
+ ip: '127.0.0.1',
+ socket: {},
+ method: 'GET',
+ path: '/resource',
+ originalUrl: '/api/resource',
+ baseUrl: '/api',
+ headers: { 'x-test-security': 'true' },
+ ...overrides,
+});
+
+describe('tiered Redis rate limiter', () => {
+ beforeEach(() => {
+ incrementRateLimitCounter.mockReset();
+ });
+
+ it('returns the standard rate limit headers for allowed requests', async () => {
+ const resetTime = new Date(Date.now() + 60_000);
+ incrementRateLimitCounter
+ .mockResolvedValueOnce({ totalHits: 1, resetTime })
+ .mockResolvedValueOnce({ totalHits: 1, resetTime });
+
+ const limiter = createRateLimiter({
+ name: 'test',
+ scope: 'ip',
+ windowMs: 60_000,
+ max: 10,
+ burstWindowMs: 10_000,
+ burstMax: 5,
+ });
+ const req = request();
+ const res = createResponse();
+ const next = jest.fn();
+
+ await limiter(req, res, next);
+
+ expect(next).toHaveBeenCalledTimes(1);
+ expect(res.headers['X-RateLimit-Limit']).toBe('10');
+ expect(res.headers['X-RateLimit-Remaining']).toBe('9');
+ expect(res.headers['X-RateLimit-Reset']).toMatch(/^\d+$/);
+ });
+
+ it('returns 429 and Retry-After when the burst allowance is exhausted', async () => {
+ const resetTime = new Date(Date.now() + 10_000);
+ incrementRateLimitCounter
+ .mockResolvedValueOnce({ totalHits: 2, resetTime })
+ .mockResolvedValueOnce({ totalHits: 6, resetTime });
+
+ const limiter = createRateLimiter({
+ name: 'test',
+ scope: 'ip',
+ windowMs: 60_000,
+ max: 10,
+ burstWindowMs: 10_000,
+ burstMax: 5,
+ message: 'Slow down.',
+ });
+ const req = request();
+ const res = createResponse();
+ const next = jest.fn();
+
+ await limiter(req, res, next);
+
+ expect(next).not.toHaveBeenCalled();
+ expect(res.statusCode).toBe(429);
+ expect(res.headers['Retry-After']).toMatch(/^\d+$/);
+ expect(res.body).toEqual(expect.objectContaining({
+ error: 'Rate limit exceeded',
+ message: 'Slow down.',
+ }));
+ });
+
+ it('applies global and authenticated-user strategies together', async () => {
+ const resetTime = new Date(Date.now() + 60_000);
+ incrementRateLimitCounter.mockResolvedValue({ totalHits: 1, resetTime });
+
+ const req = request({
+ user: { id: 'user-126', role: 'student' },
+ });
+ const res = createResponse();
+ const next = jest.fn();
+
+ await tieredRateLimiter(req, res, next);
+
+ expect(next).toHaveBeenCalledTimes(1);
+ expect(incrementRateLimitCounter).toHaveBeenCalledTimes(4);
+ const keys = incrementRateLimitCounter.mock.calls.map(([key]) => key);
+ expect(keys.some((key) => key.includes('global'))).toBe(true);
+ expect(keys.some((key) => key.includes('authenticated'))).toBe(true);
+ });
+});
diff --git a/backend/src/__tests__/requestId.test.ts b/backend/src/__tests__/requestId.test.ts
new file mode 100644
index 00000000..e6f64c54
--- /dev/null
+++ b/backend/src/__tests__/requestId.test.ts
@@ -0,0 +1,74 @@
+import { describe, it, expect } from '@jest/globals';
+import express, { type Request, type Response } from 'express';
+import request from 'supertest';
+import { v4 as uuidv4 } from 'uuid';
+import requestId, { REQUEST_ID_HEADER } from '../middleware/requestId';
+import { getRequestContext } from '../utils/requestContext';
+
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+const buildApp = () => {
+ const app = express();
+ app.use(requestId);
+ app.get('/ping', (req, res) => {
+ res.json({
+ reqId: req.requestId,
+ contextId: getRequestContext()?.requestId,
+ });
+ });
+ return app;
+};
+
+describe('requestId middleware', () => {
+ it('generates a UUID v4 when no X-Request-ID header is supplied', async () => {
+ const res = await request(buildApp()).get('/ping');
+
+ const header = res.headers[REQUEST_ID_HEADER];
+ expect(header).toMatch(UUID_V4);
+ expect(res.body.reqId).toBe(header);
+ });
+
+ it('reuses a valid UUID v4 supplied by the caller', async () => {
+ const provided = uuidv4();
+
+ const res = await request(buildApp()).get('/ping').set(REQUEST_ID_HEADER, provided);
+
+ expect(res.headers[REQUEST_ID_HEADER]).toBe(provided);
+ expect(res.body.reqId).toBe(provided);
+ });
+
+ it('discards an untrusted, non-UUID X-Request-ID and generates a fresh one', async () => {
+ const res = await request(buildApp()).get('/ping').set(REQUEST_ID_HEADER, 'abc123');
+
+ expect(res.headers[REQUEST_ID_HEADER]).not.toBe('abc123');
+ expect(res.headers[REQUEST_ID_HEADER]).toMatch(UUID_V4);
+ });
+
+ it('exposes the ID via AsyncLocalStorage for downstream async code', async () => {
+ const res = await request(buildApp()).get('/ping');
+
+ expect(res.body.contextId).toBe(res.headers[REQUEST_ID_HEADER]);
+ });
+
+ it('adds well under 1ms of overhead per request', () => {
+ const iterations = 2000;
+ const res = { setHeader: () => undefined } as unknown as Response;
+ const makeReq = () =>
+ ({
+ header: () => undefined,
+ method: 'GET',
+ originalUrl: '/bench',
+ url: '/bench',
+ path: '/bench',
+ ip: '127.0.0.1',
+ } as unknown as Request);
+
+ const start = process.hrtime.bigint();
+ for (let i = 0; i < iterations; i += 1) {
+ requestId(makeReq(), res, () => undefined);
+ }
+ const perCallMs = Number(process.hrtime.bigint() - start) / 1e6 / iterations;
+
+ expect(perCallMs).toBeLessThan(1);
+ });
+});
diff --git a/backend/src/__tests__/security.test.ts b/backend/src/__tests__/security.test.ts
new file mode 100644
index 00000000..f537d05f
--- /dev/null
+++ b/backend/src/__tests__/security.test.ts
@@ -0,0 +1,108 @@
+import { sanitizeInput, detectSuspiciousPatterns } from '../middleware/sanitizer';
+import { Request, Response, NextFunction } from 'express';
+
+describe('Security Middleware', () => {
+ describe('detectSuspiciousPatterns', () => {
+ let req: Partial
+
+
+ ← API Playground
+
+
+ {/* Sidebar */}
+
+
+ {/* Content */}
+
+
+ {/* Overview */}
+
+
+
+ {/* JWT */}
+
+
+
+
+
+ {/* API Key */}
+
+
+
+
+
+ {/* Token Refresh */}
+
+
+
+
+
+
+
+ {/* Roles */}
+
+
+
+
+
+ {/* Error codes */}
+
+
+
+
+ Authentication
+
+ AetherMint supports two authentication methods. Most client-facing endpoints use{' '}
+
+
+
+
+
+
+
+ Obtained by logging in. Passed as an{' '}
+ Authorization: Bearer <token>{' '}
+ header. Valid for 24 hours.
+
+
+
+
+
+ Static key for server-to-server use. Passed as an{' '}
+ X-API-Key: <key> header.
+ No expiry; rotate manually.
+
+
+
+ The standard flow: register or log in to receive a signed JWT, then send it with
+ every protected request in the Authorization header.
+
1. Register
+2. Login
+3. Use the token
+Python example
+
+ Security tip: Do not store JWTs in
+ localStorage in
+ production. Prefer an httpOnly cookie or in-memory store to prevent XSS theft.
+
+
+ + For backend integrations that need long-lived credentials without user sessions. + API keys are static and do not expire unless manually rotated. +
+ +
+
+
+
+
+ | Header | +Value | +Notes | +
|---|---|---|
| X-API-Key | +YOUR_API_KEY_HERE | +Obtained from the admin dashboard | +
+
+
+ JWTs are valid for 24 hours. When a token expires the API returns a{' '}
+ POST /api/auth/login to obtain a
+ new token.
+
+
+ + AetherMint uses role-based access control (RBAC). Every user has one of three roles. +
+ +
+
+
+
+
+
+ | Role | +Capabilities | +Restricted from | +
|---|---|---|
| {r.can} | +{r.cannot} | +
+ Roles are assigned at registration and can be changed by admins via{' '}
+ PUT /api/auth/assign-role/:userId.
+
Auth Error Codes
+
+ All authentication errors return a structured JSON body with a machine-readable error.code.
+
+
+
+
+
+
+ | HTTP | +Error Code | +Meaning | +
|---|---|---|
|
+ |
+ {e.code} | +{e.meaning} | +
+
+ Example error response
+{`{
+ "success": false,
+ "error": {
+ "code": "TOKEN_EXPIRED",
+ "message": "Your session has expired. Please log in again.",
+ "requestId": "req-abc-12345"
+ }
+}`}
+