@agentunion/fastaun-browser 0.5.3 → 0.5.6

package/dist/keystore/indexeddb.js

@@ -1,2031 +0,0 @@
-// ── IndexedDB KeyStore 实现 ──────────────────────────────
-import { pemToArrayBuffer } from '../crypto.js';
-import { normalizeInstanceId, slotIsolationKey } from '../config.js';
-const _noopLog = { error: () => { }, warn: () => { }, info: () => { }, debug: () => { } };
-import { isJsonObject, } from '../types.js';
-/** AID 安全化（替换路径分隔符） */
-function safeAid(aid) {
-    return aid.replace(/[/\\:]/g, '_');
-}
-/** 从 cert PEM 中提取 SPKI 公钥的 base64（纯 ASN.1 DER 解析，浏览器兼容） */
-function extractSpkiB64FromCertPem(certPem) {
-    try {
-        const der = new Uint8Array(pemToArrayBuffer(certPem));
-        // 最小 ASN.1 TLV 读取
-        const tlv = (d, o) => {
-            let lo = o + 1, len;
-            if (d[lo] & 0x80) {
-                const n = d[lo] & 0x7f;
-                len = 0;
-                for (let i = 0; i < n; i++)
-                    len = (len << 8) | d[lo + 1 + i];
-                lo += 1 + n;
-            }
-            else {
-                len = d[lo];
-                lo += 1;
-            }
-            return [lo, len]; // [valueStart, valueLen]
-        };
-        const skip = (d, o) => { const [vs, vl] = tlv(d, o); return vs + vl; };
-        // Certificate → SEQUENCE
-        let [vs] = tlv(der, 0);
-        // TBSCertificate → SEQUENCE
-        let pos = vs;
-        const [tbsVs] = tlv(der, pos);
-        pos = tbsVs;
-        // version [0] EXPLICIT (optional)
-        if (der[pos] === 0xa0)
-            pos = skip(der, pos);
-        // serialNumber, signatureAlgorithm, issuer, validity, subject — 跳过 5 个字段
-        for (let i = 0; i < 5; i++)
-            pos = skip(der, pos);
-        // SubjectPublicKeyInfo — 就是当前位置
-        const spkiEnd = skip(der, pos);
-        const spkiBytes = der.slice(pos, spkiEnd);
-        // base64 编码
-        let b = '';
-        for (let i = 0; i < spkiBytes.length; i++)
-            b += String.fromCharCode(spkiBytes[i]);
-        return btoa(b);
-    }
-    catch {
-        return '';
-    }
-}
-function encodePart(value) {
-    return encodeURIComponent(value);
-}
-function deepClone(value) {
-    return JSON.parse(JSON.stringify(value));
-}
-function isRecord(value) {
-    return isJsonObject(value);
-}
-function toBufferSource(bytes) {
-    return bytes.slice().buffer;
-}
-function sameJson(a, b) {
-    return JSON.stringify(a) === JSON.stringify(b);
-}
-// ── 私钥字段级加密 (AES-256-GCM + PBKDF2) ──────────────
-const _ENC_ALGO = 'AES-GCM';
-const _PBKDF2_ITERATIONS = 100_000;
-export class SeedMigrationError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'SeedMigrationError';
-    }
-}
-/** 将 Uint8Array 编码为 base64 字符串 */
-function _uint8ToBase64(bytes) {
-    let b = '';
-    for (let i = 0; i < bytes.length; i++)
-        b += String.fromCharCode(bytes[i]);
-    return btoa(b);
-}
-/** 将 base64 字符串解码为 Uint8Array */
-function _base64ToUint8(b64) {
-    return Uint8Array.from(atob(b64), c => c.charCodeAt(0));
-}
-/** 从 seed 派生 AES-256 加密密钥 */
-async function _deriveEncKey(seed, salt) {
-    const raw = new TextEncoder().encode(seed);
-    const base = await crypto.subtle.importKey('raw', raw, 'PBKDF2', false, ['deriveKey']);
-    return crypto.subtle.deriveKey({ name: 'PBKDF2', salt: salt, iterations: _PBKDF2_ITERATIONS, hash: 'SHA-256' }, base, { name: _ENC_ALGO, length: 256 }, false, ['encrypt', 'decrypt']);
-}
-/** 加密 PEM 字符串，返回加密信封 */
-async function _encryptPEM(pem, seed) {
-    const salt = crypto.getRandomValues(new Uint8Array(16));
-    const iv = crypto.getRandomValues(new Uint8Array(12));
-    const key = await _deriveEncKey(seed, salt);
-    const ct = await crypto.subtle.encrypt({ name: _ENC_ALGO, iv: iv }, key, new TextEncoder().encode(pem));
-    return {
-        ct: _uint8ToBase64(new Uint8Array(ct)),
-        iv: _uint8ToBase64(iv),
-        salt: _uint8ToBase64(salt),
-    };
-}
-/** 解密加密信封，还原 PEM 字符串 */
-async function _decryptPEM(enc, seed) {
-    const salt = _base64ToUint8(enc.salt);
-    const iv = _base64ToUint8(enc.iv);
-    const ct = _base64ToUint8(enc.ct);
-    const key = await _deriveEncKey(seed, salt);
-    const pt = await crypto.subtle.decrypt({ name: _ENC_ALGO, iv: toBufferSource(iv) }, key, toBufferSource(ct));
-    return new TextDecoder().decode(pt);
-}
-function hasEncryptionSeed(seed) {
-    return seed !== undefined;
-}
-// ── IndexedDB 工具 ──────────────────────────────────────
-const DB_NAME = 'aun-keystore';
-const DB_VERSION = 7;
-/** 对象仓库名称 */
-const STORE_KEY_PAIRS = 'key_pairs';
-const STORE_CERTS = 'certs';
-const STORE_METADATA = 'metadata';
-const STORE_INSTANCE_STATE = 'instance_state';
-const STORE_PREKEYS = 'prekeys';
-const STORE_GROUP_CURRENT = 'group_current';
-const STORE_GROUP_OLD_EPOCHS = 'group_old_epochs';
-const STORE_SESSIONS = 'e2ee_sessions';
-const STORE_GROUP_STATE = 'group_state';
-const STORE_AGENT_MD_CACHE = 'agent_md_cache';
-const STORE_PENDING_IDENTITIES = 'pending_identities';
-const STRUCTURED_RECOVERY_RETENTION_MS = 7 * 24 * 3600 * 1000;
-const CRITICAL_METADATA_KEYS = [];
-function metadataStoreKey(aid) {
-    return safeAid(aid);
-}
-function randomHex(byteLength) {
-    const bytes = crypto.getRandomValues(new Uint8Array(byteLength));
-    return Array.from(bytes).map((b) => b.toString(16).padStart(2, '0')).join('');
-}
-function pendingIdentityPrefix(aid) {
-    return `${safeAid(aid)}-`;
-}
-function normalizeCertFingerprint(certFingerprint) {
-    const normalized = String(certFingerprint ?? '').trim().toLowerCase();
-    if (!normalized)
-        return '';
-    if (!normalized.startsWith('sha256:'))
-        return '';
-    const hexPart = normalized.slice(7);
-    if (hexPart.length !== 64 || /[^0-9a-f]/.test(hexPart))
-        return '';
-    return normalized;
-}
-async function fingerprintFromCertPem(certPem) {
-    try {
-        const der = pemToArrayBuffer(certPem);
-        const hash = await crypto.subtle.digest('SHA-256', der);
-        const hex = Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, '0')).join('');
-        return `sha256:${hex}`;
-    }
-    catch {
-        return '';
-    }
-}
-function certStoreKey(aid, certFingerprint) {
-    const normalized = normalizeCertFingerprint(certFingerprint);
-    if (!normalized)
-        return safeAid(aid);
-    return `${safeAid(aid)}|${encodePart(normalized)}`;
-}
-function instanceStateStoreKey(aid, deviceId, slotId = '') {
-    const normalizedDevice = normalizeInstanceId(deviceId, 'device_id');
-    const slotKey = slotIsolationKey(slotId) || '_singleton';
-    return `${safeAid(aid)}|${encodePart(normalizedDevice)}|${encodePart(slotKey)}`;
-}
-function prekeyPrefix(aid) {
-    return `${safeAid(aid)}|`;
-}
-function prekeyStoreKey(aid, prekeyId, deviceId = '') {
-    const normalizedDeviceId = String(deviceId ?? '').trim();
-    if (!normalizedDeviceId) {
-        return `${safeAid(aid)}|${encodePart(prekeyId)}`;
-    }
-    return `${safeAid(aid)}|${encodePart(normalizedDeviceId)}|${encodePart(prekeyId)}`;
-}
-function groupCurrentPrefix(aid) {
-    return `${safeAid(aid)}|`;
-}
-function groupCurrentStoreKey(aid, groupId) {
-    return `${safeAid(aid)}|${encodePart(groupId)}`;
-}
-function groupOldPrefix(aid, groupId) {
-    const base = `${safeAid(aid)}|`;
-    if (groupId === undefined)
-        return base;
-    return `${base}${encodePart(groupId)}|`;
-}
-function groupOldStoreKey(aid, groupId, epoch) {
-    return `${safeAid(aid)}|${encodePart(groupId)}|${epoch}`;
-}
-function sessionPrefix(aid) {
-    return `${safeAid(aid)}|`;
-}
-function sessionStoreKey(aid, sessionId) {
-    return `${safeAid(aid)}|${encodePart(sessionId)}`;
-}
-function seqTrackerPrefix(aid, deviceId, slotId) {
-    const normalizedDevice = normalizeInstanceId(deviceId, 'device_id');
-    const slotKey = slotIsolationKey(slotId) || '_singleton';
-    return `_seq_|${safeAid(aid)}|${encodePart(normalizedDevice)}|${encodePart(slotKey)}|`;
-}
-function seqTrackerStoreKey(aid, deviceId, slotId, namespace) {
-    return `${seqTrackerPrefix(aid, deviceId, slotId)}${encodePart(namespace)}`;
-}
-function agentMdCachePrefix(ownerAid) {
-    return `${safeAid(ownerAid)}|`;
-}
-function agentMdCacheStoreKey(ownerAid, targetAid) {
-    return `${agentMdCachePrefix(ownerAid)}${encodePart(targetAid)}`;
-}
-function defaultAgentMdCacheRecord(aid) {
-    return {
-        aid,
-        content: '',
-        local_etag: '',
-        remote_etag: '',
-        last_modified: '',
-        fetched_at: 0,
-        observed_at: 0,
-        checked_at: 0,
-        remote_status: '',
-        verify_status: '',
-        verify_error: '',
-        last_error: '',
-        updated_at: 0,
-    };
-}
-function normalizeAgentMdCacheRecord(aid, value) {
-    if (!isRecord(value))
-        return null;
-    const out = defaultAgentMdCacheRecord(aid);
-    for (const key of ['content', 'local_etag', 'remote_etag', 'last_modified', 'remote_status', 'verify_status', 'verify_error', 'last_error']) {
-        out[key] = String(value[key] ?? '');
-    }
-    for (const key of ['fetched_at', 'observed_at', 'checked_at', 'updated_at']) {
-        const n = Number(value[key] ?? 0);
-        out[key] = Number.isFinite(n) ? Math.trunc(n) : 0;
-    }
-    out.aid = String(value.aid ?? aid).trim() || aid;
-    return out;
-}
-function mergeAgentMdCacheRecord(aid, current, fields) {
-    const out = current ? { ...current } : defaultAgentMdCacheRecord(aid);
-    out.aid = aid;
-    for (const key of ['content', 'local_etag', 'remote_etag', 'last_modified', 'remote_status', 'verify_status', 'verify_error', 'last_error']) {
-        if (Object.prototype.hasOwnProperty.call(fields, key) && fields[key] !== undefined && fields[key] !== null) {
-            out[key] = String(fields[key] ?? '');
-        }
-    }
-    for (const key of ['fetched_at', 'observed_at', 'checked_at']) {
-        if (Object.prototype.hasOwnProperty.call(fields, key) && fields[key] !== undefined && fields[key] !== null) {
-            const n = Number(fields[key] ?? 0);
-            out[key] = Number.isFinite(n) ? Math.trunc(n) : 0;
-        }
-    }
-    out.updated_at = Date.now();
-    return out;
-}
-function stripStructuredFields(metadata) {
-    const plain = deepClone(metadata);
-    delete plain.e2ee_prekeys;
-    delete plain.group_secrets;
-    delete plain.e2ee_sessions;
-    return plain;
-}
-/** 缓存的数据库连接 */
-let _cachedDB = null;
-/** 并发竞态保护：缓存正在进行的 openDB Promise，避免多个并发调用同时创建连接 */
-let _openDBPromise = null;
-/** 打开或升级数据库（复用已有连接） */
-function openDB() {
-    if (_cachedDB)
-        return Promise.resolve(_cachedDB);
-    // 如果已有正在进行的打开请求，直接复用同一个 Promise
-    if (_openDBPromise)
-        return _openDBPromise;
-    _openDBPromise = new Promise((resolve, reject) => {
-        const request = indexedDB.open(DB_NAME, DB_VERSION);
-        request.onupgradeneeded = () => {
-            const db = request.result;
-            if (!db.objectStoreNames.contains(STORE_KEY_PAIRS)) {
-                db.createObjectStore(STORE_KEY_PAIRS);
-            }
-            if (!db.objectStoreNames.contains(STORE_CERTS)) {
-                db.createObjectStore(STORE_CERTS);
-            }
-            if (!db.objectStoreNames.contains(STORE_METADATA)) {
-                db.createObjectStore(STORE_METADATA);
-            }
-            if (!db.objectStoreNames.contains(STORE_INSTANCE_STATE)) {
-                db.createObjectStore(STORE_INSTANCE_STATE);
-            }
-            if (!db.objectStoreNames.contains(STORE_PREKEYS)) {
-                db.createObjectStore(STORE_PREKEYS);
-            }
-            if (!db.objectStoreNames.contains(STORE_GROUP_CURRENT)) {
-                db.createObjectStore(STORE_GROUP_CURRENT);
-            }
-            if (!db.objectStoreNames.contains(STORE_GROUP_OLD_EPOCHS)) {
-                db.createObjectStore(STORE_GROUP_OLD_EPOCHS);
-            }
-            if (!db.objectStoreNames.contains(STORE_SESSIONS)) {
-                db.createObjectStore(STORE_SESSIONS);
-            }
-            if (!db.objectStoreNames.contains(STORE_GROUP_STATE)) {
-                db.createObjectStore(STORE_GROUP_STATE);
-            }
-            if (!db.objectStoreNames.contains(STORE_AGENT_MD_CACHE)) {
-                db.createObjectStore(STORE_AGENT_MD_CACHE);
-            }
-            if (!db.objectStoreNames.contains(STORE_PENDING_IDENTITIES)) {
-                db.createObjectStore(STORE_PENDING_IDENTITIES);
-            }
-        };
-        request.onsuccess = () => {
-            const db = request.result;
-            // H22: 其它 tab 持有旧版本连接时，触发 versionchange 通知它们关闭，避免 onupgradeneeded 挂起
-            db.onversionchange = () => {
-                _cachedDB = null;
-                _openDBPromise = null;
-                try {
-                    db.close();
-                }
-                catch { /* ignore */ }
-            };
-            db.onclose = () => { _cachedDB = null; };
-            _cachedDB = db;
-            _openDBPromise = null; // 成功后清除 Promise 缓存
-            resolve(db);
-        };
-        request.onerror = () => {
-            _openDBPromise = null; // 失败后清除，允许后续重试
-            reject(new Error('IndexedDB 不可用（可能处于隐私模式或 IndexedDB 被禁用）。' +
-                '请使用 FileKeyStore (Node.js) 或在浏览器中允许 IndexedDB。'));
-        };
-        // H22: onblocked = 其它 tab 持有旧版本阻塞升级；必须显式 reject 让上层感知而非永久挂起
-        request.onblocked = () => {
-            _openDBPromise = null; // 阻塞时清除，允许后续重试
-            reject(new Error('IndexedDB 升级被其它 tab 阻塞，请关闭其它页面后重试'));
-        };
-    });
-    return _openDBPromise;
-}
-/** 从指定仓库读取一条记录 */
-async function idbGet(storeName, key) {
-    const db = await openDB();
-    return new Promise((resolve, reject) => {
-        const tx = db.transaction(storeName, 'readonly');
-        const store = tx.objectStore(storeName);
-        const req = store.get(key);
-        tx.oncomplete = () => {
-            resolve(req.result ?? null);
-        };
-        tx.onerror = () => {
-            reject(tx.error ?? new Error(`读取 ${storeName} 失败`));
-        };
-        tx.onabort = () => {
-            reject(tx.error ?? new Error(`读取 ${storeName} 被中止`));
-        };
-    });
-}
-/** 读取仓库内全部记录 */
-async function idbGetAll(storeName) {
-    const db = await openDB();
-    return new Promise((resolve, reject) => {
-        const tx = db.transaction(storeName, 'readonly');
-        const store = tx.objectStore(storeName);
-        const valuesReq = store.getAll();
-        const keysReq = store.getAllKeys();
-        tx.oncomplete = () => {
-            const values = valuesReq.result ?? [];
-            const keys = keysReq.result ?? [];
-            resolve(keys.map((key, index) => ({
-                key: typeof key === 'string' ? key : String(key),
-                value: values[index],
-            })));
-        };
-        tx.onerror = () => {
-            reject(tx.error ?? new Error(`读取 ${storeName} 全量数据失败`));
-        };
-        tx.onabort = () => {
-            reject(tx.error ?? new Error(`读取 ${storeName} 全量数据被中止`));
-        };
-    });
-}
-async function idbGetAllByPrefix(storeName, prefix) {
-    const db = await openDB();
-    return new Promise((resolve, reject) => {
-        const tx = db.transaction(storeName, 'readonly');
-        const store = tx.objectStore(storeName);
-        const range = IDBKeyRange.bound(prefix, `${prefix}\uffff`, false, false);
-        const result = [];
-        const req = store.openCursor(range);
-        req.onsuccess = () => {
-            const cursor = req.result;
-            if (!cursor)
-                return;
-            result.push({
-                key: typeof cursor.key === 'string' ? cursor.key : String(cursor.key),
-                value: cursor.value,
-            });
-            cursor.continue();
-        };
-        tx.oncomplete = () => {
-            resolve(result);
-        };
-        tx.onerror = () => {
-            reject(tx.error ?? new Error(`按前缀读取 ${storeName} 失败`));
-        };
-        tx.onabort = () => {
-            reject(tx.error ?? new Error(`按前缀读取 ${storeName} 被中止`));
-        };
-    });
-}
-/** 向指定仓库写入一条记录 */
-async function idbPut(storeName, key, value) {
-    const db = await openDB();
-    return new Promise((resolve, reject) => {
-        const tx = db.transaction(storeName, 'readwrite');
-        tx.objectStore(storeName).put(value, key);
-        tx.oncomplete = () => {
-            resolve();
-        };
-        tx.onerror = () => {
-            reject(tx.error ?? new Error(`写入 ${storeName} 失败`));
-        };
-        tx.onabort = () => {
-            reject(tx.error ?? new Error(`写入 ${storeName} 被中止`));
-        };
-    });
-}
-/** 从指定仓库删除一条记录 */
-async function idbDelete(storeName, key) {
-    const db = await openDB();
-    return new Promise((resolve, reject) => {
-        const tx = db.transaction(storeName, 'readwrite');
-        tx.objectStore(storeName).delete(key);
-        tx.oncomplete = () => {
-            resolve();
-        };
-        tx.onerror = () => {
-            reject(tx.error ?? new Error(`删除 ${storeName} 失败`));
-        };
-        tx.onabort = () => {
-            reject(tx.error ?? new Error(`删除 ${storeName} 被中止`));
-        };
-    });
-}
-// ── KeyStore 实现 ───────────────────────────────────────
-/**
- * 基于 IndexedDB 的密钥存储实现。
- *
- * 设计语义：
- * - metadata 只保存普通 metadata 字段；
- * - e2ee_prekeys / group_secrets 只保存到结构化 store；
- * - loadMetadata() 返回的是运行时拼出来的 merged view；
- * - 若检测到旧版本把结构化数据写进了 metadata，会自动迁移到结构化 store。
- */
-export class IndexedDBKeyStore {
-    _log = _noopLog;
-    setLogger(log) { this._log = log; }
-    static _aidTails = new Map();
-    /** 私钥加密种子；空字符串也是有效 seed，默认不再写入明文私钥。 */
-    _encryptionSeed;
-    constructor(opts) {
-        this._encryptionSeed = opts?.encryptionSeed ?? '';
-    }
-    static async changeSeed(oldSeed, newSeed) {
-        if (oldSeed === '.seed') {
-            throw new SeedMigrationError('JS IndexedDB keystore does not support file .seed migration');
-        }
-        const rows = await idbGetAll(STORE_KEY_PAIRS);
-        const migrations = [];
-        for (const row of rows) {
-            if (!isRecord(row.value))
-                continue;
-            const envelope = row.value._encrypted_pk;
-            if (!isRecord(envelope)) {
-                const plain = row.value.private_key_pem;
-                if (typeof plain === 'string' && plain) {
-                    migrations.push({ key: row.key, value: deepClone(row.value), privateKeyPem: plain });
-                }
-                continue;
-            }
-            try {
-                const privateKeyPem = await _decryptPEM(envelope, oldSeed);
-                migrations.push({ key: row.key, value: deepClone(row.value), privateKeyPem });
-            }
-            catch {
-                throw new SeedMigrationError(`seed migration refused: private key is not encrypted by old seed: aid=${row.key}`);
-            }
-        }
-        if (migrations.length === 0) {
-            throw new SeedMigrationError('seed migration refused: no encrypted private key verified with old seed');
-        }
-        const result = {
-            migrated: 0,
-            skipped: 0,
-            errors: 0,
-            privateKeysVerified: migrations.length,
-            privateKeysMigrated: 0,
-        };
-        for (const item of migrations) {
-            const next = deepClone(item.value);
-            next._encrypted_pk = await _encryptPEM(item.privateKeyPem, newSeed);
-            const verified = await _decryptPEM(next._encrypted_pk, newSeed);
-            if (verified !== item.privateKeyPem) {
-                throw new SeedMigrationError(`new seed verification failed for private key: aid=${item.key}`);
-            }
-            delete next.private_key_pem;
-            await idbPut(STORE_KEY_PAIRS, item.key, next);
-            result.migrated += 1;
-            result.privateKeysMigrated += 1;
-        }
-        return result;
-    }
-    async changeSeed(oldSeed, newSeed) {
-        const result = await IndexedDBKeyStore.changeSeed(oldSeed, newSeed);
-        this._encryptionSeed = newSeed;
-        return result;
-    }
-    async _withAidLock(aid, fn) {
-        const key = safeAid(aid);
-        const previous = IndexedDBKeyStore._aidTails.get(key) ?? Promise.resolve();
-        let release;
-        const current = new Promise((resolve) => {
-            release = resolve;
-        });
-        const tail = previous.catch(() => undefined).then(() => current);
-        IndexedDBKeyStore._aidTails.set(key, tail);
-        await previous.catch(() => undefined);
-        try {
-            return await fn();
-        }
-        finally {
-            release();
-            if (IndexedDBKeyStore._aidTails.get(key) === tail) {
-                IndexedDBKeyStore._aidTails.delete(key);
-            }
-        }
-    }
-    async listIdentities() {
-        const tStart = Date.now();
-        this._log.debug('listIdentities enter');
-        try {
-            const records = await idbGetAll(STORE_METADATA);
-            const aids = new Set();
-            for (const item of records) {
-                if (item.key.startsWith('_seq_|'))
-                    continue;
-                const value = item.value;
-                const aid = typeof value === 'object' && value !== null && isRecord(value) && typeof value.aid === 'string' && value.aid
-                    ? value.aid
-                    : item.key;
-                aids.add(String(aid));
-            }
-            for (const item of await idbGetAll(STORE_KEY_PAIRS)) {
-                if (!item.key.startsWith('_seq_|'))
-                    aids.add(item.key);
-            }
-            for (const item of await idbGetAll(STORE_CERTS)) {
-                if (item.key.startsWith('_seq_|'))
-                    continue;
-                const [safe] = item.key.split('|', 1);
-                if (safe)
-                    aids.add(safe);
-            }
-            const result = [...aids].sort();
-            this._log.debug(`listIdentities exit: elapsed=${Date.now() - tStart}ms count=${result.length}`);
-            return result;
-        }
-        catch (err) {
-            this._log.debug(`listIdentities exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
-            throw err;
-        }
-    }
-    // ── 密钥对 ──────────────────────────────────────────
-    async loadKeyPair(aid) {
-        const data = await idbGet(STORE_KEY_PAIRS, metadataStoreKey(aid));
-        if (!isRecord(data))
-            return null;
-        const result = deepClone(data);
-        // 如果存在加密私钥信封，尝试解密还原
-        const epk = result._encrypted_pk;
-        if (epk && typeof epk === 'object' && !Array.isArray(epk) && hasEncryptionSeed(this._encryptionSeed)) {
-            try {
-                const envelope = epk;
-                result.private_key_pem = await _decryptPEM(envelope, this._encryptionSeed);
-                delete result._encrypted_pk;
-            }
-            catch {
-                this._log.error(`[keystore] decrypt ${aid} private key failed, maybe encryptionSeed mismatch`);
-                throw new Error(`private key decrypt failed for aid ${aid}: seed_password mismatch or IndexedDB record corrupted`);
-            }
-        }
-        else if (
-        // 透明迁移：旧版明文数据自动加密回写
-        !epk && typeof result.private_key_pem === 'string' && hasEncryptionSeed(this._encryptionSeed)) {
-            await this.saveKeyPair(aid, result);
-        }
-        return result;
-    }
-    async saveKeyPair(aid, keyPair) {
-        const record = deepClone(keyPair);
-        // 如果配置了加密种子且包含明文私钥，加密后再存储
-        if (hasEncryptionSeed(this._encryptionSeed) && typeof record.private_key_pem === 'string') {
-            record._encrypted_pk = await _encryptPEM(record.private_key_pem, this._encryptionSeed);
-            delete record.private_key_pem;
-        }
-        await idbPut(STORE_KEY_PAIRS, metadataStoreKey(aid), record);
-    }
-    // ── RegisterAID pending 身份 ─────────────────────────
-    async pendingIdentityDir(aid) {
-        const handle = `${pendingIdentityPrefix(aid)}${randomHex(4)}-${Math.floor(Date.now() / 1000)}`;
-        const now = Date.now();
-        await idbPut(STORE_PENDING_IDENTITIES, handle, {
-            aid,
-            created_at: now,
-            updated_at: now,
-        });
-        return handle;
-    }
-    async listPendingIdentityDirs(aid) {
-        const prefix = pendingIdentityPrefix(aid);
-        const rows = await idbGetAllByPrefix(STORE_PENDING_IDENTITIES, prefix);
-        return rows
-            .filter((row) => row.key.startsWith(prefix) && isRecord(row.value) && String(row.value.aid ?? '') === aid)
-            .sort((a, b) => Number(b.value.updated_at ?? 0) - Number(a.value.updated_at ?? 0))
-            .map((row) => row.key);
-    }
-    async savePendingKeyPair(handle, aid, keyPair) {
-        const current = await this._loadPendingRecord(handle, aid);
-        if (!current)
-            throw new Error(`pending identity not found: ${handle}`);
-        const record = deepClone(keyPair);
-        const privateKeyPem = record.private_key_pem;
-        if (typeof privateKeyPem !== 'string' || !privateKeyPem) {
-            throw new Error('savePendingKeyPair requires private_key_pem');
-        }
-        record._encrypted_pk = await _encryptPEM(privateKeyPem, this._encryptionSeed ?? '');
-        delete record.private_key_pem;
-        await idbPut(STORE_PENDING_IDENTITIES, handle, {
-            ...current,
-            aid,
-            key_pair: record,
-            updated_at: Date.now(),
-        });
-    }
-    async loadPendingKeyPair(handle, aid) {
-        const current = await this._loadPendingRecord(handle, aid, false);
-        if (!current || !isRecord(current.key_pair))
-            return null;
-        const result = deepClone(current.key_pair);
-        const encrypted = result._encrypted_pk;
-        if (isRecord(encrypted)) {
-            try {
-                const envelope = encrypted;
-                result.private_key_pem = await _decryptPEM(envelope, this._encryptionSeed ?? '');
-                delete result._encrypted_pk;
-                return result;
-            }
-            catch {
-                this._log.error(`[keystore] decrypt pending ${aid} private key failed, maybe encryptionSeed mismatch`);
-                throw new Error(`pending identity private key decrypt failed for aid ${aid}: seed_password mismatch or IndexedDB record corrupted`);
-            }
-        }
-        if (typeof result.private_key_pem === 'string' && result.private_key_pem) {
-            // 兼容历史 pending 明文记录：首次加载成功后立即加密回写，避免 pending 私钥继续明文落盘。
-            await this.savePendingKeyPair(handle, aid, result);
-            return result;
-        }
-        return result;
-    }
-    async savePendingCert(handle, certPem) {
-        const current = await this._loadPendingRecord(handle, undefined);
-        if (!current)
-            throw new Error(`pending identity not found: ${handle}`);
-        await idbPut(STORE_PENDING_IDENTITIES, handle, {
-            ...current,
-            cert: certPem,
-            updated_at: Date.now(),
-        });
-    }
-    async promotePendingIdentity(handle, aid) {
-        const current = await this._loadPendingRecord(handle, aid);
-        if (!current)
-            throw new Error(`pending identity not found: ${handle}`);
-        if (!isRecord(current.key_pair)) {
-            throw new Error(`promotePendingIdentity: missing pending key pair: ${handle}`);
-        }
-        const targetKey = metadataStoreKey(aid);
-        const [existingKeyPair, existingCert, existingMetadata] = await Promise.all([
-            idbGet(STORE_KEY_PAIRS, targetKey),
-            idbGet(STORE_CERTS, certStoreKey(aid)),
-            idbGet(STORE_METADATA, targetKey),
-        ]);
-        if (existingKeyPair || existingCert || existingMetadata) {
-            throw new Error(`promotePendingIdentity: target exists: ${targetKey}`);
-        }
-        const keyPair = await this._protectedPendingKeyPair(current, aid);
-        await idbPut(STORE_KEY_PAIRS, targetKey, keyPair);
-        if (typeof current.cert === 'string' && current.cert) {
-            await idbPut(STORE_CERTS, certStoreKey(aid), current.cert);
-        }
-        await idbDelete(STORE_PENDING_IDENTITIES, handle);
-        return targetKey;
-    }
-    async _protectedPendingKeyPair(current, aid) {
-        if (!isRecord(current.key_pair)) {
-            throw new Error(`pending identity missing key pair for ${aid}`);
-        }
-        const keyPair = deepClone(current.key_pair);
-        const privateKeyPem = keyPair.private_key_pem;
-        if (typeof privateKeyPem === 'string' && privateKeyPem) {
-            throw new Error(`pending identity private key is plaintext for ${aid}`);
-        }
-        if (!isRecord(keyPair._encrypted_pk)) {
-            throw new Error(`pending identity private key is not encrypted for ${aid}`);
-        }
-        return keyPair;
-    }
-    async cleanupPendingDirs(maxAgeMs = 600_000) {
-        const rows = await idbGetAll(STORE_PENDING_IDENTITIES);
-        const now = Date.now();
-        let removed = 0;
-        for (const row of rows) {
-            if (!isRecord(row.value))
-                continue;
-            const updatedAt = Number(row.value.updated_at ?? row.value.created_at ?? 0);
-            if (updatedAt && now - updatedAt < maxAgeMs)
-                continue;
-            await idbDelete(STORE_PENDING_IDENTITIES, row.key);
-            removed++;
-        }
-        return removed;
-    }
-    async discardPendingIdentity(handle) {
-        await idbDelete(STORE_PENDING_IDENTITIES, handle);
-    }
-    // ── 证书 ──────────────────────────────────────────
-    async loadCert(aid, certFingerprint) {
-        const tStart = Date.now();
-        this._log.debug(`loadCert enter: aid=${aid} fingerprint=${certFingerprint ?? '<none>'}`);
-        try {
-            const normalized = normalizeCertFingerprint(certFingerprint);
-            if (normalized) {
-                const versioned = await idbGet(STORE_CERTS, certStoreKey(aid, normalized));
-                if (typeof versioned === 'string') {
-                    this._log.debug(`loadCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} found=true source=versioned`);
-                    return versioned;
-                }
-                const active = await idbGet(STORE_CERTS, certStoreKey(aid));
-                if (typeof active === 'string' && await fingerprintFromCertPem(active) === normalized) {
-                    this._log.debug(`loadCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} found=true source=active`);
-                    return active;
-                }
-                this._log.debug(`loadCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} found=false`);
-                return null;
-            }
-            const data = await idbGet(STORE_CERTS, certStoreKey(aid));
-            const found = typeof data === 'string';
-            this._log.debug(`loadCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} found=${found}`);
-            return found ? data : null;
-        }
-        catch (err) {
-            this._log.debug(`loadCert exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
-            throw err;
-        }
-    }
-    async saveCert(aid, certPem, certFingerprint, opts) {
-        const tStart = Date.now();
-        this._log.debug(`saveCert enter: aid=${aid} fingerprint=${certFingerprint ?? '<none>'} make_active=${opts?.makeActive ?? false}`);
-        try {
-            const normalized = normalizeCertFingerprint(certFingerprint);
-            if (normalized) {
-                await idbPut(STORE_CERTS, certStoreKey(aid, normalized), certPem);
-                if (opts?.makeActive) {
-                    await idbPut(STORE_CERTS, certStoreKey(aid), certPem);
-                }
-                this._log.debug(`saveCert exit: elapsed=${Date.now() - tStart}ms aid=${aid}`);
-                return;
-            }
-            await idbPut(STORE_CERTS, certStoreKey(aid), certPem);
-            this._log.debug(`saveCert exit: elapsed=${Date.now() - tStart}ms aid=${aid}`);
-        }
-        catch (err) {
-            this._log.debug(`saveCert exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
-            throw err;
-        }
-    }
-    // ── 实例态 ──────────────────────────────────────────
-    async loadInstanceState(aid, deviceId, slotId = '') {
-        return this._withAidLock(aid, async () => {
-            const data = await idbGet(STORE_INSTANCE_STATE, instanceStateStoreKey(aid, deviceId, slotId));
-            return isRecord(data) ? deepClone(data) : null;
-        });
-    }
-    async saveInstanceState(aid, deviceId, slotId, state) {
-        await this._withAidLock(aid, async () => {
-            await idbPut(STORE_INSTANCE_STATE, instanceStateStoreKey(aid, deviceId, slotId), deepClone(state));
-        });
-    }
-    async updateInstanceState(aid, deviceId, slotId, updater) {
-        return this._withAidLock(aid, async () => {
-            const currentRaw = await idbGet(STORE_INSTANCE_STATE, instanceStateStoreKey(aid, deviceId, slotId));
-            const current = isRecord(currentRaw) ? deepClone(currentRaw) : {};
-            const working = deepClone(current);
-            const updated = updater(working) ?? working;
-            await idbPut(STORE_INSTANCE_STATE, instanceStateStoreKey(aid, deviceId, slotId), deepClone(updated));
-            return deepClone(updated);
-        });
-    }
-    // ── 身份信息（组合操作） ──────────────────────────
-    async loadIdentity(aid) {
-        const tStart = Date.now();
-        this._log.debug(`loadIdentity enter: aid=${aid}`);
-        try {
-            const result = await this._withAidLock(aid, async () => {
-                const [keyPair, cert] = await Promise.all([
-                    this._loadKeyPairUnlocked(aid),
-                    this._loadCertUnlocked(aid),
-                ]);
-                // 直接读取 metadata KV（含旧数据迁移）
-                const metadataOnly = await this._migrateLegacyStructuredStateUnlocked(aid);
-                const hasMeta = Object.keys(metadataOnly).length > 0;
-                if (!keyPair && !cert && !hasMeta)
-                    return null;
-                const identity = {};
-                if (hasMeta)
-                    Object.assign(identity, metadataOnly);
-                if (keyPair)
-                    Object.assign(identity, keyPair);
-                if (cert) {
-                    // key/cert 公钥一致性校验：防止 cert 被意外覆盖
-                    const localPubB64 = keyPair?.public_key_der_b64;
-                    if (typeof localPubB64 === 'string' && localPubB64) {
-                        const certSpkiB64 = extractSpkiB64FromCertPem(cert);
-                        if (certSpkiB64 && certSpkiB64 !== localPubB64) {
-                            this._log.error(`[keystore] identity ${aid}  key public key mismatches cert public key, discard cert`);
-                        }
-                        else {
-                            identity.cert = cert;
-                        }
-                    }
-                    else {
-                        identity.cert = cert;
-                    }
-                }
-                return identity;
-            });
-            this._log.debug(`loadIdentity exit: elapsed=${Date.now() - tStart}ms aid=${aid} found=${result !== null}`);
-            return result;
-        }
-        catch (err) {
-            this._log.debug(`loadIdentity exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
-            throw err;
-        }
-    }
-    async saveIdentity(aid, identity) {
-        const tStart = Date.now();
-        this._log.debug(`saveIdentity enter: aid=${aid} has_cert=${!!identity.cert}`);
-        try {
-            await this._withAidLock(aid, async () => {
-                const keyPairFields = {};
-                for (const key of ['private_key_pem', 'public_key_der_b64', 'curve']) {
-                    if (key in identity)
-                        keyPairFields[key] = identity[key];
-                }
-                if (Object.keys(keyPairFields).length > 0) {
-                    await this._saveKeyPairUnlocked(aid, keyPairFields);
-                }
-                const cert = identity.cert;
-                if (typeof cert === 'string' && cert) {
-                    await this._saveCertUnlocked(aid, cert);
-                }
-                const metadataFields = {};
-                for (const [key, value] of Object.entries(identity)) {
-                    if (!['private_key_pem', 'public_key_der_b64', 'curve', 'cert'].includes(key)) {
-                        metadataFields[key] = value;
-                    }
-                }
-                // 增量保存 metadata 字段
-                if (Object.keys(metadataFields).length > 0) {
-                    await this._replaceStructuredStateUnlocked(aid, metadataFields);
-                    const plain = stripStructuredFields(metadataFields);
-                    if (Object.keys(plain).length > 0) {
-                        const current = await this._migrateLegacyStructuredStateUnlocked(aid);
-                        Object.assign(current, plain);
-                        await this._saveMetadataOnlyUnlocked(aid, current);
-                    }
-                }
-            });
-            this._log.debug(`saveIdentity exit: elapsed=${Date.now() - tStart}ms aid=${aid}`);
-        }
-        catch (err) {
-            this._log.debug(`saveIdentity exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
-            throw err;
-        }
-    }
-    // ── 结构化 prekeys ───────────────────────────────────
-    async loadE2EEPrekeys(aid, deviceId) {
-        return this._withAidLock(aid, async () => {
-            await this._migrateLegacyStructuredStateUnlocked(aid);
-            return this._loadPrekeysUnlocked(aid, String(deviceId ?? '').trim());
-        });
-    }
-    /**
-     * 按 prekey_id 单点查询本地 prekey（O(log N) IndexedDB primary-key 查找）。
-     *
-     * 解密入站消息时，envelope 里只带 prekey_id，没有 device_id。原先要走
-     * `loadE2EEPrekeys` 全量加载（prekey 池大时一次扫描数百毫秒）。
-     * 本方法优先用 IndexedDB 主键直查；命中则 O(log N)，未命中再回退到前缀扫描，
-     * 保证跨 device_id 也能找到（兼容设备级 prekey 场景）。
-     *
-     * 返回结构与 `_loadPrekeysUnlocked` 单条值一致（已剥离 prekey_id / device_id 字段）。
-     */
-    async loadE2EEPrekeyById(aid, prekeyId) {
-        return this._withAidLock(aid, async () => {
-            await this._migrateLegacyStructuredStateUnlocked(aid);
-            return this._loadPrekeyByIdUnlocked(aid, prekeyId);
-        });
-    }
-    async saveE2EEPrekey(aid, prekeyId, prekeyData, deviceId) {
-        await this._withAidLock(aid, async () => {
-            await this._migrateLegacyStructuredStateUnlocked(aid);
-            const record = deepClone(prekeyData);
-            record.prekey_id = prekeyId;
-            const normalizedDeviceId = String(deviceId ?? '').trim();
-            if (normalizedDeviceId) {
-                record.device_id = normalizedDeviceId;
-            }
-            else {
-                delete record.device_id;
-            }
-            const targetKey = prekeyStoreKey(aid, prekeyId, normalizedDeviceId);
-            for (const item of await idbGetAllByPrefix(STORE_PREKEYS, prekeyPrefix(aid))) {
-                if (!isRecord(item.value))
-                    continue;
-                const existingPrekeyId = typeof item.value.prekey_id === 'string'
-                    ? item.value.prekey_id
-                    : '';
-                const existingDeviceId = String(item.value.device_id ?? '').trim();
-                if (existingPrekeyId === prekeyId && existingDeviceId === normalizedDeviceId && item.key !== targetKey) {
-                    await idbDelete(STORE_PREKEYS, item.key);
-                }
-            }
-            await idbPut(STORE_PREKEYS, targetKey, record);
-        });
-    }
-    async cleanupE2EEPrekeys(aid, cutoffMs, keepLatest = 7, deviceId) {
-        return this._withAidLock(aid, async () => {
-            await this._migrateLegacyStructuredStateUnlocked(aid);
-            const normalizedDeviceId = String(deviceId ?? '').trim();
-            const prekeys = await this._loadPrekeysUnlocked(aid, normalizedDeviceId);
-            const retainedIds = new Set(Object.entries(prekeys)
-                .sort((left, right) => {
-                const leftMarker = Number(left[1].created_at ?? left[1].updated_at ?? left[1].expires_at ?? 0);
-                const rightMarker = Number(right[1].created_at ?? right[1].updated_at ?? right[1].expires_at ?? 0);
-                if (rightMarker !== leftMarker)
-                    return rightMarker - leftMarker;
-                return right[0].localeCompare(left[0]);
-            })
-                .slice(0, keepLatest)
-                .map(([prekeyId]) => prekeyId));
-            const removed = Object.entries(prekeys)
-                .filter(([prekeyId, data]) => Number(data.created_at ?? data.updated_at ?? data.expires_at ?? 0) < cutoffMs
-                && !retainedIds.has(prekeyId))
-                .map(([prekeyId]) => prekeyId);
-            const removedIds = new Set(removed);
-            for (const item of await idbGetAllByPrefix(STORE_PREKEYS, prekeyPrefix(aid))) {
-                if (!isRecord(item.value))
-                    continue;
-                const recordDeviceId = String(item.value.device_id ?? '').trim();
-                if (recordDeviceId !== normalizedDeviceId)
-                    continue;
-                const prekeyId = typeof item.value.prekey_id === 'string' ? item.value.prekey_id : '';
-                if (removedIds.has(prekeyId))
-                    await idbDelete(STORE_PREKEYS, item.key);
-            }
-            return removed;
-        });
-    }
-    // ── 结构化群组密钥 ─────────────────────────────────
-    async listGroupSecretIds(aid) {
-        return this._withAidLock(aid, async () => {
-            await this._migrateLegacyStructuredStateUnlocked(aid);
-            const ids = new Set();
-            for (const item of await idbGetAllByPrefix(STORE_GROUP_CURRENT, groupCurrentPrefix(aid))) {
-                const [, encodedGroupId] = item.key.split('|');
-                if (encodedGroupId)
-                    ids.add(decodeURIComponent(encodedGroupId));
-            }
-            for (const item of await idbGetAllByPrefix(STORE_GROUP_OLD_EPOCHS, groupOldPrefix(aid))) {
-                const [, encodedGroupId] = item.key.split('|');
-                if (encodedGroupId)
-                    ids.add(decodeURIComponent(encodedGroupId));
-            }
-            return [...ids].sort();
-        });
-    }
-    async cleanupGroupOldEpochsState(aid, groupId, cutoffMs) {
-        return this._withAidLock(aid, async () => {
-            await this._migrateLegacyStructuredStateUnlocked(aid);
-            let removed = 0;
-            for (const item of await idbGetAllByPrefix(STORE_GROUP_OLD_EPOCHS, groupOldPrefix(aid, groupId))) {
-                if (!isRecord(item.value))
-                    continue;
-                if (Number(item.value.updated_at ?? 0) <= cutoffMs) {
-                    await idbDelete(STORE_GROUP_OLD_EPOCHS, item.key);
-                    removed += 1;
-                }
-            }
-            return removed;
-        });
-    }
-    async loadGroupSecretEpoch(aid, groupId, epoch) {
-        return this._withAidLock(aid, async () => {
-            await this._migrateLegacyStructuredStateUnlocked(aid);
-            const current = await idbGet(STORE_GROUP_CURRENT, groupCurrentStoreKey(aid, groupId));
-            if (isRecord(current)) {
-                const record = deepClone(current);
-                delete record.group_id;
-                if (epoch === undefined || epoch === null || Number(record.epoch ?? 0) === Number(epoch)) {
-                    return record;
-                }
-            }
-            else if (epoch === undefined || epoch === null) {
-                return null;
-            }
-            const old = await idbGet(STORE_GROUP_OLD_EPOCHS, groupOldStoreKey(aid, groupId, Number(epoch)));
-            if (!isRecord(old))
-                return null;
-            const record = deepClone(old);
-            delete record.group_id;
-            return record;
-        });
-    }
-    async loadGroupSecretEpochs(aid, groupId) {
-        return this._withAidLock(aid, async () => {
-            await this._migrateLegacyStructuredStateUnlocked(aid);
-            const result = [];
-            const current = await idbGet(STORE_GROUP_CURRENT, groupCurrentStoreKey(aid, groupId));
-            if (isRecord(current)) {
-                const record = deepClone(current);
-                delete record.group_id;
-                result.push(record);
-            }
-            for (const item of await idbGetAllByPrefix(STORE_GROUP_OLD_EPOCHS, groupOldPrefix(aid, groupId))) {
-                if (!isRecord(item.value))
-                    continue;
-                const record = deepClone(item.value);
-                delete record.group_id;
-                result.push(record);
-            }
-            return result;
-        });
-    }
-    async storeGroupSecretTransition(aid, groupId, opts) {
-        return this._withAidLock(aid, async () => {
-            await this._migrateLegacyStructuredStateUnlocked(aid);
-            return this._storeGroupSecretTransitionUnlocked(aid, groupId, opts);
-        });
-    }
-    async storeGroupSecretEpoch(aid, groupId, opts) {
-        return this._withAidLock(aid, async () => {
-            await this._migrateLegacyStructuredStateUnlocked(aid);
-            return this._storeGroupSecretEpochUnlocked(aid, groupId, opts);
-        });
-    }
-    async discardPendingGroupSecretState(aid, groupId, epoch, rotationId) {
-        return this._withAidLock(aid, async () => {
-            const rid = String(rotationId ?? '').trim();
-            if (!rid)
-                return false;
-            await this._migrateLegacyStructuredStateUnlocked(aid);
-            return this._discardPendingGroupSecretUnlocked(aid, groupId, epoch, rid);
-        });
-    }
-    async deleteGroupSecretState(aid, groupId) {
-        await this._withAidLock(aid, async () => {
-            // 删除 current epoch
-            await idbDelete(STORE_GROUP_CURRENT, groupCurrentStoreKey(aid, groupId));
-            // 删除所有 old epochs
-            for (const item of await idbGetAllByPrefix(STORE_GROUP_OLD_EPOCHS, groupOldPrefix(aid, groupId))) {
-                await idbDelete(STORE_GROUP_OLD_EPOCHS, item.key);
-            }
-        });
-    }
-    // ── E2EE Sessions ─────────────────────────────────────
-    async loadE2EESessions(aid) {
-        return this._withAidLock(aid, async () => {
-            await this._migrateLegacySessionsUnlocked(aid);
-            return this._loadSessionsUnlocked(aid);
-        });
-    }
-    async saveE2EESession(aid, sessionId, data) {
-        await this._withAidLock(aid, async () => {
-            await this._migrateLegacySessionsUnlocked(aid);
-            const record = deepClone(data);
-            record.session_id = sessionId;
-            await idbPut(STORE_SESSIONS, sessionStoreKey(aid, sessionId), record);
-        });
-    }
-    /**
-     * 读取单个 metadata KV（如 gateway_url 等跨进程缓存项）。
-     *
-     * 不存在时返回空字符串，与 Python keystore 的 get_metadata 语义保持一致。
-     */
-    async getMetadata(aid, key) {
-        if (!key)
-            return '';
-        return this._withAidLock(aid, async () => {
-            const md = (await this._loadMetadataOnlyUnlocked(aid)) ?? {};
-            const value = md[key];
-            if (typeof value === 'string')
-                return value;
-            if (value === null || value === undefined)
-                return '';
-            return String(value);
-        });
-    }
-    /**
-     * 写入单个 metadata KV。空字符串视为删除该字段。
-     *
-     * 与 _saveMetadataOnlyUnlocked 不同，本方法只更新指定 key，不影响其他字段。
-     */
-    async setMetadata(aid, key, value) {
-        if (!key)
-            return;
-        await this._withAidLock(aid, async () => {
-            const current = (await this._loadMetadataOnlyUnlocked(aid)) ?? {};
-            const next = deepClone(current);
-            if (value === '' || value === undefined || value === null) {
-                delete next[key];
-            }
-            else {
-                next[key] = value;
-            }
-            await this._saveMetadataOnlyUnlocked(aid, next);
-        });
-    }
-    // ── 内部辅助 ─────────────────────────────────────────
-    async _loadPendingRecord(handle, aid, required = true) {
-        const data = await idbGet(STORE_PENDING_IDENTITIES, handle);
-        if (!isRecord(data)) {
-            if (required)
-                throw new Error(`pending identity not found: ${handle}`);
-            return null;
-        }
-        const record = deepClone(data);
-        if (aid !== undefined && String(record.aid ?? '') !== aid) {
-            throw new Error(`pending identity aid mismatch: ${handle}`);
-        }
-        return record;
-    }
-    async _loadKeyPairUnlocked(aid) {
-        const data = await idbGet(STORE_KEY_PAIRS, metadataStoreKey(aid));
-        if (!isRecord(data))
-            return null;
-        const result = deepClone(data);
-        // 如果存在加密私钥信封，尝试解密还原
-        if (isRecord(result._encrypted_pk) && hasEncryptionSeed(this._encryptionSeed)) {
-            try {
-                const envelope = result._encrypted_pk;
-                result.private_key_pem = await _decryptPEM(envelope, this._encryptionSeed);
-                delete result._encrypted_pk;
-            }
-            catch {
-                this._log.error(`[keystore] decrypt ${aid} private key failed, maybe encryptionSeed mismatch`);
-                throw new Error(`private key decrypt failed for aid ${aid}: seed_password mismatch or IndexedDB record corrupted`);
-            }
-        }
-        else if (
-        // 透明迁移：旧版明文数据自动加密回写
-        !isRecord(result._encrypted_pk) && typeof result.private_key_pem === 'string' && hasEncryptionSeed(this._encryptionSeed)) {
-            await this._saveKeyPairUnlocked(aid, result);
-        }
-        return result;
-    }
-    async _saveKeyPairUnlocked(aid, keyPair) {
-        const record = deepClone(keyPair);
-        // 如果配置了加密种子且包含明文私钥，加密后再存储
-        if (hasEncryptionSeed(this._encryptionSeed) && typeof record.private_key_pem === 'string') {
-            record._encrypted_pk = await _encryptPEM(record.private_key_pem, this._encryptionSeed);
-            delete record.private_key_pem;
-        }
-        await idbPut(STORE_KEY_PAIRS, metadataStoreKey(aid), record);
-    }
-    async _loadCertUnlocked(aid) {
-        const data = await idbGet(STORE_CERTS, certStoreKey(aid));
-        return typeof data === 'string' ? data : null;
-    }
-    async _saveCertUnlocked(aid, certPem) {
-        await idbPut(STORE_CERTS, certStoreKey(aid), certPem);
-    }
-    async _loadMetadataOnlyUnlocked(aid) {
-        const data = await idbGet(STORE_METADATA, metadataStoreKey(aid));
-        return isRecord(data) ? deepClone(data) : null;
-    }
-    async _replaceStructuredStateUnlocked(aid, metadata) {
-        // 增量保存：只处理传入的字段，不删除未传入的
-        if ('e2ee_prekeys' in metadata && isRecord(metadata.e2ee_prekeys)) {
-            await this._replacePrekeysUnlocked(aid, metadata.e2ee_prekeys, '');
-        }
-        if ('group_secrets' in metadata && isRecord(metadata.group_secrets)) {
-            await this._replaceGroupEntriesUnlocked(aid, metadata.group_secrets);
-        }
-        if ('e2ee_sessions' in metadata && Array.isArray(metadata.e2ee_sessions)) {
-            await this._replaceSessionsUnlocked(aid, metadata.e2ee_sessions);
-        }
-    }
-    async _saveMetadataOnlyUnlocked(aid, metadata) {
-        const plain = stripStructuredFields(metadata);
-        await idbPut(STORE_METADATA, metadataStoreKey(aid), plain);
-    }
-    async _migrateLegacyStructuredStateUnlocked(aid) {
-        const metadataOnly = (await this._loadMetadataOnlyUnlocked(aid)) ?? {};
-        const hasLegacyPrekeys = isRecord(metadataOnly.e2ee_prekeys);
-        const hasLegacyGroups = isRecord(metadataOnly.group_secrets);
-        const hasLegacySessions = Array.isArray(metadataOnly.e2ee_sessions) && metadataOnly.e2ee_sessions.length > 0;
-        if (!hasLegacyPrekeys && !hasLegacyGroups && !hasLegacySessions) {
-            return metadataOnly;
-        }
-        const cleaned = deepClone(metadataOnly);
-        if (hasLegacyPrekeys) {
-            const legacyPrekeys = metadataOnly.e2ee_prekeys;
-            const structuredPrekeys = await this._loadPrekeysUnlocked(aid);
-            let changed = false;
-            if (isRecord(legacyPrekeys)) {
-                for (const [prekeyId, rawData] of Object.entries(legacyPrekeys)) {
-                    if (!isRecord(rawData) || structuredPrekeys[prekeyId])
-                        continue;
-                    if (!this._isPrekeyRecoverable(rawData))
-                        continue;
-                    structuredPrekeys[prekeyId] = deepClone(rawData);
-                    changed = true;
-                }
-            }
-            if (changed) {
-                await this._replacePrekeysUnlocked(aid, structuredPrekeys);
-            }
-            delete cleaned.e2ee_prekeys;
-        }
-        if (hasLegacyGroups) {
-            const legacyGroups = metadataOnly.group_secrets;
-            const structuredGroups = await this._loadGroupEntriesUnlocked(aid);
-            let changed = false;
-            if (isRecord(legacyGroups)) {
-                for (const [groupId, rawEntry] of Object.entries(legacyGroups)) {
-                    if (!isRecord(rawEntry))
-                        continue;
-                    const merged = this._mergeGroupEntryFromLegacy(structuredGroups[groupId], rawEntry);
-                    if (!sameJson(structuredGroups[groupId] ?? null, merged)) {
-                        if (Object.keys(merged).length > 0) {
-                            structuredGroups[groupId] = merged;
-                            changed = true;
-                        }
-                    }
-                }
-            }
-            if (changed) {
-                await this._replaceGroupEntriesUnlocked(aid, structuredGroups);
-            }
-            delete cleaned.group_secrets;
-        }
-        if (hasLegacySessions) {
-            const legacySessions = metadataOnly.e2ee_sessions;
-            for (const session of legacySessions) {
-                const sid = typeof session.session_id === 'string' ? session.session_id : '';
-                if (!sid)
-                    continue;
-                const record = deepClone(session);
-                record.session_id = sid;
-                await idbPut(STORE_SESSIONS, sessionStoreKey(aid, sid), record);
-            }
-            delete cleaned.e2ee_sessions;
-        }
-        await this._saveMetadataOnlyUnlocked(aid, cleaned);
-        return cleaned;
-    }
-    async _loadPrekeysUnlocked(aid, deviceId = '') {
-        const items = await idbGetAllByPrefix(STORE_PREKEYS, prekeyPrefix(aid));
-        const prefix = prekeyPrefix(aid);
-        const result = {};
-        const normalizedDeviceId = String(deviceId ?? '').trim();
-        for (const item of items) {
-            if (!item.key.startsWith(prefix) || !isRecord(item.value))
-                continue;
-            const recordDeviceId = String(item.value.device_id ?? '').trim();
-            if (recordDeviceId !== normalizedDeviceId)
-                continue;
-            const prekeyId = typeof item.value.prekey_id === 'string'
-                ? item.value.prekey_id
-                : item.key.slice(prefix.length);
-            const record = deepClone(item.value);
-            delete record.prekey_id;
-            delete record.device_id;
-            const canonicalKey = prekeyStoreKey(aid, prekeyId, normalizedDeviceId);
-            if (!(prekeyId in result) || item.key === canonicalKey) {
-                result[prekeyId] = record;
-            }
-        }
-        return result;
-    }
-    /**
-     * 按 prekey_id 单点查找（不锁外部，调用方负责加锁）。
-     *
-     * 实现策略：
-     * 1) 先按"无 device_id"的 canonical key 直查（命中即 O(log N)）。
-     * 2) 未命中（设备级 prekey 走的是含 device_id 的复合 key）→ 回退前缀扫描，
-     *    在 prekey_id 字段匹配的第一条记录上返回；这种情况下扫描代价仍存在，但
-     *    只在边缘 case 触发。
-     *
-     * 返回结构与 `_loadPrekeysUnlocked` 单条值保持一致：剥离 prekey_id / device_id。
-     */
-    async _loadPrekeyByIdUnlocked(aid, prekeyId) {
-        if (!prekeyId)
-            return null;
-        // 优先：deviceId='' 形态的 canonical key（generatePrekey 默认走这条路径）。
-        const directKey = prekeyStoreKey(aid, prekeyId, '');
-        const direct = await idbGet(STORE_PREKEYS, directKey);
-        if (isRecord(direct)) {
-            const record = deepClone(direct);
-            delete record.prekey_id;
-            delete record.device_id;
-            return record;
-        }
-        // 回退：设备级 prekey（key 形如 aid|device|prekey_id）→ 前缀扫描匹配 prekey_id 字段。
-        for (const item of await idbGetAllByPrefix(STORE_PREKEYS, prekeyPrefix(aid))) {
-            if (!isRecord(item.value))
-                continue;
-            const itemPrekeyId = typeof item.value.prekey_id === 'string' ? item.value.prekey_id : '';
-            if (itemPrekeyId !== prekeyId)
-                continue;
-            const record = deepClone(item.value);
-            delete record.prekey_id;
-            delete record.device_id;
-            return record;
-        }
-        return null;
-    }
-    async _replacePrekeysUnlocked(aid, prekeys, deviceId = '') {
-        const desired = new Set(Object.keys(prekeys));
-        const normalizedDeviceId = String(deviceId ?? '').trim();
-        for (const item of await idbGetAllByPrefix(STORE_PREKEYS, prekeyPrefix(aid))) {
-            if (!isRecord(item.value))
-                continue;
-            const recordDeviceId = String(item.value.device_id ?? '').trim();
-            if (recordDeviceId !== normalizedDeviceId)
-                continue;
-            const prekeyId = typeof item.value.prekey_id === 'string'
-                ? item.value.prekey_id
-                : '';
-            const canonicalKey = prekeyStoreKey(aid, prekeyId, normalizedDeviceId);
-            if (!desired.has(prekeyId) || item.key !== canonicalKey) {
-                await idbDelete(STORE_PREKEYS, item.key);
-            }
-        }
-        for (const [prekeyId, prekeyData] of Object.entries(prekeys)) {
-            const record = deepClone(prekeyData);
-            if (normalizedDeviceId) {
-                record.device_id = normalizedDeviceId;
-            }
-            else {
-                delete record.device_id;
-            }
-            await idbPut(STORE_PREKEYS, prekeyStoreKey(aid, prekeyId, normalizedDeviceId), {
-                ...record,
-                prekey_id: prekeyId,
-            });
-        }
-    }
-    async _loadGroupEntriesUnlocked(aid) {
-        const result = {};
-        for (const item of await idbGetAllByPrefix(STORE_GROUP_CURRENT, groupCurrentPrefix(aid))) {
-            if (!isRecord(item.value))
-                continue;
-            const groupId = typeof item.value.group_id === 'string'
-                ? item.value.group_id
-                : item.key.slice(groupCurrentPrefix(aid).length);
-            const record = deepClone(item.value);
-            delete record.group_id;
-            result[groupId] = record;
-        }
-        for (const item of await idbGetAllByPrefix(STORE_GROUP_OLD_EPOCHS, groupOldPrefix(aid))) {
-            if (!isRecord(item.value))
-                continue;
-            const groupId = typeof item.value.group_id === 'string'
-                ? item.value.group_id
-                : '';
-            if (!groupId)
-                continue;
-            const record = deepClone(item.value);
-            delete record.group_id;
-            const entry = result[groupId] ?? {};
-            const oldEpochs = Array.isArray(entry.old_epochs)
-                ? entry.old_epochs
-                : [];
-            oldEpochs.push(record);
-            oldEpochs.sort((a, b) => Number(a.epoch ?? 0) - Number(b.epoch ?? 0));
-            entry.old_epochs = oldEpochs;
-            result[groupId] = entry;
-        }
-        return result;
-    }
-    async _replaceGroupEntriesUnlocked(aid, groups) {
-        const desiredGroups = new Set(Object.keys(groups));
-        for (const item of await idbGetAllByPrefix(STORE_GROUP_CURRENT, groupCurrentPrefix(aid))) {
-            const groupId = isRecord(item.value) && typeof item.value.group_id === 'string'
-                ? item.value.group_id
-                : item.key.slice(groupCurrentPrefix(aid).length);
-            if (!desiredGroups.has(groupId)) {
-                await idbDelete(STORE_GROUP_CURRENT, item.key);
-            }
-        }
-        for (const item of await idbGetAllByPrefix(STORE_GROUP_OLD_EPOCHS, groupOldPrefix(aid))) {
-            if (!isRecord(item.value))
-                continue;
-            const groupId = typeof item.value.group_id === 'string' ? item.value.group_id : '';
-            if (!groupId || desiredGroups.has(groupId))
-                continue;
-            await idbDelete(STORE_GROUP_OLD_EPOCHS, item.key);
-        }
-        for (const [groupId, rawEntry] of Object.entries(groups)) {
-            if (!isRecord(rawEntry))
-                continue;
-            await this._saveSingleGroupEntryUnlocked(aid, groupId, rawEntry);
-        }
-    }
-    async _saveSingleGroupEntryUnlocked(aid, groupId, entry) {
-        for (const item of await idbGetAllByPrefix(STORE_GROUP_OLD_EPOCHS, groupOldPrefix(aid, groupId))) {
-            if (!isRecord(item.value))
-                continue;
-            const existingGroupId = typeof item.value.group_id === 'string' ? item.value.group_id : '';
-            if (existingGroupId === groupId) {
-                await idbDelete(STORE_GROUP_OLD_EPOCHS, item.key);
-            }
-        }
-        const current = deepClone(entry);
-        const oldEpochs = Array.isArray(current.old_epochs)
-            ? current.old_epochs
-            : [];
-        delete current.old_epochs;
-        if (typeof current.epoch === 'number') {
-            await idbPut(STORE_GROUP_CURRENT, groupCurrentStoreKey(aid, groupId), {
-                ...current,
-                group_id: groupId,
-            });
-        }
-        else {
-            await idbDelete(STORE_GROUP_CURRENT, groupCurrentStoreKey(aid, groupId));
-        }
-        for (const oldEpoch of oldEpochs) {
-            if (!isRecord(oldEpoch) || typeof oldEpoch.epoch !== 'number')
-                continue;
-            await idbPut(STORE_GROUP_OLD_EPOCHS, groupOldStoreKey(aid, groupId, oldEpoch.epoch), {
-                ...deepClone(oldEpoch),
-                group_id: groupId,
-            });
-        }
-    }
-    async _storeGroupSecretTransitionUnlocked(aid, groupId, opts) {
-        const currentKey = groupCurrentStoreKey(aid, groupId);
-        const currentRaw = await idbGet(STORE_GROUP_CURRENT, currentKey);
-        const now = Date.now();
-        const epoch = Number(opts.epoch);
-        const members = [...(opts.memberAids ?? [])].map((item) => String(item)).sort();
-        const pendingRotationId = String(opts.pendingRotationId ?? '').trim();
-        if (isRecord(currentRaw)) {
-            const current = deepClone(currentRaw);
-            delete current.group_id;
-            const localEpoch = Number(current.epoch ?? 0);
-            if (epoch < localEpoch)
-                return false;
-            if (epoch === localEpoch && typeof current.secret === 'string') {
-                if (current.secret !== opts.secret) {
-                    if (String(current.pending_rotation_id ?? '').trim()) {
-                        await idbPut(STORE_GROUP_CURRENT, currentKey, {
-                            ...this._buildGroupCurrentRecord(groupId, opts, members, now),
-                        });
-                        return true;
-                    }
-                    return false;
-                }
-                const updated = { ...current };
-                let changed = false;
-                const oldMembers = Array.isArray(updated.member_aids) ? updated.member_aids.map(String).sort() : [];
-                if (members.length > 0 && JSON.stringify(oldMembers) !== JSON.stringify(members)) {
-                    updated.member_aids = members;
-                    updated.commitment = opts.commitment;
-                    updated.updated_at = now;
-                    changed = true;
-                }
-                if (opts.epochChain !== undefined && updated.epoch_chain !== opts.epochChain) {
-                    updated.epoch_chain = opts.epochChain;
-                    updated.updated_at = now;
-                    changed = true;
-                }
-                if (opts.epochChainUnverified === true) {
-                    if (updated.epoch_chain_unverified !== true) {
-                        updated.epoch_chain_unverified = true;
-                        changed = true;
-                    }
-                    if (opts.epochChainUnverifiedReason && updated.epoch_chain_unverified_reason !== opts.epochChainUnverifiedReason) {
-                        updated.epoch_chain_unverified_reason = opts.epochChainUnverifiedReason;
-                        changed = true;
-                    }
-                }
-                else if (opts.epochChainUnverified === false) {
-                    if ('epoch_chain_unverified' in updated || 'epoch_chain_unverified_reason' in updated) {
-                        delete updated.epoch_chain_unverified;
-                        delete updated.epoch_chain_unverified_reason;
-                        changed = true;
-                    }
-                }
-                if (pendingRotationId && updated.pending_rotation_id !== pendingRotationId) {
-                    updated.pending_rotation_id = pendingRotationId;
-                    updated.pending_created_at = now;
-                    changed = true;
-                }
-                if (!pendingRotationId && updated.pending_rotation_id) {
-                    delete updated.pending_rotation_id;
-                    delete updated.pending_created_at;
-                    changed = true;
-                }
-                if (changed) {
-                    await idbPut(STORE_GROUP_CURRENT, currentKey, { ...updated, group_id: groupId });
-                }
-                return true;
-            }
-            if (localEpoch !== epoch) {
-                const oldEntry = { ...current };
-                oldEntry.expires_at = Number(current.updated_at ?? now) + opts.oldEpochRetentionMs;
-                await idbPut(STORE_GROUP_OLD_EPOCHS, groupOldStoreKey(aid, groupId, localEpoch), {
-                    ...oldEntry,
-                    group_id: groupId,
-                });
-            }
-            else {
-                // epoch === localEpoch 但 secret 为空：合并 data，保留已有字段
-                const merged = { ...current, ...this._buildGroupCurrentRecord(groupId, opts, members, now) };
-                if (!opts.epochChain && current.epoch_chain) {
-                    merged.epoch_chain = current.epoch_chain;
-                }
-                if (current.pending_rotation_id && !opts.pendingRotationId) {
-                    merged.pending_rotation_id = current.pending_rotation_id;
-                    if (current.pending_created_at)
-                        merged.pending_created_at = current.pending_created_at;
-                }
-                await idbPut(STORE_GROUP_CURRENT, currentKey, merged);
-                return true;
-            }
-        }
-        await idbPut(STORE_GROUP_CURRENT, currentKey, {
-            ...this._buildGroupCurrentRecord(groupId, opts, members, now),
-        });
-        return true;
-    }
-    async _storeGroupSecretEpochUnlocked(aid, groupId, opts) {
-        const now = Date.now();
-        const epoch = Number(opts.epoch);
-        const members = [...(opts.memberAids ?? [])].map((item) => String(item)).sort();
-        const pendingRotationId = String(opts.pendingRotationId ?? '').trim();
-        const currentKey = groupCurrentStoreKey(aid, groupId);
-        const currentRaw = await idbGet(STORE_GROUP_CURRENT, currentKey);
-        const newRecord = this._buildGroupCurrentRecord(groupId, opts, members, now);
-        if (!isRecord(currentRaw)) {
-            await idbPut(STORE_GROUP_CURRENT, currentKey, newRecord);
-            return true;
-        }
-        const current = deepClone(currentRaw);
-        delete current.group_id;
-        const localEpoch = Number(current.epoch ?? 0);
-        if (epoch > localEpoch) {
-            // 归档旧 epoch 到 old_epochs，然后用新 epoch 更新 current
-            const expiresAt = Date.now() + (opts.oldEpochRetentionMs ?? 604800_000);
-            const oldRecord = { ...current, group_id: groupId, expires_at: expiresAt };
-            const oldKey = groupOldStoreKey(aid, groupId, localEpoch);
-            await idbPut(STORE_GROUP_OLD_EPOCHS, oldKey, oldRecord);
-            await idbPut(STORE_GROUP_CURRENT, currentKey, newRecord);
-            return true;
-        }
-        if (epoch === localEpoch) {
-            if (typeof current.secret === 'string' && current.secret !== opts.secret) {
-                if (!String(current.pending_rotation_id ?? '').trim())
-                    return false;
-                await idbPut(STORE_GROUP_CURRENT, currentKey, newRecord);
-                return true;
-            }
-            const updated = { ...current };
-            let changed = false;
-            const oldMembers = Array.isArray(updated.member_aids) ? updated.member_aids.map(String).sort() : [];
-            if (members.length > 0 && JSON.stringify(oldMembers) !== JSON.stringify(members)) {
-                updated.member_aids = members;
-                updated.commitment = opts.commitment;
-                updated.updated_at = now;
-                changed = true;
-            }
-            if (opts.epochChain !== undefined && updated.epoch_chain !== opts.epochChain) {
-                updated.epoch_chain = opts.epochChain;
-                updated.updated_at = now;
-                changed = true;
-            }
-            if (opts.epochChainUnverified === true) {
-                if (updated.epoch_chain_unverified !== true) {
-                    updated.epoch_chain_unverified = true;
-                    changed = true;
-                }
-                if (opts.epochChainUnverifiedReason && updated.epoch_chain_unverified_reason !== opts.epochChainUnverifiedReason) {
-                    updated.epoch_chain_unverified_reason = opts.epochChainUnverifiedReason;
-                    changed = true;
-                }
-            }
-            else if (opts.epochChainUnverified === false) {
-                if ('epoch_chain_unverified' in updated || 'epoch_chain_unverified_reason' in updated) {
-                    delete updated.epoch_chain_unverified;
-                    delete updated.epoch_chain_unverified_reason;
-                    changed = true;
-                }
-            }
-            if (pendingRotationId && updated.pending_rotation_id !== pendingRotationId) {
-                updated.pending_rotation_id = pendingRotationId;
-                updated.pending_created_at = now;
-                changed = true;
-            }
-            if (!pendingRotationId && updated.pending_rotation_id) {
-                delete updated.pending_rotation_id;
-                delete updated.pending_created_at;
-                changed = true;
-            }
-            if (changed)
-                await idbPut(STORE_GROUP_CURRENT, currentKey, { ...updated, group_id: groupId });
-            return true;
-        }
-        const oldKey = groupOldStoreKey(aid, groupId, epoch);
-        const oldRaw = await idbGet(STORE_GROUP_OLD_EPOCHS, oldKey);
-        if (isRecord(oldRaw)) {
-            const old = deepClone(oldRaw);
-            if (typeof old.secret === 'string' && old.secret !== opts.secret)
-                return false;
-        }
-        await idbPut(STORE_GROUP_OLD_EPOCHS, oldKey, {
-            ...newRecord,
-            epoch,
-            expires_at: now + opts.oldEpochRetentionMs,
-        });
-        return true;
-    }
-    async _discardPendingGroupSecretUnlocked(aid, groupId, epoch, rotationId) {
-        const currentKey = groupCurrentStoreKey(aid, groupId);
-        const currentRaw = await idbGet(STORE_GROUP_CURRENT, currentKey);
-        if (!isRecord(currentRaw))
-            return false;
-        const current = deepClone(currentRaw);
-        if (Number(current.epoch ?? 0) !== Number(epoch))
-            return false;
-        if (String(current.pending_rotation_id ?? '').trim() !== rotationId)
-            return false;
-        let restored = null;
-        let restoredKey = '';
-        for (const item of await idbGetAllByPrefix(STORE_GROUP_OLD_EPOCHS, groupOldPrefix(aid, groupId))) {
-            if (!isRecord(item.value))
-                continue;
-            const old = deepClone(item.value);
-            const oldEpoch = Number(old.epoch ?? 0);
-            if (oldEpoch >= Number(epoch) || !old.secret)
-                continue;
-            if (!restored || oldEpoch > Number(restored.epoch ?? 0)) {
-                restored = old;
-                restoredKey = item.key;
-            }
-        }
-        if (!restored) {
-            await idbDelete(STORE_GROUP_CURRENT, currentKey);
-            for (const item of await idbGetAllByPrefix(STORE_GROUP_OLD_EPOCHS, groupOldPrefix(aid, groupId))) {
-                await idbDelete(STORE_GROUP_OLD_EPOCHS, item.key);
-            }
-            return true;
-        }
-        delete restored.group_id;
-        delete restored.expires_at;
-        await idbPut(STORE_GROUP_CURRENT, currentKey, { ...restored, group_id: groupId, updated_at: Date.now() });
-        if (restoredKey)
-            await idbDelete(STORE_GROUP_OLD_EPOCHS, restoredKey);
-        return true;
-    }
-    _buildGroupCurrentRecord(groupId, opts, memberAids, now) {
-        const record = {
-            group_id: groupId,
-            epoch: opts.epoch,
-            secret: opts.secret,
-            commitment: opts.commitment,
-            member_aids: memberAids,
-            updated_at: now,
-        };
-        if (opts.epochChain !== undefined)
-            record.epoch_chain = opts.epochChain;
-        const pendingRotationId = String(opts.pendingRotationId ?? '').trim();
-        if (pendingRotationId) {
-            record.pending_rotation_id = pendingRotationId;
-            record.pending_created_at = now;
-        }
-        if (opts.epochChainUnverified === true) {
-            record.epoch_chain_unverified = true;
-            if (opts.epochChainUnverifiedReason)
-                record.epoch_chain_unverified_reason = opts.epochChainUnverifiedReason;
-        }
-        return record;
-    }
-    _mergeGroupEntryFromLegacy(existing, incoming) {
-        const oldByEpoch = new Map();
-        let current = existing && typeof existing.epoch === 'number'
-            ? deepClone(Object.fromEntries(Object.entries(existing).filter(([key]) => key !== 'old_epochs')))
-            : null;
-        if (existing && Array.isArray(existing.old_epochs)) {
-            for (const rawOld of existing.old_epochs) {
-                if (typeof rawOld.epoch !== 'number')
-                    continue;
-                oldByEpoch.set(rawOld.epoch, deepClone(rawOld));
-            }
-        }
-        if (typeof incoming.epoch === 'number' && this._isGroupEpochRecoverable(incoming)) {
-            const incomingCurrent = deepClone(Object.fromEntries(Object.entries(incoming).filter(([key]) => key !== 'old_epochs')));
-            if (!current) {
-                current = incomingCurrent;
-            }
-            else if (incomingCurrent.epoch > current.epoch) {
-                oldByEpoch.set(current.epoch, this._preferNewerGroupEpochRecord(oldByEpoch.get(current.epoch), current));
-                current = incomingCurrent;
-            }
-            else if (incomingCurrent.epoch === current.epoch) {
-                current = this._preferNewerGroupEpochRecord(current, incomingCurrent);
-            }
-            else {
-                oldByEpoch.set(incomingCurrent.epoch, this._preferNewerGroupEpochRecord(oldByEpoch.get(incomingCurrent.epoch), incomingCurrent));
-            }
-        }
-        const incomingOldEpochs = Array.isArray(incoming.old_epochs)
-            ? incoming.old_epochs
-            : [];
-        for (const rawOld of incomingOldEpochs) {
-            if (typeof rawOld.epoch !== 'number' || !this._isGroupEpochRecoverable(rawOld))
-                continue;
-            oldByEpoch.set(rawOld.epoch, this._preferNewerGroupEpochRecord(oldByEpoch.get(rawOld.epoch), rawOld));
-        }
-        const merged = current ? deepClone(current) : {};
-        if (current && typeof current.epoch === 'number') {
-            oldByEpoch.delete(current.epoch);
-        }
-        if (oldByEpoch.size > 0) {
-            merged.old_epochs = [...oldByEpoch.entries()]
-                .sort(([a], [b]) => a - b)
-                .map(([, value]) => deepClone(value));
-        }
-        return merged;
-    }
-    _preferNewerGroupEpochRecord(existing, incoming) {
-        if (!existing)
-            return deepClone(incoming);
-        return Number(incoming.updated_at ?? 0) > Number(existing.updated_at ?? 0)
-            ? deepClone(incoming)
-            : deepClone(existing);
-    }
-    _isUnexpiredRecord(record, fallbackKey) {
-        const expiresAt = typeof record.expires_at === 'number' ? record.expires_at : null;
-        if (expiresAt !== null)
-            return expiresAt >= Date.now();
-        const marker = typeof record[fallbackKey] === 'number' ? record[fallbackKey] : null;
-        return marker !== null && marker + STRUCTURED_RECOVERY_RETENTION_MS >= Date.now();
-    }
-    _isPrekeyRecoverable(record) {
-        return this._isUnexpiredRecord(record, 'created_at');
-    }
-    _isGroupEpochRecoverable(record) {
-        // 空字符串 secret 不视为可恢复的有效记录
-        const secret = record.secret;
-        if (!secret || (typeof secret === 'string' && secret.length === 0))
-            return false;
-        return this._isUnexpiredRecord(record, 'updated_at');
-    }
-    // ── Sessions 内部辅助 ─────────────────────────────────
-    async _loadSessionsUnlocked(aid) {
-        const items = await idbGetAllByPrefix(STORE_SESSIONS, sessionPrefix(aid));
-        const result = [];
-        for (const item of items) {
-            if (!isRecord(item.value))
-                continue;
-            result.push(deepClone(item.value));
-        }
-        return result;
-    }
-    async _replaceSessionsUnlocked(aid, sessions) {
-        const desired = new Set();
-        for (const session of sessions) {
-            const sid = typeof session.session_id === 'string' ? session.session_id : '';
-            if (!sid)
-                continue;
-            desired.add(sid);
-            const record = deepClone(session);
-            record.session_id = sid;
-            await idbPut(STORE_SESSIONS, sessionStoreKey(aid, sid), record);
-        }
-        for (const item of await idbGetAllByPrefix(STORE_SESSIONS, sessionPrefix(aid))) {
-            if (!isRecord(item.value))
-                continue;
-            const sid = typeof item.value.session_id === 'string'
-                ? item.value.session_id
-                : item.key.slice(sessionPrefix(aid).length);
-            if (!desired.has(sid)) {
-                await idbDelete(STORE_SESSIONS, item.key);
-            }
-        }
-    }
-    async _migrateLegacySessionsUnlocked(aid) {
-        const metadataOnly = (await this._loadMetadataOnlyUnlocked(aid)) ?? {};
-        if (!Array.isArray(metadataOnly.e2ee_sessions) || metadataOnly.e2ee_sessions.length === 0) {
-            return;
-        }
-        for (const session of metadataOnly.e2ee_sessions) {
-            const sid = typeof session.session_id === 'string' ? session.session_id : '';
-            if (!sid)
-                continue;
-            const record = deepClone(session);
-            record.session_id = sid;
-            await idbPut(STORE_SESSIONS, sessionStoreKey(aid, sid), record);
-        }
-        const cleaned = deepClone(metadataOnly);
-        delete cleaned.e2ee_sessions;
-        await this._saveMetadataOnlyUnlocked(aid, cleaned);
-    }
-    // ── Seq Tracker ─────────────────────────────────────────
-    async saveSeq(aid, deviceId, slotId, namespace, contiguousSeq) {
-        const key = seqTrackerStoreKey(aid, deviceId, slotId, namespace);
-        await idbPut(STORE_INSTANCE_STATE, key, { contiguous_seq: contiguousSeq, updated_at: Date.now() });
-    }
-    async loadSeq(aid, deviceId, slotId, namespace) {
-        const key = seqTrackerStoreKey(aid, deviceId, slotId, namespace);
-        const data = await idbGet(STORE_INSTANCE_STATE, key);
-        return data?.contiguous_seq ?? 0;
-    }
-    async loadAllSeqs(aid, deviceId, slotId) {
-        const prefix = seqTrackerPrefix(aid, deviceId, slotId);
-        const items = await idbGetAllByPrefix(STORE_INSTANCE_STATE, prefix);
-        const result = {};
-        for (const item of items) {
-            if (!item.key.startsWith(prefix))
-                continue;
-            const ns = decodeURIComponent(item.key.slice(prefix.length));
-            if (ns && typeof item.value?.contiguous_seq === 'number') {
-                result[ns] = item.value.contiguous_seq;
-            }
-        }
-        return result;
-    }
-    async deleteSeq(aid, deviceId, slotId, namespace) {
-        const key = seqTrackerStoreKey(aid, deviceId, slotId, namespace);
-        await idbDelete(STORE_INSTANCE_STATE, key);
-    }
-    // ── agent.md Cache ───────────────────────────────────────
-    async loadAgentMdCache(ownerAid, targetAid) {
-        const owner = String(ownerAid ?? '').trim();
-        const target = String(targetAid ?? '').trim();
-        if (!owner || !target)
-            return null;
-        const data = await idbGet(STORE_AGENT_MD_CACHE, agentMdCacheStoreKey(owner, target));
-        const record = normalizeAgentMdCacheRecord(target, data);
-        return record ? deepClone(record) : null;
-    }
-    async upsertAgentMdCache(ownerAid, targetAid, fields) {
-        const owner = String(ownerAid ?? '').trim();
-        const target = String(targetAid ?? '').trim();
-        if (!owner || !target) {
-            throw new Error('upsertAgentMdCache requires ownerAid and targetAid');
-        }
-        const current = await this.loadAgentMdCache(owner, target);
-        const record = mergeAgentMdCacheRecord(target, current, fields ?? {});
-        await idbPut(STORE_AGENT_MD_CACHE, agentMdCacheStoreKey(owner, target), record);
-        return deepClone(record);
-    }
-    async listAgentMdContentAids(agentMdPath) {
-        const root = String(agentMdPath ?? '').trim();
-        if (!root)
-            return [];
-        const prefix = agentMdCachePrefix(root);
-        const suffix = '/agent.md';
-        const aids = new Set();
-        for (const item of await idbGetAllByPrefix(STORE_AGENT_MD_CACHE, prefix)) {
-            const encodedTarget = item.key.slice(prefix.length);
-            let target = '';
-            try {
-                target = decodeURIComponent(encodedTarget);
-            }
-            catch {
-                target = encodedTarget;
-            }
-            if (!target.endsWith(suffix))
-                continue;
-            const aid = target.slice(0, -suffix.length).trim();
-            if (aid)
-                aids.add(aid);
-        }
-        return [...aids].sort();
-    }
-    // ── Group State（群组状态快照） ─────────────────────────────
-    async saveGroupState(groupId, state) {
-        const key = encodePart(groupId);
-        await idbPut(STORE_GROUP_STATE, key, {
-            group_id: groupId,
-            state_version: state.state_version,
-            state_hash: state.state_hash,
-            key_epoch: state.key_epoch,
-            membership_json: state.membership_json,
-            policy_json: state.policy_json,
-            updated_at: state.updated_at ?? Date.now(),
-        });
-    }
-    async loadGroupState(groupId) {
-        const key = encodePart(groupId);
-        const data = await idbGet(STORE_GROUP_STATE, key);
-        if (!data || typeof data.state_version !== 'number')
-            return null;
-        return {
-            group_id: groupId,
-            state_version: data.state_version,
-            state_hash: data.state_hash ?? '',
-            key_epoch: data.key_epoch ?? 0,
-            membership_json: data.membership_json ?? '[]',
-            policy_json: data.policy_json ?? '{}',
-            updated_at: data.updated_at ?? 0,
-        };
-    }
-    // ── Trust Root Storage（信任根证书存储） ─────────────────
-    // 浏览器环境无文件系统，统一存入 STORE_INSTANCE_STATE 并以特定前缀的 key 区分。
-    // 对外返回的"路径"为虚拟标识（indexeddb://...），仅用于日志/兼容字段。
-    /** 信任根列表 JSON 在 IndexedDB 中的 key */
-    static _TRUST_LIST_KEY = '__trust_roots:list';
-    /** 信任根 bundle PEM 在 IndexedDB 中的 key */
-    static _TRUST_BUNDLE_KEY = '__trust_roots:bundle';
-    /** 单个 root cert 在 IndexedDB 中的 key 前缀 */
-    static _TRUST_CERT_PREFIX = '__trust_roots:cert:';
-    /** 单个 issuer root cert 在 IndexedDB 中的 key 前缀 */
-    static _TRUST_ISSUER_PREFIX = '__trust_roots:issuer:';
-    /** 计算 PEM 证书的 SHA-256 指纹（hex，无冒号） */
-    async _pemFingerprint(pem) {
-        try {
-            const der = new Uint8Array(pemToArrayBuffer(pem));
-            const hash = await crypto.subtle.digest('SHA-256', der);
-            return Array.from(new Uint8Array(hash))
-                .map(b => b.toString(16).padStart(2, '0'))
-                .join('');
-        }
-        catch {
-            // 解析失败时退化为对 PEM 文本本身做哈希（仅用于去重，不暴露）
-            const enc = new TextEncoder().encode(pem);
-            const hash = await crypto.subtle.digest('SHA-256', enc);
-            return Array.from(new Uint8Array(hash))
-                .map(b => b.toString(16).padStart(2, '0'))
-                .join('');
-        }
-    }
-    /** 拆分 bundle PEM 文本为单个 PEM 证书数组 */
-    _splitPemBundle(bundleText) {
-        return bundleText
-            .split(/(?<=-----END CERTIFICATE-----)\s*/)
-            .map(s => s.trim())
-            .filter(s => s.startsWith('-----BEGIN CERTIFICATE-----'));
-    }
-    async saveTrustRoots(trustList, rootCerts) {
-        // 保存每个根证书到独立 key
-        for (let i = 0; i < rootCerts.length; i++) {
-            const item = rootCerts[i];
-            const certId = item.id || item.fingerprint_sha256 || `root-${i + 1}`;
-            const safeName = certId.replace(/[^A-Za-z0-9_.-]+/g, '_').slice(0, 120);
-            await idbPut(STORE_INSTANCE_STATE, IndexedDBKeyStore._TRUST_CERT_PREFIX + safeName, item.cert_pem);
-        }
-        // 生成合并 bundle
-        const bundle = rootCerts.map(i => i.cert_pem.trim()).join('\n') + '\n';
-        await idbPut(STORE_INSTANCE_STATE, IndexedDBKeyStore._TRUST_BUNDLE_KEY, bundle);
-        // 保存元数据 JSON
-        await idbPut(STORE_INSTANCE_STATE, IndexedDBKeyStore._TRUST_LIST_KEY, deepClone(trustList));
-        return 'indexeddb://trust-roots/bundle';
-    }
-    async saveIssuerRootCert(issuer, certPem, fingerprintSha256 = '') {
-        const safeIssuer = (issuer || 'issuer').replace(/[^A-Za-z0-9_.-]+/g, '_').slice(0, 120);
-        const certKey = IndexedDBKeyStore._TRUST_ISSUER_PREFIX + safeIssuer;
-        const normalizedPem = certPem.trim() + '\n';
-        // 保存 issuer 根证书
-        await idbPut(STORE_INSTANCE_STATE, certKey, normalizedPem);
-        // 读取已有 bundle 并合并（按指纹去重）
-        const existingPems = new Map();
-        const existingBundle = await idbGet(STORE_INSTANCE_STATE, IndexedDBKeyStore._TRUST_BUNDLE_KEY);
-        if (typeof existingBundle === 'string' && existingBundle) {
-            for (const pem of this._splitPemBundle(existingBundle)) {
-                const fp = await this._pemFingerprint(pem);
-                existingPems.set(fp, pem);
-            }
-        }
-        // 新证书的指纹
-        let newFp = await this._pemFingerprint(normalizedPem);
-        if (fingerprintSha256) {
-            newFp = fingerprintSha256.toLowerCase().replace(/^sha256:/, '');
-        }
-        existingPems.set(newFp, normalizedPem);
-        // 重写 bundle
-        const merged = Array.from(existingPems.values()).map(p => p.trim()).join('\n') + '\n';
-        await idbPut(STORE_INSTANCE_STATE, IndexedDBKeyStore._TRUST_BUNDLE_KEY, merged);
-        return [`indexeddb://trust-roots/issuers/${safeIssuer}`, 'indexeddb://trust-roots/bundle'];
-    }
-    async loadTrustRoots() {
-        const data = await idbGet(STORE_INSTANCE_STATE, IndexedDBKeyStore._TRUST_LIST_KEY);
-        if (!isRecord(data))
-            return null;
-        return deepClone(data);
-    }
-}
-//# sourceMappingURL=indexeddb.js.map