@trustbaseai/account 0.1.0

package/dist/prf-webauthn.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * 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 条）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWebAuthnPrfSupported = isWebAuthnPrfSupported;
+exports.base64UrlToBytes = base64UrlToBytes;
+exports.bytesToBase64Url = bytesToBase64Url;
+exports.registerWebAuthnPrfCredential = registerWebAuthnPrfCredential;
+exports.createWebAuthnPrfProvider = createWebAuthnPrfProvider;
+exports.wipePrfSecret = wipePrfSecret;
+const bytes_1 = require("./bytes");
+const errors_1 = require("./errors");
+const prf_1 = require("./prf");
+const webcrypto_1 = require("./webcrypto");
+function webAuthn() {
+    const nav = globalThis.navigator;
+    if (!nav || typeof nav !== 'object')
+        return undefined;
+    return nav;
+}
+/**
+ * 这台设备/这个浏览器有没有可用的 WebAuthn 平台认证器（**只探测，不弹窗**）。
+ *
+ * 返回 false 的情况包括：Node 环境、非安全上下文（http 非 localhost）、
+ * 桌面浏览器没有平台认证器、隐私模式等。调用方据此选择"口令轨"。
+ */
+async function isWebAuthnPrfSupported() {
+    const api = webAuthn();
+    if (!api || typeof api.credentials?.create !== 'function' || typeof api.credentials.get !== 'function') {
+        return false;
+    }
+    if (typeof api.isUserVerifyingPlatformAuthenticatorAvailable !== 'function')
+        return false;
+    try {
+        return await api.isUserVerifyingPlatformAuthenticatorAvailable();
+    }
+    catch {
+        return false;
+    }
+}
+/** base64url → 字节（WebAuthn 的凭据 ID 是 base64url，不带填充） */
+function base64UrlToBytes(value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', 'base64url 输入必须是非空字符串');
+    }
+    const standard = value.replace(/-/gu, '+').replace(/_/gu, '/');
+    return (0, bytes_1.base64Decode)(standard);
+}
+/** 字节 → base64url（无填充），用于把凭据 ID 交给下游 */
+function bytesToBase64Url(bytes) {
+    return (0, bytes_1.base64Encode)(bytes).replace(/\+/gu, '-').replace(/\//gu, '_').replace(/=+$/u, '');
+}
+function toUint8(value) {
+    if (!value)
+        return null;
+    return value instanceof Uint8Array ? Uint8Array.from(value) : new Uint8Array(value);
+}
+function extractPrfSecret(credential, context) {
+    const results = credential.getClientExtensionResults?.().prf;
+    const first = toUint8(results?.results?.first);
+    if (!first) {
+        throw new errors_1.AccountError('PRF_UNAVAILABLE', `${context}：认证器没有返回 PRF 输出（results.first 缺失）。` +
+            '可能是该平台不支持 PRF 扩展，或需要在断言时用 evalByCredential 指定凭据。');
+    }
+    if (first.length !== prf_1.PRF_SECRET_LENGTH) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', `${context}：认证器返回的 PRF 输出是 ${first.length} 字节（本实现按 ${prf_1.PRF_SECRET_LENGTH} 字节设计）`);
+    }
+    return first;
+}
+/**
+ * 注册一个 PRF 凭据并取回它的秘密。
+ *
+ * ⚠️ 会产生**真实的 WebAuthn 弹窗**（生物识别/PIN）。Node 里调用会抛
+ * `PRF_UNAVAILABLE`。真机验证前不要在生产流程里打开它。
+ */
+async function registerWebAuthnPrfCredential(options) {
+    const api = webAuthn();
+    if (!api || typeof api.credentials?.create !== 'function' || typeof api.credentials.get !== 'function') {
+        throw new errors_1.AccountError('PRF_UNAVAILABLE', '本环境没有 WebAuthn（navigator.credentials）—— 无法注册生物识别解锁');
+    }
+    if (!options.userName) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', 'userName 不能为空');
+    }
+    if (!(options.salt instanceof Uint8Array) || options.salt.length === 0) {
+        throw new errors_1.AccountError('INVALID_ARGUMENT', 'salt 不能为空');
+    }
+    const timeout = options.timeoutMs ?? 60_000;
+    const userVerification = options.userVerification ?? 'required';
+    const rpId = options.rpId;
+    const created = (await api.credentials.create({
+        publicKey: {
+            ...(rpId ? { rp: { id: rpId, name: 'TrustBase' } } : { rp: { name: 'TrustBase' } }),
+            user: {
+                // user.id 必须是随机的、不可猜测的字节串（规范要求 ≥ 16 字节）；这里用 salt 派生
+                id: options.salt,
+                name: options.userName,
+                displayName: options.userDisplayName ?? options.userName,
+            },
+            pubKeyCredParams: [
+                { type: 'public-key', alg: -7 }, // ES256（P-256）：平台认证器的通用算法
+                { type: 'public-key', alg: -257 }, // RS256（兜底）
+            ],
+            authenticatorSelection: { userVerification, residentKey: 'preferred' },
+            timeout,
+            attestation: 'none',
+            // 关键：注册时就要求评估 PRF（部分平台只在注册时把 PRF 绑到凭据上）
+            extensions: { prf: { eval: { first: options.salt } } },
+        },
+    }));
+    if (!created || typeof created.id !== 'string' || created.id.length === 0) {
+        throw new errors_1.AccountError('PRF_UNAVAILABLE', '注册未返回凭据（用户取消或认证器拒绝）');
+    }
+    const enabled = created.getClientExtensionResults?.().prf?.enabled === true;
+    // 很多平台在 create() 的返回值里不给 results，所以立刻做一次断言去取。
+    const asserted = (await api.credentials.get({
+        publicKey: {
+            ...(rpId ? { rpId } : {}),
+            challenge: (0, webcrypto_1.randomBytes)(32),
+            allowCredentials: [{ type: 'public-key', id: base64UrlToBytes(created.id) }],
+            userVerification,
+            timeout,
+            extensions: { prf: { eval: { first: options.salt } } },
+        },
+    }));
+    if (!asserted) {
+        throw new errors_1.AccountError('PRF_UNAVAILABLE', '注册后的断言未返回（用户取消或认证器拒绝）');
+    }
+    const prfSecret = extractPrfSecret(asserted, '注册后断言');
+    return { credentialId: asserted.id ?? created.id, prfSecret, prfEnabled: enabled };
+}
+/**
+ * 浏览器 PRF 提供方（可注入给 `envelope.attachPrfTrack()` 与解锁流程）。
+ *
+ * ⚠️ 未在 Node 单测覆盖（见文件头）。它做的唯一一件事是：
+ * 触发一次生物识别授权，把认证器给的 PRF 秘密取回来。
+ */
+function createWebAuthnPrfProvider(options = {}) {
+    const timeout = options.timeoutMs ?? 60_000;
+    const userVerification = options.userVerification ?? 'required';
+    return {
+        kind: 'webauthn',
+        async isAvailable() {
+            return isWebAuthnPrfSupported();
+        },
+        async getPrfSecret(credentialId, salt) {
+            const api = webAuthn();
+            if (!api || typeof api.credentials?.get !== 'function') {
+                throw new errors_1.AccountError('PRF_UNAVAILABLE', '本环境没有 WebAuthn（navigator.credentials.get）');
+            }
+            if (typeof credentialId !== 'string' || credentialId.length === 0) {
+                throw new errors_1.AccountError('INVALID_ARGUMENT', 'credentialId 不能为空');
+            }
+            if (!(salt instanceof Uint8Array) || salt.length === 0) {
+                throw new errors_1.AccountError('INVALID_ARGUMENT', 'salt 不能为空');
+            }
+            const assertion = (await api.credentials.get({
+                publicKey: {
+                    ...(options.rpId ? { rpId: options.rpId } : {}),
+                    challenge: (0, webcrypto_1.randomBytes)(32),
+                    allowCredentials: [{ type: 'public-key', id: base64UrlToBytes(credentialId) }],
+                    userVerification,
+                    timeout,
+                    extensions: { prf: { eval: { first: salt } } },
+                },
+            }));
+            if (!assertion) {
+                throw new errors_1.AccountError('PRF_UNAVAILABLE', '断言未返回（用户取消或认证器拒绝）');
+            }
+            return extractPrfSecret(assertion, '断言');
+        },
+    };
+}
+/** 给调用方一个"用完清掉秘密"的显式动作（成功路径与失败路径都要走） */
+function wipePrfSecret(secret) {
+    (0, bytes_1.wipe)(secret);
+}
+//# sourceMappingURL=prf-webauthn.js.map

package/dist/prf-webauthn.js.map

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

package/dist/prf.d.ts

@@ -0,0 +1,157 @@
+/**
+ * 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 单测覆盖**，必须在真机浏览器验证 —— 那里写得很明确，别混。
+ */
+/** 包装格式版本 */
+export declare const PRF_WRAP_VERSION = 1;
+/** HKDF 的 info：域分隔串（带版本；换格式必须换它，否则新旧包会互相解开对方的东西） */
+export declare const PRF_WRAP_INFO = "trustbase/prf-wrap/v1";
+/** AAD 前缀（版本化） */
+export declare const PRF_WRAP_AAD_PREFIX = "trustbase-prf-wrap-v1";
+/** HKDF-SHA256 在 WebAuthn PRF 下的典型输出长度（认证器返回 32 字节） */
+export declare const PRF_SECRET_LENGTH = 32;
+/** 可接受的 PRF 秘密长度区间（给非标准认证器留余量，但拒绝明显不对的输入） */
+export declare const PRF_SECRET_MIN_LENGTH = 16;
+export declare const PRF_SECRET_MAX_LENGTH = 64;
+/** HKDF salt 长度区间；默认 16 字节随机 */
+export declare const PRF_SALT_MIN_LENGTH = 8;
+export declare const PRF_SALT_MAX_LENGTH = 64;
+export declare const PRF_SALT_DEFAULT_LENGTH = 16;
+/** 唯一支持的对称加密 */
+export declare const PRF_WRAP_CIPHER = "aes-256-gcm";
+/** 唯一支持的 KDF */
+export declare const PRF_WRAP_KDF = "hkdf-sha256";
+/** 解锁策略：生物识别（PRF）优先，口令回退 —— 两条路解出**同一份**密钥材料 */
+export type UnlockStrategy = 'prf' | 'password';
+export interface PrfWrappedKey {
+    version: typeof PRF_WRAP_VERSION;
+    kdf: typeof PRF_WRAP_KDF;
+    /** WebAuthn 凭据 ID（base64url；`-`/`_` 是合法字符） */
+    credentialId: string;
+    /** HKDF 的 salt（base64）；同时参与 AAD */
+    salt: string;
+    /** HKDF 的 info（域分隔串） */
+    info: string;
+    cipher: typeof PRF_WRAP_CIPHER;
+    /** IV（base64，12 字节） */
+    iv: string;
+    ciphertext: string;
+    tag: string;
+}
+/**
+ * PRF 秘密的提供方。**接口是给浏览器适配器与测试假实现共用的**：
+ * 一个真实现（prf-webauthn.ts）与一个假实现（`createStaticPrfProvider`）。
+ */
+export interface PrfProvider {
+    /** 标明实现来源，便于日志与排查（如 `'webauthn'` / `'static'`） */
+    readonly kind: string;
+    /** 这台设备/这个浏览器**是否具备** PRF 能力（只探测，不应弹任何 UI） */
+    isAvailable(): Promise<boolean>;
+    /**
+     * 取回某个凭据下、给定 salt 的 PRF 秘密。
+     * 真实现会在这里触发生物识别/PIN 授权；用户取消/失败应当抛错（不要返回全 0）。
+     */
+    getPrfSecret(credentialId: string, salt: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * HKDF-SHA256：`PRF 秘密 → 32 字节 KEK`（RFC 5869）。
+ *
+ * 用 `@noble/hashes/hkdf` 而不是 WebCrypto 的 HKDF：这条路径必须**确定性可复算**
+ * （`test/prf.test.ts` 里用 RFC 5869 的公开向量与 `node:crypto.hkdfSync` 双侧对照），
+ * 而且 PRF 本身已经是硬件门控的，不差平台这一道。
+ */
+export declare function derivePrfKek(prfSecret: Uint8Array, salt: Uint8Array, info?: string): Uint8Array;
+/** 被包的头的 AAD 文本（格式见文件头；由测试用字面量钉住） */
+export declare function prfWrapAadText(wrapped: Pick<PrfWrappedKey, 'kdf' | 'credentialId' | 'info' | 'salt' | 'cipher' | 'iv'>): string;
+export interface WrapKeyWithPrfOptions {
+    /** WebAuthn 凭据 ID（注册时拿到的那串 base64url） */
+    credentialId: string;
+    /**
+     * HKDF salt。**生产环境应当传注册时用的同一份 salt**（它是"这份包装属于
+     * 哪个凭据/哪台设备"的一部分）；不传则随机生成一份并写进 blob。
+     */
+    salt?: Uint8Array;
+    /** HKDF info（默认 `trustbase/prf-wrap/v1`）；跨应用/跨用途要区分时传不同的值 */
+    info?: string;
+}
+/**
+ * 用 PRF 秘密包住密钥材料（通常是账户的数据密钥 DEK）。
+ *
+ * **不修改 `keyMaterial`**（调用方的缓冲区）；内部 KEK 在返回前清零。
+ */
+export declare function wrapKeyWithPrf(prfSecret: Uint8Array, keyMaterial: Uint8Array, options: WrapKeyWithPrfOptions): Promise<PrfWrappedKey>;
+/**
+ * 用 PRF 秘密拆开包装，拿回密钥材料。
+ *
+ * PRF 秘密不对（换设备、重装、凭据被删）→ `AUTH_FAILED`，
+ * 与"口令错"同一句话：调用方应当据此提示"用口令或助记词解锁"。
+ */
+export declare function unwrapKeyWithPrf(wrapped: PrfWrappedKey | string, prfSecret: Uint8Array): Promise<Uint8Array>;
+/** 校验并归一化一份 PRF 包装（接受对象或 JSON 字符串）；不合法抛 `INVALID_BLOB` 等 */
+export declare function parsePrfWrappedKey(value: PrfWrappedKey | string | unknown): PrfWrappedKey;
+/** 只问"能不能当 PRF 包装用"，不抛异常 */
+export declare function isPrfWrappedKey(value: unknown): value is PrfWrappedKey;
+/** 序列化（字段顺序固定，便于跨端逐字节比对） */
+export declare function serializePrfWrappedKey(wrapped: PrfWrappedKey): string;
+/**
+ * 用固定秘密伪造一个 `PrfProvider`。
+ *
+ * ⚠️ **仅供测试与本地开发**：它没有任何硬件保护、不要求生物识别，秘密就在
+ * 进程内存里。生产环境必须用 prf-webauthn.ts 的真适配器（或原生侧的对应实现）。
+ * 之所以放在 src 而不是 test：它是"接口可注入"这条设计的证明，
+ * 也让上层（PWA 的降级路径、CLI 的自动化）有一个明确的替身可用。
+ */
+export declare function createStaticPrfProvider(secret: Uint8Array, options?: {
+    available?: boolean;
+    kind?: string;
+}): PrfProvider;
+/** 常数时间比对两份 PRF 秘密（给适配器做"秘密是否变化"自检用） */
+export declare function isSameSecret(a: Uint8Array, b: Uint8Array): boolean;
+//# sourceMappingURL=prf.d.ts.map

package/dist/prf.d.ts.map

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