AES Key Wrap（AES-KW）是RFC 3394定义的一种密钥包装算法，它的作用不是加密普通数据，而是用一个密钥去保护另一个密钥。在浏览器的Web Crypto API里，调用crypto.subtle.wrapKey时如果把算法指定为AES-KW，就需要提供一个初始值向量。这个IV非常特殊：长度固定为8个字节（64位），规范规定的默认值是0xA6A6A6A6A6A6A6A6，解包时会作为完整性校验的基准。如果在TypeScript里只是简单地把参数声明成BufferSource，那么传错长度、传错内容都得等到运行时才会报错。本文就来聊聊如何用类型系统把这个约束提前到编译期。
AES-KW的初始值向量到底特殊在哪
先看Web Crypto标准对AES-KW算法的字面量定义，摘录如下：
interface AesKwParams extends Algorithm {
iv: BufferSource;
}可以看到标准只给出了一个宽泛的BufferSource，也就是ArrayBuffer或者ArrayBufferView都行。这对TypeScript来说约束太弱了。AES-KW的IV必须是64位，也就是恰好8个字节，多一个少一个都会导致wrapKey抛出OperationError。更严格的是，RFC 3394规定解包时计算出的校验值必须等于初始的A6常量，如果不等，说明密钥错误或者密文被篡改，整个解包操作会直接失败。
很多内置类型定义库（比如DOM lib里的AesKwParams）也没有做更细的约束，原因很简单：TypeScript的类型系统无法直接表达“长度为8的BufferSource”这种约束，除非借助一些技巧。这正是我们需要自己动手定义类型的原因。
基础方案：字节数组元组类型
最直观的思路是用元组加0xA6的字面量类型，把默认IV定义成一个常量类型：
// 默认IV的类型：8个字节，每个字节都是0xA6
type DefaultAesKwIv = [0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6];
// 构造默认IV的工厂函数，返回值类型精确到字面量
function createDefaultIv(): Uint8Array & { __brand: DefaultAesKwIv } {
const bytes = new Uint8Array([0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6]);
return bytes as Uint8Array & { __brand: DefaultAesKwIv };
}这里用了品牌类型（branded type）的技巧。单纯声明一个元组类型没有意义，因为运行时根本没有元组这种结构，实际对象还是Uint8Array。品牌类型通过附加一个只存在于类型层面的属性，让我们能区分“任意长度任意内容的Uint8Array”和“经过校验的、长度为8的AES-KW IV”。任何没有带这个品牌的字节数组都无法赋值给IV参数，编译器会直接拒绝。
这种方案的好处是零运行时开销，类型信息在编译后完全消失。缺点是表达不了“长度为8但内容可以不是A6”的情况——虽然实践中几乎所有场景都用默认值，但规范也允许双方协商使用其他IV，这一点需要考虑。
进阶方案：类型守卫加通用品牌
为了兼容自定义IV的场景，可以把品牌定义得宽一些，只约束长度，再配合一个运行时类型守卫函数：
// 品牌类型：只标记“这是通过校验的AES-KW IV”
declare const AesKwIvBrand: unique symbol;
export type AesKwIv = Uint8Array & { readonly [AesKwIvBrand]: true };
// 类型守卫：运行时校验长度，编译期收窄类型
export function isAesKwIv(source: BufferSource): source is AesKwIv {
const view = source instanceof ArrayBuffer ? new Uint8Array(source) : new Uint8Array(
source.buffer, source.byteOffset, source.byteLength
);
return view.byteLength === 8;
}
// 包装函数：强制调用方先通过校验
export function toAesKwIv(source: BufferSource): AesKwIv {
if (!isAesKwIv(source)) {
throw new RangeError('AES-KW的初始值向量长度必须为8字节（64位）');
}
return source as AesKwIv;
}类型守卫isAesKwIv同时处理了ArrayBuffer和视图两种情况，因为BufferSource是它们的联合类型，而且视图还可能带有byteOffset偏移，直接判断source.byteLength在ArrayBuffer上会拿错含义，用统一的Uint8Array视图包装一遍最稳妥。
这个方案的思路是“不信任边界处的输入，信任内部传递的数据”。所有来自外部（网络、用户输入、配置文件）的字节序列，在进入加密流程前都必须先过一遍toAesKwIv，之后在函数签名之间传递的都是AesKwIv类型，编译器保证它一定经过了长度校验，不需要在每个使用点重复判断。
在Web Crypto接口中的实际应用
最后把这套类型接到实际的密钥包装代码里，写一个带完整类型的封装：
interface StrictAesKwParams extends Algorithm {
iv: AesKwIv;
}
async function wrapAesKey(
key: CryptoKey,
wrappingKey: CryptoKey
): Promise<ArrayBuffer> {
const params: StrictAesKwParams = {
name: 'AES-KW',
iv: toAesKwIv(new Uint8Array([0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6])),
};
return crypto.subtle.wrapKey('raw', key, wrappingKey, params);
}注意这里的StrictAesKwParams把我们自定义的AesKwIv赋给了iv字段。由于AesKwIv本身就是Uint8Array的子类型，它天然兼容标准AesKwParams要求的BufferSource，可以直接传给crypto.subtle的各个方法，不需要任何断言转换。这就是品牌类型的妙处：对外收窄，对内兼容。
还有两个容易踩的坑值得提醒。第一，解包时传入的IV必须与包装时完全一致，包括内容，否则A6校验失败后unwrapKey会抛异常，所以IV最好和密文一起存储或传输。第二，如果你的代码要同时支持Node.js，注意node:crypto里的createCipheriv对AES-KW的IV处理略有不同，早期版本甚至不需要显式传入IV，跨平台时记得做适配层，而不是让类型定义掩盖运行时的差异。
总结一下，用字面量类型、品牌类型和类型守卫的组合，可以把AES-KW初始值向量“64位固定长度”这一约束从运行时文档说明提升为编译期硬性检查。这种模式不仅适用于IV，任何有严格格式要求的二进制结构（如盐值、标签、指纹）都可以套用，是TypeScript高级类型在安全编程里非常实用的一个落地场景。
TypeScriptAES-KW初始值向量修改时间：2026-09-06 10:56:39