@rapidd/core 2.1.0

package/src/plugins/auth.ts

@@ -0,0 +1,162 @@
+import { FastifyPluginAsync, FastifyRequest } from 'fastify';
+import fp from 'fastify-plugin';
+import { Auth } from '../auth/Auth';
+import { ErrorResponse } from '../core/errors';
+import type { RapiddUser, AuthOptions, AuthStrategy, RouteAuthConfig } from '../types';
+
+interface AuthPluginOptions {
+    auth?: Auth;
+    authOptions?: AuthOptions;
+}
+
+/**
+ * Authentication plugin for Fastify.
+ * Parses Authorization header (Basic / Bearer) and sets request.user.
+ * Registers /auth/* routes when a user table is detected.
+ * Gracefully disables auth when no user table exists in the schema.
+ */
+const authPlugin: FastifyPluginAsync<AuthPluginOptions> = async (fastify, options) => {
+    const auth = options.auth || new Auth(options.authOptions);
+
+    // Initialize auth (auto-detects user model, fields, JWT secrets)
+    await auth.initialize();
+
+    if (!auth.isEnabled()) {
+        // Auth disabled — still decorate for type safety but skip routes
+        fastify.decorate('auth', auth);
+        fastify.decorate('requireAuth', function requireAuth(_request: FastifyRequest) {
+            throw new ErrorResponse(401, 'authentication_not_available');
+        });
+        fastify.decorate('requireRole', function requireRole(..._roles: string[]) {
+            return async function (_request: FastifyRequest) {
+                throw new ErrorResponse(401, 'authentication_not_available');
+            };
+        });
+        return;
+    }
+
+    // Parse auth on every request using configured strategies (checked in order).
+    // Routes can override via config.auth: { strategies, cookieName, customHeaderName }
+    fastify.addHook('onRequest', async (request) => {
+        const routeAuth = (request.routeOptions?.config as any)?.auth as RouteAuthConfig | undefined;
+        const strategies = routeAuth?.strategies || auth.options.strategies;
+        const cookieName = routeAuth?.cookieName || auth.options.cookieName;
+        const customHeaderName = routeAuth?.customHeaderName || auth.options.customHeaderName;
+
+        let user: RapiddUser | null = null;
+
+        for (const strategy of strategies) {
+            if (user) break;
+
+            switch (strategy) {
+                case 'bearer': {
+                    const h = request.headers.authorization;
+                    if (h?.startsWith('Bearer ')) {
+                        user = await auth.handleBearerAuth(h.substring(7));
+                    }
+                    break;
+                }
+                case 'basic': {
+                    const h = request.headers.authorization;
+                    if (h?.startsWith('Basic ')) {
+                        user = await auth.handleBasicAuth(h.substring(6));
+                    }
+                    break;
+                }
+                case 'cookie': {
+                    const raw = request.cookies?.[cookieName];
+                    if (raw) {
+                        const val = typeof raw === 'object' ? (raw as any).value : raw;
+                        user = await auth.handleCookieAuth(val);
+                    }
+                    break;
+                }
+                case 'header': {
+                    const val = request.headers[customHeaderName.toLowerCase()] as string | undefined;
+                    if (val) {
+                        user = await auth.handleCustomHeaderAuth(val);
+                    }
+                    break;
+                }
+            }
+        }
+
+        if (user) {
+            request.user = user;
+        }
+    });
+
+    // Auth routes
+    fastify.post('/auth/login', async (request, reply) => {
+        const result = await auth.login(request.body as { user: string; password: string });
+
+        if (auth.options.strategies.includes('cookie')) {
+            reply.setCookie(auth.options.cookieName, result.accessToken, {
+                path: '/',
+                httpOnly: true,
+                secure: process.env.NODE_ENV === 'production',
+                sameSite: 'strict',
+                signed: !!process.env.COOKIE_SECRET,
+            });
+        }
+
+        return reply.send(result);
+    });
+
+    fastify.post('/auth/logout', async (request, reply) => {
+        const result = await auth.logout(request.headers.authorization);
+
+        if (auth.options.strategies.includes('cookie')) {
+            reply.clearCookie(auth.options.cookieName, { path: '/' });
+        }
+
+        return reply.send(result);
+    });
+
+    fastify.post('/auth/refresh', async (request, reply) => {
+        const result = await auth.refresh(request.body as { refreshToken: string });
+        return reply.send(result);
+    });
+
+    fastify.get('/auth/me', async (request, reply) => {
+        const result = await auth.me(request.user);
+        return reply.send(result);
+    });
+
+    // Expose auth instance and helpers on fastify
+    fastify.decorate('auth', auth);
+    fastify.decorate('requireAuth', function requireAuth(request: FastifyRequest) {
+        if (!request.user) {
+            throw new ErrorResponse(401, 'authentication_required');
+        }
+    });
+    fastify.decorate('requireRole', function requireRole(...roles: string[]) {
+        const allowedRoles = roles.flat().map((r: string) => r.toLowerCase());
+
+        return async function (request: FastifyRequest) {
+            if (!request.user) {
+                throw new ErrorResponse(401, 'authentication_required');
+            }
+            const userRole = (request.user.role as string)?.toLowerCase();
+            if (!userRole || !allowedRoles.includes(userRole)) {
+                throw new ErrorResponse(403, 'insufficient_permissions');
+            }
+        };
+    });
+};
+
+export default fp(authPlugin, { name: 'rapidd-auth' });
+export { Auth };
+
+// Fastify type augmentation for auth decorators
+declare module 'fastify' {
+    interface FastifyInstance {
+        auth: Auth;
+        requireAuth(request: FastifyRequest): void;
+        requireRole(...roles: string[]): (request: FastifyRequest) => Promise<void>;
+    }
+
+    interface FastifyContextConfig {
+        auth?: RouteAuthConfig;
+    }
+}

package/src/plugins/language.ts

@@ -0,0 +1,79 @@
+import path from 'path';
+import { FastifyPluginAsync } from 'fastify';
+import fp from 'fastify-plugin';
+
+const ALLOWED_LANGUAGES: string[] = (() => {
+    try {
+        return require(path.join(process.cwd(), 'config', 'app.json')).languages || ['en_US'];
+    } catch {
+        return ['en_US'];
+    }
+})();
+
+const SUPPORTED_LANGUAGES: string[] = (() => {
+    try {
+        const fs = require('fs');
+        const path = require('path');
+        const stringsPath = process.env.STRINGS_PATH || './locales';
+        return fs.readdirSync(stringsPath).map((e: string) => path.parse(e).name);
+    } catch {
+        return ['en_US'];
+    }
+})();
+
+/**
+ * Parse Accept-Language header and return the best matching language
+ */
+function resolveLanguage(headerValue: string): string {
+    const defaultLang = ALLOWED_LANGUAGES.find((allowed: string) =>
+        SUPPORTED_LANGUAGES.find((avail: string) => avail.toLowerCase() === allowed.toLowerCase())
+    ) || 'en_US';
+
+    if (!headerValue || typeof headerValue !== 'string') return defaultLang;
+
+    try {
+        const languages = headerValue
+            .toLowerCase()
+            .split(',')
+            .map((lang: string) => {
+                const parts = lang.trim().split(';');
+                const code = parts[0].trim();
+                const quality = parts[1] ? parseFloat(parts[1].replace('q=', '')) : 1.0;
+                return { code, quality };
+            })
+            .sort((a, b) => b.quality - a.quality);
+
+        // Exact match
+        for (const lang of languages) {
+            const match = ALLOWED_LANGUAGES.find((a: string) => a.toLowerCase() === lang.code);
+            if (match) return match;
+        }
+
+        // Language family match (e.g. "en-GB" → "en_US")
+        for (const lang of languages) {
+            const prefix = lang.code.split('-')[0];
+            const match = ALLOWED_LANGUAGES.find((a: string) => a.toLowerCase().startsWith(prefix + '-'));
+            if (match) return match;
+        }
+    } catch {
+        /* fall through to default */
+    }
+
+    return defaultLang;
+}
+
+/**
+ * Language resolution plugin.
+ * Sets request.language based on cookie or Accept-Language header.
+ */
+const languagePlugin: FastifyPluginAsync = async (fastify) => {
+    fastify.decorateRequest('language', 'en_US');
+
+    fastify.addHook('onRequest', async (request) => {
+        const cookieLang = (request as any).cookies?.['lang'];
+        request.language = cookieLang || resolveLanguage(request.headers['accept-language'] || '');
+    });
+};
+
+export default fp(languagePlugin, { name: 'rapidd-language' });
+export { resolveLanguage, ALLOWED_LANGUAGES };

package/src/plugins/rateLimit.ts

@@ -0,0 +1,210 @@
+import { FastifyPluginAsync, FastifyRequest, FastifyReply } from 'fastify';
+import fp from 'fastify-plugin';
+import Redis from 'ioredis';
+import { ErrorResponse } from '../core/errors';
+import type { RateLimitPathConfig, RateLimitResult } from '../types';
+
+const REDIS_MAX_TIMEOUT = 1000 * 10;
+const REDIS_MAX_RETRIES = 60;
+
+interface RateLimiterOptions {
+    windowMs?: number;
+    maxRequests?: number;
+    configPath?: string;
+}
+
+class RateLimiter {
+    private useRedis: boolean;
+    private defaultWindowMs: number;
+    private defaultMaxRequests: number;
+    private rateLimits: Record<string, RateLimitPathConfig>;
+    private redis: Redis | null = null;
+    private requests: Map<string, { count: number; resetTime: number }> | null = null;
+
+    constructor() {
+        this.useRedis = !!process.env.REDIS_HOST;
+        this.defaultWindowMs = Number(process.env.RATE_LIMIT_WINDOW_MS) || 15 * 60 * 1000;
+        this.defaultMaxRequests = Number(process.env.RATE_LIMIT_MAX_REQUESTS) || 100;
+
+        try {
+            const path = require('path');
+            this.rateLimits = require(path.join(process.cwd(), 'config', 'rate-limit.json'));
+        } catch {
+            this.rateLimits = {};
+        }
+
+        if (this.useRedis) {
+            this.redis = new Redis({
+                host: process.env.REDIS_HOST || 'localhost',
+                port: Number(process.env.REDIS_PORT || 6379),
+                db: Number(process.env.REDIS_DB_RATE_LIMIT || 0),
+                lazyConnect: true,
+                connectTimeout: 1000,
+                retryStrategy: (times: number) => {
+                    if (times <= REDIS_MAX_RETRIES) {
+                        return Math.min(times * 1000, REDIS_MAX_TIMEOUT);
+                    }
+                    this.redis?.quit();
+                    this.fallbackToMemory();
+                    return null;
+                },
+                maxRetriesPerRequest: 3,
+            });
+
+            this.redis.on('connect', () => {
+                this.useRedis = true;
+            });
+
+            this.redis.connect().catch(() => {
+                this.fallbackToMemory();
+            });
+
+            this.redis.on('error', () => {
+                this.fallbackToMemory();
+            });
+        } else {
+            this.fallbackToMemory();
+        }
+    }
+
+    private getPathConfig(reqPath: string): RateLimitPathConfig {
+        return this.rateLimits[reqPath] || {
+            maxRequests: this.defaultMaxRequests,
+            windowMs: this.defaultWindowMs,
+            ignoreSuccessfulRequests: false,
+        };
+    }
+
+    private fallbackToMemory(): void {
+        this.useRedis = false;
+        if (!this.requests) this.requests = new Map();
+    }
+
+    private isRedisAvailable(): boolean {
+        return this.useRedis && this.redis !== null && this.redis.status === 'ready';
+    }
+
+    private setRateLimitHeaders(reply: FastifyReply, max: number, count: number, reset: number): void {
+        reply.header('X-RateLimit-Limit', max);
+        reply.header('X-RateLimit-Remaining', Math.max(0, max - count));
+        reply.header('X-RateLimit-Reset', reset);
+    }
+
+    async checkLimit(request: FastifyRequest, reply: FastifyReply): Promise<void> {
+        const reqPath = request.url.split('?')[0];
+        const pathConfig = this.getPathConfig(reqPath);
+        const key = `${request.ip} - ${reqPath}`;
+        const now = Date.now();
+
+        const windowMs = pathConfig.windowMs || this.defaultWindowMs;
+        const maxRequests = pathConfig.maxRequests || this.defaultMaxRequests;
+
+        let result: RateLimitResult;
+
+        if (this.isRedisAvailable()) {
+            result = await this.checkRateLimitRedis(key, windowMs, maxRequests, now);
+        } else {
+            result = this.checkRateLimitMemory(key, windowMs, maxRequests, now);
+        }
+
+        this.setRateLimitHeaders(reply, maxRequests, result.count, result.resetTime);
+
+        if (!result.allowed) {
+            throw new ErrorResponse(429, 'rate_limit_exceeded');
+        }
+    }
+
+    private async checkRateLimitRedis(
+        key: string, windowMs: number, maxRequests: number, now: number
+    ): Promise<RateLimitResult> {
+        const redisKey = `rate_limit:${key}`;
+        const windowStart = now - windowMs;
+
+        const luaScript = `
+            local key = KEYS[1]
+            local window_start = tonumber(ARGV[1])
+            local max_requests = tonumber(ARGV[2])
+            local now = tonumber(ARGV[3])
+            local window_ms = tonumber(ARGV[4])
+            redis.call('ZREMRANGEBYSCORE', key, 0, window_start)
+            local current_count = redis.call('ZCARD', key)
+            if current_count >= max_requests then
+                local reset_time = redis.call('ZRANGE', key, 0, 0, 'WITHSCORES')
+                local oldest_time = tonumber(reset_time[2]) or now
+                return {0, current_count, oldest_time + window_ms}
+            else
+                redis.call('ZADD', key, now, tostring(now) .. ":" .. redis.call('INCR', key .. ":seq"))
+                redis.call('EXPIRE', key, math.ceil(window_ms / 1000))
+                return {1, current_count + 1, now + window_ms}
+            end
+        `;
+
+        const result = await this.redis!.eval(luaScript, 1, redisKey, windowStart, maxRequests, now, windowMs) as number[];
+        return { allowed: result[0] === 1, count: result[1], resetTime: result[2] };
+    }
+
+    private checkRateLimitMemory(
+        key: string, windowMs: number, maxRequests: number, now: number
+    ): RateLimitResult {
+        this.cleanup(now);
+        const userData = this.requests!.get(key);
+
+        if (!userData) {
+            this.requests!.set(key, { count: 1, resetTime: now + windowMs });
+            return { allowed: true, count: 1, resetTime: now + windowMs };
+        }
+
+        if (now > userData.resetTime) {
+            userData.count = 1;
+            userData.resetTime = now + windowMs;
+            return { allowed: true, count: 1, resetTime: userData.resetTime };
+        }
+
+        if (userData.count >= maxRequests) {
+            return { allowed: false, count: userData.count, resetTime: userData.resetTime };
+        }
+
+        userData.count++;
+        return { allowed: true, count: userData.count, resetTime: userData.resetTime };
+    }
+
+    private cleanup(now: number): void {
+        if (!this.requests) return;
+        for (const [key, value] of this.requests.entries()) {
+            if (now > value.resetTime) {
+                this.requests.delete(key);
+            }
+        }
+    }
+
+    async close(): Promise<void> {
+        if (this.redis) {
+            await this.redis.quit();
+        }
+    }
+}
+
+let globalRateLimiter: RateLimiter | null = null;
+
+function getRateLimiter(): RateLimiter {
+    if (!globalRateLimiter) {
+        globalRateLimiter = new RateLimiter();
+    }
+    return globalRateLimiter;
+}
+
+const rateLimiterPlugin: FastifyPluginAsync<RateLimiterOptions> = async (fastify) => {
+    const limiter = getRateLimiter();
+
+    fastify.addHook('onRequest', async (request, reply) => {
+        if (process.env.NODE_ENV !== 'production') return;
+        await limiter.checkLimit(request, reply);
+    });
+
+    fastify.addHook('onClose', async () => {
+        await limiter.close();
+    });
+};
+
+export default fp(rateLimiterPlugin, { name: 'rapidd-rate-limiter' });
+export { RateLimiter, getRateLimiter };

package/src/plugins/response.ts

@@ -0,0 +1,80 @@
+import { FastifyPluginAsync, FastifyReply, FastifyRequest } from 'fastify';
+import fp from 'fastify-plugin';
+import { ErrorResponse, ErrorBasicResponse } from '../core/errors';
+import { LanguageDict } from '../core/i18n';
+import type { ListMeta } from '../types';
+
+/**
+ * API utilities plugin.
+ * Decorates reply with sendList, sendError, sendResponse.
+ * Decorates request with getTranslation.
+ * Registers a global error handler for ErrorResponse.
+ */
+const responsePlugin: FastifyPluginAsync = async (fastify) => {
+    // Decorate request
+    fastify.decorateRequest('user', null);
+    fastify.decorateRequest('remoteAddress', '');
+    fastify.decorateRequest('getTranslation', function (this: FastifyRequest, key: string, data?: Record<string, unknown> | null, language?: string) {
+        return LanguageDict.get(key, data ?? null, language || this.language || 'en_US');
+    });
+
+    // Decorate reply
+    fastify.decorateReply('sendList', function (this: FastifyReply, data: unknown[], meta: ListMeta) {
+        const body = {
+            data,
+            meta: {
+                ...(meta.total != null ? { total: meta.total } : {}),
+                count: (data as unknown[]).length,
+                limit: meta.take,
+                offset: meta.skip,
+                ...(meta.total != null ? { hasMore: meta.skip + meta.take < meta.total } : {}),
+            },
+        };
+        return this.send(body);
+    });
+
+    fastify.decorateReply('sendError', function (this: FastifyReply, statusCode: number, message: string, data?: unknown) {
+        const request = this.request;
+        const language = request?.language || 'en_US';
+        const error = new ErrorResponse(statusCode, message, data as Record<string, unknown> | null);
+        console.error(`Error ${statusCode}: ${message}`);
+        return this.code(statusCode).send(error.toJSON(language));
+    });
+
+    fastify.decorateReply('sendResponse', function (this: FastifyReply, statusCode: number, message: string, params?: unknown) {
+        const request = this.request;
+        const language = request?.language || 'en_US';
+        const translatedMessage = LanguageDict.get(message, params as Record<string, unknown> | null, language);
+        return this.code(statusCode).send({ status_code: statusCode, message: translatedMessage });
+    });
+
+    // Set remote address (Fastify resolves X-Forwarded-For when trustProxy is enabled)
+    fastify.addHook('onRequest', async (request) => {
+        request.remoteAddress = request.ip;
+    });
+
+    // Global error handler
+    fastify.setErrorHandler((error, request, reply) => {
+        const language = request.language || 'en_US';
+        const status = (error as any).status_code || (error as any).statusCode || 500;
+
+        if (error instanceof ErrorResponse) {
+            return reply.code(status).send(error.toJSON(language));
+        }
+
+        if (error instanceof ErrorBasicResponse) {
+            return reply.code(status).send(error.toJSON());
+        }
+
+        const err = error as Error;
+        const message =
+            Object.getPrototypeOf(err).constructor === Error && process.env.NODE_ENV === 'production'
+                ? 'Something went wrong'
+                : err.message || String(error);
+
+        console.error(error);
+        return reply.code(status).send({ status_code: status, message });
+    });
+};
+
+export default fp(responsePlugin, { name: 'rapidd-response' });

package/src/plugins/rls.ts

@@ -0,0 +1,51 @@
+import { FastifyPluginAsync } from 'fastify';
+import fp from 'fastify-plugin';
+import { requestContext, rlsEnabled } from '../core/prisma';
+import rlsContextFn from '../config/rls';
+import type { RLSVariables } from '../types';
+
+/**
+ * RLS (Row-Level Security) context plugin.
+ * Calls the user-defined rlsContext() function from src/config/rls.ts
+ * to build SQL session variables, then stores them in AsyncLocalStorage
+ * so that Prisma's $allOperations extension can inject them per-query.
+ *
+ * MUST be registered AFTER the auth plugin so that request.user is available.
+ * Skips entirely when RLS is disabled (auto: off for MySQL, on for PostgreSQL).
+ *
+ * Uses callback-style hook to preserve AsyncLocalStorage context
+ * across the entire request lifecycle (preHandler → handler → onSend).
+ */
+const rlsPlugin: FastifyPluginAsync = async (fastify) => {
+    if (!rlsEnabled) return;
+
+    fastify.addHook('preHandler', (request, _reply, done) => {
+        const result = rlsContextFn(request);
+
+        if (result instanceof Promise) {
+            result.then((variables) => {
+                runWithContext(variables, done);
+            }).catch(done);
+        } else {
+            runWithContext(result, done);
+        }
+    });
+};
+
+function runWithContext(variables: RLSVariables, done: () => void): void {
+    // Filter out null/undefined values
+    const filtered: RLSVariables = {};
+    for (const [key, value] of Object.entries(variables)) {
+        if (value !== null && value !== undefined) {
+            filtered[key] = value;
+        }
+    }
+
+    if (Object.keys(filtered).length > 0) {
+        requestContext.run({ variables: filtered }, () => done());
+    } else {
+        done();
+    }
+}
+
+export default fp(rlsPlugin, { name: 'rapidd-rls' });

package/src/plugins/security.ts

@@ -0,0 +1,23 @@
+import { FastifyPluginAsync } from 'fastify';
+import fp from 'fastify-plugin';
+
+const NODE_ENV = process.env.NODE_ENV;
+
+/**
+ * Security headers plugin for API-only servers.
+ * Sets strict security headers optimized for JSON API responses.
+ */
+const securityPlugin: FastifyPluginAsync = async (fastify) => {
+    fastify.addHook('onSend', async (_request, reply) => {
+        reply.header('X-Content-Type-Options', 'nosniff');
+        reply.header('Referrer-Policy', 'strict-origin-when-cross-origin');
+        reply.header('Content-Security-Policy', "default-src 'none'; frame-ancestors 'none'");
+        reply.header('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
+
+        if (NODE_ENV === 'production') {
+            reply.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+        }
+    });
+};
+
+export default fp(securityPlugin, { name: 'rapidd-security' });