如何构建默认情况下就具备安全性的 Node.js API

在我职业生涯中遇到的大多数安全问题其实都并不复杂。它们既不是国家层面的攻击，也不是那些巧妙的零日漏洞。这些问题都很普通：有的是某个限制条件被遗漏了，有的是超时设置被忘记了，还有的是某些字符串比较操作会偶尔泄露敏感信息。

恰恰就是这些看似平常的问题才会真正带来麻烦，因为大家都认为这些问题可以“以后再解决”，而“以后”往往永远不会到来。

我个人的最佳例子就是这样一个案例：我们内部使用的一个API通过简单的相等性判断来验证访问令牌的有效性，而且对请求数据的大小没有任何限制。这个系统运行了一年都没有出现问题，直到有人发现可以通过某些方法操纵这个验证过程，甚至发送体积巨大的数据让服务器不堪重负。

这两个漏洞其实都不复杂，如果一开始就能阻止我做出错误操作，这些问题根本就不会发生。

本教程会教你如何为自己开发的每一个HTTP API添加实用的安全防护措施，无论你使用的是哪种开发框架。你会用纯Node.js语言亲手编写这些代码，不需要依赖任何第三方库。这样你就能清楚地了解每一项安全措施的用途和作用原理。

学完本教程后，你将会拥有一个比我们大多数人职业生涯早期开发的版本更强大的服务器系统，它能够更好地应对公共互联网环境中的各种挑战。

本教程使用的是纯JavaScript语言，因此任何人都可以复制并运行这些代码。如果你使用TypeScript，之后也可以添加类型声明。你需要安装Node 22或更高版本的Node.js，具备对HTTP请求和响应的基本了解，并且需要一个终端来测试示例代码。

我们将涵盖的内容：

1. 先决条件

2. 你将构建什么

3. 如何开始使用基础服务器

4. 如何限制请求数据的大小

5. 如何为慢速请求设置超时机制

6. 如何安全地解析JSON数据并防止原型污染

7. 如何在每个响应中设置安全头信息

8. 如何在常数时间内比较敏感信息

9. 如何将输入验证视为一种强制性的检查机制，而不仅仅是建议

10. 如何让程序在出错时不会泄露敏感信息，并且会留下日志供你查看

11. 如何将所有这些安全措施整合到一起使用

12. 如何正确处理CORS请求

13. 本教程未涵盖的内容

14. 为什么默认设置比检查清单更有效

15. 关于开发框架的一些坦诚看法

16. 总结性检查清单

先决条件

• Node.js 22或更高版本

• 对HTTP请求与响应有基本了解

• 需要终端以及curl、Postman或其他类似的工具

这份指南并非旨在让你的API完全无法被攻击，而是帮助你避免那些常见的攻击方式，并设置更安全的默认配置。

你将构建什么

一个简单的Node.js API，它会限制请求体的大小、设置请求超时时间、确保JSON数据的安全解析、添加安全头部信息、进行安全的秘密值比对、执行数据验证以及处理错误。

如何开始使用这个简单服务器

这是我年轻时编写的服务器代码——虽然当时我更勇敢，但也犯了很多错误。这个服务器会读取接收到的JSON数据并将其原封不动地返回给客户端。不过，可以把它看作是构建真正API的基础。

import http from "node:http";

const server = http.createServer((req, res) => {
  let body = "";
  req.on("data", (chunk) => (body += chunk));
  req.on("end", () => {
    const data = JSON.parse(body || "{}");
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ youSent: data }));
  });
});

server.listen(3000, () => console.log("listening on http://localhost:3000"));

这个服务器确实可以正常工作。你可以使用curl发送请求，它也会做出响应。不过，它也存在很多安全隐患，具体原因如下：

• 它会将接收到的所有数据全部加载到内存中。如果发送的数据量达到几GB，那么服务器就会立即陷入服务中断的状态。

• 当输入的JSON数据格式不正确时，《JSON.parse》方法会抛出异常，这种未捕获的异常可能会导致整个进程崩溃。

• 这个服务器没有设置请求超时机制，因此如果客户端以极慢的速度发送数据，那么连接就会一直保持开放状态，从而导致资源浪费。

• 它没有添加任何安全头部信息，因此会暴露自己是一个Node.js服务器的事实。

• 它会直接将未经验证的JSON数据解析成对象，而不会进行任何检查，这就为后续可能出现的安全问题埋下了隐患。

你需要解决上述所有这些问题。这些修改虽然很简单，但关键在于要将它们变成你的日常习惯，而不是偶尔才做的事情。

如何限制请求体的大小

在接收来自陌生人的数据时，首先需要确定自己愿意接受多少数据量。如果你不设置任何限制，那么默认的限制就是“服务器能够使用的所有内存空间”，而总会有人找到这种方法来攻击你的系统。

这里其实有两个层面的控制措施。第一层是客户端发送的Content-Length头部信息，它用来说明请求体的大小。你可以根据这个信息提前判断是否接受该请求。但是，绝对不能仅依赖这一信息，因为客户端有可能提供虚假的数据，或者根本不发送这个头部信息。

更有效的防御措施是在数据流进入服务器时实时计算其字节数量，一旦超过预设的限制，就立即拒绝该请求。

const MAX_BODY_BYTES = 100 * 1024; // 对于大多数JSON API来说，100 KB已经足够了

function readBody(req, limit = MAX_body_bytes) {
  return new Promise((resolve, reject) => {
    // 如果客户端确实说明了请求体太大，就可以立即拒绝请求。
    const declared = Number(req.headers["content-length"]);
    if (Number.isFinite(declared) && declared > limit) {
      reject(httpError(413, "Payload too large"));
      return;
    }

    let size = 0;
    const chunks = [];

    req.on("data", (chunk) => {
      size += chunk.length;
      if (size > limit) {
        reject(httpError(413, "Payload too large"));
        req.destroy(); // 停止读取数据；不再处理这个请求。
        return;
      }
      chunks.push(chunk);
    });

    req.on("end", () => resolve(Buffer.concat(chunks)));
    req.on("error", reject);
  });
}

function httpError(statusCode, message) {
  return Object.assign(new Error(message), { statusCode });
}

这里有几点需要注意。你需要先累积这些Buffer片段，然后在最后再将它们合并起来，而不是直接将字符串连接起来。因为字符串连接会迫使系统提前进行解码操作，而这种操作可能会破坏那些位于片段边界处的多字节UTF-8字符。

一旦超过了规定的数据量限制，你就应该立即调用req.destroy()方法，这样就不会继续接收那些你已经决定拒绝处理的字节了。

需要根据具体的应用场景来设定合适的数据量限制。例如，用于创建用户的JSON API并不需要50MB的请求体；而文件上传接口的情况则不同，在那种情况下，数据应该直接被写入磁盘或对象存储系统中，而不是先保存在内存中。真正的错误在于没有设置限制，而不是设置了错误的限制值。

如何为耗时较长的请求设置超时机制

一旦确定了请求体的最大数据量限制，攻击者就会采取另一种策略：让请求的响应速度变得非常慢，而不是增加请求体本身的大小。这类攻击方法是以“slowloris”这种行动极其缓慢的灵长类动物命名的。

攻击者的具体做法是建立大量连接，然后以极慢的速度向这些连接发送数据，永远不完成发送操作，这样服务器就会一直保持这些连接处于活跃状态。如果这种情况反复发生，连接池中的所有连接都会被耗尽，但却不会有任何看起来具有恶意性的数据被发送出去。

Node.js内置了针对这种攻击的防护机制，默认设置已经相当严格了，但对于API来说，进一步优化这些设置仍然是有必要的。

const server = http.createServer(handler);

// 允许接收整个请求所需的总时间（包括请求头和请求体）。
server.requestTimeout = 30_000; // 30秒

// 允许接收请求头所需的时间。slowloris攻击就是利用这个设置来拖延时间的。
server.headersTimeout = 10_000; // 10秒

// 空闲连接超时时间：会关闭那些长时间没有活动的连接。
server.setTimeout(60_000);

上述这三行代码用于处理网络层的相关配置。但还有一种导致请求响应速度变慢的原因，那就是你的应用程序自身处理请求的逻辑存在问题。比如数据库查询耗时过长、与第三方的调用没有得到响应，或者正则表达式的匹配过程过于复杂等。你需要为单个请求设置一个最长处理时间限制，并且要在这个时间限制被达到时能够立即取消该请求的处理。

在Node.js中，用于实现请求取消功能的工具是AbortController。下面是一个简单的封装示例，它可以为每个请求处理函数设定一个截止时间，并允许该函数向任何支持取消操作的函数传递取消信号，比如fetch函数。

function withTimeout(handler, ms = 15_000) {
  return async (req, res) => {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), ms);
    try {
      await handler(req, res, controller.signal);
    } finally {
      clearTimeouttimer);
    }
  };
}

现在，一个请求处理函数可以通过await fetch(url, { signal })这种方式来发送请求，如果请求的处理超出了设定的截止时间，那么请求就会被立即终止，而不会一直占用系统资源。

在这里需要遵守的规则是：每当你在处理流程之外与某些内容进行交互时，都必须为这些操作设定明确的截止时间。网络故障往往以最令人沮丧的方式发生——它们会陷入“挂起”状态，而不是出现错误。通过设置超时机制，就可以将这种“挂起”状态转化为可以妥善处理的错误。

如何安全地解析JSON数据并防止原型污染

很多人会忽略这个知识点，因为它听起来很抽象；但后来在某些安全漏洞报告中，就会发现他们的代码中存在这个问题。

首先来看比较简单的一部分。`JSON.parse`方法会在遇到格式错误的输入时抛出`SyntaxError`异常。在那些设计不严谨的服务器程序中，这种异常往往不会被捕获，从而导致整个进程崩溃。因此，我们可以通过一些处理手段，在解析失败时返回一个明确的400错误响应。

function parseJson(buffer) {
  if (buffer.length === 0) return {};
  let text = buffer.toString("utf8");
  try {
    return JSON.parse(text, reviver);
  } catch {
    throw httpError(400, "无效的JSON数据");
  }
}

现在来看比较有趣的部分：那就是`reviver`这个参数。所谓“原型污染”，其实就是攻击者利用请求数据修改了`Object.prototype`对象——几乎所有程序中的对象都是从这个对象继承属性的。如果攻击者能够在这个对象上设置某些属性，那么他们实际上就可以同时影响程序中所有的对象。

当你亲眼看到这种机制时，就会明白它的危害性了。下面是一个递归合并函数，这类函数通常用于将更新内容应用到现有的数据结构上：

function merge(target, source) {
  for (const key in source) {
    if (source[key] && typeof source[key] === "object") {
      if (!target[key]) target[key] = {};
      merge(target[key], source[key]);
    } else {
      target[key] = source[key];
    }
  }
}

这个函数看起来似乎没什么危害，但如果你给它传入一个被攻击者控制的输入数据，情况就会变得糟糕：

const evil = JSON.parse('{"__proto__": {"isAdmin": true}}');
const account = {};
merge(account, evil);

console.log(account.isAdmin);   // undefined，account本身没有问题
console.log(({}).ADMIN);      // true  -- 现在所有的对象都被认为是“管理员”

第二行代码才是真正的隐患。你明明并没有修改`({})`这个对象，但通过这种机制，你还是污染了所有对象的共享原型，导致一个全新的空对象也被认定为“管理员”。如果后续你的代码中出现了`if (user.isAdmin)`这样的判断语句，而该对象的`isAdmin`属性本来并没有被设置，那么结果就是——所有人都被视为管理员了。`__proto__`这个键的作用，其实就是让合并操作触及到了所有对象共用的原型对象。

防范这种攻击的方法就是在数据被处理之前，就拒绝那些危险的键值对进入系统。在解析JSON数据时，最有效的办法就是使用`reviver`函数。`JSON.parse`方法在构建解析结果的过程中，会为每一个键调用这个函数；如果某个键对应的值应该被忽略，就可以让`reviver`返回`undefined`，这样这个键就会被从最终的结果中剔除。

const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"];

function reviver(key, value) {
  if (FORBIDDEN_keys.has(key)) return undefined;
  return value;
}

就是这样。通过阻止这三个关键键值的传递，上述那些攻击手段就变得无效了，因为数据载体根本不会将 `__proto__` 这个属性传递给解析器。

为了进一步增强安全性，你还可以使用 `Object.create(null)` 创建没有原型的对象，或者当键值由用户控制时使用 `Map`。如果你还想采取更进一步的防护措施，在程序开始运行时就使用 `Object.freeze(Object.prototype)`，这样就能有效地阻止所有攻击行为。

不过我并不建议单独依赖这种冻结机制，因为有些库可能不支持这种做法；但阻止这些关键键值的传递绝对不会给你带来任何损失，因此这应该成为默认的防护措施。

如何在每个响应中设置安全头部信息

浏览器会为你保护用户的安全，但前提是你必须明确告诉它们该这么做。这种保护机制是通过一组响应头部信息来实现的。对于返回 JSON 数据的 API 来说，这些头部信息的列表很短，而且默认设置也非常严格，这正是你所需要的。

function secureHeaders(res) {
  // 阻止浏览器自行猜测内容类型，这样就不会把 JSON 响应误认为是 HTML 或脚本文件。
  res.setHeader("X-Content-Type-Options", "nosniff");

  // 防范点击劫持：禁止在框架中显示此响应。
  res.setHeader("X-Frame-Options", "DENY");
  res.setHeader("Content-Security-Policy", "default-src 'none'; frame-ancestors 'none'");

  // 避免在导航过程中泄露完整的 URL（其中可能包含 ID 或令牌等信息）。
  res.setHeader("Referrer-Policy", "no-referrer");

  // 仅在 HTTPS 协议下生效：强制使用 HTTPS 协议，包括子域名。
  res.setHeader("Strict-Transport-Security", "max-age=63072000; includeSubDomains");

  // 阻止他人通过这些头部信息了解你的服务内容，从而避免被用于侦察活动。
  res.removeHeader("X-Powered-By");
}

简单来说，如果盲目地添加各种安全头部信息，反而可能会导致内容安全策略失效。

X-Content-Type-Options: nosniff 这一设置可以防止浏览器自行判断响应的内容类型，从而避免将 JSON 响应误认为是可执行文件。`X-Frame-Options` 以及 `frame-ancestors` 这些设置都可以阻止响应被嵌入到框架中，而点击劫持正是利用了这种机制。对于纯粹提供 JSON 数据的 API 来说，`default-src ‘none’` 是一个非常合适的安全策略，因为 API 并不需要加载脚本、样式表或图片。

Referrer-Policy: no-referrer 这一设置可以防止包含敏感信息的 URL 被发送到其他网站。`Strict-Transport-Security` 仅在使用 HTTPS 协议时才有效，但它能通过阻止浏览器使用普通 HTTP 协议来防止攻击行为。

X-Powered-By 这一头部信息的删除虽然看似微不足道，但实际上它可以防止攻击者轻易获取有关你服务的信息，从而避免被他们用来发起攻击。

之所以要将这一操作封装成函数，并在每次收到响应时都执行它，是因为人们往往会忘记“每次接收响应时都需要进行这样的检查”。因此，最好在请求开始时就执行这一次检查，这样就不会被其他事情分心了。

如何在常数时间内比较秘密值

下面这个代码看起来完全正常，但实际上却存在严重的问题：

if (providedApiKey === expectedApiKey) {
  // 授予访问权限
}

问题在于，对于字符串来说，===操作的执行速度本来就很快。它会逐个字符地进行比较，一旦发现不匹配的地方就会立即返回false。因此，即使猜测的第一个字符是正确的，这种判断方式也会比那些一开始就判断错误的做法花费更长的时间。

虽然这种时间差异非常微小，但在大量的请求中，这种差异还是可以被测量的。攻击者可以利用这一点，一次只恢复一个字符的内容。这是一种真实的攻击手段，它有一个专门的名称——时间差攻击，而Node.js中也已经提供了相应的修复措施。

你需要的是一种比较方法，其执行时间不应取决于第一次出现差异的位置。Node.js提供了cryptotimingSafeEqual函数，正好可以满足这个需求。不过这个函数也有一个缺点：如果两个输入缓冲区的长度不同，它就会抛出错误，而缓冲区的长度本身也有可能被攻击者利用来获取秘密信息。

要同时解决这两个问题，最简单的方法就是先对两个输入进行哈希处理，将其转换为固定长度的字符串，然后再比较这些哈希值。

import { timingSafeEqual, createHash } from "node:crypto";

function safeCompare(a, b) {
  // 哈希处理可以统一长度，并且能够隐藏真实秘密的长度，从而防止攻击者通过观察哈希值来获取秘密信息。
  const ha = createHash("sha256").update(String(a)).digest();
  const hb = createHash("sha256").update(String(b)).digest();
  return timingSafeEqual(ha, hb);
}

在任何需要将陌生人提供的值与你自己持有的秘密值进行比较的地方，都可以使用这个函数。例如API密钥、Webhook签名、密码重置令牌、会话标识符等等。一个简单的原则是：如果判断错误会导致他人获得访问权限，那就千万不要使用===操作。

还需要注意一点，不要误用这个函数。对于用户密码来说，不应该直接使用这个函数来进行比较。因为密码通常会经过专门的哈希算法处理，即使数据库被泄露，攻击者也需要花费大量的时间才能破解这些哈希值。

Node.js在node:crypto模块中提供了scrypt库来处理密码加密问题，而bcrypt和argon2也是常用的密码加密库。safeCompare函数适用于比较那些高熵值的秘密信息，比如令牌和密钥，而不适合用来比较用户自己选择的密码。

res.setHeader("Access-Control-Allow-Origin", "*"); // 在正式发布代码之前，请务必仔细考虑这个设置

const ALLOWED_ORIGINS = new Set(["https://app.example.com"]); 

function applyCors(req, res) { 
  const origin = req.headers.origin; 
  if (origin && ALLOWED_ORIGINS.has(origin)) { 
    res.setHeader("Access-Control-Allow-Origin", origin); 
    res.setHeader("Vary", "Origin"); // 这样缓存机制就不会混淆不同的来源地址 
    res.setHeader("Access-Control-Allow-Credentials", "true"); 
  } 
}