Authorization

Auth Guard

AuthGuard is the route-level companion to the package traits and NetPress authorization helpers. It produces Express 5 middleware that short-circuits requests with a 401 when the user is not authenticated or a 403 when they fail the authorization check.

This package AuthGuard is authorization middleware, not the Laravel auth manager itself. Laravel-style named authentication guards now live in NetPress core under Auth from @admicaa/netpress; AuthGuard simply authenticates through that core layer first, then performs policy, role, or permission checks.

Importing

import { AuthGuard } from '@admicaa/netpress-permissions';

Each method returns a fresh middleware function — safe to reuse across routes or mount per-route.

Require Authentication

router.get('/dashboard', AuthGuard.authenticated(), dashboardController.index);

Throws HttpException(401, 'Unauthenticated') if req.user is absent.

Require An Ability

router.post('/posts', AuthGuard.can('posts.create'), postsController.store);
router.patch('/posts/:id', AuthGuard.can('update', 'id'), postsController.update);

The second argument can be:

a string — treated as the name of a param on req.params to pass as the resource
a function — called with req and returns any value (typically a model)
null — no resource is passed to the authorization helper

Every can check runs through core can(user, ability, resource), so registered policies are consulted first and permission-aware models fall back through hasPermissionTo().

Require Any / All Abilities

AuthGuard.canAny(['posts.publish', 'posts.archive']);
AuthGuard.canAll(['billing.read', 'billing.write']);

canAny allows the request when at least one ability passes. canAll demands every listed ability.

Role Checks

AuthGuard.role('editor', 'admin');      // any of the listed roles
AuthGuard.roles('editor', 'reviewer');  // must have ALL of the listed roles

Both helpers read from the user's getRoleNames() (or roles()) to stay consistent with the HasRoles trait.

Permission Checks

AuthGuard.permission('posts.publish', 'posts.archive');
AuthGuard.permissions('billing.read', 'billing.write');

These read the user's stored permission graph directly. Use can() when you want policy-aware ability checks, and permission() / permissions() when you want explicit permission-name checks.

Guest Only Routes

router.get('/login', AuthGuard.guest(), loginController.show);

Returns 403 if req.user is present.

Custom Resource Resolution

router.patch('/posts/:id', AuthGuard.can('update', async (req) => {
  return Post.find(req.params.id);
}), postsController.update);

The resolver runs per-request. Combine it with an async cache or request memoization if you need the model for both the guard and the controller.

Error Handling

AuthGuard throws HttpException from @admicaa/netpress. The framework's default error handler maps the status to the response code. If you use a custom error handler, make sure it respects exception.status.

Stacking Middleware

router.use('/admin', AuthGuard.authenticated(), AuthGuard.role('admin'));

Stacks behave like regular Express middleware: the first one that rejects wins. Put the cheapest check (authentication) first.