sm-crypto-wasm 0.3.0 → 0.7.0

package/dist/sm2/index.d.ts

@@ -120,12 +120,81 @@ export declare function createSignaturePointPool(n: number): Promise<SignaturePo
  * @returns 64 字节签名（r || s）的 hex。
  */
 export declare function sign(privateKey: string | Uint8Array, message: string | Uint8Array, opts?: SignOptions): string;
+/**
+ * SM2 签名（自定义用户标识）。
+ *
+ * 与 `sign` 的区别仅在于 Z 值使用 `userID` 计算。X.509 签发需要它：
+ * OpenSSL 的 X.509 路径默认使用空标识，GM/T 证书使用 `1234567812345678`。
+ *
+ * 不支持 `pointPool`（签发场景不需要；需要时用 `sign` 的默认标识路径）。
+ *
+ * @param privateKey 32 字节私钥（hex / Uint8Array / PEM）。
+ * @param message 待签名消息。
+ * @param userID 用户标识（可为空数组）。
+ * @returns 64 字节签名 `r ‖ s` 的 hex。
+ */
+export declare function signWithID(privateKey: string | Uint8Array, message: string | Uint8Array, userID: Uint8Array): string;
 /**
  * SM2 验签。
  *
  * @returns true 有效。
  */
 export declare function verify(publicKey: string | Uint8Array, message: string | Uint8Array, signature: string | Uint8Array): boolean;
+/**
+ * SM2 验签（自定义用户标识）。
+ *
+ * 与 `verify` 的区别仅在于 Z 值使用 `userID` 计算。X.509 证书签名需要它：
+ * GM/T 证书使用默认标识 `1234567812345678`，而 OpenSSL 的 X.509 路径
+ * 默认使用空标识。
+ *
+ * @param publicKey 64/65 字节公钥。
+ * @param message 消息。
+ * @param signature 64 字节 `r ‖ s`。
+ * @param userID 用户标识（可为空数组）。
+ * @returns true 有效。
+ */
+export declare function verifyWithID(publicKey: string | Uint8Array, message: string | Uint8Array, signature: string | Uint8Array, userID: Uint8Array): boolean;
+/** 多槽公钥缓存的配置。 */
+export interface PreparedKeyCacheOptions {
+    /** 槽位上限，1..8，默认 8。 */
+    capacity?: number;
+}
+/**
+ * 配置多槽公钥缓存（默认 8 槽，满了按 LRU 淘汰）。
+ *
+ * 缩小容量不会立即清除高槽位，只是之后的查找与 `getPreparedPublicKeys` 不再考虑它们；
+ * 需要释放时调用 `clearPreparedPublicKeys()`。wasm 未加载时只记录，首次
+ * `preparePublicKey` 会应用。
+ */
+export declare function configurePreparedKeyCache(opts?: PreparedKeyCacheOptions): void;
+/**
+ * 为一对**固定公钥**预计算 comb 表（默认 8 槽，满了 LRU 淘汰）。
+ *
+ * 之后 `encrypt` / `kemEncrypt` / `hybridEncrypt` 对该公钥会把 `k·P` 从 wNAF
+ * （256 次倍点）切到 comb（52 次倍点）：本机端到端约 486 → 260 µs。建表一次性
+ * 约 280 µs，**约 1.2 次加密回本**。
+ *
+ * **只有显式 prepare 才会建表**：`encrypt` 命中就走 comb，不命中直接回退 wNAF，
+ * 绝不隐式建表 —— 否则外部可控的公钥能反复触发建表，形成放大面。
+ *
+ * 公钥是公开信息，缓存它不引入新的密钥材料驻留；8 槽共占 wasm 永久区固定 24 KiB。
+ *
+ * @param publicKey 64/65 字节公钥（hex / Uint8Array / PEM）。
+ * @throws {InvalidPublicKeyError} 公钥不在 SM2 曲线上。
+ */
+export declare function preparePublicKey(publicKey: string | Uint8Array): Promise<void>;
+/** 清空所有公钥预计算槽，之后的 `encrypt` 全部回退到 wNAF。未加载 wasm 时也安全。 */
+export declare function clearPreparedPublicKeys(): void;
+/** @deprecated 用 `clearPreparedPublicKeys()`（保留单数别名）。 */
+export declare function clearPreparedPublicKey(): void;
+/**
+ * 当前槽位中的公钥（hex，按槽序）。
+ *
+ * wasm 未加载时返回空数组。
+ */
+export declare function getPreparedPublicKeys(): string[];
+/** 最后一次 `preparePublicKey` 的公钥（hex）；没有则为 `null`。 */
+export declare function getPreparedPublicKey(): string | null;
 /**
  * SM2 加密。
  *

package/dist/sm2/index.js

@@ -128,6 +128,14 @@ function derivePublicKeyRaw(d) {
  *   "派生公钥"这个操作的语义，以及 `bench` 里这一项的可测性。
  */
 const PUB_CACHE = new Map();
+/**
+ * 最后一次 `preparePublicKey` 的公钥（hex，x || y），没有则为 `null`。
+ *
+ * 只用于单数查询接口；多槽的真实状态在 wasm 侧（指纹 + LRU），正确性不依赖它。
+ */
+let PREPARED_PUB = null;
+/** 多槽公钥缓存的槽位上限（1..8，默认 8）。wasm 未加载时先记在这里。 */
+let preparedCapacity = 8;
 let cacheEnabled = true;
 let cacheCapacity = 32;
 /**
@@ -345,6 +353,52 @@ export function sign(privateKey, message, opts = {}) {
         exports.freeAll();
     }
 }
+/**
+ * SM2 签名（自定义用户标识）。
+ *
+ * 与 `sign` 的区别仅在于 Z 值使用 `userID` 计算。X.509 签发需要它：
+ * OpenSSL 的 X.509 路径默认使用空标识，GM/T 证书使用 `1234567812345678`。
+ *
+ * 不支持 `pointPool`（签发场景不需要；需要时用 `sign` 的默认标识路径）。
+ *
+ * @param privateKey 32 字节私钥（hex / Uint8Array / PEM）。
+ * @param message 待签名消息。
+ * @param userID 用户标识（可为空数组）。
+ * @returns 64 字节签名 `r ‖ s` 的 hex。
+ */
+export function signWithID(privateKey, message, userID) {
+    const d = toPrivateKeyBytes(privateKey);
+    const m = toBytes(message, 'message');
+    const id = userID instanceof Uint8Array ? userID : new Uint8Array(0);
+    const pub = derivePublicKeyBytes(d);
+    const { exports, memory } = getModule();
+    const dp = exports.alloc(32);
+    const pxp = exports.alloc(32);
+    const pyp = exports.alloc(32);
+    const idp = exports.alloc(id.length === 0 ? 1 : id.length);
+    const mp = exports.alloc(m.length === 0 ? 1 : m.length);
+    const kp = exports.alloc(32);
+    const op = exports.alloc(64);
+    try {
+        putBytes(d, dp);
+        putBytes(pub.subarray(0, 32), pxp);
+        putBytes(pub.subarray(32, 64), pyp);
+        if (id.length > 0)
+            putBytes(id, idp);
+        putBytes(m, mp);
+        for (let attempt = 0; attempt < 16; attempt++) {
+            putBytes(randomK(), kp);
+            const rc = exports.signWithIDOut(dp, pxp, pyp, idp, id.length, mp, m.length, kp, op);
+            if (rc === 0)
+                return fromBytes(readBytes(op, 64), 'hex');
+        }
+        throw new Error('sm2.signWithID: failed to produce a valid signature after retries');
+    }
+    finally {
+        new Uint8Array(memory.buffer, kp, 32).fill(0);
+        exports.freeAll();
+    }
+}
 /**
  * SM2 验签。
  *
@@ -375,6 +429,140 @@ export function verify(publicKey, message, signature) {
         exports.freeAll();
     }
 }
+/**
+ * SM2 验签（自定义用户标识）。
+ *
+ * 与 `verify` 的区别仅在于 Z 值使用 `userID` 计算。X.509 证书签名需要它：
+ * GM/T 证书使用默认标识 `1234567812345678`，而 OpenSSL 的 X.509 路径
+ * 默认使用空标识。
+ *
+ * @param publicKey 64/65 字节公钥。
+ * @param message 消息。
+ * @param signature 64 字节 `r ‖ s`。
+ * @param userID 用户标识（可为空数组）。
+ * @returns true 有效。
+ */
+export function verifyWithID(publicKey, message, signature, userID) {
+    const { x, y } = splitPub(publicKey);
+    if (!isOnCurve(x, y))
+        return false;
+    const m = toBytes(message, 'message');
+    const sig = toBytes(signature, 'signature');
+    if (sig.length !== 64)
+        throw new InvalidCiphertextError('sm2: signature must be 64 bytes');
+    const id = userID instanceof Uint8Array ? userID : new Uint8Array(0);
+    const { exports } = getModule();
+    const pxp = exports.alloc(32);
+    const pyp = exports.alloc(32);
+    const idp = exports.alloc(id.length === 0 ? 1 : id.length);
+    const mp = exports.alloc(m.length === 0 ? 1 : m.length);
+    const sigp = exports.alloc(64);
+    const zp = exports.alloc(32);
+    try {
+        putBytes(x, pxp);
+        putBytes(y, pyp);
+        if (id.length > 0)
+            putBytes(id, idp);
+        putBytes(m, mp);
+        putBytes(sig, sigp);
+        exports.computeZIdOut(pxp, pyp, idp, id.length, zp);
+        return exports.verifyWithZOut(pxp, pyp, zp, mp, m.length, sigp) === 1;
+    }
+    finally {
+        exports.freeAll();
+    }
+}
+/**
+ * 配置多槽公钥缓存（默认 8 槽，满了按 LRU 淘汰）。
+ *
+ * 缩小容量不会立即清除高槽位，只是之后的查找与 `getPreparedPublicKeys` 不再考虑它们；
+ * 需要释放时调用 `clearPreparedPublicKeys()`。wasm 未加载时只记录，首次
+ * `preparePublicKey` 会应用。
+ */
+export function configurePreparedKeyCache(opts = {}) {
+    const capacity = opts.capacity ?? 8;
+    if (!Number.isInteger(capacity) || capacity < 1 || capacity > 8) {
+        throw new RangeError(`sm2.configurePreparedKeyCache: capacity 必须是 1..8 的整数，收到 ${String(capacity)}`);
+    }
+    preparedCapacity = capacity;
+    const mod = globalThis.__sm2Wasm;
+    if (mod)
+        mod.exports.setCombCapacityOut(capacity);
+}
+/**
+ * 为一对**固定公钥**预计算 comb 表（默认 8 槽，满了 LRU 淘汰）。
+ *
+ * 之后 `encrypt` / `kemEncrypt` / `hybridEncrypt` 对该公钥会把 `k·P` 从 wNAF
+ * （256 次倍点）切到 comb（52 次倍点）：本机端到端约 486 → 260 µs。建表一次性
+ * 约 280 µs，**约 1.2 次加密回本**。
+ *
+ * **只有显式 prepare 才会建表**：`encrypt` 命中就走 comb，不命中直接回退 wNAF，
+ * 绝不隐式建表 —— 否则外部可控的公钥能反复触发建表，形成放大面。
+ *
+ * 公钥是公开信息，缓存它不引入新的密钥材料驻留；8 槽共占 wasm 永久区固定 24 KiB。
+ *
+ * @param publicKey 64/65 字节公钥（hex / Uint8Array / PEM）。
+ * @throws {InvalidPublicKeyError} 公钥不在 SM2 曲线上。
+ */
+export async function preparePublicKey(publicKey) {
+    await ensureLoaded();
+    const { x, y } = splitPub(publicKey);
+    if (!isOnCurve(x, y)) {
+        throw new InvalidPublicKeyError('sm2.preparePublicKey: public key is not a point on the SM2 curve');
+    }
+    const hexPub = bytesToHex(x) + bytesToHex(y);
+    const { exports } = getModule();
+    const pxp = exports.alloc(32);
+    const pyp = exports.alloc(32);
+    try {
+        putBytes(x, pxp);
+        putBytes(y, pyp);
+        exports.setCombCapacityOut(preparedCapacity);
+        exports.prepareCombOut(pxp, pyp, preparedCapacity);
+        PREPARED_PUB = hexPub;
+    }
+    finally {
+        exports.freeAll();
+    }
+}
+/** 清空所有公钥预计算槽，之后的 `encrypt` 全部回退到 wNAF。未加载 wasm 时也安全。 */
+export function clearPreparedPublicKeys() {
+    PREPARED_PUB = null;
+    const mod = globalThis.__sm2Wasm;
+    if (mod)
+        mod.exports.clearComb();
+}
+/** @deprecated 用 `clearPreparedPublicKeys()`（保留单数别名）。 */
+export function clearPreparedPublicKey() {
+    clearPreparedPublicKeys();
+}
+/**
+ * 当前槽位中的公钥（hex，按槽序）。
+ *
+ * wasm 未加载时返回空数组。
+ */
+export function getPreparedPublicKeys() {
+    const mod = globalThis.__sm2Wasm;
+    if (!mod)
+        return [];
+    const out = mod.exports.alloc(64);
+    const keys = [];
+    try {
+        for (let s = 0; s < preparedCapacity; s++) {
+            if (mod.exports.combSlotKeyOut(s, out) === 1) {
+                keys.push(bytesToHex(new Uint8Array(mod.memory.buffer, out, 64).slice()));
+            }
+        }
+    }
+    finally {
+        mod.exports.freeAll();
+    }
+    return keys;
+}
+/** 最后一次 `preparePublicKey` 的公钥（hex）；没有则为 `null`。 */
+export function getPreparedPublicKey() {
+    return PREPARED_PUB;
+}
 /**
  * SM2 加密。
  *

package/dist/webcrypto/algorithms.d.ts

@@ -0,0 +1,42 @@
+/**
+ * WebCrypto 算法名归一化与参数校验。
+ *
+ * 算法名大小写不敏感；对外只暴露 `sm-crypto-wasm/webcrypto` 的一个精选子集：
+ * SM3、HMAC(SM3)、SM2、SM4 的 ECB/CBC/CTR/CFB/OFB/GCM。
+ */
+/** 算法输入：字符串或带 `name` 的对象。 */
+export type AlgorithmInput = string | {
+    readonly name: string;
+    readonly [key: string]: unknown;
+};
+/** 归一化后的算法。 */
+export interface NormalizedAlgorithm {
+    readonly name: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * 归一化算法名并校验支持性。
+ *
+ * @throws DOMException `NotSupportedError` / `TypeError`
+ */
+export declare function normalizeAlgorithm(input: AlgorithmInput): NormalizedAlgorithm;
+/** 是否为 SM4 系列算法。 */
+export declare function isSm4(name: string): boolean;
+/** 是否为 AES 风格的对称算法（SM4）。 */
+export declare function isSymmetric(name: string): boolean;
+/** BufferSource → 独立 Uint8Array（拷贝）。 */
+export declare function bufferSourceBytes(value: ArrayBuffer | ArrayBufferView | undefined, label: string, required?: boolean): Uint8Array;
+/** 必需的 IV。 */
+export declare function requireIv(algorithm: NormalizedAlgorithm): Uint8Array;
+/** 可选的 additionalData。 */
+export declare function optionalAad(algorithm: NormalizedAlgorithm): Uint8Array;
+/** GCM 的 tagLength：只支持 128。 */
+export declare function requireGcmTagLength(algorithm: NormalizedAlgorithm): 128;
+/** SM4-CTR 的 length：只支持 128。 */
+export declare function requireCtrLength(algorithm: NormalizedAlgorithm): 128;
+/** SM4 密钥长度：固定 128。 */
+export declare function requireAesLength(algorithm: NormalizedAlgorithm): 128;
+/** HMAC 的 hash 参数归一化为 SM3。 */
+export declare function hashName(hash: unknown): 'SM3';
+/** SM2 的可选 userID。 */
+export declare function optionalUserId(algorithm: NormalizedAlgorithm): Uint8Array | undefined;

package/dist/webcrypto/algorithms.js

@@ -0,0 +1,120 @@
+/**
+ * WebCrypto 算法名归一化与参数校验。
+ *
+ * 算法名大小写不敏感；对外只暴露 `sm-crypto-wasm/webcrypto` 的一个精选子集：
+ * SM3、HMAC(SM3)、SM2、SM4 的 ECB/CBC/CTR/CFB/OFB/GCM。
+ */
+import { dataError, notSupported } from './errors.js';
+const SUPPORTED = new Set([
+    'SM3',
+    'HMAC',
+    'SM2',
+    'SM4-ECB',
+    'SM4-CBC',
+    'SM4-CTR',
+    'SM4-CFB',
+    'SM4-OFB',
+    'SM4-GCM',
+]);
+const SM4_NAMES = new Set(['SM4-ECB', 'SM4-CBC', 'SM4-CTR', 'SM4-CFB', 'SM4-OFB', 'SM4-GCM']);
+/**
+ * 归一化算法名并校验支持性。
+ *
+ * @throws DOMException `NotSupportedError` / `TypeError`
+ */
+export function normalizeAlgorithm(input) {
+    if (typeof input === 'string') {
+        const name = input.toUpperCase();
+        if (!SUPPORTED.has(name)) {
+            throw notSupported(`unsupported algorithm "${input}"`);
+        }
+        return { name };
+    }
+    if (input === null || typeof input !== 'object' || typeof input.name !== 'string') {
+        throw new TypeError('algorithm must be a string or an object with a name');
+    }
+    const name = input.name.toUpperCase();
+    if (!SUPPORTED.has(name)) {
+        throw notSupported(`unsupported algorithm "${input.name}"`);
+    }
+    return { ...input, name };
+}
+/** 是否为 SM4 系列算法。 */
+export function isSm4(name) {
+    return SM4_NAMES.has(name);
+}
+/** 是否为 AES 风格的对称算法（SM4）。 */
+export function isSymmetric(name) {
+    return SM4_NAMES.has(name);
+}
+/** BufferSource → 独立 Uint8Array（拷贝）。 */
+export function bufferSourceBytes(value, label, required = true) {
+    if (value === undefined) {
+        if (required)
+            throw dataError(`${label} is required`);
+        return new Uint8Array(0);
+    }
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value.slice(0));
+    if (ArrayBuffer.isView(value)) {
+        return new Uint8Array(value.buffer, value.byteOffset, value.byteLength).slice();
+    }
+    throw dataError(`${label} must be an ArrayBuffer or ArrayBufferView`);
+}
+/** 必需的 IV。 */
+export function requireIv(algorithm) {
+    const iv = bufferSourceBytes(algorithm.iv, 'iv', true);
+    if (iv.length === 0)
+        throw dataError('iv must not be empty');
+    return iv;
+}
+/** 可选的 additionalData。 */
+export function optionalAad(algorithm) {
+    return bufferSourceBytes(algorithm.additionalData, 'additionalData', false);
+}
+/** GCM 的 tagLength：只支持 128。 */
+export function requireGcmTagLength(algorithm) {
+    const tagLength = algorithm.tagLength ?? 128;
+    if (!Number.isInteger(tagLength) || tagLength !== 128) {
+        throw notSupported(`SM4-GCM tagLength ${String(tagLength)} is not supported (only 128)`);
+    }
+    return 128;
+}
+/** SM4-CTR 的 length：只支持 128。 */
+export function requireCtrLength(algorithm) {
+    const length = algorithm.length ?? 128;
+    if (!Number.isInteger(length) || length !== 128) {
+        throw notSupported(`SM4-CTR length ${String(length)} is not supported (only 128)`);
+    }
+    return 128;
+}
+/** SM4 密钥长度：固定 128。 */
+export function requireAesLength(algorithm) {
+    const length = algorithm.length ?? 128;
+    if (!Number.isInteger(length) || length !== 128) {
+        throw notSupported(`SM4 key length ${String(length)} is not supported (only 128)`);
+    }
+    return 128;
+}
+/** HMAC 的 hash 参数归一化为 SM3。 */
+export function hashName(hash) {
+    if (hash === undefined)
+        throw dataError('HMAC requires a hash parameter');
+    const name = typeof hash === 'string'
+        ? hash.toUpperCase()
+        : typeof hash === 'object' && hash !== null && 'name' in hash
+            ? String(hash.name).toUpperCase()
+            : '';
+    if (name !== 'SM3')
+        throw notSupported(`HMAC hash "${name}" is not supported (only SM3)`);
+    return 'SM3';
+}
+/** SM2 的可选 userID。 */
+export function optionalUserId(algorithm) {
+    const raw = algorithm.userID;
+    if (raw === undefined)
+        return undefined;
+    if (!(raw instanceof Uint8Array))
+        throw dataError('SM2 userID must be a Uint8Array');
+    return new Uint8Array(raw);
+}

package/dist/webcrypto/cryptoKey.d.ts

@@ -0,0 +1,64 @@
+/**
+ * WebCrypto 风格的 `CryptoKey`。
+ *
+ * 密钥材料放在模块级 `WeakMap` 中，对象本身只暴露只读元数据；这样：
+ * - 无法通过序列化/枚举把私钥带出去；
+ * - 将来接入 HSM/RemoteSigner 时可把材料换成 `provider`，公共 API 不变。
+ */
+/** 密钥类型。 */
+export type KeyType = 'secret' | 'public' | 'private';
+/** WebCrypto 密钥用途。 */
+export type KeyUsage = 'encrypt' | 'decrypt' | 'sign' | 'verify' | 'deriveKey' | 'deriveBits' | 'wrapKey' | 'unwrapKey';
+/** 密钥算法元数据（只读）。 */
+export interface KeyAlgorithm {
+    readonly name: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * 将来的外部密钥提供者（HSM / RemoteSigner）。
+ *
+ * v1 不实现；`KeyMaterial` 已按联合类型预留，后续无需改公共 API。
+ */
+export interface KeyProvider {
+    sign?(algorithm: KeyAlgorithm, data: Uint8Array): Uint8Array | Promise<Uint8Array>;
+    verify?(algorithm: KeyAlgorithm, signature: Uint8Array, data: Uint8Array): boolean | Promise<boolean>;
+    encrypt?(algorithm: KeyAlgorithm, data: Uint8Array): Uint8Array | Promise<Uint8Array>;
+    decrypt?(algorithm: KeyAlgorithm, data: Uint8Array): Uint8Array | Promise<Uint8Array>;
+    exportKey?(format: string): Uint8Array | Promise<Uint8Array>;
+}
+/** 密钥材料。v1 只创建 `bytes`；`provider` 为将来预留。 */
+export type KeyMaterial = {
+    readonly kind: 'bytes';
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: 'provider';
+    readonly provider: KeyProvider;
+};
+/** WebCrypto 风格的密钥对象。 */
+export declare class CryptoKey {
+    readonly type: KeyType;
+    readonly extractable: boolean;
+    readonly algorithm: KeyAlgorithm;
+    readonly usages: readonly KeyUsage[];
+    constructor(type: KeyType, algorithm: KeyAlgorithm, extractable: boolean, usages: readonly KeyUsage[]);
+}
+/** 创建带字节材料的密钥（内部使用）。 */
+export declare function createBytesKey(type: KeyType, algorithm: KeyAlgorithm, extractable: boolean, usages: readonly KeyUsage[], bytes: Uint8Array): CryptoKey;
+/** 创建带外部 provider 的密钥（v1 预留，内部使用）。 */
+export declare function createProviderKey(type: KeyType, algorithm: KeyAlgorithm, extractable: boolean, usages: readonly KeyUsage[], provider: KeyProvider): CryptoKey;
+/** 读取密钥材料（内部使用）。 */
+export declare function getKeyMaterial(key: CryptoKey): KeyMaterial;
+/** 读取字节材料（内部使用）；provider 材料暂不支持同步读取。 */
+export declare function getKeyBytes(key: CryptoKey): Uint8Array;
+/** 校验密钥类型。 */
+export declare function assertKeyType(key: unknown, expected: KeyType, operation: string): asserts key is CryptoKey;
+/** 校验密钥用途。 */
+export declare function assertUsage(key: CryptoKey, usage: KeyUsage, operation: string): void;
+/** 校验密钥算法名。 */
+export declare function assertKeyAlgorithm(key: CryptoKey, name: string, operation: string): void;
+/** 校验 usage 列表合法（未知值抛 SyntaxError）。 */
+export declare function normalizeUsages(usages: readonly string[] | undefined): KeyUsage[];
+/** 检查 usage 是否属于允许集合；不允许时抛 SyntaxError。 */
+export declare function assertUsagesAllowed(usages: readonly KeyUsage[], allowed: readonly KeyUsage[], algorithm: string): void;
+/** 取交集（保持 requesting 顺序）。 */
+export declare function filterUsages(usages: readonly KeyUsage[], allowed: readonly KeyUsage[]): KeyUsage[];

package/dist/webcrypto/cryptoKey.js

@@ -0,0 +1,109 @@
+/**
+ * WebCrypto 风格的 `CryptoKey`。
+ *
+ * 密钥材料放在模块级 `WeakMap` 中，对象本身只暴露只读元数据；这样：
+ * - 无法通过序列化/枚举把私钥带出去；
+ * - 将来接入 HSM/RemoteSigner 时可把材料换成 `provider`，公共 API 不变。
+ */
+import { invalidAccess, notSupported } from './errors.js';
+const ALL_USAGES = [
+    'encrypt',
+    'decrypt',
+    'sign',
+    'verify',
+    'deriveKey',
+    'deriveBits',
+    'wrapKey',
+    'unwrapKey',
+];
+const MATERIAL = new WeakMap();
+/** WebCrypto 风格的密钥对象。 */
+export class CryptoKey {
+    type;
+    extractable;
+    algorithm;
+    usages;
+    constructor(type, algorithm, extractable, usages) {
+        this.type = type;
+        this.extractable = extractable;
+        this.algorithm = Object.freeze({ ...algorithm });
+        this.usages = Object.freeze([...usages]);
+    }
+}
+/** 创建带字节材料的密钥（内部使用）。 */
+export function createBytesKey(type, algorithm, extractable, usages, bytes) {
+    const key = new CryptoKey(type, algorithm, extractable, usages);
+    MATERIAL.set(key, { kind: 'bytes', bytes: new Uint8Array(bytes) });
+    return key;
+}
+/** 创建带外部 provider 的密钥（v1 预留，内部使用）。 */
+export function createProviderKey(type, algorithm, extractable, usages, provider) {
+    const key = new CryptoKey(type, algorithm, extractable, usages);
+    MATERIAL.set(key, { kind: 'provider', provider });
+    return key;
+}
+/** 读取密钥材料（内部使用）。 */
+export function getKeyMaterial(key) {
+    const material = MATERIAL.get(key);
+    if (material === undefined) {
+        throw invalidAccess('key has no material (was it created by this module?)');
+    }
+    return material;
+}
+/** 读取字节材料（内部使用）；provider 材料暂不支持同步读取。 */
+export function getKeyBytes(key) {
+    const material = getKeyMaterial(key);
+    if (material.kind !== 'bytes') {
+        throw notSupported('external key providers are not supported yet');
+    }
+    return material.bytes;
+}
+/** 校验密钥类型。 */
+export function assertKeyType(key, expected, operation) {
+    if (!(key instanceof CryptoKey)) {
+        throw new TypeError(`${operation}: key must be a CryptoKey`);
+    }
+    if (key.type !== expected) {
+        throw invalidAccess(`${operation} requires a ${expected} key, got ${key.type}`);
+    }
+}
+/** 校验密钥用途。 */
+export function assertUsage(key, usage, operation) {
+    if (!key.usages.includes(usage)) {
+        throw invalidAccess(`${operation}: key does not allow "${usage}"`);
+    }
+}
+/** 校验密钥算法名。 */
+export function assertKeyAlgorithm(key, name, operation) {
+    if (key.algorithm.name !== name) {
+        throw invalidAccess(`${operation}: key algorithm is ${key.algorithm.name}, expected ${name}`);
+    }
+}
+/** 校验 usage 列表合法（未知值抛 SyntaxError）。 */
+export function normalizeUsages(usages) {
+    if (usages === undefined)
+        return [];
+    if (!Array.isArray(usages))
+        throw new TypeError('keyUsages must be an array');
+    const out = [];
+    for (const usage of usages) {
+        if (!ALL_USAGES.includes(usage)) {
+            throw new DOMException(`unknown key usage "${usage}"`, 'SyntaxError');
+        }
+        if (!out.includes(usage))
+            out.push(usage);
+    }
+    return out;
+}
+/** 检查 usage 是否属于允许集合；不允许时抛 SyntaxError。 */
+export function assertUsagesAllowed(usages, allowed, algorithm) {
+    for (const usage of usages) {
+        if (!allowed.includes(usage)) {
+            throw new DOMException(`usage "${usage}" is not valid for ${algorithm}`, 'SyntaxError');
+        }
+    }
+}
+/** 取交集（保持 requesting 顺序）。 */
+export function filterUsages(usages, allowed) {
+    return usages.filter((usage) => allowed.includes(usage));
+}

package/dist/webcrypto/errors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * WebCrypto 适配层的错误映射。
+ *
+ * 对外的所有失败都映射为 `DOMException`（WebCrypto 的约定）：
+ * - `NotSupportedError`：未知算法/格式/不支持的参数；
+ * - `InvalidAccessError`：密钥用途或 `extractable` 不允许；
+ * - `DataError`：密钥/数据格式非法；
+ * - `OperationError`：加解密/验签失败。
+ */
+/** 构造 `DOMException` 的便捷函数。 */
+export declare function notSupported(message: string): DOMException;
+/** 构造 `InvalidAccessError`。 */
+export declare function invalidAccess(message: string): DOMException;
+/** 构造 `DataError`。 */
+export declare function dataError(message: string): DOMException;
+/** 构造 `OperationError`。 */
+export declare function operationError(message: string): DOMException;
+/** 把库内错误映射为 `DOMException`；已经是 `DOMException` 时原样返回。 */
+export declare function toDOMException(err: unknown, fallback?: 'OperationError' | 'DataError'): DOMException;