@zero-server/sdk 0.9.0 → 0.9.2

package/lib/auth/authorize.js

@@ -1,399 +1,399 @@
-/**
- * @module auth/authorize
- * @description Authorization helpers — role-based access control (RBAC),
- *              permission-based access, and policy classes.
- *
- *              Works with any authentication middleware that sets `req.user`.
- *
- * @example
- *   const { createApp, jwt, authorize, can, canAny, Policy, gate,
- *       attachUserHelpers, Router } = require('@zero-server/sdk');
- *   const app = createApp();
- *
- *   app.use(jwt({ secret: process.env.JWT_SECRET }));
- *   app.use(attachUserHelpers());
- *
- *   // Role-based — only admins and editors can modify posts
- *   app.put('/posts/:id', authorize('admin', 'editor'), (req, res) => {
- *       res.json({ updated: true });
- *   });
- *
- *   // Permission-based — require ALL listed permissions
- *   app.delete('/users/:id', can('users:read', 'users:delete'), (req, res) => {
- *       res.json({ deleted: true });
- *   });
- *
- *   // ANY permission — useful for overlapping access
- *   app.get('/reports', canAny('reports:read', 'admin:read'), (req, res) => {
- *       res.json({ reports: [] });
- *   });
- *
- *   // Policy class — resource-level authorization
- *   class PostPolicy extends Policy {
- *       before(user) { if (user.role === 'superadmin') return true; }
- *       update(user, post) { return user.id === post.authorId || user.role === 'admin'; }
- *       delete(user, post) { return user.role === 'admin'; }
- *   }
- *
- *   app.put('/posts/:id', gate(new PostPolicy(), 'update', async (req) => {
- *       return await Post.findById(req.params.id);
- *   }), (req, res) => {
- *       // req.resource is auto-populated by gate()
- *       res.json({ updated: req.resource });
- *   });
- *
- *   // Inline checks via attachUserHelpers()
- *   app.get('/dashboard', (req, res) => {
- *       const data = { user: req.user.sub };
- *       if (req.user.is('admin')) data.adminPanel = true;
- *       if (req.user.can('reports:export')) data.canExport = true;
- *       res.json(data);
- *   });
- */
-const log = require('../debug')('zero:auth');
-
-// -- Role-Based Access Control ------------------------------------
-
-/**
- * Role-based authorization middleware.
- * Checks `req.user.role` or `req.user.roles` against allowed roles.
- *
- * Returns 401 if `req.user` is missing (not authenticated).
- * Returns 403 if the user's role is not in the allowed list.
- *
- * @param {...string} roles - Allowed roles.
- * @returns {Function} Middleware `(req, res, next) => void`.
- *
- * @example
- *   app.get('/admin', authorize('admin'), (req, res) => {
- *       res.json({ message: 'Welcome, admin!' });
- *   });
- *
- * @example | Multiple Roles
- *   app.put('/posts/:id', authorize('admin', 'editor'), (req, res) => {
- *       res.json({ updated: true });
- *   });
- */
-function authorize(...roles)
-{
-    const allowed = new Set(roles.flat());
-
-    return function authorizeMiddleware(req, res, next)
-    {
-        if (!req.user)
-        {
-            return res.status(401).json({
-                error: 'Authentication required',
-                code: 'NOT_AUTHENTICATED',
-                statusCode: 401,
-            });
-        }
-
-        const userRoles = _extractRoles(req.user);
-        const hasRole = userRoles.some(r => allowed.has(r));
-
-        if (!hasRole)
-        {
-            log.debug('access denied: user roles [%s] not in [%s]', userRoles.join(', '), [...allowed].join(', '));
-            return res.status(403).json({
-                error: 'Insufficient permissions',
-                code: 'FORBIDDEN',
-                statusCode: 403,
-            });
-        }
-
-        log.debug('authorized: role=%s', userRoles.find(r => allowed.has(r)));
-        next();
-    };
-}
-
-// -- Permission-Based Access Control --------------------------------
-
-/**
- * Permission-based authorization middleware.
- * Checks `req.user.permissions` (array or Set) for the required permission(s).
- *
- * Permission strings follow a `resource:action` convention:
- *   - `'posts:write'` — write access to posts
- *   - `'users:delete'` — delete users
- *   - `'*'` — superuser wildcard
- *
- * @param {...string} permissions - Required permissions (ALL must be present unless `opts.any` is true).
- * @returns {Function} Middleware `(req, res, next) => void`.
- *
- * @example | Require Specific Permission
- *   app.post('/posts', can('posts:write'), (req, res) => {
- *       res.status(201).json(req.body);
- *   });
- *
- * @example | Require ALL Permissions
- *   app.put('/users/:id', can('users:read', 'users:write'), (req, res) => {
- *       res.json({ updated: true });
- *   });
- *
- * @example | Require ANY Permission
- *   app.get('/dashboard', canAny('admin:read', 'reports:read'), (req, res) => {
- *       res.json({ dashboard: true });
- *   });
- */
-function can(...permissions)
-{
-    return _permissionMiddleware(permissions.flat(), false);
-}
-
-/**
- * Like `can()`, but passes if the user has ANY of the listed permissions.
- *
- * @param {...string} permissions - Permissions to check (any one is sufficient).
- * @returns {Function} Middleware.
- *
- * @example
- *   app.get('/reports', canAny('reports:read', 'admin:read'), (req, res) => {
- *       res.json({ reports: [] });
- *   });
- */
-function canAny(...permissions)
-{
-    return _permissionMiddleware(permissions.flat(), true);
-}
-
-/** @private */
-function _permissionMiddleware(required, anyMode)
-{
-    return function permissionMiddleware(req, res, next)
-    {
-        if (!req.user)
-        {
-            return res.status(401).json({
-                error: 'Authentication required',
-                code: 'NOT_AUTHENTICATED',
-                statusCode: 401,
-            });
-        }
-
-        const userPerms = _extractPermissions(req.user);
-
-        // Wildcard superuser
-        if (userPerms.has('*'))
-        {
-            log.debug('wildcard permission granted');
-            return next();
-        }
-
-        const check = anyMode
-            ? required.some(p => userPerms.has(p))
-            : required.every(p => userPerms.has(p));
-
-        if (!check)
-        {
-            log.debug('permission denied: required [%s] (mode=%s)', required.join(', '), anyMode ? 'any' : 'all');
-            return res.status(403).json({
-                error: 'Insufficient permissions',
-                code: 'FORBIDDEN',
-                statusCode: 403,
-            });
-        }
-
-        next();
-    };
-}
-
-// -- Policy Classes -----------------------------------------------
-
-/**
- * Base policy class for resource-level authorization.
- * Subclass and define methods matching action names.
- * Each method receives `(user, resource)` and returns `boolean`.
- *
- * @example
- *   class PostPolicy extends Policy {
- *       view()                 { return true; }          // anyone can view
- *       update(user, post)     { return user.id === post.authorId; }
- *       delete(user, post)     { return user.role === 'admin'; }
- *       publish(user, post)    { return ['admin', 'editor'].includes(user.role); }
- *   }
- */
-class Policy
-{
-    /**
-     * Check if an action is allowed.
-     * Falls through to the action method if defined, otherwise denies.
-     *
-     * @param {string} action - The action name (method name).
-     * @param {object} user - The authenticated user.
-     * @param {object} [resource] - The resource being accessed.
-     * @returns {boolean|Promise<boolean>}
-     */
-    check(action, user, resource)
-    {
-        if (typeof this.before === 'function')
-        {
-            const beforeResult = this.before(user, action, resource);
-            if (beforeResult === true) return true;
-            if (beforeResult === false) return false;
-            // undefined = continue to action method
-        }
-
-        if (typeof this[action] !== 'function') return false;
-        return this[action](user, resource);
-    }
-}
-
-/**
- * Policy gate middleware.
- * Runs a policy check against a resource loaded from the request.
- *
- * @param {Policy} policy - Policy instance.
- * @param {string} action - Action name to check.
- * @param {Function} [getResource] - `async (req) => resource` loader. If omitted, passes `null`.
- * @returns {Function} Middleware `(req, res, next) => void`.
- *
- * @example
- *   const postPolicy = new PostPolicy();
- *
- *   // With resource loader
- *   app.put('/posts/:id', gate(postPolicy, 'update', async (req) => {
- *       return await Post.findById(req.params.id);
- *   }), (req, res) => {
- *       res.json({ updated: req.resource });
- *   });
- *
- *   // Without resource (for create/list actions)
- *   app.post('/posts', gate(postPolicy, 'create'), (req, res) => {
- *       res.status(201).json(req.body);
- *   });
- */
-function gate(policy, action, getResource)
-{
-    return async function gateMiddleware(req, res, next)
-    {
-        if (!req.user)
-        {
-            return res.status(401).json({
-                error: 'Authentication required',
-                code: 'NOT_AUTHENTICATED',
-                statusCode: 401,
-            });
-        }
-
-        let resource = null;
-        if (typeof getResource === 'function')
-        {
-            resource = await getResource(req);
-        }
-
-        const allowed = await policy.check(action, req.user, resource);
-        if (!allowed)
-        {
-            log.debug('policy denied: action=%s', action);
-            return res.status(403).json({
-                error: 'Action not allowed',
-                code: 'POLICY_DENIED',
-                statusCode: 403,
-            });
-        }
-
-        // Attach resource if loaded — saves a redundant DB query in the handler
-        if (resource && !req.resource) req.resource = resource;
-        next();
-    };
-}
-
-// -- req.user helpers (mixed in by middleware barrel) ----------------
-
-/**
- * Attach convenience authorization methods to `req.user`.
- * Call this middleware after JWT/session middleware.
- *
- * Adds:
- *   - `req.user.is(...roles)` — check roles
- *   - `req.user.can(...perms)` — check permissions
- *
- * @returns {Function} Middleware.
- *
- * @example
- *   app.use(jwt({ secret }));
- *   app.use(attachUserHelpers());
- *
- *   app.get('/dashboard', (req, res) => {
- *       if (req.user.is('admin')) {
- *           // admin view
- *       }
- *       if (req.user.can('reports:export')) {
- *           // show export button
- *       }
- *   });
- */
-function attachUserHelpers()
-{
-    return function userHelpersMiddleware(req, res, next)
-    {
-        if (!req.user) return next();
-
-        if (!req.user.is)
-        {
-            req.user.is = (...roles) =>
-            {
-                const userRoles = _extractRoles(req.user);
-                return roles.flat().some(r => userRoles.includes(r));
-            };
-        }
-
-        if (!req.user.can)
-        {
-            req.user.can = (...perms) =>
-            {
-                const userPerms = _extractPermissions(req.user);
-                if (userPerms.has('*')) return true;
-                return perms.flat().every(p => userPerms.has(p));
-            };
-        }
-
-        next();
-    };
-}
-
-// -- Internal Helpers -----------------------------------------------
-
-/**
- * Normalise user roles from various formats.
- * Supports `user.role` (string), `user.roles` (array), and `user.role` (array).
- *
- * @param {object} user
- * @returns {string[]}
- * @private
- */
-function _extractRoles(user)
-{
-    if (!user) return [];
-    if (Array.isArray(user.roles)) return user.roles;
-    if (Array.isArray(user.role)) return user.role;
-    if (typeof user.role === 'string') return [user.role];
-    return [];
-}
-
-/**
- * Normalise user permissions from various formats.
- * Supports `user.permissions` (array or Set), `user.scopes` (array).
- *
- * @param {object} user
- * @returns {Set<string>}
- * @private
- */
-function _extractPermissions(user)
-{
-    if (!user) return new Set();
-    if (user.permissions instanceof Set) return user.permissions;
-    if (Array.isArray(user.permissions)) return new Set(user.permissions);
-    if (Array.isArray(user.scopes)) return new Set(user.scopes);
-    return new Set();
-}
-
-module.exports = {
-    authorize,
-    can,
-    canAny,
-    Policy,
-    gate,
-    attachUserHelpers,
-};
+/**
+ * @module auth/authorize
+ * @description Authorization helpers — role-based access control (RBAC),
+ *              permission-based access, and policy classes.
+ *
+ *              Works with any authentication middleware that sets `req.user`.
+ *
+ * @example
+ *   const { createApp, jwt, authorize, can, canAny, Policy, gate,
+ *       attachUserHelpers, Router } = require('@zero-server/sdk');
+ *   const app = createApp();
+ *
+ *   app.use(jwt({ secret: process.env.JWT_SECRET }));
+ *   app.use(attachUserHelpers());
+ *
+ *   // Role-based — only admins and editors can modify posts
+ *   app.put('/posts/:id', authorize('admin', 'editor'), (req, res) => {
+ *       res.json({ updated: true });
+ *   });
+ *
+ *   // Permission-based — require ALL listed permissions
+ *   app.delete('/users/:id', can('users:read', 'users:delete'), (req, res) => {
+ *       res.json({ deleted: true });
+ *   });
+ *
+ *   // ANY permission — useful for overlapping access
+ *   app.get('/reports', canAny('reports:read', 'admin:read'), (req, res) => {
+ *       res.json({ reports: [] });
+ *   });
+ *
+ *   // Policy class — resource-level authorization
+ *   class PostPolicy extends Policy {
+ *       before(user) { if (user.role === 'superadmin') return true; }
+ *       update(user, post) { return user.id === post.authorId || user.role === 'admin'; }
+ *       delete(user, post) { return user.role === 'admin'; }
+ *   }
+ *
+ *   app.put('/posts/:id', gate(new PostPolicy(), 'update', async (req) => {
+ *       return await Post.findById(req.params.id);
+ *   }), (req, res) => {
+ *       // req.resource is auto-populated by gate()
+ *       res.json({ updated: req.resource });
+ *   });
+ *
+ *   // Inline checks via attachUserHelpers()
+ *   app.get('/dashboard', (req, res) => {
+ *       const data = { user: req.user.sub };
+ *       if (req.user.is('admin')) data.adminPanel = true;
+ *       if (req.user.can('reports:export')) data.canExport = true;
+ *       res.json(data);
+ *   });
+ */
+const log = require('../debug')('zero:auth');
+
+// -- Role-Based Access Control ------------------------------------
+
+/**
+ * Role-based authorization middleware.
+ * Checks `req.user.role` or `req.user.roles` against allowed roles.
+ *
+ * Returns 401 if `req.user` is missing (not authenticated).
+ * Returns 403 if the user's role is not in the allowed list.
+ *
+ * @param {...string} roles - Allowed roles.
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   app.get('/admin', authorize('admin'), (req, res) => {
+ *       res.json({ message: 'Welcome, admin!' });
+ *   });
+ *
+ * @example | Multiple Roles
+ *   app.put('/posts/:id', authorize('admin', 'editor'), (req, res) => {
+ *       res.json({ updated: true });
+ *   });
+ */
+function authorize(...roles)
+{
+    const allowed = new Set(roles.flat());
+
+    return function authorizeMiddleware(req, res, next)
+    {
+        if (!req.user)
+        {
+            return res.status(401).json({
+                error: 'Authentication required',
+                code: 'NOT_AUTHENTICATED',
+                statusCode: 401,
+            });
+        }
+
+        const userRoles = _extractRoles(req.user);
+        const hasRole = userRoles.some(r => allowed.has(r));
+
+        if (!hasRole)
+        {
+            log.debug('access denied: user roles [%s] not in [%s]', userRoles.join(', '), [...allowed].join(', '));
+            return res.status(403).json({
+                error: 'Insufficient permissions',
+                code: 'FORBIDDEN',
+                statusCode: 403,
+            });
+        }
+
+        log.debug('authorized: role=%s', userRoles.find(r => allowed.has(r)));
+        next();
+    };
+}
+
+// -- Permission-Based Access Control --------------------------------
+
+/**
+ * Permission-based authorization middleware.
+ * Checks `req.user.permissions` (array or Set) for the required permission(s).
+ *
+ * Permission strings follow a `resource:action` convention:
+ *   - `'posts:write'` — write access to posts
+ *   - `'users:delete'` — delete users
+ *   - `'*'` — superuser wildcard
+ *
+ * @param {...string} permissions - Required permissions (ALL must be present unless `opts.any` is true).
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example | Require Specific Permission
+ *   app.post('/posts', can('posts:write'), (req, res) => {
+ *       res.status(201).json(req.body);
+ *   });
+ *
+ * @example | Require ALL Permissions
+ *   app.put('/users/:id', can('users:read', 'users:write'), (req, res) => {
+ *       res.json({ updated: true });
+ *   });
+ *
+ * @example | Require ANY Permission
+ *   app.get('/dashboard', canAny('admin:read', 'reports:read'), (req, res) => {
+ *       res.json({ dashboard: true });
+ *   });
+ */
+function can(...permissions)
+{
+    return _permissionMiddleware(permissions.flat(), false);
+}
+
+/**
+ * Like `can()`, but passes if the user has ANY of the listed permissions.
+ *
+ * @param {...string} permissions - Permissions to check (any one is sufficient).
+ * @returns {Function} Middleware.
+ *
+ * @example
+ *   app.get('/reports', canAny('reports:read', 'admin:read'), (req, res) => {
+ *       res.json({ reports: [] });
+ *   });
+ */
+function canAny(...permissions)
+{
+    return _permissionMiddleware(permissions.flat(), true);
+}
+
+/** @private */
+function _permissionMiddleware(required, anyMode)
+{
+    return function permissionMiddleware(req, res, next)
+    {
+        if (!req.user)
+        {
+            return res.status(401).json({
+                error: 'Authentication required',
+                code: 'NOT_AUTHENTICATED',
+                statusCode: 401,
+            });
+        }
+
+        const userPerms = _extractPermissions(req.user);
+
+        // Wildcard superuser
+        if (userPerms.has('*'))
+        {
+            log.debug('wildcard permission granted');
+            return next();
+        }
+
+        const check = anyMode
+            ? required.some(p => userPerms.has(p))
+            : required.every(p => userPerms.has(p));
+
+        if (!check)
+        {
+            log.debug('permission denied: required [%s] (mode=%s)', required.join(', '), anyMode ? 'any' : 'all');
+            return res.status(403).json({
+                error: 'Insufficient permissions',
+                code: 'FORBIDDEN',
+                statusCode: 403,
+            });
+        }
+
+        next();
+    };
+}
+
+// -- Policy Classes -----------------------------------------------
+
+/**
+ * Base policy class for resource-level authorization.
+ * Subclass and define methods matching action names.
+ * Each method receives `(user, resource)` and returns `boolean`.
+ *
+ * @example
+ *   class PostPolicy extends Policy {
+ *       view()                 { return true; }          // anyone can view
+ *       update(user, post)     { return user.id === post.authorId; }
+ *       delete(user, post)     { return user.role === 'admin'; }
+ *       publish(user, post)    { return ['admin', 'editor'].includes(user.role); }
+ *   }
+ */
+class Policy
+{
+    /**
+     * Check if an action is allowed.
+     * Falls through to the action method if defined, otherwise denies.
+     *
+     * @param {string} action - The action name (method name).
+     * @param {object} user - The authenticated user.
+     * @param {object} [resource] - The resource being accessed.
+     * @returns {boolean|Promise<boolean>}
+     */
+    check(action, user, resource)
+    {
+        if (typeof this.before === 'function')
+        {
+            const beforeResult = this.before(user, action, resource);
+            if (beforeResult === true) return true;
+            if (beforeResult === false) return false;
+            // undefined = continue to action method
+        }
+
+        if (typeof this[action] !== 'function') return false;
+        return this[action](user, resource);
+    }
+}
+
+/**
+ * Policy gate middleware.
+ * Runs a policy check against a resource loaded from the request.
+ *
+ * @param {Policy} policy - Policy instance.
+ * @param {string} action - Action name to check.
+ * @param {Function} [getResource] - `async (req) => resource` loader. If omitted, passes `null`.
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   const postPolicy = new PostPolicy();
+ *
+ *   // With resource loader
+ *   app.put('/posts/:id', gate(postPolicy, 'update', async (req) => {
+ *       return await Post.findById(req.params.id);
+ *   }), (req, res) => {
+ *       res.json({ updated: req.resource });
+ *   });
+ *
+ *   // Without resource (for create/list actions)
+ *   app.post('/posts', gate(postPolicy, 'create'), (req, res) => {
+ *       res.status(201).json(req.body);
+ *   });
+ */
+function gate(policy, action, getResource)
+{
+    return async function gateMiddleware(req, res, next)
+    {
+        if (!req.user)
+        {
+            return res.status(401).json({
+                error: 'Authentication required',
+                code: 'NOT_AUTHENTICATED',
+                statusCode: 401,
+            });
+        }
+
+        let resource = null;
+        if (typeof getResource === 'function')
+        {
+            resource = await getResource(req);
+        }
+
+        const allowed = await policy.check(action, req.user, resource);
+        if (!allowed)
+        {
+            log.debug('policy denied: action=%s', action);
+            return res.status(403).json({
+                error: 'Action not allowed',
+                code: 'POLICY_DENIED',
+                statusCode: 403,
+            });
+        }
+
+        // Attach resource if loaded — saves a redundant DB query in the handler
+        if (resource && !req.resource) req.resource = resource;
+        next();
+    };
+}
+
+// -- req.user helpers (mixed in by middleware barrel) ----------------
+
+/**
+ * Attach convenience authorization methods to `req.user`.
+ * Call this middleware after JWT/session middleware.
+ *
+ * Adds:
+ *   - `req.user.is(...roles)` — check roles
+ *   - `req.user.can(...perms)` — check permissions
+ *
+ * @returns {Function} Middleware.
+ *
+ * @example
+ *   app.use(jwt({ secret }));
+ *   app.use(attachUserHelpers());
+ *
+ *   app.get('/dashboard', (req, res) => {
+ *       if (req.user.is('admin')) {
+ *           // admin view
+ *       }
+ *       if (req.user.can('reports:export')) {
+ *           // show export button
+ *       }
+ *   });
+ */
+function attachUserHelpers()
+{
+    return function userHelpersMiddleware(req, res, next)
+    {
+        if (!req.user) return next();
+
+        if (!req.user.is)
+        {
+            req.user.is = (...roles) =>
+            {
+                const userRoles = _extractRoles(req.user);
+                return roles.flat().some(r => userRoles.includes(r));
+            };
+        }
+
+        if (!req.user.can)
+        {
+            req.user.can = (...perms) =>
+            {
+                const userPerms = _extractPermissions(req.user);
+                if (userPerms.has('*')) return true;
+                return perms.flat().every(p => userPerms.has(p));
+            };
+        }
+
+        next();
+    };
+}
+
+// -- Internal Helpers -----------------------------------------------
+
+/**
+ * Normalise user roles from various formats.
+ * Supports `user.role` (string), `user.roles` (array), and `user.role` (array).
+ *
+ * @param {object} user
+ * @returns {string[]}
+ * @private
+ */
+function _extractRoles(user)
+{
+    if (!user) return [];
+    if (Array.isArray(user.roles)) return user.roles;
+    if (Array.isArray(user.role)) return user.role;
+    if (typeof user.role === 'string') return [user.role];
+    return [];
+}
+
+/**
+ * Normalise user permissions from various formats.
+ * Supports `user.permissions` (array or Set), `user.scopes` (array).
+ *
+ * @param {object} user
+ * @returns {Set<string>}
+ * @private
+ */
+function _extractPermissions(user)
+{
+    if (!user) return new Set();
+    if (user.permissions instanceof Set) return user.permissions;
+    if (Array.isArray(user.permissions)) return new Set(user.permissions);
+    if (Array.isArray(user.scopes)) return new Set(user.scopes);
+    return new Set();
+}
+
+module.exports = {
+    authorize,
+    can,
+    canAny,
+    Policy,
+    gate,
+    attachUserHelpers,
+};