RamosJSouza/secure-nestjs-drizzle-template

# NestJS Security Pro [](https://github.com/RamosJSouza/secure-nestjs-drizzle-template/actions/workflows/ci.yml) [](https://github.com/RamosJSouza/secure-nestjs-drizzle-template/actions/workflows/cd.yml) [](https://codecov.io/gh/RamosJSouza/secure-nestjs-drizzle-template) [](https://nestjs.com/) [](https://orm.drizzle.team/) [](./LICENSE) [](https://github.com/RamosJSouza/secure-nestjs-drizzle-template/pkgs/container/secure-nestjs-drizzle-template) [](https://nodejs.org/) 生产级安全后端架构，基于 NestJS、Drizzle ORM、RBAC 和 JWT RS256。 ## 为什么选择 NestJS Security Pro 大多数模板旨在帮助您快速交付。 **NestJS Security Pro 帮助您快速交付并通过安全审查。** 它专为构建 SaaS、金融科技、健康和企业产品的团队设计，这些产品必须满足安全和治理要求，例如： - SOC 2 就绪（可追溯性、访问控制、审计证据） - 面向 GDPR 的控制（最小权限、事件可追溯性、操作问责） - 内部安全审查和事件响应工作流 无需从头组装 auth、RBAC、日志记录、健康检查和数据库模式，您可以从一个加固的基线开始，节省数周的架构工作。 ## 价值驱动特性 - **企业级 Auth (RS256 JWT)** — 通过非对称密钥防止共享密钥泄露风险。 - **Argon2id 密码哈希** — 密码哈希竞赛获胜者；首次登录时从 bcrypt 透明迁移。 - **JTI Token 撤销** — 每个 access token 携带唯一 ID；通过 Redis 黑名单，注销和密码更改会立即撤销它 — 无需等待 15 分钟的 TTL。 - **Refresh Token 轮换 + 重用检测** — 阻止重放攻击，并在检测到盗窃时撤销所有会话 JTI。 - **凭证填充保护** — 基于 IP 的 Redis 计数器；每小时 20 次失败 → 15 分钟 IP 封锁 (HTTP 429)，适用于所有账户。 - **风险引擎** — 每次成功登录都会通过 5 个威胁信号（新设备、新 IP、IP 失败率、近期锁定、token 重用）进行评分；`critical` 分数 (≥80) 会阻止登录并立即撤销所有会话。 - **更改时验证 currentPassword** — `POST /auth/change-password` 需要当前密码，防止通过被盗 access token 接管账户。 - **会话限制 + 设备指纹识别** — 每个用户最多 10 个会话；最旧的会话随 JTI 撤销被剔除；通过 User-Agent + IP 的完整 SHA-256 hex 跟踪设备。 - **显式注销** — `POST /auth/logout` 撤销 DB 会话并通过 JTI 立即使 access token 失效。 - **审计就绪的会话撤销** — 保留 `revoked_at` 历史记录以确保证据完整性。 - **数据库驱动的 RBAC** — 避免硬编码角色；角色更改在下一个请求中生效（无需重新登录）。 - **RBAC 审计追踪** — `assignPermissions` 将前后差异（`added`、`removed`）记录到审计日志。 - **仅追加审计日志** — 为合规性和事件分析创建可靠的证据链。 - **快速失败配置验证** — 当关键环境变量缺失时，在生产环境中停止不安全的启动。 - **双层速率限制** — 全局 IP 级 (`express-rate-limit`) + 每端点 (`@nestjs/throttler`)；登录限制为每个 IP 每分钟 5 次请求。 - **生产环境中禁用 Swagger** — 在 `NODE_ENV=production` 中永远不会公开 API 蓝图。 - **软删除 Auth 绕过保护** — 已删除的用户无法通过认证；`remove()` 原子性地设置 `deletedAt` 和 `isActive = false`。 - **PII 安全的结构化日志** — Pino 在写入日志前编辑 `authorization`、`cookie`、`password` 和 `refresh_token` 字段。 - **Correlation ID 注入预防** — 对 `X-Correlation-Id` 进行 UUID v4 验证；无效值被丢弃并在服务端替换。 - **生产可观测性** — 带有 correlation ID 的结构化日志、存活/就绪探针、优雅关闭。 - **Drizzle ORM + 迁移工作流** — 通过显式 SQL 迁移实现可预测的模式演进。 - **通过 PostgreSQL RLS 实现多租户** — `TenantDatabaseService.withTenant()` 将每个查询包装在带有 `set_config('app.current_tenant', orgId, true)` 的事务中；并使用显式 `WHERE organization_id` 子句作为双重保障。 - **弹性 Webhooks** — 使用 HMAC-SHA256 签名的 BullMQ 异步交付；当 Redis 不可用时的优雅降级 (`DISABLE_REDIS=true`)。 - **CI/CD 与安全流水线** — GitHub Actions: lint → type-check → coverage ≥ 85% → npm audit → Docker build → Trivy scan；每周 CodeQL + Snyk 扫描；针对 npm/Actions/Docker 的 Dependabot。 ## 架构快照 - **框架:** NestJS 11 - **数据库:** PostgreSQL + Drizzle ORM - **Auth:** JWT RS256 (access 15m, refresh 7d) · Argon2id 哈希 - **授权:** RBAC (`Feature -> Permission -> RolePermission -> Role -> User`) - **缓存/基础设施:** Redis - **速率限制:** express-rate-limit (IP 级) + @nestjs/throttler (每端点) - **可观测性:** Pino + correlation ID + 健康端点 ## 快速开始 ``` cp .env.example .env npm install openssl genrsa -out private.pem 2048 openssl rsa -in private.pem -pubout -out public.pem npm run db:migrate npm run seed:rbac npm run dev ``` 打开 API 文档: `http://localhost:3000/api/docs` *(仅限开发环境 — 生产环境禁用)* ### 数据库命令 (Drizzle) ``` npm run db:generate # generate migration from schema changes npm run db:migrate # apply migrations npm run db:studio # open Drizzle Studio ``` ## 环境要点 - 运行时 DB: `DB_HOST`, `DB_PORT`, `DB_USERNAME`, `DB_PASSWORD`, `DB_DATABASE`, `DB_SSL` - Drizzle 工具: `DATABASE_URL` (可选，CLI 工具首选) - Auth 密钥: `PRIVATE_KEY`, `PUBLIC_KEY` - 安全: `ALLOWED_ORIGINS` (生产环境必需), `NODE_ENV` 详情请参阅: - `docs/en/configuration.md` - `docs/pt-br/configuracao.md` ## 安全加固摘要 | 控制措施 | 实现 | |---------|----------------| | 密码哈希 | Argon2id (64 MiB / 3t / 4p) | | 旧哈希迁移 | 登录时透明 bcrypt → Argon2id | | **Access token 撤销** | **每个 token 的 JTI UUID + Redis 黑名单 (每次请求 O(1))** | | **凭证填充** | **基于 IP 的 Redis 计数器; 20 次/小时 → 15 分钟封锁 (HTTP 429)** | | **会话限制** | **每用户最多 10 个; 最旧的随 JTI 撤销被剔除** | | **设备指纹识别** | **存储每个会话的 (User-Agent + IP) 完整 SHA-256 hex** | | **风险引擎** | **5 信号登录风险评分; `critical` (≥80) → 登录被阻止 + 所有会话被撤销** | | **更改时的 currentPassword** | **`change-password` 在应用新密码前验证当前密码** | | **PermissionGuard 安全性** | **如果缺少 `@RequirePermissions` 则开放失败并记录 WARN 日志; 403 永不暴露权限名称** | | **RBAC 审计追踪** | **`assignPermissions` 记录前后差异** | | **PII 编辑** | **Pino 编辑 auth header、cookie、passwords、refresh_token** | | **Correlation ID 验证** | **强制 UUID v4 格式; 注入的值被丢弃** | | Auth 速率限制 | `/auth/login` 上每个 IP 5 次/分钟 | | Refresh 速率限制 | `/auth/refresh` 上每个 IP 10 次/分钟 | | 全局速率限制 | 每个 IP 300 次/15分钟 | | 安全头 | 带有 CSP 的 Helmet | | Swagger | 在 `NODE_ENV=production` 中禁用 | | CORS | 已解析、已清理; 生产环境必需 | | Trust proxy | 为真实 IP 速率限制配置 | | UUID 验证 | 所有路由参数上的 `ParseUUIDPipe` | | 密码策略 | 最小 8，最大 72，大写+小写+数字 | | 用户枚举 | 所有登录失败统一错误 | | 软删除绕过 | `deletedAt` + `isActive` 原子设置 | | req.user 中的密码 | 在 `JwtStrategy.validate()` 中剥离 | | 角色过期 | 每次请求重新加载 DB — JWT `roleId` 从不被信任 | ## 面向合规的用例 - 构建具有权限操作和完整可审计性的管理后端。 - 通过重放检测和受控的会话失效来强制执行安全的 token 生命周期。 - 为事件响应和安全操作提供结构化日志和追踪 ID。 - 为受监管的产品团队建立可复用的后端基线。 ## 📚 深入探究与教程 来自 Ramos da Informatica 的技术参考（根据需要替换/添加链接）： - [Docker 安全：真实事件的教训](https://ramosdainformatica.com.br/seguranca-em-docker-licoes-de-incidentes-reais/) - [如何为 Node.js 项目安装和配置 SonarQube](https://ramosdainformatica.com.br/como-instalar-e-configurar-sonarqube-para-projetos-node-js/) - [Redis 与关系型数据库的性能](https://ramosdainformatica.com.br/performance-em-aplicacoes-com-bancos-de-dados-relacionais-usando-redis/) - [用实用图表解释 Kubernetes](https://ramosdainformatica.com.br/kubernetes-explicado-com-diagramas-que-fazem-sentido/) - [Elasticsearch 与 Node.js：实用指南](https://ramosdainformatica.com.br/o-que-e-o-elasticsearch-e-como-instalar-e-utilizar-com-o-node/) 使用您自己的权威内容自定义占位符： - [NestJS SOC2 安全蓝图](https://ramosdainformatica.com.br/nestjs-security-blueprint-arquitetura-de-backend-pronta-para-soc2/) - [实践中的 JWT 轮换与会话防御](https://ramosdainformatica.com.br/rotacao-de-jwt-e-defesa-de-sessao-na-pratica-com-nestjs/) ## 安全 有关漏洞披露，请参阅 [SECURITY.md](./SECURITY.md)。合规证据和审计追踪文档：[docs/en/compliance.md](./docs/en/compliance.md)。 ## 贡献或聘请专家帮助 - **贡献:** 提交 issue、改进文档、添加测试，或通过 PR 提交加固改进。 - **咨询:** 如果您的团队需要安全架构、侧重合规的后端设计或现代化支持，请联系： - 网站: [ramosdainformatica.com.br](https://ramosdainformatica.com.br/) - LinkedIn: [Ramos de Souza Janones](https://www.linkedin.com/in/ramos-souza/) ## 权威说明 (PT-BR) Este projeto e sua arquitetura sao mantidos por **Ramos de Souza Janones**, engenheiro senior com foco em Node.js/NestJS, seguranca de aplicacoes e arquiteturas prontas para producao e auditoria. ## 文档 - 英语文档: `docs/en/` - 葡萄牙语: `docs/pt-br/` - 旧版镜像: `documentation/`

标签：Boilerplate, Docker, Drizzle ORM, Fintech, GDPR, GNU通用公共许可证, Healthtech, JWT RS256, NestJS, Node.js, RBAC, SaaS, SOC 2, TypeScript, 人工智能安全, 仅追加日志, 企业级脚手架, 医疗科技, 合规性, 后端开发, 基于角色的访问控制, 安全插件, 安全架构, 安全防御评估, 审计日志, 密钥轮换, 授权, 搜索引擎查询, 最佳实践, 权限管理, 模型越狱, 测试用例, 生产就绪, 请求拦截, 金融科技