simple-authz 1.0.5 → 1.2.0

package/README.md

@@ -1,3 +1,5 @@
+---
+
 # Simple Authz
 
 A lightweight and flexible **authorization engine for Node.js** built around a simple policy language called **TOON (Token-Oriented Object Notation)**.
@@ -31,6 +33,7 @@ We recommend testing thoroughly before using it in production.
 - Using Conditions
 - Working with Roles
 - Authorization API
+- Middleware (Express)
 - Example Integrations
 - Project Structure
 - Performance
@@ -55,66 +58,38 @@ 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:
-
-```
-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
-```
-
-Your application then only needs to ask:
-
-```javascript
-authz.can(user, "edit", "listing", listing);
-```
-
 ---
 
 # Why Simple Authz
 
 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 (TOON)**
+* Fast permission lookup (compiled rules)
+* Built-in **caching for repeated checks**
+* Support for **multiple user roles**
+* Logical **conditional rules (AND / OR)**
+* Policy **validation**
+* Policy **AST compilation (no eval)**
+* Express middleware support
+* Debugging via `authz.explain()`
+* TypeScript support
+* Lightweight with minimal dependencies
 
 ---
 
 # Installation
 
-Install using npm:
-
 ```bash
 npm install simple-authz
 ```
@@ -126,36 +101,24 @@ 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:
-
-```
+```toon
 rule
   role admin
   action *
   resource *
 end
 
-rule
-  role broker
-  action publish
-  resource listing
-end
-
 rule
   role user
   action edit
@@ -177,34 +140,12 @@ 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);
@@ -212,7 +153,7 @@ const result = authz.explain(user, "edit", "listing", listing);
 console.log(result);
 ```
 
-### Example Output
+Example output:
 
 ```javascript
 {
@@ -224,207 +165,125 @@ 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
-
-Simple Authz follows a common authorization model:
-
-```
-Subject → Action → Resource
-```
-
-| Component | Description                    |
-| --------- | ------------------------------ |
-| Subject   | The user performing the action |
-| Action    | What the user wants to do      |
-| Resource  | The object being accessed      |
-
-Example:
-
-```
-broker → edit → listing
-```
-
 ---
 
-# Policy Language (TOON)
-
-Policies are written in **TOON format**.
+# Middleware (Express)
 
-Basic rule syntax:
+Protect routes easily:
 
-```
-rule
-  role <Role>
-  action <Action>
-  resource <Resource>
-end
-```
+```javascript
+const express = require("express");
+const authz = require("simple-authz");
 
-Example:
+const app = express();
+app.use(express.json());
 
-```
-rule
-  role admin
-  action *
-  resource *
-end
-
-rule
-  role broker
-  action publish
-  resource listing
-end
+authz.load("./authz.toon");
 
-rule
-  role user
-  action edit
-  resource listing
-  condition listing.owner_id == user.id
-end
-```
+app.post(
+  "/listing",
+  authz.middleware("edit", "listing"),
+  (req, res) => {
+    res.send("Allowed");
+  }
+);
+```
+
+> ⚠️ **Security note:** by default the middleware checks against `req.body`.
+> That's fine for actions where the body *is* the thing being created, but
+> if your policy has conditions like `listing.owner_id == user.id`, a client
+> can put whatever `owner_id` it wants in its own request body and bypass
+> the check. Pass a third argument — an (optionally async) function that
+> loads the **real** resource from your database — whenever a condition
+> depends on data the client shouldn't be trusted to supply:
+>
+> ```javascript
+> app.post(
+>   "/listing/:id",
+>   authz.middleware("edit", "listing", async (req) => {
+>     return await db.listings.findById(req.params.id);
+>   }),
+>   (req, res) => {
+>     res.send("Allowed");
+>   }
+> );
+> ```
 
 ---
 
-# Wildcard Permissions
-
-You can use `*` to allow everything.
-
-Example:
+# Core Concepts
 
 ```
-rule
-  role admin
-  action *
-  resource *
-end
+Subject → Action → Resource
 ```
 
-This allows the admin role to perform **any action on any resource**.
+| Component | Description   |
+| --------- | ------------- |
+| Subject   | User          |
+| Action    | Operation     |
+| Resource  | Target object |
 
 ---
 
-# Conditional Rules
-
-Policies can include conditions.
+# Policy Language (TOON)
 
-Syntax:
+Basic syntax:
 
 ```
 rule
   role <role>
   action <action>
   resource <resource>
-  condition <condition1> OR <condition2>
-end
-```
-
-Example:
-
-```
-rule
-  role user
-  action view
-  resource listing
-  condition listing.status == "public" OR listing.owner_id == user.id
 end
 ```
 
-Meaning:
-
-A broker can only edit listings they own.
+The parser is strict on purpose: a stray `end`, a `rule` opened twice without
+closing it, an unrecognized key (e.g. a typo'd `roel`), or a key with no
+value all throw a clear error with the line number, instead of silently
+dropping or mis-parsing part of your policy. `authz.load()` runs full
+validation too — every condition is actually compiled during validation, so
+a broken condition (missing operand, mixed `AND`/`OR`, etc.) is reported
+against its rule number at load time rather than failing later, mid-request,
+somewhere inside the evaluator.
 
 ---
 
-# Condition Variables
-
-Conditions can reference:
-
-| Variable | Description           |
-| -------- | --------------------- |
-| user     | authenticated user    |
-| resource | target resource       |
-| context  | optional request data |
-
-Example:
+# Wildcards
 
 ```
-rule
-  role user
-  action edit
-  resource profile
-  condition user.id == resource.id
-end
+action *
+resource *
 ```
 
 ---
 
-# Policy Examples
+# Conditional Rules
 
-## Example 1 – Basic Roles
+Example:
 
 ```
-rule
-  role admin
-  action *
-  resource *
-end
-
-rule
-  role broker
-  action publish
-  resource listing
-end
-
-rule
-  role user
-  action edit
-  resource listing
-end
+condition listing.owner_id == user.id AND listing.status != "published"
 ```
 
----
+Chains of any length work: `a == 1 AND b == 2 AND c == 3`. You can also
+compare against numbers and booleans directly (`listing.views > 100`), not
+just strings.
 
-## Example 2 – Ownership Rules
+Only one operator type per condition — `AND` and `OR` can't be mixed in the
+same condition (`a == 1 AND b == 2 OR c == 3` throws an error). Split that
+into two separate rules instead.
 
-```
-rule
-  role broker
-  action edit
-  resource listing
-  condition listing.owner_id == user.id
-end
-```
+String literals are quote-safe: a value like
+`doc.title == "Terms AND Conditions"` is treated as one literal, not
+accidentally split on the "AND" inside it.
 
 ---
 
-## Example 3 – Multiple Rules
-
-```
-rule
-  role admin
-  action *
-  resource *
-end
+# Policy Examples
 
-rule
-  role broker
-  action publish
-  resource listing
-end
+### Ownership Rule
 
+```
 rule
   role user
   action edit
@@ -437,33 +296,23 @@ 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");
@@ -474,91 +323,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:
-
-```javascript
-const user = {
-  id: 10,
-  roles: ["broker"],
-};
-```
-
-Listing:
+## Explain decision
 
 ```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
 ```
 
@@ -566,66 +361,75 @@ project
 
 # Performance
 
-Policies are compiled into an **internal permission index** for fast lookups.
+* Rules compiled into indexed structure
+* AST-based condition evaluation
+* O(1) permission lookup
+* Built-in LRU cache with TTL-based expiration, keyed by user + action +
+  resource + object id (falls back to a data snapshot if there's no id)
 
-Authorization checks are optimized to avoid scanning all rules.
+**Caching caveat:** because the cache keys on object *identity* (id/owner_id),
+if a resource's *other* fields change while its id stays the same (e.g. a
+document gets locked) within the TTL window, a stale decision can be served.
+Call `authz.clearCache()` right after any write that could flip a condition's
+outcome, or lower `cacheTTL` / set `cacheEnabled: false` for policies with
+conditions on fast-changing fields:
 
-This allows the engine to remain efficient even as policy files grow.
+```javascript
+const authz = new Authz({ cacheEnabled: true, cacheSize: 1000, cacheTTL: 60 });
+```
 
 ---
 
-# Security Model
+# CLI
 
-Default behavior follows the **deny-by-default principle**.
+```bash
+npx simple-authz validate ./policies/authz.toon
+npx simple-authz check ./policies/authz.toon --user '{"id":1,"roles":["user"]}' --action edit --resource listing --context '{"owner_id":1}'
+npx simple-authz benchmark ./policies/authz.toon --iterations 10000
+```
 
-Meaning:
+* `validate` — parses and validates a policy file, lists roles found
+* `check` — runs `authz.explain()` against a policy and prints the decision
+* `benchmark` — runs repeated checks and prints throughput + cache stats
 
-If no rule allows an action, access is automatically denied.
+---
+
+# Security Model
+
+**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
+* Role hierarchy
+* Modular policies
 
----
+### v2.0
 
-# Contributing
-
-Contributions are welcome.
-
-Steps:
-
-1. Fork the repository
-2. Create a feature branch
-3. Commit changes
-4. Open a pull request
+* Advanced ABAC
+* Distributed policies
+* Policy versioning
 
 ---
 
-# License
+# Contributing
 
-This project is licensed under the [Apache 2.0 license](LICENSE).
+1. Fork repository
+2. Create branch
+3. Submit PR
 
 ---
 
-# Author
+# License
 
-Simple Authz was created to simplify authorization logic in modern Node.js applications.
+Apache 2.0
 
-# Keywords
+---