@cldmv/slothlet 3.3.0 → 3.4.0

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

@@ -14,395 +14,4 @@
 	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);
-	}
-}
+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;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,condition:rule.condition??null,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,runtimeContext=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,runtimeContext);if(!entry.hasConditionalRules){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){const getValueType=value=>{if(value===null)return"null";if(Array.isArray(value))return"array";return typeof value};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})}if(rule.condition!==void 0&&rule.condition!==null){const isPlainObject=c=>{if(c===null||typeof c!=="object")return false;const proto=Object.getPrototypeOf(c);return proto===Object.prototype||proto===null};const isValidConditionEntry=c=>typeof c==="function"||isPlainObject(c);const entries=Array.isArray(rule.condition)?rule.condition:[rule.condition];const allValid=entries.length>0&&entries.every(isValidConditionEntry);if(!allValid){const conditionIndex=entries.findIndex(entry=>!isValidConditionEntry(entry));const invalidEntry=conditionIndex>=0?entries[conditionIndex]:rule.condition;throw new this.SlothletError("INVALID_PERMISSION_RULE",{reason:translate("PERM_RULE_CONDITION_INVALID"),received:getValueType(invalidEntry)})}}}#deepObjectMatches(pattern,ctx){if(ctx==null||typeof ctx!=="object")return false;for(const[key,val]of Object.entries(pattern)){const proto=val!==null&&typeof val==="object"?Object.getPrototypeOf(val):null;const isPlainNested=proto===Object.prototype||proto===null;if(val!==null&&typeof val==="object"&&isPlainNested){if(!this.#deepObjectMatches(val,ctx[key]))return false}else{if(ctx[key]!==val)return false}}return true}#singleConditionMatches(conditionEntry,ctx){if(typeof conditionEntry==="function"){try{return!!conditionEntry(ctx)}catch{return false}}return this.#deepObjectMatches(conditionEntry,ctx)}#conditionMatches(entry,runtimeContext){if(entry.condition==null)return true;const ctx=runtimeContext??{};if(Array.isArray(entry.condition)){return entry.condition.some(c=>this.#singleConditionMatches(c,ctx))}return this.#singleConditionMatches(entry.condition,ctx)}#evaluate(callerPath,targetPath,runtimeContext=null){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)}}const hasConditionalRules=matches.some(m=>m.condition!=null);const conditioned=matches.filter(entry=>this.#conditionMatches(entry,runtimeContext));if(conditioned.length===0){const allowed2=this.#defaultPolicy==="allow";return{allowed:allowed2,event:"permission:default",payload:{caller:callerPath,target:targetPath,policy:this.#defaultPolicy},hasConditionalRules}}conditioned.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(conditioned[0],callerPath,targetPath);const topTier=conditioned.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),conditionMatched:winner.condition!=null},hasConditionalRules}}#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,condition:entry.condition??null,ownerModuleID:entry.ownerModuleID,registeredAt:entry.registeredAt}}debug(category,data){this.slothlet.debug(category,data)}}export{PermissionManager};