simple-authz 1.0.3 → 1.0.5

package/README.md

@@ -8,26 +8,36 @@ The goal of this project is to make authorization **simple, fast, readable, and
 
 ---
 
+## ⚠️ Development Status
+
+**simple-authz** is currently under active development.
+
+Some features may change, and there may be inconsistencies between the documentation and the package behavior.
+
+We recommend testing thoroughly before using it in production.
+
+---
+
 # Table of Contents
 
-* Overview
-* Why Simple Authz
-* Key Features
-* Installation
-* Quick Start
-* Core Concepts
-* Policy Language (TOON)
-* Policy Examples
-* Using Conditions
-* Working with Roles
-* Authorization API
-* Example Integrations
-* Project Structure
-* Performance
-* Security Model
-* Roadmap
-* Contributing
-* License
+- Overview
+- Why Simple Authz
+- Key Features
+- Installation
+- Quick Start
+- Core Concepts
+- Policy Language (TOON)
+- Policy Examples
+- Using Conditions
+- Working with Roles
+- Authorization API
+- Example Integrations
+- Project Structure
+- Performance
+- Security Model
+- Roadmap
+- Contributing
+- License
 
 ---
 
@@ -48,20 +58,30 @@ Over time this logic spreads across many files and becomes difficult to maintain
 Example policy file:
 
 ```
-allow admin *
+rule
+  role admin
+  action *
+  resource *
+end
 
-allow user view listing
+rule
+  role broker
+  action publish
+  resource listing
+end
 
-allow broker publish listing
-
-allow broker edit listing
-condition listing.owner_id == user.id
+rule
+  role user
+  action edit
+  resource listing
+  condition listing.owner_id == user.id
+end
 ```
 
 Your application then only needs to ask:
 
 ```javascript
-authz.can(user, "edit", "listing", listing)
+authz.can(user, "edit", "listing", listing);
 ```
 
 ---
@@ -70,24 +90,24 @@ authz.can(user, "edit", "listing", listing)
 
 Benefits of centralized authorization:
 
-* Clear separation between **business logic and security rules**
-* Easy permission updates without touching application code
-* Better maintainability for large projects
-* Safer and more predictable access control
-* Easier onboarding for new developers
+- Clear separation between **business logic and security rules**
+- Easy permission updates without touching application code
+- Better maintainability for large projects
+- Safer and more predictable access control
+- Easier onboarding for new developers
 
 ---
 
 # Key Features
 
-* Simple and readable **policy language**
-* Fast permission lookup
-* Support for **multiple user roles**
-* Logical **conditional rules**
-* Policy **validation**
-* Policy **AST compilation**
-* Lightweight with minimal dependencies
-* Works with any Node.js framework
+- Simple and readable **policy language**
+- Fast permission lookup
+- Support for **multiple user roles**
+- Logical **conditional rules**
+- Policy **validation**
+- Policy **AST compilation**
+- Lightweight with minimal dependencies
+- Works with any Node.js framework
 
 ---
 
@@ -106,9 +126,9 @@ npm install simple-authz
 ## 1. Import the library
 
 ```javascript
-const Authz = require("simple-authz")
+const Authz = require("simple-authz");
 
-const authz = new Authz()
+const authz = new Authz();
 ```
 
 ---
@@ -124,14 +144,24 @@ authz.toon
 Example policy:
 
 ```
-allow admin *
-
-allow user view listing
+rule
+  role admin
+  action *
+  resource *
+end
 
-allow broker publish listing
+rule
+  role broker
+  action publish
+  resource listing
+end
 
-allow broker edit listing
-condition listing.owner_id == user.id
+rule
+  role user
+  action edit
+  resource listing
+  condition listing.owner_id == user.id
+end
 ```
 
 ---
@@ -139,7 +169,7 @@ condition listing.owner_id == user.id
 ## 3. Load the policy
 
 ```javascript
-authz.load("./authz.toon")
+authz.load("./authz.toon");
 ```
 
 ---
@@ -147,21 +177,66 @@ authz.load("./authz.toon")
 ## 4. Check permissions
 
 ```javascript
-const allowed = authz.can(user, "edit", "listing", listing)
+const allowed = authz.can(user, "edit", "listing", listing);
 ```
 
 Example usage:
 
 ```javascript
-if(authz.can(user,"edit","listing",listing)){
-    updateListing()
-}else{
-    throw new Error("Access denied")
+if (authz.can(user, "edit", "listing", listing)) {
+  updateListing();
+} else {
+  throw new Error("Access denied");
 }
 ```
 
 ---
 
+## 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:
@@ -191,15 +266,34 @@ Policies are written in **TOON format**.
 Basic rule syntax:
 
 ```
-allow <role> <action> <resource>
+rule
+  role <Role>
+  action <Action>
+  resource <Resource>
+end
 ```
 
 Example:
 
 ```
-allow admin *
-allow user view listing
-allow broker publish listing
+rule
+  role admin
+  action *
+  resource *
+end
+
+rule
+  role broker
+  action publish
+  resource listing
+end
+
+rule
+  role user
+  action edit
+  resource listing
+  condition listing.owner_id == user.id
+end
 ```
 
 ---
@@ -211,7 +305,11 @@ You can use `*` to allow everything.
 Example:
 
 ```
-allow admin *
+rule
+  role admin
+  action *
+  resource *
+end
 ```
 
 This allows the admin role to perform **any action on any resource**.
@@ -225,15 +323,23 @@ Policies can include conditions.
 Syntax:
 
 ```
-allow <role> <action> <resource>
-condition <condition>
+rule
+  role <role>
+  action <action>
+  resource <resource>
+  condition <condition1> OR <condition2>
+end
 ```
 
 Example:
 
 ```
-allow broker edit listing
-condition listing.owner_id == user.id
+rule
+  role user
+  action view
+  resource listing
+  condition listing.status == "public" OR listing.owner_id == user.id
+end
 ```
 
 Meaning:
@@ -255,8 +361,12 @@ Conditions can reference:
 Example:
 
 ```
-allow user edit profile
-condition user.id == resource.id
+rule
+  role user
+  action edit
+  resource profile
+  condition user.id == resource.id
+end
 ```
 
 ---
@@ -266,11 +376,23 @@ condition user.id == resource.id
 ## Example 1 – Basic Roles
 
 ```
-allow admin *
+rule
+  role admin
+  action *
+  resource *
+end
 
-allow user view listing
+rule
+  role broker
+  action publish
+  resource listing
+end
 
-allow broker publish listing
+rule
+  role user
+  action edit
+  resource listing
+end
 ```
 
 ---
@@ -278,8 +400,12 @@ allow broker publish listing
 ## Example 2 – Ownership Rules
 
 ```
-allow broker edit listing
-condition listing.owner_id == user.id
+rule
+  role broker
+  action edit
+  resource listing
+  condition listing.owner_id == user.id
+end
 ```
 
 ---
@@ -287,14 +413,24 @@ condition listing.owner_id == user.id
 ## Example 3 – Multiple Rules
 
 ```
-allow admin *
-
-allow user view listing
+rule
+  role admin
+  action *
+  resource *
+end
 
-allow broker publish listing
+rule
+  role broker
+  action publish
+  resource listing
+end
 
-allow broker edit listing
-condition listing.owner_id == user.id
+rule
+  role user
+  action edit
+  resource listing
+  condition listing.owner_id == user.id
+end
 ```
 
 ---
@@ -307,18 +443,18 @@ Example user:
 
 ```javascript
 const user = {
-    id: 10,
-    roles: ["broker"]
-}
+  id: 10,
+  roles: ["broker"],
+};
 ```
 
 Multiple roles:
 
 ```javascript
 const user = {
-    id: 5,
-    roles: ["user","editor"]
-}
+  id: 5,
+  roles: ["user", "editor"],
+};
 ```
 
 The engine checks permissions against **all roles**.
@@ -330,7 +466,7 @@ The engine checks permissions against **all roles**.
 ## Load policy file
 
 ```javascript
-authz.load("./authz.toon")
+authz.load("./authz.toon");
 ```
 
 ---
@@ -338,13 +474,13 @@ authz.load("./authz.toon")
 ## Check permission
 
 ```javascript
-authz.can(user, action, resource, object)
+authz.can(user, action, resource, object);
 ```
 
 Example:
 
 ```javascript
-authz.can(user,"edit","listing",listing)
+authz.can(user, "edit", "listing", listing);
 ```
 
 Returns:
@@ -365,22 +501,22 @@ User:
 ```javascript
 const user = {
   id: 10,
-  roles: ["broker"]
-}
+  roles: ["broker"],
+};
 ```
 
 Listing:
 
 ```javascript
 const listing = {
-  owner_id: 10
-}
+  owner_id: 10,
+};
 ```
 
 Permission check:
 
 ```javascript
-authz.can(user,"edit","listing",listing)
+authz.can(user, "edit", "listing", listing);
 ```
 
 Result:
@@ -396,21 +532,15 @@ true
 Example route protection:
 
 ```javascript
-app.put("/listing/:id", async (req,res)=>{
+app.put("/listing/:id", async (req, res) => {
+  const allowed = authz.can(req.user, "edit", "listing", req.listing);
 
-    const allowed = authz.can(
-        req.user,
-        "edit",
-        "listing",
-        req.listing
-    )
+  if (!allowed) {
+    return res.status(403).send("Access denied");
+  }
 
-    if(!allowed){
-        return res.status(403).send("Access denied")
-    }
-
-    updateListing()
-})
+  updateListing();
+});
 ```
 
 ---
@@ -465,13 +595,13 @@ This reduces the risk of unintended access.
 
 Future versions may include:
 
-* Policy hot reloading
-* Role inheritance
-* Policy debugger
-* Middleware helpers
-* Permission caching
-* Modular policy files
-* Distributed policy storage
+- Policy hot reloading
+- Role inheritance
+- Policy debugger
+- Middleware helpers
+- Permission caching
+- Modular policy files
+- Distributed policy storage
 
 ---
 
@@ -498,5 +628,4 @@ This project is licensed under the [Apache 2.0 license](LICENSE).
 
 Simple Authz was created to simplify authorization logic in modern Node.js applications.
 
-
-# Keywords
+# Keywords

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.3",
-  "description": "Simple authorization engine with TOON policy language",
-  "main": "lib/core/authz.js",
+  "version": "1.0.5",
+  "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"
 }