secure-node-typescript

安全的 Node.js TypeScript

概述

编写默认安全的 Node.js 和 TypeScript 应用，以抵御常见的服务器端威胁。本技能提供按领域组织的安全指南，并针对最关键的控制措施提供内联模式。

所有指南均映射到 OWASP Top 10:2025 类别，以便进行合规性跟踪和审计。完整的 OWASP 映射请参阅 references/security-index.md。

安全等级

根据代码上下文应用相应指南：

等级	适用场景	重点领域
始终	所有 Node.js/TS 代码	严格 TypeScript、输入验证、不硬编码密钥、安全错误处理
API/HTTP	Web 端点、中间件	标头（helmet）、速率限制、CORS、请求体大小限制、Content-Type 验证
身份验证	身份验证功能	密码哈希（argon2）、JWT 验证、安全 Cookie、RBAC
数据	外部数据处理	SQL 注入、XSS 清理、原型污染、架构验证
运行时	动态代码、进程	不使用 eval、安全使用 child_process、防止路径遍历

快速模式

最关键的 10 项安全控制。默认应用这些控制。

1. 启用严格 TypeScript

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true
  }
}

2. 使用 Zod 验证所有输入

// DO: Schema validation at entry points
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  age: z.number().int().min(0).max(150),
})

// In route handler
const result = UserSchema.safeParse(req.body)
if (!result.success) {
  return res.status(400).json({ error: 'Invalid input' })
}
const user = result.data // Type-safe validated data

3. 使用参数化查询

// DON'T: String concatenation (SQL injection)
const query = `SELECT * FROM users WHERE id = ${userId}`

// DO: Parameterized queries
const result = await db.query('SELECT * FROM users WHERE id = $1', [userId])

4. 使用 Argon2 对密码进行哈希处理

import argon2 from 'argon2'

// Hash password
const hash = await argon2.hash(password, { type: argon2.argon2id })

// Verify password
const valid = await argon2.verify(hash, password)

5. 使用 Helmet 设置安全标头

import helmet from 'helmet'
import express from 'express'

const app = express()
app.use(helmet()) // Sets HSTS, CSP, X-Frame-Options, etc.
app.disable('x-powered-by')

6. 限制请求体大小

// DO: Enforce strict body limits
app.use(express.json({ limit: '1kb' })) // Adjust based on expected payload

// DON'T: Unlimited body parsing (DoS risk)
app.use(express.json())

7. 清理文件路径

import path from 'node:path'

// DO: Resolve and validate paths
const ALLOWED_DIR = '/app/uploads'
const safePath = path.resolve(ALLOWED_DIR, userInput)

if (!safePath.startsWith(ALLOWED_DIR)) {
  throw new Error('Path traversal attempt blocked')
}

8. 切勿暴露堆栈跟踪

// DO: Generic error response to clients
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  console.error(err) // Log full error internally
  res.status(500).json({ error: 'Internal server error' }) // Generic to client
})

// DON'T: Expose error details
res.status(500).json({ error: err.message, stack: err.stack })

9. 使用环境变量存储密钥

// DO: Load secrets from environment
import 'dotenv/config'

const dbPassword = process.env.DB_PASSWORD
if (!dbPassword) throw new Error('DB_PASSWORD required')

// DON'T: Hardcoded secrets
const dbPassword = 'secret123' // Never do this

10. 使用 node: 协议导入

// DO: Explicit Node.js built-in imports (prevents typosquatting)
import { createServer } from 'node:http'
import { readFile } from 'node:fs/promises'
import path from 'node:path'

// DON'T: Implicit imports
import { createServer } from 'http' // Could resolve to malicious package

参考文件加载指南

根据当前任务加载相应的参考文件：

任务	加载参考文件
项目设置、tsconfig、类型安全	references/typescript-safety.md
表单验证、用户输入、API 参数	references/input-validation.md
登录、会话、JWT、密码、RBAC	references/authentication.md
标头、CORS、速率限制、CSP	references/http-security.md
eval、child_process、原型污染	references/runtime-safety.md
文件上传、路径处理、正则表达式	references/filesystem-paths.md
npm audit、锁文件、供应链	references/dependencies.md
错误处理、日志记录、监控	references/error-logging.md
代码检查工具、CI/CD、威胁建模	references/operational.md
完整指南查找	references/security-index.md

审计脚本

验证项目 tsconfig.json 中与安全相关的设置：

python3 scripts/audit-tsconfig.py /path/to/project

该脚本会检查：

• 是否启用了 strict: true
• 是否启用了 noImplicitAny
• 是否启用了 strictNullChecks
• 是否启用了 noUncheckedIndexedAccess
• 其他与安全相关的编译器选项

资源

assets/ 中提供了模板配置：

• tsconfig.secure.json - 严格 TypeScript 配置模板
• eslint-security.config.js - ESLint 安全插件配置

复制并根据你的项目进行调整，即可开始使用。

Resources

• Security index: references/security-index.md
• TypeScript safety: references/typescript-safety.md
• Input validation: references/input-validation.md
• Authentication: references/authentication.md
• HTTP security: references/http-security.md
• Runtime safety: references/runtime-safety.md
• Filesystem paths: references/filesystem-paths.md
• Dependencies: references/dependencies.md
• Error logging: references/error-logging.md
• Operational: references/operational.md