simple-authz 1.0.0

package/README.md

@@ -0,0 +1,503 @@
+
+````markdown
+# Simple Authz
+
+A lightweight and flexible **authorization engine for Node.js** built around a simple policy language called **TOON (Token-Oriented Object Notation)**.
+
+Simple Authz allows developers to **centralize authorization logic** using policy files instead of scattering permission checks across application code.
+
+The goal of this project is to make authorization **simple, fast, readable, and scalable**.
+
+---
+
+# 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
+
+Most applications implement authorization like this:
+
+```javascript
+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
+when listing.owner_id == user.id
+```
+
+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
+
+---
+
+# 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
+
+---
+
+# Installation
+
+Install using npm:
+
+```bash
+npm install simple-authz
+```
+
+---
+
+# Quick Start
+
+## 1. Import the library
+
+```javascript
+const Authz = require("simple-authz")
+
+const authz = new Authz()
+```
+
+---
+
+## 2. Create a policy file
+
+Create a file called:
+
+```
+authz.toon
+```
+
+Example policy:
+
+```
+allow admin *
+
+allow user view listing
+
+allow broker publish listing
+
+allow broker edit listing
+when listing.owner_id == user.id
+```
+
+---
+
+## 3. Load the policy
+
+```javascript
+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")
+}
+```
+
+---
+
+# 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**.
+
+Basic rule syntax:
+
+```
+allow <role> <action> <resource>
+```
+
+Example:
+
+```
+allow admin *
+allow user view listing
+allow broker publish listing
+```
+
+---
+
+# Wildcard Permissions
+
+You can use `*` to allow everything.
+
+Example:
+
+```
+allow admin *
+```
+
+This allows the admin role to perform **any action on any resource**.
+
+---
+
+# Conditional Rules
+
+Policies can include conditions.
+
+Syntax:
+
+```
+allow <role> <action> <resource>
+when <condition>
+```
+
+Example:
+
+```
+allow broker edit listing
+when listing.owner_id == user.id
+```
+
+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 |
+
+Example:
+
+```
+allow user edit profile
+when user.id == resource.id
+```
+
+---
+
+# Policy Examples
+
+## Example 1 – Basic Roles
+
+```
+allow admin *
+
+allow user view listing
+
+allow broker publish listing
+```
+
+---
+
+## Example 2 – Ownership Rules
+
+```
+allow broker edit listing
+when listing.owner_id == user.id
+```
+
+---
+
+## Example 3 – Multiple Rules
+
+```
+allow admin *
+
+allow user view listing
+
+allow broker publish listing
+
+allow broker edit listing
+when listing.owner_id == user.id
+```
+
+---
+
+# Working with Roles
+
+Users can have one or multiple roles.
+
+Example user:
+
+```javascript
+const user = {
+    id: 10,
+    roles: ["broker"]
+}
+```
+
+Multiple roles:
+
+```javascript
+const user = {
+    id: 5,
+    roles: ["user","editor"]
+}
+```
+
+The engine checks permissions against **all roles**.
+
+---
+
+# Authorization API
+
+## Load policy file
+
+```javascript
+authz.load("./authz.toon")
+```
+
+---
+
+## Check permission
+
+```javascript
+authz.can(user, action, resource, object)
+```
+
+Example:
+
+```javascript
+authz.can(user,"edit","listing",listing)
+```
+
+Returns:
+
+```
+true
+false
+```
+
+---
+
+# Example Integration
+
+## Example: Listing System
+
+User:
+
+```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
+```
+
+---
+
+# Example: Express.js Integration
+
+Example route protection:
+
+```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()
+})
+```
+
+---
+
+# Project Structure Example
+
+Recommended project layout:
+
+```
+project
+│
+├── policies
+│   └── authz.toon
+│
+├── src
+│
+├── app.js
+│
+└── package.json
+```
+
+---
+
+# 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.
+
+---
+
+# Security Model
+
+Default behavior follows the **deny-by-default principle**.
+
+Meaning:
+
+If no rule allows an action, access is automatically denied.
+
+```
+no rule → deny
+rule exists → allow
+```
+
+This reduces the risk of unintended access.
+
+---
+
+# Roadmap
+
+Future versions may include:
+
+* Policy hot reloading
+* Role inheritance
+* Policy debugger
+* Middleware helpers
+* Permission caching
+* Modular policy files
+* Distributed policy storage
+
+---
+
+# Contributing
+
+Contributions are welcome.
+
+Steps:
+
+1. Fork the repository
+2. Create a feature branch
+3. Commit changes
+4. Open a pull request
+
+---
+
+# License
+
+MIT License
+
+---
+
+# Author
+
+Simple Authz was created to simplify authorization logic in modern Node.js applications.
+
+

package/lib/authz.rules

@@ -0,0 +1,6 @@
+allow admin *
+
+allow broker publish listing
+allow broker feature listing
+
+allow user view listing

package/lib/core/authz.js

@@ -0,0 +1,81 @@
+const { parseRules } = require("../rules/parser")
+const { compileRules } = require("../rules/compiler")
+const { validateRules } = require("../rules/validator")
+const { normalizeUser } = require("../utils/normalizeUser")
+const { evaluateAST } = require("../engine/conditionExecutor")
+
+class Authz {
+
+    constructor() {
+        this.permissions = {}
+        this.conditions = {}
+    }
+
+    load(filePath) {
+
+        const rules = parseRules(filePath)
+        validateRules(rules)
+
+        const compiled = compileRules(rules)
+
+        this.permissions = compiled.permissions
+        this.conditions = compiled.conditions
+    }
+
+    can(user, action, resourceType, data = {}) {
+
+        const roles = normalizeUser(user)
+
+        for (const role of roles) {
+
+            const rolePerm = this.permissions[role]
+
+            if (rolePerm) {
+
+                const resourcePerm = rolePerm[resourceType]
+
+                if (resourcePerm) {
+
+                    if (resourcePerm.has("*") || resourcePerm.has(action)) {
+                        return true
+                    }
+                }
+
+                if (rolePerm["*"]) {
+
+                    if (rolePerm["*"].has("*") || rolePerm["*"].has(action)) {
+                        return true
+                    }
+                }
+            }
+
+            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
+                }
+
+                if (evaluateAST(cond, context)) {
+                    return true
+                }
+            }
+        }
+
+        return false
+    }
+}
+
+module.exports = Authz

package/lib/engine/conditionCompiler.js

@@ -0,0 +1,57 @@
+function detectLogical(condition) {
+
+    if (condition.includes(" AND ")) {
+        return {
+            operator: "AND",
+            parts: condition.split(" AND ")
+        }
+    }
+
+    if (condition.includes(" OR ")) {
+        return {
+            operator: "OR",
+            parts: condition.split(" OR ")
+        }
+    }
+
+    return null
+}
+
+function parseComparison(expr) {
+
+    const operators = ["==", "!=", ">=", "<=", ">", "<"]
+
+    for (const op of operators) {
+
+        if (expr.includes(op)) {
+
+            const [left, right] = expr.split(op).map(s => s.trim())
+
+            return {
+                type: "comparison",
+                operator: op,
+                left,
+                right
+            }
+        }
+    }
+
+    throw new Error(`Invalid condition: ${expr}`)
+}
+
+function compileCondition(condition) {
+
+    const logical = detectLogical(condition)
+
+    if (!logical) {
+        return parseComparison(condition)
+    }
+
+    return {
+        type: logical.operator,
+        left: parseComparison(logical.parts[0]),
+        right: parseComparison(logical.parts[1])
+    }
+}
+
+module.exports = { compileCondition }

package/lib/engine/conditionExecutor.js

@@ -0,0 +1,64 @@
+function getValue(path, context) {
+
+    const parts = path.split(".")
+    let value = context
+
+    for (const p of parts) {
+
+        if (value === undefined) return undefined
+        value = value[p]
+
+    }
+
+    return value
+}
+
+function evaluateComparison(node, context) {
+
+    const leftVal = getValue(node.left, context)
+
+    let rightVal
+
+    if (node.right.startsWith('"') || node.right.startsWith("'")) {
+        rightVal = node.right.slice(1, -1)
+    } else {
+        rightVal = getValue(node.right, context)
+    }
+
+    switch (node.operator) {
+
+        case "==": return leftVal == rightVal
+        case "!=": return leftVal != rightVal
+        case ">": return leftVal > rightVal
+        case "<": return leftVal < rightVal
+        case ">=": return leftVal >= rightVal
+        case "<=": return leftVal <= rightVal
+    }
+
+    return false
+}
+
+function evaluateAST(node, context) {
+
+    if (node.type === "comparison") {
+        return evaluateComparison(node, context)
+    }
+
+    if (node.type === "AND") {
+        return (
+            evaluateAST(node.left, context) &&
+            evaluateAST(node.right, context)
+        )
+    }
+
+    if (node.type === "OR") {
+        return (
+            evaluateAST(node.left, context) ||
+            evaluateAST(node.right, context)
+        )
+    }
+
+    return false
+}
+
+module.exports = { evaluateAST }

package/lib/index.js

@@ -0,0 +1,3 @@
+const Authz = require("./core/authz")
+
+module.exports = new Authz()

package/lib/rules/compiler.js

@@ -0,0 +1,36 @@
+const { compileCondition } = require("../engine/conditionCompiler")
+
+function compileRules(rules) {
+
+    const permissions = {}
+    const conditions = {}
+
+    for (const rule of rules) {
+
+        const { role, action, resource, condition } = rule
+
+        if (condition) {
+
+            if (!conditions[role]) conditions[role] = {}
+            if (!conditions[role][resource]) conditions[role][resource] = {}
+            if (!conditions[role][resource][action])
+                conditions[role][resource][action] = []
+
+            const compiledCondition = compileCondition(condition)
+
+            conditions[role][resource][action].push(compiledCondition)
+
+        } else {
+
+            if (!permissions[role]) permissions[role] = {}
+            if (!permissions[role][resource])
+                permissions[role][resource] = new Set()
+
+            permissions[role][resource].add(action)
+        }
+    }
+
+    return { permissions, conditions }
+}
+
+module.exports = { compileRules }

package/lib/rules/parser.js

@@ -0,0 +1,41 @@
+const fs = require("fs")
+
+function parseRules(filePath) {
+
+    const content = fs.readFileSync(filePath, "utf8")
+
+    const lines = content.split("\n").map(l => l.trim())
+
+    const rules = []
+    let current = null
+
+    for (const line of lines) {
+
+        if (!line || line.startsWith("#")) continue
+
+        if (line === "rule") {
+            current = {}
+        }
+
+        else if (line === "end") {
+            rules.push(current)
+            current = null
+        }
+
+        else if (current) {
+
+            const [key, ...rest] = line.split(" ")
+            const value = rest.join(" ")
+
+            if (key === "role") current.role = value
+            if (key === "action") current.action = value
+            if (key === "resource") current.resource = value
+            if (key === "condition") current.condition = value
+
+        }
+    }
+
+    return rules
+}
+
+module.exports = { parseRules }

package/lib/rules/validator.js

@@ -0,0 +1,50 @@
+function validateRules(rules) {
+
+    const errors = []
+
+    rules.forEach((rule, index) => {
+
+        const ruleNumber = index + 1
+
+        if (!rule.role) {
+            errors.push(`Rule ${ruleNumber}: missing role`)
+        }
+
+        if (!rule.action) {
+            errors.push(`Rule ${ruleNumber}: missing action`)
+        }
+
+        if (!rule.resource) {
+            errors.push(`Rule ${ruleNumber}: missing resource`)
+        }
+
+        if (rule.condition) {
+
+            const validOperators = [
+                "==", "!=", ">", "<", ">=", "<="
+            ]
+
+            const hasOperator = validOperators.some(op =>
+                rule.condition.includes(op)
+            )
+
+            if (!hasOperator) {
+                errors.push(
+                    `Rule ${ruleNumber}: invalid condition "${rule.condition}"`
+                )
+            }
+        }
+
+    })
+
+    if (errors.length > 0) {
+
+        throw new Error(
+            "Policy validation failed:\n\n" +
+            errors.join("\n")
+        )
+    }
+
+}
+
+module.exports = { validateRules }

package/lib/utils/normalizeUser.js

@@ -0,0 +1,10 @@
+function normalizeUser(user) {
+
+    if (user.roles) return user.roles
+
+    if (user.role) return [user.role]
+
+    return []
+}
+
+module.exports = { normalizeUser }

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "simple-authz",
+  "version": "v1.0.0",
+  "description": "Simple authorization engine with TOON policy language",
+  "main": "lib/core/authz.js",
+  "scripts": {
+    "test": "node bin/test.js",
+    "dev": "node lib/core/authz.js"
+  },
+  "keywords": [],
+  "author": "Dhruvil",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dhruvil05/simple-authz"
+  }
+}