@cldmv/slothlet 3.2.3 → 3.3.0

package/README.md

@@ -55,17 +55,18 @@ Every feature has been hardened with a comprehensive test suite - over **5,300 t
 
 ## ✨ What's New
 
-### Latest: v3.2.3 (April 2026)
+### Latest: v3.3.0 (April 2026)
 
-- **Publish workflow fix** — switched CI trigger from `pull_request` to `push` on master so releases publish immediately on merge without depending on the PR event payload
-- [View full v3.2.3 Changelog](./docs/changelog/v3/v3.2.3.md)
+- **Permission System** — path-based access control for inter-module calls with glob pattern rules, most-specific-wins evaluation, audit events, and runtime `api.slothlet.permissions.*` management API
+- **Shared pattern matcher** — extracted hook system's glob compilation into a shared utility for reuse across hooks and permissions
+- [View full v3.3.0 Changelog](./docs/changelog/v3/v3.3.0.md)
 
 ### Recent Releases
 
+- **v3.2.3** (April 2026) — publish workflow fix ([Changelog](./docs/changelog/v3/v3.2.3.md))
 - **v3.2.2** (April 2026) — missing `set` trap on version dispatchers; `util.inspect(api.auth)` now shows resolved versioned namespace ([Changelog](./docs/changelog/v3/v3.2.2.md))
 - **v3.2.1** (April 2026) — version-dispatcher `defineProperty` trap fix; pre-commit validation cleanup ([Changelog](./docs/changelog/v3/v3.2.1.md))
 - **v3.2.0** (April 2026) — API Path Versioning (`versionDispatcher`, `api.slothlet.versioning.*`, version metadata, dispatcher proxy); lazy-mode shutdown race fix ([Changelog](./docs/changelog/v3/v3.2.0.md))
-- **v3.1.0** (March 2026) — Frozen `api.slothlet.env` snapshot; `env.include` allowlist; reload immunity ([Changelog](./docs/changelog/v3/v3.1.0.md))
 
 
 📚 **For complete version history and detailed release notes, see [docs/changelog/](./docs/changelog/) folder.**
@@ -113,6 +114,19 @@ Each hook type supports three ordered execution **subsets**: `"before"` → `"pr
 
 🎣 **For complete hook system documentation, see [docs/HOOKS.md](https://github.com/CLDMV/slothlet/blob/master/docs/HOOKS.md)**
 
+### 🔐 **Permission System** _(new in v3.3)_
+
+Path-based access control for inter-module API calls:
+
+- **Glob pattern rules** — same `*`, `**`, `?`, `{a,b}` syntax as hooks
+- **Most-specific-wins** — exact patterns override broad globs; tiebreak by registration order
+- **Self-call bypass** — calls within the same source file always succeed
+- **Enforcement before hooks** — denied calls never trigger `before:` hooks or function execution
+- **Audit events** — `permission:denied`, `permission:allowed`, `permission:default`, `permission:self-bypass`
+- **Runtime management** — `api.slothlet.permissions.addRule()`, `.removeRule()`, `.self.*`, `.global.*`, `.control.*`
+
+🔐 **For complete permission system documentation, see [docs/PERMISSIONS.md](https://github.com/CLDMV/slothlet/blob/master/docs/PERMISSIONS.md)**
+
 ### 🌍 **Full Internationalization** _(new in v3)_
 
 All error messages and debug output are translated. Supported languages:
@@ -324,8 +338,9 @@ await api.slothlet.api.reload("database.*");
 | `hook`                    | `mixed`   | `false`       | Enable hook system: `true` (enable all), `"pattern"` (enable with pattern), or object with `enabled`, `pattern`, `suppressErrors` options - **note: `hook` singular, not `hooks`**                           |
 | `backgroundMaterialize`   | `boolean` | `false`       | In lazy mode: start background pre-loading of all modules immediately after init; automatically enables materialization tracking and the `materialized:complete` lifecycle event                              |
 | `api.collision`           | `mixed`   | `"merge"`     | Collision mode for API namespace conflicts: `"merge"`, `"skip"`, `"overwrite"`, `"throw"` - or `{ initial: "merge", api: "skip" }` to set independently for load vs runtime `add()`                          |
-| `api.mutations`           | `object`  | all `true`    | Per-operation mutation controls: `{ add: true, remove: true, reload: true }` - set any to `false` to disable                                                                                                 |
+| `api.mutations`           | `object`  | all `true`    | Per-operation mutation controls: `{ add: true, remove: true, reload: true, permissions: true }` - set any to `false` to disable                                                                              |
 | `versionDispatcher`       | `mixed`   | `undefined`   | Version routing discriminator: `"version"` (or any string key) looks up that key in the caller's version metadata; a function receives `(allVersions, caller)` and returns a tag or `null`; `undefined` behaves like `"version"` |
+| `permissions`             | `object`  | `undefined`   | Permission system config: `{ defaultPolicy: "allow"\|"deny", enabled: true, audit: "default"\|"verbose", rules: [...] }` — see [PERMISSIONS.md](./docs/PERMISSIONS.md)                                    |
 | `i18n`                    | `object`  | `{}`          | Internationalization settings: `{ language: "en" }` - supported: `en`, `es`, `fr`, `de`, `pt`, `it`, `ja`, `zh`, `ko`                                                                                       |
 
 ---

package/dist/lib/builders/api_builder.mjs

@@ -582,9 +582,7 @@ export class ApiBuilder extends ComponentBase {
 				setForVersion: function slothlet_metadata_setForVersion(logicalPath, versionTag, keyOrObj, value) {
 					if (!slothlet.handlers?.metadata) {
 						throw new slothlet.SlothletError("METADATA_NOT_AVAILABLE", {
-							handlersKeys: slothlet.handlers
-								? Object.keys(slothlet.handlers).join(", ")
-								: "undefined",
+							handlersKeys: slothlet.handlers ? Object.keys(slothlet.handlers).join(", ") : "undefined",
 							validationError: true
 						});
 					}
@@ -734,6 +732,238 @@ export class ApiBuilder extends ComponentBase {
 					if (!slothlet.handlers?.versionManager) return;
 					return slothlet.handlers.versionManager.setVersionMetadataByPath(logicalPath, versionTag, patch);
 				}
+			},
+
+			
+			permissions: {
+				
+				addRule: function slothlet_permissions_addRule(rule) {
+					
+					if (!config.api?.mutations?.permissions) {
+						throw new slothlet.SlothletError("INVALID_CONFIG_MUTATIONS_DISABLED", {
+							operation: "api.slothlet.permissions.addRule",
+							validationError: true
+						});
+					}
+
+					
+					const permissionManager = slothlet.handlers?.permissionManager;
+					
+					if (!permissionManager?.addRule) {
+						throw new slothlet.SlothletError("PERMISSION_MANAGER_NOT_AVAILABLE", {
+							validationError: true
+						});
+					}
+					
+
+					const ruleId = permissionManager.addRule(rule, null);
+
+					
+					if (slothlet.handlers?.apiManager?.state?.operationHistory) {
+						slothlet.handlers.apiManager.state.operationHistory.push({
+							type: "addPermissionRule",
+							rule,
+							ownerModuleID: null,
+							ruleId,
+							timestamp: Date.now()
+						});
+					}
+
+					return ruleId;
+				},
+
+				
+				removeRule: function slothlet_permissions_removeRule(ruleId) {
+					
+					if (!config.api?.mutations?.permissions) {
+						throw new slothlet.SlothletError("INVALID_CONFIG_MUTATIONS_DISABLED", {
+							operation: "api.slothlet.permissions.removeRule",
+							validationError: true
+						});
+					}
+
+					
+					const permissionManager = slothlet.handlers?.permissionManager;
+					
+					if (!permissionManager?.removeRule) {
+						throw new slothlet.SlothletError("PERMISSION_MANAGER_NOT_AVAILABLE", {
+							validationError: true
+						});
+					}
+					
+
+					const ctx = slothlet.contextManager?.tryGetContext?.();
+					const currentWrapper = ctx?.currentWrapper;
+					const callerModuleID = currentWrapper?.____slothletInternal?.moduleID ?? null;
+					const result = slothlet.handlers.permissionManager.removeRule(ruleId, callerModuleID);
+
+					
+					if (result && slothlet.handlers?.apiManager?.state?.operationHistory) {
+						slothlet.handlers.apiManager.state.operationHistory.push({
+							type: "removePermissionRule",
+							ruleId,
+							callerModuleID,
+							timestamp: Date.now()
+						});
+					}
+
+					return result;
+				},
+
+				
+				self: {
+					
+					access: function slothlet_permissions_self_access(target) {
+						
+						const permissionManager = slothlet.handlers?.permissionManager;
+						
+						if (!permissionManager?.checkAccess) {
+							throw new slothlet.SlothletError("PERMISSION_MANAGER_NOT_AVAILABLE", {
+								validationError: true
+							});
+						}
+						
+
+						const currentWrapper = slothlet.contextManager?.tryGetContext?.()?.currentWrapper;
+						const callerPath = currentWrapper?.____slothletInternal?.apiPath ?? "";
+						const callerFilePath = currentWrapper?.____slothletInternal?.filePath ?? null;
+						return slothlet.handlers.permissionManager.checkAccess(callerPath, target, callerFilePath, null);
+					},
+
+					
+					rules: function slothlet_permissions_self_rules() {
+						
+						const permissionManager = slothlet.handlers?.permissionManager;
+						
+						if (!permissionManager?.getRulesForCaller) {
+							throw new slothlet.SlothletError("PERMISSION_MANAGER_NOT_AVAILABLE", {
+								validationError: true
+							});
+						}
+						
+
+						const currentWrapper = slothlet.contextManager?.tryGetContext?.()?.currentWrapper;
+						const callerPath = currentWrapper?.____slothletInternal?.apiPath ?? "";
+						return slothlet.handlers.permissionManager.getRulesForCaller(callerPath);
+					}
+				},
+
+				
+				global: {
+					
+					checkAccess: function slothlet_permissions_global_checkAccess(caller, target) {
+						
+						const permissionManager = slothlet.handlers?.permissionManager;
+						
+						if (!permissionManager?.checkAccess) {
+							throw new slothlet.SlothletError("PERMISSION_MANAGER_NOT_AVAILABLE", {
+								validationError: true
+							});
+						}
+						
+
+						return slothlet.handlers.permissionManager.checkAccess(caller, target);
+					},
+
+					
+					rulesForPath: function slothlet_permissions_global_rulesForPath(path) {
+						
+						const permissionManager = slothlet.handlers?.permissionManager;
+						
+						if (!permissionManager?.getRulesForPath) {
+							throw new slothlet.SlothletError("PERMISSION_MANAGER_NOT_AVAILABLE", {
+								validationError: true
+							});
+						}
+						
+
+						return slothlet.handlers.permissionManager.getRulesForPath(path);
+					},
+
+					
+					rulesByModule: function slothlet_permissions_global_rulesByModule(moduleID) {
+						
+						const permissionManager = slothlet.handlers?.permissionManager;
+						
+						if (!permissionManager?.getRulesByModule) {
+							throw new slothlet.SlothletError("PERMISSION_MANAGER_NOT_AVAILABLE", {
+								validationError: true
+							});
+						}
+						
+
+						return slothlet.handlers.permissionManager.getRulesByModule(moduleID);
+					}
+				},
+
+				
+				control: {
+					
+					enable: function slothlet_permissions_control_enable() {
+						
+						const permissionManager = slothlet.handlers?.permissionManager;
+						
+						if (!permissionManager?.enable) {
+							throw new slothlet.SlothletError("PERMISSION_MANAGER_NOT_AVAILABLE", {
+								validationError: true
+							});
+						}
+						
+
+						
+						
+						const ctx = slothlet.contextManager?.tryGetContext?.();
+						const callerWrapper = ctx?.currentWrapper;
+						if (callerWrapper) {
+							
+							
+							const callerPath = callerWrapper.____slothletInternal?.apiPath ?? "";
+							const callerFilePath = callerWrapper.____slothletInternal?.filePath ?? null;
+							
+							if (!permissionManager.checkAccess(callerPath, "slothlet.permissions.control.enable", callerFilePath, null)) {
+								throw new slothlet.SlothletError("PERMISSION_DENIED", {
+									caller: callerPath,
+									target: "slothlet.permissions.control.enable"
+								});
+							}
+						}
+
+						slothlet.handlers.permissionManager.enable();
+					},
+
+					
+					disable: function slothlet_permissions_control_disable() {
+						
+						const permissionManager = slothlet.handlers?.permissionManager;
+						
+						if (!permissionManager?.disable) {
+							throw new slothlet.SlothletError("PERMISSION_MANAGER_NOT_AVAILABLE", {
+								validationError: true
+							});
+						}
+						
+
+						
+						
+						const ctx = slothlet.contextManager?.tryGetContext?.();
+						const callerWrapper = ctx?.currentWrapper;
+						if (callerWrapper) {
+							
+							
+							const callerPath = callerWrapper.____slothletInternal?.apiPath ?? "";
+							const callerFilePath = callerWrapper.____slothletInternal?.filePath ?? null;
+							
+							if (!permissionManager.checkAccess(callerPath, "slothlet.permissions.control.disable", callerFilePath, null)) {
+								throw new slothlet.SlothletError("PERMISSION_DENIED", {
+									caller: callerPath,
+									target: "slothlet.permissions.control.disable"
+								});
+							}
+						}
+
+						slothlet.handlers.permissionManager.disable();
+					}
+				}
 			}
 		};
 

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

@@ -1380,6 +1380,29 @@ export class ApiManager extends ComponentBase {
 			}
 		}
 
+		
+		if (restOptions.permissions && this.slothlet.handlers?.permissionManager) {
+			const perms = restOptions.permissions;
+			const callerPattern = `${normalizedPath}.**`;
+
+			if (Array.isArray(perms.deny)) {
+				for (const target of perms.deny) {
+					this.slothlet.handlers.permissionManager.addRule(
+						{ caller: callerPattern, target, effect: "deny" },
+						moduleID
+					);
+				}
+			}
+			if (Array.isArray(perms.allow)) {
+				for (const target of perms.allow) {
+					this.slothlet.handlers.permissionManager.addRule(
+						{ caller: callerPattern, target, effect: "allow" },
+						moduleID
+					);
+				}
+			}
+		}
+
 		return moduleID;
 	}
 

package/dist/lib/handlers/context-async.mjs

@@ -98,6 +98,8 @@ export class AsyncContextManager {
 					}
 					return result;
 				} catch (error) {
+					
+					if (error instanceof SlothletError) throw error;
 					throw new SlothletError(
 						"CONTEXT_EXECUTION_FAILED",
 						{
@@ -120,6 +122,8 @@ export class AsyncContextManager {
 				}
 				return result;
 			} catch (error) {
+				
+				if (error instanceof SlothletError) throw error;
 				throw new SlothletError(
 					"CONTEXT_EXECUTION_FAILED",
 					{

package/dist/lib/handlers/context-live.mjs

@@ -87,6 +87,9 @@ export class LiveContextManager {
 		const previousCallerWrapper = store.callerWrapper;
 
 		this.currentInstanceID = targetInstanceID;
+		
+		
+		
 		if (currentWrapper) {
 			store.callerWrapper = previousWrapper;
 			store.currentWrapper = currentWrapper;
@@ -95,6 +98,8 @@ export class LiveContextManager {
 		try {
 			return fn.apply(thisArg, args);
 		} catch (error) {
+			
+			if (error instanceof SlothletError) throw error;
 			throw new SlothletError(
 				"CONTEXT_EXECUTION_FAILED",
 				{

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

@@ -19,6 +19,7 @@
 
 
 import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+import { compilePattern } from "@cldmv/slothlet/helpers/pattern-matcher";
 
 
 
@@ -511,118 +512,11 @@ export class HookManager extends ComponentBase {
 
 	
 	#compilePattern(pattern) {
-		
-		const isNegation = pattern.startsWith("!");
-		if (isNegation) {
-			pattern = pattern.slice(1);
-			const matcher = this.#compilePattern(pattern);
-			return (path) => !matcher(path);
-		}
-
-		
-		const expanded = this.#expandBraces(pattern);
-		if (expanded.length > 1) {
-			
-			const matchers = expanded.map((p) => this.#compilePattern(p));
-			return (path) => matchers.some((m) => m(path));
-		}
-
-		
-		pattern = expanded[0];
-
-		
-		let regexPattern = pattern
-			.replace(/[+^$()|[\]\\]/g, "\\$&") 
-			.replace(/\*\*/g, "__DOUBLESTAR__") 
-			.replace(/\*/g, "[^.]*") 
-			.replace(/__DOUBLESTAR__/g, ".*") 
-			.replace(/\?/g, "."); 
-
-		regexPattern = `^${regexPattern}$`;
-		const regex = new RegExp(regexPattern);
-
-		return (path) => regex.test(path);
-	}
-
-	
-	#expandBraces(pattern, depth = 0, maxDepth = 10) {
-		
-		if (depth >= maxDepth) {
-			throw new this.SlothletError("HOOK_BRACE_EXPANSION_MAX_DEPTH", { maxDepth }, null, { validationError: true });
-		}
-
-		
-		const braceStart = pattern.indexOf("{");
-		if (braceStart === -1) {
-			return [pattern]; 
-		}
-
-		
-		let braceEnd = -1;
-		let depth_count = 1;
-		for (let i = braceStart + 1; i < pattern.length; i++) {
-			if (pattern[i] === "{") depth_count++;
-			if (pattern[i] === "}") {
-				depth_count--;
-				if (depth_count === 0) {
-					braceEnd = i;
-					break;
-				}
-			}
-		}
-
-		if (braceEnd === -1) {
-			return [pattern]; 
-		}
-
-		
-		const prefix = pattern.slice(0, braceStart);
-		const braceContent = pattern.slice(braceStart + 1, braceEnd);
-		const suffix = pattern.slice(braceEnd + 1);
-
-		
-		const alternatives = this.#splitBraceAlternatives(braceContent);
-
-		
-		const expanded = [];
-		for (const alt of alternatives) {
-			const combined = prefix + alt + suffix;
-			
-			const recursiveExpanded = this.#expandBraces(combined, depth + 1, maxDepth);
-			expanded.push(...recursiveExpanded);
-		}
-
-		return expanded;
-	}
-
-	
-	#splitBraceAlternatives(content) {
-		const alternatives = [];
-		let current = "";
-		let depth = 0;
-
-		for (let i = 0; i < content.length; i++) {
-			const char = content[i];
-
-			if (char === "{") {
-				depth++;
-				current += char;
-			} else if (char === "}") {
-				depth--;
-				current += char;
-			} else if (char === "," && depth === 0) {
-				alternatives.push(current);
-				current = "";
-			} else {
-				current += char;
+		return compilePattern(pattern, {
+			onMaxDepth: (maxDepth) => {
+				throw new this.SlothletError("HOOK_BRACE_EXPANSION_MAX_DEPTH", { maxDepth }, null, { validationError: true });
 			}
-		}
-
-		if (current) {
-			alternatives.push(current);
-		}
-
-		return alternatives;
+		});
 	}