@tacet-ink/journal-core 0.1.2 → 0.1.4

package/README.md

@@ -1,5 +1,10 @@
 # @tacet-ink/journal-core
 
+[![npm](https://img.shields.io/npm/v/@tacet-ink/journal-core.svg)](https://www.npmjs.com/package/@tacet-ink/journal-core)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/%40tacet-ink%2Fjournal-core.svg)](./package.json)
+[![verify](https://img.shields.io/github/actions/workflow/status/tacet-ink/journal-core/verify.yml?branch=main&label=verify)](https://github.com/tacet-ink/journal-core/actions/workflows/verify.yml)
+
 零知識日記核心：端對端加密、密語即身份的 auth、傳輸與限流原語。
 伺服器看不到任何一個字：passphrase 永不過線，密鑰包裹與密文都在客戶端完成。
 
@@ -16,8 +21,9 @@
   前綴全部可配置，AAD（防搬移繫結）由呼叫端傳入。
 - **extractable 鐵律**：要被 exportKey/wrap 的 key（noteKey 全部產生路徑），
   import 當下就必須 `extractable=true`；KEK/guest key 恆 nonextractable。
-- **opt-in 原語**：選配契約（wrapDual／wrapShare／pinLock）未配置即拒絕，
-  不配置的產品行為完全不受影響。
+- **opt-in 原語**：選配契約（cipherGuest／wrapDual／wrapShare／pinLock／cipherAttach／cipherLocal）
+  未配置即拒絕，不配置的產品行為完全不受影響（cipherGuest 未配置時 bound 路徑不受牽連，
+  解密面 guest 家族整面拒絕、不明字串不當明文顯示）。
 
 ## 模組
 
@@ -32,7 +38,7 @@
 | `src/server/ratelimit.ts` | per-IP 滑動視窗限流（D1 計數，併發安全版） |
 | `src/server/cors.ts`／`hash.ts` | 共用 CORS／雜湊工具（`src/server/env.ts` 為內部 Env 介面，不入 exports） |
 
-## 前綴契約（家族表：8 個資料前綴＋閘對照組 jr1g.）
+## 前綴契約（家族表：10 個資料前綴＋閘對照組 jr1g.）
 
 前綴是版本契約：payload 佈局與 KDF 由前綴界定，升級 = 新前綴。
 Tacet 部署實例（config 傳入）：
@@ -41,6 +47,8 @@ Tacet 部署實例（config 傳入）：
 | --- | --- | --- | --- |
 | `jr1u.` | guest 時代密文 | K_u = SHA-256(guestKdfPrefix ‖ identity) | AES-GCM |
 | `jr1b.` | 綁定時代密文 | 隨機 256-bit noteKey | AES-GCM，AAD 綁 noteId |
+| `jr1c.` | 附件密文（image attachments；選配） | 同筆記金鑰（noteKey／guest key 由呼叫端決定） | AES-GCM，AAD `jr1a:<noteId>:<attachId>` |
+| `jr1d.` | 本機 IDB stored 密文（notes store；選配） | 同筆記金鑰（呼叫端注入） | AES-GCM，AAD 綁 note_id，payload 自帶 `v` 欄 |
 | `jr1w.` | passphrase 包裹＋復原套件包裹 | PBKDF2-SHA256 600k | b64(iv[12] ‖ GCM(hex(noteKey)))，AAD `notekey` |
 | `jr2w.` | PIN 第二因子合鑰（PBKDF2 版） | PBKDF2 600k(pass)＋2M(pin) → HKDF-SHA256 | pinSalt[16] ‖ iv[12] ‖ GCM，108B，AAD `notekey2` |
 | `jr3w.` | passphrase 包裹（Argon2id 版） | Argon2id m=64MiB t=3 p=1 tag=32B | 同 jr1w. 形，AAD `notekey` |
@@ -54,7 +62,7 @@ guest 密文前綴在閘對照組另驗 `jr1g.`（閘自造前綴，驗證品牌
 ## 驗證
 
 ```sh
-npm run verify   # 102 斷言對真模組（禁鏡像）：roundtrip/AAD 防搬移/extractable/時代隔離/
+npm run verify   # 127 斷言對真模組（禁鏡像）：roundtrip/AAD 防搬移/extractable/時代隔離/
                  # 跨前綴家族隔離/payload 竄改/RFC 9106 KAT/BIP39 @scure 對照 200 組
 ```
 
@@ -85,7 +93,7 @@ const cfg = {
   cipherBound: 'jr1b.',
   wrap: 'jr1w.',
   store: makeKeyStore({ brand: 'myapp' }),
-  // wrapDual / wrapShare / pinLock：選配，未配置即拒絕
+  // cipherGuest / wrapDual / wrapShare / pinLock / cipherAttach / cipherLocal：選配，未配置即拒絕
 };
 
 const held = makeHeldKey();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tacet-ink/journal-core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Zero-knowledge journal core — e2e crypto, passphrase-only auth, transport, ratelimit. The server never sees plaintext.",
   "homepage": "https://tacet.ink",
   "repository": {

package/scripts/verify-core-crypto.ts

@@ -22,6 +22,10 @@ import {
   wrapNoteKeyDual,
   unwrapNoteKeyDual,
   normalizePin,
+  encryptAttach,
+  decryptAttach,
+  encryptLocal,
+  decryptLocal,
 } from '../src/client/note-crypto.ts';
 import {
   verifyArgonKat,
@@ -360,18 +364,26 @@ await A('23 詞 → null', (await bip.wordsToRecToken(kitWords.slice(0, 23).join
 await A('25 詞 → null', (await bip.wordsToRecToken([...kitWords, kitWords[0]].join(' '))) === null);
 await A('詞表外 → null', (await bip.wordsToRecToken(kitWords.slice(0, 23).concat('notaword').join(' '))) === null);
 
-// checksum 面：錯一詞（詞表內不同詞）→ 幾乎必被 checksum 抓；64 樣本全抓（理論 255/256，樣本容許 ≥63）
+// checksum 面：錯一詞（詞表內不同詞）→ 幾乎必被 checksum 抓；固定種子 64 樣本全抓。
+// （t_d1cf3846：真隨機取樣時 P(漏 ≥2)≈0.4%＝偶發 62/64 flake 實證——改 xorshift 常數
+// 種子樣本集（bip39.seededSampleBytes），向量可重放、閘輸出逐輪恆定；種子窗 1..64
+// 經五窗 320 樣本探針驗證全抓後採用，非挑窗）
 const wlArr: readonly string[] = wl.wordlist;
 let checksumCaught = 0;
 for (let t = 0; t < 64; t++) {
-  const ws = [...(await bip.generateBip39Words())];
+  const ws = [...(await bip.generateBip39Words(bip.seededSampleBytes(1 + t)))];
   const idx = t % 24;
   let alt = wlArr[(wlArr.indexOf(ws[idx]) + 1 + t) % 2048];
   if (alt === ws[idx]) alt = wlArr[(wlArr.indexOf(ws[idx]) + 1) % 2048];
   ws[idx] = alt;
   if ((await bip.wordsToRecToken(ws.join(' '))) === null) checksumCaught++;
 }
-await A('錯一詞 64 樣本 ≥63 被抓（checksum 8-bit）', checksumCaught >= 63, `caught=${checksumCaught}/64`);
+await A('錯一詞固定種子 64 樣本全抓（checksum 8-bit；flake 歸零）', checksumCaught === 64, `caught=${checksumCaught}/64`);
+const detA = await bip.generateBip39Words(bip.seededSampleBytes(20260919));
+const detB = await bip.generateBip39Words(bip.seededSampleBytes(20260919));
+const detC = await bip.generateBip39Words(bip.seededSampleBytes(20260920));
+await A('種子樣本確定性（同 seed 逐字同詞、異 seed 異詞；產品面無參數真隨機不變）',
+  detA.join(' ') === detB.join(' ') && detA.join(' ') !== detC.join(' '));
 
 // spot-check 抽驗索引
 const picks = bip.spotCheckIndexes();
@@ -404,6 +416,96 @@ await A('words 派生 hex64 包裹前綴 jr1w.', kitWrapped.startsWith('jr1w.'))
 await A('words 派生 hex64 unwrap 救回 noteKey',
   (await unwrapNoteKeyWithRecToken(TACET, kitWrapped, kitHexAsToken, identityA)) !== null);
 
+// ── 10. 附件密文（jr1c.，image attachments；opt-in 未配置即拒） ───────────────
+
+console.log('\n[10] 附件密文（jr1c. cipherAttach opt-in）');
+const bareCfgAttach: NoteCryptoConfig = { ...TACET }; // 無 cipherAttach 欄
+let attachCfgThrow = '';
+try { await encryptAttach(bareCfgAttach, noteKey, '{"v":1}', 'jr1a:n1:a1'); } catch (e) { attachCfgThrow = (e as Error).message; }
+await A('未配置 cipherAttach → encryptAttach throw', attachCfgThrow === 'ERR_ATTACH_NOT_CONFIGURED', attachCfgThrow);
+
+const TACET_ATTACH: NoteCryptoConfig = { ...TACET, cipherAttach: 'jr1c.' };
+const attachAad = 'jr1a:note-abc:att-001';
+const attachPayload = JSON.stringify({ v: 1, kind: 'img', mime: 'image/jpeg', w: 2048, h: 1365, b64: b64(new Uint8Array(2048)) });
+const attachCt = await encryptAttach(TACET_ATTACH, noteKey, attachPayload, attachAad);
+await A('附件前綴 jr1c.', attachCt.startsWith('jr1c.'));
+await A('附件 roundtrip（顯式 noteKey）',
+  (await decryptAttach(TACET_ATTACH, noteKey, attachCt, attachAad)) === attachPayload);
+await A('附件 AAD 防搬移：錯 attachment_id → null',
+  (await decryptAttach(TACET_ATTACH, noteKey, attachCt, 'jr1a:note-abc:att-999')) === null);
+await A('附件錯鑰匙 → null',
+  (await decryptAttach(TACET_ATTACH, await generateNoteKey(), attachCt, attachAad)) === null);
+
+// ── 11. 本機 IDB 密文（jr1d. cipherLocal opt-in）＋ guest 選配拒絕面 ──────────
+
+console.log('\n[11] 本機 IDB 密文（jr1d. cipherLocal opt-in）＋ guest 選配');
+const bareCfgLocal: NoteCryptoConfig = { ...TACET }; // 無 cipherLocal 欄
+let localCfgThrow = '';
+try { await encryptLocal(bareCfgLocal, noteKey, '{}', 'jr1:n1'); } catch (e) { localCfgThrow = (e as Error).message; }
+await A('未配置 cipherLocal → encryptLocal throw', localCfgThrow === 'ERR_LOCAL_NOT_CONFIGURED', localCfgThrow);
+
+const TACET_LOCAL: NoteCryptoConfig = { ...TACET, cipherLocal: 'jr1d.' };
+const localAad = 'jr1:note-abc';
+const localPayload = JSON.stringify({ v: 1, text: '今天寫了一點東西。', title: '標題' });
+const localCt = await encryptLocal(TACET_LOCAL, noteKey, localPayload, localAad);
+await A('本機前綴 jr1d.', localCt.startsWith('jr1d.'));
+await A('本機 roundtrip（bound noteKey）', (await decryptLocal(TACET_LOCAL, noteKey, localCt, localAad)) === localPayload);
+await A('本機 AAD 防搬移：錯 note_id → null', (await decryptLocal(TACET_LOCAL, noteKey, localCt, 'jr1:note-zzz')) === null);
+await A('本機錯鑰匙 → null', (await decryptLocal(TACET_LOCAL, await generateNoteKey(), localCt, localAad)) === null);
+
+// Era 0 形：guest key（呼叫端派生注入，與 IDB store 層同構）
+const localGuest = await (async () => {
+  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', enc.encode('tacet-note-u1' + identityA)));
+  return crypto.subtle.importKey('raw', digest, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+})();
+const localCtGuest = await encryptLocal(TACET_LOCAL, localGuest, localPayload, localAad);
+await A('本機 roundtrip（Era 0 guest key）', (await decryptLocal(TACET_LOCAL, localGuest, localCtGuest, localAad)) === localPayload);
+
+// 跨前綴隔離：jr1d. 非 jr1c./jr1b./jr1u.；他家族入口不吃本機密文
+await A('本機密文非附件/筆記前綴',
+  !localCt.startsWith('jr1c.') && !localCt.startsWith('jr1b.') && !localCt.startsWith('jr1u.'));
+await A('decryptAttach 拒收 jr1d.', (await decryptAttach(TACET_ATTACH, noteKey, localCt, localAad)) === null);
+await A('decryptLocal 拒收 jr1c.', (await decryptLocal(TACET_LOCAL, noteKey, attachCt, attachAad)) === null);
+await A('decryptNote 對未配置的 jr1d.＝未知前綴相容層原樣（不誤判不誤解）',
+  (await decryptNote({ ...TACET }, makeHeldKey(), localCt, localAad, { current: () => identityA })) === localCt);
+
+// payload 竄改 → GCM 驗證失敗 → null（iv 區 byte 3／ct 尾最後一位元組；索引以解碼後
+// 位元組面計——b64 字串索引會越界靜默 no-op＝假紅，閘毒化同族教訓）
+const tamperLocal = async (byteIdx: number): Promise<boolean> => {
+  const bin = atob(localCt.slice('jr1d.'.length));
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  if (byteIdx < 0 || byteIdx >= bytes.length) return false; // 索引自守衛：越界即顯性失敗
+  bytes[byteIdx] ^= 0x01;
+  let out = '';
+  for (let i = 0; i < bytes.byteLength; i++) out += String.fromCharCode(bytes[i]);
+  return (await decryptLocal(TACET_LOCAL, noteKey, 'jr1d.' + btoa(out), localAad)) === null;
+};
+await A('本機 payload 竄改 iv 區 → null', await tamperLocal(3));
+await A('篡改索引越界＝顯性失敗（runner 自檢：靜默 no-op 即假紅）', await tamperLocal(-1) === false);
+await A('本機 payload 竄改 ct 尾 → null', await tamperLocal(59));
+
+// guest 選配未配置拒絕面（2026-09-19 收編：cipherGuest 轉選配；未配置即拒鐵律）
+const TACET_NOGUEST: NoteCryptoConfig = { ...TACET, cipherGuest: undefined };
+const guestThrowsMsg = async (): Promise<string | null> => {
+  try { await encryptNote(TACET_NOGUEST, makeHeldKey(), note, 'noteId:n1', { current: () => identityA }); return null; }
+  catch (e) { return (e as Error).message; }
+};
+await A('未配置 cipherGuest → encryptNote guest 路徑 throw ERR_GUEST_NOT_CONFIGURED',
+  (await guestThrowsMsg()) === 'ERR_GUEST_NOT_CONFIGURED');
+const heldBound = makeHeldKey();
+heldBound.set(noteKey);
+await A('未配置 guest 的 bound 加密不受牽連',
+  (await encryptNote(TACET_NOGUEST, heldBound, note, 'noteId:n1', { current: () => identityA })).startsWith('jr1b.'));
+await A('未配置 guest → decryptNote guest 密文 null',
+  (await decryptNote(TACET_NOGUEST, makeHeldKey(), cipherGuest, 'noteId:n1', { current: () => identityA })) === null);
+await A('未配置 guest → decryptNote 不明字串 null（guest 家族整面拒絕、不當明文顯示）',
+  (await decryptNote(TACET_NOGUEST, makeHeldKey(), 'jr9x.somestring', 'x', { current: () => identityA })) === null);
+await A('配置 guest → decryptNote 舊明文相容層原樣（既有契約不變）',
+  (await decryptNote(TACET, makeHeldKey(), '純舊明文', 'x', { current: () => identityA })) === '純舊明文');
+await A('既有 guest 配置 roundtrip 不受選配收編影響',
+  (await decryptNote(TACET, makeHeldKey(), cipherGuest, 'noteId:n1', { current: () => identityA })) === note);
+
 // ── 決議 ────────────────────────────────────────────────────────────────────
 
 console.log(`\n${passed} 斷言全綠` + (failures.length ? `；${failures.length} 失敗` : ''));

package/src/client/bip39.ts

@@ -74,13 +74,40 @@ function indexesToBytes(indexes: number[]): Uint8Array {
   return out; // 24 詞 = 264 bits = 33 bytes 整除，無餘位（11-bit 打包自洽）
 }
 
-/** 產生 24 詞套件（entropy 32B 隨機 → +8-bit checksum → 24 詞）。 */
-export async function generateBip39Words(): Promise<string[]> {
-  const entropy = crypto.getRandomValues(new Uint8Array(32));
+/** 產生 24 詞套件（entropy 32B 隨機 → +8-bit checksum → 24 詞）。
+ *  entropyBytes 可注入（驗證閘固定種子樣本用；產品面不傳＝真隨機契約不變）。 */
+export async function generateBip39Words(entropyBytes?: Uint8Array): Promise<string[]> {
+  const entropy = entropyBytes ?? crypto.getRandomValues(new Uint8Array(32));
   const checksum = (await sha256(entropy))[0];
   return entropyToIndexes(entropy, checksum).map(idx => wordlist[idx]);
 }
 
+// ── 驗證閘固定種子樣本（flake 歸零；t_d1cf3846）──────────────────────────────
+//
+// 背景：checksum 統計面「錯一詞 64 樣本 ≥63 被抓」用真隨機取樣時，P(漏 ≥2)≈0.4%，
+// 偶發 62/64＝閘 flake（2026-09-19 session 實證）。治本是固定種子：xorshift32 以
+// 常數 seed 產生確定性位元組流（種子決定樣本集＝向量可重放、閘輸出逐輪恆定）。
+// 樣本集僅供驗證閘使用（checksum 是 BIP39 公開數學，非機密；產品面
+// generateBip39Words() 不帶參數＝crypto.getRandomValues 真隨機契約不變）。
+
+function xorshift32Bytes(seed: number, len: number): Uint8Array {
+  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: number): Uint8Array {
+  return xorshift32Bytes(seed, 32);
+}
+
 /** 24 詞 → recToken hex64。任何不符（字數/詞表外/checksum）回 null，不洩漏哪類錯。 */
 export async function wordsToRecToken(input: string | string[]): Promise<string | null> {
   const words = typeof input === 'string' ? normalizeWords(input) : input.map(w => w.normalize('NFKC').trim().toLowerCase());

package/src/client/note-crypto.ts

@@ -27,8 +27,8 @@ export interface NoteCryptoConfig {
   guestKdfPrefix: string;
   /** 復原包裹 KDF salt 前綴，如 'journal-note-rec1:'。 */
   recSaltPrefix: string;
-  /** 密文前綴：guest 時代，如 'jr1g.'。 */
-  cipherGuest: string;
+  /** 密文前綴：guest 時代，如 'jr1g.'。未配置 = guest API 拒絕（未配置行為不變；2026-09-19 選配收編）。 */
+  cipherGuest?: string;
   /** 密文前綴：綁定時代，如 'jr1b.'。 */
   cipherBound: string;
   /** 金鑰包裹前綴，如 'jr1w.'。 */
@@ -39,6 +39,10 @@ export interface NoteCryptoConfig {
   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;
 }
@@ -87,7 +91,7 @@ export async function importAesGcm(raw: Uint8Array, extractable = false): Promis
   return crypto.subtle.importKey('raw', raw as BufferSource, { name: 'AES-GCM' }, extractable, ['encrypt', 'decrypt']);
 }
 
-async function deriveGuestKey(cfg: NoteCryptoConfig, identity: string): Promise<CryptoKey> {
+export async function deriveGuestKey(cfg: NoteCryptoConfig, identity: string): Promise<CryptoKey> {
   const material = new TextEncoder().encode(cfg.guestKdfPrefix + identity);
   const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', material));
   return importAesGcm(digest);
@@ -218,6 +222,49 @@ export async function decryptWithKey(key: CryptoKey, payload: Uint8Array, aad: s
   }
 }
 
+// ── 附件密文（jr1c.，image attachments；金鑰由呼叫端決定） ────────────────────
+//
+// 附件用既有 noteKey（綁定後）或 guest key（Era 0 純本地），零新金鑰管理；
+// AAD 帶 'jr1a:<note_id>:<attachment_id>'（綁篇＋綁附件，跨列搬移必失敗）。
+// 前綴 cfg opt-in（未配置即拒）：兄弟 fork 不配置＝API 拒絕，行為不變。
+
+export async function encryptAttach(cfg: NoteCryptoConfig, key: CryptoKey, plaintext: string, aad: string): Promise<string> {
+  if (!cfg.cipherAttach) throw new Error('ERR_ATTACH_NOT_CONFIGURED');
+  return cfg.cipherAttach + await encryptWithKey(key, plaintext, aad);
+}
+
+export async function decryptAttach(cfg: NoteCryptoConfig, key: CryptoKey, cipher: string, aad: string): Promise<string | null> {
+  try {
+    if (!cfg.cipherAttach) return null;
+    if (!cipher.startsWith(cfg.cipherAttach)) return null;
+    return await decryptWithKey(key, unb64(cipher.slice(cfg.cipherAttach.length)), aad);
+  } catch {
+    return null;
+  }
+}
+
+// ── 本機 IDB 密文（jr1d.，notes store stored 形；金鑰由呼叫端決定） ──────────
+//
+// IDB 持久形密文：bound 態＝held noteKey、Era 0＝guest key（兩者皆由呼叫端注入；
+// 鑰匙狀態機在呼叫端 store 層，core 只承載前綴與對稱本體）。payload 自帶 {v:1,...}
+// 版本欄（呼叫端 JSON 面），前綴即可辨識；AAD 綁 note_id（呼叫端契約，跨列搬移必失敗）。
+// 前綴 cfg opt-in（未配置即拒）：兄弟 fork 不配置＝API 拒絕，行為不變。
+
+export async function encryptLocal(cfg: NoteCryptoConfig, key: CryptoKey, plaintext: string, aad: string): Promise<string> {
+  if (!cfg.cipherLocal) throw new Error('ERR_LOCAL_NOT_CONFIGURED');
+  return cfg.cipherLocal + await encryptWithKey(key, plaintext, aad);
+}
+
+export async function decryptLocal(cfg: NoteCryptoConfig, key: CryptoKey, cipher: string, aad: string): Promise<string | null> {
+  try {
+    if (!cfg.cipherLocal) return null;
+    if (!cipher.startsWith(cfg.cipherLocal)) return null;
+    return await decryptWithKey(key, unb64(cipher.slice(cfg.cipherLocal.length)), aad);
+  } catch {
+    return null;
+  }
+}
+
 // ── noteKey（時代 2）─────────────────────────────────────────────────────────
 
 /** 綁定當下生成：random 256-bit AES-GCM key。必須 extractable（包裹靠 exportKey）。 */
@@ -385,7 +432,8 @@ export interface IdentityProvider {
   current(): string;
 }
 
-/** 加密一則：綁定時代持有 noteKey → cipherBound；否則 guest key → cipherGuest。
+/** 加密一則：綁定時代持有 noteKey → cipherBound；否則 guest key → cipherGuest
+ *  （guest 前綴選配：未配置＝ERR_GUEST_NOT_CONFIGURED，bound 路徑不受牽連）。
  *  held 為空時先試本機包裹（reload / PWA 續存期免重打密語）。 */
 export async function encryptNote(
   cfg: NoteCryptoConfig,
@@ -401,11 +449,13 @@ export async function encryptNote(
   if (held.get()) {
     return cfg.cipherBound + await encryptWithKey(held.get()!, plaintext, aad);
   }
+  if (!cfg.cipherGuest) throw new Error('ERR_GUEST_NOT_CONFIGURED'); // guest 路徑選配：未配置即拒（bound 路徑不受牽連）
   const guest = await deriveGuestKey(cfg, idp.current());
   return cfg.cipherGuest + await encryptWithKey(guest, plaintext, aad);
 }
 
-/** 解密一則：按前綴選鑰匙；無前綴 = 舊版明文（相容層）原樣返回；失敗回 null。 */
+/** 解密一則：按前綴選鑰匙；無前綴 = 舊版明文（相容層）原樣返回（guest 前綴未配置時
+ *  不明字串一律 null＝guest 家族整面拒絕，跨前綴鐵律不降級）；失敗回 null。 */
 export async function decryptNote(
   cfg: NoteCryptoConfig,
   held: HeldKey,
@@ -414,12 +464,17 @@ export async function decryptNote(
   idp: IdentityProvider,
 ): Promise<string | null> {
   try {
-    const isGuest = cipher.startsWith(cfg.cipherGuest);
+    const guestPrefix = cfg.cipherGuest;
+    const isGuest = guestPrefix !== undefined && cipher.startsWith(guestPrefix);
     const isBound = cipher.startsWith(cfg.cipherBound);
-    if (!isGuest && !isBound) return cipher; // 舊版明文（相容層）：原樣顯示
+    if (!isGuest && !isBound) {
+      // 舊版明文（相容層）原樣返回；guest 前綴未配置＝guest 家族整面拒絕（不明字串
+      // 一律 null——跨前綴鐵律「回 null 不降級」，避免他家族殘列被當明文顯示）。
+      return guestPrefix === undefined ? null : cipher;
+    }
     if (isGuest) {
       const guest = await deriveGuestKey(cfg, idp.current());
-      return await decryptWithKey(guest, unb64(cipher.slice(cfg.cipherGuest.length)), aad);
+      return await decryptWithKey(guest, unb64(cipher.slice(guestPrefix!.length)), aad);
     }
     if (!held.get()) {
       const identity = idp.current();

package/src/index.ts

@@ -8,6 +8,10 @@ export {
   generateNoteKey,
   encryptNote,
   decryptNote,
+  encryptAttach,
+  decryptAttach,
+  encryptLocal,
+  decryptLocal,
   wrapNoteKey,
   unwrapNoteKey,
   wrapNoteKeyWithRecToken,