@objectstack/core 0.8.2 → 0.9.1

package/dist/security/plugin-permission-enforcer.js

@@ -0,0 +1,323 @@
+/**
+ * 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 class PluginPermissionEnforcer {
+    constructor(logger) {
+        this.permissionRegistry = new Map();
+        this.capabilityRegistry = new Map();
+        this.logger = logger;
+    }
+    /**
+     * Register plugin capabilities and build permission set
+     *
+     * @param pluginName - Plugin identifier
+     * @param capabilities - Array of capability declarations
+     */
+    registerPluginPermissions(pluginName, capabilities) {
+        this.capabilityRegistry.set(pluginName, capabilities);
+        const permissions = {
+            canAccessService: (service) => this.checkServiceAccess(capabilities, service),
+            canTriggerHook: (hook) => this.checkHookAccess(capabilities, hook),
+            canReadFile: (path) => this.checkFileRead(capabilities, path),
+            canWriteFile: (path) => this.checkFileWrite(capabilities, path),
+            canNetworkRequest: (url) => this.checkNetworkAccess(capabilities, url),
+        };
+        this.permissionRegistry.set(pluginName, permissions);
+        this.logger.info(`Permissions registered for plugin: ${pluginName}`, {
+            plugin: pluginName,
+            capabilityCount: capabilities.length,
+        });
+    }
+    /**
+     * Enforce service access permission
+     *
+     * @param pluginName - Plugin requesting access
+     * @param serviceName - Service to access
+     * @throws Error if permission denied
+     */
+    enforceServiceAccess(pluginName, serviceName) {
+        const result = this.checkPermission(pluginName, (perms) => perms.canAccessService(serviceName));
+        if (!result.allowed) {
+            const error = `Permission denied: Plugin ${pluginName} cannot access service ${serviceName}`;
+            this.logger.warn(error, {
+                plugin: pluginName,
+                service: serviceName,
+                reason: result.reason,
+            });
+            throw new Error(error);
+        }
+        this.logger.debug(`Service access granted: ${pluginName} -> ${serviceName}`);
+    }
+    /**
+     * Enforce hook trigger permission
+     *
+     * @param pluginName - Plugin requesting access
+     * @param hookName - Hook to trigger
+     * @throws Error if permission denied
+     */
+    enforceHookTrigger(pluginName, hookName) {
+        const result = this.checkPermission(pluginName, (perms) => perms.canTriggerHook(hookName));
+        if (!result.allowed) {
+            const error = `Permission denied: Plugin ${pluginName} cannot trigger hook ${hookName}`;
+            this.logger.warn(error, {
+                plugin: pluginName,
+                hook: hookName,
+                reason: result.reason,
+            });
+            throw new Error(error);
+        }
+        this.logger.debug(`Hook trigger granted: ${pluginName} -> ${hookName}`);
+    }
+    /**
+     * Enforce file read permission
+     *
+     * @param pluginName - Plugin requesting access
+     * @param path - File path to read
+     * @throws Error if permission denied
+     */
+    enforceFileRead(pluginName, path) {
+        const result = this.checkPermission(pluginName, (perms) => perms.canReadFile(path));
+        if (!result.allowed) {
+            const error = `Permission denied: Plugin ${pluginName} cannot read file ${path}`;
+            this.logger.warn(error, {
+                plugin: pluginName,
+                path,
+                reason: result.reason,
+            });
+            throw new Error(error);
+        }
+        this.logger.debug(`File read granted: ${pluginName} -> ${path}`);
+    }
+    /**
+     * Enforce file write permission
+     *
+     * @param pluginName - Plugin requesting access
+     * @param path - File path to write
+     * @throws Error if permission denied
+     */
+    enforceFileWrite(pluginName, path) {
+        const result = this.checkPermission(pluginName, (perms) => perms.canWriteFile(path));
+        if (!result.allowed) {
+            const error = `Permission denied: Plugin ${pluginName} cannot write file ${path}`;
+            this.logger.warn(error, {
+                plugin: pluginName,
+                path,
+                reason: result.reason,
+            });
+            throw new Error(error);
+        }
+        this.logger.debug(`File write granted: ${pluginName} -> ${path}`);
+    }
+    /**
+     * Enforce network request permission
+     *
+     * @param pluginName - Plugin requesting access
+     * @param url - URL to access
+     * @throws Error if permission denied
+     */
+    enforceNetworkRequest(pluginName, url) {
+        const result = this.checkPermission(pluginName, (perms) => perms.canNetworkRequest(url));
+        if (!result.allowed) {
+            const error = `Permission denied: Plugin ${pluginName} cannot access URL ${url}`;
+            this.logger.warn(error, {
+                plugin: pluginName,
+                url,
+                reason: result.reason,
+            });
+            throw new Error(error);
+        }
+        this.logger.debug(`Network request granted: ${pluginName} -> ${url}`);
+    }
+    /**
+     * Get plugin capabilities
+     *
+     * @param pluginName - Plugin identifier
+     * @returns Array of capabilities or undefined
+     */
+    getPluginCapabilities(pluginName) {
+        return this.capabilityRegistry.get(pluginName);
+    }
+    /**
+     * Get plugin permissions
+     *
+     * @param pluginName - Plugin identifier
+     * @returns Permissions object or undefined
+     */
+    getPluginPermissions(pluginName) {
+        return this.permissionRegistry.get(pluginName);
+    }
+    /**
+     * Revoke all permissions for a plugin
+     *
+     * @param pluginName - Plugin identifier
+     */
+    revokePermissions(pluginName) {
+        this.permissionRegistry.delete(pluginName);
+        this.capabilityRegistry.delete(pluginName);
+        this.logger.warn(`Permissions revoked for plugin: ${pluginName}`);
+    }
+    // Private methods
+    checkPermission(pluginName, check) {
+        const permissions = this.permissionRegistry.get(pluginName);
+        if (!permissions) {
+            return {
+                allowed: false,
+                reason: 'Plugin permissions not registered',
+            };
+        }
+        const allowed = check(permissions);
+        return {
+            allowed,
+            reason: allowed ? undefined : 'No matching capability found',
+        };
+    }
+    checkServiceAccess(capabilities, serviceName) {
+        // Check if plugin has capability to access this service
+        return capabilities.some(cap => {
+            const protocolId = cap.protocol.id;
+            // Check for wildcard service access
+            if (protocolId.includes('protocol.service.all')) {
+                return true;
+            }
+            // Check for specific service protocol
+            if (protocolId.includes(`protocol.service.${serviceName}`)) {
+                return true;
+            }
+            // Check for service category match
+            const serviceCategory = serviceName.split('.')[0];
+            if (protocolId.includes(`protocol.service.${serviceCategory}`)) {
+                return true;
+            }
+            return false;
+        });
+    }
+    checkHookAccess(capabilities, hookName) {
+        // Check if plugin has capability to trigger this hook
+        return capabilities.some(cap => {
+            const protocolId = cap.protocol.id;
+            // Check for wildcard hook access
+            if (protocolId.includes('protocol.hook.all')) {
+                return true;
+            }
+            // Check for specific hook protocol
+            if (protocolId.includes(`protocol.hook.${hookName}`)) {
+                return true;
+            }
+            // Check for hook category match
+            const hookCategory = hookName.split(':')[0];
+            if (protocolId.includes(`protocol.hook.${hookCategory}`)) {
+                return true;
+            }
+            return false;
+        });
+    }
+    checkFileRead(capabilities, _path) {
+        // Check if plugin has capability to read this file
+        return capabilities.some(cap => {
+            const protocolId = cap.protocol.id;
+            // Check for file read capability
+            if (protocolId.includes('protocol.filesystem.read')) {
+                // TODO: Add path pattern matching
+                return true;
+            }
+            return false;
+        });
+    }
+    checkFileWrite(capabilities, _path) {
+        // Check if plugin has capability to write this file
+        return capabilities.some(cap => {
+            const protocolId = cap.protocol.id;
+            // Check for file write capability
+            if (protocolId.includes('protocol.filesystem.write')) {
+                // TODO: Add path pattern matching
+                return true;
+            }
+            return false;
+        });
+    }
+    checkNetworkAccess(capabilities, _url) {
+        // Check if plugin has capability to access this URL
+        return capabilities.some(cap => {
+            const protocolId = cap.protocol.id;
+            // Check for network capability
+            if (protocolId.includes('protocol.network')) {
+                // TODO: Add URL pattern matching
+                return true;
+            }
+            return false;
+        });
+    }
+}
+/**
+ * Secure Plugin Context
+ * Wraps PluginContext with permission checks
+ */
+export class SecurePluginContext {
+    constructor(pluginName, permissionEnforcer, baseContext) {
+        this.pluginName = pluginName;
+        this.permissionEnforcer = permissionEnforcer;
+        this.baseContext = baseContext;
+    }
+    registerService(name, service) {
+        // No permission check for service registration (handled during init)
+        this.baseContext.registerService(name, service);
+    }
+    getService(name) {
+        // Check permission before accessing service
+        this.permissionEnforcer.enforceServiceAccess(this.pluginName, name);
+        return this.baseContext.getService(name);
+    }
+    getServices() {
+        // Return all services (no permission check for listing)
+        return this.baseContext.getServices();
+    }
+    hook(name, handler) {
+        // No permission check for registering hooks (handled during init)
+        this.baseContext.hook(name, handler);
+    }
+    async trigger(name, ...args) {
+        // Check permission before triggering hook
+        this.permissionEnforcer.enforceHookTrigger(this.pluginName, name);
+        await this.baseContext.trigger(name, ...args);
+    }
+    get logger() {
+        return this.baseContext.logger;
+    }
+    getKernel() {
+        return this.baseContext.getKernel();
+    }
+}
+/**
+ * Create a plugin permission enforcer
+ *
+ * @param logger - Logger instance
+ * @returns Plugin permission enforcer
+ */
+export function createPluginPermissionEnforcer(logger) {
+    return new PluginPermissionEnforcer(logger);
+}

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

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

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

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

package/dist/security/plugin-permission-enforcer.test.js

@@ -0,0 +1,205 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PluginPermissionEnforcer, SecurePluginContext } from './plugin-permission-enforcer.js';
+import { createLogger } from '../logger.js';
+describe('PluginPermissionEnforcer', () => {
+    let enforcer;
+    let logger;
+    beforeEach(() => {
+        logger = createLogger({ level: 'error' });
+        enforcer = new PluginPermissionEnforcer(logger);
+    });
+    describe('registerPluginPermissions', () => {
+        it('should register plugin capabilities', () => {
+            const capabilities = [
+                {
+                    protocol: {
+                        id: 'com.objectstack.protocol.service.database.v1',
+                        label: 'Database Service',
+                        version: { major: 1, minor: 0, patch: 0 },
+                    },
+                    conformance: 'full',
+                    certified: false,
+                },
+            ];
+            enforcer.registerPluginPermissions('com.test.plugin', capabilities);
+            const registeredCapabilities = enforcer.getPluginCapabilities('com.test.plugin');
+            expect(registeredCapabilities).toEqual(capabilities);
+        });
+    });
+    describe('enforceServiceAccess', () => {
+        it('should allow access to declared services', () => {
+            const capabilities = [
+                {
+                    protocol: {
+                        id: 'com.objectstack.protocol.service.database.v1',
+                        label: 'Database Service',
+                        version: { major: 1, minor: 0, patch: 0 },
+                    },
+                    conformance: 'full',
+                    certified: false,
+                },
+            ];
+            enforcer.registerPluginPermissions('com.test.plugin', capabilities);
+            // Should not throw
+            expect(() => {
+                enforcer.enforceServiceAccess('com.test.plugin', 'database');
+            }).not.toThrow();
+        });
+        it('should deny access to undeclared services', () => {
+            const capabilities = [
+                {
+                    protocol: {
+                        id: 'com.objectstack.protocol.service.database.v1',
+                        label: 'Database Service',
+                        version: { major: 1, minor: 0, patch: 0 },
+                    },
+                    conformance: 'full',
+                    certified: false,
+                },
+            ];
+            enforcer.registerPluginPermissions('com.test.plugin', capabilities);
+            expect(() => {
+                enforcer.enforceServiceAccess('com.test.plugin', 'network');
+            }).toThrow(/Permission denied/);
+        });
+        it('should allow wildcard service access', () => {
+            const capabilities = [
+                {
+                    protocol: {
+                        id: 'com.objectstack.protocol.service.all.v1',
+                        label: 'All Services',
+                        version: { major: 1, minor: 0, patch: 0 },
+                    },
+                    conformance: 'full',
+                    certified: false,
+                },
+            ];
+            enforcer.registerPluginPermissions('com.test.plugin', capabilities);
+            // Should allow any service
+            expect(() => {
+                enforcer.enforceServiceAccess('com.test.plugin', 'database');
+                enforcer.enforceServiceAccess('com.test.plugin', 'network');
+                enforcer.enforceServiceAccess('com.test.plugin', 'filesystem');
+            }).not.toThrow();
+        });
+    });
+    describe('enforceHookTrigger', () => {
+        it('should allow triggering declared hooks', () => {
+            const capabilities = [
+                {
+                    protocol: {
+                        id: 'com.objectstack.protocol.hook.data.v1',
+                        label: 'Data Hooks',
+                        version: { major: 1, minor: 0, patch: 0 },
+                    },
+                    conformance: 'full',
+                    certified: false,
+                },
+            ];
+            enforcer.registerPluginPermissions('com.test.plugin', capabilities);
+            expect(() => {
+                enforcer.enforceHookTrigger('com.test.plugin', 'data:beforeCreate');
+            }).not.toThrow();
+        });
+        it('should deny triggering undeclared hooks', () => {
+            const capabilities = [
+                {
+                    protocol: {
+                        id: 'com.objectstack.protocol.hook.data.v1',
+                        label: 'Data Hooks',
+                        version: { major: 1, minor: 0, patch: 0 },
+                    },
+                    conformance: 'full',
+                    certified: false,
+                },
+            ];
+            enforcer.registerPluginPermissions('com.test.plugin', capabilities);
+            expect(() => {
+                enforcer.enforceHookTrigger('com.test.plugin', 'kernel:shutdown');
+            }).toThrow(/Permission denied/);
+        });
+    });
+    describe('revokePermissions', () => {
+        it('should revoke plugin permissions', () => {
+            const capabilities = [
+                {
+                    protocol: {
+                        id: 'com.objectstack.protocol.service.database.v1',
+                        label: 'Database Service',
+                        version: { major: 1, minor: 0, patch: 0 },
+                    },
+                    conformance: 'full',
+                    certified: false,
+                },
+            ];
+            enforcer.registerPluginPermissions('com.test.plugin', capabilities);
+            enforcer.revokePermissions('com.test.plugin');
+            expect(() => {
+                enforcer.enforceServiceAccess('com.test.plugin', 'database');
+            }).toThrow(/Permission denied/);
+        });
+    });
+});
+describe('SecurePluginContext', () => {
+    let enforcer;
+    let logger;
+    let mockBaseContext;
+    beforeEach(() => {
+        logger = createLogger({ level: 'error' });
+        enforcer = new PluginPermissionEnforcer(logger);
+        mockBaseContext = {
+            registerService: () => { },
+            getService: (name) => ({ name }),
+            getServices: () => new Map(),
+            hook: () => { },
+            trigger: async () => { },
+            logger,
+            getKernel: () => ({}),
+        };
+    });
+    describe('getService', () => {
+        it('should check permission before accessing service', () => {
+            const capabilities = [
+                {
+                    protocol: {
+                        id: 'com.objectstack.protocol.service.database.v1',
+                        label: 'Database Service',
+                        version: { major: 1, minor: 0, patch: 0 },
+                    },
+                    conformance: 'full',
+                    certified: false,
+                },
+            ];
+            enforcer.registerPluginPermissions('com.test.plugin', capabilities);
+            const secureContext = new SecurePluginContext('com.test.plugin', enforcer, mockBaseContext);
+            // Should succeed with permission
+            const service = secureContext.getService('database');
+            expect(service).toBeDefined();
+            // Should fail without permission
+            expect(() => {
+                secureContext.getService('network');
+            }).toThrow(/Permission denied/);
+        });
+    });
+    describe('trigger', () => {
+        it('should check permission before triggering hook', async () => {
+            const capabilities = [
+                {
+                    protocol: {
+                        id: 'com.objectstack.protocol.hook.data.v1',
+                        label: 'Data Hooks',
+                        version: { major: 1, minor: 0, patch: 0 },
+                    },
+                    conformance: 'full',
+                    certified: false,
+                },
+            ];
+            enforcer.registerPluginPermissions('com.test.plugin', capabilities);
+            const secureContext = new SecurePluginContext('com.test.plugin', enforcer, mockBaseContext);
+            // Should succeed with permission
+            await expect(secureContext.trigger('data:beforeCreate')).resolves.not.toThrow();
+            // Should fail without permission
+            await expect(secureContext.trigger('kernel:shutdown')).rejects.toThrow(/Permission denied/);
+        });
+    });
+});

package/dist/security/plugin-signature-verifier.d.ts

@@ -0,0 +1,96 @@
+import type { Logger } from '@objectstack/spec/contracts';
+import type { PluginMetadata } from '../plugin-loader.js';
+/**
+ * Plugin Signature Configuration
+ * Controls how plugin signatures are verified
+ */
+export interface PluginSignatureConfig {
+    /**
+     * Map of publisher IDs to their trusted public keys
+     * Format: { 'com.objectstack': '-----BEGIN PUBLIC KEY-----...' }
+     */
+    trustedPublicKeys: Map<string, string>;
+    /**
+     * Signature algorithm to use
+     * - RS256: RSA with SHA-256
+     * - ES256: ECDSA with SHA-256
+     */
+    algorithm: 'RS256' | 'ES256';
+    /**
+     * Strict mode: reject plugins without signatures
+     * - true: All plugins must be signed
+     * - false: Unsigned plugins are allowed with warning
+     */
+    strictMode: boolean;
+    /**
+     * Allow self-signed plugins in development
+     */
+    allowSelfSigned?: boolean;
+}
+/**
+ * Plugin Signature Verification Result
+ */
+export interface SignatureVerificationResult {
+    verified: boolean;
+    error?: string;
+    publisherId?: string;
+    algorithm?: string;
+    signedAt?: Date;
+}
+/**
+ * Plugin Signature Verifier
+ *
+ * Implements cryptographic verification of plugin signatures to ensure:
+ * 1. Plugin integrity - code hasn't been tampered with
+ * 2. Publisher authenticity - plugin comes from trusted source
+ * 3. Non-repudiation - publisher cannot deny signing
+ *
+ * Architecture:
+ * - Uses Node.js crypto module for signature verification
+ * - Supports RSA (RS256) and ECDSA (ES256) algorithms
+ * - Verifies against trusted public key registry
+ * - Computes hash of plugin code for integrity check
+ *
+ * Security Model:
+ * - Public keys are pre-registered and trusted
+ * - Plugin signature is verified before loading
+ * - Strict mode rejects unsigned plugins
+ * - Development mode allows self-signed plugins
+ */
+export declare class PluginSignatureVerifier {
+    private config;
+    private logger;
+    constructor(config: PluginSignatureConfig, logger: Logger);
+    /**
+     * Verify plugin signature
+     *
+     * @param plugin - Plugin metadata with signature
+     * @returns Verification result
+     * @throws Error if verification fails in strict mode
+     */
+    verifyPluginSignature(plugin: PluginMetadata): Promise<SignatureVerificationResult>;
+    /**
+     * Register a trusted public key for a publisher
+     */
+    registerPublicKey(publisherId: string, publicKey: string): void;
+    /**
+     * Remove a trusted public key
+     */
+    revokePublicKey(publisherId: string): void;
+    /**
+     * Get list of trusted publishers
+     */
+    getTrustedPublishers(): string[];
+    private handleUnsignedPlugin;
+    private extractPublisherId;
+    private computePluginHash;
+    private computePluginHashNode;
+    private computePluginHashBrowser;
+    private computePluginHashFallback;
+    private serializePluginCode;
+    private verifyCryptoSignature;
+    private verifyCryptoSignatureNode;
+    private verifyCryptoSignatureBrowser;
+    private validateConfig;
+}
+//# sourceMappingURL=plugin-signature-verifier.d.ts.map

package/dist/security/plugin-signature-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-signature-verifier.d.ts","sourceRoot":"","sources":["../../src/security/plugin-signature-verifier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAc1D;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEvC;;;;OAIG;IACH,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC;IAE7B;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM;IAOzD;;;;;;OAMG;IACG,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAqEzF;;OAEG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAK/D;;OAEG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAK1C;;OAEG;IACH,oBAAoB,IAAI,MAAM,EAAE;IAMhC,OAAO,CAAC,oBAAoB;IAkB5B,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,qBAAqB;IAY7B,OAAO,CAAC,wBAAwB;IAOhC,OAAO,CAAC,yBAAyB;IAcjC,OAAO,CAAC,mBAAmB;YAoBb,qBAAqB;IAcnC,OAAO,CAAC,yBAAyB;YAqCnB,4BAA4B;IAW1C,OAAO,CAAC,cAAc;CAavB"}