说明

指定要精确遵循的逐步任务序列。

步骤 1：设计数据模型

为用户和认证设计数据库模式。

任务：

• 设计用户表（id、email、password_hash、role、created_at、updated_at）
• 刷新令牌表（可选）
• OAuth 提供商表（如果使用社交登录）
• 切勿以明文存储密码（必须使用 bcrypt/argon2 哈希）

示例（PostgreSQL）：

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255),  -- NULL if OAuth only
    role VARCHAR(50) DEFAULT 'user',
    is_verified BOOLEAN DEFAULT false,
    mfa_secret VARCHAR(255),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE refresh_tokens (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    token VARCHAR(500) UNIQUE NOT NULL,
    expires_at TIMESTAMP NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_refresh_tokens_user_id ON refresh_tokens(user_id);

步骤 2：实现密码安全性

实现密码哈希和验证逻辑。

任务：

• 使用 bcrypt（Node.js）或 argon2（Python）
• 将盐轮次设置为至少 10
• 密码强度验证（至少 8 个字符，大写/小写字母，数字，特殊字符）

决策标准：

• Node.js 项目 → 使用 bcrypt 库
• Python 项目 → 使用 argon2-cffi 或 passlib
• 性能关键型场景 → 选择 bcrypt
• 需要最高安全性的场景 → 选择 argon2

示例（Node.js + TypeScript）：

import bcrypt from 'bcrypt';

const SALT_ROUNDS = 12;

export async function hashPassword(password: string): Promise<string> {
    // Validate password strength
    if (password.length < 8) {
        throw new Error('Password must be at least 8 characters');
    }

    const hasUpperCase = /[A-Z]/.test(password);
    const hasLowerCase = /[a-z]/.test(password);
    const hasNumber = /\d/.test(password);
    const hasSpecial = /[!@#$%^&*(),.?":{}|<>]/.test(password);

    if (!hasUpperCase || !hasLowerCase || !hasNumber || !hasSpecial) {
        throw new Error('Password must contain uppercase, lowercase, number, and special character');
    }

    return await bcrypt.hash(password, SALT_ROUNDS);
}

export async function verifyPassword(password: string, hash: string): Promise<boolean> {
    return await bcrypt.compare(password, hash);
}

步骤 3：生成和验证 JWT 令牌

为基于 JWT 的认证实现令牌系统。

任务：

• 访问令牌（短过期时间：15 分钟）
• 刷新令牌（长过期时间：7–30 天）
• 使用强 SECRET 密钥进行 JWT 签名（通过环境变量管理）
• 令牌负载中仅包含最少必要信息（user_id、role）

示例（Node.js）：

import jwt from 'jsonwebtoken';

const ACCESS_TOKEN_SECRET = process.env.ACCESS_TOKEN_SECRET!;
const REFRESH_TOKEN_SECRET = process.env.REFRESH_TOKEN_SECRET!;
const ACCESS_TOKEN_EXPIRY = '15m';
const REFRESH_TOKEN_EXPIRY = '7d';

interface TokenPayload {
    userId: string;
    email: string;
    role: string;
}

export function generateAccessToken(payload: TokenPayload): string {
    return jwt.sign(payload, ACCESS_TOKEN_SECRET, {
        expiresIn: ACCESS_TOKEN_EXPIRY,
        issuer: 'your-app-name',
        audience: 'your-app-users'
    });
}

export function generateRefreshToken(payload: TokenPayload): string {
    return jwt.sign(payload, REFRESH_TOKEN_SECRET, {
        expiresIn: REFRESH_TOKEN_EXPIRY,
        issuer: 'your-app-name',
        audience: 'your-app-users'
    });
}

export function verifyAccessToken(token: string): TokenPayload {
    return jwt.verify(token, ACCESS_TOKEN_SECRET, {
        issuer: 'your-app-name',
        audience: 'your-app-users'
    }) as TokenPayload;
}

export function verifyRefreshToken(token: string): TokenPayload {
    return jwt.verify(token, REFRESH_TOKEN_SECRET, {
        issuer: 'your-app-name',
        audience: 'your-app-users'
    }) as TokenPayload;
}

步骤 4：实现认证中间件

编写认证中间件以保护 API 请求。

检查清单：

• 从 Authorization 标头中提取 Bearer 令牌
• 验证令牌并检查过期时间
• 为有效令牌将用户信息附加到 req.user
• 错误处理（401 未授权）

示例（Express.js）：

import { Request, Response, NextFunction } from 'express';
import { verifyAccessToken } from './jwt';

export interface AuthRequest extends Request {
    user?: {
        userId: string;
        email: string;
        role: string;
    };
}

export function authenticateToken(req: AuthRequest, res: Response, next: NextFunction) {
    const authHeader = req.headers['authorization'];
    const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN

    if (!token) {
        return res.status(401).json({ error: 'Access token required' });
    }

    try {
        const payload = verifyAccessToken(token);
        req.user = payload;
        next();
    } catch (error) {
        if (error.name === 'TokenExpiredError') {
            return res.status(401).json({ error: 'Token expired' });
        }
        return res.status(403).json({ error: 'Invalid token' });
    }
}

// Role-based authorization middleware
export function requireRole(...roles: string[]) {
    return (req: AuthRequest, res: Response, next: NextFunction) => {
        if (!req.user) {
            return res.status(401).json({ error: 'Authentication required' });
        }

        if (!roles.includes(req.user.role)) {
            return res.status(403).json({ error: 'Insufficient permissions' });
        }

        next();
    };
}

步骤 5：实现认证 API 端点

编写用于注册、登录、令牌刷新等的 API。

任务：

• POST /auth/register - 注册
• POST /auth/login - 登录
• POST /auth/refresh - 令牌刷新
• POST /auth/logout - 注销
• GET /auth/me - 当前用户信息

示例：

import express from 'express';
import { hashPassword, verifyPassword } from './password';
import { generateAccessToken, generateRefreshToken, verifyRefreshToken } from './jwt';
import { authenticateToken } from './middleware';

const router = express.Router();

// Registration
router.post('/register', async (req, res) => {
    try {
        const { email, password } = req.body;

        // Check for duplicate email
        const existingUser = await db.user.findUnique({ where: { email } });
        if (existingUser) {
            return res.status(409).json({ error: 'Email already exists' });
        }

        // Hash the password
        const passwordHash = await hashPassword(password);

        // Create the user
        const user = await db.user.create({
            data: { email, password_hash: passwordHash, role: 'user' }
        });

        // Generate tokens
        const accessToken = generateAccessToken({
            userId: user.id,
            email: user.email,
            role: user.role
        });
        const refreshToken = generateRefreshToken({
            userId: user.id,
            email: user.email,
            role: user.role
        });

        // Store Refresh token in DB
        await db.refreshToken.create({
            data: {
                user_id: user.id,
                token: refreshToken,
                expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000) // 7 days
            }
        });

        res.status(201).json({
            user: { id: user.id, email: user.email, role: user.role },
            accessToken,
            refreshToken
        });
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

// Login
router.post('/login', async (req, res) => {
    try {
        const { email, password } = req.body;

        // Find the user
        const user = await db.user.findUnique({ where: { email } });
        if (!user || !user.password_hash) {
            return res.status(401).json({ error: 'Invalid credentials' });
        }

        // Verify the password
        const isValid = await verifyPassword(password, user.password_hash);
        if (!isValid) {
            return res.status(401).json({ error: 'Invalid credentials' });
        }

        // Generate tokens
        const accessToken = generateAccessToken({
            userId: user.id,
            email: user.email,
            role: user.role
        });
        const refreshToken = generateRefreshToken({
            userId: user.id,
            email: user.email,
            role: user.role
        });

        // Store Refresh token
        await db.refreshToken.create({
            data: {
                user_id: user.id,
                token: refreshToken,
                expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
            }
        });

        res.json({
            user: { id: user.id, email: user.email, role: user.role },
            accessToken,
            refreshToken
        });
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

// Token refresh
router.post('/refresh', async (req, res) => {
    try {
        const { refreshToken } = req.body;

        if (!refreshToken) {
            return res.status(401).json({ error: 'Refresh token required' });
        }

        // Verify Refresh token
        const payload = verifyRefreshToken(refreshToken);

        // Check token in DB
        const storedToken = await db.refreshToken.findUnique({
            where: { token: refreshToken }
        });

        if (!storedToken || storedToken.expires_at < new Date()) {
            return res.status(403).json({ error: 'Invalid or expired refresh token' });
        }

        // Generate new Access token
        const accessToken = generateAccessToken({
            userId: payload.userId,
            email: payload.email,
            role: payload.role
        });

        res.json({ accessToken });
    } catch (error) {
        res.status(403).json({ error: 'Invalid refresh token' });
    }
});

// Current user info
router.get('/me', authenticateToken, async (req: AuthRequest, res) => {
    try {
        const user = await db.user.findUnique({
            where: { id: req.user!.userId },
            select: { id: true, email: true, role: true, created_at: true }
        });

        res.json({ user });
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

export default router;

输出格式

定义交付成果应遵循的确切格式。

基本结构

Project directory/
├── src/
│   ├── auth/
│   │   ├── password.ts          # password hashing/verification
│   │   ├── jwt.ts                # JWT token generation/verification
│   │   ├── middleware.ts         # authentication middleware
│   │   └── routes.ts             # authentication API endpoints
│   ├── models/
│   │   └── User.ts               # user model
│   └── database/
│       └── schema.sql            # database schema
├── .env.example                  # environment variable template
└── README.md                     # authentication system documentation

环境变量文件 (.env.example)

# JWT Secrets (MUST change in production)
ACCESS_TOKEN_SECRET=your-access-token-secret-min-32-characters
REFRESH_TOKEN_SECRET=your-refresh-token-secret-min-32-characters

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/myapp

# OAuth (Optional)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

约束

指定强制性规则和禁止的操作。

强制性规则（必须）

1. 密码安全：切勿以明文存储密码
   • 使用经过验证的哈希算法，如 bcrypt 或 argon2
   • 盐轮次至少为 10
2. 环境变量管理：通过环境变量管理所有密钥
   • 将 .env 文件添加到 .gitignore
   • 通过 .env.example 提供所需变量列表
3. 令牌过期：访问令牌应为短期有效（15 分钟），刷新令牌应适当延长（7 天）
   • 平衡安全性和用户体验
   • 将刷新令牌存储在数据库中以便撤销

禁止的操作（不得）

1. 明文密码：切勿以明文存储密码或将其打印到日志中
   • 严重的安全风险
   • 法律责任问题
2. 硬编码 JWT SECRET：不要直接在代码中写入 SECRET 密钥
   • 存在在 GitHub 上暴露的风险
   • 生产环境安全漏洞
3. 令牌中的敏感数据：不要在 JWT 负载中包含密码、卡号或其他敏感数据
   • JWT 可以被解码（它没有加密）
   • 仅包含最少信息（user_id、role）

安全规则

• 速率限制：对登录 API 应用速率限制（防止暴力攻击）
• 需要 HTTPS：在生产环境中仅使用 HTTPS
• CORS 配置：仅允许已批准的域访问 API
• 输入验证：验证所有用户输入（防止 SQL 注入和 XSS）

示例

演示如何通过实际用例应用此技能。

示例 1：Express.js + PostgreSQL JWT 认证

情况：为 Node.js Express 应用添加基于 JWT 的用户认证

用户请求：

Add JWT authentication to an Express.js app using PostgreSQL,
with access token expiry of 15 minutes and refresh token expiry of 7 days.

技能应用过程：

1. 安装包：

   npm install jsonwebtoken bcrypt pg
   npm install --save-dev @types/jsonwebtoken @types/bcrypt
   

2. 创建数据库模式（使用上面的 SQL）

3. 设置环境变量：

   ACCESS_TOKEN_SECRET=$(openssl rand -base64 32)
   REFRESH_TOKEN_SECRET=$(openssl rand -base64 32)
   

4. 实现认证模块（使用上面的代码示例）

5. 连接 API 路由：

   import authRoutes from './auth/routes';
   app.use('/api/auth', authRoutes);
   

最终结果：基于 JWT 的认证系统完成，注册/登录/令牌刷新 API 正常工作

示例 2：基于角色的访问控制（RBAC）

情况：区分管理员和普通用户的权限系统

用户请求：

Create an API accessible only to administrators.
Regular users should receive a 403 error.

最终结果：

// Admin-only API
router.delete('/users/:id',
    authenticateToken,           // verify authentication
    requireRole('admin'),         // verify role
    async (req, res) => {
        // user deletion logic
        await db.user.delete({ where: { id: req.params.id } });
        res.json({ message: 'User deleted' });
    }
);

// Usage example
// Regular user (role: 'user') request → 403 Forbidden
// Admin (role: 'admin') request → 200 OK

最佳实践

有效使用此技能的建议。

质量改进

1. 密码轮换策略：建议定期更改密码
   • 每 90 天发送更改通知
   • 防止重用最近 5 个密码
   • 平衡用户体验和安全性
2. 多因素认证（MFA）：对重要账户应用 2FA
   • 使用 TOTP 应用，如 Google Authenticator 或 Authy
   • SMS 安全性较低（存在 SIM 卡交换风险）
   • 提供备份代码
3. 审计日志记录：记录所有认证事件
   • 记录登录成功/失败、IP 地址和用户代理
   • 异常检测和事后分析
   • GDPR 合规性（排除敏感数据）

效率改进

• 令牌黑名单：在注销时撤销刷新令牌
• Redis 缓存：缓存频繁使用的用户数据
• 数据库索引：在 email 和 refresh_token 上添加索引

常见问题

常见问题及其解决方案。

问题 1："JsonWebTokenError: invalid signature"

症状：

• 令牌验证期间发生错误
• 登录成功但认证的 API 调用失败

原因：访问令牌和刷新令牌的 SECRET 密钥不同，但使用了相同的密钥来验证两者。

解决方案：

1. 检查环境变量：ACCESS_TOKEN_SECRET、REFRESH_TOKEN_SECRET
2. 为每种令牌类型使用正确的 SECRET
3. 验证环境变量是否正确加载（初始化 dotenv）

问题 2：前端因 CORS 错误无法登录

症状：浏览器控制台中出现 "CORS policy" 错误

原因：Express 服务器缺少 CORS 配置

解决方案：

import cors from 'cors';

app.use(cors({
    origin: process.env.FRONTEND_URL || 'http://localhost:3000',
    credentials: true
}));

问题 3：刷新令牌持续过期

症状：用户频繁被登出

原因：刷新令牌未在数据库中正确管理

解决方案：

1. 确认刷新令牌在创建时已保存到数据库
2. 设置适当的过期时间（至少 7 天）
3. 添加定时任务以定期清理过期的令牌

参考资料

官方文档

• JWT.io - JSON Web Token 简介
• OWASP 认证备忘单
• OAuth 2.0 RFC 6749

库

• jsonwebtoken (Node.js)
• bcrypt (Node.js)
• Passport.js - 多种认证策略
• NextAuth.js - Next.js 认证

安全指南

• OWASP Top 10
• NIST 数字身份指南

元数据

版本

• 当前版本：1.0.0
• 最后更新：2025-01-01
• 兼容平台：Claude、ChatGPT、Gemini

相关技能

• api-design: API 端点设计
• security: 安全最佳实践

标签

#authentication #authorization #JWT #OAuth #security #backend

每周安装数

1

仓库

akillness/oh-my-gods

首次出现

1 天前

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

mcpjam1

claude-code1

replit1

junie1

windsurf1

zencoder1

Input Example

Build a user authentication system:
- Auth method: JWT
- Framework: Express.js + TypeScript
- Database: PostgreSQL
- MFA: Google Authenticator support
- Social login: Google, GitHub
- Refresh Token: enabled

Instructions

Specifies the step-by-step task sequence to follow precisely.

Step 1: Design the Data Model

Design the database schema for users and authentication.

Tasks :

• Design the User table (id, email, password_hash, role, created_at, updated_at)
• RefreshToken table (optional)
• OAuthProvider table (if using social login)
• Never store passwords in plaintext (bcrypt/argon2 hashing is mandatory)

Example (PostgreSQL):

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255),  -- NULL if OAuth only
    role VARCHAR(50) DEFAULT 'user',
    is_verified BOOLEAN DEFAULT false,
    mfa_secret VARCHAR(255),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE refresh_tokens (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    token VARCHAR(500) UNIQUE NOT NULL,
    expires_at TIMESTAMP NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_refresh_tokens_user_id ON refresh_tokens(user_id);

Step 2: Implement Password Security

Implement password hashing and verification logic.

Tasks :

• Use bcrypt (Node.js) or argon2 (Python)
• Set salt rounds to a minimum of 10
• Password strength validation (minimum 8 chars, upper/lowercase, numbers, special characters)

Decision Criteria :

• Node.js projects → use the bcrypt library
• Python projects → use argon2-cffi or passlib
• Performance-critical cases → choose bcrypt
• Cases requiring maximum security → choose argon2

Example (Node.js + TypeScript):

import bcrypt from 'bcrypt';

const SALT_ROUNDS = 12;

export async function hashPassword(password: string): Promise<string> {
    // Validate password strength
    if (password.length < 8) {
        throw new Error('Password must be at least 8 characters');
    }

    const hasUpperCase = /[A-Z]/.test(password);
    const hasLowerCase = /[a-z]/.test(password);
    const hasNumber = /\d/.test(password);
    const hasSpecial = /[!@#$%^&*(),.?":{}|<>]/.test(password);

    if (!hasUpperCase || !hasLowerCase || !hasNumber || !hasSpecial) {
        throw new Error('Password must contain uppercase, lowercase, number, and special character');
    }

    return await bcrypt.hash(password, SALT_ROUNDS);
}

export async function verifyPassword(password: string, hash: string): Promise<boolean> {
    return await bcrypt.compare(password, hash);
}

Step 3: Generate and Verify JWT Tokens

Implement a token system for JWT-based authentication.

Tasks :

• Access Token (short expiry: 15 minutes)
• Refresh Token (long expiry: 7–30 days)
• Use a strong SECRET key for JWT signing (manage via environment variables)
• Include only the minimum necessary information in the token payload (user_id, role)

Example (Node.js):

import jwt from 'jsonwebtoken';

const ACCESS_TOKEN_SECRET = process.env.ACCESS_TOKEN_SECRET!;
const REFRESH_TOKEN_SECRET = process.env.REFRESH_TOKEN_SECRET!;
const ACCESS_TOKEN_EXPIRY = '15m';
const REFRESH_TOKEN_EXPIRY = '7d';

interface TokenPayload {
    userId: string;
    email: string;
    role: string;
}

export function generateAccessToken(payload: TokenPayload): string {
    return jwt.sign(payload, ACCESS_TOKEN_SECRET, {
        expiresIn: ACCESS_TOKEN_EXPIRY,
        issuer: 'your-app-name',
        audience: 'your-app-users'
    });
}

export function generateRefreshToken(payload: TokenPayload): string {
    return jwt.sign(payload, REFRESH_TOKEN_SECRET, {
        expiresIn: REFRESH_TOKEN_EXPIRY,
        issuer: 'your-app-name',
        audience: 'your-app-users'
    });
}

export function verifyAccessToken(token: string): TokenPayload {
    return jwt.verify(token, ACCESS_TOKEN_SECRET, {
        issuer: 'your-app-name',
        audience: 'your-app-users'
    }) as TokenPayload;
}

export function verifyRefreshToken(token: string): TokenPayload {
    return jwt.verify(token, REFRESH_TOKEN_SECRET, {
        issuer: 'your-app-name',
        audience: 'your-app-users'
    }) as TokenPayload;
}

Step 4: Implement Authentication Middleware

Write authentication middleware to protect API requests.

Checklist :

• Extract Bearer token from the Authorization header
• Verify token and check expiry
• Attach user info to req.user for valid tokens
• Error handling (401 Unauthorized)

Example (Express.js):

import { Request, Response, NextFunction } from 'express';
import { verifyAccessToken } from './jwt';

export interface AuthRequest extends Request {
    user?: {
        userId: string;
        email: string;
        role: string;
    };
}

export function authenticateToken(req: AuthRequest, res: Response, next: NextFunction) {
    const authHeader = req.headers['authorization'];
    const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN

    if (!token) {
        return res.status(401).json({ error: 'Access token required' });
    }

    try {
        const payload = verifyAccessToken(token);
        req.user = payload;
        next();
    } catch (error) {
        if (error.name === 'TokenExpiredError') {
            return res.status(401).json({ error: 'Token expired' });
        }
        return res.status(403).json({ error: 'Invalid token' });
    }
}

// Role-based authorization middleware
export function requireRole(...roles: string[]) {
    return (req: AuthRequest, res: Response, next: NextFunction) => {
        if (!req.user) {
            return res.status(401).json({ error: 'Authentication required' });
        }

        if (!roles.includes(req.user.role)) {
            return res.status(403).json({ error: 'Insufficient permissions' });
        }

        next();
    };
}

Step 5: Implement Authentication API Endpoints

Write APIs for registration, login, token refresh, etc.

Tasks :

• POST /auth/register - registration
• POST /auth/login - login
• POST /auth/refresh - token refresh
• POST /auth/logout - logout
• GET /auth/me - current user info

Example :

import express from 'express';
import { hashPassword, verifyPassword } from './password';
import { generateAccessToken, generateRefreshToken, verifyRefreshToken } from './jwt';
import { authenticateToken } from './middleware';

const router = express.Router();

// Registration
router.post('/register', async (req, res) => {
    try {
        const { email, password } = req.body;

        // Check for duplicate email
        const existingUser = await db.user.findUnique({ where: { email } });
        if (existingUser) {
            return res.status(409).json({ error: 'Email already exists' });
        }

        // Hash the password
        const passwordHash = await hashPassword(password);

        // Create the user
        const user = await db.user.create({
            data: { email, password_hash: passwordHash, role: 'user' }
        });

        // Generate tokens
        const accessToken = generateAccessToken({
            userId: user.id,
            email: user.email,
            role: user.role
        });
        const refreshToken = generateRefreshToken({
            userId: user.id,
            email: user.email,
            role: user.role
        });

        // Store Refresh token in DB
        await db.refreshToken.create({
            data: {
                user_id: user.id,
                token: refreshToken,
                expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000) // 7 days
            }
        });

        res.status(201).json({
            user: { id: user.id, email: user.email, role: user.role },
            accessToken,
            refreshToken
        });
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

// Login
router.post('/login', async (req, res) => {
    try {
        const { email, password } = req.body;

        // Find the user
        const user = await db.user.findUnique({ where: { email } });
        if (!user || !user.password_hash) {
            return res.status(401).json({ error: 'Invalid credentials' });
        }

        // Verify the password
        const isValid = await verifyPassword(password, user.password_hash);
        if (!isValid) {
            return res.status(401).json({ error: 'Invalid credentials' });
        }

        // Generate tokens
        const accessToken = generateAccessToken({
            userId: user.id,
            email: user.email,
            role: user.role
        });
        const refreshToken = generateRefreshToken({
            userId: user.id,
            email: user.email,
            role: user.role
        });

        // Store Refresh token
        await db.refreshToken.create({
            data: {
                user_id: user.id,
                token: refreshToken,
                expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
            }
        });

        res.json({
            user: { id: user.id, email: user.email, role: user.role },
            accessToken,
            refreshToken
        });
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

// Token refresh
router.post('/refresh', async (req, res) => {
    try {
        const { refreshToken } = req.body;

        if (!refreshToken) {
            return res.status(401).json({ error: 'Refresh token required' });
        }

        // Verify Refresh token
        const payload = verifyRefreshToken(refreshToken);

        // Check token in DB
        const storedToken = await db.refreshToken.findUnique({
            where: { token: refreshToken }
        });

        if (!storedToken || storedToken.expires_at < new Date()) {
            return res.status(403).json({ error: 'Invalid or expired refresh token' });
        }

        // Generate new Access token
        const accessToken = generateAccessToken({
            userId: payload.userId,
            email: payload.email,
            role: payload.role
        });

        res.json({ accessToken });
    } catch (error) {
        res.status(403).json({ error: 'Invalid refresh token' });
    }
});

// Current user info
router.get('/me', authenticateToken, async (req: AuthRequest, res) => {
    try {
        const user = await db.user.findUnique({
            where: { id: req.user!.userId },
            select: { id: true, email: true, role: true, created_at: true }
        });

        res.json({ user });
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

export default router;

Output format

Defines the exact format that deliverables should follow.

Basic Structure

Project directory/
├── src/
│   ├── auth/
│   │   ├── password.ts          # password hashing/verification
│   │   ├── jwt.ts                # JWT token generation/verification
│   │   ├── middleware.ts         # authentication middleware
│   │   └── routes.ts             # authentication API endpoints
│   ├── models/
│   │   └── User.ts               # user model
│   └── database/
│       └── schema.sql            # database schema
├── .env.example                  # environment variable template
└── README.md                     # authentication system documentation

Environment Variable File (.env.example)

# JWT Secrets (MUST change in production)
ACCESS_TOKEN_SECRET=your-access-token-secret-min-32-characters
REFRESH_TOKEN_SECRET=your-refresh-token-secret-min-32-characters

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/myapp

# OAuth (Optional)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Constraints

Specifies mandatory rules and prohibited actions.

Mandatory Rules (MUST)

1. Password Security : Never store passwords in plaintext

   • Use a proven hashing algorithm such as bcrypt or argon2
   • Salt rounds minimum of 10

2. Environment Variable Management : Manage all secret keys via environment variables

   • Add .env files to .gitignore
   • Provide a list of required variables via .env.example

3. Token Expiry : Access Tokens should be short-lived (15 min), Refresh Tokens appropriately longer (7 days)

   • Balance security and user experience
   • Store Refresh Tokens in the DB to enable revocation

Prohibited Actions (MUST NOT)

1. Plaintext Passwords : Never store passwords in plaintext or print them to logs

   • Serious security risk
   • Legal liability issues

2. Hardcoding JWT SECRET : Do not write SECRET keys directly in code

   • Risk of being exposed on GitHub
   • Production security vulnerability

3. Sensitive Data in Tokens : Do not include passwords, card numbers, or other sensitive data in JWT payloads

   • JWT can be decoded (it is not encrypted)
   • Include only the minimum information (user_id, role)

Security Rules

• Rate Limiting : Apply rate limiting to the login API (prevents brute-force attacks)
• HTTPS Required : Use HTTPS only in production environments
• CORS Configuration : Allow only approved domains to access the API
• Input Validation : Validate all user input (prevents SQL Injection and XSS)

Examples

Demonstrates how to apply the skill through real-world use cases.

Example 1: Express.js + PostgreSQL JWT Authentication

Situation : Adding JWT-based user authentication to a Node.js Express app

User Request :

Add JWT authentication to an Express.js app using PostgreSQL,
with access token expiry of 15 minutes and refresh token expiry of 7 days.

Skill Application Process :

1. Install packages:

   npm install jsonwebtoken bcrypt pg
   npm install --save-dev @types/jsonwebtoken @types/bcrypt
   

2. Create the database schema (use the SQL above)

3. Set environment variables:

   ACCESS_TOKEN_SECRET=$(openssl rand -base64 32)
   REFRESH_TOKEN_SECRET=$(openssl rand -base64 32)
   

4. Implement auth modules (use the code examples above)

5. Connect API routes:

   import authRoutes from './auth/routes';
   app.use('/api/auth', authRoutes);
   

Final Result : JWT-based authentication system complete, registration/login/token-refresh APIs working

Example 2: Role-Based Access Control (RBAC)

Situation : A permission system that distinguishes administrators from regular users

User Request :

Create an API accessible only to administrators.
Regular users should receive a 403 error.

Final Result :

// Admin-only API
router.delete('/users/:id',
    authenticateToken,           // verify authentication
    requireRole('admin'),         // verify role
    async (req, res) => {
        // user deletion logic
        await db.user.delete({ where: { id: req.params.id } });
        res.json({ message: 'User deleted' });
    }
);

// Usage example
// Regular user (role: 'user') request → 403 Forbidden
// Admin (role: 'admin') request → 200 OK

Best practices

Recommendations for using this skill effectively.

Quality Improvement

1. Password Rotation Policy : Recommend periodic password changes

   • Change notification every 90 days
   • Prevent reuse of the last 5 passwords
   • Balance user experience and security

2. Multi-Factor Authentication (MFA) : Apply 2FA to important accounts

   • Use TOTP apps such as Google Authenticator or Authy
   • SMS is less secure (risk of SIM swapping)
   • Provide backup codes

3. Audit Logging : Log all authentication events

   • Record login success/failure, IP address, and User Agent
   • Anomaly detection and post-incident analysis
   • GDPR compliance (exclude sensitive data)

Efficiency Improvements

• Token Blacklist : Revoke Refresh Tokens on logout
• Redis Caching : Cache frequently used user data
• Database Indexing : Add indexes on email and refresh_token

Common Issues

Common problems and their solutions.

Issue 1: "JsonWebTokenError: invalid signature"

Symptom :

• Error occurs during token verification
• Login succeeds but authenticated API calls fail

Cause : The SECRET keys for Access Token and Refresh Token are different, but the same key is being used to verify both.

Solution :

1. Check environment variables: ACCESS_TOKEN_SECRET, REFRESH_TOKEN_SECRET
2. Use the correct SECRET for each token type
3. Verify that environment variables load correctly (initialize dotenv)

Issue 2: Frontend Cannot Log In Due to CORS Error

Symptom : "CORS policy" error in the browser console

Cause : Missing CORS configuration on the Express server

Solution :

import cors from 'cors';

app.use(cors({
    origin: process.env.FRONTEND_URL || 'http://localhost:3000',
    credentials: true
}));

Issue 3: Refresh Token Keeps Expiring

Symptom : Users are frequently logged out

Cause : Refresh Token is not properly managed in the DB

Solution :

1. Confirm Refresh Token is saved to DB upon creation
2. Set an appropriate expiry time (minimum 7 days)
3. Add a cron job to regularly clean up expired tokens

References

Official Documentation

• JWT.io - JSON Web Token Introduction
• OWASP Authentication Cheat Sheet
• OAuth 2.0 RFC 6749

Libraries

• jsonwebtoken (Node.js)
• bcrypt (Node.js)
• Passport.js - multiple authentication strategies
• NextAuth.js - Next.js authentication

Security Guides

• OWASP Top 10
• NIST Digital Identity Guidelines

Metadata

Version

• Current Version : 1.0.0
• Last Updated : 2025-01-01
• Compatible Platforms : Claude, ChatGPT, Gemini

Related Skills

• api-design: API endpoint design
• security: Security best practices

Tags

#authentication #authorization #JWT #OAuth #security #backend

Weekly Installs

1

Repository

akillness/oh-my-gods

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

mcpjam1

claude-code1

replit1

junie1

windsurf1

zencoder1