@objectstack/core 0.9.1 → 1.0.0

package/dist/security/permission-manager.js

@@ -0,0 +1,235 @@
+/**
+ * Plugin Permission Manager
+ *
+ * Manages fine-grained permissions for plugin security and access control
+ */
+export class PluginPermissionManager {
+    constructor(logger) {
+        // Plugin permission definitions
+        this.permissionSets = new Map();
+        // Granted permissions (pluginId -> Set of permission IDs)
+        this.grants = new Map();
+        // Permission grant details
+        this.grantDetails = new Map();
+        this.logger = logger.child({ component: 'PermissionManager' });
+    }
+    /**
+     * Register permission requirements for a plugin
+     */
+    registerPermissions(pluginId, permissionSet) {
+        this.permissionSets.set(pluginId, permissionSet);
+        this.logger.info('Permissions registered for plugin', {
+            pluginId,
+            permissionCount: permissionSet.permissions.length
+        });
+    }
+    /**
+     * Grant a permission to a plugin
+     */
+    grantPermission(pluginId, permissionId, grantedBy, expiresAt) {
+        // Verify permission exists in plugin's declared permissions
+        const permissionSet = this.permissionSets.get(pluginId);
+        if (!permissionSet) {
+            throw new Error(`No permissions registered for plugin: ${pluginId}`);
+        }
+        const permission = permissionSet.permissions.find(p => p.id === permissionId);
+        if (!permission) {
+            throw new Error(`Permission ${permissionId} not declared by plugin ${pluginId}`);
+        }
+        // Create grant
+        if (!this.grants.has(pluginId)) {
+            this.grants.set(pluginId, new Set());
+        }
+        this.grants.get(pluginId).add(permissionId);
+        // Store grant details
+        const grantKey = `${pluginId}:${permissionId}`;
+        this.grantDetails.set(grantKey, {
+            permissionId,
+            pluginId,
+            grantedAt: new Date(),
+            grantedBy,
+            expiresAt,
+        });
+        this.logger.info('Permission granted', {
+            pluginId,
+            permissionId,
+            grantedBy
+        });
+    }
+    /**
+     * Revoke a permission from a plugin
+     */
+    revokePermission(pluginId, permissionId) {
+        const grants = this.grants.get(pluginId);
+        if (grants) {
+            grants.delete(permissionId);
+            const grantKey = `${pluginId}:${permissionId}`;
+            this.grantDetails.delete(grantKey);
+            this.logger.info('Permission revoked', { pluginId, permissionId });
+        }
+    }
+    /**
+     * Grant all permissions for a plugin
+     */
+    grantAllPermissions(pluginId, grantedBy) {
+        const permissionSet = this.permissionSets.get(pluginId);
+        if (!permissionSet) {
+            throw new Error(`No permissions registered for plugin: ${pluginId}`);
+        }
+        for (const permission of permissionSet.permissions) {
+            this.grantPermission(pluginId, permission.id, grantedBy);
+        }
+        this.logger.info('All permissions granted', { pluginId, grantedBy });
+    }
+    /**
+     * Check if a plugin has a specific permission
+     */
+    hasPermission(pluginId, permissionId) {
+        const grants = this.grants.get(pluginId);
+        if (!grants) {
+            return false;
+        }
+        // Check if granted
+        if (!grants.has(permissionId)) {
+            return false;
+        }
+        // Check expiration
+        const grantKey = `${pluginId}:${permissionId}`;
+        const grantDetails = this.grantDetails.get(grantKey);
+        if (grantDetails?.expiresAt && grantDetails.expiresAt < new Date()) {
+            this.revokePermission(pluginId, permissionId);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Check if plugin can perform an action on a resource
+     */
+    checkAccess(pluginId, resource, action, resourceId) {
+        const permissionSet = this.permissionSets.get(pluginId);
+        if (!permissionSet) {
+            return {
+                allowed: false,
+                reason: 'No permissions registered for plugin',
+            };
+        }
+        // Find matching permissions
+        const matchingPermissions = permissionSet.permissions.filter(p => {
+            // Check resource type
+            if (p.resource !== resource) {
+                return false;
+            }
+            // Check action
+            if (!p.actions.includes(action)) {
+                return false;
+            }
+            // Check resource filter if specified
+            if (resourceId && p.filter?.resourceIds) {
+                if (!p.filter.resourceIds.includes(resourceId)) {
+                    return false;
+                }
+            }
+            return true;
+        });
+        if (matchingPermissions.length === 0) {
+            return {
+                allowed: false,
+                reason: `No permission found for ${action} on ${resource}`,
+            };
+        }
+        // Check if any matching permission is granted
+        const grantedPermissions = matchingPermissions.filter(p => this.hasPermission(pluginId, p.id));
+        if (grantedPermissions.length === 0) {
+            return {
+                allowed: false,
+                reason: 'Required permissions not granted',
+                requiredPermission: matchingPermissions[0].id,
+            };
+        }
+        return {
+            allowed: true,
+            grantedPermissions: grantedPermissions.map(p => p.id),
+        };
+    }
+    /**
+     * Get all permissions for a plugin
+     */
+    getPluginPermissions(pluginId) {
+        const permissionSet = this.permissionSets.get(pluginId);
+        return permissionSet?.permissions || [];
+    }
+    /**
+     * Get granted permissions for a plugin
+     */
+    getGrantedPermissions(pluginId) {
+        const grants = this.grants.get(pluginId);
+        return grants ? Array.from(grants) : [];
+    }
+    /**
+     * Get required but not granted permissions
+     */
+    getMissingPermissions(pluginId) {
+        const permissionSet = this.permissionSets.get(pluginId);
+        if (!permissionSet) {
+            return [];
+        }
+        const granted = this.grants.get(pluginId) || new Set();
+        return permissionSet.permissions.filter(p => p.required && !granted.has(p.id));
+    }
+    /**
+     * Check if all required permissions are granted
+     */
+    hasAllRequiredPermissions(pluginId) {
+        return this.getMissingPermissions(pluginId).length === 0;
+    }
+    /**
+     * Get permission grant details
+     */
+    getGrantDetails(pluginId, permissionId) {
+        const grantKey = `${pluginId}:${permissionId}`;
+        return this.grantDetails.get(grantKey);
+    }
+    /**
+     * Validate permission against scope constraints
+     */
+    validatePermissionScope(permission, context) {
+        switch (permission.scope) {
+            case 'global':
+                return true;
+            case 'tenant':
+                return !!context.tenantId;
+            case 'user':
+                return !!context.userId;
+            case 'resource':
+                return !!context.resourceId;
+            case 'plugin':
+                return true;
+            default:
+                return false;
+        }
+    }
+    /**
+     * Clear all permissions for a plugin
+     */
+    clearPluginPermissions(pluginId) {
+        this.permissionSets.delete(pluginId);
+        const grants = this.grants.get(pluginId);
+        if (grants) {
+            for (const permissionId of grants) {
+                const grantKey = `${pluginId}:${permissionId}`;
+                this.grantDetails.delete(grantKey);
+            }
+            this.grants.delete(pluginId);
+        }
+        this.logger.info('All permissions cleared', { pluginId });
+    }
+    /**
+     * Shutdown permission manager
+     */
+    shutdown() {
+        this.permissionSets.clear();
+        this.grants.clear();
+        this.grantDetails.clear();
+        this.logger.info('Permission manager shutdown complete');
+    }
+}

package/dist/security/permission-manager.test.d.ts

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

package/dist/security/permission-manager.test.d.ts.map

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

package/dist/security/permission-manager.test.js

@@ -0,0 +1,220 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PluginPermissionManager } from './permission-manager.js';
+import { createLogger } from '../logger.js';
+describe('PluginPermissionManager', () => {
+    let manager;
+    let logger;
+    beforeEach(() => {
+        logger = createLogger({ level: 'silent' });
+        manager = new PluginPermissionManager(logger);
+    });
+    describe('registerPermissions', () => {
+        it('should register permissions for a plugin', () => {
+            const permissionSet = {
+                permissions: [
+                    {
+                        id: 'read-data',
+                        resource: 'data.object',
+                        actions: ['read'],
+                        scope: 'plugin',
+                        description: 'Read object data',
+                        required: true,
+                    },
+                ],
+                defaultGrant: 'prompt',
+            };
+            manager.registerPermissions('test-plugin', permissionSet);
+            const permissions = manager.getPluginPermissions('test-plugin');
+            expect(permissions).toHaveLength(1);
+            expect(permissions[0].id).toBe('read-data');
+        });
+    });
+    describe('grantPermission', () => {
+        it('should grant a permission to a plugin', () => {
+            const permissionSet = {
+                permissions: [
+                    {
+                        id: 'read-data',
+                        resource: 'data.object',
+                        actions: ['read'],
+                        scope: 'plugin',
+                        description: 'Read object data',
+                        required: true,
+                    },
+                ],
+                defaultGrant: 'prompt',
+            };
+            manager.registerPermissions('test-plugin', permissionSet);
+            manager.grantPermission('test-plugin', 'read-data');
+            expect(manager.hasPermission('test-plugin', 'read-data')).toBe(true);
+        });
+        it('should throw error for non-existent permission', () => {
+            const permissionSet = {
+                permissions: [],
+                defaultGrant: 'prompt',
+            };
+            manager.registerPermissions('test-plugin', permissionSet);
+            expect(() => {
+                manager.grantPermission('test-plugin', 'invalid-permission');
+            }).toThrow();
+        });
+    });
+    describe('revokePermission', () => {
+        it('should revoke a permission from a plugin', () => {
+            const permissionSet = {
+                permissions: [
+                    {
+                        id: 'read-data',
+                        resource: 'data.object',
+                        actions: ['read'],
+                        scope: 'plugin',
+                        description: 'Read object data',
+                        required: true,
+                    },
+                ],
+                defaultGrant: 'prompt',
+            };
+            manager.registerPermissions('test-plugin', permissionSet);
+            manager.grantPermission('test-plugin', 'read-data');
+            manager.revokePermission('test-plugin', 'read-data');
+            expect(manager.hasPermission('test-plugin', 'read-data')).toBe(false);
+        });
+    });
+    describe('checkAccess', () => {
+        it('should allow access when permission is granted', () => {
+            const permissionSet = {
+                permissions: [
+                    {
+                        id: 'read-data',
+                        resource: 'data.object',
+                        actions: ['read'],
+                        scope: 'plugin',
+                        description: 'Read object data',
+                        required: true,
+                    },
+                ],
+                defaultGrant: 'prompt',
+            };
+            manager.registerPermissions('test-plugin', permissionSet);
+            manager.grantPermission('test-plugin', 'read-data');
+            const result = manager.checkAccess('test-plugin', 'data.object', 'read');
+            expect(result.allowed).toBe(true);
+        });
+        it('should deny access when permission is not granted', () => {
+            const permissionSet = {
+                permissions: [
+                    {
+                        id: 'read-data',
+                        resource: 'data.object',
+                        actions: ['read'],
+                        scope: 'plugin',
+                        description: 'Read object data',
+                        required: true,
+                    },
+                ],
+                defaultGrant: 'prompt',
+            };
+            manager.registerPermissions('test-plugin', permissionSet);
+            const result = manager.checkAccess('test-plugin', 'data.object', 'read');
+            expect(result.allowed).toBe(false);
+        });
+        it('should deny access when permission does not exist', () => {
+            const permissionSet = {
+                permissions: [],
+                defaultGrant: 'prompt',
+            };
+            manager.registerPermissions('test-plugin', permissionSet);
+            const result = manager.checkAccess('test-plugin', 'data.object', 'read');
+            expect(result.allowed).toBe(false);
+        });
+    });
+    describe('getMissingPermissions', () => {
+        it('should return missing required permissions', () => {
+            const permissionSet = {
+                permissions: [
+                    {
+                        id: 'read-data',
+                        resource: 'data.object',
+                        actions: ['read'],
+                        scope: 'plugin',
+                        description: 'Read object data',
+                        required: true,
+                    },
+                    {
+                        id: 'write-data',
+                        resource: 'data.object',
+                        actions: ['create', 'update'],
+                        scope: 'plugin',
+                        description: 'Write object data',
+                        required: true,
+                    },
+                ],
+                defaultGrant: 'prompt',
+            };
+            manager.registerPermissions('test-plugin', permissionSet);
+            manager.grantPermission('test-plugin', 'read-data');
+            const missing = manager.getMissingPermissions('test-plugin');
+            expect(missing).toHaveLength(1);
+            expect(missing[0].id).toBe('write-data');
+        });
+    });
+    describe('hasAllRequiredPermissions', () => {
+        it('should return true when all required permissions are granted', () => {
+            const permissionSet = {
+                permissions: [
+                    {
+                        id: 'read-data',
+                        resource: 'data.object',
+                        actions: ['read'],
+                        scope: 'plugin',
+                        description: 'Read object data',
+                        required: true,
+                    },
+                ],
+                defaultGrant: 'prompt',
+            };
+            manager.registerPermissions('test-plugin', permissionSet);
+            manager.grantPermission('test-plugin', 'read-data');
+            expect(manager.hasAllRequiredPermissions('test-plugin')).toBe(true);
+        });
+        it('should return false when required permissions are missing', () => {
+            const permissionSet = {
+                permissions: [
+                    {
+                        id: 'read-data',
+                        resource: 'data.object',
+                        actions: ['read'],
+                        scope: 'plugin',
+                        description: 'Read object data',
+                        required: true,
+                    },
+                ],
+                defaultGrant: 'prompt',
+            };
+            manager.registerPermissions('test-plugin', permissionSet);
+            expect(manager.hasAllRequiredPermissions('test-plugin')).toBe(false);
+        });
+    });
+    describe('clearPluginPermissions', () => {
+        it('should clear all permissions for a plugin', () => {
+            const permissionSet = {
+                permissions: [
+                    {
+                        id: 'read-data',
+                        resource: 'data.object',
+                        actions: ['read'],
+                        scope: 'plugin',
+                        description: 'Read object data',
+                        required: true,
+                    },
+                ],
+                defaultGrant: 'prompt',
+            };
+            manager.registerPermissions('test-plugin', permissionSet);
+            manager.grantPermission('test-plugin', 'read-data');
+            manager.clearPluginPermissions('test-plugin');
+            expect(manager.getPluginPermissions('test-plugin')).toHaveLength(0);
+            expect(manager.getGrantedPermissions('test-plugin')).toHaveLength(0);
+        });
+    });
+});

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

@@ -1,5 +1,5 @@
 import type { Logger } from '@objectstack/spec/contracts';
-import type { PluginCapability } from '@objectstack/spec/system';
+import type { PluginCapability } from '@objectstack/spec/kernel';
 import type { PluginContext } from '../types.js';
 /**
  * Plugin Permissions

package/dist/security/sandbox-runtime.d.ts

@@ -0,0 +1,115 @@
+import type { SandboxConfig } from '@objectstack/spec/kernel';
+import type { ObjectLogger } from '../logger.js';
+/**
+ * Resource Usage Statistics
+ */
+export interface ResourceUsage {
+    memory: {
+        current: number;
+        peak: number;
+        limit?: number;
+    };
+    cpu: {
+        current: number;
+        average: number;
+        limit?: number;
+    };
+    connections: {
+        current: number;
+        limit?: number;
+    };
+}
+/**
+ * Sandbox Execution Context
+ * Represents an isolated execution environment for a plugin
+ */
+export interface SandboxContext {
+    pluginId: string;
+    config: SandboxConfig;
+    startTime: Date;
+    resourceUsage: ResourceUsage;
+}
+/**
+ * Plugin Sandbox Runtime
+ *
+ * Provides isolated execution environments for plugins with resource limits
+ * and access controls
+ */
+export declare class PluginSandboxRuntime {
+    private logger;
+    private sandboxes;
+    private monitoringIntervals;
+    constructor(logger: ObjectLogger);
+    /**
+     * Create a sandbox for a plugin
+     */
+    createSandbox(pluginId: string, config: SandboxConfig): SandboxContext;
+    /**
+     * Destroy a sandbox
+     */
+    destroySandbox(pluginId: string): void;
+    /**
+     * Check if resource access is allowed
+     */
+    checkResourceAccess(pluginId: string, resourceType: 'file' | 'network' | 'process' | 'env', resourcePath?: string): {
+        allowed: boolean;
+        reason?: string;
+    };
+    /**
+     * Check file system access
+     * WARNING: Uses simple prefix matching. For production, use proper path
+     * resolution with path.resolve() and path.normalize() to prevent traversal.
+     */
+    private checkFileAccess;
+    /**
+     * Check network access
+     * WARNING: Uses simple string matching. For production, use proper URL
+     * parsing with new URL() and check hostname property.
+     */
+    private checkNetworkAccess;
+    /**
+     * Check process spawning access
+     */
+    private checkProcessAccess;
+    /**
+     * Check environment variable access
+     */
+    private checkEnvAccess;
+    /**
+     * Check resource limits
+     */
+    checkResourceLimits(pluginId: string): {
+        withinLimits: boolean;
+        violations: string[];
+    };
+    /**
+     * Get resource usage for a plugin
+     */
+    getResourceUsage(pluginId: string): ResourceUsage | undefined;
+    /**
+     * Start monitoring resource usage
+     */
+    private startResourceMonitoring;
+    /**
+     * Stop monitoring resource usage
+     */
+    private stopResourceMonitoring;
+    /**
+     * Update resource usage statistics
+     *
+     * NOTE: Currently uses global process.memoryUsage() which tracks the entire
+     * Node.js process, not individual plugins. For production, implement proper
+     * per-plugin tracking using V8 heap snapshots or allocation tracking at
+     * plugin boundaries.
+     */
+    private updateResourceUsage;
+    /**
+     * Get all active sandboxes
+     */
+    getAllSandboxes(): Map<string, SandboxContext>;
+    /**
+     * Shutdown sandbox runtime
+     */
+    shutdown(): void;
+}
+//# sourceMappingURL=sandbox-runtime.d.ts.map

package/dist/security/sandbox-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-runtime.d.ts","sourceRoot":"","sources":["../../src/security/sandbox-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,GAAG,EAAE;QACH,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,EAAE;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,IAAI,CAAC;IAChB,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED;;;;;GAKG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAe;IAG7B,OAAO,CAAC,SAAS,CAAqC;IAGtD,OAAO,CAAC,mBAAmB,CAAqC;gBAEpD,MAAM,EAAE,YAAY;IAIhC;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,cAAc;IA+BtE;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IActC;;OAEG;IACH,mBAAmB,CACjB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,KAAK,EACpD,YAAY,CAAC,EAAE,MAAM,GACpB;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IA0BxC;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAiDvB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAwD1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;OAEG;IACH,OAAO,CAAC,cAAc;IAsBtB;;OAEG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG;QACrC,YAAY,EAAE,OAAO,CAAC;QACtB,UAAU,EAAE,MAAM,EAAE,CAAA;KACrB;IAiCD;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAK7D;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAS/B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAQ9B;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAiC3B;;OAEG;IACH,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC;IAI9C;;OAEG;IACH,QAAQ,IAAI,IAAI;CAUjB"}