@trustbaseai/account 0.1.0

package/dist/keystore.d.ts

@@ -0,0 +1,168 @@
+/**
+ * 加密 keystore（SDK 方案 §3.3.1）—— **只存密文**，口令不落任何地方。
+ *
+ * ## 密文形状（格式 v1，跨语言可复算）
+ *
+ * ```jsonc
+ * {
+ *   "version": 1,                 // 格式版本；不认识就拒，不猜
+ *   "kdf": "argon2id",            // 或 "pbkdf2"
+ *   "kdfParams": { "salt": "<base64>", "memory": 19456, "cost": 2,
+ *                  "parallelism": 1, "hashLength": 32, "version": 19 },
+ *   "cipher": "aes-256-gcm",
+ *   "iv": "<base64, 12 字节>",
+ *   "ciphertext": "<base64>",
+ *   "tag": "<base64, 16 字节 GCM 认证标签>"
+ * }
+ * ```
+ *
+ * `pbkdf2` 时 `kdfParams` 是 `{salt, iterations, hashLength, hash:'sha256'}`。
+ * 字段顺序固定（`serializeKeystore` 显式按序构造），这样同一份 keystore
+ * 在任何实现里序列化出来都一样，便于做金标准向量。
+ *
+ * ## 为什么 KDF 参数要进 AAD（本实现相对设计文档的一点加固）
+ *
+ * 设计文档列的字段里，`kdf` / `kdfParams` / `version` / `cipher` / `iv` 都是
+ * **明文头**：它们不参与解密，但决定了密钥怎么派生。如果只把密文丢给 GCM，
+ * 攻击者可以改掉 `kdfParams.cost`（甚至把 `argon2id` 改成 `pbkdf2`）而密文
+ * 照样解得开 —— 那就等于"KDF 强度随人调"。所以这里把整个明文头的**规范化
+ * 文本**作为 GCM 的 AAD 一起认证：
+ *
+ * ```
+ * trustbase-keystore-v1|kdf=argon2id|salt=<b64>|memory=19456|cost=2|parallelism=1|hashLength=32|version=19|cipher=aes-256-gcm|iv=<b64>
+ * trustbase-keystore-v1|kdf=pbkdf2|salt=<b64>|iterations=600000|hashLength=32|hash=sha256|cipher=aes-256-gcm|iv=<b64>
+ * ```
+ *
+ * 任何一位被改 → 认证失败 → `AUTH_FAILED`（与"口令错"同一句话，见 errors.ts）。
+ * 这条格式被 `test/keystore.test.ts` 用字面量钉住，改它等于改密钥库格式。
+ *
+ * ## 内存卫生（说清楚能做到什么）
+ *
+ * - 派生密钥、KDF 输入字节、解密出的明文：本包都在 `finally` 里 `wipe()`
+ * - **不**提供任何把明文写 `localStorage` / `sessionStorage` / IndexedDB 的路径
+ *   （持久化是调用方的事：设备账户存 IndexedDB，商户侧存本机文件，都只存密文）
+ * - 口令是 JS 字符串，**清不掉**（见 bytes.ts `wipe` 的诚实说明）；
+ *   `Uint8Array` 缓冲区我们能清，但引擎/WASM 内部副本清不到
+ *
+ * ## 校验失败的分类（调用方要能分支）
+ *
+ * | 情况 | 错误码 |
+ * |---|---|
+ * | 不是密文 / 字段缺失 / 字段类型不对 / base64 坏 / 参数越界 | `INVALID_BLOB` |
+ * | `version` 比本实现新 | `UNSUPPORTED_VERSION` |
+ * | `kdf` / `hash` / Argon2 版本不认 | `UNSUPPORTED_KDF` |
+ * | 口令错 / 密文被改 / 头被改 | `AUTH_FAILED`（刻意含糊） |
+ * | 环境没有 WebCrypto | `CRYPTO_UNAVAILABLE` |
+ * | 口令超长（>128）、secret 形状不对 | `INVALID_ARGUMENT` |
+ */
+import { type Argon2idParams, type KdfAlgorithm, type Pbkdf2Params } from './kdf';
+/** 密文格式版本。加字段/换算法都要 bump 它（旧实现会拒收，而不是猜着解） */
+export declare const KEYSTORE_VERSION = 1;
+/** 唯一支持的对称加密 */
+export declare const KEYSTORE_CIPHER = "aes-256-gcm";
+/** AAD 前缀（版本化，见文件头） */
+export declare const KEYSTORE_AAD_PREFIX = "trustbase-keystore-v1";
+/** 密钥材料的长度上限（32B 私钥 / 64B BIP39 种子都够；太长的输入说明用错了 API） */
+export declare const MAX_SECRET_MATERIAL_LENGTH = 256;
+interface KeystoreBlobCommon {
+    version: typeof KEYSTORE_VERSION;
+    cipher: typeof KEYSTORE_CIPHER;
+    /** IV（base64，12 字节） */
+    iv: string;
+    /** 密文（base64，不含 tag） */
+    ciphertext: string;
+    /** GCM 认证标签（base64，16 字节） */
+    tag: string;
+}
+/**
+ * 密文 blob。写成"公共字段 & (算法 + 该算法的参数)"的**判别联合**：
+ * `kdf` 与 `kdfParams` 的形状必须配对，写错在编译期就报。
+ */
+export type KeystoreBlob = (KeystoreBlobCommon & {
+    kdf: 'argon2id';
+    kdfParams: Argon2idParams;
+}) | (KeystoreBlobCommon & {
+    kdf: 'pbkdf2';
+    kdfParams: Pbkdf2Params;
+});
+interface KeystoreHeaderCommon {
+    version: typeof KEYSTORE_VERSION;
+    cipher: typeof KEYSTORE_CIPHER;
+    iv: string;
+}
+/**
+ * 明文头 = AAD 的输入。
+ *
+ * `ciphertext` / `tag` **不在里面**：它们本身就是"被认证的对象"，
+ * 自己认证自己没有意义。
+ */
+export type KeystoreHeader = (KeystoreHeaderCommon & {
+    kdf: 'argon2id';
+    kdfParams: Argon2idParams;
+}) | (KeystoreHeaderCommon & {
+    kdf: 'pbkdf2';
+    kdfParams: Pbkdf2Params;
+});
+export interface CreateKeystoreOptions {
+    /**
+     * KDF 选择。默认 `'auto'`：能跑 Argon2id 就用它，否则退 PBKDF2
+     * （退化只发生在**创建**时；解锁永远按密文里写的 KDF 走）。
+     */
+    kdf?: KdfAlgorithm | 'auto';
+    /** Argon2id 参数覆盖（盐/长度/版本由本包决定，不接受覆盖） */
+    argon2?: Partial<Pick<Argon2idParams, 'memory' | 'cost' | 'parallelism'>>;
+    /** PBKDF2 参数覆盖（迭代次数不得低于设计下限 60 万） */
+    pbkdf2?: {
+        iterations?: number;
+    };
+    /**
+     * 口令强度门（0..4）。**默认不设**（本函数是密码学原语，不替调用方做产品策略）。
+     *
+     * 但 SDK 方案 §3.3.6 要求"评分 < 3 拒绝"，所以 PWA 的建户流程应当传
+     * `minStrength: 3`；也可以先自己调 `estimatePasswordStrength()` 给用户完整
+     * 的实时反馈再调本函数（两条路都行，结果一致）。
+     * 传入时按需动态载入口令强度模块（zxcvbn 字典约 1 MB，不建户就不该加载）。
+     */
+    minStrength?: number;
+    /** 强度估算选项（仅当传了 `minStrength` 时生效） */
+    strengthOptions?: {
+        extraBlocklist?: readonly string[];
+        userInputs?: readonly string[];
+    };
+}
+/** 明文头的规范化文本（AAD 的输入，格式见文件头；被测试用字面量钉住） */
+export declare function keystoreAadText(header: KeystoreHeader): string;
+/** 明文头的 AAD 字节（= `utf8(keystoreAadText(header))`） */
+export declare function keystoreAad(header: KeystoreHeader): Uint8Array;
+/**
+ * 创建密钥库：`secret`（私钥 / BIP39 种子等密钥材料）在 `password` 下加密成密文 blob。
+ *
+ * **不修改 `secret`**（它是调用方的缓冲区，用完由调用方 `wipe()`）；
+ * 内部派生的密钥与 KDF 输入字节在返回前清零。
+ */
+export declare function createKeystore(secret: Uint8Array, password: string, options?: CreateKeystoreOptions): Promise<KeystoreBlob>;
+/**
+ * 解锁密钥库，返回密钥材料明文。
+ *
+ * 返回的是**新分配的** `Uint8Array`，调用方负责在用完后 `wipe()` 它
+ * （本包不缓存明文，也不提供任何持久化明文的路径）。
+ */
+export declare function unlockKeystore(keystore: KeystoreBlob | string, password: string): Promise<Uint8Array>;
+/**
+ * 校验并归一化一份密文（接受对象或 JSON 字符串）。
+ *
+ * 这一步是**信任边界**：任何来自磁盘 / IndexedDB / 网络的东西都必须先过这里，
+ * 再交给 KDF —— 否则一个 `memory: 2^31` 的 blob 就是一次 DoS。
+ */
+export declare function parseKeystore(value: KeystoreBlob | string | unknown): KeystoreBlob;
+/** 只问"能不能当密钥库用"，不抛异常 */
+export declare function isKeystoreBlob(value: unknown): value is KeystoreBlob;
+/**
+ * 序列化成 JSON 文本（字段顺序固定：version / kdf / kdfParams / cipher / iv / ciphertext / tag）。
+ *
+ * 固定顺序不是为了好看，而是为了"同一份 keystore 在任何实现里字节一致" ——
+ * 备份文件、金标准向量、跨端比对都要靠它。
+ */
+export declare function serializeKeystore(blob: KeystoreBlob): string;
+export {};
+//# sourceMappingURL=keystore.d.ts.map

package/dist/keystore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystore.d.ts","sourceRoot":"","sources":["../src/keystore.ts"],"names":[],"mappings":"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"}

package/dist/keystore.js

@@ -0,0 +1,340 @@
+"use strict";
+/**
+ * 加密 keystore（SDK 方案 §3.3.1）—— **只存密文**，口令不落任何地方。
+ *
+ * ## 密文形状（格式 v1，跨语言可复算）
+ *
+ * ```jsonc
+ * {
+ *   "version": 1,                 // 格式版本；不认识就拒，不猜
+ *   "kdf": "argon2id",            // 或 "pbkdf2"
+ *   "kdfParams": { "salt": "<base64>", "memory": 19456, "cost": 2,
+ *                  "parallelism": 1, "hashLength": 32, "version": 19 },
+ *   "cipher": "aes-256-gcm",
+ *   "iv": "<base64, 12 字节>",
+ *   "ciphertext": "<base64>",
+ *   "tag": "<base64, 16 字节 GCM 认证标签>"
+ * }
+ * ```
+ *
+ * `pbkdf2` 时 `kdfParams` 是 `{salt, iterations, hashLength, hash:'sha256'}`。
+ * 字段顺序固定（`serializeKeystore` 显式按序构造），这样同一份 keystore
+ * 在任何实现里序列化出来都一样，便于做金标准向量。
+ *
+ * ## 为什么 KDF 参数要进 AAD（本实现相对设计文档的一点加固）
+ *
+ * 设计文档列的字段里，`kdf` / `kdfParams` / `version` / `cipher` / `iv` 都是
+ * **明文头**：它们不参与解密，但决定了密钥怎么派生。如果只把密文丢给 GCM，
+ * 攻击者可以改掉 `kdfParams.cost`（甚至把 `argon2id` 改成 `pbkdf2`）而密文
+ * 照样解得开 —— 那就等于"KDF 强度随人调"。所以这里把整个明文头的**规范化
+ * 文本**作为 GCM 的 AAD 一起认证：
+ *
+ * ```
+ * trustbase-keystore-v1|kdf=argon2id|salt=<b64>|memory=19456|cost=2|parallelism=1|hashLength=32|version=19|cipher=aes-256-gcm|iv=<b64>
+ * trustbase-keystore-v1|kdf=pbkdf2|salt=<b64>|iterations=600000|hashLength=32|hash=sha256|cipher=aes-256-gcm|iv=<b64>
+ * ```
+ *
+ * 任何一位被改 → 认证失败 → `AUTH_FAILED`（与"口令错"同一句话，见 errors.ts）。
+ * 这条格式被 `test/keystore.test.ts` 用字面量钉住，改它等于改密钥库格式。
+ *
+ * ## 内存卫生（说清楚能做到什么）
+ *
+ * - 派生密钥、KDF 输入字节、解密出的明文：本包都在 `finally` 里 `wipe()`
+ * - **不**提供任何把明文写 `localStorage` / `sessionStorage` / IndexedDB 的路径
+ *   （持久化是调用方的事：设备账户存 IndexedDB，商户侧存本机文件，都只存密文）
+ * - 口令是 JS 字符串，**清不掉**（见 bytes.ts `wipe` 的诚实说明）；
+ *   `Uint8Array` 缓冲区我们能清，但引擎/WASM 内部副本清不到
+ *
+ * ## 校验失败的分类（调用方要能分支）
+ *
+ * | 情况 | 错误码 |
+ * |---|---|
+ * | 不是密文 / 字段缺失 / 字段类型不对 / base64 坏 / 参数越界 | `INVALID_BLOB` |
+ * | `version` 比本实现新 | `UNSUPPORTED_VERSION` |
+ * | `kdf` / `hash` / Argon2 版本不认 | `UNSUPPORTED_KDF` |
+ * | 口令错 / 密文被改 / 头被改 | `AUTH_FAILED`（刻意含糊） |
+ * | 环境没有 WebCrypto | `CRYPTO_UNAVAILABLE` |
+ * | 口令超长（>128）、secret 形状不对 | `INVALID_ARGUMENT` |
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SECRET_MATERIAL_LENGTH = exports.KEYSTORE_AAD_PREFIX = exports.KEYSTORE_CIPHER = exports.KEYSTORE_VERSION = void 0;
+exports.keystoreAadText = keystoreAadText;
+exports.keystoreAad = keystoreAad;
+exports.createKeystore = createKeystore;
+exports.unlockKeystore = unlockKeystore;
+exports.parseKeystore = parseKeystore;
+exports.isKeystoreBlob = isKeystoreBlob;
+exports.serializeKeystore = serializeKeystore;
+const bytes_1 = require("./bytes");
+const errors_1 = require("./errors");
+const kdf_1 = require("./kdf");
+const webcrypto_1 = require("./webcrypto");
+/** 密文格式版本。加字段/换算法都要 bump 它（旧实现会拒收，而不是猜着解） */
+exports.KEYSTORE_VERSION = 1;
+/** 唯一支持的对称加密 */
+exports.KEYSTORE_CIPHER = 'aes-256-gcm';
+/** AAD 前缀（版本化，见文件头） */
+exports.KEYSTORE_AAD_PREFIX = 'trustbase-keystore-v1';
+/** 密钥材料的长度上限（32B 私钥 / 64B BIP39 种子都够；太长的输入说明用错了 API） */
+exports.MAX_SECRET_MATERIAL_LENGTH = 256;
+function assertSecretMaterial(secret) {
+    if (!(secret instanceof Uint8Array)) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', '密钥材料必须是 Uint8Array（不要传字符串：字符串无法清零）');
+    }
+    if (secret.length === 0) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', '密钥材料不能为空');
+    }
+    if (secret.length > exports.MAX_SECRET_MATERIAL_LENGTH) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', `密钥材料不得超过 ${exports.MAX_SECRET_MATERIAL_LENGTH} 字节（本 API 是密钥库，不是通用文件存储）`);
+    }
+}
+/** 明文头的规范化文本（AAD 的输入，格式见文件头；被测试用字面量钉住） */
+function keystoreAadText(header) {
+    const parts = [exports.KEYSTORE_AAD_PREFIX, `kdf=${header.kdf}`];
+    if (header.kdf === 'argon2id') {
+        parts.push(`salt=${header.kdfParams.salt}`, `memory=${header.kdfParams.memory}`, `cost=${header.kdfParams.cost}`, `parallelism=${header.kdfParams.parallelism}`, `hashLength=${header.kdfParams.hashLength}`, `version=${header.kdfParams.version}`);
+    }
+    else {
+        parts.push(`salt=${header.kdfParams.salt}`, `iterations=${header.kdfParams.iterations}`, `hashLength=${header.kdfParams.hashLength}`, `hash=${header.kdfParams.hash}`);
+    }
+    parts.push(`cipher=${header.cipher}`, `iv=${header.iv}`);
+    return parts.join('|');
+}
+/** 明文头的 AAD 字节（= `utf8(keystoreAadText(header))`） */
+function keystoreAad(header) {
+    return (0, bytes_1.utf8ToBytes)(keystoreAadText(header));
+}
+function buildKdfSelection(algorithm, options) {
+    if (algorithm === 'argon2id') {
+        return {
+            kdf: 'argon2id',
+            kdfParams: {
+                salt: (0, kdf_1.generateSalt)(),
+                memory: options.argon2?.memory ?? kdf_1.DEFAULT_ARGON2ID_PARAMS.memory,
+                cost: options.argon2?.cost ?? kdf_1.DEFAULT_ARGON2ID_PARAMS.cost,
+                parallelism: options.argon2?.parallelism ?? kdf_1.DEFAULT_ARGON2ID_PARAMS.parallelism,
+                // 长度与版本固定：换它们 = 换格式（要 bump KEYSTORE_VERSION）
+                hashLength: kdf_1.DERIVED_KEY_LENGTH,
+                version: kdf_1.ARGON2ID_VERSION,
+            },
+        };
+    }
+    return {
+        kdf: 'pbkdf2',
+        kdfParams: {
+            salt: (0, kdf_1.generateSalt)(),
+            iterations: options.pbkdf2?.iterations ?? kdf_1.DEFAULT_PBKDF2_ITERATIONS,
+            hashLength: kdf_1.DERIVED_KEY_LENGTH,
+            hash: 'sha256',
+        },
+    };
+}
+/** 明文头 + 密文/标签 = 完整 blob（显式按判别联合拼装，避免类型走散） */
+function withCiphertext(header, ciphertext, tag) {
+    if (header.kdf === 'argon2id') {
+        return {
+            version: header.version,
+            kdf: 'argon2id',
+            kdfParams: header.kdfParams,
+            cipher: header.cipher,
+            iv: header.iv,
+            ciphertext,
+            tag,
+        };
+    }
+    return {
+        version: header.version,
+        kdf: 'pbkdf2',
+        kdfParams: header.kdfParams,
+        cipher: header.cipher,
+        iv: header.iv,
+        ciphertext,
+        tag,
+    };
+}
+/**
+ * 创建密钥库：`secret`（私钥 / BIP39 种子等密钥材料）在 `password` 下加密成密文 blob。
+ *
+ * **不修改 `secret`**（它是调用方的缓冲区，用完由调用方 `wipe()`）；
+ * 内部派生的密钥与 KDF 输入字节在返回前清零。
+ */
+async function createKeystore(secret, password, options = {}) {
+    assertSecretMaterial(secret);
+    if (options.minStrength !== undefined) {
+        const { estimatePasswordStrength } = await Promise.resolve().then(() => __importStar(require('./password')));
+        const strength = estimatePasswordStrength(password, options.strengthOptions);
+        if (strength.score < options.minStrength) {
+            throw new errors_1.AccountError('WEAK_PASSWORD', `口令强度不足（评分 ${strength.score}/4，需要 ≥ ${options.minStrength}）：${strength.reasons.join('；')}`, { score: strength.score, reasons: strength.reasons, acceptable: strength.acceptable });
+        }
+    }
+    const kdfInput = (0, kdf_1.passwordToKdfInput)(password);
+    try {
+        const requested = options.kdf ?? 'auto';
+        const algorithm = requested === 'auto' ? ((await (0, kdf_1.isArgon2idAvailable)()) ? 'argon2id' : 'pbkdf2') : requested;
+        const selection = buildKdfSelection(algorithm, options);
+        (0, kdf_1.assertCreateTimeKdfParams)(selection.kdf, selection.kdfParams);
+        const key = selection.kdf === 'argon2id'
+            ? await (0, kdf_1.deriveArgon2idKey)(selection.kdfParams, kdfInput)
+            : await (0, kdf_1.derivePbkdf2Key)(selection.kdfParams, kdfInput);
+        try {
+            const iv = (0, bytes_1.base64Encode)((0, webcrypto_1.randomBytes)(webcrypto_1.AES_GCM_IV_LENGTH));
+            const header = selection.kdf === 'argon2id'
+                ? { version: exports.KEYSTORE_VERSION, kdf: 'argon2id', kdfParams: selection.kdfParams, cipher: exports.KEYSTORE_CIPHER, iv }
+                : { version: exports.KEYSTORE_VERSION, kdf: 'pbkdf2', kdfParams: selection.kdfParams, cipher: exports.KEYSTORE_CIPHER, iv };
+            const sealed = await (0, webcrypto_1.aesGcmEncrypt)(key, (0, bytes_1.base64Decode)(iv), secret, keystoreAad(header));
+            return withCiphertext(header, (0, bytes_1.base64Encode)(sealed.ciphertext), (0, bytes_1.base64Encode)(sealed.tag));
+        }
+        finally {
+            (0, bytes_1.wipe)(key);
+        }
+    }
+    finally {
+        // 口令的 UTF-8 副本是我们自己的缓冲区 —— 这是"能清的那一半"
+        (0, bytes_1.wipe)(kdfInput);
+    }
+}
+/**
+ * 解锁密钥库，返回密钥材料明文。
+ *
+ * 返回的是**新分配的** `Uint8Array`，调用方负责在用完后 `wipe()` 它
+ * （本包不缓存明文，也不提供任何持久化明文的路径）。
+ */
+async function unlockKeystore(keystore, password) {
+    const blob = parseKeystore(keystore);
+    const kdfInput = (0, kdf_1.passwordToKdfInput)(password);
+    try {
+        const key = blob.kdf === 'argon2id'
+            ? await (0, kdf_1.deriveArgon2idKey)(blob.kdfParams, kdfInput)
+            : await (0, kdf_1.derivePbkdf2Key)(blob.kdfParams, kdfInput);
+        try {
+            return await (0, webcrypto_1.aesGcmDecrypt)(key, (0, bytes_1.decodeBlobField)(blob.iv, 'iv', { exact: webcrypto_1.AES_GCM_IV_LENGTH }), (0, bytes_1.decodeBlobField)(blob.ciphertext, 'ciphertext', { min: 1 }), (0, bytes_1.decodeBlobField)(blob.tag, 'tag', { exact: webcrypto_1.AES_GCM_TAG_LENGTH }), keystoreAad(blob));
+        }
+        finally {
+            (0, bytes_1.wipe)(key);
+        }
+    }
+    finally {
+        (0, bytes_1.wipe)(kdfInput);
+    }
+}
+const COMMON_KEYS = ['version', 'kdf', 'kdfParams', 'cipher', 'iv', 'ciphertext', 'tag'];
+function assertExactKeys(raw) {
+    for (const key of COMMON_KEYS) {
+        if (!(key in raw)) {
+            throw new errors_1.AccountError('INVALID_BLOB', `密钥库缺少字段：${key}`);
+        }
+    }
+    for (const key of Object.keys(raw)) {
+        if (!COMMON_KEYS.includes(key)) {
+            // v1 的形状是冻结的：多出来的字段意味着这不是我们的密文（或有人往里塞数据）
+            throw new errors_1.AccountError('INVALID_BLOB', `密钥库含未知字段：${key}`);
+        }
+    }
+}
+/**
+ * 校验并归一化一份密文（接受对象或 JSON 字符串）。
+ *
+ * 这一步是**信任边界**：任何来自磁盘 / IndexedDB / 网络的东西都必须先过这里，
+ * 再交给 KDF —— 否则一个 `memory: 2^31` 的 blob 就是一次 DoS。
+ */
+function parseKeystore(value) {
+    let raw = value;
+    if (typeof value === 'string') {
+        try {
+            raw = JSON.parse(value);
+        }
+        catch {
+            throw new errors_1.AccountError('INVALID_BLOB', '密钥库不是合法 JSON');
+        }
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new errors_1.AccountError('INVALID_BLOB', '密钥库必须是对象');
+    }
+    const record = raw;
+    if (record.version !== exports.KEYSTORE_VERSION) {
+        // 只有"整数且比本实现新"才算版本问题（提示升级）；1.5 / "1" / null 一律是结构非法
+        if (typeof record.version === 'number' && Number.isInteger(record.version) && record.version > exports.KEYSTORE_VERSION) {
+            throw new errors_1.AccountError('UNSUPPORTED_VERSION', `这份密钥库的格式版本是 ${record.version}，本实现只认识 ${exports.KEYSTORE_VERSION} —— 请升级客户端后再打开`);
+        }
+        throw new errors_1.AccountError('INVALID_BLOB', `密钥库的 version 非法：${String(record.version)}`);
+    }
+    if (record.cipher !== exports.KEYSTORE_CIPHER) {
+        throw new errors_1.AccountError('INVALID_BLOB', `密钥库的 cipher 非法：${String(record.cipher)}`);
+    }
+    if (!(0, kdf_1.isKdfAlgorithm)(record.kdf)) {
+        throw new errors_1.AccountError('UNSUPPORTED_KDF', `密钥库声明的 kdf 本实现不支持：${String(record.kdf)}`);
+    }
+    assertExactKeys(record);
+    if (record.kdf === 'argon2id') {
+        (0, kdf_1.assertArgon2idParams)(record.kdfParams);
+    }
+    else {
+        (0, kdf_1.assertPbkdf2Params)(record.kdfParams);
+    }
+    (0, bytes_1.decodeBlobField)(record.iv, 'iv', { exact: webcrypto_1.AES_GCM_IV_LENGTH });
+    (0, bytes_1.decodeBlobField)(record.tag, 'tag', { exact: webcrypto_1.AES_GCM_TAG_LENGTH });
+    (0, bytes_1.decodeBlobField)(record.ciphertext, 'ciphertext', { min: 1 });
+    return record;
+}
+/** 只问"能不能当密钥库用"，不抛异常 */
+function isKeystoreBlob(value) {
+    try {
+        parseKeystore(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 序列化成 JSON 文本（字段顺序固定：version / kdf / kdfParams / cipher / iv / ciphertext / tag）。
+ *
+ * 固定顺序不是为了好看，而是为了"同一份 keystore 在任何实现里字节一致" ——
+ * 备份文件、金标准向量、跨端比对都要靠它。
+ */
+function serializeKeystore(blob) {
+    const normalized = parseKeystore(blob);
+    return JSON.stringify({
+        version: normalized.version,
+        kdf: normalized.kdf,
+        kdfParams: normalized.kdfParams,
+        cipher: normalized.cipher,
+        iv: normalized.iv,
+        ciphertext: normalized.ciphertext,
+        tag: normalized.tag,
+    });
+}
+//# sourceMappingURL=keystore.js.map

package/dist/keystore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystore.js","sourceRoot":"","sources":["../src/keystore.ts"],"names":[],"mappings":"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"}

package/dist/mnemonic.d.ts

@@ -0,0 +1,84 @@
+/**
+ * BIP39 助记词（纸密钥）与"抄写门"。
+ *
+ * ## 定位（SDK 方案 §3.3.3 第 1 条，必须写进产品文案）
+ *
+ * **助记词是唯一的"忘记密码"退路。** 我们不掌握任何解密材料，没有找回密码
+ * 服务，也没有云端解密备份 —— 这不是能力不足，而是设计：一旦我们能解密，
+ * 我们就成了资金保管方。所以"创建账户必须真的抄一遍助记词"（不是打个勾），
+ * 本文件提供抄写门需要的两个原语。
+ *
+ * ## 生成严出、校验宽进（有意的不对称）
+ *
+ * | 方向 | 口径 | 理由 |
+ * |---|---|---|
+ * | 生成 | 只允许 **128 / 256 bit**（12 / 24 词） | 我们只造这两种，少一种长度就少一类"用户抄错还没发现"的可能 |
+ * | 校验 | 接受任何合法 BIP39（12..24 词、词表内、校验和对） | 用户拿来的旧纸密钥可能是 15/18/21 词的。这里是**用户的钱**，不因为我们不喜欢这个长度就拒收 |
+ *
+ * 助记词派生（BIP39 种子 → BIP32 → secp256k1 → 地址）在 `hd.ts`。
+ */
+/** 我们**生成**的助记词强度（bit） */
+export declare const MNEMONIC_STRENGTHS: readonly [128, 256];
+export type MnemonicStrength = (typeof MNEMONIC_STRENGTHS)[number];
+/** 默认强度：128 bit（12 词）—— 手机上手抄得完 */
+export declare const DEFAULT_MNEMONIC_STRENGTH: MnemonicStrength;
+/** 随机源签名（与 `crypto.getRandomValues` 同形；测试可注入确定性替身） */
+export type RandomSource = (length: number) => Uint8Array;
+/** 生成新助记词（默认 12 词）。随机源只用 `crypto.getRandomValues`（见 webcrypto.ts）。 */
+export declare function generateMnemonic(strength?: MnemonicStrength, rng?: RandomSource): string;
+/**
+ * 归一化助记词文本：去掉首尾空白、把**任意空白**（多空格/换行/制表符）折成
+ * 单个空格、再做 NFKD 归一（BIP39 规定）。
+ *
+ * 为什么必须做：BIP39 的种子是 `PBKDF2(助记词字符串)` —— 多一个空格就是
+ * **另一份种子、另一个账户**。用户从手机备忘录/邮件里粘贴时几乎一定带多余空白，
+ * 于是会出现"抄对了却打不开"这种最伤人的失败。归一化把这个失败模式从
+ * "用户的问题"变成"我们处理掉的问题"。
+ *
+ * 空白以外的字符**不**做宽容处理（不做大小写折叠、不做同义词）：那是真的抄错了。
+ *
+ * @throws AccountError 输入为空（没有任何词）时
+ */
+export declare function normalizeMnemonic(mnemonic: string): string;
+/**
+ * 是不是合法助记词（词表 + 校验和 + 词数）。
+ * 宽进：12/15/18/21/24 词都接受（见文件头）；空白先归一化（见 `normalizeMnemonic`）。
+ */
+export declare function validateMnemonic(mnemonic: string): boolean;
+/** 助记词 → 熵（字节）。非法助记词抛 `INVALID_MNEMONIC` */
+export declare function mnemonicToEntropy(mnemonic: string): Uint8Array;
+/** 熵 → 助记词。只接受 16 字节（128 bit）与 32 字节（256 bit） */
+export declare function entropyToMnemonic(entropy: Uint8Array): string;
+/** 把助记词切成词数组（按任意空白切；不做大小写/字符归一 —— 那是抄错，不是格式问题） */
+export declare function splitMnemonicWords(mnemonic: string): string[];
+/**
+ * 抄写门：从助记词里随机抽 `count` 个位置，让用户回填。
+ *
+ * 返回**升序去重的 0 基下标**（数组下标语义，`words[i]` 直接可用）。
+ * UI 要显示"第几个词"时用 `index + 1`（人类从 1 数）—— 这个转换留在调用方，
+ * 因为它是文案问题，不是密码学问题。
+ */
+export declare function pickTranscriptionIndices(input: string | readonly string[], count: number, rng?: RandomSource): number[];
+export interface TranscriptionAnswer {
+    /** 0 基下标（`pickTranscriptionIndices` 给的那套） */
+    index: number;
+    /** 用户填回来的词 */
+    word: string;
+}
+export interface TranscriptionResult {
+    /** 全部填对（`failed` 与 `missing` 都空）才算过 */
+    ok: boolean;
+    /** 填了但填错的位置（0 基，升序） */
+    failed: number[];
+    /** 根本没填的位置（0 基，升序） */
+    missing: number[];
+}
+/**
+ * 校验抄写结果。
+ *
+ * `answers` 既接受 `{index, word}[]`，也接受 `{ [index]: word }`（表单更顺手）。
+ * **不返回正确答案**（`failed`/`missing` 只给位置）—— 否则这个 API 就成了
+ * 一个"帮你把助记词填回去"的工具，抄写门也就白设了。
+ */
+export declare function checkTranscription(input: string | readonly string[], indices: readonly number[], answers: readonly TranscriptionAnswer[] | Readonly<Record<number, string>>): TranscriptionResult;
+//# sourceMappingURL=mnemonic.d.ts.map

package/dist/mnemonic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mnemonic.d.ts","sourceRoot":"","sources":["../src/mnemonic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,0BAA0B;AAC1B,eAAO,MAAM,kBAAkB,qBAAsB,CAAC;AACtD,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,mCAAmC;AACnC,eAAO,MAAM,yBAAyB,EAAE,gBAAsB,CAAC;AAE/D,sDAAsD;AACtD,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC;AAE1D,sEAAsE;AACtE,wBAAgB,gBAAgB,CAC9B,QAAQ,GAAE,gBAA4C,EACtD,GAAG,GAAE,YAA0B,GAC9B,MAAM,CAWR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAO1D;AAED,4CAA4C;AAC5C,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAQ9D;AAED,iDAAiD;AACjD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAK7D;AAED,kDAAkD;AAClD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAY7D;AAuBD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EACjC,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,YAA0B,GAC9B,MAAM,EAAE,CAUV;AAED,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,cAAc;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,uCAAuC;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,uBAAuB;IACvB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sBAAsB;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAOD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EACjC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,SAAS,mBAAmB,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACzE,mBAAmB,CAoCrB"}