@objectstack/core 0.8.2 → 0.9.1

package/dist/security/plugin-config-validator.js

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+/**
+ * Plugin Configuration Validator
+ *
+ * Validates plugin configurations against Zod schemas to ensure:
+ * 1. Type safety - all config values have correct types
+ * 2. Business rules - values meet constraints (min/max, regex, etc.)
+ * 3. Required fields - all mandatory configuration is provided
+ * 4. Default values - missing optional fields get defaults
+ *
+ * Architecture:
+ * - Uses Zod for runtime validation
+ * - Provides detailed error messages with field paths
+ * - Supports nested configuration objects
+ * - Allows partial validation for incremental updates
+ *
+ * Usage:
+ * ```typescript
+ * const validator = new PluginConfigValidator(logger);
+ * const validConfig = validator.validatePluginConfig(plugin, userConfig);
+ * ```
+ */
+export class PluginConfigValidator {
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Validate plugin configuration against its Zod schema
+     *
+     * @param plugin - Plugin metadata with configSchema
+     * @param config - User-provided configuration
+     * @returns Validated and typed configuration
+     * @throws Error with detailed validation errors
+     */
+    validatePluginConfig(plugin, config) {
+        if (!plugin.configSchema) {
+            this.logger.debug(`Plugin ${plugin.name} has no config schema - skipping validation`);
+            return config;
+        }
+        try {
+            // Use Zod to parse and validate
+            const validatedConfig = plugin.configSchema.parse(config);
+            this.logger.debug(`✅ Plugin config validated: ${plugin.name}`, {
+                plugin: plugin.name,
+                configKeys: Object.keys(config || {}).length,
+            });
+            return validatedConfig;
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                const formattedErrors = this.formatZodErrors(error);
+                const errorMessage = [
+                    `Plugin ${plugin.name} configuration validation failed:`,
+                    ...formattedErrors.map(e => `  - ${e.path}: ${e.message}`),
+                ].join('\n');
+                this.logger.error(errorMessage, undefined, {
+                    plugin: plugin.name,
+                    errors: formattedErrors,
+                });
+                throw new Error(errorMessage);
+            }
+            // Re-throw other errors
+            throw error;
+        }
+    }
+    /**
+     * Validate partial configuration (for incremental updates)
+     *
+     * @param plugin - Plugin metadata
+     * @param partialConfig - Partial configuration to validate
+     * @returns Validated partial configuration
+     */
+    validatePartialConfig(plugin, partialConfig) {
+        if (!plugin.configSchema) {
+            return partialConfig;
+        }
+        try {
+            // Use Zod's partial() method for partial validation
+            // Cast to ZodObject to access partial() method
+            const partialSchema = plugin.configSchema.partial();
+            const validatedConfig = partialSchema.parse(partialConfig);
+            this.logger.debug(`✅ Partial config validated: ${plugin.name}`);
+            return validatedConfig;
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                const formattedErrors = this.formatZodErrors(error);
+                const errorMessage = [
+                    `Plugin ${plugin.name} partial configuration validation failed:`,
+                    ...formattedErrors.map(e => `  - ${e.path}: ${e.message}`),
+                ].join('\n');
+                throw new Error(errorMessage);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get default configuration from schema
+     *
+     * @param plugin - Plugin metadata
+     * @returns Default configuration object
+     */
+    getDefaultConfig(plugin) {
+        if (!plugin.configSchema) {
+            return undefined;
+        }
+        try {
+            // Parse empty object to get defaults
+            const defaults = plugin.configSchema.parse({});
+            this.logger.debug(`Default config extracted: ${plugin.name}`);
+            return defaults;
+        }
+        catch (error) {
+            // Schema may require some fields - return undefined
+            this.logger.debug(`No default config available: ${plugin.name}`);
+            return undefined;
+        }
+    }
+    /**
+     * Check if configuration is valid without throwing
+     *
+     * @param plugin - Plugin metadata
+     * @param config - Configuration to check
+     * @returns True if valid, false otherwise
+     */
+    isConfigValid(plugin, config) {
+        if (!plugin.configSchema) {
+            return true;
+        }
+        const result = plugin.configSchema.safeParse(config);
+        return result.success;
+    }
+    /**
+     * Get configuration errors without throwing
+     *
+     * @param plugin - Plugin metadata
+     * @param config - Configuration to check
+     * @returns Array of validation errors, or empty array if valid
+     */
+    getConfigErrors(plugin, config) {
+        if (!plugin.configSchema) {
+            return [];
+        }
+        const result = plugin.configSchema.safeParse(config);
+        if (result.success) {
+            return [];
+        }
+        return this.formatZodErrors(result.error);
+    }
+    // Private methods
+    formatZodErrors(error) {
+        return error.issues.map((e) => ({
+            path: e.path.join('.') || 'root',
+            message: e.message,
+        }));
+    }
+}
+/**
+ * Create a plugin config validator
+ *
+ * @param logger - Logger instance
+ * @returns Plugin config validator
+ */
+export function createPluginConfigValidator(logger) {
+    return new PluginConfigValidator(logger);
+}

package/dist/security/plugin-config-validator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin-config-validator.test.d.ts.map

package/dist/security/plugin-config-validator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-config-validator.test.d.ts","sourceRoot":"","sources":["../../src/security/plugin-config-validator.test.ts"],"names":[],"mappings":""}

package/dist/security/plugin-config-validator.test.js

@@ -0,0 +1,223 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { z } from 'zod';
+import { PluginConfigValidator } from './plugin-config-validator.js';
+import { createLogger } from '../logger.js';
+describe('PluginConfigValidator', () => {
+    let validator;
+    let logger;
+    beforeEach(() => {
+        logger = createLogger({ level: 'error' });
+        validator = new PluginConfigValidator(logger);
+    });
+    describe('validatePluginConfig', () => {
+        it('should validate valid configuration', () => {
+            const configSchema = z.object({
+                port: z.number().min(1000).max(65535),
+                host: z.string(),
+                debug: z.boolean().default(false),
+            });
+            const plugin = {
+                name: 'com.test.plugin',
+                version: '1.0.0',
+                configSchema,
+                init: async () => { },
+            };
+            const config = {
+                port: 3000,
+                host: 'localhost',
+                debug: true,
+            };
+            const validatedConfig = validator.validatePluginConfig(plugin, config);
+            expect(validatedConfig).toEqual(config);
+        });
+        it('should apply defaults for missing optional fields', () => {
+            const configSchema = z.object({
+                port: z.number().default(3000),
+                host: z.string().default('localhost'),
+                debug: z.boolean().default(false),
+            });
+            const plugin = {
+                name: 'com.test.plugin',
+                version: '1.0.0',
+                configSchema,
+                init: async () => { },
+            };
+            const config = {
+                port: 8080,
+            };
+            const validatedConfig = validator.validatePluginConfig(plugin, config);
+            expect(validatedConfig).toEqual({
+                port: 8080,
+                host: 'localhost',
+                debug: false,
+            });
+        });
+        it('should throw error for invalid configuration', () => {
+            const configSchema = z.object({
+                port: z.number().min(1000).max(65535),
+                host: z.string(),
+            });
+            const plugin = {
+                name: 'com.test.plugin',
+                version: '1.0.0',
+                configSchema,
+                init: async () => { },
+            };
+            const config = {
+                port: 100, // Invalid: < 1000
+                host: 'localhost',
+            };
+            expect(() => validator.validatePluginConfig(plugin, config)).toThrow();
+        });
+        it('should provide detailed error messages', () => {
+            const configSchema = z.object({
+                port: z.number().min(1000),
+                host: z.string().min(1),
+            });
+            const plugin = {
+                name: 'com.test.plugin',
+                version: '1.0.0',
+                configSchema,
+                init: async () => { },
+            };
+            const config = {
+                port: 100,
+                host: '',
+            };
+            try {
+                validator.validatePluginConfig(plugin, config);
+                expect.fail('Should have thrown validation error');
+            }
+            catch (error) {
+                const errorMessage = error.message;
+                expect(errorMessage).toContain('com.test.plugin');
+                expect(errorMessage).toContain('port');
+                expect(errorMessage).toContain('host');
+            }
+        });
+        it('should skip validation when no schema is provided', () => {
+            const plugin = {
+                name: 'com.test.plugin',
+                version: '1.0.0',
+                init: async () => { },
+            };
+            const config = { anything: 'goes' };
+            const validatedConfig = validator.validatePluginConfig(plugin, config);
+            expect(validatedConfig).toEqual(config);
+        });
+    });
+    describe('validatePartialConfig', () => {
+        it('should validate partial configuration', () => {
+            const configSchema = z.object({
+                port: z.number().min(1000),
+                host: z.string(),
+                debug: z.boolean(),
+            });
+            const plugin = {
+                name: 'com.test.plugin',
+                version: '1.0.0',
+                configSchema,
+                init: async () => { },
+            };
+            const partialConfig = {
+                port: 8080,
+            };
+            const validatedConfig = validator.validatePartialConfig(plugin, partialConfig);
+            expect(validatedConfig).toEqual({ port: 8080 });
+        });
+    });
+    describe('getDefaultConfig', () => {
+        it('should extract default configuration', () => {
+            const configSchema = z.object({
+                port: z.number().default(3000),
+                host: z.string().default('localhost'),
+                debug: z.boolean().default(false),
+            });
+            const plugin = {
+                name: 'com.test.plugin',
+                version: '1.0.0',
+                configSchema,
+                init: async () => { },
+            };
+            const defaults = validator.getDefaultConfig(plugin);
+            expect(defaults).toEqual({
+                port: 3000,
+                host: 'localhost',
+                debug: false,
+            });
+        });
+        it('should return undefined when schema requires fields', () => {
+            const configSchema = z.object({
+                port: z.number(),
+                host: z.string(),
+            });
+            const plugin = {
+                name: 'com.test.plugin',
+                version: '1.0.0',
+                configSchema,
+                init: async () => { },
+            };
+            const defaults = validator.getDefaultConfig(plugin);
+            expect(defaults).toBeUndefined();
+        });
+    });
+    describe('isConfigValid', () => {
+        it('should return true for valid config', () => {
+            const configSchema = z.object({
+                port: z.number(),
+            });
+            const plugin = {
+                name: 'com.test.plugin',
+                version: '1.0.0',
+                configSchema,
+                init: async () => { },
+            };
+            const isValid = validator.isConfigValid(plugin, { port: 3000 });
+            expect(isValid).toBe(true);
+        });
+        it('should return false for invalid config', () => {
+            const configSchema = z.object({
+                port: z.number(),
+            });
+            const plugin = {
+                name: 'com.test.plugin',
+                version: '1.0.0',
+                configSchema,
+                init: async () => { },
+            };
+            const isValid = validator.isConfigValid(plugin, { port: 'invalid' });
+            expect(isValid).toBe(false);
+        });
+    });
+    describe('getConfigErrors', () => {
+        it('should return errors for invalid config', () => {
+            const configSchema = z.object({
+                port: z.number().min(1000),
+                host: z.string().min(1),
+            });
+            const plugin = {
+                name: 'com.test.plugin',
+                version: '1.0.0',
+                configSchema,
+                init: async () => { },
+            };
+            const errors = validator.getConfigErrors(plugin, { port: 100, host: '' });
+            expect(errors).toHaveLength(2);
+            expect(errors[0].path).toBe('port');
+            expect(errors[1].path).toBe('host');
+        });
+        it('should return empty array for valid config', () => {
+            const configSchema = z.object({
+                port: z.number(),
+            });
+            const plugin = {
+                name: 'com.test.plugin',
+                version: '1.0.0',
+                configSchema,
+                init: async () => { },
+            };
+            const errors = validator.getConfigErrors(plugin, { port: 3000 });
+            expect(errors).toEqual([]);
+        });
+    });
+});

package/dist/security/plugin-permission-enforcer.d.ts

@@ -0,0 +1,154 @@
+import type { Logger } from '@objectstack/spec/contracts';
+import type { PluginCapability } from '@objectstack/spec/system';
+import type { PluginContext } from '../types.js';
+/**
+ * Plugin Permissions
+ * Defines what actions a plugin is allowed to perform
+ */
+export interface PluginPermissions {
+    canAccessService(serviceName: string): boolean;
+    canTriggerHook(hookName: string): boolean;
+    canReadFile(path: string): boolean;
+    canWriteFile(path: string): boolean;
+    canNetworkRequest(url: string): boolean;
+}
+/**
+ * Permission Check Result
+ */
+export interface PermissionCheckResult {
+    allowed: boolean;
+    reason?: string;
+    capability?: string;
+}
+/**
+ * Plugin Permission Enforcer
+ *
+ * Implements capability-based security model to enforce:
+ * 1. Service access control - which services a plugin can use
+ * 2. Hook restrictions - which hooks a plugin can trigger
+ * 3. File system permissions - what files a plugin can read/write
+ * 4. Network permissions - what URLs a plugin can access
+ *
+ * Architecture:
+ * - Uses capability declarations from plugin manifest
+ * - Checks permissions before allowing operations
+ * - Logs all permission denials for security audit
+ * - Supports allowlist and denylist patterns
+ *
+ * Security Model:
+ * - Principle of least privilege - plugins get minimal permissions
+ * - Explicit declaration - all capabilities must be declared
+ * - Runtime enforcement - checks happen at operation time
+ * - Audit trail - all denials are logged
+ *
+ * Usage:
+ * ```typescript
+ * const enforcer = new PluginPermissionEnforcer(logger);
+ * enforcer.registerPluginPermissions(pluginName, capabilities);
+ * enforcer.enforceServiceAccess(pluginName, 'database');
+ * ```
+ */
+export declare class PluginPermissionEnforcer {
+    private logger;
+    private permissionRegistry;
+    private capabilityRegistry;
+    constructor(logger: Logger);
+    /**
+     * Register plugin capabilities and build permission set
+     *
+     * @param pluginName - Plugin identifier
+     * @param capabilities - Array of capability declarations
+     */
+    registerPluginPermissions(pluginName: string, capabilities: PluginCapability[]): void;
+    /**
+     * Enforce service access permission
+     *
+     * @param pluginName - Plugin requesting access
+     * @param serviceName - Service to access
+     * @throws Error if permission denied
+     */
+    enforceServiceAccess(pluginName: string, serviceName: string): void;
+    /**
+     * Enforce hook trigger permission
+     *
+     * @param pluginName - Plugin requesting access
+     * @param hookName - Hook to trigger
+     * @throws Error if permission denied
+     */
+    enforceHookTrigger(pluginName: string, hookName: string): void;
+    /**
+     * Enforce file read permission
+     *
+     * @param pluginName - Plugin requesting access
+     * @param path - File path to read
+     * @throws Error if permission denied
+     */
+    enforceFileRead(pluginName: string, path: string): void;
+    /**
+     * Enforce file write permission
+     *
+     * @param pluginName - Plugin requesting access
+     * @param path - File path to write
+     * @throws Error if permission denied
+     */
+    enforceFileWrite(pluginName: string, path: string): void;
+    /**
+     * Enforce network request permission
+     *
+     * @param pluginName - Plugin requesting access
+     * @param url - URL to access
+     * @throws Error if permission denied
+     */
+    enforceNetworkRequest(pluginName: string, url: string): void;
+    /**
+     * Get plugin capabilities
+     *
+     * @param pluginName - Plugin identifier
+     * @returns Array of capabilities or undefined
+     */
+    getPluginCapabilities(pluginName: string): PluginCapability[] | undefined;
+    /**
+     * Get plugin permissions
+     *
+     * @param pluginName - Plugin identifier
+     * @returns Permissions object or undefined
+     */
+    getPluginPermissions(pluginName: string): PluginPermissions | undefined;
+    /**
+     * Revoke all permissions for a plugin
+     *
+     * @param pluginName - Plugin identifier
+     */
+    revokePermissions(pluginName: string): void;
+    private checkPermission;
+    private checkServiceAccess;
+    private checkHookAccess;
+    private checkFileRead;
+    private checkFileWrite;
+    private checkNetworkAccess;
+}
+/**
+ * Secure Plugin Context
+ * Wraps PluginContext with permission checks
+ */
+export declare class SecurePluginContext implements PluginContext {
+    private pluginName;
+    private permissionEnforcer;
+    private baseContext;
+    constructor(pluginName: string, permissionEnforcer: PluginPermissionEnforcer, baseContext: PluginContext);
+    registerService(name: string, service: any): void;
+    getService<T>(name: string): T;
+    getServices(): Map<string, any>;
+    hook(name: string, handler: (...args: any[]) => void | Promise<void>): void;
+    trigger(name: string, ...args: any[]): Promise<void>;
+    get logger(): Logger;
+    getKernel(): import("../kernel.js").ObjectKernel;
+}
+/**
+ * Create a plugin permission enforcer
+ *
+ * @param logger - Logger instance
+ * @returns Plugin permission enforcer
+ */
+export declare function createPluginPermissionEnforcer(logger: Logger): PluginPermissionEnforcer;
+//# sourceMappingURL=plugin-permission-enforcer.d.ts.map

package/dist/security/plugin-permission-enforcer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-permission-enforcer.d.ts","sourceRoot":"","sources":["../../src/security/plugin-permission-enforcer.ts"],"names":[],"mappings":"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"}