@zero-server/auth 0.9.1 → 0.9.3

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Tony Wiedman
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Tony Wiedman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.d.ts

@@ -1,2 +1,2 @@
 // AUTO-GENERATED by .tools/generate-package-stubs.js — edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
-export { jwt, jwtSign, jwtVerify, jwtDecode, jwks, tokenPair, createRefreshToken, SUPPORTED_ALGORITHMS, session, Session, MemoryStore, oauth, generatePKCE, generateState, OAUTH_PROVIDERS, authorize, can, canAny, Policy, gate, attachUserHelpers, twoFactor, webauthn, trustedDevice, enrollment } from "@zero-server/sdk";
+export * from './types/auth';

package/index.js

@@ -1,31 +1,31 @@
 // AUTO-GENERATED by .tools/generate-package-stubs.js — edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
 'use strict';
-const sdk = require("@zero-server/sdk");
+const lib = require("./lib/auth");
 
 module.exports = {
-    jwt: sdk.jwt,
-    jwtSign: sdk.jwtSign,
-    jwtVerify: sdk.jwtVerify,
-    jwtDecode: sdk.jwtDecode,
-    jwks: sdk.jwks,
-    tokenPair: sdk.tokenPair,
-    createRefreshToken: sdk.createRefreshToken,
-    SUPPORTED_ALGORITHMS: sdk.SUPPORTED_ALGORITHMS,
-    session: sdk.session,
-    Session: sdk.Session,
-    MemoryStore: sdk.MemoryStore,
-    oauth: sdk.oauth,
-    generatePKCE: sdk.generatePKCE,
-    generateState: sdk.generateState,
-    OAUTH_PROVIDERS: sdk.OAUTH_PROVIDERS,
-    authorize: sdk.authorize,
-    can: sdk.can,
-    canAny: sdk.canAny,
-    Policy: sdk.Policy,
-    gate: sdk.gate,
-    attachUserHelpers: sdk.attachUserHelpers,
-    twoFactor: sdk.twoFactor,
-    webauthn: sdk.webauthn,
-    trustedDevice: sdk.trustedDevice,
-    enrollment: sdk.enrollment,
+    jwt: lib.jwt,
+    jwtSign: lib.sign,
+    jwtVerify: lib.verify,
+    jwtDecode: lib.decode,
+    jwks: lib.jwks,
+    tokenPair: lib.tokenPair,
+    createRefreshToken: lib.createRefreshToken,
+    SUPPORTED_ALGORITHMS: lib.SUPPORTED_ALGORITHMS,
+    session: lib.session,
+    Session: lib.Session,
+    MemoryStore: lib.MemoryStore,
+    oauth: lib.oauth,
+    generatePKCE: lib.generatePKCE,
+    generateState: lib.generateState,
+    OAUTH_PROVIDERS: lib.PROVIDERS,
+    authorize: lib.authorize,
+    can: lib.can,
+    canAny: lib.canAny,
+    Policy: lib.Policy,
+    gate: lib.gate,
+    attachUserHelpers: lib.attachUserHelpers,
+    twoFactor: lib.twoFactor,
+    webauthn: lib.webauthn,
+    trustedDevice: lib.trustedDevice,
+    enrollment: lib.enrollment,
 };

package/lib/auth/authorize.js

@@ -0,0 +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,
+};