PBKDF2（Password-Based Key Derivation Function 2）是目前最常用的基于密码的密钥派生函数之一，无论是用户密码哈希存储，还是从口令派生加密密钥，都离不开它。在调用 PBKDF2 时，迭代次数是一个关键安全参数：OWASP 等安全机构建议至少使用 60 万次以上的迭代（针对 PBKDF2-HMAC-SHA256）。然而在 TypeScript 项目中，这个参数通常只是一个普通的 number，任何调用方都可以随手传入 1，编译器不会报任何错误。本文将展示如何通过类型系统把迭代次数的安全下限固化下来，让错误在编译期就被发现。
一、为什么迭代次数不能只是普通的 number 类型
先看一段典型的隐患代码：
// 危险：任何数字都能传进来
async function deriveKey(password: string, salt: Uint8Array, iterations: number) {
const keyMaterial = await crypto.subtle.importKey(
"raw", new TextEncoder().encode(password), "PBKDF2", false, ["deriveKey"]
);
return crypto.subtle.deriveKey(
{ name: "PBKDF2", salt, iterations, hash: "SHA-256" },
keyMaterial,
{ name: "AES-GCM", length: 256 },
false,
["encrypt", "decrypt"]
);
}
// 编译通过，但只有 1 次迭代，毫无抗暴力破解能力
deriveKey("password123", salt, 1);
这段代码在类型层面完全合法，却埋下了严重的安全漏洞。迭代次数为 1 时，攻击者每秒可以尝试数百万甚至上亿个密码组合，而现代推荐值（如 60 万次）能让单次尝试的耗时增加到几十甚至上百毫秒，攻击成本呈线性放大。问题在于 number 类型承载不了「这个值必须大于某个下限」的约束信息。
更隐蔽的风险是，团队成员可能在单元测试中为了加速写下 iterations: 10，然后这段代码被复制到生产路径中。类型系统如果足够聪明，这类问题在代码评审之前就能被编译器揪出来。这正是 TypeScript 的强项：把业务约束编码进类型，让非法状态无法表示。
二、用 Branded Type 构造带约束的迭代次数类型
TypeScript 的结构化类型系统认为两个结构相同的类型是兼容的，但我们可以通过「品牌标记」（branded type）打破这一规则：给基础类型附加一个唯一的不可达属性，让普通数字无法直接赋值给品牌类型。实现方式如下：
// 品牌标记符号，外部模块无法伪造
declare const IterationsBrand: unique symbol;
/**
* 带安全约束的迭代次数类型
* 只能通过 safeIterations 工厂函数构造
*/
export type SafeIterations = number & {
readonly [IterationsBrand]: "PBKDF2-safe-iterations";
};
/** 安全下限：OWASP 对 PBKDF2-HMAC-SHA256 的建议值 */
export const MIN_ITERATIONS = 600_000 as const;
/** 推荐档位：低、标准、高 */
export const ITERATION_PRESETS = {
standard: 600_000,
high: 1_000_000,
paranoid: 1_500_000,
} as const;
/**
* 工厂函数：唯一合法的构造入口
* 同时承担编译期文档与运行时校验职责
*/
export function safeIterations(value: number): SafeIterations {
if (!Number.isInteger(value)) {
throw new TypeError(`迭代次数必须是整数，收到: ${value}`);
}
if (value < MIN_ITERATIONS) {
throw new RangeError(
`迭代次数 ${value} 低于安全下限 ${MIN_ITERATIONS}，拒绝执行`
);
}
return value as SafeIterations;
}
这个设计的精妙之处在于：模块外部无法凭空构造 SafeIterations，因为 declare const 声明的 symbol 不会真正发出运行时代码，只能在本模块内通过断言产生值。任何想获得该类型实例的代码都必须经过 safeIterations 函数，而这个函数会在运行时强制校验下限。类型系统和运行时校验形成了双保险。
使用时的效果非常直观。密钥派生函数的签名改为接收品牌类型后，直接传数字会得到编译错误：
async function deriveKey(
password: string,
salt: Uint8Array,
iterations: SafeIterations // 只接受品牌类型
) {
// ...内部实现同前
}
deriveKey("pw", salt, 1000);
// 编译错误：number 不能赋给 SafeIterations
deriveKey("pw", salt, safeIterations(1000));
// 编译通过，但运行时抛出 RangeError
deriveKey("pw", salt, safeIterations(ITERATION_PRESETS.standard));
// 编译与运行时都安全
注意 ITERATION_PRESETS 的设计：把推荐档位收敛为少数几个具名常量，比让每个开发者自己填数字更能保证一致性。团队升级安全策略时，只需修改这一处即可全局生效。
三、类型守卫与 Web Crypto API 的整合细节
品牌类型与 Web Crypto API 交互时，还有几个值得注意的细节。首先是类型守卫的编写：在解析来自配置文件或数据库的持久化参数时，需要先用类型守卫验证再收窄类型：
export function isSafeIterations(value: unknown): value is SafeIterations {
return (
typeof value === "number" &&
Number.isInteger(value) &&
value >= MIN_ITERATIONS
);
}
// 从配置中解析，失败时回退到默认档位
function resolveIterations(raw: unknown): SafeIterations {
return isSafeIterations(raw) ? raw : safeIterations(ITERATION_PRESETS.standard);
}
其次要理解 Web Crypto API 本身并不认识品牌类型，传入 deriveKey 的算法对象仍然期望普通 number。由于 SafeIterations 是 number 的交叉类型，它天然可以赋给 number，无需任何转换，这正是交叉类型方案优于独立接口方案的地方。
最后还有两点实践建议：第一，把哈希算法与迭代次数放在一起管理，因为安全下限是针对特定哈希函数的——PBKDF2-HMAC-SHA1 的建议迭代次数就远高于 SHA256 版本，可以为不同哈希算法定义不同的品牌类型（如 Sha256Iterations 与 Sha512Iterations）；第二，在算法参数中同时固化盐的最小长度（建议 16 字节以上），用同样的品牌技巧封装 Salt 类型，让整个密钥派生接口从参数层面就无法被误用。密码学代码的特殊性在于，一旦出错往往没有明显症状，直到被攻击才暴露，因此把约束前移到编译期是性价比极高的防御手段。
TypeScript PBKDF2 密钥派生修改时间：2026-08-31 21:58:37