@cldmv/slothlet 3.2.3 → 3.3.0

package/dist/lib/handlers/permission-manager.mjs

@@ -0,0 +1,408 @@
+/*
+	Copyright 2026 CLDMV/Shinrai
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+
+
+
+
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+import { compilePattern } from "@cldmv/slothlet/helpers/pattern-matcher";
+import { translate } from "@cldmv/slothlet/i18n";
+
+
+let ruleIdCounter = 0;
+
+
+export class PermissionManager extends ComponentBase {
+	
+	static slothletProperty = "permissionManager";
+
+	
+	#rules = new Map();
+
+	
+	#defaultPolicy = "allow";
+
+	
+	#enabled = false;
+
+	
+	#audit = "default";
+
+	
+	#resolvedCache = new Map();
+
+	
+	#compiledCache = new Map();
+
+	
+	constructor(slothlet) {
+		super(slothlet);
+
+		const permConfig = slothlet.config?.permissions;
+		if (permConfig) {
+			
+			
+			this.#defaultPolicy = permConfig.defaultPolicy || "allow";
+			this.#enabled = permConfig.enabled !== false;
+			this.#audit = permConfig.audit || "default";
+
+			
+			if (Array.isArray(permConfig.rules)) {
+				for (const rule of permConfig.rules) {
+					this.addRule(rule, null);
+				}
+			}
+		}
+
+		
+		this.addRule({ caller: "**", target: "slothlet.permissions.control.**", effect: "deny" }, "__builtin__");
+	}
+
+	
+	addRule(rule, ownerModuleID = null, ruleId = null) {
+		this.#validateRule(rule);
+
+		const id = ruleId || `perm-${++ruleIdCounter}`;
+		const entry = {
+			id,
+			caller: rule.caller,
+			target: rule.target,
+			effect: rule.effect,
+			ownerModuleID: ownerModuleID,
+			registeredAt: Date.now()
+		};
+
+		this.#rules.set(id, entry);
+		this.#clearCache();
+
+		this.debug("permissions", {
+			key: "DEBUG_PERMISSION_RULE_ADDED",
+			ruleId: id,
+			caller: rule.caller,
+			target: rule.target,
+			effect: rule.effect,
+			ownerModuleID
+		});
+
+		return id;
+	}
+
+	
+	removeRule(ruleId, callerModuleID = null) {
+		const entry = this.#rules.get(ruleId);
+		if (!entry) return false;
+
+		
+		
+		
+		
+		
+		if (callerModuleID && entry.ownerModuleID && callerModuleID === entry.ownerModuleID) {
+			throw new this.SlothletError("PERMISSION_SELF_MODIFY", {
+				ruleId,
+				moduleID: callerModuleID
+			});
+		}
+		
+		this.#rules.delete(ruleId);
+		this.#clearCache();
+
+		this.debug("permissions", {
+			key: "DEBUG_PERMISSION_RULE_REMOVED",
+			ruleId,
+			caller: entry.caller,
+			target: entry.target,
+			effect: entry.effect
+		});
+
+		return true;
+	}
+
+	
+	checkAccess(callerPath, targetPath, callerFilePath = null, targetFilePath = null) {
+		
+		
+		
+		
+		
+		
+		const isControlTarget = targetPath?.startsWith("slothlet.permissions.control.");
+		if (!this.#enabled && !isControlTarget) return true;
+
+		
+		if (callerFilePath && targetFilePath && callerFilePath === targetFilePath) {
+			this.#emitAuditEvent("permission:self-bypass", {
+				caller: callerPath,
+				target: targetPath,
+				filePath: callerFilePath
+			});
+			return true;
+		}
+
+		
+		const cacheKey = `${callerPath}::${targetPath}`;
+		if (this.#resolvedCache.has(cacheKey)) {
+			const cached = this.#resolvedCache.get(cacheKey);
+			this.#emitAuditEvent(cached.event, cached.payload);
+			return cached.allowed;
+		}
+
+		
+		const entry = this.#evaluate(callerPath, targetPath);
+		this.#resolvedCache.set(cacheKey, entry);
+		this.#emitAuditEvent(entry.event, entry.payload);
+		return entry.allowed;
+	}
+
+	
+	getRulesForPath(targetPath) {
+		const matching = [];
+		for (const entry of this.#rules.values()) {
+			const targetMatcher = this.#getCompiledPattern(entry.target);
+			if (targetMatcher(targetPath)) {
+				matching.push(this.#serializeRule(entry));
+			}
+		}
+		return matching;
+	}
+
+	
+	getRulesByModule(moduleID) {
+		const matching = [];
+		for (const entry of this.#rules.values()) {
+			if (entry.ownerModuleID === moduleID) {
+				matching.push(this.#serializeRule(entry));
+			}
+		}
+		return matching;
+	}
+
+	
+	getRulesForCaller(callerPath) {
+		const matching = [];
+		for (const entry of this.#rules.values()) {
+			const callerMatcher = this.#getCompiledPattern(entry.caller);
+			if (callerMatcher(callerPath)) {
+				matching.push(this.#serializeRule(entry));
+			}
+		}
+		return matching;
+	}
+
+	
+	enable() {
+		this.#enabled = true;
+		this.#clearCache();
+	}
+
+	
+	disable() {
+		this.#enabled = false;
+		this.#clearCache();
+	}
+
+	
+	isEnabled() {
+		return this.#enabled;
+	}
+
+	
+	
+	
+	
+	exportRules() {
+		const rules = [];
+		for (const entry of this.#rules.values()) {
+			rules.push({
+				rule: { caller: entry.caller, target: entry.target, effect: entry.effect },
+				ownerModuleID: entry.ownerModuleID
+			});
+		}
+		return rules;
+	}
+
+	
+	importRules(registrations) {
+		if (!Array.isArray(registrations)) return;
+		for (const reg of registrations) {
+			this.addRule(reg.rule, reg.ownerModuleID);
+		}
+	}
+	
+
+	
+	async shutdown() {
+		this.#rules.clear();
+		this.#resolvedCache.clear();
+		this.#compiledCache.clear();
+		this.#enabled = false;
+		this.#defaultPolicy = "allow";
+		this.#audit = "default";
+	}
+
+	
+
+	
+	#validateRule(rule) {
+		if (!rule || typeof rule !== "object") {
+			throw new this.SlothletError("INVALID_PERMISSION_RULE", {
+				reason: translate("PERM_RULE_NOT_OBJECT"),
+				received: typeof rule
+			});
+		}
+		if (typeof rule.caller !== "string" || !rule.caller) {
+			throw new this.SlothletError("INVALID_PERMISSION_RULE", {
+				reason: translate("PERM_RULE_CALLER_REQUIRED"),
+				received: typeof rule.caller
+			});
+		}
+		if (typeof rule.target !== "string" || !rule.target) {
+			throw new this.SlothletError("INVALID_PERMISSION_RULE", {
+				reason: translate("PERM_RULE_TARGET_REQUIRED"),
+				received: typeof rule.target
+			});
+		}
+		if (rule.effect !== "allow" && rule.effect !== "deny") {
+			throw new this.SlothletError("INVALID_PERMISSION_RULE", {
+				reason: translate("PERM_RULE_EFFECT_INVALID"),
+				received: rule.effect
+			});
+		}
+	}
+
+	
+	#evaluate(callerPath, targetPath) {
+		
+		const matches = [];
+
+		for (const entry of this.#rules.values()) {
+			const callerMatcher = this.#getCompiledPattern(entry.caller);
+			const targetMatcher = this.#getCompiledPattern(entry.target);
+
+			if (callerMatcher(callerPath) && targetMatcher(targetPath)) {
+				matches.push(entry);
+			}
+		}
+
+		
+		if (matches.length === 0) {
+			const allowed = this.#defaultPolicy === "allow";
+			return {
+				allowed,
+				event: "permission:default",
+				payload: { caller: callerPath, target: targetPath, policy: this.#defaultPolicy }
+			};
+		}
+
+		
+		matches.sort((a, b) => {
+			const specA = this.#computeSpecificity(a, callerPath, targetPath);
+			const specB = this.#computeSpecificity(b, callerPath, targetPath);
+			if (specA !== specB) return specB - specA; 
+			return a.registeredAt - b.registeredAt; 
+		});
+
+		
+		const highestSpec = this.#computeSpecificity(matches[0], callerPath, targetPath);
+		const topTier = matches.filter((m) => this.#computeSpecificity(m, callerPath, targetPath) === highestSpec);
+		
+		const winner = topTier[topTier.length - 1];
+		const allowed = winner.effect === "allow";
+
+		return {
+			allowed,
+			event: allowed ? "permission:allowed" : "permission:denied",
+			payload: { caller: callerPath, target: targetPath, rule: this.#serializeRule(winner) }
+		};
+	}
+
+	
+	#computeSpecificity(entry, callerPath, targetPath) {
+		return this.#patternSpecificity(entry.caller, callerPath) + this.#patternSpecificity(entry.target, targetPath);
+	}
+
+	
+	#patternSpecificity(pattern, _path) {
+		
+		if (!pattern.includes("*") && !pattern.includes("?") && !pattern.includes("{")) {
+			return 3;
+		}
+		
+		if (pattern.includes("**")) {
+			return 1;
+		}
+		
+		return 2;
+	}
+
+	
+	#getCompiledPattern(pattern) {
+		let matcher = this.#compiledCache.get(pattern);
+		if (!matcher) {
+			matcher = compilePattern(pattern);
+			this.#compiledCache.set(pattern, matcher);
+		}
+		return matcher;
+	}
+
+	
+	#clearCache() {
+		this.#resolvedCache.clear();
+	}
+
+	
+	#emitAuditEvent(event, payload) {
+		
+		this.debug("permissions", {
+			key:
+				event === "permission:denied"
+					? "DEBUG_PERMISSION_DENIED"
+					: event === "permission:allowed"
+						? "DEBUG_PERMISSION_ALLOWED"
+						: event === "permission:self-bypass"
+							? "DEBUG_PERMISSION_SELF_BYPASS"
+							: "DEBUG_PERMISSION_DEFAULT",
+			...payload
+		});
+
+		
+		const alwaysEmit = event === "permission:denied" || event === "permission:self-bypass";
+		if (!alwaysEmit && this.#audit !== "verbose") return;
+
+		const lifecycle = this.slothlet.handlers?.lifecycle;
+		if (lifecycle) {
+			lifecycle.emit(event, { ...payload, timestamp: Date.now() });
+		}
+	}
+
+	
+	#serializeRule(entry) {
+		return {
+			id: entry.id,
+			caller: entry.caller,
+			target: entry.target,
+			effect: entry.effect,
+			ownerModuleID: entry.ownerModuleID,
+			registeredAt: entry.registeredAt
+		};
+	}
+
+	
+	debug(category, data) {
+		this.slothlet.debug(category, data);
+	}
+}

package/dist/lib/handlers/unified-wrapper.mjs

@@ -1654,6 +1654,13 @@ export class UnifiedWrapper extends ComponentBase {
 			},
 
 			async apply(___target, ___thisArg, args) {
+				
+				
+				
+				
+				
+				const ___capturedCallerWrapper = wrapper.slothlet.contextManager?.tryGetContext?.()?.currentWrapper ?? null;
+
 				wrapper.slothlet.debug("wrapper", {
 					key: "DEBUG_MODE_WAITING_APPLY_ENTRY",
 					apiPath: wrapper.____slothletInternal.apiPath,
@@ -1834,6 +1841,27 @@ export class UnifiedWrapper extends ComponentBase {
 					
 					
 					
+
+					
+					
+					
+					
+					
+					if (___capturedCallerWrapper && wrapper.slothlet.contextManager) {
+						const ___instanceStore = wrapper.slothlet.contextManager.instances?.get?.(wrapper.instanceID);
+						
+						
+						
+						if (___instanceStore && !___instanceStore.currentWrapper) {
+							return wrapper.slothlet.contextManager.runInContext(
+								wrapper.instanceID,
+								() => Reflect.apply(current, lastObject, args),
+								null,
+								[],
+								___capturedCallerWrapper
+							);
+						}
+					}
 					return Reflect.apply(current, lastObject, args);
 				}
 
@@ -2540,6 +2568,35 @@ export class UnifiedWrapper extends ComponentBase {
 			}
 
 			
+			
+			
+			const permissionManager = wrapper.slothlet.handlers?.permissionManager;
+			if (permissionManager && permissionManager.isEnabled()) {
+				const ctx = wrapper.slothlet.contextManager?.tryGetContext?.();
+				
+				
+				const callerWrapper = ctx?.currentWrapper;
+
+				
+				if (callerWrapper) {
+					
+					
+					const callerPath = callerWrapper.____slothletInternal?.apiPath ?? "";
+					const callerFilePath = callerWrapper.____slothletInternal?.filePath ?? null;
+					const targetPath = wrapper.____slothletInternal.apiPath;
+					const targetFilePath = wrapper.____slothletInternal.filePath ?? null;
+					
+
+					if (!permissionManager.checkAccess(callerPath, targetPath, callerFilePath, targetFilePath)) {
+						throw new wrapper.SlothletError("PERMISSION_DENIED", {
+							caller: callerPath,
+							target: targetPath
+						});
+					}
+				}
+			}
+
+			
 			const hookManager = wrapper.slothlet.handlers?.hookManager;
 			
 			const hasHooks = hookManager && hookManager.enabled && !wrapper.____slothletInternal.apiPath.startsWith("slothlet.hook");
@@ -2584,33 +2641,43 @@ export class UnifiedWrapper extends ComponentBase {
 						const checkMaterialized = () => {
 							if (wrapper.____slothletInternal.state.materialized) {
 								const impl = wrapper.____slothletInternal.impl;
-								if (typeof impl === "function") {
-									if (wrapper.slothlet.contextManager) {
-										resolve(wrapper.slothlet.contextManager.runInContext(wrapper.instanceID, impl, thisArg, args, wrapper));
-									} else {
-										resolve(impl.apply(thisArg, args));
-									}
-								} else if (impl && typeof impl === "object" && typeof impl.default === "function") {
-									if (wrapper.contextManager) {
-										resolve(wrapper.contextManager.runInContext(wrapper.instanceID, impl.default, impl, args, wrapper));
+								try {
+									if (typeof impl === "function") {
+										if (wrapper.slothlet.contextManager) {
+											resolve(wrapper.slothlet.contextManager.runInContext(wrapper.instanceID, impl, thisArg, args, wrapper));
+										} else {
+											resolve(impl.apply(thisArg, args));
+										}
+									} else if (impl && typeof impl === "object" && typeof impl.default === "function") {
+										if (wrapper.contextManager) {
+											resolve(wrapper.contextManager.runInContext(wrapper.instanceID, impl.default, impl, args, wrapper));
+										} else {
+											resolve(impl.default.apply(impl, args));
+										}
 									} else {
-										resolve(impl.default.apply(impl, args));
+										reject(
+											new wrapper.slothlet.SlothletError(
+												"INVALID_CONFIG_NOT_A_FUNCTION",
+												{
+													apiPath: wrapper.____slothletInternal.apiPath,
+													actualType: typeof impl
+												},
+												null,
+												{ validationError: true }
+											)
+										);
 									}
-								} else {
-									reject(
-										new wrapper.slothlet.SlothletError(
-											"INVALID_CONFIG_NOT_A_FUNCTION",
-											{
-												apiPath: wrapper.____slothletInternal.apiPath,
-												actualType: typeof impl
-											},
-											null,
-											{ validationError: true }
-										)
-									);
+								} catch (err) {
+									
+									
+									
+									reject(err);
 								}
 								return;
 							}
+							
+							
+							
 							if (!wrapper.____slothletInternal.state.inFlight) {
 								reject(
 									new wrapper.slothlet.SlothletError(
@@ -2623,6 +2690,7 @@ export class UnifiedWrapper extends ComponentBase {
 									)
 								);
 								return;
+								
 							}
 							setImmediate(checkMaterialized);
 						};

package/dist/lib/helpers/config.mjs

@@ -18,6 +18,7 @@
 
 
 import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+import { SlothletError } from "@cldmv/slothlet/errors";
 
 
 export class Config extends ComponentBase {
@@ -98,7 +99,7 @@ export class Config extends ComponentBase {
 
 	
 	normalizeMutations(mutations) {
-		const defaults = { add: true, remove: true, reload: true };
+		const defaults = { add: true, remove: true, reload: true, permissions: true };
 
 		
 		if (!mutations || typeof mutations !== "object") {
@@ -109,7 +110,8 @@ export class Config extends ComponentBase {
 		return {
 			add: mutations.add === false ? false : true,
 			remove: mutations.remove === false ? false : true,
-			reload: mutations.reload === false ? false : true
+			reload: mutations.reload === false ? false : true,
+			permissions: mutations.permissions === false ? false : true
 		};
 	}
 
@@ -126,7 +128,8 @@ export class Config extends ComponentBase {
 				context: false,
 				initialization: false,
 				materialize: false,
-				versioning: false
+				versioning: false,
+				permissions: false
 			};
 		}
 
@@ -142,7 +145,8 @@ export class Config extends ComponentBase {
 				context: true,
 				initialization: true,
 				materialize: true,
-				versioning: true
+				versioning: true,
+				permissions: true
 			};
 		}
 
@@ -158,7 +162,8 @@ export class Config extends ComponentBase {
 				context: debug.context || false,
 				initialization: debug.initialization || false,
 				materialize: debug.materialize || false,
-				versioning: debug.versioning || false
+				versioning: debug.versioning || false,
+				permissions: debug.permissions || false
 			};
 		}
 
@@ -173,7 +178,8 @@ export class Config extends ComponentBase {
 			context: false,
 			initialization: false,
 			materialize: false,
-			versioning: false
+			versioning: false,
+			permissions: false
 		};
 	}
 
@@ -284,6 +290,9 @@ export class Config extends ComponentBase {
 		}
 
 		
+		const permissionsConfig = this.normalizePermissions(config.permissions);
+
+		
 		let i18nConfig = null;
 		if (config.i18n && typeof config.i18n === "object") {
 			i18nConfig = {
@@ -315,7 +324,8 @@ export class Config extends ComponentBase {
 			silent: config.silent === true,
 			typescript: this.normalizeTypeScript(config.typescript),
 			env: this.normalizeEnv(config.env),
-			versionDispatcher: config.versionDispatcher ?? null
+			versionDispatcher: config.versionDispatcher ?? null,
+			permissions: permissionsConfig
 		};
 	}
 
@@ -368,4 +378,78 @@ export class Config extends ComponentBase {
 		}
 		return null; 
 	}
+
+	
+	normalizePermissions(permissions) {
+		if (!permissions || typeof permissions !== "object") {
+			return null;
+		}
+
+		
+		let defaultPolicy;
+		if (permissions.defaultPolicy === "deny") {
+			defaultPolicy = "deny";
+		} else if (permissions.defaultPolicy === "allow" || permissions.defaultPolicy === undefined) {
+			defaultPolicy = "allow";
+		} else {
+			throw new SlothletError(
+				"INVALID_CONFIG",
+				{
+					option: "permissions.defaultPolicy",
+					value: permissions.defaultPolicy,
+					expected: '"allow" or "deny"',
+					hint: "HINT_INVALID_CONFIG"
+				},
+				null,
+				{ validationError: true }
+			);
+		}
+
+		const enabled = permissions.enabled !== false;
+
+		
+		let audit;
+		if (permissions.audit === "verbose") {
+			audit = "verbose";
+		} else if (permissions.audit === "default" || permissions.audit === undefined) {
+			audit = "default";
+		} else if (permissions.audit === true) {
+			
+			audit = "default";
+		} else if (permissions.audit === false) {
+			
+			audit = "default";
+		} else {
+			throw new SlothletError(
+				"INVALID_CONFIG",
+				{
+					option: "permissions.audit",
+					value: permissions.audit,
+					expected: '"default" or "verbose"',
+					hint: "HINT_INVALID_CONFIG"
+				},
+				null,
+				{ validationError: true }
+			);
+		}
+
+		
+		if (permissions.rules !== undefined && !Array.isArray(permissions.rules)) {
+			throw new SlothletError(
+				"INVALID_CONFIG",
+				{
+					option: "permissions.rules",
+					value: permissions.rules,
+					expected: "array",
+					hint: "HINT_INVALID_CONFIG"
+				},
+				null,
+				{ validationError: true }
+			);
+		}
+
+		const rules = Array.isArray(permissions.rules) ? permissions.rules : [];
+
+		return { defaultPolicy, enabled, audit, rules };
+	}
 }