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:

Tier	When to Apply	Key Focus Areas
Always	All Node.js/TS code	Strict TypeScript, input validation, no hardcoded secrets, safe error handling
API/HTTP	Web endpoints, middleware	Headers (helmet), rate limiting, CORS, body limits, Content-Type validation
Auth	Authentication features	Password hashing (argon2), JWT validation, secure cookies, RBAC
Data	External data processing	SQL injection, XSS sanitization, prototype pollution, schema validation
Runtime	Dynamic code, processes	No eval, safe child_process, path traversal prevention

根据代码场景应用相应的指南：

层级	适用场景	核心关注领域
始终遵循	所有Node.js/TS代码	严格TypeScript配置、输入验证、禁止硬编码密钥、安全错误处理
API/HTTP	Web端点、中间件	安全头（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:

Task	Load 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
```