Back to Details

secure-node-typescript

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Secure Node.js TypeScript

安全的Node.js TypeScript开发

Overview

概述

Write secure-by-default Node.js and TypeScript applications that neutralize common server-side threats. This skill provides security guidelines organized by domain, with inline patterns for the most critical controls.
All guidelines are mapped to OWASP Top 10:2025 categories for compliance tracking and audit purposes. See 
references/security-index.md
for the complete OWASP mapping.
开发默认安全的Node.js和TypeScript应用，抵御常见的服务器端威胁。本技能按领域整理了安全指南，并针对最关键的控制措施提供了嵌入式代码示例。
所有指南均映射到OWASP Top 10:2025分类，以便于合规跟踪和审计。完整的OWASP映射请参阅
references/security-index.md
。

Security Tiers

安全层级

Apply guidelines based on the code context:
TierWhen to ApplyKey Focus Areas
AlwaysAll Node.js/TS codeStrict TypeScript, input validation, no hardcoded secrets, safe error handling
API/HTTPWeb endpoints, middlewareHeaders (helmet), rate limiting, CORS, body limits, Content-Type validation
AuthAuthentication featuresPassword hashing (argon2), JWT validation, secure cookies, RBAC
DataExternal data processingSQL injection, XSS sanitization, prototype pollution, schema validation
RuntimeDynamic code, processesNo eval, safe child_process, path traversal prevention
根据代码场景应用相应的指南：
层级适用场景核心关注领域
始终遵循所有Node.js/TS代码严格TypeScript配置、输入验证、禁止硬编码密钥、安全错误处理
API/HTTPWeb端点、中间件安全头（Helmet）、请求频率限制、CORS、请求体大小限制、Content-Type验证
身份验证身份验证功能密码哈希（argon2）、JWT验证、安全Cookie、基于角色的访问控制（RBAC）
数据处理外部数据处理SQL注入防护、XSS攻击净化、原型污染防护、Schema验证
运行时动态代码、进程处理禁止使用eval、安全子进程、路径遍历防护

Quick Patterns

快速实践方案

The 10 most critical security controls. Apply these by default.
以下是10项最关键的安全控制措施，应默认应用。

1. Enable Strict TypeScript

1. 启用严格的TypeScript配置

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

2. Validate All Inputs with Zod

2. 使用Zod验证所有输入

typescript
// 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
typescript
// 正确做法：在入口点进行Schema验证
import { z } from 'zod'

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

// 在路由处理器中
const result = UserSchema.safeParse(req.body)
if (!result.success) {
  return res.status(400).json({ error: 'Invalid input' })
}
const user = result.data // 类型安全的已验证数据

3. Use Parameterized Queries

3. 使用参数化查询

typescript
// 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])
typescript
// 错误做法：字符串拼接（存在SQL注入风险）
const query = `SELECT * FROM users WHERE id = ${userId}`

// 正确做法：参数化查询
const result = await db.query('SELECT * FROM users WHERE id = $1', [userId])

4. Hash Passwords with Argon2

4. 使用Argon2哈希密码

typescript
import argon2 from 'argon2'

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

// Verify password
const valid = await argon2.verify(hash, password)
typescript
import argon2 from 'argon2'

// 哈希密码
const hash = await argon2.hash(password, { type: argon2.argon2id })

// 验证密码
const valid = await argon2.verify(hash, password)

5. Set Security Headers with Helmet

5. 使用Helmet设置安全头

typescript
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')
typescript
import helmet from 'helmet'
import express from 'express'

const app = express()
app.use(helmet()) // 设置HSTS、CSP、X-Frame-Options等安全头
app.disable('x-powered-by')

6. Limit Request Body Size

6. 限制请求体大小

typescript
// 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())
typescript
// 正确做法：严格限制请求体大小
app.use(express.json({ limit: '1kb' })) // 根据预期负载调整

// 错误做法：无限制解析请求体（存在DoS风险）
app.use(express.json())

7. Sanitize File Paths

7. 净化文件路径

typescript
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')
}
typescript
import path from 'node:path'

// 正确做法：解析并验证路径
const ALLOWED_DIR = '/app/uploads'
const safePath = path.resolve(ALLOWED_DIR, userInput)

if (!safePath.startsWith(ALLOWED_DIR)) {
  throw new Error('路径遍历尝试已被阻止')
}

8. Never Expose Stack Traces

8. 切勿暴露堆栈跟踪

typescript
// 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 })
typescript
// 正确做法：向客户端返回通用错误响应
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  console.error(err) // 在内部记录完整错误
  res.status(500).json({ error: '服务器内部错误' }) // 向客户端返回通用信息
})

// 错误做法：暴露错误详情
res.status(500).json({ error: err.message, stack: err.stack })

9. Use Environment Variables for Secrets

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

typescript
// 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
typescript
// 正确做法：从环境变量加载密钥
import 'dotenv/config'

const dbPassword = process.env.DB_PASSWORD
if (!dbPassword) throw new Error('需要配置DB_PASSWORD')

// 错误做法：硬编码密钥
const dbPassword = 'secret123' // 绝对不要这样做

10. Import with node: Protocol

10. 使用node:协议导入模块

typescript
// 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
typescript
// 正确做法：显式导入Node.js内置模块（防止包名劫持）
import { createServer } from 'node:http'
import { readFile } from 'node:fs/promises'
import path from 'node:path'

// 错误做法：隐式导入
import { createServer } from 'http' // 可能解析为恶意包

Reference Loading Guide

参考文档加载指南

Load reference files based on the task at hand:
TaskLoad Reference
Project setup, tsconfig, type safety
references/typescript-safety.md
Form validation, user input, API params
references/input-validation.md
Login, sessions, JWT, passwords, RBAC
references/authentication.md
Headers, CORS, rate limiting, CSP
references/http-security.md
eval, child_process, prototype pollution
references/runtime-safety.md
File uploads, path handling, regex
references/filesystem-paths.md
npm audit, lockfiles, supply chain
references/dependencies.md
Error handling, logging, monitoring
references/error-logging.md
Linters, CI/CD, threat modeling
references/operational.md
Full guideline lookup
references/security-index.md
根据任务需求加载对应的参考文件：
任务内容加载的参考文档
项目搭建、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审计、锁定文件、供应链安全
references/dependencies.md
错误处理、日志、监控
references/error-logging.md
代码检查工具、CI/CD、威胁建模
references/operational.md
完整指南查询
references/security-index.md

Audit Script

审计脚本

Validate a project's 
tsconfig.json
for security-relevant settings:
bash
python3 scripts/audit-tsconfig.py /path/to/project
The script checks for:
  • strict: true
    enabled
  • noImplicitAny
    enabled
  • strictNullChecks
    enabled
  • noUncheckedIndexedAccess
    enabled
  • Other security-relevant compiler options
验证项目的
tsconfig.json
中与安全相关的配置：
bash
python3 scripts/audit-tsconfig.py /path/to/project
该脚本会检查以下内容：
  • 是否启用
    strict: true
  • 是否启用
    noImplicitAny
  • 是否启用
    strictNullChecks
  • 是否启用
    noUncheckedIndexedAccess
  • 其他与安全相关的编译器选项

Assets

资源文件

Template configurations available in 
assets/
:
  • tsconfig.secure.json
    - Strict TypeScript configuration template
  • eslint-security.config.js
    - ESLint security plugin configuration
Copy and adapt these to your project as a starting point.
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
  • 安全索引：
    references/security-index.md
  • TypeScript安全：
    references/typescript-safety.md
  • 输入验证：
    references/input-validation.md
  • 身份验证：
    references/authentication.md
  • HTTP安全：
    references/http-security.md
  • 运行时安全：
    references/runtime-safety.md
  • 文件系统与路径：
    references/filesystem-paths.md
  • 依赖管理：
    references/dependencies.md
  • 错误与日志：
    references/error-logging.md
  • 运维安全：
    references/operational.md