@rapidd/core 2.1.0

package/src/auth/stores/index.ts

@@ -0,0 +1,149 @@
+import { ISessionStore } from './ISessionStore';
+import { MemoryStore } from './MemoryStore';
+import { RedisStore } from './RedisStore';
+
+const builtInStores: Record<string, new (options?: any) => ISessionStore> = {
+    memory: MemoryStore,
+    redis: RedisStore,
+};
+
+/**
+ * Central session store manager with automatic fallback.
+ * Handles store failures transparently and switches to fallback.
+ */
+export class SessionStoreManager extends ISessionStore {
+    private ttl: number;
+    private storeName: string;
+    private healthCheckInterval: number;
+    private _primaryStore: ISessionStore | null = null;
+    private _fallbackStore: ISessionStore | null = null;
+    private _usingFallback = false;
+    private _initialized = false;
+    private _healthCheckTimer: ReturnType<typeof setInterval> | null = null;
+
+    constructor(options: { ttl?: number; store?: string; healthCheckInterval?: number } = {}) {
+        super();
+        this.ttl = options.ttl || parseInt(process.env.AUTH_SESSION_TTL || '86400', 10);
+        this.storeName = (options.store || process.env.AUTH_SESSION_STORAGE || 'redis').toLowerCase();
+        this.healthCheckInterval = options.healthCheckInterval || 30000;
+    }
+
+    private async _ensureInitialized(): Promise<void> {
+        if (this._initialized) return;
+
+        this._fallbackStore = new MemoryStore({ ttl: this.ttl });
+
+        if (this.storeName === 'memory') {
+            this._primaryStore = this._fallbackStore;
+            this._initialized = true;
+            return;
+        }
+
+        const StoreClass = builtInStores[this.storeName];
+        if (!StoreClass) {
+            console.warn(`[SessionStore] Unknown store "${this.storeName}", using memory`);
+            this._primaryStore = this._fallbackStore;
+            this._initialized = true;
+            return;
+        }
+
+        try {
+            this._primaryStore = new StoreClass({ ttl: this.ttl });
+        } catch (err) {
+            console.warn(`[SessionStore] Failed to create ${this.storeName}: ${(err as Error).message}, using memory`);
+            this._primaryStore = this._fallbackStore;
+        }
+
+        this._initialized = true;
+
+        if (this._primaryStore !== this._fallbackStore) {
+            this._startHealthCheck();
+        }
+    }
+
+    private _startHealthCheck(): void {
+        if (this._healthCheckTimer) return;
+        this._healthCheckTimer = setInterval(() => this._checkPrimaryHealth(), this.healthCheckInterval);
+    }
+
+    private async _checkPrimaryHealth(): Promise<void> {
+        try {
+            const isHealthy = await this._primaryStore!.isHealthy();
+            if (isHealthy && this._usingFallback) {
+                console.log(`[SessionStore] ${this.storeName} recovered, switching back from memory`);
+                this._usingFallback = false;
+            } else if (!isHealthy && !this._usingFallback) {
+                console.warn(`[SessionStore] ${this.storeName} unavailable, switching to memory`);
+                this._usingFallback = true;
+            }
+        } catch {
+            if (!this._usingFallback) {
+                console.warn(`[SessionStore] ${this.storeName} health check failed, switching to memory`);
+                this._usingFallback = true;
+            }
+        }
+    }
+
+    private async _execute<T>(operation: string, ...args: any[]): Promise<T> {
+        await this._ensureInitialized();
+
+        if (this._primaryStore === this._fallbackStore) {
+            return (this._primaryStore as any)[operation](...args);
+        }
+
+        if (this._usingFallback) {
+            return (this._fallbackStore as any)[operation](...args);
+        }
+
+        try {
+            return await (this._primaryStore as any)[operation](...args);
+        } catch (err) {
+            console.warn(`[SessionStore] ${this.storeName}.${operation} failed: ${(err as Error).message}, switching to memory`);
+            this._usingFallback = true;
+            return (this._fallbackStore as any)[operation](...args);
+        }
+    }
+
+    async create(sessionId: string, data: Record<string, unknown>): Promise<void> {
+        return this._execute('create', sessionId, data);
+    }
+
+    async get(sessionId: string): Promise<Record<string, unknown> | null> {
+        return this._execute('get', sessionId);
+    }
+
+    async delete(sessionId: string): Promise<void> {
+        return this._execute('delete', sessionId);
+    }
+
+    async refresh(sessionId: string): Promise<void> {
+        return this._execute('refresh', sessionId);
+    }
+
+    async isHealthy(): Promise<boolean> {
+        await this._ensureInitialized();
+        const store = this._usingFallback ? this._fallbackStore! : this._primaryStore!;
+        return store.isHealthy();
+    }
+
+    destroy(): void {
+        if (this._healthCheckTimer) {
+            clearInterval(this._healthCheckTimer);
+            this._healthCheckTimer = null;
+        }
+    }
+
+    getStatus(): { configured: string; active: string; usingFallback: boolean } {
+        return {
+            configured: this.storeName,
+            active: this._usingFallback ? 'memory' : this.storeName,
+            usingFallback: this._usingFallback,
+        };
+    }
+}
+
+export function createStore(options: { ttl?: number; store?: string } = {}): SessionStoreManager {
+    return new SessionStoreManager(options);
+}
+
+export { ISessionStore, MemoryStore, RedisStore };

package/src/config/acl.ts

@@ -0,0 +1,9 @@
+import type { AclConfig, RapiddUser } from '../types';
+
+const acl: AclConfig = {
+    model: {
+        
+    },
+};
+
+export default acl;

package/src/config/rls.ts

@@ -0,0 +1,38 @@
+import type { RlsContextFn } from '../types';
+
+/**
+ * RLS (Row-Level Security) variable mapping.
+ *
+ * Return the SQL session variables to set before each database query.
+ * Keys become variable names (e.g. `app.current_user_id`), values are set per-request.
+ * Return null for a key to skip it. Return an empty object to disable RLS.
+ *
+ * The `request` parameter is the full Fastify request object — you can read
+ * from request.user, request.headers, request.body, or any custom property.
+ *
+ * @example
+ * // User-based isolation
+ * const rlsContext: RlsContextFn = (request) => ({
+ *     current_user_id: request.user?.id ?? null,
+ *     current_user_role: request.user?.role ?? null,
+ * });
+ *
+ * @example
+ * // Multi-tenant from header
+ * const rlsContext: RlsContextFn = (request) => ({
+ *     current_tenant_id: request.headers['x-tenant-id'] ?? null,
+ * });
+ *
+ * @example
+ * // Composite: tenant + user + department
+ * const rlsContext: RlsContextFn = (request) => ({
+ *     current_user_id: request.user?.id ?? null,
+ *     current_tenant_id: request.user?.tenantId ?? null,
+ *     current_department_id: request.user?.departmentId ?? null,
+ * });
+ */
+const rlsContext: RlsContextFn = (request) => {
+    return {};
+};
+
+export default rlsContext;

package/src/core/dmmf.ts

@@ -0,0 +1,226 @@
+import fs from 'fs';
+import path from 'path';
+import type { DMMF, DMMFModel, DMMFField, RelationConfig } from '../types';
+
+let _dmmf: DMMF | null = null;
+let _dmmfPromise: Promise<DMMF> | null = null;
+
+/**
+ * Load and cache the full DMMF from the Prisma schema.
+ * Uses @prisma/internals for complete DMMF including:
+ * isId, isList, isRequired, relationFromFields, relationToFields, primaryKey
+ */
+export async function loadDMMF(): Promise<DMMF> {
+    if (_dmmf) return _dmmf;
+    if (_dmmfPromise) return _dmmfPromise;
+
+    _dmmfPromise = (async () => {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { getDMMF } = require('@prisma/internals');
+        const schemaPath = path.join(process.cwd(), 'prisma', 'schema.prisma');
+        const schema = fs.readFileSync(schemaPath, 'utf8');
+        _dmmf = await getDMMF({ datamodel: schema });
+        return _dmmf!;
+    })();
+
+    return _dmmfPromise;
+}
+
+/**
+ * Get cached DMMF synchronously (must call loadDMMF first)
+ */
+export function getDMMFSync(): DMMF | null {
+    return _dmmf;
+}
+
+/**
+ * Get a model from the DMMF by name
+ */
+export function getModel(modelName: string): DMMFModel | undefined {
+    if (!_dmmf) {
+        throw new Error('DMMF not loaded. Call loadDMMF() first.');
+    }
+    return _dmmf.datamodel.models.find((m: DMMFModel) => m.name === modelName);
+}
+
+/**
+ * Get all fields for a model (including relation fields)
+ */
+export function getFields(modelName: string): Record<string, DMMFField> {
+    const model = getModel(modelName);
+    if (!model) return {};
+    return model.fields.reduce((acc: Record<string, DMMFField>, field: DMMFField) => {
+        acc[field.name] = field;
+        return acc;
+    }, {});
+}
+
+/**
+ * Get only scalar fields for a model (excludes relation fields)
+ */
+export function getScalarFields(modelName: string): Record<string, DMMFField> {
+    const model = getModel(modelName);
+    if (!model) return {};
+    return model.fields
+        .filter((field: DMMFField) => field.kind !== 'object')
+        .reduce((acc: Record<string, DMMFField>, field: DMMFField) => {
+            acc[field.name] = field;
+            return acc;
+        }, {});
+}
+
+/**
+ * Get the primary key field(s) for a model
+ */
+export function getPrimaryKey(modelName: string): string | string[] {
+    const model = getModel(modelName);
+    if (!model) return 'id';
+
+    if (model.primaryKey?.fields && model.primaryKey.fields.length > 0) {
+        return model.primaryKey.fields.length === 1
+            ? model.primaryKey.fields[0]
+            : model.primaryKey.fields;
+    }
+
+    const idField = model.fields.find((f: DMMFField) => f.isId);
+    return idField ? idField.name : 'id';
+}
+
+/**
+ * Get all relation fields for a model
+ */
+export function getRelations(modelName: string): DMMFField[] {
+    const model = getModel(modelName);
+    if (!model) return [];
+    return model.fields.filter((f: DMMFField) => f.kind === 'object');
+}
+
+/**
+ * Check if a field is a list relation
+ */
+export function isListRelation(modelName: string, fieldName: string): boolean {
+    const model = getModel(modelName);
+    if (!model) return false;
+    const field = model.fields.find((f: DMMFField) => f.name === fieldName);
+    return field?.isList === true;
+}
+
+/**
+ * Get relationship info for a relation field
+ */
+export function getRelationInfo(
+    modelName: string,
+    relationName: string
+): { name: string; targetModel: string; isList: boolean; fromFields: string[]; toFields: string[]; onDelete?: string } | null {
+    const model = getModel(modelName);
+    if (!model) return null;
+
+    const field = model.fields.find((f: DMMFField) => f.name === relationName && f.kind === 'object');
+    if (!field) return null;
+
+    return {
+        name: field.name,
+        targetModel: field.type,
+        isList: field.isList,
+        fromFields: field.relationFromFields || [],
+        toFields: field.relationToFields || [],
+        onDelete: field.relationOnDelete as string | undefined,
+    };
+}
+
+// =====================================================
+// AUTO-DETECTION HELPERS
+// =====================================================
+
+const USER_MODEL_NAMES = ['user', 'users', 'account', 'accounts'];
+const PASSWORD_FIELD_NAMES = ['password', 'hash', 'passwordhash', 'password_hash', 'passwd', 'pwd', 'hashed_password'];
+
+/**
+ * Find a user-like model by common naming conventions
+ */
+export function findUserModel(): DMMFModel | null {
+    if (!_dmmf) return null;
+    for (const name of USER_MODEL_NAMES) {
+        const model = _dmmf.datamodel.models.find(
+            (m: DMMFModel) => m.name.toLowerCase() === name
+        );
+        if (model) return model;
+    }
+    return null;
+}
+
+/**
+ * Find unique scalar string fields suitable as login identifiers
+ */
+export function findIdentifierFields(modelName: string): string[] {
+    const fields = getScalarFields(modelName);
+    const result: string[] = [];
+
+    for (const [name, field] of Object.entries(fields)) {
+        if (field.isUnique && field.type === 'String' && !field.isId) {
+            const lower = name.toLowerCase();
+            if (!PASSWORD_FIELD_NAMES.includes(lower)) {
+                result.push(name);
+            }
+        }
+    }
+
+    return result.length > 0 ? result : ['email'];
+}
+
+/**
+ * Find the password field by common naming conventions
+ */
+export function findPasswordField(modelName: string): string | null {
+    const fields = getScalarFields(modelName);
+
+    for (const [name] of Object.entries(fields)) {
+        if (PASSWORD_FIELD_NAMES.includes(name.toLowerCase())) {
+            return name;
+        }
+    }
+
+    return null;
+}
+
+// =====================================================
+// RELATIONSHIP BUILDING
+// =====================================================
+
+/**
+ * Build relationships configuration for a model (replaces relationships.json)
+ */
+export function buildRelationships(modelName: string): RelationConfig[] {
+    const relations = getRelations(modelName);
+
+    return relations.map((rel: DMMFField) => {
+        const config: RelationConfig = {
+            name: rel.name,
+            object: rel.type,
+            isList: rel.isList,
+        };
+
+        if (rel.relationFromFields && rel.relationFromFields.length > 0) {
+            config.field = rel.relationFromFields[0];
+            config.foreignKey = rel.relationToFields?.[0] || 'id';
+
+            if (rel.relationFromFields.length > 1) {
+                config.fields = rel.relationFromFields;
+                config.foreignKeys = rel.relationToFields;
+            }
+        }
+
+        const targetRelations = getRelations(rel.type);
+        if (targetRelations.length > 0) {
+            config.relation = targetRelations.map((nested: DMMFField) => ({
+                name: nested.name,
+                object: nested.type,
+                isList: nested.isList,
+                field: nested.relationFromFields?.[0],
+                foreignKey: nested.relationToFields?.[0] || 'id',
+            }));
+        }
+
+        return config;
+    });
+}

package/src/core/env.ts

@@ -0,0 +1,183 @@
+/**
+ * Environment variable validation and access
+ * Validates required variables at startup and provides typed access
+ */
+
+export interface EnvConfig {
+    // Required
+    DATABASE_URL: string;
+
+    // Optional (auto-generated if auth is enabled)
+    JWT_SECRET?: string;
+    JWT_REFRESH_SECRET?: string;
+
+    // Optional with defaults
+    NODE_ENV: 'development' | 'production' | 'test';
+    PORT: number;
+    HOST: string;
+    DATABASE_URL_ADMIN?: string;
+    DATABASE_PROVIDER?: 'postgresql' | 'mysql';
+    COOKIE_SECRET?: string;
+    ALLOWED_ORIGINS?: string;
+
+    // Auth
+    AUTH_SESSION_STORAGE: 'redis' | 'memory';
+    AUTH_SESSION_TTL: number;
+    AUTH_SALT_ROUNDS: number;
+    AUTH_ACCESS_TOKEN_EXPIRY: string;
+    AUTH_REFRESH_TOKEN_EXPIRY: string;
+    DB_USER_TABLE: string;
+
+    // API
+    API_RESULT_LIMIT: number;
+    REQUEST_TIMEOUT: number;
+    API_MAX_RETRIES: number;
+
+    // Rate limiting
+    RATE_LIMIT_ENABLED: boolean;
+    RATE_LIMIT_WINDOW_MS: number;
+    RATE_LIMIT_MAX_REQUESTS: number;
+
+    // Redis
+    REDIS_HOST?: string;
+    REDIS_PORT: number;
+    REDIS_PASSWORD?: string;
+    REDIS_DB_RATE_LIMIT: number;
+    REDIS_DB_AUTH: number;
+
+    // RLS
+    RLS_ENABLED?: boolean;
+    RLS_NAMESPACE: string;
+
+    // Proxy
+    TRUST_PROXY?: boolean;
+}
+
+const REQUIRED_VARS = [
+    'DATABASE_URL'
+] as const;
+
+const DEFAULTS: Partial<Record<keyof EnvConfig, string | number | boolean>> = {
+    NODE_ENV: 'development',
+    PORT: 3000,
+    HOST: '0.0.0.0',
+    AUTH_SESSION_STORAGE: 'redis',
+    AUTH_SESSION_TTL: 86400,
+    AUTH_SALT_ROUNDS: 10,
+    AUTH_ACCESS_TOKEN_EXPIRY: '1d',
+    AUTH_REFRESH_TOKEN_EXPIRY: '7d',
+    DB_USER_TABLE: 'users',
+    API_RESULT_LIMIT: 500,
+    REQUEST_TIMEOUT: 10000,
+    API_MAX_RETRIES: 2,
+    RATE_LIMIT_ENABLED: true,
+    RATE_LIMIT_WINDOW_MS: 900000,
+    RATE_LIMIT_MAX_REQUESTS: 100,
+    REDIS_PORT: 6379,
+    REDIS_DB_RATE_LIMIT: 0,
+    REDIS_DB_AUTH: 1,
+    RLS_NAMESPACE: 'app'
+};
+
+/**
+ * Validate that all required environment variables are set
+ * @throws Error if required variables are missing
+ */
+export function validateEnv(): void {
+    const missing: string[] = [];
+
+    for (const key of REQUIRED_VARS) {
+        if (!process.env[key]) {
+            missing.push(key);
+        }
+    }
+
+    if (missing.length > 0) {
+        throw new Error(
+            `Missing required environment variables: ${missing.join(', ')}\n` +
+            `Please check your .env file or environment configuration.`
+        );
+    }
+
+    // Validate DATABASE_URL format
+    const dbUrl = process.env.DATABASE_URL!;
+    if (!dbUrl.startsWith('postgresql://') && !dbUrl.startsWith('postgres://') &&
+        !dbUrl.startsWith('mysql://') && !dbUrl.startsWith('mariadb://')) {
+        throw new Error(
+            `Invalid DATABASE_URL format. Must start with postgresql://, postgres://, mysql://, or mariadb://`
+        );
+    }
+}
+
+/**
+ * Get an environment variable with type coercion
+ */
+export function getEnv<K extends keyof EnvConfig>(key: K): EnvConfig[K] {
+    const value = process.env[key];
+    const defaultValue = DEFAULTS[key];
+
+    if (value === undefined || value === '') {
+        if (defaultValue !== undefined) {
+            return defaultValue as EnvConfig[K];
+        }
+        return undefined as EnvConfig[K];
+    }
+
+    // Type coercion based on default value type
+    if (typeof defaultValue === 'number') {
+        return parseInt(value, 10) as EnvConfig[K];
+    }
+    if (typeof defaultValue === 'boolean') {
+        return (value.toLowerCase() === 'true') as EnvConfig[K];
+    }
+
+    return value as EnvConfig[K];
+}
+
+/**
+ * Get all environment configuration
+ */
+export function getAllEnv(): Partial<EnvConfig> {
+    const config: Partial<EnvConfig> = {};
+
+    for (const key of Object.keys(DEFAULTS) as (keyof EnvConfig)[]) {
+        (config as any)[key] = getEnv(key);
+    }
+
+    // Add required vars
+    for (const key of REQUIRED_VARS) {
+        (config as any)[key] = process.env[key];
+    }
+
+    return config;
+}
+
+/**
+ * Check if running in production
+ */
+export function isProduction(): boolean {
+    return getEnv('NODE_ENV') === 'production';
+}
+
+/**
+ * Check if running in development
+ */
+export function isDevelopment(): boolean {
+    return getEnv('NODE_ENV') === 'development';
+}
+
+/**
+ * Check if running in test
+ */
+export function isTest(): boolean {
+    return getEnv('NODE_ENV') === 'test';
+}
+
+export default {
+    validate: validateEnv,
+    get: getEnv,
+    getAll: getAllEnv,
+    isProduction,
+    isDevelopment,
+    isTest
+};

package/src/core/errors.ts

@@ -0,0 +1,87 @@
+import { LanguageDict } from './i18n';
+
+/**
+ * Basic error response with HTTP status code
+ */
+export class ErrorBasicResponse extends Error {
+    status_code: number;
+
+    constructor(message: string, status_code: number = 500) {
+        super(message);
+        this.status_code = status_code;
+    }
+
+    toJSON(): { status_code: number; message: string } {
+        return {
+            status_code: this.status_code,
+            message: this.message,
+        };
+    }
+}
+
+/**
+ * Localized error response with i18n support via LanguageDict.
+ * Constructor takes (status_code, message_key, data?) — NOT the standard Error(message) order.
+ */
+export class ErrorResponse extends ErrorBasicResponse {
+    data: Record<string, unknown> | null;
+
+    constructor(status_code: number, message: string, data: Record<string, unknown> | null = null) {
+        super(message, status_code);
+        this.data = data;
+    }
+
+    toJSON(language: string = 'en_US'): { status_code: number; message: string } {
+        return {
+            status_code: this.status_code,
+            message: LanguageDict.get(this.message, this.data, language),
+        };
+    }
+
+    static badRequest(key: string, data: Record<string, unknown> | null = null): ErrorResponse {
+        return new ErrorResponse(400, key, data);
+    }
+
+    static unauthorized(key: string, data: Record<string, unknown> | null = null): ErrorResponse {
+        return new ErrorResponse(401, key, data);
+    }
+
+    static forbidden(key: string, data: Record<string, unknown> | null = null): ErrorResponse {
+        return new ErrorResponse(403, key, data);
+    }
+
+    static notFound(key: string, data: Record<string, unknown> | null = null): ErrorResponse {
+        return new ErrorResponse(404, key, data);
+    }
+
+    static conflict(key: string, data: Record<string, unknown> | null = null): ErrorResponse {
+        return new ErrorResponse(409, key, data);
+    }
+
+    static tooManyRequests(key: string, data: Record<string, unknown> | null = null): ErrorResponse {
+        return new ErrorResponse(429, key, data);
+    }
+}
+
+/**
+ * Success response with i18n support
+ */
+export class Response {
+    status_code: number;
+    message: string;
+    data: Record<string, unknown> | null;
+
+    constructor(status_code: number, message: string, data: Record<string, unknown> | null = null) {
+        this.status_code = status_code;
+        this.message = message;
+        this.data = data;
+    }
+
+    toJSON(language: string = 'en_US'): { status_code: number; message: string; data: Record<string, unknown> | null } {
+        return {
+            status_code: this.status_code,
+            message: LanguageDict.get(this.message, this.data, language),
+            data: this.data,
+        };
+    }
+}