security-patterns

Security Patterns 是一份安全实现模式参考，用于在开发过程中落地认证、授权、加密、密钥管理、CORS 配置、输入校验与限流等安全能力。资料以代码示例和检查清单的形式组织，适合在涉及安全面的任务中按步骤实施。

用途与触发场景当任务涉及认证流程、加密、密钥管理、CORS 配置、输入校验或限流时，可加载本模式。若当前任务不涉及安全面，则可跳过。

实施工作流资料提供了一份可复制的检查清单，用于跟踪进度：

选择认证策略
实现授权模型
设置密码哈希
配置密钥管理
启用加密（传输中与静态）
配置 CORS
添加限流
对照反模式清单进行校验

认证模式

JWT：示例展示使用 jsonwebtoken 生成访问令牌（15 分钟，HS256）与刷新令牌（7 天），并强调刷新令牌应放入 httpOnly、secure、sameSite=strict 的 Cookie，访问令牌存于内存，而非 localStorage。验证中间件固定算法为 HS256，并区分令牌过期与无效令牌的响应。
基于会话的认证：示例使用 express-session 与 connect-redis，配置 httpOnly、secure（生产环境）、sameSite=strict 及 24 小时有效期。
OAuth 2.0 / OIDC：概述所有客户端使用带 PKCE 的授权码流程，包括重定向参数（state、nonce、code_challenge 等）、校验 state、后端用 code_verifier 交换令牌、验证 id_token（签名、iss、aud、exp、nonce）后创建会话或 JWT。公共客户端（SPA、移动端）不携带 client_secret，并明确禁止使用已弃用的隐式流程。
API Key 认证：示例强调不要直接比较（防时序攻击），而应对 API Key 做 SHA-256 哈希后查库，并检查是否已撤销。

授权模型

RBAC：示例定义 admin、editor、viewer 三种角色的权限集合，并提供 authorize 中间件按所需权限校验。
资源级授权：示例指出仅检查角色不够，还需检查资源归属或管理员身份；同时强调避免批量赋值，只允许白名单字段（如 title、body）更新。

密码处理

使用 bcrypt，SALT_ROUNDS 为 12（现代硬件约 250ms）。
登录时对未知邮箱也执行 bcrypt 比较（使用启动时生成的 DUMMY_HASH），并返回通用错误信息“Invalid email or password”，避免邮箱枚举。
密码策略：最小 12 字符，最大 72 字节（bcrypt 会忽略超出部分），建议对照泄露密码列表检查，不强制任意复杂度规则，引用 NIST 800-63B 建议以长度优先。

密钥管理

禁止在源码中硬编码密钥，应使用环境变量（如 dotenv 加载 .env）。
生产环境使用密钥管理器：AWS Secrets Manager / Parameter Store、GCP Secret Manager、自托管 HashiCorp Vault。
密钥轮换步骤：生成新值、部署同时接受新旧值的代码、更新所有消费方、验证旧值不再使用、撤销旧值；不要在无过渡期的情况下原地轮换。

加密模式

传输中：生产环境将 HTTP 重定向到 HTTPS（301），并设置 HSTS 头（max-age=31536000; includeSubDomains）。
静态：示例使用 aes-256-gcm，随机 16 字节 IV，返回密文、IV 与认证标签；解密时设置认证标签。适用于 PII 与敏感数据，加密密钥应存放于密钥管理器而非代码中。

CORS 配置

避免 cors() 默认允许所有来源，也避免通配符与 credentials 同时使用（浏览器会拒绝）。
正确做法：维护显式允许来源列表（生产域名，开发环境可加 localhost），使用回调校验来源，设置 credentials、允许的方法与请求头，并缓存预检请求 24 小时。

限流

使用 express-rate-limit 与 rate-limit-redis。
全局限流：15 分钟 100 次请求，启用标准 RateLimit-* 头。
认证端点严格限流：15 分钟 5 次登录尝试。
开发者 API 按 API Key 限流：每分钟 60 次，keyGenerator 优先使用 apiClient.id，否则回退到 IP。

安全响应头

使用 helmet 一次性设置多个安全头，包括 X-Content-Type-Options: nosniff、X-Frame-Options: SAMEORIGIN、Strict-Transport-Security、Content-Security-Policy: default-src 'self'。
可按应用自定义 CSP 指令（defaultSrc、scriptSrc、styleSrc、imgSrc、connectSrc）。

输入校验

避免直接信任用户输入拼接 SQL（注入风险）。
使用 zod 定义 schema（如 email 最大 255、name 去空格 1-100、age 可选整数 13-150），safeParse 校验失败返回 400 与错误详情，并使用参数化查询或 ORM 写入。

常见反模式对照资料以表格形式列出应避免的做法与替代方案，包括：JWT 存 localStorage 改为 httpOnly Cookie（刷新）与内存（访问）；密码用 MD5/SHA 改为 bcrypt 或 argon2；硬编码密钥改为环境变量加密钥管理器；cors({ origin: '*' }) 改为显式来源列表；“Invalid password”改为“Invalid email or password”；认证端点无限流改为严格限流；自研加密改为成熟库（jose、bcrypt）；信任用户输入改为 zod/joi 校验与参数化查询；长期使用同一 API Key 改为定期轮换并支持多个活跃密钥；无 HTTPS 重定向改为强制 HTTPS 加 HSTS；多服务使用对称 JWT 改为 RS256/ES256 非对称；无输入长度限制改为所有字符串输入设置最大长度。

适用场景与限制本模式适用于需要在 Web 服务中实现认证、授权、加密、密钥管理、CORS、限流与输入校验的开发者。资料以 JavaScript/TypeScript 生态（Express、jsonwebtoken、bcrypt、zod、helmet、express-rate-limit 等）示例为主，其他语言或框架需自行适配。资料未提供具体产品的收费、价格、平台支持或效果数据，这些信息暂未提供。

技能介绍