@veloxts/orm 0.6.27 → 0.6.31

package/dist/tenant/schema/manager.js

@@ -0,0 +1,334 @@
+/**
+ * Tenant schema manager for PostgreSQL schema lifecycle operations
+ *
+ * Handles:
+ * - Creating tenant schemas
+ * - Running Prisma migrations per schema
+ * - Listing and deleting schemas
+ *
+ * SECURITY:
+ * - All SQL queries use parameterized queries via pg library
+ * - Prisma migrations use execFile (no shell) with validated paths
+ * - Input validation prevents injection attacks
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import pg from 'pg';
+import format from 'pg-format';
+import { InvalidSlugError, SchemaCreateError, SchemaDeleteError, SchemaListError, SchemaMigrateError, SchemaNotFoundError, } from '../errors.js';
+const { Client } = pg;
+const execFileAsync = promisify(execFile);
+/**
+ * Default configuration
+ */
+const DEFAULTS = {
+    schemaPrefix: 'tenant_',
+    prismaSchemaPath: './prisma/schema.prisma',
+};
+/**
+ * Regex for validating schema names (PostgreSQL identifier rules)
+ * Must start with letter or underscore, contain only alphanumeric and underscores
+ */
+const SCHEMA_NAME_REGEX = /^[a-z_][a-z0-9_]*$/i;
+/**
+ * Maximum schema name length (PostgreSQL limit is 63)
+ */
+const MAX_SCHEMA_NAME_LENGTH = 63;
+/**
+ * Reserved PostgreSQL schema names that cannot be used
+ */
+const RESERVED_SCHEMAS = new Set([
+    'public',
+    'pg_catalog',
+    'pg_toast',
+    'pg_temp',
+    'information_schema',
+]);
+/**
+ * Validate database URL format and check for injection patterns
+ */
+function validateDatabaseUrl(url) {
+    try {
+        const parsed = new URL(url);
+        // Only allow postgresql:// protocol
+        if (parsed.protocol !== 'postgresql:' && parsed.protocol !== 'postgres:') {
+            throw new Error('Invalid database protocol');
+        }
+        // Check for shell metacharacters
+        const DANGEROUS_CHARS = /[;|&$`<>(){}[\]!]/;
+        if (DANGEROUS_CHARS.test(url)) {
+            throw new Error('Database URL contains dangerous characters');
+        }
+    }
+    catch {
+        throw new Error('Invalid database URL format');
+    }
+}
+/**
+ * Validate Prisma schema path to prevent path traversal
+ */
+function validatePrismaSchemaPath(path) {
+    // Check for path traversal
+    if (path.includes('..') || path.includes('\0')) {
+        throw new Error('Invalid Prisma schema path: path traversal detected');
+    }
+    // Check for shell metacharacters
+    const DANGEROUS_CHARS = /[;|&$`<>(){}[\]!'"]/;
+    if (DANGEROUS_CHARS.test(path)) {
+        throw new Error('Invalid Prisma schema path: dangerous characters detected');
+    }
+    // Must end with .prisma
+    if (!path.endsWith('.prisma')) {
+        throw new Error('Invalid Prisma schema path: must end with .prisma');
+    }
+}
+/**
+ * Sanitize error messages to prevent credential leakage
+ */
+function sanitizeError(error) {
+    let message = error.message;
+    // Remove connection strings
+    message = message.replace(/postgresql:\/\/[^@]+@[^\s"']+/gi, 'postgresql://***:***@***/***');
+    // Remove passwords
+    message = message.replace(/password[=:]\s*['"]?[^'"\s]+/gi, 'password=***');
+    return new Error(message);
+}
+/**
+ * Create a tenant schema manager
+ *
+ * @example
+ * ```typescript
+ * const schemaManager = createTenantSchemaManager({
+ *   databaseUrl: process.env.DATABASE_URL!,
+ *   schemaPrefix: 'tenant_',
+ * });
+ *
+ * // Create a new schema
+ * const result = await schemaManager.createSchema('acme-corp');
+ * // result.schemaName === 'tenant_acme_corp'
+ *
+ * // Run migrations
+ * await schemaManager.migrateSchema('tenant_acme_corp');
+ * ```
+ */
+export function createTenantSchemaManager(config) {
+    // Validate configuration
+    validateDatabaseUrl(config.databaseUrl);
+    const schemaPrefix = config.schemaPrefix ?? DEFAULTS.schemaPrefix;
+    const prismaSchemaPath = config.prismaSchemaPath ?? DEFAULTS.prismaSchemaPath;
+    validatePrismaSchemaPath(prismaSchemaPath);
+    /**
+     * Create a PostgreSQL client connection
+     */
+    async function createClient() {
+        const client = new Client({ connectionString: config.databaseUrl });
+        await client.connect();
+        return client;
+    }
+    /**
+     * Execute a parameterized SQL query safely
+     */
+    async function executeSql(sql, params = []) {
+        const client = await createClient();
+        try {
+            const result = await client.query(sql, params);
+            return result.rows;
+        }
+        catch (error) {
+            throw sanitizeError(error instanceof Error ? error : new Error(String(error)));
+        }
+        finally {
+            await client.end();
+        }
+    }
+    /**
+     * Sanitize a slug to create a valid schema name
+     */
+    function slugToSchemaName(slug) {
+        // Convert to lowercase and replace hyphens with underscores
+        const sanitized = slug.toLowerCase().replace(/-/g, '_');
+        // Remove any characters that aren't alphanumeric or underscore
+        const cleaned = sanitized.replace(/[^a-z0-9_]/g, '');
+        // Ensure it starts with a letter or underscore
+        const normalized = /^[a-z_]/.test(cleaned) ? cleaned : `_${cleaned}`;
+        return `${schemaPrefix}${normalized}`;
+    }
+    /**
+     * Validate a slug with strict security checks
+     */
+    function validateSlug(slug) {
+        if (!slug || slug.trim().length === 0) {
+            throw new InvalidSlugError(slug, 'slug cannot be empty');
+        }
+        if (slug.length > 50) {
+            throw new InvalidSlugError(slug, 'slug cannot exceed 50 characters');
+        }
+        // Strict whitelist validation
+        const VALID_SLUG_REGEX = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/;
+        if (!VALID_SLUG_REGEX.test(slug)) {
+            throw new InvalidSlugError(slug, 'slug must contain only lowercase letters, numbers, and hyphens');
+        }
+        // Check for dangerous patterns
+        const DANGEROUS_PATTERNS = [
+            /[;|&$`<>]/, // Shell metacharacters
+            /['"`]/, // SQL quotes
+            /\0/, // Null bytes
+            /\.\./, // Path traversal
+            /[\\/]/, // Path separators
+        ];
+        for (const pattern of DANGEROUS_PATTERNS) {
+            if (pattern.test(slug)) {
+                throw new InvalidSlugError(slug, 'slug contains forbidden characters');
+            }
+        }
+        const schemaName = slugToSchemaName(slug);
+        if (!SCHEMA_NAME_REGEX.test(schemaName)) {
+            throw new InvalidSlugError(slug, 'results in invalid schema name');
+        }
+        if (schemaName.length > MAX_SCHEMA_NAME_LENGTH) {
+            throw new InvalidSlugError(slug, `results in schema name exceeding ${MAX_SCHEMA_NAME_LENGTH} characters`);
+        }
+        if (RESERVED_SCHEMAS.has(schemaName.toLowerCase())) {
+            throw new InvalidSlugError(slug, 'results in reserved schema name');
+        }
+    }
+    /**
+     * Validate a schema name
+     */
+    function validateSchemaName(schemaName) {
+        if (!SCHEMA_NAME_REGEX.test(schemaName)) {
+            throw new Error(`Invalid schema name: ${schemaName}`);
+        }
+        if (schemaName.length > MAX_SCHEMA_NAME_LENGTH) {
+            throw new Error(`Schema name too long: ${schemaName}`);
+        }
+        if (RESERVED_SCHEMAS.has(schemaName.toLowerCase())) {
+            throw new Error(`Cannot use reserved schema name: ${schemaName}`);
+        }
+        // Additional security checks
+        const DANGEROUS_PATTERNS = [/[;|&$`<>]/, /['"`]/, /\0/, /\.\./, /[\\/]/];
+        for (const pattern of DANGEROUS_PATTERNS) {
+            if (pattern.test(schemaName)) {
+                throw new Error(`Schema name contains forbidden characters: ${schemaName}`);
+            }
+        }
+    }
+    return {
+        /**
+         * Create a new PostgreSQL schema for a tenant
+         */
+        async createSchema(slug) {
+            validateSlug(slug);
+            const schemaName = slugToSchemaName(slug);
+            try {
+                // Check if schema already exists using parameterized query
+                const exists = await this.schemaExists(schemaName);
+                if (exists) {
+                    return { schemaName, created: false };
+                }
+                // Create the schema using pg-format for safe identifier quoting
+                // %I is the identifier placeholder that properly escapes schema names
+                const createSchemaSql = format('CREATE SCHEMA %I', schemaName);
+                await executeSql(createSchemaSql);
+                return { schemaName, created: true };
+            }
+            catch (error) {
+                throw new SchemaCreateError(schemaName, error instanceof Error ? error : new Error(String(error)));
+            }
+        },
+        /**
+         * Run Prisma migrations on a tenant schema
+         *
+         * SECURITY: Uses execFile (not exec) to prevent command injection
+         */
+        async migrateSchema(schemaName) {
+            validateSchemaName(schemaName);
+            try {
+                // Set the schema in the database URL
+                const url = new URL(config.databaseUrl);
+                url.searchParams.set('schema', schemaName);
+                const schemaUrl = url.toString();
+                // Run prisma migrate deploy using execFile (no shell interpretation)
+                // This prevents command injection via the schemaUrl or prismaSchemaPath
+                const { stdout } = await execFileAsync('npx', ['prisma', 'migrate', 'deploy', `--schema=${prismaSchemaPath}`], {
+                    env: { ...process.env, DATABASE_URL: schemaUrl },
+                    timeout: 120000, // 2 minute timeout for migrations
+                });
+                // Parse migration count from output
+                const match = stdout.match(/(\d+) migration[s]? applied/i);
+                const migrationsApplied = match ? Number.parseInt(match[1], 10) : 0;
+                return { schemaName, migrationsApplied };
+            }
+            catch (error) {
+                throw new SchemaMigrateError(schemaName, sanitizeError(error instanceof Error ? error : new Error(String(error))));
+            }
+        },
+        /**
+         * Delete a PostgreSQL schema (DANGEROUS - drops all data)
+         */
+        async deleteSchema(schemaName) {
+            validateSchemaName(schemaName);
+            // Extra safety check - don't allow deleting public schema
+            if (schemaName.toLowerCase() === 'public') {
+                throw new Error('Cannot delete public schema');
+            }
+            try {
+                const exists = await this.schemaExists(schemaName);
+                if (!exists) {
+                    throw new SchemaNotFoundError(schemaName);
+                }
+                // CASCADE drops all objects in the schema
+                // Using pg-format for safe identifier quoting
+                const dropSchemaSql = format('DROP SCHEMA %I CASCADE', schemaName);
+                await executeSql(dropSchemaSql);
+            }
+            catch (error) {
+                if (error instanceof SchemaNotFoundError) {
+                    throw error;
+                }
+                throw new SchemaDeleteError(schemaName, error instanceof Error ? error : new Error(String(error)));
+            }
+        },
+        /**
+         * List all tenant schemas
+         *
+         * @throws {SchemaListError} When database query fails
+         */
+        async listSchemas() {
+            try {
+                // Use parameterized query with LIKE pattern
+                const result = await executeSql(`SELECT schema_name
+           FROM information_schema.schemata
+           WHERE schema_name LIKE $1
+           ORDER BY schema_name`, [`${schemaPrefix}%`]);
+                return result.map((row) => row.schema_name);
+            }
+            catch (error) {
+                throw new SchemaListError(error instanceof Error ? error : new Error(String(error)));
+            }
+        },
+        /**
+         * Check if a schema exists
+         *
+         * @throws {Error} When database query fails (schema name validation errors, connection issues)
+         */
+        async schemaExists(schemaName) {
+            validateSchemaName(schemaName);
+            // Use parameterized query - errors propagate to caller
+            const result = await executeSql(`SELECT EXISTS(
+          SELECT 1 FROM information_schema.schemata
+          WHERE schema_name = $1
+        ) as exists`, [schemaName]);
+            return result[0]?.exists ?? false;
+        },
+    };
+}
+/**
+ * Utility to convert a slug to a schema name without creating a manager
+ */
+export function slugToSchemaName(slug, prefix = 'tenant_') {
+    const sanitized = slug.toLowerCase().replace(/-/g, '_');
+    const cleaned = sanitized.replace(/[^a-z0-9_]/g, '');
+    const normalized = /^[a-z_]/.test(cleaned) ? cleaned : `_${cleaned}`;
+    return `${prefix}${normalized}`;
+}

package/dist/tenant/schema/provisioner.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Tenant provisioner for creating and managing tenant lifecycle
+ *
+ * Orchestrates:
+ * - Creating tenant records in public schema
+ * - Creating PostgreSQL schemas
+ * - Running migrations
+ * - Cleanup on failure
+ */
+import type { DatabaseClient } from '../../types.js';
+import type { TenantProvisioner as ITenantProvisioner, TenantProvisionerConfig } from '../types.js';
+/**
+ * Create a tenant provisioner
+ *
+ * @example
+ * ```typescript
+ * const provisioner = createTenantProvisioner({
+ *   schemaManager,
+ *   publicClient: publicDb,
+ *   clientPool,
+ * });
+ *
+ * // Provision a new tenant
+ * const result = await provisioner.provision({
+ *   slug: 'acme-corp',
+ *   name: 'Acme Corporation',
+ * });
+ *
+ * console.log(result.tenant.schemaName); // 'tenant_acme_corp'
+ * ```
+ */
+export declare function createTenantProvisioner<TClient extends DatabaseClient>(config: TenantProvisionerConfig<TClient>): ITenantProvisioner;

package/dist/tenant/schema/provisioner.js

@@ -0,0 +1,281 @@
+/**
+ * Tenant provisioner for creating and managing tenant lifecycle
+ *
+ * Orchestrates:
+ * - Creating tenant records in public schema
+ * - Creating PostgreSQL schemas
+ * - Running migrations
+ * - Cleanup on failure
+ */
+import { DeprovisionError, InvalidSlugError, ProvisionError, TenantNotFoundError, } from '../errors.js';
+import { slugToSchemaName } from './manager.js';
+/**
+ * Type guard to check if client has tenant model delegate
+ */
+function hasTenantModel(client) {
+    return client.tenant !== undefined && typeof client.tenant.findUnique === 'function';
+}
+/**
+ * Type guard to check if client has raw query methods
+ */
+function hasRawQueryMethods(client) {
+    return typeof client.$queryRaw === 'function' && typeof client.$executeRaw === 'function';
+}
+/**
+ * Create a tenant provisioner
+ *
+ * @example
+ * ```typescript
+ * const provisioner = createTenantProvisioner({
+ *   schemaManager,
+ *   publicClient: publicDb,
+ *   clientPool,
+ * });
+ *
+ * // Provision a new tenant
+ * const result = await provisioner.provision({
+ *   slug: 'acme-corp',
+ *   name: 'Acme Corporation',
+ * });
+ *
+ * console.log(result.tenant.schemaName); // 'tenant_acme_corp'
+ * ```
+ */
+export function createTenantProvisioner(config) {
+    const { schemaManager, publicClient, clientPool } = config;
+    /**
+     * Validate provision input
+     */
+    function validateInput(input) {
+        if (!input.slug || input.slug.trim().length === 0) {
+            throw new InvalidSlugError(input.slug || '', 'slug is required');
+        }
+        if (!input.name || input.name.trim().length === 0) {
+            throw new ProvisionError(input.slug, new Error('name is required'));
+        }
+        // Basic slug validation
+        if (!/^[a-z0-9-]+$/i.test(input.slug)) {
+            throw new InvalidSlugError(input.slug, 'slug must contain only letters, numbers, and hyphens');
+        }
+        if (input.slug.length > 50) {
+            throw new InvalidSlugError(input.slug, 'slug cannot exceed 50 characters');
+        }
+    }
+    /**
+     * Check if a tenant with this slug already exists
+     */
+    async function tenantExists(slug) {
+        if (hasTenantModel(publicClient)) {
+            const existing = await publicClient.tenant.findUnique({ where: { slug } });
+            return existing !== null;
+        }
+        if (hasRawQueryMethods(publicClient)) {
+            const result = await publicClient.$queryRaw `
+        SELECT EXISTS(SELECT 1 FROM tenants WHERE slug = ${slug}) as exists
+      `;
+            return result[0]?.exists ?? false;
+        }
+        return false;
+    }
+    /**
+     * Create tenant record in public schema
+     */
+    async function createTenantRecord(input, schemaName) {
+        const now = new Date();
+        if (hasTenantModel(publicClient)) {
+            return publicClient.tenant.create({
+                data: {
+                    slug: input.slug,
+                    name: input.name,
+                    schemaName,
+                    status: 'pending',
+                },
+            });
+        }
+        if (hasRawQueryMethods(publicClient)) {
+            const id = crypto.randomUUID();
+            await publicClient.$executeRaw `
+        INSERT INTO tenants (id, slug, name, schema_name, status, created_at, updated_at)
+        VALUES (${id}, ${input.slug}, ${input.name}, ${schemaName}, 'pending', ${now}, ${now})
+      `;
+            return {
+                id,
+                slug: input.slug,
+                name: input.name,
+                schemaName,
+                status: 'pending',
+                createdAt: now,
+                updatedAt: now,
+            };
+        }
+        throw new Error('Unable to create tenant record: no compatible method found');
+    }
+    /**
+     * Update tenant status
+     */
+    async function updateTenantStatus(tenantId, status) {
+        if (hasTenantModel(publicClient)) {
+            await publicClient.tenant.update({
+                where: { id: tenantId },
+                data: { status },
+            });
+            return;
+        }
+        if (hasRawQueryMethods(publicClient)) {
+            await publicClient.$executeRaw `
+        UPDATE tenants SET status = ${status}, updated_at = ${new Date()} WHERE id = ${tenantId}
+      `;
+            return;
+        }
+        throw new Error('Unable to update tenant status: no compatible method found');
+    }
+    /**
+     * Delete tenant record
+     */
+    async function deleteTenantRecord(tenantId) {
+        if (hasTenantModel(publicClient)) {
+            await publicClient.tenant.delete({ where: { id: tenantId } });
+            return;
+        }
+        if (hasRawQueryMethods(publicClient)) {
+            await publicClient.$executeRaw `DELETE FROM tenants WHERE id = ${tenantId}`;
+            return;
+        }
+        throw new Error('Unable to delete tenant record: no compatible method found');
+    }
+    /**
+     * Get tenant by ID
+     */
+    async function getTenant(tenantId) {
+        if (hasTenantModel(publicClient)) {
+            return publicClient.tenant.findUnique({ where: { id: tenantId } });
+        }
+        if (hasRawQueryMethods(publicClient)) {
+            const result = await publicClient.$queryRaw `
+        SELECT * FROM tenants WHERE id = ${tenantId} LIMIT 1
+      `;
+            return result[0] ?? null;
+        }
+        return null;
+    }
+    /**
+     * Get all tenants
+     */
+    async function getAllTenants() {
+        if (hasTenantModel(publicClient)) {
+            return publicClient.tenant.findMany();
+        }
+        if (hasRawQueryMethods(publicClient)) {
+            return publicClient.$queryRaw `SELECT * FROM tenants`;
+        }
+        return [];
+    }
+    return {
+        /**
+         * Provision a new tenant
+         */
+        async provision(input) {
+            validateInput(input);
+            const schemaName = slugToSchemaName(input.slug);
+            let tenant = null;
+            let schemaCreated = false;
+            try {
+                // Check for existing tenant
+                const exists = await tenantExists(input.slug);
+                if (exists) {
+                    throw new Error(`Tenant with slug '${input.slug}' already exists`);
+                }
+                // 1. Create tenant record (status: pending)
+                tenant = await createTenantRecord(input, schemaName);
+                // 2. Create PostgreSQL schema
+                const schemaResult = await schemaManager.createSchema(input.slug);
+                schemaCreated = schemaResult.created;
+                // 3. Update status to migrating
+                await updateTenantStatus(tenant.id, 'migrating');
+                // 4. Run migrations
+                const migrateResult = await schemaManager.migrateSchema(schemaName);
+                // 5. Test connection via client pool
+                await clientPool.getClient(schemaName);
+                clientPool.releaseClient(schemaName);
+                // 6. Update status to active
+                await updateTenantStatus(tenant.id, 'active');
+                return {
+                    tenant: { ...tenant, status: 'active' },
+                    schemaCreated,
+                    migrationsApplied: migrateResult.migrationsApplied,
+                };
+            }
+            catch (error) {
+                // Rollback on failure
+                if (tenant) {
+                    try {
+                        await deleteTenantRecord(tenant.id);
+                    }
+                    catch {
+                        // Ignore cleanup errors
+                    }
+                }
+                if (schemaCreated) {
+                    try {
+                        await schemaManager.deleteSchema(schemaName);
+                    }
+                    catch {
+                        // Ignore cleanup errors
+                    }
+                }
+                throw new ProvisionError(input.slug, error instanceof Error ? error : new Error(String(error)));
+            }
+        },
+        /**
+         * Deprovision a tenant (delete schema and record)
+         */
+        async deprovision(tenantId) {
+            const tenant = await getTenant(tenantId);
+            if (!tenant) {
+                throw new TenantNotFoundError(tenantId);
+            }
+            try {
+                // 1. Update status to suspended first
+                await updateTenantStatus(tenantId, 'suspended');
+                // 2. Delete the schema
+                try {
+                    await schemaManager.deleteSchema(tenant.schemaName);
+                }
+                catch {
+                    // Schema might not exist - continue with record deletion
+                }
+                // 3. Delete the tenant record
+                await deleteTenantRecord(tenantId);
+            }
+            catch (error) {
+                if (error instanceof TenantNotFoundError) {
+                    throw error;
+                }
+                throw new DeprovisionError(tenantId, error instanceof Error ? error : new Error(String(error)));
+            }
+        },
+        /**
+         * Migrate all tenant schemas
+         */
+        async migrateAll() {
+            const tenants = await getAllTenants();
+            const results = [];
+            for (const tenant of tenants) {
+                if (tenant.status !== 'active' && tenant.status !== 'pending') {
+                    continue; // Skip suspended/migrating tenants
+                }
+                try {
+                    await updateTenantStatus(tenant.id, 'migrating');
+                    const result = await schemaManager.migrateSchema(tenant.schemaName);
+                    results.push(result);
+                    await updateTenantStatus(tenant.id, 'active');
+                }
+                catch (error) {
+                    console.error(`[TenantProvisioner] Failed to migrate ${tenant.schemaName}:`, error);
+                    // Continue with other tenants
+                }
+            }
+            return results;
+        },
+    };
+}