simple-authz 1.0.2 → 1.0.4

package/README.md

@@ -153,7 +153,7 @@ const allowed = authz.can(user, "edit", "listing", listing)
 Example usage:
 
 ```javascript
-if(authz.can(user,"edit","listing",listing)){
+if(authz.can(user,"edit", "listing", listing)){
     updateListing()
 }else{
     throw new Error("Access denied")
@@ -162,6 +162,51 @@ if(authz.can(user,"edit","listing",listing)){
 
 ---
 
+## 5. `authz.explain()` (Optional)
+
+The `authz.explain()` method helps debug authorization decisions by returning detailed information about **why access was allowed or denied**.
+
+Unlike `authz.can()`, which returns only `true` or `false`, this method returns an object explaining the result.
+
+### Usage
+
+```javascript
+authz.explain(user, "edit", "listing", listing)
+```
+
+### Example
+
+```javascript
+const result = authz.explain(user, "edit", "listing", listing)
+
+console.log(result)
+```
+
+### Example Output
+
+```javascript
+{
+  allowed: true,
+  role: "user",
+  resource: "listing",
+  action: "edit",
+  reason: "condition passed"
+}
+```
+
+If no rule matches:
+
+```javascript
+{
+  allowed: false,
+  reason: "no matching rule"
+}
+```
+
+Use `authz.explain()` for **debugging and development**, and `authz.can()` for **regular authorization checks**.
+
+---
+
 # Core Concepts
 
 Simple Authz follows a common authorization model:
@@ -490,7 +535,7 @@ Steps:
 
 # License
 
-MIT License
+This project is licensed under the [Apache 2.0 license](LICENSE).
 
 ---
 

package/lib/core/authz.js

@@ -76,6 +76,95 @@ class Authz {
 
         return false
     }
+
+    explain(user, action, resourceType, data = {}) {
+
+        const roles = normalizeUser(user)
+
+        for (const role of roles) {
+
+            const rolePerm = this.permissions[role]
+
+            // ---------- Permission check ----------
+            if (rolePerm) {
+
+                const resourcePerm = rolePerm[resourceType]
+
+                if (resourcePerm) {
+
+                    if (resourcePerm.has("*") || resourcePerm.has(action)) {
+                        return {
+                            allowed: true,
+                            role,
+                            resource: resourceType,
+                            action,
+                            reason: "direct permission match"
+                        }
+                    }
+                }
+
+                if (rolePerm["*"]) {
+                    if (rolePerm["*"].has("*") || rolePerm["*"].has(action)) {
+                        return {
+                            allowed: true,
+                            role,
+                            resource: "*",
+                            action,
+                            reason: "wildcard permission"
+                        }
+                    }
+                }
+            }
+
+            // ---------- Condition check ----------
+            const roleCond = this.conditions[role]
+
+            if (!roleCond) continue
+
+            const resourceCond = roleCond[resourceType]
+
+            if (!resourceCond) continue
+
+            const actionCond = resourceCond[action]
+
+            if (!actionCond) continue
+
+            for (const cond of actionCond) {
+
+                const context = {
+                    user,
+                    [resourceType]: data
+                }
+
+                const result = evaluateAST(cond, context)
+
+                if (result) {
+                    return {
+                        allowed: true,
+                        role,
+                        resource: resourceType,
+                        action,
+                        reason: "condition passed",
+                        condition: cond
+                    }
+                }
+            }
+
+            return {
+                allowed: false,
+                role,
+                resource: resourceType,
+                action,
+                reason: "condition failed"
+            }
+
+        }
+
+        return {
+            allowed: false,
+            reason: "no matching rule"
+        }
+    }
 }
 
 module.exports = Authz

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "simple-authz",
-  "version": "1.0.2",
-  "description": "Simple authorization engine with TOON policy language",
-  "main": "lib/core/authz.js",
+  "version": "1.0.4",
+  "description": "Lightweight policy-based authorization engine for Node.js using TOON policy language",
+  "main": "lib/index.js",
   "scripts": {
     "test": "node bin/test.js",
     "dev": "node lib/core/authz.js"
@@ -28,5 +28,9 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/dhruvil05/simple-authz"
-  }
+  },
+  "bugs": {
+    "url": "https://github.com/dhruvil05/simple-authz/issues"
+  },
+  "homepage": "https://github.com/dhruvil05/simple-authz#readme"
 }