simple-authz 1.0.5 → 1.2.0

package/bin/simple-authz/index.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const Authz = require('../../lib/core/authz');
+const chalk = require('chalk'); // for colored output
+const path = require('path');
+
+program.version('1.1.0');
+
+program
+    .command('validate <policyFile>')
+    .description('Validate a TOON policy file')
+    .action((policyFile) => {
+        try {
+            const authz = new Authz();
+            authz.load(policyFile);
+
+            const rules = authz.getRules();
+            console.log(chalk.green('✓ Policy file is valid\n'));
+            console.log(`  File: ${chalk.gray(path.resolve(policyFile))}`);
+            console.log(`  Rules loaded: ${chalk.blue(rules.length)}`);
+            console.log(`  Roles: ${chalk.blue([...new Set(rules.map(r => r.role))].join(', '))}`);
+            console.log();
+        } catch (err) {
+            console.error(chalk.red('✗ Validation failed\n'));
+            console.error(`  ${chalk.red(err.message)}`);
+            process.exit(1);
+        }
+    });
+
+program
+    .command('check <policyFile>')
+    .requiredOption('--user <json>', 'User object as JSON')
+    .requiredOption('--action <action>', 'Action to check')
+    .requiredOption('--resource <resource>', 'Resource type')
+    .option('--context <json>', 'Context/object as JSON')
+    .description('Test an authorization decision')
+    .action((policyFile, options) => {
+        try {
+            const authz = new Authz({ debugMode: true });
+            authz.load(policyFile);
+
+            const user = JSON.parse(options.user);
+            const context = options.context ? JSON.parse(options.context) : {};
+
+            const result = authz.explain(user, options.action, options.resource, context);
+
+            console.log();
+            if (result.allowed) {
+                console.log(chalk.green('✓ ALLOWED\n'));
+            } else {
+                console.log(chalk.red('✗ DENIED\n'));
+            }
+
+            const userRoles = user.roles || (user.role ? [user.role] : []);
+
+            console.log(`  User ID:        ${chalk.blue(user.id)}`);
+            console.log(`  User roles:     ${chalk.blue(userRoles.join(', '))}`);
+            console.log(`  Action:         ${chalk.blue(options.action)}`);
+            console.log(`  Resource:       ${chalk.blue(options.resource)}`);
+            console.log(`  Reason:         ${chalk.yellow(result.reason)}`);
+
+            if (result.ruleMatched) {
+                console.log(`  Rule matched:   ${chalk.green(result.ruleMatched)}`);
+            }
+            if (result.evaluationTime) {
+                console.log(`  Eval time:      ${chalk.gray(result.evaluationTime + 'ms')}`);
+            }
+            console.log();
+
+            process.exit(result.allowed ? 0 : 1);
+        } catch (err) {
+            console.error(chalk.red('✗ Check failed\n'));
+            console.error(`  ${chalk.red(err.message)}`);
+            process.exit(1);
+        }
+    });
+
+program
+    .command('benchmark <policyFile>')
+    .option('--iterations <n>', 'Number of checks to run', '10000')
+    .description('Benchmark authorization performance')
+    .action((policyFile, options) => {
+        const iterations = parseInt(options.iterations);
+
+        try {
+            const authz = new Authz({ cacheEnabled: true });
+            authz.load(policyFile);
+
+            const user = { id: 1, roles: ['admin', 'user'] };
+            const object = { owner_id: 1, status: 'active' };
+
+            // Warmup
+            for (let i = 0; i < 10; i++) {
+                authz.can(user, 'edit', 'resource', object);
+            }
+
+            // Benchmark
+            const start = process.hrtime.bigint();
+            for (let i = 0; i < iterations; i++) {
+                authz.can(user, 'edit', 'resource', object);
+            }
+            const end = process.hrtime.bigint();
+
+            const timeMs = Number(end - start) / 1_000_000;
+            const checksPerSec = Math.round((iterations / timeMs) * 1000);
+
+            console.log();
+            console.log(chalk.cyan('Performance Benchmark'));
+            console.log('─'.repeat(40));
+            console.log(`  Iterations:    ${chalk.blue(iterations.toLocaleString())}`);
+            console.log(`  Total time:    ${chalk.blue(timeMs.toFixed(2))} ms`);
+            console.log(`  Avg per check: ${chalk.blue((timeMs / iterations).toFixed(4))} ms`);
+            console.log(`  Checks/sec:    ${chalk.green(checksPerSec.toLocaleString())}`);
+
+            const stats = authz.cacheStats();
+            console.log();
+            console.log(chalk.cyan('Cache Statistics'));
+            console.log('─'.repeat(40));
+            console.log(`  Hit rate:      ${chalk.blue(stats.hitRate)}`);
+            console.log(`  Cache size:    ${chalk.blue(stats.size)}/${stats.maxSize}`);
+            console.log(`  Hits:          ${chalk.green(stats.hits.toLocaleString())}`);
+            console.log(`  Misses:        ${chalk.yellow(stats.misses.toLocaleString())}`);
+            console.log();
+        } catch (err) {
+            console.error(chalk.red('✗ Benchmark failed\n'));
+            console.error(`  ${chalk.red(err.message)}`);
+            process.exit(1);
+        }
+    });
+
+program.parse();

package/lib/cache.js

@@ -0,0 +1,149 @@
+/**
+ * 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();
+        // Named _stats (not `stats`) because a class method `stats()` exists
+        // below — an instance property named the same as a prototype method
+        // shadows it, so `cache.stats()` would throw "not a function" the
+        // moment anyone actually called it (this went uncaught only because
+        // the cache itself was never wired into Authz until now).
+        this._stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            timeouts: 0
+        };
+    }
+
+    /**
+     * Generate cache key from request parameters
+     * Format: {userIdentity}:{action}:{resource}:{objectId or 'null'}
+     *
+     * Falls back to role(s) when there's no `user.id` — otherwise every
+     * id-less user (e.g. identified only by `user.role`/`user.roles`, which
+     * this library explicitly supports) would collide into the same cache
+     * key and could get served another user's cached decision.
+     */
+    _key(user, action, resource, objectId) {
+        const identity = user && user.id != null
+            ? user.id
+            : `roles:${JSON.stringify((user && (user.roles || user.role)) || null)}`;
+
+        return `${identity}:${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,30 @@ const { compileRules } = require("../rules/compiler")
 const { validateRules } = require("../rules/validator")
 const { normalizeUser } = require("../utils/normalizeUser")
 const { evaluateAST } = require("../engine/conditionExecutor")
+const createMiddleware = require("./middleware")
+const AuthzCache = require("../cache")
 
 class Authz {
 
-    constructor() {
+    /**
+     * @param {object} [options]
+     * @param {boolean} [options.cacheEnabled=true]
+     * @param {number} [options.cacheSize=1000]
+     * @param {number} [options.cacheTTL=3600] seconds
+     */
+    constructor(options = {}) {
         this.permissions = {}
         this.conditions = {}
+        this.rules = []
+        // Previously this was a plain Map keyed by JSON.stringify(...) that
+        // was checked in can() but never written to (no .set() call), so
+        // caching silently never happened. lib/cache.js already had a full
+        // LRU+TTL cache implementation sitting unused — wiring it in here.
+        this.cache = new AuthzCache({
+            enabled: options.cacheEnabled !== false,
+            maxSize: options.cacheSize || 1000,
+            ttl: options.cacheTTL || 3600
+        })
     }
 
     load(filePath) {
@@ -18,14 +36,55 @@ class Authz {
 
         const compiled = compileRules(rules)
 
+        this.rules = rules
         this.permissions = compiled.permissions
         this.conditions = compiled.conditions
+
+        // Stale decisions from a previous policy must not survive a reload.
+        this.cache.clear()
+    }
+
+    getRules() {
+        return this.rules
+    }
+
+    cacheStats() {
+        return this.cache.stats()
+    }
+
+    /**
+     * Manually invalidate cached decisions. Caching keys on id/owner_id (or a
+     * snapshot of the data if neither exists) — so if a resource's OTHER
+     * fields change (e.g. a document gets locked) while its id stays the
+     * same, a cached decision from before that change can still be served
+     * until the TTL expires. Call this right after any write that could
+     * affect a condition's outcome, or set `cacheTTL` low / `cacheEnabled:
+     * false` for policies with conditions on fast-changing fields.
+     */
+    clearCache() {
+        return this.cache.clear()
     }
 
     can(user, action, resourceType, data = {}) {
 
         const roles = normalizeUser(user)
+        // Cache key needs something that uniquely identifies this resource.
+        // id/owner_id is cheap and covers the common case. When neither is
+        // present, fall back to a stringified snapshot of the data — without
+        // this, two different payloads with no id (e.g. {age:25} vs {age:10})
+        // would collide onto the same cache key and one call's result would
+        // wrongly get served to the other.
+        const objectId = data && (data.id ?? data.owner_id ?? JSON.stringify(data))
+
+        const cached = this.cache.get(user, action, resourceType, objectId)
+
+        if (cached !== null) {
+            return cached
+        }
+
+        let result = false
 
+        outer:
         for (const role of roles) {
 
             const rolePerm = this.permissions[role]
@@ -37,14 +96,16 @@ class Authz {
                 if (resourcePerm) {
 
                     if (resourcePerm.has("*") || resourcePerm.has(action)) {
-                        return true
+                        result = true
+                        break outer
                     }
                 }
 
                 if (rolePerm["*"]) {
 
                     if (rolePerm["*"].has("*") || rolePerm["*"].has(action)) {
-                        return true
+                        result = true
+                        break outer
                     }
                 }
             }
@@ -69,12 +130,14 @@ class Authz {
                 }
 
                 if (evaluateAST(cond, context)) {
-                    return true
+                    result = true
+                    break outer
                 }
             }
         }
 
-        return false
+        this.cache.set(user, action, resourceType, objectId, result)
+        return result
     }
 
     explain(user, action, resourceType, data = {}) {
@@ -167,4 +230,9 @@ class Authz {
     }
 }
 
+Authz.prototype.middleware = function (action, resourceType, getResource) {
+    const middleware = createMiddleware(this)
+    return middleware(action, resourceType, getResource)
+}
+
 module.exports = Authz

package/lib/core/middleware.js

@@ -0,0 +1,44 @@
+/**
+ * @param {Authz} authz
+ */
+module.exports = function (authz) {
+    /**
+     * @param {string} action
+     * @param {string} resourceType
+     * @param {(req: import('express').Request) => any | Promise<any>} [getResource]
+     *   Optional loader that returns the REAL resource (e.g. fetched from DB)
+     *   to authorize against. If omitted, falls back to `req.body` for
+     *   backwards compatibility — but be aware `req.body` is client-controlled
+     *   and MUST NOT be trusted for ownership/condition checks (a caller can
+     *   put whatever `owner_id` they want in the body). Always pass
+     *   `getResource` when your policy uses conditions like
+     *   `resource.owner_id == user.id`.
+     */
+    return function (action, resourceType, getResource) {
+        return async (req, res, next) => {
+            const user = req.user
+
+            if (!user) {
+                return res.status(401).json({ error: "Unauthorized" })
+            }
+
+            try {
+                const resource = typeof getResource === "function"
+                    ? await getResource(req)
+                    : (req.body || {})
+
+                const allowed = authz.can(user, action, resourceType, resource)
+
+                if (allowed) {
+                    return next()
+                }
+
+                return res.status(403).json({
+                    error: "Forbidden"
+                })
+            } catch (err) {
+                return next(err)
+            }
+        }
+    }
+}

package/lib/engine/conditionCompiler.js

@@ -1,16 +1,106 @@
+/**
+ * Split `str` on `delimiter`, but ignore any delimiter occurrence that falls
+ * inside a quoted string literal. Without this, a condition like
+ * `doc.title == "Terms AND Conditions"` would get incorrectly split in the
+ * middle of its own string literal, since the naive version just looked for
+ * the substring " AND " anywhere in the raw text.
+ */
+function splitOutsideQuotes(str, delimiter) {
+
+    const parts = []
+    let current = ""
+    let inQuote = null
+
+    for (let i = 0; i < str.length; i++) {
+
+        const ch = str[i]
+
+        if (inQuote) {
+            current += ch
+            if (ch === inQuote) inQuote = null
+            continue
+        }
+
+        if (ch === '"' || ch === "'") {
+            inQuote = ch
+            current += ch
+            continue
+        }
+
+        if (str.startsWith(delimiter, i)) {
+            parts.push(current)
+            current = ""
+            i += delimiter.length - 1
+            continue
+        }
+
+        current += ch
+    }
+
+    parts.push(current)
+    return parts
+}
+
+/**
+ * Find the first comparison operator that appears outside any quoted
+ * literal. Longer operators are checked first at each position so ">=" is
+ * matched instead of being mistaken for ">" followed by "=".
+ */
+function findTopLevelOperator(expr) {
+
+    const operators = ["==", "!=", ">=", "<=", ">", "<"]
+    let inQuote = null
+
+    for (let i = 0; i < expr.length; i++) {
+
+        const ch = expr[i]
+
+        if (inQuote) {
+            if (ch === inQuote) inQuote = null
+            continue
+        }
+
+        if (ch === '"' || ch === "'") {
+            inQuote = ch
+            continue
+        }
+
+        for (const op of operators) {
+            if (expr.startsWith(op, i)) {
+                return { operator: op, index: i }
+            }
+        }
+    }
+
+    return null
+}
+
 function detectLogical(condition) {
 
-    if (condition.includes(" AND ")) {
+    const andParts = splitOutsideQuotes(condition, " AND ")
+    const orParts = splitOutsideQuotes(condition, " OR ")
+
+    const hasAnd = andParts.length > 1
+    const hasOr = orParts.length > 1
+
+    if (hasAnd && hasOr) {
+        throw new Error(
+            `Mixing AND and OR in a single condition is not supported: "${condition}". ` +
+            `Split this into separate rules instead.`
+        )
+    }
+
+    if (hasAnd) {
         return {
             operator: "AND",
-            parts: condition.split(" AND ")
+            parts: andParts
         }
     }
 
-    if (condition.includes(" OR ")) {
+    if (hasOr) {
         return {
             operator: "OR",
-            parts: condition.split(" OR ")
+            parts: orParts
         }
     }
 
@@ -19,24 +109,29 @@ function detectLogical(condition) {
 
 function parseComparison(expr) {
 
-    const operators = ["==", "!=", ">=", "<=", ">", "<"]
-
-    for (const op of operators) {
+    // Previously this scanned for each operator with .includes()/.split(),
+    // which splits on EVERY occurrence in the string — including one that
+    // happens to sit inside a quoted literal (e.g. `a == "x==y"`) — and then
+    // silently discarded everything past the first two resulting pieces.
+    const found = findTopLevelOperator(expr)
 
-        if (expr.includes(op)) {
+    if (!found) {
+        throw new Error(`Invalid condition: ${expr}`)
+    }
 
-            const [left, right] = expr.split(op).map(s => s.trim())
+    const left = expr.slice(0, found.index).trim()
+    const right = expr.slice(found.index + found.operator.length).trim()
 
-            return {
-                type: "comparison",
-                operator: op,
-                left,
-                right
-            }
-        }
+    if (!left || !right) {
+        throw new Error(`Invalid condition: "${expr}" is missing an operand.`)
     }
 
-    throw new Error(`Invalid condition: ${expr}`)
+    return {
+        type: "comparison",
+        operator: found.operator,
+        left,
+        right
+    }
 }
 
 function compileCondition(condition) {
@@ -47,11 +142,17 @@ function compileCondition(condition) {
         return parseComparison(condition)
     }
 
-    return {
+    // Previously only logical.parts[0] and logical.parts[1] were used, so any
+    // clause past the second one in a chain like "a AND b AND c" was silently
+    // dropped (c never gets checked). Fold every clause into a left-leaning
+    // AST so chains of any length are honored.
+    const nodes = logical.parts.map(part => parseComparison(part.trim()))
+
+    return nodes.reduce((left, right) => ({
         type: logical.operator,
-        left: parseComparison(logical.parts[0]),
-        right: parseComparison(logical.parts[1])
-    }
+        left,
+        right
+    }))
 }
 
 module.exports = { compileCondition }

package/lib/engine/conditionExecutor.js

@@ -13,17 +13,41 @@ function getValue(path, context) {
     return value
 }
 
+/**
+ * Determine whether the right-hand side of a condition is a literal value
+ * (string, number, boolean, null) rather than a field path to look up in
+ * context. Previously only quoted strings were treated as literals, so
+ * `count > 5` or `active == true` silently resolved `5`/`true` as a field
+ * path (e.g. context["5"]), which is always undefined — the condition could
+ * never match.
+ */
+function parseLiteral(raw) {
+
+    if ((raw.startsWith('"') && raw.endsWith('"')) ||
+        (raw.startsWith("'") && raw.endsWith("'"))) {
+        return { isLiteral: true, value: raw.slice(1, -1) }
+    }
+
+    if (raw === "true") return { isLiteral: true, value: true }
+    if (raw === "false") return { isLiteral: true, value: false }
+    if (raw === "null") return { isLiteral: true, value: null }
+
+    if (/^-?\d+(\.\d+)?$/.test(raw)) {
+        return { isLiteral: true, value: Number(raw) }
+    }
+
+    return { isLiteral: false, value: undefined }
+}
+
 function evaluateComparison(node, context) {
 
     const leftVal = getValue(node.left, context)
 
-    let rightVal
+    const literal = parseLiteral(node.right)
 
-    if (node.right.startsWith('"') || node.right.startsWith("'")) {
-        rightVal = node.right.slice(1, -1)
-    } else {
-        rightVal = getValue(node.right, context)
-    }
+    const rightVal = literal.isLiteral
+        ? literal.value
+        : getValue(node.right, context)
 
     switch (node.operator) {