@veloxts/orm 0.6.27 → 0.6.31

package/dist/tenant/errors.js

@@ -0,0 +1,220 @@
+/**
+ * Tenant-specific error classes for @veloxts/orm/tenant
+ */
+/**
+ * Base error class for tenant-related errors
+ */
+export class TenantError extends Error {
+    code;
+    tenantId;
+    schemaName;
+    constructor(message, code, options) {
+        super(message, { cause: options?.cause });
+        this.name = 'TenantError';
+        this.code = code;
+        this.tenantId = options?.tenantId;
+        this.schemaName = options?.schemaName;
+        // Maintains proper stack trace for where error was thrown (V8 engines)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, TenantError);
+        }
+    }
+}
+/**
+ * Tenant not found in database
+ */
+export class TenantNotFoundError extends TenantError {
+    constructor(tenantId) {
+        super(`Tenant not found: ${tenantId}`, 'TENANT_NOT_FOUND', { tenantId });
+        this.name = 'TenantNotFoundError';
+    }
+}
+/**
+ * Tenant is suspended and cannot be accessed
+ */
+export class TenantSuspendedError extends TenantError {
+    constructor(tenantId) {
+        super(`Tenant is suspended: ${tenantId}`, 'TENANT_SUSPENDED', { tenantId });
+        this.name = 'TenantSuspendedError';
+    }
+}
+/**
+ * Tenant is pending activation
+ */
+export class TenantPendingError extends TenantError {
+    constructor(tenantId) {
+        super(`Tenant is pending activation: ${tenantId}`, 'TENANT_PENDING', { tenantId });
+        this.name = 'TenantPendingError';
+    }
+}
+/**
+ * Tenant is currently being migrated
+ */
+export class TenantMigratingError extends TenantError {
+    constructor(tenantId) {
+        super(`Tenant is currently migrating: ${tenantId}`, 'TENANT_MIGRATING', { tenantId });
+        this.name = 'TenantMigratingError';
+    }
+}
+/**
+ * Tenant ID missing from request context
+ */
+export class TenantIdMissingError extends TenantError {
+    constructor() {
+        super('Tenant ID is required but was not found in request context', 'TENANT_ID_MISSING');
+        this.name = 'TenantIdMissingError';
+    }
+}
+/**
+ * User does not have access to the requested tenant
+ *
+ * SECURITY: This error is thrown when tenant access verification fails.
+ * It prevents tenant isolation bypass attacks where a user might try
+ * to access a tenant they don't belong to by manipulating JWT claims.
+ */
+export class TenantAccessDeniedError extends TenantError {
+    userId;
+    constructor(tenantId, userId) {
+        super(`Access denied to tenant: ${tenantId}`, 'TENANT_ACCESS_DENIED', { tenantId });
+        this.name = 'TenantAccessDeniedError';
+        this.userId = userId;
+    }
+}
+/**
+ * Schema creation failed
+ */
+export class SchemaCreateError extends TenantError {
+    constructor(schemaName, cause) {
+        super(`Failed to create schema: ${schemaName}`, 'SCHEMA_CREATE_FAILED', { schemaName, cause });
+        this.name = 'SchemaCreateError';
+    }
+}
+/**
+ * Schema deletion failed
+ */
+export class SchemaDeleteError extends TenantError {
+    constructor(schemaName, cause) {
+        super(`Failed to delete schema: ${schemaName}`, 'SCHEMA_DELETE_FAILED', { schemaName, cause });
+        this.name = 'SchemaDeleteError';
+    }
+}
+/**
+ * Schema migration failed
+ */
+export class SchemaMigrateError extends TenantError {
+    constructor(schemaName, cause) {
+        super(`Failed to migrate schema: ${schemaName}`, 'SCHEMA_MIGRATE_FAILED', {
+            schemaName,
+            cause,
+        });
+        this.name = 'SchemaMigrateError';
+    }
+}
+/**
+ * Schema not found
+ */
+export class SchemaNotFoundError extends TenantError {
+    constructor(schemaName) {
+        super(`Schema not found: ${schemaName}`, 'SCHEMA_NOT_FOUND', { schemaName });
+        this.name = 'SchemaNotFoundError';
+    }
+}
+/**
+ * Schema list operation failed
+ */
+export class SchemaListError extends TenantError {
+    constructor(cause) {
+        super('Failed to list schemas', 'SCHEMA_LIST_FAILED', { cause });
+        this.name = 'SchemaListError';
+    }
+}
+/**
+ * Schema already exists
+ */
+export class SchemaAlreadyExistsError extends TenantError {
+    constructor(schemaName) {
+        super(`Schema already exists: ${schemaName}`, 'SCHEMA_ALREADY_EXISTS', { schemaName });
+        this.name = 'SchemaAlreadyExistsError';
+    }
+}
+/**
+ * Client pool has reached maximum capacity
+ */
+export class ClientPoolExhaustedError extends TenantError {
+    constructor(maxClients) {
+        super(`Client pool exhausted: maximum ${maxClients} clients reached`, 'CLIENT_POOL_EXHAUSTED');
+        this.name = 'ClientPoolExhaustedError';
+    }
+}
+/**
+ * Failed to create database client
+ */
+export class ClientCreateError extends TenantError {
+    constructor(schemaName, cause) {
+        super(`Failed to create client for schema: ${schemaName}`, 'CLIENT_CREATE_FAILED', {
+            schemaName,
+            cause,
+        });
+        this.name = 'ClientCreateError';
+    }
+}
+/**
+ * Failed to disconnect database client
+ */
+export class ClientDisconnectError extends TenantError {
+    constructor(schemaName, cause) {
+        super(`Failed to disconnect client for schema: ${schemaName}`, 'CLIENT_DISCONNECT_FAILED', {
+            schemaName,
+            cause,
+        });
+        this.name = 'ClientDisconnectError';
+    }
+}
+/**
+ * Invalid tenant slug format
+ */
+export class InvalidSlugError extends TenantError {
+    constructor(slug, reason) {
+        super(`Invalid tenant slug '${slug}': ${reason}`, 'INVALID_SLUG');
+        this.name = 'InvalidSlugError';
+    }
+}
+/**
+ * Tenant provisioning failed
+ */
+export class ProvisionError extends TenantError {
+    constructor(slug, cause) {
+        super(`Failed to provision tenant: ${slug}`, 'PROVISION_FAILED', { cause });
+        this.name = 'ProvisionError';
+    }
+}
+/**
+ * Tenant deprovisioning failed
+ */
+export class DeprovisionError extends TenantError {
+    constructor(tenantId, cause) {
+        super(`Failed to deprovision tenant: ${tenantId}`, 'DEPROVISION_FAILED', { tenantId, cause });
+        this.name = 'DeprovisionError';
+    }
+}
+/**
+ * Type guard to check if an error is a TenantError
+ */
+export function isTenantError(error) {
+    return error instanceof TenantError;
+}
+/**
+ * Get error based on tenant status
+ */
+export function getTenantStatusError(tenantId, status) {
+    switch (status) {
+        case 'suspended':
+            return new TenantSuspendedError(tenantId);
+        case 'pending':
+            return new TenantPendingError(tenantId);
+        case 'migrating':
+            return new TenantMigratingError(tenantId);
+        default:
+            return null;
+    }
+}

package/dist/tenant/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @veloxts/orm/tenant - Multi-tenancy support for VeloxTS
+ *
+ * Schema-per-tenant isolation with PostgreSQL schemas.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createTenantClientPool,
+ *   createTenantSchemaManager,
+ *   createTenantProvisioner,
+ *   createTenant,
+ * } from '@veloxts/orm/tenant';
+ *
+ * // 1. Create schema manager
+ * const schemaManager = createTenantSchemaManager({
+ *   databaseUrl: process.env.DATABASE_URL!,
+ * });
+ *
+ * // 2. Create client pool
+ * const clientPool = createTenantClientPool({
+ *   baseDatabaseUrl: process.env.DATABASE_URL!,
+ *   createClient: (schemaName) => {
+ *     const url = `${process.env.DATABASE_URL}?schema=${schemaName}`;
+ *     const adapter = new PrismaPg({ connectionString: url });
+ *     return new PrismaClient({ adapter });
+ *   },
+ * });
+ *
+ * // 3. Create provisioner
+ * const provisioner = createTenantProvisioner({
+ *   schemaManager,
+ *   publicClient: publicDb,
+ *   clientPool,
+ * });
+ *
+ * // 4. Create tenant middleware
+ * const tenant = createTenant({
+ *   loadTenant: (id) => publicDb.tenant.findUnique({ where: { id } }),
+ *   clientPool,
+ *   publicClient: publicDb,
+ * });
+ *
+ * // 5. Use in procedures
+ * const getUsers = procedure()
+ *   .use(auth.requireAuth())
+ *   .use(tenant.middleware())
+ *   .query(({ ctx }) => ctx.db.user.findMany());
+ * ```
+ *
+ * @module @veloxts/orm/tenant
+ */
+export type { CachedClient, SchemaCreateResult, SchemaMigrateResult, Tenant, TenantClientPool, TenantClientPoolConfig, TenantContext, TenantContextInput, TenantDatabaseClient, TenantMiddlewareConfig, TenantPoolStats, TenantProvisioner, TenantProvisionerConfig, TenantProvisionInput, TenantProvisionResult, TenantSchemaManager, TenantSchemaManagerConfig, TenantStatus, } from './types.js';
+export { ClientCreateError, ClientDisconnectError, ClientPoolExhaustedError, DeprovisionError, getTenantStatusError, InvalidSlugError, isTenantError, ProvisionError, SchemaAlreadyExistsError, SchemaCreateError, SchemaDeleteError, SchemaListError, SchemaMigrateError, SchemaNotFoundError, TenantAccessDeniedError, TenantError, type TenantErrorCode, TenantIdMissingError, TenantMigratingError, TenantNotFoundError, TenantPendingError, TenantSuspendedError, } from './errors.js';
+export { createTenantClientPool } from './client-pool.js';
+export { createTenant, createTenantMiddleware, getTenantOrThrow, hasTenant, type MiddlewareFunction, type TenantNamespace, } from './middleware.js';
+export { createTenantSchemaManager, slugToSchemaName, } from './schema/manager.js';
+export { createTenantProvisioner } from './schema/provisioner.js';

package/dist/tenant/index.js

@@ -0,0 +1,85 @@
+/**
+ * @veloxts/orm/tenant - Multi-tenancy support for VeloxTS
+ *
+ * Schema-per-tenant isolation with PostgreSQL schemas.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createTenantClientPool,
+ *   createTenantSchemaManager,
+ *   createTenantProvisioner,
+ *   createTenant,
+ * } from '@veloxts/orm/tenant';
+ *
+ * // 1. Create schema manager
+ * const schemaManager = createTenantSchemaManager({
+ *   databaseUrl: process.env.DATABASE_URL!,
+ * });
+ *
+ * // 2. Create client pool
+ * const clientPool = createTenantClientPool({
+ *   baseDatabaseUrl: process.env.DATABASE_URL!,
+ *   createClient: (schemaName) => {
+ *     const url = `${process.env.DATABASE_URL}?schema=${schemaName}`;
+ *     const adapter = new PrismaPg({ connectionString: url });
+ *     return new PrismaClient({ adapter });
+ *   },
+ * });
+ *
+ * // 3. Create provisioner
+ * const provisioner = createTenantProvisioner({
+ *   schemaManager,
+ *   publicClient: publicDb,
+ *   clientPool,
+ * });
+ *
+ * // 4. Create tenant middleware
+ * const tenant = createTenant({
+ *   loadTenant: (id) => publicDb.tenant.findUnique({ where: { id } }),
+ *   clientPool,
+ *   publicClient: publicDb,
+ * });
+ *
+ * // 5. Use in procedures
+ * const getUsers = procedure()
+ *   .use(auth.requireAuth())
+ *   .use(tenant.middleware())
+ *   .query(({ ctx }) => ctx.db.user.findMany());
+ * ```
+ *
+ * @module @veloxts/orm/tenant
+ */
+// ============================================================================
+// Errors
+// ============================================================================
+export { ClientCreateError, ClientDisconnectError, 
+// Client pool errors
+ClientPoolExhaustedError, DeprovisionError, getTenantStatusError, 
+// Validation errors
+InvalidSlugError, 
+// Utilities
+isTenantError, 
+// Provisioning errors
+ProvisionError, SchemaAlreadyExistsError, 
+// Schema errors
+SchemaCreateError, SchemaDeleteError, SchemaListError, SchemaMigrateError, SchemaNotFoundError, 
+// Authorization error
+TenantAccessDeniedError, 
+// Base error
+TenantError, TenantIdMissingError, TenantMigratingError, 
+// Tenant errors
+TenantNotFoundError, TenantPendingError, TenantSuspendedError, } from './errors.js';
+// ============================================================================
+// Client Pool
+// ============================================================================
+export { createTenantClientPool } from './client-pool.js';
+// ============================================================================
+// Middleware
+// ============================================================================
+export { createTenant, createTenantMiddleware, getTenantOrThrow, hasTenant, } from './middleware.js';
+// ============================================================================
+// Schema Management
+// ============================================================================
+export { createTenantSchemaManager, slugToSchemaName, } from './schema/manager.js';
+export { createTenantProvisioner } from './schema/provisioner.js';

package/dist/tenant/middleware.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Tenant middleware for procedure handlers
+ *
+ * Resolves tenant from JWT claims and provides tenant-scoped database access.
+ */
+import type { DatabaseClient } from '../types.js';
+import type { Tenant, TenantClientPool, TenantContext, TenantContextInput, TenantMiddlewareConfig } from './types.js';
+/**
+ * Middleware function type compatible with tRPC/procedure middleware
+ */
+export type MiddlewareFunction<TInput, TOutput> = (opts: {
+    ctx: TInput;
+    next: (opts: {
+        ctx: TOutput;
+    }) => Promise<unknown>;
+}) => Promise<unknown>;
+/**
+ * Create tenant middleware for procedures
+ *
+ * This middleware:
+ * 1. Extracts tenantId from JWT claims (ctx.auth.token.tenantId)
+ * 2. Loads tenant from public schema
+ * 3. Validates tenant status (must be 'active')
+ * 4. Gets a tenant-scoped database client from the pool
+ * 5. Extends context with tenant info and scoped db client
+ *
+ * @example
+ * ```typescript
+ * const tenantMw = createTenantMiddleware({
+ *   loadTenant: async (tenantId) => publicDb.tenant.findUnique({ where: { id: tenantId } }),
+ *   clientPool,
+ *   publicClient: publicDb,
+ * });
+ *
+ * // Use in procedures
+ * const getUsers = procedure()
+ *   .use(auth.requireAuth())
+ *   .use(tenantMw)
+ *   .query(({ ctx }) => ctx.db.user.findMany());
+ * ```
+ */
+export declare function createTenantMiddleware<TClient extends DatabaseClient>(config: TenantMiddlewareConfig<TClient>): MiddlewareFunction<TenantContextInput, TenantContextInput & TenantContext<TClient>>;
+/**
+ * Create a tenant namespace object with middleware and helpers
+ *
+ * Provides a cleaner API similar to auth package pattern.
+ *
+ * @example
+ * ```typescript
+ * const tenant = createTenant({
+ *   loadTenant: async (id) => publicDb.tenant.findUnique({ where: { id } }),
+ *   clientPool,
+ *   publicClient: publicDb,
+ * });
+ *
+ * // Use the middleware
+ * const procedure = baseProcedure
+ *   .use(auth.requireAuth())
+ *   .use(tenant.middleware());
+ * ```
+ */
+export declare function createTenant<TClient extends DatabaseClient>(config: TenantMiddlewareConfig<TClient>): TenantNamespace<TClient>;
+/**
+ * Tenant namespace interface
+ */
+export interface TenantNamespace<TClient extends DatabaseClient> {
+    middleware: () => MiddlewareFunction<TenantContextInput, TenantContextInput & TenantContext<TClient>>;
+    optionalMiddleware: () => MiddlewareFunction<TenantContextInput, TenantContextInput & Partial<TenantContext<TClient>>>;
+    getClientPool: () => TenantClientPool<TClient>;
+    getPublicClient: () => TClient | undefined;
+    loadTenant: (tenantId: string) => Promise<Tenant | null>;
+    getClient: (schemaName: string) => Promise<TClient>;
+}
+/**
+ * Type guard to check if context has tenant
+ */
+export declare function hasTenant<TClient extends DatabaseClient>(ctx: TenantContextInput): ctx is TenantContextInput & TenantContext<TClient>;
+/**
+ * Get tenant from context or throw
+ */
+export declare function getTenantOrThrow<TClient extends DatabaseClient>(ctx: TenantContextInput): TenantContext<TClient>;

package/dist/tenant/middleware.js

@@ -0,0 +1,162 @@
+/**
+ * Tenant middleware for procedure handlers
+ *
+ * Resolves tenant from JWT claims and provides tenant-scoped database access.
+ */
+import { getTenantStatusError, TenantAccessDeniedError, TenantIdMissingError, TenantNotFoundError, } from './errors.js';
+/**
+ * Create tenant middleware for procedures
+ *
+ * This middleware:
+ * 1. Extracts tenantId from JWT claims (ctx.auth.token.tenantId)
+ * 2. Loads tenant from public schema
+ * 3. Validates tenant status (must be 'active')
+ * 4. Gets a tenant-scoped database client from the pool
+ * 5. Extends context with tenant info and scoped db client
+ *
+ * @example
+ * ```typescript
+ * const tenantMw = createTenantMiddleware({
+ *   loadTenant: async (tenantId) => publicDb.tenant.findUnique({ where: { id: tenantId } }),
+ *   clientPool,
+ *   publicClient: publicDb,
+ * });
+ *
+ * // Use in procedures
+ * const getUsers = procedure()
+ *   .use(auth.requireAuth())
+ *   .use(tenantMw)
+ *   .query(({ ctx }) => ctx.db.user.findMany());
+ * ```
+ */
+export function createTenantMiddleware(config) {
+    const { loadTenant, clientPool, publicClient, getTenantId = defaultGetTenantId, allowNoTenant = false, verifyTenantAccess, } = config;
+    return async ({ ctx, next }) => {
+        // Extract tenant ID from context
+        const tenantId = getTenantId(ctx);
+        if (!tenantId) {
+            if (allowNoTenant) {
+                // Continue without tenant context
+                return next({
+                    ctx: ctx,
+                });
+            }
+            throw new TenantIdMissingError();
+        }
+        // Load tenant from database
+        const tenant = await loadTenant(tenantId);
+        if (!tenant) {
+            throw new TenantNotFoundError(tenantId);
+        }
+        // Validate tenant status
+        const statusError = getTenantStatusError(tenantId, tenant.status);
+        if (statusError) {
+            throw statusError;
+        }
+        // SECURITY: Verify user has access to this tenant
+        // This prevents tenant isolation bypass where a user could
+        // manipulate JWT claims to access another tenant's data
+        if (verifyTenantAccess) {
+            const hasAccess = await verifyTenantAccess(ctx, tenant);
+            if (!hasAccess) {
+                throw new TenantAccessDeniedError(tenantId, ctx.user?.id);
+            }
+        }
+        // Get tenant-scoped database client
+        const db = await clientPool.getClient(tenant.schemaName);
+        // Build extended context
+        const extendedCtx = {
+            ...ctx,
+            tenant,
+            db,
+            ...(publicClient ? { publicDb: publicClient } : {}),
+        };
+        try {
+            // Continue to next middleware/handler
+            return await next({ ctx: extendedCtx });
+        }
+        finally {
+            // Release client back to pool
+            clientPool.releaseClient(tenant.schemaName);
+        }
+    };
+}
+/**
+ * Default tenant ID extractor from JWT claims
+ */
+function defaultGetTenantId(ctx) {
+    return ctx.auth?.token?.tenantId;
+}
+/**
+ * Create a tenant namespace object with middleware and helpers
+ *
+ * Provides a cleaner API similar to auth package pattern.
+ *
+ * @example
+ * ```typescript
+ * const tenant = createTenant({
+ *   loadTenant: async (id) => publicDb.tenant.findUnique({ where: { id } }),
+ *   clientPool,
+ *   publicClient: publicDb,
+ * });
+ *
+ * // Use the middleware
+ * const procedure = baseProcedure
+ *   .use(auth.requireAuth())
+ *   .use(tenant.middleware());
+ * ```
+ */
+export function createTenant(config) {
+    const middleware = createTenantMiddleware(config);
+    const { clientPool, publicClient, loadTenant } = config;
+    return {
+        /**
+         * Middleware that requires tenant context
+         */
+        middleware: () => middleware,
+        /**
+         * Middleware that makes tenant context optional
+         */
+        optionalMiddleware: () => createTenantMiddleware({
+            ...config,
+            allowNoTenant: true,
+        }),
+        /**
+         * Get the client pool for direct access
+         */
+        getClientPool: () => clientPool,
+        /**
+         * Get the public client
+         */
+        getPublicClient: () => publicClient,
+        /**
+         * Load a tenant by ID
+         */
+        loadTenant,
+        /**
+         * Get a tenant-scoped client directly
+         */
+        getClient: (schemaName) => clientPool.getClient(schemaName),
+    };
+}
+/**
+ * Type guard to check if context has tenant
+ */
+export function hasTenant(ctx) {
+    return (ctx !== null &&
+        typeof ctx === 'object' &&
+        'tenant' in ctx &&
+        ctx.tenant !== null &&
+        typeof ctx.tenant === 'object' &&
+        'db' in ctx &&
+        ctx.db !== null);
+}
+/**
+ * Get tenant from context or throw
+ */
+export function getTenantOrThrow(ctx) {
+    if (!hasTenant(ctx)) {
+        throw new TenantIdMissingError();
+    }
+    return ctx;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * 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 type { TenantSchemaManager as ITenantSchemaManager, TenantSchemaManagerConfig } from '../types.js';
+/**
+ * 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 declare function createTenantSchemaManager(config: TenantSchemaManagerConfig): ITenantSchemaManager;
+/**
+ * Utility to convert a slug to a schema name without creating a manager
+ */
+export declare function slugToSchemaName(slug: string, prefix?: string): string;