n1kFord/session-auth

# 🔐 Session Auth - Express.js 认证样板代码 [](https://nodejs.org/) [](https://expressjs.com/) [](./LICENSE) [](https://jestjs.io/) [](https://github.com/n1kFord/session-auth/pulls) 一个基于 **Express.js** 构建的生产级认证系统，具备基于会话的认证、CSRF 防护、限流和全面的测试。非常适合学习现代 Web 认证模式。 [](https://github.com/n1kFord/session-auth/actions/workflows/test.yml) ## ✨ **功能特性** - 🔑 结合 express-session 的 **基于会话的认证** - 🛡️ **CSRF 防护** (同步令牌模式) - 📦 生产级可扩展的 **Redis 会话存储** - 🗄️ 结合 Mongoose ODM 的 **MongoDB** - 🧪 使用 Jest & Supertest 的 **全面测试套件** - 🚦 防止暴力破解攻击的 **限流** - 🔐 使用 bcrypt 的 **密码哈希** - 🛡️ 用于跨域请求的 **CORS** 配置 - 📝 使用 express-validator 的 **输入验证** - 🔄 登录时的 **会话重新生成** (防止会话固定攻击) - ✅ 如果未提供则 **自动生成用户名** ## 🛠️ **技术栈** ### 后端 - **运行时**: Node.js (v20+) - **框架**: Express.js 5.x - **数据库**: MongoDB 与 Mongoose ODM - **会话存储**: Redis (通过 connect-redis) - **安全**: bcrypt, express-session, CSRF 防护 - **验证**: express-validator - **限流**: express-rate-limit - **CORS**: cors 中间件 ### 测试 - **测试运行器**: Jest - **HTTP 测试**: Supertest - **测试数据库**: MongoDB (独立测试数据库) ### 开发工具 - **进程管理器**: nodemon - **环境变量**: dotenv ## 📋 **前置条件** - Node.js (v20 或更高版本) - Docker 与 Docker Compose (用于 Redis 和 MongoDB) - npm 或 yarn ## 🚀 **开始使用** ### 1. 克隆仓库 ``` git clone https://github.com/n1kFord/session-auth.git cd session-auth ``` ### 2. 安装依赖 ``` npm install ``` ### 3. 设置环境变量 在根目录下创建一个 `.env` 文件： ``` PORT=8080 MONGO_URI=mongodb://localhost:27017/authDB REDIS_CLIENT_URI=redis://localhost:6379 REDIS_SECRET=your-super-secret-key-here ``` ### 4. 使用 Docker Compose 启动 MongoDB 和 Redis ``` docker-compose up -d ``` 这将启动： - MongoDB 端口 `27017` - Redis 端口 `6379` ### 5. 运行应用 ``` # 开发模式（带自动重启） npm run dev # 生产模式 npm start ``` 你的服务器将在 `http://localhost:8080` 运行 ## 🧪 **运行测试** 该项目使用单独的测试数据库 (`auth_test`) 以确保你的开发数据安全。 ``` # 运行所有测试 npm test # 测试将： # - 使用 localhost:27017 上的 MongoDB（确保 Docker 正在运行） # - 创建/使用数据库 'auth_test' # - 每个测试套件后进行清理 ``` ## 📁 **项目结构** ``` session-auth/ ├── src/ │ ├── config/ │ │ ├── constants.js # Environment variables │ │ ├── mongo.js # MongoDB connection │ │ ├── redis.js # Redis connection │ │ └── session.js # Session configuration │ ├── middlewares/ │ │ ├── authenticate.js # Authentication middleware │ │ ├── csrf.js # CSRF protection │ │ ├── fallback.js # Error handling │ │ └── validation.js # Input validation │ ├── models/ │ │ └── User.js # User model │ ├── routers/ │ │ ├── authRouter.js # Auth endpoints │ │ └── userRouter.js # User management │ ├── utils/ │ │ ├── csrf.js # CSRF token utilities │ │ ├── handler.js # Async handler wrapper │ │ ├── hash.js # Password hashing │ │ ├── session.js # Session utilities │ │ └── username.js # Random username generator │ ├── __tests__/ │ │ ├── auth.test.js # Auth endpoint tests │ │ └── user.test.js # User endpoint tests │ └── index.js # Application entry point ├── .env.example ├── .gitignore ├── docker-compose.yml ├── Dockerfile ├── jest.config.js ├── jest.setup.js ├── package.json └── README.md ``` ## 🔌 **API 接口** ### 认证 (`/auth`) | Method | Endpoint | Description | Requires CSRF | |--------|----------|-------------|---------------| | POST | `/auth/register` | 注册新用户 | ❌ No | | POST | `/auth/login` | 用户登录 | ❌ No | | POST | `/auth/logout` | 用户登出 | ❌ No | ### 用户管理 (`/me`) | Method | Endpoint | Description | Requires CSRF | |--------|----------|-------------|---------------| | GET | `/me/` | 获取当前用户资料 | ❌ No | | POST | `/me/change-email` | 修改邮箱地址 | ✅ Yes | | POST | `/me/change-password` | 修改密码 | ✅ Yes | | POST | `/me/change-username` | 修改用户名 | ✅ Yes | | POST | `/me/change-bio` | 修改个人简介 | ✅ Yes | | DELETE | `/me/` | 删除账户 | ✅ Yes | ### 请求示例 **注册：** ``` curl -X POST http://localhost:8080/auth/register \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "password": "secret123", "confirmPassword": "secret123", "username": "john_doe" }' ``` **登录：** ``` curl -X POST http://localhost:8080/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "password": "secret123" }' ``` **受保护的接口（带 CSRF token）：** ``` curl -X GET http://localhost:8080/me/ \ -H "X-XSRF-Token: your-csrf-token-here" \ -H "Cookie: sessionId=your-session-id" ``` ## 🛡️ **安全特性** 1. **基于会话的认证** - HTTP-only cookie - 登录时重新生成会话 - 可配置的会话过期时间 2. **CSRF 防护** - 同步令牌模式 - 会话更改时重新生成令牌 - 所有更改状态的操作都需要验证 3. **限流** - 全局每 15 分钟 100 次请求 - 登录每 15 分钟 10 次尝试 4. **密码安全** - Bcrypt 哈希 (10 轮) - 最小长度要求 - 禁止明文存储 5. **输入验证** - 邮箱验证 - 密码强度检查 - 净化输入内容 ## 🐳 **Docker 支持** 使用 Docker 构建并运行： ``` # 构建镜像 docker build -t session-auth . # 运行容器 docker run -p 8080:8080 --env-file .env session-auth ``` 或者使用 docker-compose（包含 MongoDB 和 Redis）： ``` docker-compose up -d ``` ## 🧪 **测试覆盖率** 测试套件涵盖： - ✅ 用户注册（成功、验证、重复） - ✅ 用户登录（成功、错误凭据、验证） - ✅ 用户登出 - ✅ 修改邮箱（成功、重复、密码错误） - ✅ 修改密码（成功、密码错误、验证） - ✅ 更新用户名/个人简介 - ✅ 删除账户 - ✅ CSRF 防护验证 - ✅ 认证中间件 ## 📝 **环境变量** | Variable | Description | Default | |----------|-------------|---------| | `PORT` | 服务器端口 | `8080` | | `MONGO_URI` | MongoDB 连接字符串 | `mongodb://localhost:27017/authDB` | | `REDIS_CLIENT_URI` | Redis 连接字符串 | `redis://localhost:6379` | | `REDIS_SECRET` | 会话加密密钥 | 必填 | ## 📄 **许可证** 该项目基于 [MIT License](./LICENSE) 授权。 欢迎自由使用、修改和分发，但请保留出处。 ## 🙏 **致谢** - 灵感来源于现代认证模式 - 为学习目的而构建 - 生产级安全实践 - 全面的测试策略 **⭐ 如果这个仓库对你有帮助，请给个 Star！**

标签：API密钥检测, bcrypt, CORS, CSRF防护, Express.js, GNU通用公共许可证, Jest, MITM代理, MongoDB, Mongoose, Node.js, Redis, Supertest, Synchronizer Token Pattern, Syscall, Web开发, 中间件, 会话固定攻击防护, 会话管理, 单元测试, 安全防护, 密码哈希, 搜索引擎查询, 生产就绪, 脚手架, 自定义脚本, 请求拦截, 输入验证, 防暴力破解, 限流