@trustbaseai/account 0.1.0

package/dist/prf.js

@@ -0,0 +1,318 @@
+"use strict";
+/**
+ * PRF 硬件解锁（SDK 方案 §3.3.5）—— 用平台认证器持有的秘密包住解锁密钥。
+ *
+ * ## 它解决什么问题、不解决什么问题
+ *
+ * ✅ 解决：把"解锁 keystore 的钥匙"绑到**硬件 + 生物识别/PIN**。秘密由
+ *    Secure Enclave / Android Keystore（StrongBox）持有，**永不导出**，
+ *    每次取都要过生物识别。我们不存它、也导不出它。
+ *
+ * ❌ 不解决（**别往这个方向设计**）：拿 SE/Keystore 直接签链上交易。
+ *    浏览器只有 WebAuthn，而 WebAuthn 断言签的是"认证器数据 + 客户端数据哈希"，
+ *    **不能对任意 payload 签名** —— 拿不到一把能签 Cosmos 交易的密钥。
+ *    （出处：SDK 方案 §3.3.5 的 ⚠️ 段，这是本节最容易被想歪的地方。）
+ *
+ * ## 包装格式（v1，跨语言可复算）
+ *
+ * ```
+ * KEK = HKDF-SHA256(ikm = PRF 秘密, salt = salt, info = info) → 32 字节
+ * wrapped = AES-256-GCM(key = KEK, iv = 12 随机字节, plaintext = 被包的密钥材料)
+ * ```
+ *
+ * ```jsonc
+ * {
+ *   "version": 1,
+ *   "kdf": "hkdf-sha256",
+ *   "credentialId": "<WebAuthn 凭据 ID（base64url）>",
+ *   "salt": "<base64>",       // 同时是 HKDF 的 salt 与 AAD 的一部分
+ *   "info": "trustbase/prf-wrap/v1",
+ *   "cipher": "aes-256-gcm",
+ *   "iv": "<base64, 12 字节>",
+ *   "ciphertext": "<base64>",
+ *   "tag": "<base64>"
+ * }
+ * ```
+ *
+ * AAD（防"参数被改"）：
+ *
+ * ```
+ * trustbase-prf-wrap-v1|kdf=hkdf-sha256|credentialId=<id>|info=<info>|salt=<b64>|cipher=aes-256-gcm|iv=<b64>
+ * ```
+ *
+ * 于是：**换设备/重装 → PRF 秘密变了 → 认证失败 → 回退口令或助记词**
+ * （SDK 方案 §3.3.7 第 2 条的取舍：PRF 是"首选体验"，不是唯一出路；
+ * 双轨的编排见 envelope.ts）。
+ *
+ * ## 本文件与 prf-webauthn.ts 的分工
+ *
+ * 本文件是**纯密码学 + 接口**，在 Node 里能完整单测（用 `createStaticPrfProvider`
+ * 造假秘密）。真正调 `navigator.credentials` 的适配器在 prf-webauthn.ts，
+ * 那个文件**没有 Node 单测覆盖**，必须在真机浏览器验证 —— 那里写得很明确，别混。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRF_WRAP_KDF = exports.PRF_WRAP_CIPHER = exports.PRF_SALT_DEFAULT_LENGTH = exports.PRF_SALT_MAX_LENGTH = exports.PRF_SALT_MIN_LENGTH = exports.PRF_SECRET_MAX_LENGTH = exports.PRF_SECRET_MIN_LENGTH = exports.PRF_SECRET_LENGTH = exports.PRF_WRAP_AAD_PREFIX = exports.PRF_WRAP_INFO = exports.PRF_WRAP_VERSION = void 0;
+exports.derivePrfKek = derivePrfKek;
+exports.prfWrapAadText = prfWrapAadText;
+exports.wrapKeyWithPrf = wrapKeyWithPrf;
+exports.unwrapKeyWithPrf = unwrapKeyWithPrf;
+exports.parsePrfWrappedKey = parsePrfWrappedKey;
+exports.isPrfWrappedKey = isPrfWrappedKey;
+exports.serializePrfWrappedKey = serializePrfWrappedKey;
+exports.createStaticPrfProvider = createStaticPrfProvider;
+exports.isSameSecret = isSameSecret;
+const hkdf_1 = require("@noble/hashes/hkdf");
+const sha256_1 = require("@noble/hashes/sha256");
+const bytes_1 = require("./bytes");
+const errors_1 = require("./errors");
+const webcrypto_1 = require("./webcrypto");
+/** 包装格式版本 */
+exports.PRF_WRAP_VERSION = 1;
+/** HKDF 的 info：域分隔串（带版本；换格式必须换它，否则新旧包会互相解开对方的东西） */
+exports.PRF_WRAP_INFO = 'trustbase/prf-wrap/v1';
+/** AAD 前缀（版本化） */
+exports.PRF_WRAP_AAD_PREFIX = 'trustbase-prf-wrap-v1';
+/** HKDF-SHA256 在 WebAuthn PRF 下的典型输出长度（认证器返回 32 字节） */
+exports.PRF_SECRET_LENGTH = 32;
+/** 可接受的 PRF 秘密长度区间（给非标准认证器留余量，但拒绝明显不对的输入） */
+exports.PRF_SECRET_MIN_LENGTH = 16;
+exports.PRF_SECRET_MAX_LENGTH = 64;
+/** HKDF salt 长度区间；默认 16 字节随机 */
+exports.PRF_SALT_MIN_LENGTH = 8;
+exports.PRF_SALT_MAX_LENGTH = 64;
+exports.PRF_SALT_DEFAULT_LENGTH = 16;
+/** 唯一支持的对称加密 */
+exports.PRF_WRAP_CIPHER = 'aes-256-gcm';
+/** 唯一支持的 KDF */
+exports.PRF_WRAP_KDF = 'hkdf-sha256';
+function assertPrfSecret(prfSecret) {
+    if (!(prfSecret instanceof Uint8Array)) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', 'PRF 秘密必须是 Uint8Array');
+    }
+    if (prfSecret.length < exports.PRF_SECRET_MIN_LENGTH || prfSecret.length > exports.PRF_SECRET_MAX_LENGTH) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', `PRF 秘密长度必须在 ${exports.PRF_SECRET_MIN_LENGTH}..${exports.PRF_SECRET_MAX_LENGTH} 字节之间` +
+            `（WebAuthn 的 PRF 扩展通常给 ${exports.PRF_SECRET_LENGTH} 字节）`);
+    }
+}
+function assertCredentialId(credentialId) {
+    if (typeof credentialId !== 'string' || credentialId.length === 0) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', 'credentialId 必须是非空字符串（WebAuthn 凭据 ID，base64url）');
+    }
+    if (credentialId.includes('|')) {
+        // AAD 用 `|` 做分隔符：如果 ID 里可以有 `|`，就能构造出两份不同的字段组合、
+        // 同一段 AAD 文本 —— 那正是 AAD 想防的东西
+        throw new errors_1.AccountError('INVALID_ARGUMENT', 'credentialId 不能包含 `|`（会破坏 AAD 的分隔语义）');
+    }
+}
+function resolveSalt(salt) {
+    const resolved = salt ?? (0, webcrypto_1.randomBytes)(exports.PRF_SALT_DEFAULT_LENGTH);
+    if (!(resolved instanceof Uint8Array)) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', 'salt 必须是 Uint8Array');
+    }
+    if (resolved.length < exports.PRF_SALT_MIN_LENGTH || resolved.length > exports.PRF_SALT_MAX_LENGTH) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', `salt 长度必须在 ${exports.PRF_SALT_MIN_LENGTH}..${exports.PRF_SALT_MAX_LENGTH} 字节之间`);
+    }
+    return resolved;
+}
+function resolveInfo(info) {
+    const resolved = info ?? exports.PRF_WRAP_INFO;
+    if (typeof resolved !== 'string' || resolved.length === 0 || resolved.includes('|')) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', 'info 必须是非空字符串且不含 `|`');
+    }
+    return resolved;
+}
+/**
+ * HKDF-SHA256：`PRF 秘密 → 32 字节 KEK`（RFC 5869）。
+ *
+ * 用 `@noble/hashes/hkdf` 而不是 WebCrypto 的 HKDF：这条路径必须**确定性可复算**
+ * （`test/prf.test.ts` 里用 RFC 5869 的公开向量与 `node:crypto.hkdfSync` 双侧对照），
+ * 而且 PRF 本身已经是硬件门控的，不差平台这一道。
+ */
+function derivePrfKek(prfSecret, salt, info = exports.PRF_WRAP_INFO) {
+    assertPrfSecret(prfSecret);
+    if (!(salt instanceof Uint8Array) || salt.length === 0) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', 'HKDF salt 不能为空');
+    }
+    return (0, hkdf_1.hkdf)(sha256_1.sha256, prfSecret, salt, (0, bytes_1.utf8ToBytes)(info), 32);
+}
+/** 被包的头的 AAD 文本（格式见文件头；由测试用字面量钉住） */
+function prfWrapAadText(wrapped) {
+    return [
+        exports.PRF_WRAP_AAD_PREFIX,
+        `kdf=${wrapped.kdf}`,
+        `credentialId=${wrapped.credentialId}`,
+        `info=${wrapped.info}`,
+        `salt=${wrapped.salt}`,
+        `cipher=${wrapped.cipher}`,
+        `iv=${wrapped.iv}`,
+    ].join('|');
+}
+/**
+ * 用 PRF 秘密包住密钥材料（通常是账户的数据密钥 DEK）。
+ *
+ * **不修改 `keyMaterial`**（调用方的缓冲区）；内部 KEK 在返回前清零。
+ */
+async function wrapKeyWithPrf(prfSecret, keyMaterial, options) {
+    assertPrfSecret(prfSecret);
+    if (!(keyMaterial instanceof Uint8Array) || keyMaterial.length === 0) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', '被包装的密钥材料必须是非空 Uint8Array');
+    }
+    assertCredentialId(options.credentialId);
+    const salt = resolveSalt(options.salt);
+    const info = resolveInfo(options.info);
+    const kek = derivePrfKek(prfSecret, salt, info);
+    try {
+        const iv = (0, bytes_1.base64Encode)((0, webcrypto_1.randomBytes)(webcrypto_1.AES_GCM_IV_LENGTH));
+        const header = {
+            kdf: exports.PRF_WRAP_KDF,
+            credentialId: options.credentialId,
+            info,
+            salt: (0, bytes_1.base64Encode)(salt),
+            cipher: exports.PRF_WRAP_CIPHER,
+            iv,
+        };
+        const sealed = await (0, webcrypto_1.aesGcmEncrypt)(kek, (0, bytes_1.base64Decode)(iv), keyMaterial, (0, bytes_1.utf8ToBytes)(prfWrapAadText(header)));
+        return {
+            version: exports.PRF_WRAP_VERSION,
+            ...header,
+            ciphertext: (0, bytes_1.base64Encode)(sealed.ciphertext),
+            tag: (0, bytes_1.base64Encode)(sealed.tag),
+        };
+    }
+    finally {
+        (0, bytes_1.wipe)(kek);
+    }
+}
+/**
+ * 用 PRF 秘密拆开包装，拿回密钥材料。
+ *
+ * PRF 秘密不对（换设备、重装、凭据被删）→ `AUTH_FAILED`，
+ * 与"口令错"同一句话：调用方应当据此提示"用口令或助记词解锁"。
+ */
+async function unwrapKeyWithPrf(wrapped, prfSecret) {
+    const record = parsePrfWrappedKey(wrapped);
+    assertPrfSecret(prfSecret);
+    const kek = derivePrfKek(prfSecret, (0, bytes_1.base64Decode)(record.salt), record.info);
+    try {
+        return await (0, webcrypto_1.aesGcmDecrypt)(kek, (0, bytes_1.base64Decode)(record.iv), (0, bytes_1.base64Decode)(record.ciphertext), (0, bytes_1.base64Decode)(record.tag), (0, bytes_1.utf8ToBytes)(prfWrapAadText(record)));
+    }
+    finally {
+        (0, bytes_1.wipe)(kek);
+    }
+}
+const PRF_WRAP_KEYS = [
+    'version',
+    'kdf',
+    'credentialId',
+    'salt',
+    'info',
+    'cipher',
+    'iv',
+    'ciphertext',
+    'tag',
+];
+/** 校验并归一化一份 PRF 包装（接受对象或 JSON 字符串）；不合法抛 `INVALID_BLOB` 等 */
+function parsePrfWrappedKey(value) {
+    let raw = value;
+    if (typeof value === 'string') {
+        try {
+            raw = JSON.parse(value);
+        }
+        catch {
+            throw new errors_1.AccountError('INVALID_BLOB', 'PRF 包装不是合法 JSON');
+        }
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new errors_1.AccountError('INVALID_BLOB', 'PRF 包装必须是对象');
+    }
+    const record = raw;
+    for (const key of PRF_WRAP_KEYS) {
+        if (!(key in record))
+            throw new errors_1.AccountError('INVALID_BLOB', `PRF 包装缺少字段：${key}`);
+    }
+    for (const key of Object.keys(record)) {
+        if (!PRF_WRAP_KEYS.includes(key)) {
+            throw new errors_1.AccountError('INVALID_BLOB', `PRF 包装含未知字段：${key}`);
+        }
+    }
+    if (record.version !== exports.PRF_WRAP_VERSION) {
+        // 只有"整数且比本实现新"才算版本问题；1.5 / "1" 一律是结构非法
+        if (typeof record.version === 'number' && Number.isInteger(record.version) && record.version > exports.PRF_WRAP_VERSION) {
+            throw new errors_1.AccountError('UNSUPPORTED_VERSION', `PRF 包装版本 ${record.version} 本实现不认识`);
+        }
+        throw new errors_1.AccountError('INVALID_BLOB', `PRF 包装的 version 非法：${String(record.version)}`);
+    }
+    if (record.kdf !== exports.PRF_WRAP_KDF) {
+        throw new errors_1.AccountError('UNSUPPORTED_KDF', `PRF 包装的 kdf 不支持：${String(record.kdf)}`);
+    }
+    if (record.cipher !== exports.PRF_WRAP_CIPHER) {
+        throw new errors_1.AccountError('INVALID_BLOB', `PRF 包装的 cipher 非法：${String(record.cipher)}`);
+    }
+    assertCredentialId(record.credentialId);
+    if (typeof record.info !== 'string' || record.info.length === 0 || record.info.includes('|')) {
+        throw new errors_1.AccountError('INVALID_BLOB', 'PRF 包装的 info 非法');
+    }
+    (0, bytes_1.decodeBlobField)(record.salt, 'PRF 包装的 salt', { min: exports.PRF_SALT_MIN_LENGTH, max: exports.PRF_SALT_MAX_LENGTH });
+    (0, bytes_1.decodeBlobField)(record.iv, 'PRF 包装的 iv', { exact: webcrypto_1.AES_GCM_IV_LENGTH });
+    (0, bytes_1.decodeBlobField)(record.tag, 'PRF 包装的 tag', { exact: webcrypto_1.AES_GCM_TAG_LENGTH });
+    (0, bytes_1.decodeBlobField)(record.ciphertext, 'PRF 包装的 ciphertext', { min: 1 });
+    return record;
+}
+/** 只问"能不能当 PRF 包装用"，不抛异常 */
+function isPrfWrappedKey(value) {
+    try {
+        parsePrfWrappedKey(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 序列化（字段顺序固定，便于跨端逐字节比对） */
+function serializePrfWrappedKey(wrapped) {
+    const record = parsePrfWrappedKey(wrapped);
+    return JSON.stringify({
+        version: record.version,
+        kdf: record.kdf,
+        credentialId: record.credentialId,
+        salt: record.salt,
+        info: record.info,
+        cipher: record.cipher,
+        iv: record.iv,
+        ciphertext: record.ciphertext,
+        tag: record.tag,
+    });
+}
+/**
+ * 用固定秘密伪造一个 `PrfProvider`。
+ *
+ * ⚠️ **仅供测试与本地开发**：它没有任何硬件保护、不要求生物识别，秘密就在
+ * 进程内存里。生产环境必须用 prf-webauthn.ts 的真适配器（或原生侧的对应实现）。
+ * 之所以放在 src 而不是 test：它是"接口可注入"这条设计的证明，
+ * 也让上层（PWA 的降级路径、CLI 的自动化）有一个明确的替身可用。
+ */
+function createStaticPrfProvider(secret, options = {}) {
+    assertPrfSecret(secret);
+    const expected = Uint8Array.from(secret);
+    const available = options.available ?? true;
+    return {
+        kind: options.kind ?? 'static',
+        async isAvailable() {
+            return available;
+        },
+        async getPrfSecret(credentialId, salt) {
+            assertCredentialId(credentialId);
+            if (!available) {
+                throw new errors_1.AccountError('PRF_UNAVAILABLE', '该 provider 被标记为不可用（测试替身）');
+            }
+            // 真实认证器返回的是"由凭据秘密与 salt 共同决定的固定值"；这里用
+            // HKDF 复现同样的性质：同一个 (credentialId, salt) 永远得到同一串秘密。
+            return derivePrfKek(expected, salt, `static-provider/${credentialId}`);
+        },
+    };
+}
+/** 常数时间比对两份 PRF 秘密（给适配器做"秘密是否变化"自检用） */
+function isSameSecret(a, b) {
+    return (0, bytes_1.equalBytes)(a, b);
+}
+//# sourceMappingURL=prf.js.map

package/dist/prf.js.map

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

package/dist/webcrypto.d.ts

@@ -0,0 +1,93 @@
+/**
+ * WebCrypto 访问层 —— 本包**唯一**碰平台密码学的地方。
+ *
+ * ## 为什么是 WebCrypto 而不是自造或 Node 的 `crypto`
+ *
+ * - SDK 方案 §3.3.1 定的就是「AES-256-GCM（WebCrypto 原生）」，随机数只用
+ *   `crypto.getRandomValues`；Node 18+ 也有同一套 API（`globalThis.crypto.subtle`），
+ *   所以同构不需要两套实现。
+ * - 自造 AES-GCM 或走 `node:crypto` 都会把浏览器侧搞死（同构守卫直接拦）。
+ *
+ * ## 为什么手写这几个 `…Like` 类型，而不是开 `lib: ["DOM"]`
+ *
+ * 本包（与 `@trustbase/protocol` 一样）只开 `lib: ["ES2022"]`。一旦开 DOM lib，
+ * `document` / `window` / `fetch` / `localStorage` 全都变成"能通过类型检查"的
+ * 全局 —— 而它们**在 Node 里跑测试时不存在**：错误就从"编译期"漂到"运行时"，
+ * 而且只在上线后某个环境炸。这里只声明我们真正用到的那几个成员，
+ * 多一个都不给（调用方也别想从本模块借到 `document` 的类型）。
+ *
+ * ## 认证失败为什么在这里被"压平"
+ *
+ * `subtle.decrypt` 在 GCM 标签不匹配时抛 `OperationError`。我们把它**统一**
+ * 转换成 `AUTH_FAILED`（口令错 / 密文被改 / PRF 秘密不匹配都用这一个码），
+ * 理由见 errors.ts 文件头。反过来，**参数形状错误**（key 不是 32 字节、
+ * iv 不是 12 字节、tag 不是 16 字节）是我们自己代码的 bug，抛
+ * `INVALID_ARGUMENT` —— 这种错必须一眼看出是编程错误，不能被伪装成"认证失败"。
+ */
+/** GCM 推荐 IV 长度（96 bit）—— NIST SP 800-38D 的规定长度，别的长度要多一次 GHASH */
+export declare const AES_GCM_IV_LENGTH = 12;
+/** GCM 认证标签长度（128 bit，WebCrypto 默认，也是最强） */
+export declare const AES_GCM_TAG_LENGTH = 16;
+/** AES-256 密钥长度 */
+export declare const AES_KEY_LENGTH = 32;
+/** WebCrypto 密钥句柄（只声明我们需要读的成员） */
+export interface CryptoKeyLike {
+    readonly type: string;
+    readonly extractable: boolean;
+    readonly usages: readonly string[];
+}
+interface AesGcmParamsLike {
+    readonly name: 'AES-GCM';
+    readonly iv: Uint8Array;
+    readonly tagLength: number;
+    readonly additionalData?: Uint8Array;
+}
+/** `crypto.subtle` 中本包用到的成员（AES-GCM 加解密） */
+export interface SubtleCryptoLike {
+    importKey(format: 'raw', keyData: Uint8Array, algorithm: {
+        readonly name: string;
+    }, extractable: boolean, keyUsages: readonly string[]): Promise<CryptoKeyLike>;
+    encrypt(algorithm: AesGcmParamsLike, key: CryptoKeyLike, data: Uint8Array): Promise<ArrayBuffer>;
+    decrypt(algorithm: AesGcmParamsLike, key: CryptoKeyLike, data: Uint8Array): Promise<ArrayBuffer>;
+}
+/** `globalThis.crypto` 中本包用到的成员 */
+export interface CryptoLike {
+    readonly subtle: SubtleCryptoLike;
+    getRandomValues<T extends Uint8Array>(array: T): T;
+}
+/** 运行环境是否有可用的 WebCrypto（含 `subtle` 与 `getRandomValues`） */
+export declare function isWebCryptoAvailable(): boolean;
+/** 取 `crypto.subtle`；不可用时抛 `CRYPTO_UNAVAILABLE`（附可读原因） */
+export declare function requireSubtle(): SubtleCryptoLike;
+/**
+ * 密码学随机字节。
+ *
+ * **绝不用 `Math.random`**（SDK 方案 §3.3.1 明写）—— 这里的实现只走
+ * `crypto.getRandomValues`，拿不到随机源就抛 `CRYPTO_UNAVAILABLE`，
+ * 不存在"退化为弱随机"的分支。这一点很关键：退化分支一旦存在，
+ * 就一定会有人在某个环境里静默用上它。
+ */
+export declare function randomBytes(length: number): Uint8Array;
+/**
+ * AES-256-GCM 加密。
+ *
+ * `aad`（additional authenticated data）用来把**明文头**（blob 版本 / KDF 名字 /
+ * KDF 参数 / IV）绑进认证范围：这些字段不参与密钥派生，若不认证，攻击者可以
+ * 改掉它们而密文照样解得开 —— 那就等于"KDF 参数随人改"。见 keystore.ts 的
+ * `keystoreAad()`。
+ *
+ * WebCrypto 返回的是 `ciphertext || tag` 连在一起的缓冲，这里按设计文档的
+ * 字段形状拆成两段（`ciphertext` / `tag`），方便别的语言/别的实现对照复算。
+ */
+export declare function aesGcmEncrypt(key: Uint8Array, iv: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Promise<{
+    ciphertext: Uint8Array;
+    tag: Uint8Array;
+}>;
+/**
+ * AES-256-GCM 解密。
+ *
+ * 认证失败（口令错 / 密文被改 / 秘密不匹配）→ `AUTH_FAILED`，消息刻意含糊。
+ */
+export declare function aesGcmDecrypt(key: Uint8Array, iv: Uint8Array, ciphertext: Uint8Array, tag: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
+export {};
+//# sourceMappingURL=webcrypto.d.ts.map

package/dist/webcrypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webcrypto.d.ts","sourceRoot":"","sources":["../src/webcrypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,4CAA4C;AAC5C,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,mBAAmB;AACnB,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,UAAU,gBAAgB;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;CACtC;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CACP,MAAM,EAAE,KAAK,EACb,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EACpC,WAAW,EAAE,OAAO,EACpB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B,OAAO,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACjG,OAAO,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAClG;AAED,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,eAAe,CAAC,CAAC,SAAS,UAAU,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;CACpD;AAQD,2DAA2D;AAC3D,wBAAgB,oBAAoB,IAAI,OAAO,CAQ9C;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,IAAI,gBAAgB,CAUhD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAetD;AAsBD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,UAAU,EACd,SAAS,EAAE,UAAU,EACrB,GAAG,CAAC,EAAE,UAAU,GACf,OAAO,CAAC;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,UAAU,CAAA;CAAE,CAAC,CAkBtD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,UAAU,EACd,UAAU,EAAE,UAAU,EACtB,GAAG,EAAE,UAAU,EACf,GAAG,CAAC,EAAE,UAAU,GACf,OAAO,CAAC,UAAU,CAAC,CAuBrB"}

package/dist/webcrypto.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * WebCrypto 访问层 —— 本包**唯一**碰平台密码学的地方。
+ *
+ * ## 为什么是 WebCrypto 而不是自造或 Node 的 `crypto`
+ *
+ * - SDK 方案 §3.3.1 定的就是「AES-256-GCM（WebCrypto 原生）」，随机数只用
+ *   `crypto.getRandomValues`；Node 18+ 也有同一套 API（`globalThis.crypto.subtle`），
+ *   所以同构不需要两套实现。
+ * - 自造 AES-GCM 或走 `node:crypto` 都会把浏览器侧搞死（同构守卫直接拦）。
+ *
+ * ## 为什么手写这几个 `…Like` 类型，而不是开 `lib: ["DOM"]`
+ *
+ * 本包（与 `@trustbase/protocol` 一样）只开 `lib: ["ES2022"]`。一旦开 DOM lib，
+ * `document` / `window` / `fetch` / `localStorage` 全都变成"能通过类型检查"的
+ * 全局 —— 而它们**在 Node 里跑测试时不存在**：错误就从"编译期"漂到"运行时"，
+ * 而且只在上线后某个环境炸。这里只声明我们真正用到的那几个成员，
+ * 多一个都不给（调用方也别想从本模块借到 `document` 的类型）。
+ *
+ * ## 认证失败为什么在这里被"压平"
+ *
+ * `subtle.decrypt` 在 GCM 标签不匹配时抛 `OperationError`。我们把它**统一**
+ * 转换成 `AUTH_FAILED`（口令错 / 密文被改 / PRF 秘密不匹配都用这一个码），
+ * 理由见 errors.ts 文件头。反过来，**参数形状错误**（key 不是 32 字节、
+ * iv 不是 12 字节、tag 不是 16 字节）是我们自己代码的 bug，抛
+ * `INVALID_ARGUMENT` —— 这种错必须一眼看出是编程错误，不能被伪装成"认证失败"。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AES_KEY_LENGTH = exports.AES_GCM_TAG_LENGTH = exports.AES_GCM_IV_LENGTH = void 0;
+exports.isWebCryptoAvailable = isWebCryptoAvailable;
+exports.requireSubtle = requireSubtle;
+exports.randomBytes = randomBytes;
+exports.aesGcmEncrypt = aesGcmEncrypt;
+exports.aesGcmDecrypt = aesGcmDecrypt;
+const errors_1 = require("./errors");
+/** GCM 推荐 IV 长度（96 bit）—— NIST SP 800-38D 的规定长度，别的长度要多一次 GHASH */
+exports.AES_GCM_IV_LENGTH = 12;
+/** GCM 认证标签长度（128 bit，WebCrypto 默认，也是最强） */
+exports.AES_GCM_TAG_LENGTH = 16;
+/** AES-256 密钥长度 */
+exports.AES_KEY_LENGTH = 32;
+function globalCrypto() {
+    const candidate = globalThis.crypto;
+    if (!candidate || typeof candidate !== 'object')
+        return undefined;
+    return candidate;
+}
+/** 运行环境是否有可用的 WebCrypto（含 `subtle` 与 `getRandomValues`） */
+function isWebCryptoAvailable() {
+    const candidate = globalCrypto();
+    return (candidate !== undefined &&
+        typeof candidate.getRandomValues === 'function' &&
+        typeof candidate.subtle === 'object' &&
+        candidate.subtle !== null);
+}
+/** 取 `crypto.subtle`；不可用时抛 `CRYPTO_UNAVAILABLE`（附可读原因） */
+function requireSubtle() {
+    const candidate = globalCrypto();
+    if (!candidate || typeof candidate.subtle !== 'object' || candidate.subtle === null) {
+        throw new errors_1.AccountError('CRYPTO_UNAVAILABLE', '本环境没有 WebCrypto（globalThis.crypto.subtle）—— 无法加解密密钥库。' +
+            '浏览器请用 https/localhost 打开（非安全上下文不暴露 WebCrypto），Node 请用 18 及以上。');
+    }
+    return candidate.subtle;
+}
+/**
+ * 密码学随机字节。
+ *
+ * **绝不用 `Math.random`**（SDK 方案 §3.3.1 明写）—— 这里的实现只走
+ * `crypto.getRandomValues`，拿不到随机源就抛 `CRYPTO_UNAVAILABLE`，
+ * 不存在"退化为弱随机"的分支。这一点很关键：退化分支一旦存在，
+ * 就一定会有人在某个环境里静默用上它。
+ */
+function randomBytes(length) {
+    if (!Number.isInteger(length) || length < 0) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', '随机字节长度必须是非负整数');
+    }
+    const candidate = globalCrypto();
+    if (!candidate || typeof candidate.getRandomValues !== 'function') {
+        throw new errors_1.AccountError('CRYPTO_UNAVAILABLE', '本环境没有 crypto.getRandomValues —— 无法生成安全随机数');
+    }
+    const out = new Uint8Array(length);
+    // getRandomValues 对单次请求有 65536 字节上限（超出抛 QuotaExceededError），分块填充
+    const MAX_CHUNK = 65_536;
+    for (let offset = 0; offset < length; offset += MAX_CHUNK) {
+        candidate.getRandomValues(out.subarray(offset, Math.min(offset + MAX_CHUNK, length)));
+    }
+    return out;
+}
+/** 断言密钥长度（编程错误，不是认证失败） */
+function assertKeyLength(key) {
+    if (!(key instanceof Uint8Array) || key.length !== exports.AES_KEY_LENGTH) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', `AES-256-GCM 密钥必须是 ${exports.AES_KEY_LENGTH} 字节`);
+    }
+}
+/** 断言 IV 长度 */
+function assertIvLength(iv) {
+    if (!(iv instanceof Uint8Array) || iv.length !== exports.AES_GCM_IV_LENGTH) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', `AES-GCM 的 IV 必须是 ${exports.AES_GCM_IV_LENGTH} 字节`);
+    }
+}
+async function importAesKey(key, usage) {
+    assertKeyLength(key);
+    // extractable = false：这把句柄再也导不出原始字节，是"少一份副本"的免费收益
+    return requireSubtle().importKey('raw', key, { name: 'AES-GCM' }, false, [usage]);
+}
+/**
+ * AES-256-GCM 加密。
+ *
+ * `aad`（additional authenticated data）用来把**明文头**（blob 版本 / KDF 名字 /
+ * KDF 参数 / IV）绑进认证范围：这些字段不参与密钥派生，若不认证，攻击者可以
+ * 改掉它们而密文照样解得开 —— 那就等于"KDF 参数随人改"。见 keystore.ts 的
+ * `keystoreAad()`。
+ *
+ * WebCrypto 返回的是 `ciphertext || tag` 连在一起的缓冲，这里按设计文档的
+ * 字段形状拆成两段（`ciphertext` / `tag`），方便别的语言/别的实现对照复算。
+ */
+async function aesGcmEncrypt(key, iv, plaintext, aad) {
+    assertIvLength(iv);
+    if (!(plaintext instanceof Uint8Array)) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', '待加密的明文必须是 Uint8Array');
+    }
+    const cryptoKey = await importAesKey(key, 'encrypt');
+    const sealed = new Uint8Array(await requireSubtle().encrypt({ name: 'AES-GCM', iv, tagLength: exports.AES_GCM_TAG_LENGTH * 8, additionalData: aad }, cryptoKey, plaintext));
+    if (sealed.length < exports.AES_GCM_TAG_LENGTH) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', 'GCM 输出短于认证标签长度 —— 运行时的 WebCrypto 行为异常');
+    }
+    const tagStart = sealed.length - exports.AES_GCM_TAG_LENGTH;
+    return { ciphertext: sealed.slice(0, tagStart), tag: sealed.slice(tagStart) };
+}
+/**
+ * AES-256-GCM 解密。
+ *
+ * 认证失败（口令错 / 密文被改 / 秘密不匹配）→ `AUTH_FAILED`，消息刻意含糊。
+ */
+async function aesGcmDecrypt(key, iv, ciphertext, tag, aad) {
+    assertIvLength(iv);
+    if (!(tag instanceof Uint8Array) || tag.length !== exports.AES_GCM_TAG_LENGTH) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', `GCM 认证标签必须是 ${exports.AES_GCM_TAG_LENGTH} 字节`);
+    }
+    if (!(ciphertext instanceof Uint8Array)) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', '密文必须是 Uint8Array');
+    }
+    const cryptoKey = await importAesKey(key, 'decrypt');
+    const sealed = new Uint8Array(ciphertext.length + tag.length);
+    sealed.set(ciphertext, 0);
+    sealed.set(tag, ciphertext.length);
+    try {
+        const opened = await requireSubtle().decrypt({ name: 'AES-GCM', iv, tagLength: exports.AES_GCM_TAG_LENGTH * 8, additionalData: aad }, cryptoKey, sealed);
+        return new Uint8Array(opened);
+    }
+    catch (error) {
+        if (error instanceof errors_1.AccountError)
+            throw error;
+        throw new errors_1.AccountError('AUTH_FAILED', '解锁失败：口令错误或数据已损坏');
+    }
+}
+//# sourceMappingURL=webcrypto.js.map

package/dist/webcrypto.js.map

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

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@trustbaseai/account",
+  "version": "0.1.0",
+  "description": "TrustBase 账户与密钥库：tct1… 地址派生、口令加密 keystore（Argon2id + AES-256-GCM）、WebAuthn PRF 硬件解锁、口令强度与 BIP39 助记词",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "trustbase",
+    "account",
+    "keystore",
+    "argon2id",
+    "aes-gcm",
+    "webauthn",
+    "prf",
+    "bip39",
+    "bech32"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "jest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
+  },
+  "dependencies": {
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0",
+    "@scure/bip32": "^1.7.0",
+    "@scure/bip39": "^1.6.0",
+    "@zxcvbn-ts/core": "^4.2.0",
+    "@zxcvbn-ts/language-common": "^4.1.3",
+    "hash-wasm": "^4.12.0"
+  },
+  "devDependencies": {
+    "@cosmjs/amino": "^0.36.2",
+    "@cosmjs/crypto": "^0.36.2",
+    "@cosmjs/encoding": "^0.36.2",
+    "@cosmjs/proto-signing": "^0.36.2"
+  }
+}