@trustbaseai/account 0.1.0

package/dist/mnemonic.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * BIP39 助记词（纸密钥）与"抄写门"。
+ *
+ * ## 定位（SDK 方案 §3.3.3 第 1 条，必须写进产品文案）
+ *
+ * **助记词是唯一的"忘记密码"退路。** 我们不掌握任何解密材料，没有找回密码
+ * 服务，也没有云端解密备份 —— 这不是能力不足，而是设计：一旦我们能解密，
+ * 我们就成了资金保管方。所以"创建账户必须真的抄一遍助记词"（不是打个勾），
+ * 本文件提供抄写门需要的两个原语。
+ *
+ * ## 生成严出、校验宽进（有意的不对称）
+ *
+ * | 方向 | 口径 | 理由 |
+ * |---|---|---|
+ * | 生成 | 只允许 **128 / 256 bit**（12 / 24 词） | 我们只造这两种，少一种长度就少一类"用户抄错还没发现"的可能 |
+ * | 校验 | 接受任何合法 BIP39（12..24 词、词表内、校验和对） | 用户拿来的旧纸密钥可能是 15/18/21 词的。这里是**用户的钱**，不因为我们不喜欢这个长度就拒收 |
+ *
+ * 助记词派生（BIP39 种子 → BIP32 → secp256k1 → 地址）在 `hd.ts`。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MNEMONIC_STRENGTH = exports.MNEMONIC_STRENGTHS = void 0;
+exports.generateMnemonic = generateMnemonic;
+exports.normalizeMnemonic = normalizeMnemonic;
+exports.validateMnemonic = validateMnemonic;
+exports.mnemonicToEntropy = mnemonicToEntropy;
+exports.entropyToMnemonic = entropyToMnemonic;
+exports.splitMnemonicWords = splitMnemonicWords;
+exports.pickTranscriptionIndices = pickTranscriptionIndices;
+exports.checkTranscription = checkTranscription;
+const bip39_1 = require("@scure/bip39");
+const bip39_2 = require("@scure/bip39");
+const bip39_3 = require("@scure/bip39");
+const english_1 = require("@scure/bip39/wordlists/english");
+const errors_1 = require("./errors");
+const webcrypto_1 = require("./webcrypto");
+/** 我们**生成**的助记词强度（bit） */
+exports.MNEMONIC_STRENGTHS = [128, 256];
+/** 默认强度：128 bit（12 词）—— 手机上手抄得完 */
+exports.DEFAULT_MNEMONIC_STRENGTH = 128;
+/** 生成新助记词（默认 12 词）。随机源只用 `crypto.getRandomValues`（见 webcrypto.ts）。 */
+function generateMnemonic(strength = exports.DEFAULT_MNEMONIC_STRENGTH, rng = webcrypto_1.randomBytes) {
+    if (strength !== 128 && strength !== 256) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', `只生成长度 ${exports.MNEMONIC_STRENGTHS.join(' / ')} bit 的助记词（12 / 24 词）`);
+    }
+    const entropy = rng(strength / 8);
+    if (!(entropy instanceof Uint8Array) || entropy.length !== strength / 8) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', '随机源返回的字节数不对');
+    }
+    // 自己取熵、再交给 BIP39 编码（而不是用库内部的随机源）：随机源只有一个入口，
+    // 测试也能注入确定性替身，跑出可复现的助记词
+    return (0, bip39_1.entropyToMnemonic)(entropy, english_1.wordlist);
+}
+/**
+ * 归一化助记词文本：去掉首尾空白、把**任意空白**（多空格/换行/制表符）折成
+ * 单个空格、再做 NFKD 归一（BIP39 规定）。
+ *
+ * 为什么必须做：BIP39 的种子是 `PBKDF2(助记词字符串)` —— 多一个空格就是
+ * **另一份种子、另一个账户**。用户从手机备忘录/邮件里粘贴时几乎一定带多余空白，
+ * 于是会出现"抄对了却打不开"这种最伤人的失败。归一化把这个失败模式从
+ * "用户的问题"变成"我们处理掉的问题"。
+ *
+ * 空白以外的字符**不**做宽容处理（不做大小写折叠、不做同义词）：那是真的抄错了。
+ *
+ * @throws AccountError 输入为空（没有任何词）时
+ */
+function normalizeMnemonic(mnemonic) {
+    return splitMnemonicWords(mnemonic).join(' ').normalize('NFKD');
+}
+/**
+ * 是不是合法助记词（词表 + 校验和 + 词数）。
+ * 宽进：12/15/18/21/24 词都接受（见文件头）；空白先归一化（见 `normalizeMnemonic`）。
+ */
+function validateMnemonic(mnemonic) {
+    if (typeof mnemonic !== 'string')
+        return false;
+    try {
+        return (0, bip39_3.validateMnemonic)(normalizeMnemonic(mnemonic), english_1.wordlist);
+    }
+    catch {
+        return false;
+    }
+}
+/** 助记词 → 熵（字节）。非法助记词抛 `INVALID_MNEMONIC` */
+function mnemonicToEntropy(mnemonic) {
+    if (!validateMnemonic(mnemonic)) {
+        throw new errors_1.AccountError('INVALID_MNEMONIC', '助记词不合法（词不在 BIP39 英文词表内，或校验和不对 —— 通常意味着某个词抄错了）');
+    }
+    return (0, bip39_2.mnemonicToEntropy)(normalizeMnemonic(mnemonic), english_1.wordlist);
+}
+/** 熵 → 助记词。只接受 16 字节（128 bit）与 32 字节（256 bit） */
+function entropyToMnemonic(entropy) {
+    if (!(entropy instanceof Uint8Array) || (entropy.length !== 16 && entropy.length !== 32)) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', '熵必须是 16 字节（128 bit）或 32 字节（256 bit）');
+    }
+    return (0, bip39_1.entropyToMnemonic)(entropy, english_1.wordlist);
+}
+/** 把助记词切成词数组（按任意空白切；不做大小写/字符归一 —— 那是抄错，不是格式问题） */
+function splitMnemonicWords(mnemonic) {
+    if (typeof mnemonic !== 'string') {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', '助记词必须是字符串');
+    }
+    const words = mnemonic
+        .trim()
+        .split(/\s+/u)
+        .filter((word) => word.length > 0);
+    if (words.length === 0) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', '助记词为空');
+    }
+    return words;
+}
+function toWords(input) {
+    return typeof input === 'string' ? splitMnemonicWords(input) : [...input];
+}
+/**
+ * 无偏地取一个 `[0, limit)` 的随机下标。
+ *
+ * 用**拒绝采样**而不是 `byte % limit`：后者在 limit 不整除 256 时会让前几个
+ * 下标出现得更频繁（模偏差）。抽词位置这种"看起来无所谓"的地方正是模偏差
+ * 最爱藏身之处，而且它会让"随机抽 3 个词"变成"更爱抽前几个词"。
+ */
+function randomIndexBelow(limit, rng) {
+    const bound = 256 - (256 % limit);
+    for (let attempt = 0; attempt < 1000; attempt++) {
+        const byte = rng(1)[0];
+        if (byte === undefined)
+            break;
+        if (byte < bound)
+            return byte % limit;
+    }
+    throw new errors_1.AccountError('INVALID_ARGUMENT', '随机源异常（拒绝采样连续失败）—— 检查 rng 实现');
+}
+/**
+ * 抄写门：从助记词里随机抽 `count` 个位置，让用户回填。
+ *
+ * 返回**升序去重的 0 基下标**（数组下标语义，`words[i]` 直接可用）。
+ * UI 要显示"第几个词"时用 `index + 1`（人类从 1 数）—— 这个转换留在调用方，
+ * 因为它是文案问题，不是密码学问题。
+ */
+function pickTranscriptionIndices(input, count, rng = webcrypto_1.randomBytes) {
+    const words = toWords(input);
+    if (!Number.isInteger(count) || count < 1 || count > words.length) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', `抽词数量必须是 1..${words.length} 的整数（收到 ${String(count)}）`);
+    }
+    const picked = new Set();
+    while (picked.size < count) {
+        picked.add(randomIndexBelow(words.length, rng));
+    }
+    return [...picked].sort((a, b) => a - b);
+}
+/** 比对用的归一化：去空白 + 小写 + NFC（英文词表全小写，这样能容忍手抄的大小写与空格） */
+function normalizeWord(value) {
+    return value.normalize('NFC').trim().toLowerCase();
+}
+/**
+ * 校验抄写结果。
+ *
+ * `answers` 既接受 `{index, word}[]`，也接受 `{ [index]: word }`（表单更顺手）。
+ * **不返回正确答案**（`failed`/`missing` 只给位置）—— 否则这个 API 就成了
+ * 一个"帮你把助记词填回去"的工具，抄写门也就白设了。
+ */
+function checkTranscription(input, indices, answers) {
+    const words = toWords(input);
+    const answerMap = new Map();
+    if (Array.isArray(answers)) {
+        for (const answer of answers) {
+            if (!answer || !Number.isInteger(answer.index)) {
+                throw new errors_1.AccountError('INVALID_ARGUMENT', '答案的 index 必须是整数');
+            }
+            answerMap.set(answer.index, String(answer.word ?? ''));
+        }
+    }
+    else {
+        for (const [key, value] of Object.entries(answers)) {
+            const index = Number(key);
+            if (!Number.isInteger(index)) {
+                throw new errors_1.AccountError('INVALID_ARGUMENT', `答案的键必须是下标（收到 "${key}"）`);
+            }
+            answerMap.set(index, String(value ?? ''));
+        }
+    }
+    const failed = [];
+    const missing = [];
+    for (const index of [...new Set(indices)].sort((a, b) => a - b)) {
+        if (!Number.isInteger(index) || index < 0 || index >= words.length) {
+            throw new errors_1.AccountError('INVALID_ARGUMENT', `下标越界：${String(index)}`);
+        }
+        const answer = answerMap.get(index);
+        if (answer === undefined || normalizeWord(answer).length === 0) {
+            missing.push(index);
+            continue;
+        }
+        if (normalizeWord(answer) !== normalizeWord(words[index] ?? '')) {
+            failed.push(index);
+        }
+    }
+    return { ok: failed.length === 0 && missing.length === 0, failed, missing };
+}
+//# sourceMappingURL=mnemonic.js.map

package/dist/mnemonic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mnemonic.js","sourceRoot":"","sources":["../src/mnemonic.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAqBH,4CAcC;AAeD,8CAEC;AAMD,4CAOC;AAGD,8CAQC;AAGD,8CAKC;AAGD,gDAYC;AA8BD,4DAcC;AA8BD,gDAwCC;AAnND,wCAA2E;AAC3E,wCAA2E;AAC3E,wCAAyE;AACzE,4DAA6E;AAE7E,qCAAwC;AACxC,2CAA0C;AAE1C,0BAA0B;AACb,QAAA,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,CAAU,CAAC;AAGtD,mCAAmC;AACtB,QAAA,yBAAyB,GAAqB,GAAG,CAAC;AAK/D,sEAAsE;AACtE,SAAgB,gBAAgB,CAC9B,WAA6B,iCAAyB,EACtD,MAAoB,uBAAW;IAE/B,IAAI,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;QACzC,MAAM,IAAI,qBAAY,CAAC,kBAAkB,EAAE,SAAS,0BAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC5G,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;IAClC,IAAI,CAAC,CAAC,OAAO,YAAY,UAAU,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,GAAG,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,qBAAY,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;IAC5D,CAAC;IACD,4CAA4C;IAC5C,wBAAwB;IACxB,OAAO,IAAA,yBAAsB,EAAC,OAAO,EAAE,kBAAe,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,iBAAiB,CAAC,QAAgB;IAChD,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,QAAgB;IAC/C,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC/C,IAAI,CAAC;QACH,OAAO,IAAA,wBAAqB,EAAC,iBAAiB,CAAC,QAAQ,CAAC,EAAE,kBAAe,CAAC,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,4CAA4C;AAC5C,SAAgB,iBAAiB,CAAC,QAAgB;IAChD,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,qBAAY,CACpB,kBAAkB,EAClB,+CAA+C,CAChD,CAAC;IACJ,CAAC;IACD,OAAO,IAAA,yBAAsB,EAAC,iBAAiB,CAAC,QAAQ,CAAC,EAAE,kBAAe,CAAC,CAAC;AAC9E,CAAC;AAED,iDAAiD;AACjD,SAAgB,iBAAiB,CAAC,OAAmB;IACnD,IAAI,CAAC,CAAC,OAAO,YAAY,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,EAAE,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE,CAAC,EAAE,CAAC;QACzF,MAAM,IAAI,qBAAY,CAAC,kBAAkB,EAAE,qCAAqC,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,IAAA,yBAAsB,EAAC,OAAO,EAAE,kBAAe,CAAC,CAAC;AAC1D,CAAC;AAED,kDAAkD;AAClD,SAAgB,kBAAkB,CAAC,QAAgB;IACjD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,IAAI,qBAAY,CAAC,kBAAkB,EAAE,WAAW,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,KAAK,GAAG,QAAQ;SACnB,IAAI,EAAE;SACN,KAAK,CAAC,MAAM,CAAC;SACb,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,qBAAY,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,OAAO,CAAC,KAAiC;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;;GAMG;AACH,SAAS,gBAAgB,CAAC,KAAa,EAAE,GAAiB;IACxD,MAAM,KAAK,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC;IAClC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM;QAC9B,IAAI,IAAI,GAAG,KAAK;YAAE,OAAO,IAAI,GAAG,KAAK,CAAC;IACxC,CAAC;IACD,MAAM,IAAI,qBAAY,CAAC,kBAAkB,EAAE,6BAA6B,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,wBAAwB,CACtC,KAAiC,EACjC,KAAa,EACb,MAAoB,uBAAW;IAE/B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAClE,MAAM,IAAI,qBAAY,CAAC,kBAAkB,EAAE,cAAc,KAAK,CAAC,MAAM,WAAW,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpG,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,OAAO,MAAM,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3C,CAAC;AAkBD,qDAAqD;AACrD,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACrD,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAChC,KAAiC,EACjC,OAA0B,EAC1B,OAA0E;IAE1E,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,KAAK,MAAM,MAAM,IAAI,OAAyC,EAAE,CAAC;YAC/D,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC/C,MAAM,IAAI,qBAAY,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,CAAC;YAChE,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;SAAM,CAAC;QACN,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAA2C,CAAC,EAAE,CAAC;YACvF,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAC1B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,qBAAY,CAAC,kBAAkB,EAAE,iBAAiB,GAAG,IAAI,CAAC,CAAC;YACvE,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QAChE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACnE,MAAM,IAAI,qBAAY,CAAC,kBAAkB,EAAE,QAAQ,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;QACD,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,MAAM,KAAK,SAAS,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/D,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,SAAS;QACX,CAAC;QACD,IAAI,aAAa,CAAC,MAAM,CAAC,KAAK,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAChE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC9E,CAAC"}

package/dist/password.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 口令强度估算（SDK 方案 §3.3.6）—— **用估算，不用复杂度规则**。
+ *
+ * ## 为什么不搞"必须含大小写数字符号"
+ *
+ * 规则只会逼出 `Password1!` 这种"看着合规、实际上榜"的口令：它满足所有规则，
+ * 却是攻击者字典里的第一批。真正决定成本的是**可猜空间**，只有估算器能看到
+ * 这一点（"这是常见口令"、"这是键盘序列"、"这像是日期"）。
+ *
+ * ## 三件事的边界
+ *
+ * | 事 | 本模块怎么做 |
+ * |---|---|
+ * | 强度估算 | `zxcvbn-ts` 评分 0..4 + 我们翻译成中文的理由（库默认返回 key，如 `topTen`；我们不引它的英文文案包，见下） |
+ * | 通过线 | 默认 `score >= 3`（SDK 方案原文；约 50+ bits 熵量级）**且**不在本地黑名单 |
+ * | 黑名单 | **纯本地、不联网**：复用 zxcvbn 自带的常见口令字典（`@zxcvbn-ts/language-common` 的 `passwords-common` 49233 条 + `diceware-common` 7776 条）＋ 一份小的应用相关词表（`APP_BLOCKLIST`），并支持 `extraBlocklist` 扩充 |
+ *
+ * **不做** HIBP 之类的联网查询：那是外部依赖，还会把口令哈希前缀发出去
+ * （SDK 方案 §3.3.6 明确排除）。
+ *
+ * ## 两个实现细节（都是坑）
+ *
+ * 1. **`userInputs` 里绝不能塞口令本身**。zxcvbn 会把 userInputs 当字典匹配，
+ *    如果口令自己进了字典，任何口令都会被判 0 分（"自证"式的假阴性）。
+ *    这里只塞黑名单词与应用相关词。
+ * 2. **超长口令不估算**。`tooLong` 直接不可接受并短路返回：估算器本身是
+ *    "把口令喂给一堆正则与字典"，超过上限的输入没有估算价值（上限 128 是
+ *    SDK 方案 §3.3.6 的防 DoS 条款）。
+ */
+/** 通过线：评分 ≥ 3（SDK 方案 §3.3.6） */
+export declare const ACCEPTABLE_SCORE = 3;
+/** 评分类型（zxcvbn 的 0..4） */
+export type PasswordScore = 0 | 1 | 2 | 3 | 4;
+/**
+ * 应用相关词表（"黑名单"的第二半）。
+ *
+ * 只放**公开的产品/域名/币种词**与占位示例域名 —— 这个仓库将来要开源，
+ * 不得出现真实内网地址、真实商户域名、任何密钥材料。
+ * 中文产品词也放几条：用户拿"私钥""助记词"当口令是真实存在的。
+ */
+export declare const APP_BLOCKLIST: readonly string[];
+export interface PasswordStrength {
+    /** zxcvbn 评分：0（极弱）.. 4（强） */
+    score: PasswordScore;
+    /** 中文理由（可展示给用户；去重保序，最强的那条在最前） */
+    reasons: string[];
+    /** 是否可接受 = 评分达标 && 未命中黑名单 && 未超长 */
+    acceptable: boolean;
+    /** 估算的可猜空间（log10 次猜测）；超长短路时为 null */
+    guessesLog10: number | null;
+    /** 命中本地黑名单（应用词表 / `extraBlocklist` 的精确或包含命中） */
+    blocklisted: boolean;
+    /** 超长（> 上限）：没有做估算，直接不可接受 */
+    tooLong: boolean;
+}
+export interface PasswordStrengthOptions {
+    /** 追加黑名单（精确命中或长度达标时的包含命中都会被判黑） */
+    extraBlocklist?: readonly string[];
+    /** 额外"用户输入"（用户名/邮箱/手机号等）—— 传给 zxcvbn 当字典，**不要传口令自身** */
+    userInputs?: readonly string[];
+    /** 通过线，默认 3 */
+    acceptableScore?: number;
+    /** 长度上限，默认 128 */
+    maxLength?: number;
+}
+/**
+ * 是否命中本地黑名单：**精确命中**（归一化后相等）或**包含命中**
+ * （黑名单词达到 {@link containmentThreshold} 且被归一化口令包含，
+ * 如 `trustbase2026`、`Trust-Base-2026`、`私钥123`）。
+ */
+export declare function isBlocklisted(password: string, extraBlocklist?: readonly string[]): boolean;
+/**
+ * 估算口令强度（SDK 方案 §3.3.6）。
+ *
+ * 不做任何"必须含 X"的规则；`acceptable` 只看三件事：评分 ≥ 通过线、
+ * 不在黑名单、长度在 `1..maxLength` 之内。
+ */
+export declare function estimatePasswordStrength(password: string, options?: PasswordStrengthOptions): PasswordStrength;
+//# sourceMappingURL=password.d.ts.map

package/dist/password.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"password.d.ts","sourceRoot":"","sources":["../src/password.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAOH,gCAAgC;AAChC,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,0BAA0B;AAC1B,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAe1C,CAAC;AAgBF,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,KAAK,EAAE,aAAa,CAAC;IACrB,iCAAiC;IACjC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oCAAoC;IACpC,UAAU,EAAE,OAAO,CAAC;IACpB,qCAAqC;IACrC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gDAAgD;IAChD,WAAW,EAAE,OAAO,CAAC;IACrB,4BAA4B;IAC5B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,wDAAwD;IACxD,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,eAAe;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAmFD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,GAAE,SAAS,MAAM,EAAO,GAAG,OAAO,CAW/F;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CA6DlB"}

package/dist/password.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * 口令强度估算（SDK 方案 §3.3.6）—— **用估算，不用复杂度规则**。
+ *
+ * ## 为什么不搞"必须含大小写数字符号"
+ *
+ * 规则只会逼出 `Password1!` 这种"看着合规、实际上榜"的口令：它满足所有规则，
+ * 却是攻击者字典里的第一批。真正决定成本的是**可猜空间**，只有估算器能看到
+ * 这一点（"这是常见口令"、"这是键盘序列"、"这像是日期"）。
+ *
+ * ## 三件事的边界
+ *
+ * | 事 | 本模块怎么做 |
+ * |---|---|
+ * | 强度估算 | `zxcvbn-ts` 评分 0..4 + 我们翻译成中文的理由（库默认返回 key，如 `topTen`；我们不引它的英文文案包，见下） |
+ * | 通过线 | 默认 `score >= 3`（SDK 方案原文；约 50+ bits 熵量级）**且**不在本地黑名单 |
+ * | 黑名单 | **纯本地、不联网**：复用 zxcvbn 自带的常见口令字典（`@zxcvbn-ts/language-common` 的 `passwords-common` 49233 条 + `diceware-common` 7776 条）＋ 一份小的应用相关词表（`APP_BLOCKLIST`），并支持 `extraBlocklist` 扩充 |
+ *
+ * **不做** HIBP 之类的联网查询：那是外部依赖，还会把口令哈希前缀发出去
+ * （SDK 方案 §3.3.6 明确排除）。
+ *
+ * ## 两个实现细节（都是坑）
+ *
+ * 1. **`userInputs` 里绝不能塞口令本身**。zxcvbn 会把 userInputs 当字典匹配，
+ *    如果口令自己进了字典，任何口令都会被判 0 分（"自证"式的假阴性）。
+ *    这里只塞黑名单词与应用相关词。
+ * 2. **超长口令不估算**。`tooLong` 直接不可接受并短路返回：估算器本身是
+ *    "把口令喂给一堆正则与字典"，超过上限的输入没有估算价值（上限 128 是
+ *    SDK 方案 §3.3.6 的防 DoS 条款）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APP_BLOCKLIST = exports.ACCEPTABLE_SCORE = void 0;
+exports.isBlocklisted = isBlocklisted;
+exports.estimatePasswordStrength = estimatePasswordStrength;
+const core_1 = require("@zxcvbn-ts/core");
+const language_common_1 = require("@zxcvbn-ts/language-common");
+const kdf_1 = require("./kdf");
+/** 通过线：评分 ≥ 3（SDK 方案 §3.3.6） */
+exports.ACCEPTABLE_SCORE = 3;
+/**
+ * 应用相关词表（"黑名单"的第二半）。
+ *
+ * 只放**公开的产品/域名/币种词**与占位示例域名 —— 这个仓库将来要开源，
+ * 不得出现真实内网地址、真实商户域名、任何密钥材料。
+ * 中文产品词也放几条：用户拿"私钥""助记词"当口令是真实存在的。
+ */
+exports.APP_BLOCKLIST = [
+    'trustbase',
+    'trustbase.com',
+    'trustchain',
+    'trustcoin',
+    'trust chain',
+    'trustbase wallet',
+    'tct',
+    'utct',
+    'shop.example.com',
+    'example.com',
+    '信任链',
+    '私钥',
+    '助记词',
+    '钱包',
+];
+/** 只有长度 ≥ 这个值的词才做"包含"判定（太短的词做包含判定会误伤，如 `tct`） */
+const CONTAINMENT_MIN_LENGTH = 5;
+/**
+ * 某个黑名单词做"包含"判定所需的最短长度。
+ *
+ * 拉丁字母的短串（`tct`）会自然地出现在随机口令里，做包含判定会误伤，
+ * 所以要求 ≥5 个字符；而 CJK 这类文字信息密度高，两个字就是一个完整词
+ * （`私钥`、`钱包`），做包含判定既不会误伤、又能挡住 `私钥123` 这种写法。
+ */
+function containmentThreshold(term) {
+    return /[^\u0000-\u007f]/u.test(term) ? 2 : CONTAINMENT_MIN_LENGTH;
+}
+/** 警告 key → 中文理由（zxcvbn 默认给的是 key，不是文案） */
+const WARNING_REASONS = {
+    straightRow: '这是键盘上相邻键位串（如 qwerty）',
+    keyPattern: '这是键盘图案（相邻键位组合）',
+    simpleRepeat: '这是重复的字符（如 aaaa）',
+    extendedRepeat: '这是重复的片段（如 abcabcabc）',
+    sequences: '这是连续序列（如 abcdef / 123456）',
+    recentYears: '这是近年份',
+    dates: '这像是日期',
+    topTen: '这是最常见的十个口令之一',
+    topHundred: '这是最常见的百个口令之一',
+    common: '这是常见口令',
+    similarToCommon: '与常见口令非常接近（只差一点改动）',
+    wordByItself: '这就是一个常见单词',
+    namesByThemselves: '这是常见人名',
+    commonNames: '这是常见姓名的组合',
+    userInputs: '包含应用名/产品名或你自己的信息',
+    pwned: '这个口令已出现在公开泄漏库里',
+};
+/** 匹配模式 → 中文理由（警告没覆盖到的结构，用这里补上） */
+const PATTERN_REASONS = {
+    dictionary: '包含常见口令 / 常见词（字典命中）',
+    spatial: '这是键盘上相邻键位的组合',
+    repeat: '这是重复的字符或片段',
+    sequence: '这是连续序列（如 abcd / 1234）',
+    date: '这像是日期',
+    regex: '这像是年份或成串的数字',
+    wordSequence: '这是常见词的顺序组合',
+    separator: '这是用分隔符拼起来的常见词',
+    userInputs: '包含应用名/产品名或你自己的信息',
+};
+/** 某条警告已经说明了哪些模式（避免同一个理由说两遍） */
+const WARNING_COVERS = {
+    straightRow: ['spatial'],
+    keyPattern: ['spatial'],
+    simpleRepeat: ['repeat'],
+    extendedRepeat: ['repeat'],
+    sequences: ['sequence'],
+    recentYears: ['regex', 'date'],
+    dates: ['date', 'regex', 'sequence'],
+    topTen: ['dictionary'],
+    topHundred: ['dictionary'],
+    common: ['dictionary'],
+    similarToCommon: ['dictionary'],
+    wordByItself: ['dictionary'],
+    namesByThemselves: ['dictionary'],
+    commonNames: ['dictionary', 'wordSequence'],
+    userInputs: ['dictionary', 'userInputs'],
+};
+/** 不产生理由的模式：`bruteforce` 是"没识别出结构"的兜底，不是缺点 */
+const IGNORED_PATTERNS = ['bruteforce'];
+let engine = null;
+/**
+ * 惰性构造估算器（字典很大，构造一次约几十毫秒；模块顶层不做事，
+ * 保持"零副作用导入"）。
+ */
+function getEngine(maxLength) {
+    if (engine === null) {
+        engine = new core_1.ZxcvbnFactory({
+            dictionary: language_common_1.dictionary,
+            graphs: language_common_1.adjacencyGraphs,
+            // 上限与我们的口令长度上限一致：超长输入根本不该进估算器
+            maxLength,
+        });
+    }
+    return engine;
+}
+/** 归一化：小写 + 去掉非字母数字 + NFC（黑名单比对与"包含"判定都走它） */
+function normalizeForBlocklist(value) {
+    return value
+        .normalize('NFC')
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, '');
+}
+/**
+ * 是否命中本地黑名单：**精确命中**（归一化后相等）或**包含命中**
+ * （黑名单词达到 {@link containmentThreshold} 且被归一化口令包含，
+ * 如 `trustbase2026`、`Trust-Base-2026`、`私钥123`）。
+ */
+function isBlocklisted(password, extraBlocklist = []) {
+    if (typeof password !== 'string' || password.length === 0)
+        return false;
+    const normalized = normalizeForBlocklist(password);
+    if (normalized.length === 0)
+        return false;
+    for (const term of [...exports.APP_BLOCKLIST, ...extraBlocklist]) {
+        const candidate = normalizeForBlocklist(term);
+        if (candidate.length === 0)
+            continue;
+        if (normalized === candidate)
+            return true;
+        if (candidate.length >= containmentThreshold(candidate) && normalized.includes(candidate))
+            return true;
+    }
+    return false;
+}
+/**
+ * 估算口令强度（SDK 方案 §3.3.6）。
+ *
+ * 不做任何"必须含 X"的规则；`acceptable` 只看三件事：评分 ≥ 通过线、
+ * 不在黑名单、长度在 `1..maxLength` 之内。
+ */
+function estimatePasswordStrength(password, options = {}) {
+    const maxLength = options.maxLength ?? kdf_1.MAX_PASSWORD_LENGTH;
+    const acceptableScore = options.acceptableScore ?? exports.ACCEPTABLE_SCORE;
+    if (typeof password !== 'string' || password.length === 0) {
+        return {
+            score: 0,
+            reasons: ['口令为空'],
+            acceptable: false,
+            guessesLog10: null,
+            blocklisted: false,
+            tooLong: false,
+        };
+    }
+    if (password.length > maxLength) {
+        return {
+            score: 0,
+            reasons: [`口令长度超过上限 ${maxLength} 个字符（上限是防 DoS 用的，不是强度要求）`],
+            acceptable: false,
+            guessesLog10: null,
+            blocklisted: false,
+            tooLong: true,
+        };
+    }
+    const blocklist = [...exports.APP_BLOCKLIST, ...(options.extraBlocklist ?? [])];
+    const userInputs = [...blocklist, ...(options.userInputs ?? [])];
+    const result = getEngine(maxLength).check(password, userInputs);
+    const blocklisted = isBlocklisted(password, options.extraBlocklist ?? []);
+    const reasons = [];
+    const warning = result.feedback.warning;
+    if (typeof warning === 'string' && warning.length > 0) {
+        reasons.push(WARNING_REASONS[warning] ?? '这是可预测的口令模式');
+    }
+    const covered = new Set(warning ? (WARNING_COVERS[warning] ?? []) : []);
+    const patterns = [];
+    for (const match of result.sequence) {
+        if (!patterns.includes(match.pattern))
+            patterns.push(match.pattern);
+    }
+    for (const pattern of patterns) {
+        if (IGNORED_PATTERNS.includes(pattern) || covered.has(pattern))
+            continue;
+        const reason = PATTERN_REASONS[pattern];
+        if (reason && !reasons.includes(reason))
+            reasons.push(reason);
+    }
+    if (blocklisted) {
+        reasons.push('包含应用名/产品名/示例域名等本地黑名单词');
+    }
+    if (reasons.length === 0 && result.score < acceptableScore) {
+        reasons.push(`可猜空间偏小（估算约需 10^${result.guessesLog10.toFixed(1)} 次尝试）`);
+    }
+    return {
+        score: result.score,
+        reasons,
+        acceptable: result.score >= acceptableScore && !blocklisted,
+        guessesLog10: result.guessesLog10,
+        blocklisted,
+        tooLong: false,
+    };
+}
+//# sourceMappingURL=password.js.map

package/dist/password.js.map

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

package/dist/prf-webauthn.d.ts

@@ -0,0 +1,85 @@
+/**
+ * WebAuthn PRF 适配器 —— ⚠️ **骨架，未在 Node 单测覆盖，必须在真机浏览器验证**。
+ *
+ * ## 这个文件为什么不能靠单测放心
+ *
+ * `navigator.credentials` 在 Node 里不存在，认证器的 PRF 输出又依赖具体平台
+ * 实现（iOS Safari / Android Chrome / 桌面浏览器并不一致）。所以：
+ *
+ * - 本文件**没有任何 Node 测试覆盖它的成功路径**；单测只覆盖"没有 WebAuthn 时
+ *   应当优雅降级"这一支（`isWebAuthnPrfSupported()` 返回 false、
+ *   `getPrfSecret()` 抛 `PRF_UNAVAILABLE`）
+ * - 真机验证清单写在包 README「未验证清单」里；**上生产前必须走一遍真机**
+ * - 本文件刻意不开 DOM lib（本包只开 `lib: ["ES2022"]`，见 webcrypto.ts 文件头），
+ *   所以下面是本文件需要的几个最小声明，参数对象是普通字面量。**不要把这里
+ *   当成"类型已经保证正确"的代码**
+ *
+ * ## 流程要点（照 WebAuthn PRF 扩展的规范与各平台现状写）
+ *
+ * 1. **注册**：`create()` 时带 `extensions.prf.eval.first = salt`。
+ *    ⚠️ 很多平台在 `create()` 的返回值里**不给** `prf.results`（只给
+ *    `prf.enabled`），所以正确做法是注册后**立刻再 `get()` 一次断言**去取
+ *    `results.first` —— 本文件的 `registerWebAuthnPrfCredential()` 就是这么做的。
+ * 2. **解锁**：`get()` 时带 `extensions.prf.eval.first = salt`（或
+ *    `evalByCredential`），`allowCredentials` 里放凭据的 **rawId 字节**。
+ * 3. **salt 必须与注册时一致**，否则认证器按不同 salt 给不同秘密（这是 PRF 的
+ *    定义）。所以 salt 存在我们的包装 blob 里（见 prf.ts 的 `salt` 字段）。
+ * 4. **换设备/重装/重置生物识别 → 秘密就变了**（或凭据没了）→ 认证失败 →
+ *    回退口令或助记词。这是设计内行为，不是 bug（SDK 方案 §3.3.7 第 2 条）。
+ */
+import { type PrfProvider } from './prf';
+export interface WebAuthnPrfProviderOptions {
+    /**
+     * RP ID（依赖方标识）。默认用当前页面 origin 的主机名 —— 传错会导致
+     * "凭据属于另一个 RP"从而断言失败，所以除非明确知道为什么，不要传。
+     */
+    rpId?: string;
+    /** 认证器超时（毫秒），默认 60000 */
+    timeoutMs?: number;
+    /** 是否要求用户验证（生物识别/PIN），默认 `'required'`（硬件门控就是这个功能的意义） */
+    userVerification?: 'required' | 'preferred' | 'discouraged';
+}
+/**
+ * 这台设备/这个浏览器有没有可用的 WebAuthn 平台认证器（**只探测，不弹窗**）。
+ *
+ * 返回 false 的情况包括：Node 环境、非安全上下文（http 非 localhost）、
+ * 桌面浏览器没有平台认证器、隐私模式等。调用方据此选择"口令轨"。
+ */
+export declare function isWebAuthnPrfSupported(): Promise<boolean>;
+/** base64url → 字节（WebAuthn 的凭据 ID 是 base64url，不带填充） */
+export declare function base64UrlToBytes(value: string): Uint8Array;
+/** 字节 → base64url（无填充），用于把凭据 ID 交给下游 */
+export declare function bytesToBase64Url(bytes: Uint8Array): string;
+export interface RegisterWebAuthnPrfOptions extends WebAuthnPrfProviderOptions {
+    /** 展示给用户的账户名（如 `tct1…` 或用户名；userName 不能是空串） */
+    userName: string;
+    /** 展示名（可选） */
+    userDisplayName?: string;
+    /** PRF salt —— **必须与将来解锁时用的那一份相同**（存进 prf.ts 的包装里） */
+    salt: Uint8Array;
+}
+export interface RegisteredWebAuthnPrfCredential {
+    /** base64url 凭据 ID（存进我们的设备记录里） */
+    credentialId: string;
+    /** 注册后立刻断言取回的 PRF 秘密（32 字节；调用方用完必须 `wipe()`） */
+    prfSecret: Uint8Array;
+    /** 凭据创建时的 `prf.enabled` 标记（仅供参考，不能当作"拿到了秘密"） */
+    prfEnabled: boolean;
+}
+/**
+ * 注册一个 PRF 凭据并取回它的秘密。
+ *
+ * ⚠️ 会产生**真实的 WebAuthn 弹窗**（生物识别/PIN）。Node 里调用会抛
+ * `PRF_UNAVAILABLE`。真机验证前不要在生产流程里打开它。
+ */
+export declare function registerWebAuthnPrfCredential(options: RegisterWebAuthnPrfOptions): Promise<RegisteredWebAuthnPrfCredential>;
+/**
+ * 浏览器 PRF 提供方（可注入给 `envelope.attachPrfTrack()` 与解锁流程）。
+ *
+ * ⚠️ 未在 Node 单测覆盖（见文件头）。它做的唯一一件事是：
+ * 触发一次生物识别授权，把认证器给的 PRF 秘密取回来。
+ */
+export declare function createWebAuthnPrfProvider(options?: WebAuthnPrfProviderOptions): PrfProvider;
+/** 给调用方一个"用完清掉秘密"的显式动作（成功路径与失败路径都要走） */
+export declare function wipePrfSecret(secret: Uint8Array | null | undefined): void;
+//# sourceMappingURL=prf-webauthn.d.ts.map

package/dist/prf-webauthn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prf-webauthn.d.ts","sourceRoot":"","sources":["../src/prf-webauthn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,OAAO,CAAC;AA8B5D,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,aAAa,CAAC;CAC7D;AAQD;;;;;GAKG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,OAAO,CAAC,CAW/D;AAED,uDAAuD;AACvD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAM1D;AAED,wCAAwC;AACxC,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAE1D;AA0BD,MAAM,WAAW,0BAA2B,SAAQ,0BAA0B;IAC5E,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,+BAA+B;IAC9C,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,SAAS,EAAE,UAAU,CAAC;IACtB,gDAAgD;IAChD,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,+BAA+B,CAAC,CA0D1C;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,0BAA+B,GAAG,WAAW,CAmC/F;AAED,wCAAwC;AACxC,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAEzE"}