@cldmv/slothlet 3.2.1 → 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/handlers/version-manager.mjs

@@ -508,6 +508,30 @@ export class VersionManager extends ComponentBase {
 			return manager.#walkApiPath([versionTag, ...logicalPath.split(".")]);
 		};
 
+		
+		
+		
+		
+		
+		target[Symbol.for("nodejs.util.inspect.custom")] = function (_depth, options, inspectFn) {
+			const vw = resolveVersionedWrapper();
+			if (vw) {
+				try {
+					return typeof inspectFn === "function" ? inspectFn(vw, options) : inspect(vw, options);
+				} catch {
+					
+					
+					void 0;
+				}
+			}
+			
+			
+			
+			const entry = manager.#registry.get(logicalPath);
+			const versions = entry ? Array.from(entry.versions.keys()) : [];
+			return { __versionDispatcher: logicalPath, versions };
+		};
+
 		const handlers = {
 			
 			get(t, prop) {
@@ -566,24 +590,26 @@ export class VersionManager extends ComponentBase {
 				
 				
 				
-				if (typeof prop === "symbol" && prop.toString() === "Symbol(nodejs.util.inspect.custom)") {
-					return () => {
+				
+				if (prop === inspect.custom) {
+					return (_depth, options, inspectFn) => {
 						const vw = resolveVersionedWrapper();
 						if (vw) {
 							try {
-								return inspect(vw);
+								return typeof inspectFn === "function" ? inspectFn(vw, options) : inspect(vw, options);
 							} catch {
 								
+								
 								void 0; 
 							}
 						}
 						
+						
 						const entry = manager.#registry.get(logicalPath);
 						const versions = entry ? Array.from(entry.versions.keys()) : [];
 						return { __versionDispatcher: logicalPath, versions };
 					};
 				}
-				
 
 				
 				if (prop === "toString") return () => `[VersionDispatcher: ${logicalPath}]`;
@@ -741,6 +767,53 @@ export class VersionManager extends ComponentBase {
 				}
 				
 				return Reflect.defineProperty(vw, prop, descriptor);
+			},
+
+			
+			set(t, prop, value) {
+				
+				
+				
+				
+				
+				if (typeof prop === "symbol") return true;
+
+				
+				if (prop === "____slothletInternal" || prop === "_impl" || prop === "__impl" || prop === "__state" || prop === "__invalid")
+					return true;
+
+				
+				if (
+					prop === "__isVersionDispatcher" ||
+					prop === "__mode" ||
+					prop === "__apiPath" ||
+					prop === "__slothletPath" ||
+					prop === "__isCallable" ||
+					prop === "__materializeOnCreate" ||
+					prop === "__materialized" ||
+					prop === "__inFlight" ||
+					prop === "__displayName" ||
+					prop === "__moduleID" ||
+					prop === "_materialize" ||
+					prop === "length" ||
+					prop === "name"
+				)
+					return true;
+
+				
+				if (prop === "then" || prop === "constructor" || prop === "toString" || prop === "valueOf" || prop === "toJSON") return true;
+
+				const vw = resolveVersionedWrapper();
+				
+				
+				
+				
+				
+				if (!vw) return true;
+				
+				
+				
+				return Reflect.set(vw, prop, value, vw);
 			}
 		};