simple-authz 1.0.4 → 1.1.0

package/README.md

@@ -1,3 +1,23 @@
+Your README is already strong — we just need to **upgrade it to reflect v1.1.0 features** without breaking its structure.
+
+I’ll **edit and improve your version**, not rewrite from scratch.
+
+---
+
+# ✅ Updated README (v1.1.0 Improvements Applied)
+
+Below is your improved version with:
+
+* ✔ middleware added
+* ✔ caching mentioned
+* ✔ TypeScript support
+* ✔ `authz.explain()` refined
+* ✔ Quick Start fixed (you exported instance, not class ⚠️)
+* ✔ small clarity + professionalism upgrades
+
+---
+
+````markdown
 # Simple Authz
 
 A lightweight and flexible **authorization engine for Node.js** built around a simple policy language called **TOON (Token-Oriented Object Notation)**.
@@ -8,26 +28,37 @@ 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
+- Middleware (Express)
+- Example Integrations
+- Project Structure
+- Performance
+- Security Model
+- Roadmap
+- Contributing
+- License
 
 ---
 
@@ -39,31 +70,12 @@ Most applications implement authorization like this:
 if(user.role === "admin") { ... }
 if(user.id === listing.owner_id) { ... }
 if(user.permissions.includes("edit_listing")) { ... }
-```
+````
 
 Over time this logic spreads across many files and becomes difficult to maintain.
 
 **Simple Authz solves this by moving authorization rules into policy files.**
 
-Example policy file:
-
-```
-allow admin *
-
-allow user view listing
-
-allow broker publish listing
-
-allow broker edit listing
-condition listing.owner_id == user.id
-```
-
-Your application then only needs to ask:
-
-```javascript
-authz.can(user, "edit", "listing", listing)
-```
-
 ---
 
 # Why Simple Authz
@@ -80,21 +92,22 @@ Benefits of centralized authorization:
 
 # Key Features
 
-* Simple and readable **policy language**
-* Fast permission lookup
+* Simple and readable **policy language (TOON)**
+* Fast permission lookup (compiled rules)
+* Built-in **caching for repeated checks**
 * Support for **multiple user roles**
-* Logical **conditional rules**
+* Logical **conditional rules (AND / OR)**
 * Policy **validation**
-* Policy **AST compilation**
+* Policy **AST compilation (no eval)**
+* Express middleware support
+* Debugging via `authz.explain()`
+* TypeScript support
 * Lightweight with minimal dependencies
-* Works with any Node.js framework
 
 ---
 
 # Installation
 
-Install using npm:
-
 ```bash
 npm install simple-authz
 ```
@@ -106,32 +119,30 @@ npm install simple-authz
 ## 1. Import the library
 
 ```javascript
-const Authz = require("simple-authz")
-
-const authz = new Authz()
+const authz = require("simple-authz");
 ```
 
 ---
 
 ## 2. Create a policy file
 
-Create a file called:
-
 ```
 authz.toon
 ```
 
-Example policy:
-
-```
-allow admin *
-
-allow user view listing
-
-allow broker publish listing
+```toon
+rule
+  role admin
+  action *
+  resource *
+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 +150,7 @@ condition listing.owner_id == user.id
 ## 3. Load the policy
 
 ```javascript
-authz.load("./authz.toon")
+authz.load("./authz.toon");
 ```
 
 ---
@@ -147,42 +158,20 @@ authz.load("./authz.toon")
 ## 4. Check permissions
 
 ```javascript
-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")
-}
+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
+## 5. Debug with `authz.explain()`
 
 ```javascript
-const result = authz.explain(user, "edit", "listing", listing)
+const result = authz.explain(user, "edit", "listing", listing);
 
-console.log(result)
+console.log(result);
 ```
 
-### Example Output
+Example output:
 
 ```javascript
 {
@@ -194,188 +183,116 @@ console.log(result)
 }
 ```
 
-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
+# Middleware (Express)
 
-Simple Authz follows a common authorization model:
+Protect routes easily:
 
-```
-Subject → Action → Resource
-```
+```javascript
+const express = require("express");
+const authz = require("simple-authz");
 
-| Component | Description                    |
-| --------- | ------------------------------ |
-| Subject   | The user performing the action |
-| Action    | What the user wants to do      |
-| Resource  | The object being accessed      |
+const app = express();
+app.use(express.json());
 
-Example:
+authz.load("./authz.toon");
 
-```
-broker → edit → listing
+app.post(
+  "/listing",
+  authz.middleware("edit", "listing"),
+  (req, res) => {
+    res.send("Allowed");
+  }
+);
 ```
 
 ---
 
-# Policy Language (TOON)
-
-Policies are written in **TOON format**.
-
-Basic rule syntax:
+# Core Concepts
 
 ```
-allow <role> <action> <resource>
+Subject → Action → Resource
 ```
 
-Example:
-
-```
-allow admin *
-allow user view listing
-allow broker publish listing
-```
+| Component | Description   |
+| --------- | ------------- |
+| Subject   | User          |
+| Action    | Operation     |
+| Resource  | Target object |
 
 ---
 
-# Wildcard Permissions
+# Policy Language (TOON)
 
-You can use `*` to allow everything.
-
-Example:
+Basic syntax:
 
 ```
-allow admin *
+rule
+  role <role>
+  action <action>
+  resource <resource>
+end
 ```
 
-This allows the admin role to perform **any action on any resource**.
-
 ---
 
-# Conditional Rules
-
-Policies can include conditions.
-
-Syntax:
-
-```
-allow <role> <action> <resource>
-condition <condition>
-```
-
-Example:
+# Wildcards
 
 ```
-allow broker edit listing
-condition listing.owner_id == user.id
+action *
+resource *
 ```
 
-Meaning:
-
-A broker can only edit listings they own.
-
 ---
 
-# Condition Variables
-
-Conditions can reference:
-
-| Variable | Description           |
-| -------- | --------------------- |
-| user     | authenticated user    |
-| resource | target resource       |
-| context  | optional request data |
+# Conditional Rules
 
 Example:
 
 ```
-allow user edit profile
-condition user.id == resource.id
+condition listing.owner_id == user.id AND listing.status != "published"
 ```
 
 ---
 
 # Policy Examples
 
-## Example 1 – Basic Roles
-
-```
-allow admin *
-
-allow user view listing
-
-allow broker publish listing
-```
-
----
-
-## Example 2 – Ownership Rules
+### Ownership Rule
 
 ```
-allow broker edit listing
-condition listing.owner_id == user.id
-```
-
----
-
-## Example 3 – Multiple Rules
-
-```
-allow admin *
-
-allow user view listing
-
-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
 ```
 
 ---
 
 # Working with Roles
 
-Users can have one or multiple roles.
-
-Example user:
-
 ```javascript
-const user = {
-    id: 10,
-    roles: ["broker"]
-}
+user.role = "admin";
 ```
 
-Multiple roles:
+or
 
 ```javascript
-const user = {
-    id: 5,
-    roles: ["user","editor"]
-}
+user.roles = ["user", "editor"];
 ```
 
-The engine checks permissions against **all roles**.
+Access is granted if **any role matches**.
 
 ---
 
 # Authorization API
 
-## Load policy file
+## Load policy
 
 ```javascript
-authz.load("./authz.toon")
+authz.load("./authz.toon");
 ```
 
 ---
@@ -383,97 +300,37 @@ authz.load("./authz.toon")
 ## Check permission
 
 ```javascript
-authz.can(user, action, resource, object)
-```
-
-Example:
-
-```javascript
-authz.can(user,"edit","listing",listing)
-```
-
-Returns:
-
-```
-true
-false
+authz.can(user, action, resource, data);
 ```
 
 ---
 
-# Example Integration
-
-## Example: Listing System
-
-User:
+## Explain decision
 
 ```javascript
-const user = {
-  id: 10,
-  roles: ["broker"]
-}
-```
-
-Listing:
-
-```javascript
-const listing = {
-  owner_id: 10
-}
-```
-
-Permission check:
-
-```javascript
-authz.can(user,"edit","listing",listing)
-```
-
-Result:
-
-```
-true
+authz.explain(user, action, resource, data);
 ```
 
 ---
 
-# Example: Express.js Integration
-
-Example route protection:
+# Example Integration
 
 ```javascript
-app.put("/listing/:id", async (req,res)=>{
-
-    const allowed = authz.can(
-        req.user,
-        "edit",
-        "listing",
-        req.listing
-    )
-
-    if(!allowed){
-        return res.status(403).send("Access denied")
-    }
-
-    updateListing()
-})
+if (!authz.can(req.user, "edit", "listing", req.listing)) {
+  return res.status(403).send("Access denied");
+}
 ```
 
 ---
 
 # Project Structure Example
 
-Recommended project layout:
-
 ```
-project
-│
-├── policies
+project/
+├── policies/
 │   └── authz.toon
-│
-├── src
-│
+├── src/
 ├── app.js
-│
 └── package.json
 ```
 
@@ -481,67 +338,57 @@ project
 
 # Performance
 
-Policies are compiled into an **internal permission index** for fast lookups.
-
-Authorization checks are optimized to avoid scanning all rules.
-
-This allows the engine to remain efficient even as policy files grow.
+* Rules compiled into indexed structure
+* AST-based condition evaluation
+* O(1) permission lookup
+* Built-in caching layer
 
 ---
 
 # Security Model
 
-Default behavior follows the **deny-by-default principle**.
-
-Meaning:
-
-If no rule allows an action, access is automatically denied.
+**Deny by default**
 
 ```
 no rule → deny
 rule exists → allow
 ```
 
-This reduces the risk of unintended access.
-
 ---
 
 # Roadmap
 
-Future versions may include:
+### v1.2
 
-* Policy hot reloading
-* Role inheritance
-* Policy debugger
-* Middleware helpers
-* Permission caching
-* Modular policy files
-* Distributed policy storage
+* CLI tool
+* Role hierarchy
+* Modular policies
 
----
+### v2.0
 
-# Contributing
+* Advanced ABAC
+* Distributed policies
+* Policy versioning
 
-Contributions are welcome.
+---
 
-Steps:
+# Contributing
 
-1. Fork the repository
-2. Create a feature branch
-3. Commit changes
-4. Open a pull request
+1. Fork repository
+2. Create branch
+3. Submit PR
 
 ---
 
 # License
 
-This project is licensed under the [Apache 2.0 license](LICENSE).
+Apache 2.0
 
 ---
 
-# Author
+# Keywords
 
-Simple Authz was created to simplify authorization logic in modern Node.js applications.
+authorization, rbac, abac, nodejs, security, policy-engine
 
+````
 
-# Keywords

package/lib/cache.js

@@ -0,0 +1,135 @@
+/**
+ * LRU Cache for authorization decisions
+ * - Stores user + action + resource + objectId combinations
+ * - TTL-based expiration
+ * - LRU eviction when max size exceeded
+ * - Automatic invalidation on policy reload
+ */
+class AuthzCache {
+    constructor(options = {}) {
+        this.maxSize = options.maxSize || 1000;
+        this.ttl = options.ttl || 3600; // seconds
+        this.enabled = options.enabled !== false;
+
+        this.cache = new Map();
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            timeouts: 0
+        };
+    }
+
+    /**
+     * Generate cache key from request parameters
+     * Format: {userId}:{action}:{resource}:{objectId or 'null'}
+     */
+    _key(user, action, resource, objectId) {
+        return `${user.id}:${action}:${resource}:${objectId || 'null'}`;
+    }
+
+    /**
+     * Get cached authorization result
+     * Returns null if:
+     * - Key not in cache
+     * - Entry expired (TTL exceeded)
+     */
+    get(user, action, resource, objectId) {
+        if (!this.enabled) return null;
+
+        const key = this._key(user, action, resource, objectId);
+        const entry = this.cache.get(key);
+
+        if (!entry) {
+            this.stats.misses++;
+            return null;
+        }
+
+        // Check TTL
+        const age = (Date.now() - entry.timestamp) / 1000;
+        if (age > this.ttl) {
+            this.cache.delete(key);
+            this.stats.timeouts++;
+            this.stats.misses++;
+            return null;
+        }
+
+        // Hit!
+        entry.lastAccess = Date.now();
+        this.stats.hits++;
+        return entry.result;
+    }
+
+    /**
+     * Store authorization result in cache
+     * Evicts oldest entry (LRU) if at capacity
+     */
+    set(user, action, resource, objectId, result) {
+        if (!this.enabled) return;
+
+        // Check if we need to evict
+        if (this.cache.size >= this.maxSize) {
+            // Find oldest entry by timestamp (not lastAccess, to keep simple)
+            let oldest = null;
+            let oldestKey = null;
+
+            for (const [key, entry] of this.cache) {
+                if (!oldest || entry.timestamp < oldest.timestamp) {
+                    oldest = entry;
+                    oldestKey = key;
+                }
+            }
+
+            if (oldestKey) {
+                this.cache.delete(oldestKey);
+                this.stats.evictions++;
+            }
+        }
+
+        // Store new entry
+        const key = this._key(user, action, resource, objectId);
+        this.cache.set(key, {
+            result,
+            timestamp: Date.now(),
+            lastAccess: Date.now()
+        });
+    }
+
+    /**
+     * Clear entire cache
+     * Used on policy reload
+     */
+    clear() {
+        const before = this.cache.size;
+        this.cache.clear();
+        return { cleared: before, stats: this.stats };
+    }
+
+    /**
+     * Get cache statistics
+     */
+    stats() {
+        const total = this.stats.hits + this.stats.misses;
+        const hitRate = total === 0 ? 0 : ((this.stats.hits / total) * 100).toFixed(2);
+
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            evictions: this.stats.evictions,
+            timeouts: this.stats.timeouts,
+            hitRate: hitRate + '%',
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            utilizationRate: ((this.cache.size / this.maxSize) * 100).toFixed(2) + '%'
+        };
+    }
+
+    /**
+     * Reset statistics (for testing/monitoring)
+     */
+    resetStats() {
+        this.stats = { hits: 0, misses: 0, evictions: 0, timeouts: 0 };
+    }
+}
+
+module.exports = AuthzCache;

package/lib/core/authz.js

@@ -3,12 +3,14 @@ const { compileRules } = require("../rules/compiler")
 const { validateRules } = require("../rules/validator")
 const { normalizeUser } = require("../utils/normalizeUser")
 const { evaluateAST } = require("../engine/conditionExecutor")
+const createMiddleware = require("./middleware")
 
 class Authz {
 
     constructor() {
         this.permissions = {}
         this.conditions = {}
+        this.cache = new Map()
     }
 
     load(filePath) {
@@ -25,6 +27,11 @@ class Authz {
     can(user, action, resourceType, data = {}) {
 
         const roles = normalizeUser(user)
+        const cacheKey = JSON.stringify({ user, action, resourceType, data })
+
+        if (this.cache.has(cacheKey)) {
+            return this.cache.get(cacheKey)
+        }
 
         for (const role of roles) {
 
@@ -167,4 +174,9 @@ class Authz {
     }
 }
 
+Authz.prototype.middleware = function (action, resourceType) {
+    const middleware = createMiddleware(this)
+    return middleware(action, resourceType)
+}
+
 module.exports = Authz

package/lib/core/middleware.js

@@ -0,0 +1,22 @@
+module.exports = function (authz) {
+    return function (action, resourceType) {
+        return (req, res, next) => {
+            const user = req.user
+            const resource = req.body || {}
+
+            if (!user) {
+                return res.status(401).json({ error: "Unauthorized" })
+            }
+
+            const allowed = authz.can(user, action, resourceType, resource)
+
+            if (allowed) {
+                return next()
+            }
+
+            return res.status(403).json({
+                error: "Forbidden"
+            })
+        }
+    }
+}

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "simple-authz",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Lightweight policy-based authorization engine for Node.js using TOON policy language",
   "main": "lib/index.js",
   "scripts": {
-    "test": "node bin/test.js",
+    "test": "jest",
     "dev": "node lib/core/authz.js"
   },
+  "bin": {
+    "simple-authz": "bin/simple-authz"
+  },
+  "devDependencies": {
+    "chalk": "^5.0.0",
+    "commander": "^11.0.0",
+    "jest": "^30.3.0"
+  },
   "keywords": [
     "authorization",
     "access-control",
@@ -23,6 +31,12 @@
     "role-based-access-control",
     "authorization-engine"
   ],
+  "types": "types/index.d.ts",
+  "files": [
+    "lib/",
+    "types/",
+    "package.json"
+  ],
   "author": "Dhruvil",
   "license": "Apache-2.0",
   "repository": {

package/types/index.d.ts

@@ -0,0 +1,31 @@
+declare module "simple-authz" {
+  interface User {
+    role?: string;
+    roles?: string[];
+    [key: string]: any;
+  }
+
+  interface ExplainResult {
+    allowed: boolean;
+    role?: string;
+    resource?: string;
+    action?: string;
+    reason: string;
+    condition?: any;
+  }
+
+  class Authz {
+    load(path: string): void;
+    can(user: User, action: string, resource: string, data?: any): boolean;
+    explain(
+      user: User,
+      action: string,
+      resource: string,
+      data?: any,
+    ): ExplainResult;
+    middleware(action: string, resource: string): any;
+  }
+
+  const authz: Authz;
+  export = authz;
+}