@tacet-ink/journal-core 0.2.5 → 0.3.1

package/dist/client/bip39.js

@@ -0,0 +1,139 @@
+/**
+ * bip39.ts — 復原套件轉寫層（BIP39 英文 24 詞 ⇄ entropy 32B ⇄ recToken hex64）。
+ *
+ * 契約裁定（2026-09-10 復原套件三件）：
+ * - **轉寫層，非 KDF 升級**：24 詞 ⇄ hex64 可逆互轉；線上契約（rec_hash = SHA-256(hex64)、
+ *   wrappedRec = jr1w. + GCM(PBKDF2(recToken, ...))）完全不變，伺服器零改動。
+ *   熵等價：24 詞 = 256-bit entropy + 8-bit checksum（BIP39 標準）；與舊 hex64 同熵。
+ * - **checksum 是轉寫品質閘**：單詞打錯 255/256 機率當場被抓（64 hex 轉寫無此偵測）；
+ *   解析失敗一律回 null（不洩漏哪類錯：字數/詞表外/checksum 統一，UI 統一訊息）。
+ * - **只收 24 詞**：12 詞是降級禁用（security-roadmap 裁定）；15/18/21 不收（契約面單一）。
+ * - **相容層永久**：舊帳戶 hex64 紙本照走現行鏈；recTokenToWords 供既有套件顯示用。
+ * - **零依賴**：SHA-256 用 WebCrypto（全 async API）；bits 打包自製（閘 [9] 以
+ *   @scure/bip39 參照實作 200 組雙向對照守證）。禁用 @scure 的 mnemonicToSeed
+ *   （PBKDF2-SHA512 seed 派生與 Tacet 契約無關，不可混入）。
+ */
+import { wordlist } from './wordlist.js';
+const HEX64_RE = /^[0-9a-f]{64}$/;
+async function sha256(data) {
+    return new Uint8Array(await crypto.subtle.digest('SHA-256', data));
+}
+function hexToBytes(hexStr) {
+    const out = new Uint8Array(hexStr.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(hexStr.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+/** 輸入正規化：NFKC → 換行/全形空白/多空白收斂單半形空格 → 小寫（wordlist 全小寫，輸入容錯）。 */
+function normalizeWords(input) {
+    return input.normalize('NFKC').trim().toLowerCase().split(/\s+/).filter(w => w.length > 0);
+}
+/** 11-bit 打包（BIP39 標準位元累積器；carry 恆 < 19 bits，索引 = 低位遮罩 0x7ff）。 */
+function entropyToIndexes(entropy, checksum) {
+    const bytes = new Uint8Array(entropy.length + 1);
+    bytes.set(entropy);
+    bytes[entropy.length] = checksum; // 32B entropy → checksum 8 bits = SHA-256 首位元組全值
+    const indexes = [];
+    let carry = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        carry = (carry << 8) | byte;
+        bits += 8;
+        if (bits >= 11) {
+            bits -= 11;
+            indexes.push((carry >>> bits) & 0x7ff);
+            carry &= (1 << bits) - 1;
+        }
+    }
+    return indexes;
+}
+/** 11-bit 逆打包：24 個索引 → 33 bytes（entropy 32B + checksum 1B）。 */
+function indexesToBytes(indexes) {
+    const out = new Uint8Array(33);
+    let carry = 0;
+    let bits = 0;
+    let pos = 0;
+    for (const idx of indexes) {
+        carry = (carry << 11) | idx;
+        bits += 11;
+        while (bits >= 8) {
+            bits -= 8;
+            out[pos++] = (carry >>> bits) & 0xff;
+            carry &= (1 << bits) - 1;
+        }
+    }
+    return out; // 24 詞 = 264 bits = 33 bytes 整除，無餘位（11-bit 打包自洽）
+}
+/** 產生 24 詞套件（entropy 32B 隨機 → +8-bit checksum → 24 詞）。
+ *  entropyBytes 可注入（驗證閘固定種子樣本用；產品面不傳＝真隨機契約不變）。 */
+export async function generateBip39Words(entropyBytes) {
+    const entropy = entropyBytes ?? crypto.getRandomValues(new Uint8Array(32));
+    const checksum = (await sha256(entropy))[0];
+    return entropyToIndexes(entropy, checksum).map(idx => wordlist[idx]);
+}
+// ── 驗證閘固定種子樣本（flake 歸零）──────────────────────────────
+//
+// 背景：checksum 統計面「錯一詞 64 樣本 ≥63 被抓」用真隨機取樣時，P(漏 ≥2)≈0.4%，
+// 偶發 62/64＝閘 flake（2026-09-19 session 實證）。治本是固定種子：xorshift32 以
+// 常數 seed 產生確定性位元組流（種子決定樣本集＝向量可重放、閘輸出逐輪恆定）。
+// 樣本集僅供驗證閘使用（checksum 是 BIP39 公開數學，非機密；產品面
+// generateBip39Words() 不帶參數＝crypto.getRandomValues 真隨機契約不變）。
+function xorshift32Bytes(seed, len) {
+    let s = seed >>> 0;
+    if (s === 0)
+        s = 0x9e3779b9; // xorshift 全零態死鎖防護
+    const out = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        s ^= s << 13;
+        s >>>= 0;
+        s ^= s >>> 17;
+        s ^= s << 5;
+        s >>>= 0;
+        out[i] = s & 0xff;
+    }
+    return out;
+}
+/** 固定種子樣本集：seed 給定 → 32B 確定（xorshift32 常數種子流）。 */
+export function seededSampleBytes(seed) {
+    return xorshift32Bytes(seed, 32);
+}
+/** 24 詞 → recToken hex64。任何不符（字數/詞表外/checksum）回 null，不洩漏哪類錯。 */
+export async function wordsToRecToken(input) {
+    const words = typeof input === 'string' ? normalizeWords(input) : input.map(w => w.normalize('NFKC').trim().toLowerCase());
+    if (words.length !== 24)
+        return null;
+    const indexes = [];
+    for (const w of words) {
+        const idx = wordlist.indexOf(w);
+        if (idx < 0)
+            return null;
+        indexes.push(idx);
+    }
+    const bytes = indexesToBytes(indexes);
+    const entropy = bytes.slice(0, 32);
+    const checksum = bytes[32];
+    const expected = (await sha256(entropy))[0];
+    if (checksum !== expected)
+        return null;
+    return bytesToHex(entropy);
+}
+/** recToken hex64 → 24 詞（既有套件顯示需求；非 hex64 或格式不符回 null）。 */
+export async function recTokenToWords(recToken) {
+    if (!HEX64_RE.test(recToken))
+        return null;
+    const entropy = hexToBytes(recToken);
+    const checksum = (await sha256(entropy))[0];
+    return entropyToIndexes(entropy, checksum).map(idx => wordlist[idx]);
+}
+/** 抄寫抽驗位置：24 詞中抽 4 個不重複位置（0-23），排序回傳（顯示順序穩定）。 */
+export function spotCheckIndexes() {
+    const pool = Array.from({ length: 24 }, (_, i) => i);
+    for (let i = pool.length - 1; i > 0; i--) {
+        const j = crypto.getRandomValues(new Uint32Array(1))[0] % (i + 1);
+        [pool[i], pool[j]] = [pool[j], pool[i]];
+    }
+    return pool.slice(0, 4).sort((a, b) => a - b);
+}

package/dist/client/keys.d.ts

@@ -0,0 +1,15 @@
+/**
+ * keys.ts — storage key 命名空間。各產品以 config 指定前綴（如 journal 的 <brand>_）。
+ * 理由：fork diff 證實 noteCrypto 差異一半在 localStorage key 前綴——參數化收進 core。
+ */
+export interface KeyStoreConfig {
+    /** 產品前綴，如 'tacet'（不含底線）。 */
+    brand: string;
+}
+export declare function makeKeyStore(config: KeyStoreConfig): {
+    get: (k: string) => string | null;
+    set: (k: string, v: string) => void;
+    remove: (k: string) => void;
+    noteKeyWrap: (soulKey: string) => string;
+};
+export type KeyStore = ReturnType<typeof makeKeyStore>;

package/dist/client/keys.js

@@ -0,0 +1,30 @@
+/**
+ * keys.ts — storage key 命名空間。各產品以 config 指定前綴（如 journal 的 <brand>_）。
+ * 理由：fork diff 證實 noteCrypto 差異一半在 localStorage key 前綴——參數化收進 core。
+ */
+export function makeKeyStore(config) {
+    const wrapKey = (soulKey) => `${config.brand}_notekey:${soulKey}`;
+    return {
+        get: (k) => {
+            try {
+                return localStorage.getItem(k);
+            }
+            catch {
+                return null;
+            }
+        },
+        set: (k, v) => {
+            try {
+                localStorage.setItem(k, v);
+            }
+            catch { /* private mode：不阻擋主流程 */ }
+        },
+        remove: (k) => {
+            try {
+                localStorage.removeItem(k);
+            }
+            catch { /* noop */ }
+        },
+        noteKeyWrap: wrapKey,
+    };
+}

package/dist/client/note-crypto.d.ts

@@ -0,0 +1,203 @@
+/**
+ * note-crypto.ts — 自由書寫 e2e 加密，品牌參數化核心。
+ *
+ * 血統：抽取自姊妹專案的日記加密模組（37 斷言驗證閘母型）；
+ * fork diff 已證實：除品牌前綴（guest KDF 前綴、密文前綴家族、KDF salt 前綴）
+ * 與產品附加機制外，密碼學本體在多個產品間完全一致——本檔承載該本體。
+ *
+ * 兩時代金鑰模型（不變量，勿破壞）：
+ *   時代 1（未綁定 guest）：K_u = SHA-256(guestKdfPrefix ‖ identity) — 純客戶端派生，混淆級
+ *   時代 2（綁定後）：隨機 256-bit noteKey；日常加解密只用 noteKey，passphrase 以
+ *     KEK = PBKDF2(pass, salt, 600000, SHA-256) 包裹成 wrapped 上傳；復原套件 wrappedRec
+ *     = 同款包裹在 KEK_rec = PBKDF2(recToken, salt = recSaltPrefix ‖ identity) 下。
+ *     passphrase 從此不過線：線上憑證送 PH1（雜湊形，派生方式由各產品自定義），伺服器存 PH2。
+ *     復原套件 v0.2.0 世代：前綴專用化（wrapRec=jr1r.）＋KEK_rec 派生
+ *     世代化（recKekHkdf 配置＝HKDF-SHA256，info='journal-kek-rec-v1:'+recKekHkdf）＋
+ *     AAD 帶內切換（'notekey'→'notekey-rec'）；新世代讀舊寫新——unwrap 新面先行、回落
+ *     舊契約面（PBKDF2＋AAD 'notekey'）雙試（過渡保護承諾：舊 blob 永遠可解；摘雙試
+ *     時點＝遷移率裁定非日曆）。
+ *
+ * 前綴全部可配置（帶內版本化：升級 KDF 參數 = 換新前綴）。AAD 由呼叫端傳入——
+ * 例如綁 `noteId`（跨列搬移必解密失敗）、`lifeId:day`（逐日日記）或留言綁 `tst:<lifeId>`。
+ *
+ * ⚠️ extractable 鐵律：所有要被 exportKey/wrap 的 key，
+ * import 當下就必須 extractable=true。noteKey 全部產生路徑（generate/unwrap×3）
+ * 一律顯式 true；KEK/guest key 保持 nonextractable（只加解密、永不 export）。
+ */
+export interface NoteCryptoConfig {
+    /** guest 時代 KDF 前綴，如 'journal-note-u1'。 */
+    guestKdfPrefix: string;
+    /** 復原包裹 KDF salt 前綴，如 'journal-note-rec1:'。 */
+    recSaltPrefix: string;
+    /** 密文前綴：guest 時代，如 'jr1g.'。未配置 = guest API 拒絕（未配置行為不變；2026-09-19 轉選配）。 */
+    cipherGuest?: string;
+    /** 密文前綴：綁定時代，如 'jr1b.'。 */
+    cipherBound: string;
+    /** 金鑰包裹前綴，如 'jr1w.'。 */
+    wrap: string;
+    /** 本機包裹前綴（jr1l.：本機包裹不再借用 cfg.wrap——「一個前綴一份契約」
+     *  的第二違例收口）。未配置 = storeLocalWrap/loadLocalWrap 退場（無寫入／讀取照走
+     *  舊形回落，零資料損失——cipherLocal opt-in 母型；寫面功能退場——v1 可用者升級後
+     *  需配置 wrapLocal 才保留本機包裹寫入）。 */
+    wrapLocal?: string;
+    /** 復原套件專用前綴（jr1r.：wrappedRec 不再借用 cfg.wrap——同前例收口）。
+     *  AAD 亦帶內切換 'notekey'→'notekey-rec'（共用 AAD 收口）。與 recKekHkdf **兩欄一體**
+     *  （同缺同在；部分配置＝ERR_REC_CFG_PARTIAL 拒寫——世代配對門，fail-closed 禁寫出
+     *  「前綴面 jr1r.×派生面 PBKDF2」跨契約 blob）。兩欄皆缺席 = wrap/unwrap 復原套件面
+     *  照走舊契約（cfg.wrap＋PBKDF2＋AAD 'notekey'）＝行為不變態（配置形正確
+     *  時舊 wrappedRec blob 永遠可解——HKDF 腿誤配拋點整面 fail-closed 既有契約）。 */
+    wrapRec?: string;
+    /** 復原套件「KEK 派生」世代開關：KEK_rec = HKDF-SHA256(
+     *  ikm = recToken（256-bit 實體因子）， salt = recKekSalt？:16B hex（未配置＝零鹽），
+     *  info = 'journal-kek-rec-v1:' + recKekHkdf, L = 32 )——info 合成名沿 argon2 家族
+     *  慣例（呼叫端帶入；KEK 派生世代空間由前綴＋info 承載）。HKDF 世代 identity 不入
+     *  KEK（identity-free by design——256-bit 實體因子足綁；identity 綁域由
+     *  舊契約面 recSaltPrefix‖identity 專屬承載，兩世代綁域刻意分離）。與 wrapRec 兩欄
+     *  一體（同缺同在；部分配置＝ERR_REC_CFG_PARTIAL 拒寫）。未配置 = PBKDF2 舊世代
+     *  （裁定：HKDF 強化屬 v0.2.0 世代；強度差異對 256-bit recToken 無意義，
+     *  收的是「派生域＋前綴契約面分離」的語意收口）。 */
+    recKekHkdf?: string;
+    /** HKDF salt：16B hex 專屬鹽域（與 PBKDF2 面 recSaltPrefix 前綴域分離
+     *  ——KEK 派生世代鹽）。未配置 = HKDF 零鹽（HKDF salt 欄位本就 optional；語意不變，
+     *  域由 info 承載）。 */
+    recKekSalt?: string;
+    /** 雙因子合鑰包裹前綴（jr2w.，PIN 第二因子）。未配置 = dual API 拒絕（未配置行為不變）。 */
+    wrapDual?: string;
+    /** 雙因子 pin 段 PBKDF2 salt 前綴，如 'journal-note-pin1:'（pinSalt 內嵌 payload 後拼接）。 */
+    pinSaltPrefix?: string;
+    /** 分享包裹前綴（jrsw.，單篇分享連結 V1）。未配置 = share API 拒絕（未配置行為不變）。 */
+    wrapShare?: string;
+    /** 附件密文前綴（jr1c.，image attachments）。未配置 = attach API 拒絕（未配置行為不變）。 */
+    cipherAttach?: string;
+    /** 本機 IDB 密文前綴（jr1d.，notes store stored 形）。未配置 = local API 拒絕（未配置行為不變）。 */
+    cipherLocal?: string;
+    /** localStorage key store（品牌前綴由 keys.ts 管理）。 */
+    store: import('./keys').KeyStore;
+}
+export declare const PBKDF2_ITERATIONS = 600000;
+export declare const PIN_PBKDF2_ITERATIONS = 2000000;
+export declare const IV_LEN = 12;
+export declare function b64(bytes: Uint8Array): string;
+export declare function unb64(text: string): Uint8Array;
+export declare function toHex(bytes: Uint8Array): string;
+export declare function hexToBytes(hex: string): Uint8Array;
+/** SHA-256 hex（分享定位鍵雜湊等呼叫端雜湊用；與伺服器端 sha256Hex 同構）。 */
+export declare function sha256HexExport(text: string): Promise<string>;
+export declare function importAesGcm(raw: Uint8Array, extractable?: boolean): Promise<CryptoKey>;
+export declare function deriveGuestKey(cfg: NoteCryptoConfig, identity: string): Promise<CryptoKey>;
+/** PIN 正規化契約：NFKC → trim → lowercase（不分大小寫；正規化後內含空白由強度檢拒絕）。 */
+export declare function normalizePin(pin: string): string;
+/**
+ * 密語正規化契約 v3（NFKC-only 裁定）：NFKC——**大小寫摺疊禁絕：區分大小寫
+ * （大小寫差＝不同 KEK/ph2）＋首尾空白保留（不 trim）**。
+ * 消費面只有 v3 世代：jr4w./jr4d. 包裹家族與 PH1 v3（derivePh1ArgonV3）——
+ * 舊前綴家族（jr1w./jr3w./jr2w./jr3d.）契約面永不變（raw pass 派生，帶內版本化＝
+ * KEK 輸入契約改變＝換新前綴，禁原地改語意），禁把本函式接進舊家族入口。
+ * 與 normalizePin 契約並存不混（NFKC→trim→lowercase，pinlock/dual 面不動）：
+ * 兩函式是正交契約，閘有「同輸入不同輸出」行為向量承載分離。
+ * 三面單一真相：本體（此處）＋README 家族表＋驗證閘 [15] 行為向量——改 NFKC 語意＝帶內版本化（換世代），禁原地改。
+ */
+export declare function normalizePassphrase(passphrase: string): string;
+/** 雙因子包裹：payload = pinSalt[16] ‖ iv[12] ‖ GCM(KEK2, hex(noteKey))；salt1 隨機由呼叫端存 users.salt。 */
+export declare function wrapNoteKeyDual(cfg: NoteCryptoConfig, noteKey: CryptoKey, passphrase: string, pin: string): Promise<{
+    wrapped: string;
+    salt: string;
+}>;
+/** 雙因子解包：pinSalt 內嵌自描述，salt1 取自 login 回應（與 jr1w 同形）；任何不符回 null，不拋。 */
+export declare function unwrapNoteKeyDual(cfg: NoteCryptoConfig, wrapped: string, passphrase: string, pin: string, salt1Hex: string): Promise<CryptoKey | null>;
+export declare function encryptWithKey(key: CryptoKey, plaintext: string, aad: string): Promise<string>;
+export declare function decryptWithKey(key: CryptoKey, payload: Uint8Array, aad: string): Promise<string | null>;
+export declare function encryptAttach(cfg: NoteCryptoConfig, key: CryptoKey, plaintext: string, aad: string): Promise<string>;
+export declare function decryptAttach(cfg: NoteCryptoConfig, key: CryptoKey, cipher: string, aad: string): Promise<string | null>;
+export declare function encryptLocal(cfg: NoteCryptoConfig, key: CryptoKey, plaintext: string, aad: string): Promise<string>;
+export declare function decryptLocal(cfg: NoteCryptoConfig, key: CryptoKey, cipher: string, aad: string): Promise<string | null>;
+/** 綁定當下生成：random 256-bit AES-GCM key。必須 extractable（包裹靠 exportKey）。 */
+export declare function generateNoteKey(): Promise<CryptoKey>;
+/** 登入憑證：PH1 = SHA-256(pass)——pass 明文從此不過線（伺服器存 PH2）。 */
+export declare function ph1Of(passphrase: string): Promise<string>;
+/** 復原種子：32 bytes hex，只顯示一次；伺服器只收 SHA-256。 */
+export declare function generateRecToken(): string;
+export declare function recTokenHash(recToken: string): Promise<string>;
+/**
+ * 共用包裹核心（收口）：prefix + b64(iv[12] ‖ GCM(KEK, hex(noteKey), aad))。
+ * 鹽外置家族字首家系清點（七呼叫端）：jr1w.（wrapNoteKey）/jrsw.
+ *（wrapNoteKeyShare）/jr3w.（wrapNoteKey3）/jr4w.（wrapNoteKey4）/jr3s.
+ *（wrapNoteKeyShare3）/jr1l.（storeLocalWrap）/jr1r.＋jr1w.（wrapNoteKeyWithRecToken——
+ * HKDF 世代專用前綴＋AAD 'notekey-rec'、未配置世代 legacy 面＝cfg.wrap＋AAD 'notekey'）
+ * 同一本體；KDF 差異在呼叫端 KEK、payload 形狀（salt 外置 vs 內嵌）由各家族維持。
+ * prefix null/undefined＝未配置拒絕（呼叫端亦可先行拒絕，帶自家錯誤碼形；雙防線）。
+ */
+export declare function sealNoteKey(prefix: string | null | undefined, noteKey: CryptoKey, kek: CryptoKey, aad: string): Promise<string>;
+/**
+ * 共用解包核心（收口）：任何不符——前綴、base64 形、payload 長度、
+ * GCM（金鑰/AAD/密文損壞）、rawHex 長度/hex 形——恆回 null 不拋。
+ * 修正紀錄：atob 對非法字元會拋、原 docstring「不拋」與實作不符——
+ * 本體吞收 null（公開原語誠實契約；呼叫端 unwrap 家族 try/catch 是雙防線非依賴面）。
+ * 家族嚴格度收口實況（校正＋殘餘校正；
+ * 七呼叫端帳同步——鹽外置家族字首家系清點，6 點帳已過期）：
+ * 本體嚴格 92B 終結七呼叫端＝note-crypto 四點（unwrapNoteKey＝jr1w／
+ * unwrapNoteKeyShare＝jrsw／unwrapNoteKeyWithRecToken（legacy 面 jr1w.／HKDF 面 jr1r.）
+ * ／loadLocalWrap＝jr1l.）
+ * ＋argon2 三點（unwrapNoteKey3＝jr3w／unwrapNoteKey4＝jr4w／unwrapNoteKeyShare3＝jr3s；
+ * own 92B 檢已隨收口摘除）；
+ * 鹽內嵌 3 點（jr2w/jr3d/jr1p）own 108B＋rawHex 形檢——與本體同嚴格度、刻意不經本體
+ * （pinSalt 前綴不在鹽外置形契約內）。維護本體時鹽內嵌三族不隨行。
+ */
+export declare function openNoteKey(wrapped: string, kek: CryptoKey, aad: string, prefix: string): Promise<CryptoKey | null>;
+/** passphrase 包裹：salt 隨機 16 bytes（hex 存於 users.salt）。 */
+export declare function wrapNoteKey(cfg: NoteCryptoConfig, noteKey: CryptoKey, passphrase: string): Promise<{
+    wrapped: string;
+    salt: string;
+}>;
+export declare function unwrapNoteKey(cfg: NoteCryptoConfig, wrapped: string, passphrase: string, saltHex: string): Promise<CryptoKey | null>;
+/** 分享包裹：salt 隨機 16 bytes（hex 由呼叫端存 shares.salt）。 */
+export declare function wrapNoteKeyShare(cfg: NoteCryptoConfig, noteKey: CryptoKey, sharePass: string): Promise<{
+    wrapped: string;
+    salt: string;
+}>;
+/** 分享解包：salt 取自 GET /shares/:hash 回應（與 jr1w 同形）；任何不符回 null，不拋。 */
+export declare function unwrapNoteKeyShare(cfg: NoteCryptoConfig, wrapped: string, sharePass: string, saltHex: string): Promise<CryptoKey | null>;
+export declare function wrapNoteKeyWithRecToken(cfg: NoteCryptoConfig, noteKey: CryptoKey, recToken: string, identity: string): Promise<string>;
+export declare function unwrapNoteKeyWithRecToken(cfg: NoteCryptoConfig, wrapped: string, recToken: string, identity: string): Promise<CryptoKey | null>;
+/**
+ * 綁定請求的金鑰包裹三件套（bind 用）+ recovery_token_hash。
+ * 兩段 600k PBKDF2 相互獨立（pass 鹽隨機、rec 鹽=recSaltPrefix‖identity 定值）＝並行
+ *（node 實測 133-152ms→68-84ms，與閘執行帳同源）。
+ * AES-GCM derive 佔 600k 迴圈 99%，兩段 wrapped 各自隨機 iv（pass 段另隨機鹽 16B；rec 腿
+ * KEK 鹽定值、回傳 salt 來自 pass 腿 w1）——逐位等值帳由
+ * 「兩段各自與 wrapNoteKey 直呼相等」承載。
+ */
+export declare function buildBindPayload(cfg: NoteCryptoConfig, noteKey: CryptoKey, passphrase: string, recToken: string, identity: string): Promise<{
+    wrapped: string;
+    salt: string;
+    wrappedRec: string;
+    recTokenHash: string;
+}>;
+/**
+ * 本機包裹：KEK = deriveGuestKey（identity 派生、passphrase-free——
+ * session 期免重打密語的機制原樣），payload 改走專用前綴 cfg.wrapLocal（jr1l.）。
+ * 舊實作借用 cfg.wrap（jr1w. passphrase 包裹前綴）寫本機包裹＝「一個前綴一份契約」
+ * 的第二違例（wrappedRec 專用前綴歸 v0.2.0 世代收口）：本機包裹的 KDF 與 caller 不同、
+ * 儲存面（localStorage）不同、生命週期不同（clearLocalWrap 隨時摘除）——共前綴讓
+ * 「本機字串是否可能誤入 server 包裹欄」對帳失真。新前綴＝讀舊寫新自癒：
+ * loadLocalWrap 先試 jr1l.（本體嚴格面），命中舊形（jr1w.）回落解密後即重包
+ * cfg.wrapLocal 回寫（自癒一次），寫入恆 jr1l.。
+ */
+export declare function storeLocalWrap(cfg: NoteCryptoConfig, identity: string, noteKey: CryptoKey): Promise<void>;
+export declare function clearLocalWrap(cfg: NoteCryptoConfig, identity: string): void;
+export interface HeldKey {
+    get(): CryptoKey | null;
+    set(key: CryptoKey | null): void;
+}
+export declare function makeHeldKey(): HeldKey;
+export interface IdentityProvider {
+    /** 當前身份字串（guest 派生與本機包裹的命名空間，如 account_id）。 */
+    current(): string;
+}
+/** 加密一則：綁定時代持有 noteKey → cipherBound；否則 guest key → cipherGuest
+ *  （guest 前綴選配：未配置＝ERR_GUEST_NOT_CONFIGURED，bound 路徑不受牽連）。
+ *  held 為空時先試本機包裹（reload / PWA 續存期免重打密語）。 */
+export declare function encryptNote(cfg: NoteCryptoConfig, held: HeldKey, plaintext: string, aad: string, idp: IdentityProvider): Promise<string>;
+/** 解密一則：按前綴選鑰匙；無前綴 = 舊版明文（相容層）原樣返回（guest 前綴未配置時
+ *  不明字串一律 null＝guest 家族整面拒絕，跨前綴鐵律不降級）；失敗回 null。 */
+export declare function decryptNote(cfg: NoteCryptoConfig, held: HeldKey, cipher: string, aad: string, idp: IdentityProvider): Promise<string | null>;