@tacet-ink/journal-core 0.3.5 → 0.4.1

package/README.md

@@ -69,7 +69,7 @@ run: `npm install @tacet-ink/journal-core && node example.mts`（0.3.4 起；Nod
 ```sh
 git clone https://github.com/tacet-ink/journal-core.git && cd journal-core
 npm ci --ignore-scripts
-npm run verify   # 531 assertions, all green, run against the real modules (no mocks); needs this repo checkout — the published package is dist-only since 0.3.4 (no gate, no src/, no scripts/)
+npm run verify   # 575 assertions, all green, run against the real modules (no mocks); needs this repo checkout — the published package is dist-only since 0.3.4 (no gate, no src/, no scripts/)
 ```
 
 上例為高階 Vault API；錯誤碼見[例外契約](#例外契約錯誤碼語意)（`VaultError` 表）。低階原語範例（note-crypto 兩時代加解密、前綴自配）與完整 API 見[使用（Usage）](#使用usage)節。Live product: [https://tacet.ink](https://tacet.ink)
@@ -101,9 +101,9 @@ npm run verify   # 531 assertions, all green, run against the real modules (no m
 | `src/client/pinlock.ts` | 本機 PIN 鎖定包裹（jr1p.，開啟時鎖定） |
 | `src/client/bip39.ts` | 復原套件 24 詞 ⇄ hex64 轉寫層（BIP39，零依賴自製） |
 | `src/client/keys.ts` | 品牌前綴 localStorage 命名空間 |
-| `src/server/auth.ts` | 零知識 auth 核心：PH1→PH2 login 動線、入庫格式驗證、包裹欄組成對（pair 檢查 pickKeyPackage）；PH2 UNIQUE 衝突與 session 撤銷＝呼叫端職責 |
+| `src/server/auth.ts` | 零知識 auth 核心：PH1→PH2 login 動線、入庫格式驗證、包裹欄組成對（pair 檢查 pickKeyPackage）；PH2 UNIQUE 衝突與 session 撤銷＝呼叫端職責；PH2 落庫形派生 `AuthStore.ph2Of?`（optional，0.4.0）＝pepper 收口注入點（未注入＝`sha256Hex(PH1)` 單查零變） |
 | `src/server/ladder.ts` | 密語正規化 v3 世代 ladder 表原語（ph2_ladder：以舊 ph2 查列／遷移入表 upsert 值主權威）＋幽靈守衛查表接線已內建 loginRouteCore——fork 只需配 `ladderLookup` store＋0011 migration（未配置＝單查行為零變） |
-| `src/server/ratelimit.ts` | per-IP fixed-window 限流（單句 UPSERT…RETURNING；D1 計數，跨 isolate 有效；IPv6 鍵經 `normalizeRateIp` 聚合至 /64；IPv4-mapped 位址回點分 IPv4 鍵（＝原生同 /32 鍵）） |
+| `src/server/ratelimit.ts` | per-IP fixed-window 限流（單句 UPSERT…RETURNING；D1 計數，跨 isolate 有效；IPv6 鍵經 `normalizeRateIp` 聚合至 /64；IPv4-mapped 位址回點分 IPv4 鍵（＝原生同 /32 鍵）；0.4.1 第二層粗桶 `normalizeRateIpCoarse`（/48|/24）＋`checkRateLadder` 雙窗＋`bumpRate` opts.fallbackInMemory 記憶體退避＋`globalLoginBump` 全站計數——粗桶/全站計數表由呼叫端自建表＋GC 承載（tacet maintenance 母型），core 不代建） |
 | `src/server/cors.ts`／`hash.ts` | 共用 CORS／雜湊工具（`src/server/env.ts` 為內部 Env 介面，不入 exports） |
 
 發行形（0.3.0 起）：`dist/`＝tsc 原生 emit 的 ESM `.js`＋`.d.ts`，`exports` 全部子路徑指向 dist。
@@ -111,7 +111,7 @@ npm run verify   # 531 assertions, all green, run against the real modules (no m
 不再隨包（驗證閘與向量產生器為 repo 樹面，走源碼 clone 動線）；稽核／閱讀路徑＝GitHub 瀏覽 `src/`＋
 [docs/format-spec.md](./docs/format-spec.md) 規格＋[docs/vectors/](./docs/vectors/) 向量（`docs/` 仍隨包）。
 
-## 前綴契約（家族表：13 個資料前綴＋閘對照組 jr1g.）
+## 前綴契約（家族表：15 個資料前綴＋閘對照組 jr1g.）
 
 前綴是版本契約：payload 佈局與 KDF 由前綴界定，升級 = 新前綴。
 逐位元組布局、KDF 參數、AAD 與世代契約的完整規格見 [docs/format-spec.md](./docs/format-spec.md)，
@@ -132,7 +132,8 @@ Tacet 部署實例（config 傳入）：
 | `jr3d.` | PIN 第二因子合鑰（Argon2id 版） | Argon2id(pass)＋Argon2id(pin) → HKDF-SHA256 | 同 jr2w. 形，108B，AAD `notekey2` |
 | `jr4w.` | passphrase 包裹（密語正規化 v3 世代） | Argon2id(normalizePassphrase(pass)，NFKC-only) 同上參數 | 同 jr1w./jr3w. 形，AAD `notekey` |
 | `jr4d.` | PIN 第二因子合鑰（密語正規化 v3 世代） | Argon2id(normalizePassphrase(pass))＋Argon2id(pin) → HKDF-SHA256 | 同 jr2w./jr3d. 形，108B，AAD `notekey2` |
-| `jr3s.` | 單篇分享連結包裹 | Argon2id（同上參數） | 同 jr1w. 形，AAD `notekey-share` |
+| `jrsw.` | 分享包裹 V1（PBKDF2 版；建立面退役，讀取面兩代並行保留） | PBKDF2-SHA256 600k | 同 jr1w. 形，AAD `notekey-share`（⚠️ 不可傳入帳戶主鑰 noteKey——分享包裹的金鑰範圍＝該次分享；傳主鑰＝收分享者可解全帳戶（J1；tacet 親例）） |
+| `jr3s.` | 單篇分享連結包裹（Argon2id 版；`createShareEnvelope` 高階組裝產出） | Argon2id（同上參數） | 同 jr1w. 形，AAD `notekey-share`（⚠️ 不可傳入帳戶主鑰 noteKey——分享包裹的金鑰範圍＝該次分享；傳主鑰＝收分享者可解全帳戶（J1；tacet 親例）） |
 | `jr1p.` | 本機 PIN 鎖定（開啟時鎖定） | PBKDF2-SHA256 600k（刻意不用 Argon2id：解鎖要即時） | 同 jr2w. 形，AAD `notekey-pinlock` |
 
 guest 密文前綴在閘對照組另驗 `jr1g.`（閘自造前綴，驗證品牌參數化本身；tacet 部署實例 guest 用 `jr1u.`）。
@@ -152,7 +153,7 @@ jr3d/jr4d 兩入參數同輸入，域分離由 info 承載；凍結 KAT 兩 blob
 
 ```sh
 npm ci --ignore-scripts
-npm run verify   # 531 斷言對真模組（禁鏡像；限流單句 UPSERT…RETURNING 直載真 SQLite）：roundtrip/AAD 防搬移/
+npm run verify   # 575 斷言對真模組（禁鏡像；限流單句 UPSERT…RETURNING 直載真 SQLite）：roundtrip/AAD 防搬移/
                  # extractable/時代隔離/跨前綴家族隔離/payload 竄改/RFC 9106 KAT/BIP39 @scure 對照 200 組/
                  # server-side（inboundCipher/validWrappedKey/pickKeyPackage/checkRate/timingSafeEq）+ pinlock 全函式
                  # + 密語正規化 v3 世代（normalizePassphrase／jr4w./jr4d.／PH1 v3 鹽域分離＋帶內版本化舊契約向量）
@@ -164,10 +165,11 @@ npm run verify   # 531 斷言對真模組（禁鏡像；限流單句 UPSERT…RE
                  # ＋KAT 凍結向量 [17]（HKDF info 域世代分離＋v3/raw 入口契約四 blob）
                  # ＋包裹前綴快檢 [13-2]（錯前綴試探免付 KDF：五入口行為＋計時帽＋計數錨）
                  # ＋CI 供應鏈面 [21]（npm ci --ignore-scripts＋dependabot runner fromJSON 分流＋腳本摘除＋NIT-1 錨＋r2 MINOR-1 URL 直傳；
-                 #   531 帳＝repo 樹——workflow 錨在 .github＝repo 樹恆在、四條全跑；包內 SKIP 對照帳段隨 0.3.4 dist-only 瘦身退役：發行包不再帶閘＝無包內帳可言）
+                 #   575 帳＝repo 樹——workflow 錨在 .github＝repo 樹恆在、四條全跑；包內 SKIP 對照帳段隨 0.3.4 dist-only 瘦身退役：發行包不再帶閘＝無包內帳可言）
                  # ＋發行 tarball 治理面 [22]（pack 白名單零 open-card-pr.sh）
                  # ＋格式規格＋測試向量 [26]（docs/format-spec.md＋docs/vectors 存在性／位元組 shape／欄位名對規格／凍結 KAT 逐字對閘）
                  # ＋高階 Vault API [27]（roundtrip 三形／新舊前綴解鎖／upgrade／換密語／復原／VaultError 毒化／載體覆寫＋Worker 回退鏈／vendor 孿生）
+                 # ＋分享 envelope 高階 API [28]（createShareEnvelope：一次性 shareKey 與主鑰隔離＋jr3s. 包裹三件組＋無狀態純函數毒化錨）
 ```
 
 - 產品碼**零執行時依賴**（WebCrypto 原語）；devDependencies 僅閘用（typescript、@scure/bip39 對照、workers types）。
@@ -245,6 +247,20 @@ const identity = { current: () => 'acct-xxxxxxxxxxxxxxxx' };
 const cipher = await encryptNote(cfg, held, '今天寫了一點東西。', 'noteId:n1', identity);
 ```
 
+單篇分享 envelope（`client/argon2`，0.3.6）：一次性 `shareKey`＋該次快照密文＋`jr3s.` 包裹
+三件一組——`shareKey` 與帳戶主鑰隔離（J1：主鑰過分享包＝收分享者可解全帳戶，tacet 親例已修），
+無狀態純函數（`shareKey` 每次新生成，module 層無快取殘留）：
+
+```ts
+import { createShareEnvelope, unwrapNoteKeyShare3 } from '@tacet-ink/journal-core/client/argon2';
+// createShareEnvelope 亦經根 barrel 公開匯出（'@tacet-ink/journal-core'）
+
+const argon = { wrapShare3: 'jr3s.' };   // Argon3Config：wrapShare3 選配（未配置＝分享 API 拒絕）
+const env = await createShareEnvelope(cfg, argon, '今天寫了一點東西。', 'noteId:n1', 'share-pass', identity);
+// env = { ciphertext, wrapped, salt }——存 shares 表（salt 外置 hex）；密文前綴 cfg.cipherBound（held 恆 set 路徑）
+const shareKey = await unwrapNoteKeyShare3(argon, env.wrapped, 'share-pass', env.salt); // 收分享端
+```
+
 PH1 派生（登入憑證）：`derivePh1Argon(pass, saltArg?)` 預設鹽 `PH1_V2_SALT`
 （`'tacet-ph1-v1'`，Tacet 實例，raw pass）。其他產品可自選**固定域鹽**傳入 `saltArg`——
 鹽一經選定即 per-product 恆固定（PH2 UNIQUE 約束：同一密語必須恆生同一 PH2；
@@ -256,6 +272,11 @@ raw 'PASS' 撞同一 ph2）。派生輸入吃 `normalizePassphrase`（NFKC-only
 大小寫差恆不同 ph2）；v2/legacy 派生面零變更（舊帳戶憑證 raw 契約）。兩代 ph2 可並存查表＝
 tacet 遷移層職責（v0.2.0 世代收口）。
 
+`ph1Of`（legacy，`SHA-256(pass)`）標 `@deprecated`：無塩 SHA-256 過登入 wire，DB 洩後
+ph2 離線爆破面＝快雜湊重算命中——不可與 Argon2id PH1 同時作為上線探證。新整合恆改用
+`derivePh1ArgonV3`／`deriveVaultPh1`（Argon2id 派生、固定域鹽）。函式本體零動（legacy 平台
+登入與 deleteAccount 證明面仍在用；退場窗口＝J2a 批）。
+
 server 登入動線（fork 端）：`loginRouteCore(env, store, ip, ph1)` 內建
 ladder 查表守衛——現值 miss 時經 `AuthStore.ladderLookup`（optional）查 ph2_ladder，
 命中回舊帳不建幽靈、兩面 miss 才 `createUser`；未配置＝行為與 0.2.3 單查恆等。
@@ -409,6 +430,18 @@ on their store (the tacet reference: `d1AuthStore`) and applying `migrations/001
 — the lookup itself never writes (inserts stay on the `rekeyWithLadder` migration path,
 deletes on the fork's delete-account flow).
 
+**PH2 pepper injection (0.4.0, J2b).** The PH2 stored-value derivation is now injectable via
+the optional `AuthStore.ph2Of?(ph1Hex) → Promise<string>`: when a fork injects a peppered
+form (tacet: `HMAC-SHA256(PH2_PEPPER, sha256Hex(PH1))`) `loginRouteCore` runs a dual-read
+migration window — current value `ph2Of(PH1)` first (pepper-closed), then the legacy
+`sha256(PH1)` form + ladder guard on a miss; ghost account creation always takes the
+new form `createUser(ph2Of(PH1))` so fresh accounts are pepper-closed at rest. **Uninjected
+(`undefined`) is byte-identical to the 0.3.x single `sha256Hex(PH1)` lookup** (sibling-fork
+zero-impact iron rule; the optional field means a fork pinned to 0.3.5 builds unchanged).
+The opportunistic rewrite of a legacy-form hit to the new form is fork-owned (this layer is
+write-free); `ph2Of` throwing is surfaced (fail-closed, not fail-open — a missing/failed
+pepper read is a loud 5xx, never a silent downgrade to the un-peppered form).
+
 **Opt-in primitives.** Optional contracts (`cipherGuest` / `wrapDual` / `wrapShare` / `pinLock` /
 `cipherAttach` / `cipherLocal` / `wrap4` / `wrapDual4` / `wrapLocal` / `wrapRec` (paired with
 `recKekHkdf`: configured together or not at all; partial configuration is rejected on write) /
@@ -440,7 +473,7 @@ prefix family (`families.json`), known-answer vectors (RFC 9106 Argon2id, the ga
 `scripts/generate-vectors.ts` against the real primitives and committed as frozen evidence; the
 verify gate checks their presence and shape (section [26]) and does not regenerate them.
 
-**Verification.** `npm run verify` runs 531 assertions against the real modules (no mocks; run it from a repo checkout — since 0.3.4 the published package is dist-only and carries no gate):
+**Verification.** `npm run verify` runs 575 assertions against the real modules (no mocks; run it from a repo checkout — since 0.3.4 the published package is dist-only and carries no gate):
 roundtrips, AAD tamper-evidence, extractability rules, era isolation, cross-prefix family
 isolation, payload tampering, RFC 9106 KAT, a 200-vector BIP39 cross-check, and the
 login ladder-guard behavior suite (external audit #8), and presence/shape checks for the format

package/dist/client/argon2.d.ts

@@ -33,6 +33,7 @@
  * ＋AAD 'notekey-rec'，jr1w. 前綴回歸僅 carrying passphrase-PBKDF2 派生（未配置世代
  * wrappedRec 續走 jr1w.＋PBKDF2＋'notekey'）。
  */
+import { type NoteCryptoConfig, type IdentityProvider } from './note-crypto.ts';
 /** RFC 9106 無 secret/ad 標準向量（Argon2id v=0x13, t=3, m=32, p=4, T=32, pwd=32B 0x01, salt=16B 0x00）。 */
 export declare const ARGON_RFC9106_EXPECTED = "72d2a36fd5c266bcc96121b24937bc253338cdfcbd273713655748c54b4dd503";
 /** RFC 9106 KAT 參數單一真相（verifyArgonKat／scripts/generate-vectors.ts 寫 kat.json／閘 [26] 對帳共用）。
@@ -164,8 +165,12 @@ export declare function wrapNoteKeyDual4(cfg: Argon3Config, noteKey: CryptoKey,
     salt: string;
 }>;
 export declare function unwrapNoteKeyDual4(cfg: Argon3Config, wrapped: string, passphrase: string, pin: string, salt1Hex: string): Promise<CryptoKey | null>;
-/** jr3s. 包裹：salt 隨機 16 bytes（hex 由呼叫端存 shares.salt）。 */
-export declare function wrapNoteKeyShare3(cfg: Argon3Config, noteKey: CryptoKey, sharePass: string): Promise<{
+/**
+ * jr3s. 包裹：salt 隨機 16 bytes（hex 由呼叫端存 shares.salt）。
+ * ⚠️ 不可傳入帳戶主鑰（noteKey）——分享包裹的金鑰範圍＝該次分享；
+ * 傳主鑰＝收分享者可解全帳戶（J1；tacet 親例）。
+ */
+export declare function wrapNoteKeyShare3(cfg: Argon3Config, shareKey: CryptoKey, sharePass: string): Promise<{
     wrapped: string;
     salt: string;
 }>;
@@ -174,5 +179,16 @@ export declare function wrapNoteKeyShare3(cfg: Argon3Config, noteKey: CryptoKey,
  *  收口 openNoteKey：鹽外置家族（payload 嚴格 92B＋rawHex 形＋hex fail-closed
  *  全在共用核心）；本函式只做家族守衛、salt hex-形檢查與 KEK 派生——own 92B 檢已隨收口摘除。 */
 export declare function unwrapNoteKeyShare3(cfg: Argon3Config, wrapped: string, sharePass: string, saltHex: string): Promise<CryptoKey | null>;
+/**
+ * 單篇分享 envelope：`generateNoteKey()` 一次性 shareKey → `encryptNote`（held 恆 set，
+ * 密文前綴 cfg.cipherBound）→ `wrapNoteKeyShare3`（jr3s.，sharePass 永不過線）。
+ * 回傳三件：ciphertext（該次快照密文）／wrapped（分享金鑰包裹）／salt（16B hex，呼叫端
+ * 存 shares.salt）。⚠️ 產出的包裹金鑰範圍＝該次分享——絕非帳戶主鑰。
+ */
+export declare function createShareEnvelope(cfg: NoteCryptoConfig, argon: Argon3Config, plaintext: string, aad: string, sharePass: string, idp: IdentityProvider): Promise<{
+    ciphertext: string;
+    wrapped: string;
+    salt: string;
+}>;
 /** jr4d. 解包（重取 salt1 面）：pinSalt 內嵌自描述，salt1 由呼叫端重取後帶入（ladder 遷移後的新値）；任何不符回 null，不拋。 */
 export declare function unwrapNoteKeyDual4WithSalt(cfg: Argon3Config, wrapped: string, passphrase: string, pin: string, salt1Hex: string): Promise<CryptoKey | null>;

package/dist/client/argon2.js

@@ -34,7 +34,7 @@
  * wrappedRec 續走 jr1w.＋PBKDF2＋'notekey'）。
  */
 import { normalizePin, normalizePassphrase } from './note-crypto.js';
-import { b64, unb64, toHex, hexToBytes, decryptWithKey, importAesGcm, openNoteKey, sealNoteKey, } from './note-crypto.js';
+import { b64, unb64, toHex, hexToBytes, decryptWithKey, importAesGcm, openNoteKey, sealNoteKey, generateNoteKey, makeHeldKey, encryptNote, } from './note-crypto.js';
 /** KDF 派生輸入正規化收口（mirror normalizePin 先例）：v3 入口 = normalizePassphrase(pass)；raw 世代入口 = 原密語。
  *  正規化永不進共用派生本體：deriveKekArgon/deriveKek2Argon 吃的是「派生輸入」——
  *  raw 契約（jr3d./jr2w.…）不經此面（帶內版本化「契約面永不變」的結構保證）。
@@ -370,13 +370,17 @@ export async function unwrapNoteKeyDual4(cfg, wrapped, passphrase, pin, salt1Hex
 // 帶內版本化：share KDF 升級 = 換新前綴（jrsw. → jr3s.），舊前綴語意不動；讀取端兩代並行，
 // 建立端只收 jr3s.（關閉弱 KDF 建立面）。
 // ⚠️ unwrap 輸出 noteKey 一律 extractable=true（要能解日記密文；鐵律 4）。
-/** jr3s. 包裹：salt 隨機 16 bytes（hex 由呼叫端存 shares.salt）。 */
-export async function wrapNoteKeyShare3(cfg, noteKey, sharePass) {
+/**
+ * jr3s. 包裹：salt 隨機 16 bytes（hex 由呼叫端存 shares.salt）。
+ * ⚠️ 不可傳入帳戶主鑰（noteKey）——分享包裹的金鑰範圍＝該次分享；
+ * 傳主鑰＝收分享者可解全帳戶（J1；tacet 親例）。
+ */
+export async function wrapNoteKeyShare3(cfg, shareKey, sharePass) {
     if (!cfg.wrapShare3)
         throw new Error('ERR_JR3S_NOT_CONFIGURED');
     const salt = crypto.getRandomValues(new Uint8Array(SALT_LEN));
     const kek = await deriveKekArgon(sharePass, salt);
-    const wrapped = await sealNoteKey(cfg.wrapShare3, noteKey, kek, 'notekey-share');
+    const wrapped = await sealNoteKey(cfg.wrapShare3, shareKey, kek, 'notekey-share');
     return { wrapped, salt: toHex(salt) };
 }
 /** jr3s. 解包：salt 取自 GET /shares/:hash 回應（與 jr1w 同形）；任何不符回 null，不拋。
@@ -399,6 +403,28 @@ export async function unwrapNoteKeyShare3(cfg, wrapped, sharePass, saltHex) {
         return null;
     }
 }
+// ── 單篇分享高階組裝（J1 收口：core 單一真相，0.3.6） ─────────────────────────
+//
+// 分享建立動線的單一步驟 API：一次性 shareKey（與帳戶主鑰隔離——J1：主鑰過分享包＝
+// 收分享者可解全帳戶，tacet 親例已修）＋該次快照密文（AAD 由呼叫端綁 noteId 同律）
+// ＋jr3s. 分享包裹三件一組產出。無狀態純函數：shareKey 每次新生成（module 層無快取
+// 殘留——「envelope 殘部快取 shareKey」否決案：狀態即舊主鑰事故的土壤）。
+// held 恆 set 路徑為主契約：encryptNote 持 shareKey 走 cipherBound 面；idp 是
+// encryptNote 簽名必填（guest 分支不可達——held 先 set，idp 值零影響）。
+/**
+ * 單篇分享 envelope：`generateNoteKey()` 一次性 shareKey → `encryptNote`（held 恆 set，
+ * 密文前綴 cfg.cipherBound）→ `wrapNoteKeyShare3`（jr3s.，sharePass 永不過線）。
+ * 回傳三件：ciphertext（該次快照密文）／wrapped（分享金鑰包裹）／salt（16B hex，呼叫端
+ * 存 shares.salt）。⚠️ 產出的包裹金鑰範圍＝該次分享——絕非帳戶主鑰。
+ */
+export async function createShareEnvelope(cfg, argon, plaintext, aad, sharePass, idp) {
+    const shareKey = await generateNoteKey();
+    const sHeld = makeHeldKey();
+    sHeld.set(shareKey);
+    const ciphertext = await encryptNote(cfg, sHeld, plaintext, aad, idp);
+    const share = await wrapNoteKeyShare3(argon, shareKey, sharePass);
+    return { ciphertext, wrapped: share.wrapped, salt: share.salt };
+}
 // ── ladder 重試鹽面：unwrapNoteKeyDual4WithSalt ────
 //
 // 為何同構再開一支：v3 遷移（登入即重遷）會旋轉 salt1（wrapNoteKeyDual4 落新值）；

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

@@ -114,7 +114,12 @@ export declare function encryptLocal(cfg: NoteCryptoConfig, key: CryptoKey, plai
 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）。 */
+/** 登入憑證：PH1 = SHA-256(pass)——pass 明文從此不過線（伺服器存 PH2）。
+ *  @deprecated 無塩 SHA-256(pass)——登入 wire 用 ph1_legacy 暴露 GPU 可全速爆破的密碼
+ *  指標（外部審查 2026-10-18 J2：不可與 Argon2id PH1 同時作為上線探證；DB 洩後 ph2 的
+ *  離線爆破面＝快雜湊重算命中）。新整合改用 derivePh1ArgonV3／deriveVaultPh1（Argon2id
+ *  派生、固定域鹽）。函式本體零動——legacy 平台登入與 deleteAccount 證明面仍在用
+ *  （帶內版本化：legacy 面不可原地改語意或摘除，退場窗口＝J2a 批）。 */
 export declare function ph1Of(passphrase: string): Promise<string>;
 /** 復原種子：32 bytes hex，只顯示一次；伺服器只收 SHA-256。 */
 export declare function generateRecToken(): string;
@@ -151,8 +156,12 @@ export declare function wrapNoteKey(cfg: NoteCryptoConfig, noteKey: CryptoKey, p
     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<{
+/**
+ * 分享包裹：salt 隨機 16 bytes（hex 由呼叫端存 shares.salt）。
+ * ⚠️ 不可傳入帳戶主鑰（noteKey）——分享包裹的金鑰範圍＝該次分享；
+ * 傳主鑰＝收分享者可解全帳戶（J1；tacet 親例）。
+ */
+export declare function wrapNoteKeyShare(cfg: NoteCryptoConfig, shareKey: CryptoKey, sharePass: string): Promise<{
     wrapped: string;
     salt: string;
 }>;

package/dist/client/note-crypto.js

@@ -270,7 +270,12 @@ export async function generateNoteKey() {
     const raw = crypto.getRandomValues(new Uint8Array(32));
     return importAesGcm(raw, true);
 }
-/** 登入憑證：PH1 = SHA-256(pass)——pass 明文從此不過線（伺服器存 PH2）。 */
+/** 登入憑證：PH1 = SHA-256(pass)——pass 明文從此不過線（伺服器存 PH2）。
+ *  @deprecated 無塩 SHA-256(pass)——登入 wire 用 ph1_legacy 暴露 GPU 可全速爆破的密碼
+ *  指標（外部審查 2026-10-18 J2：不可與 Argon2id PH1 同時作為上線探證；DB 洩後 ph2 的
+ *  離線爆破面＝快雜湊重算命中）。新整合改用 derivePh1ArgonV3／deriveVaultPh1（Argon2id
+ *  派生、固定域鹽）。函式本體零動——legacy 平台登入與 deleteAccount 證明面仍在用
+ *  （帶內版本化：legacy 面不可原地改語意或摘除，退場窗口＝J2a 批）。 */
 export function ph1Of(passphrase) {
     return sha256Hex(passphrase);
 }
@@ -366,13 +371,17 @@ export async function unwrapNoteKey(cfg, wrapped, passphrase, saltHex) {
 // payload = iv[12] ‖ AES-GCM(KEK_share, hex(noteKey), aad='notekey-share')，
 // wrapped = 'jrsw.' + b64(payload)。salt 由呼叫端存 D1（shares.salt）；
 // 分享密語永不過線（與 passphrase 同律）。AAD 用獨立字串，兩種包裹結構不可互換。
-/** 分享包裹：salt 隨機 16 bytes（hex 由呼叫端存 shares.salt）。 */
-export async function wrapNoteKeyShare(cfg, noteKey, sharePass) {
+/**
+ * 分享包裹：salt 隨機 16 bytes（hex 由呼叫端存 shares.salt）。
+ * ⚠️ 不可傳入帳戶主鑰（noteKey）——分享包裹的金鑰範圍＝該次分享；
+ * 傳主鑰＝收分享者可解全帳戶（J1；tacet 親例）。
+ */
+export async function wrapNoteKeyShare(cfg, shareKey, sharePass) {
     if (!cfg.wrapShare)
         throw new Error('ERR_SHARE_NOT_CONFIGURED');
     const salt = crypto.getRandomValues(new Uint8Array(16));
     const kek = await deriveKek(sharePass, salt);
-    const wrapped = await sealNoteKey(cfg.wrapShare, noteKey, kek, 'notekey-share');
+    const wrapped = await sealNoteKey(cfg.wrapShare, shareKey, kek, 'notekey-share');
     return { wrapped, salt: toHex(salt) };
 }
 /** 分享解包：salt 取自 GET /shares/:hash 回應（與 jr1w 同形）；任何不符回 null，不拋。 */

package/dist/index.d.ts

@@ -4,14 +4,14 @@
  * 客戶端原語（WebCrypto；Argon2id 瀏覽器載體見 argon2.ts 檔頭 setArgonLoader）：
  */
 export { makeHeldKey, generateNoteKey, encryptNote, decryptNote, encryptAttach, decryptAttach, encryptLocal, decryptLocal, wrapNoteKey, unwrapNoteKey, wrapNoteKeyWithRecToken, unwrapNoteKeyWithRecToken, wrapNoteKeyDual, unwrapNoteKeyDual, storeLocalWrap, clearLocalWrap, buildBindPayload, ph1Of, normalizePin, normalizePassphrase, recTokenHash, generateRecToken, PBKDF2_ITERATIONS, PIN_PBKDF2_ITERATIONS, type NoteCryptoConfig, type IdentityProvider, type HeldKey, } from './client/note-crypto.ts';
-export { setArgonLoader, verifyArgonKat, wrapNoteKey3, unwrapNoteKey3, wrapNoteKeyDual3, unwrapNoteKeyDual3, wrapNoteKey4, unwrapNoteKey4, wrapNoteKeyDual4, unwrapNoteKeyDual4, wrapNoteKeyShare3, unwrapNoteKeyShare3, derivePh1Argon, derivePh1ArgonV3, PH1_V2_SALT, PH1_V3_SALT, ARGON_MEMORY_KIB, ARGON_ITERATIONS, ARGON_PARALLELISM, ARGON_TAG_LEN, type Argon3Config, } from './client/argon2.ts';
+export { setArgonLoader, verifyArgonKat, wrapNoteKey3, unwrapNoteKey3, wrapNoteKeyDual3, unwrapNoteKeyDual3, wrapNoteKey4, unwrapNoteKey4, wrapNoteKeyDual4, unwrapNoteKeyDual4, wrapNoteKeyShare3, unwrapNoteKeyShare3, createShareEnvelope, derivePh1Argon, derivePh1ArgonV3, PH1_V2_SALT, PH1_V3_SALT, ARGON_MEMORY_KIB, ARGON_ITERATIONS, ARGON_PARALLELISM, ARGON_TAG_LEN, type Argon3Config, } from './client/argon2.ts';
 export { wrapNoteKeyPinLock, unwrapNoteKeyPinLock, PINLOCK_ITERATIONS, type PinLockConfig, } from './client/pinlock.ts';
 export { generateBip39Words, wordsToRecToken, recTokenToWords, spotCheckIndexes, } from './client/bip39.ts';
 export { makeKeyStore, type KeyStore, type KeyStoreConfig } from './client/keys.ts';
 export { wordlist } from './client/wordlist.ts';
 /** 伺服器端原語（Cloudflare Workers + D1）。 */
-export { makeInboundCipher, isCipherFor, validWrappedKey, validHash64, validSalt, pickKeyPackage, loginRouteCore, errResponse, AUTH_RATE, type AuthRow, type AuthStore, type CipherFormats, type KeyPackage, } from './server/auth.ts';
-export { checkRate, normalizeRateIp, type RateWindow } from './server/ratelimit.ts';
+export { makeInboundCipher, isCipherFor, validWrappedKey, validHash64, validSalt, pickKeyPackage, loginRouteCore, errResponse, AUTH_RATE, AUTH_RATE_COARSE, type AuthRow, type AuthStore, type CipherFormats, type KeyPackage, } from './server/auth.ts';
+export { checkRate, checkRateLadder, bumpRate, normalizeRateIp, normalizeRateIpCoarse, globalLoginBump, type RateWindow, } from './server/ratelimit.ts';
 export { corsResponse, CORS_HEADERS } from './server/cors.ts';
 export { sha256Hex, hashString, generateSessionToken, timingSafeEq, } from './server/hash.ts';
 export type { Env } from './server/env.ts';

package/dist/index.js

@@ -4,14 +4,14 @@
  * 客戶端原語（WebCrypto；Argon2id 瀏覽器載體見 argon2.ts 檔頭 setArgonLoader）：
  */
 export { makeHeldKey, generateNoteKey, encryptNote, decryptNote, encryptAttach, decryptAttach, encryptLocal, decryptLocal, wrapNoteKey, unwrapNoteKey, wrapNoteKeyWithRecToken, unwrapNoteKeyWithRecToken, wrapNoteKeyDual, unwrapNoteKeyDual, storeLocalWrap, clearLocalWrap, buildBindPayload, ph1Of, normalizePin, normalizePassphrase, recTokenHash, generateRecToken, PBKDF2_ITERATIONS, PIN_PBKDF2_ITERATIONS, } from './client/note-crypto.js';
-export { setArgonLoader, verifyArgonKat, wrapNoteKey3, unwrapNoteKey3, wrapNoteKeyDual3, unwrapNoteKeyDual3, wrapNoteKey4, unwrapNoteKey4, wrapNoteKeyDual4, unwrapNoteKeyDual4, wrapNoteKeyShare3, unwrapNoteKeyShare3, derivePh1Argon, derivePh1ArgonV3, PH1_V2_SALT, PH1_V3_SALT, ARGON_MEMORY_KIB, ARGON_ITERATIONS, ARGON_PARALLELISM, ARGON_TAG_LEN, } from './client/argon2.js';
+export { setArgonLoader, verifyArgonKat, wrapNoteKey3, unwrapNoteKey3, wrapNoteKeyDual3, unwrapNoteKeyDual3, wrapNoteKey4, unwrapNoteKey4, wrapNoteKeyDual4, unwrapNoteKeyDual4, wrapNoteKeyShare3, unwrapNoteKeyShare3, createShareEnvelope, derivePh1Argon, derivePh1ArgonV3, PH1_V2_SALT, PH1_V3_SALT, ARGON_MEMORY_KIB, ARGON_ITERATIONS, ARGON_PARALLELISM, ARGON_TAG_LEN, } from './client/argon2.js';
 export { wrapNoteKeyPinLock, unwrapNoteKeyPinLock, PINLOCK_ITERATIONS, } from './client/pinlock.js';
 export { generateBip39Words, wordsToRecToken, recTokenToWords, spotCheckIndexes, } from './client/bip39.js';
 export { makeKeyStore } from './client/keys.js';
 export { wordlist } from './client/wordlist.js';
 /** 伺服器端原語（Cloudflare Workers + D1）。 */
-export { makeInboundCipher, isCipherFor, validWrappedKey, validHash64, validSalt, pickKeyPackage, loginRouteCore, errResponse, AUTH_RATE, } from './server/auth.js';
-export { checkRate, normalizeRateIp } from './server/ratelimit.js';
+export { makeInboundCipher, isCipherFor, validWrappedKey, validHash64, validSalt, pickKeyPackage, loginRouteCore, errResponse, AUTH_RATE, AUTH_RATE_COARSE, } from './server/auth.js';
+export { checkRate, checkRateLadder, bumpRate, normalizeRateIp, normalizeRateIpCoarse, globalLoginBump, } from './server/ratelimit.js';
 export { corsResponse, CORS_HEADERS } from './server/cors.js';
 export { sha256Hex, hashString, generateSessionToken, timingSafeEq, } from './server/hash.js';
 export { PH2_LADDER_TABLE, PH2_LADDER_KIND_LEGACY, PH2_LADDER_KIND_V2, } from './server/ladder.js';

package/dist/server/auth.d.ts

@@ -81,6 +81,20 @@ export interface AuthStore {
     ladderInsert?(accountId: string, oldPh2: string, oldKind: 'legacy' | 'v2'): Promise<void>;
     /** ladder 刪列（直銷面；遷移批次同批或後續呼叫端承擔）。 */
     ladderDelete?(accountId: string): Promise<void>;
+    /**
+     * PH2 派生注入點（0.4.0，J2b pepper 收口）：以「PH1 的 hex64」回傳**落庫形 PH2**。
+     * 未注入（undefined）＝loginRouteCore 回落 `sha256Hex(PH1)` 單查，行為與 0.3.x
+     * byte-identical（兄弟 fork 零影響鐵律）。tacet 注入
+     * `HMAC-SHA256(PH2_PEPPER, sha256Hex(PH1))`——D1 外洩面由 pepper 收口（pepper 與 DB
+     * 分離存儲；遺失＝整平台鎖死，已離線備份）。契約：
+     * - 純函數（同 ph1 恆回同值）＝PH2 UNIQUE 查詢鍵的確定性來源；
+     * - 雙讀過渡＝loginRouteCore 先查 `ph2Of(PH1)` 新形、miss 再查 `sha256(PH1)` 舊形
+     *   （＋ladder 守衛）；舊形命中的「順手改寫新形」是 fork 責任（本層零寫入面）；
+     * - 幽靈建帳恆新形（createUser 吃 `ph2Of(PH1)`）＝新帳戶落庫即過 pepper 收口；
+     * - 錯誤外拋（不 fail-open）：pepper 讀取缺失/故障＝顯性 5xx（fork fail-closed 裁定——
+     *   靜默退回無 pepper 形＝攻擊者部署面小錯差即整線降級）。
+     */
+    ph2Of?(ph1Hex: string): Promise<string>;
     revokeAllSessions(userKey: string): Promise<void>;
     insertSession(tokenHash: string, userKey: string, expiresAt: number): Promise<void>;
 }
@@ -95,5 +109,12 @@ export interface AuthRow {
     plan?: string;
 }
 export declare const AUTH_RATE: RateWindow;
+/**
+ * 粗桶第二層帽（0.4.1 J7）：/64 細窗（AUTH_RATE 10/min）擋不住「同 /48 輪換 50 個 /64」的
+ * 分散攻擊（PoC F：500/500 放行）——粗桶表以 normalizeRateIpCoarse 粗鍵（IPv6→/48、
+ * IPv4→/24）各計，60/min（報告建議值、卡面裁定）。表名由呼叫端建表＋GC 承載（同
+ * login_rate 母型）；本常數只是「第二窗 config」，呼叫端**可選**接線——未接＝單窗零變。
+ */
+export declare const AUTH_RATE_COARSE: RateWindow;
 export declare function errResponse(code: string, status: number): Response;
-export declare function loginRouteCore(env: Env & Record<string, unknown>, store: AuthStore, ip: string, ph1In: unknown): Promise<Response>;
+export declare function loginRouteCore(env: Env & Record<string, unknown>, store: AuthStore, ip: string, ph1In: unknown, coarseRate?: RateWindow): Promise<Response>;

package/dist/server/auth.js

@@ -27,7 +27,7 @@
  */
 import { corsResponse } from './cors.js';
 import { sha256Hex, generateSessionToken } from './hash.js';
-import { checkRate } from './ratelimit.js';
+import { checkRate, checkRateLadder } from './ratelimit.js';
 const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
 const BINARY_RE = /[\x00-\x08\x0e-\x1f]/;
 const HASH64_RE = /^[0-9a-f]{64}$/;
@@ -105,6 +105,13 @@ export function pickKeyPackage(body, wrapPrefix) {
     return { wrapped: wrapped && salt ? wrapped : null, salt: wrapped && salt ? salt : null };
 }
 export const AUTH_RATE = { table: 'login_rate', windowMs: 60_000, max: 10 };
+/**
+ * 粗桶第二層帽（0.4.1 J7）：/64 細窗（AUTH_RATE 10/min）擋不住「同 /48 輪換 50 個 /64」的
+ * 分散攻擊（PoC F：500/500 放行）——粗桶表以 normalizeRateIpCoarse 粗鍵（IPv6→/48、
+ * IPv4→/24）各計，60/min（報告建議值、卡面裁定）。表名由呼叫端建表＋GC 承載（同
+ * login_rate 母型）；本常數只是「第二窗 config」，呼叫端**可選**接線——未接＝單窗零變。
+ */
+export const AUTH_RATE_COARSE = { table: 'coarse_login_rate', windowMs: 60_000, max: 60 };
 export function errResponse(code, status) {
     return corsResponse(new Response(code, { status }));
 }
@@ -138,15 +145,41 @@ async function ladderGuard(store, ph2) {
         return null;
     return store.getByUserKey(ladderAcc);
 }
-export async function loginRouteCore(env, store, ip, ph1In) {
-    if (!(await checkRate(env, AUTH_RATE, ip)))
+export async function loginRouteCore(env, store, ip, ph1In, coarseRate) {
+    // 0.4.1 J7 粗桶第二層（可選）：coarseRate 在場＝雙窗 ladder（細窗 AUTH_RATE 10/min 照舊
+    // ＋粗窗粗鍵各計）；未傳＝原單窗零行為變（additive 參數——兄弟 fork／pin 0.3.x 零影響鐵律）。
+    // fallbackInMemory：auth 面 opt-in——限流表 D1 故障/異形退 per-isolate 記憶體計數
+    //（非全站 429 亦非完全放行；2026-09-06 fail-open 裁定的 auth 收口面）。
+    const rateOk = coarseRate
+        ? await checkRateLadder(env, AUTH_RATE, coarseRate, ip, { fallbackInMemory: true })
+        : await checkRate(env, AUTH_RATE, ip, { fallbackInMemory: true });
+    if (!rateOk)
         return errResponse('ERR_RATE_LIMITED', 429);
     const ph1 = validHash64(ph1In);
     if (!ph1)
         return errResponse('ERR_BAD_REQUEST', 400);
+    // 0.4.0 J2b pepper 收口（t_41d5bb18）：ph2Of 注入點。ph2＝現行 sha256(PH1) 舊形
+    // （恆算——未注入單查＋ladder 守衛單一真相源＝[23] 毒化錨字面承載）；ph2New＝ph2Of(PH1)
+    // 新形（HMAC 落庫形，只在注入時算）。ph2Of 拋錯外拋（fail-closed 不 fail-open：pepper
+    // 讀取缺失/故障＝顯性 5xx——靜默退回無 pepper 形＝攻擊者部署面小錯差即整線降級，fork 裁定）。
     const ph2 = await sha256Hex(ph1);
-    const user = (await store.findByIdentityQuery(ph2)) ?? (await ladderGuard(store, ph2));
-    const userKey = user ? user.userKey : await store.createUser(ph2);
+    const ph2New = store.ph2Of ? await store.ph2Of(ph1) : null;
+    let user;
+    if (ph2New !== null) {
+        // 雙讀過渡：先查新形（pepper 收口）→ miss 再查舊形（sha256 舊形＋ladder 守衛）。
+        // 舊形命中的「順手改寫新形」（users.ph2/ladder 對應值覆蓋）是 fork 責任——本層零寫入面
+        //（tacet 走自訂 loginRoute 顯性承載此面；用 loginRouteCore 的兄弟 fork 在 store 層承載）。
+        user = (await store.findByIdentityQuery(ph2New))
+            ?? (await store.findByIdentityQuery(ph2))
+            ?? (await ladderGuard(store, ph2));
+    }
+    else {
+        // 未注入＝現行單查零變（byte-identical 0.3.x——兄弟 fork 零影響鐵律；[23] 錨字面恰此面）。
+        user = (await store.findByIdentityQuery(ph2)) ?? (await ladderGuard(store, ph2));
+    }
+    // 幽靈建帳恆新形（注入）／sha256 舊形（未注入）＝新帳戶落庫即過 pepper 收口。
+    const ph2Create = ph2New ?? ph2;
+    const userKey = user ? user.userKey : await store.createUser(ph2Create);
     const token = generateSessionToken();
     const expiresAt = Date.now() + 30 * 24 * 60 * 60 * 1000; // PWA：30 天
     await store.insertSession(await sha256Hex(token), userKey, expiresAt);

package/dist/server/ratelimit.d.ts

@@ -18,8 +18,25 @@
  * （單一終端可自由輪換 /64 內尾段＝完整地址當鍵即每發新鍵、限流失效）；IPv4-mapped
  * 位址回點分 IPv4（＝原生 IPv4 同 /32 鍵，review r1 MAJOR-1 收口）；IPv4 與非 IPv6 形原樣。
  *
+ * 第二層粗桶（2026-10-20 J7，外審報告 J7 條收口）：/64 帽 10/min 擋不住「同 /48 輪換 50 個
+ * /64」的分散攻擊（PoC F 實證 500/500 放行）——checkRateLadder 第二窗以 normalizeRateIpCoarse
+ * 粗鍵（IPv6→/48、IPv4→/24；**第二層非取代**——/64 細窗是 2026-10-11 定案載體，本層加帽
+ * 非改鍵）＋粗桶表（同構 UPSERT；呼叫端須建表＋GC 承載，同 login_rate 母型）各計。
+ *
+ * fail-open 收口（J7，2026-10-20）：auth 類端點「D1 故障＝全放行」＝攻擊者在 D1 故障期
+ * 全站登入無帽——**非 fail-closed 429**（單點故障反噬主功能，2026-09-06 裁定初諱）亦非
+ * 完全放行：bumpRate/checkRateLadder 支援 opts.fallbackInMemory——D1 出錯或 RETURNING
+ * 異形時退 per-isolate 記憶體計數（module-scope Map；isolate 生命週期恆有效，跨 isolate
+ * 失效＝攻擊者換 isolate 也重置的誠實面，比完全放行嚴）。auth 面 opt-in（呼叫端顯式
+ * 傳 opts），其他端點（shares/notes…）零觸＝完全零行為變。
+ *
+ * 全站登入計數（J7 觀測面）：globalLoginBump＝固定鍵 'global' 單列 UPSERT（同構；
+ * 呼叫端須建表＋GC 承載）——每呼叫 +1 全站計數、回窗內真值；本層只做計數面，
+ * 告警通道（閾值觸發 webhook/log 行）由呼叫端承載（無現成通道則 log JSON 一行）。
+ *
  * 呼叫端須自建表（無 GC 機制：舊 IP 列不清，表隨活躍 IP 數緩慢增長——
- * 每列 ~40 bytes，量級可忽略；如需回收見下方 GC 註記）：
+ * 每列 ~40 bytes，量級可忽略；GC 由呼叫端承載（tacet maintenance 母型——schema.sql 表
+ * 清單真相源＋固定形 SQL_RATE_GC_<表> 常數＋runRateTablesGc batch 接線））：
  *   CREATE TABLE IF NOT EXISTS {table} (ip TEXT PRIMARY KEY, window_start INTEGER, count INTEGER);
  * 可選 GC（未內建）：定期 DELETE WHERE window_start < {now} - windowMs。
  */
@@ -33,6 +50,15 @@ export interface RateWindow {
 export declare const SQL_RATE_BUMP = "INSERT INTO {table} (ip, window_start, count) VALUES (?1, ?2, 1)\n  ON CONFLICT(ip) DO UPDATE SET\n    count        = CASE WHEN window_start <= ?3 THEN 1 ELSE count + 1 END,\n    window_start = CASE WHEN window_start <= ?3 THEN ?2 ELSE window_start END\n  RETURNING count AS n";
 /** @internal（0.1.6 公開面走 index.ts checkRate）。放行判準單一真相：窗口內超額後照實回實際 count，呼叫端以 count <= max 拒絕。 */
 export declare function isRateAllowed(count: number, max: number): boolean;
+/**
+ * 單窗計數（0.1.6 公開面走 index.ts checkRate；ip 已正規化）。
+ * opts.fallbackInMemory（0.4.1 J7，opt-in）：D1 出錯或 RETURNING 異形時退 per-isolate
+ * 記憶體計數（比完全放行嚴；auth 面才傳——limit 表故障≠全站登入狂、亦非全站 429）。
+ * 未傳 opts＝原 fail-open 完全放行（其他端點零行為變鐵律）。
+ */
+export declare function bumpRate(env: Env, w: RateWindow, ip: string, opts?: {
+    fallbackInMemory?: boolean;
+}): Promise<boolean>;
 /**
  * 限流鍵正規化（單一真相；純函式、零 throw）：
  * - IPv6 → /64 前綴＋`/64` 標記（RFC 5952 規範形：hextet 前導零摘除、小寫、零串壓縮），
@@ -44,4 +70,38 @@ export declare function isRateAllowed(count: number, max: number): boolean;
  * - embedded-IPv4 三家族刻意聚合進其所屬前綴的 /64（deliberate nondecision）：IPv4-compatible（RFC 4291 §2.5.5.1 已棄）::192.0.2.1 → ::/64、SIIT ::ffff:0:192.0.2.1 → ::/64、NAT64 64:ff9b::192.0.2.1 → 64:ff9b::/64——僅 IPv4-mapped（§2.5.5.2）還原點分 IPv4。
  */
 export declare function normalizeRateIp(ip: string): string;
-export declare function checkRate(env: Env, w: RateWindow, ip: string): Promise<boolean>;
+export declare function checkRate(env: Env, w: RateWindow, ip: string, opts?: {
+    fallbackInMemory?: boolean;
+}): Promise<boolean>;
+/**
+ * 限流粗鍵正規化（J7 第二層；純函式、零 throw）：
+ * - IPv6 → /48 前綴＋`/48` 標記（同 normalizeRateIp 的 RFC 5952 規範形：前導零摘除、小寫、
+ *   零串壓縮；前綴取前 3 組 hextet），例 `2001:db8:1234:5678::1` → `2001:db8:1234::/48`、
+ *   `::1` → `::/48`；zone id（`%…`）先剝除。
+ * - IPv4-mapped → 先還原點分 IPv4（同 §2.5.5.2 裁定）再 /24：`::ffff:192.0.2.1` →
+ *   `192.0.2.0/24`——mapped 位址回 IPv4 粗桶，禁併入 `::/48` 全域桶（同 /64 層裁定）。
+ * - IPv4 → 前三組 octet＋`0/24`：`192.0.2.33` → `192.0.2.0/24`。
+ * - `'unknown'`／空串／無法解析形／octet 越界：原樣返回（與細層同律：鍵照樣進表＝可見面）。
+ * - 粗層是**第二層非取代**：細層 /64 鍵（t_b30cbc5f 定案）與本層 /48|/24 鍵各入各表、
+ *   各自計數——同 /48 輪換 50 個 /64 的分散攻擊（PoC F）被本層 60/min 帽收斂。
+ */
+export declare function normalizeRateIpCoarse(ip: string): string;
+/**
+ * 雙窗 ladder（J7 第二層；0.4.1）：同 IP 兩窗**各計**——細窗 w（/64 帽照舊）＋粗窗 w2
+ * （粗鍵 normalizeRateIpCoarse＋粗桶表）。任一窗超額即 false（計數不封頂語意兩窗照舊，
+ * 超額發兩窗皆照實累計＝審計可見）。兩窗須為**不同表**（同表＝雙 UPSERT 同鍵＝計數翻倍，
+ * 呼叫端配置錯誤由 assertSafeTable 外的表面自證——本層不代判表異，契約由呼叫端常數承載）。
+ * opts.fallbackInMemory：任一窗 D1 故障/異形時該窗退 per-isolate 記憶體計數（同
+ * bumpRate 裁定——非全站 429 亦非全放行；auth 面 opt-in，其他端點零行為變）。
+ */
+export declare function checkRateLadder(env: Env, w: RateWindow, w2: RateWindow, ip: string, opts?: {
+    fallbackInMemory?: boolean;
+}): Promise<boolean>;
+/**
+ * 全站登入計數（J7 觀測面；0.4.1）：固定鍵 `'global'` 單列 UPSERT（同構 fixed window）——
+ * 每呼叫 +1、回**窗內實際 count**（計數不封頂、超額照實累計＝審計面）。本層只做計數面
+ * 與故障 fail-open 放行（回 null＝本發計數不可信，呼叫端跳過告警判斷）；告警通道
+ * （閾值觸發 webhook／log JSON 行 `{'evt':'login_rate_global','n':N}`）由呼叫端承載——
+ * 本層零 I/O 副作用（console.error 除外的既有裁定）。
+ */
+export declare function globalLoginBump(env: Env, w: RateWindow): Promise<number | null>;

package/dist/server/ratelimit.js

@@ -18,8 +18,25 @@
  * （單一終端可自由輪換 /64 內尾段＝完整地址當鍵即每發新鍵、限流失效）；IPv4-mapped
  * 位址回點分 IPv4（＝原生 IPv4 同 /32 鍵，review r1 MAJOR-1 收口）；IPv4 與非 IPv6 形原樣。
  *
+ * 第二層粗桶（2026-10-20 J7，外審報告 J7 條收口）：/64 帽 10/min 擋不住「同 /48 輪換 50 個
+ * /64」的分散攻擊（PoC F 實證 500/500 放行）——checkRateLadder 第二窗以 normalizeRateIpCoarse
+ * 粗鍵（IPv6→/48、IPv4→/24；**第二層非取代**——/64 細窗是 2026-10-11 定案載體，本層加帽
+ * 非改鍵）＋粗桶表（同構 UPSERT；呼叫端須建表＋GC 承載，同 login_rate 母型）各計。
+ *
+ * fail-open 收口（J7，2026-10-20）：auth 類端點「D1 故障＝全放行」＝攻擊者在 D1 故障期
+ * 全站登入無帽——**非 fail-closed 429**（單點故障反噬主功能，2026-09-06 裁定初諱）亦非
+ * 完全放行：bumpRate/checkRateLadder 支援 opts.fallbackInMemory——D1 出錯或 RETURNING
+ * 異形時退 per-isolate 記憶體計數（module-scope Map；isolate 生命週期恆有效，跨 isolate
+ * 失效＝攻擊者換 isolate 也重置的誠實面，比完全放行嚴）。auth 面 opt-in（呼叫端顯式
+ * 傳 opts），其他端點（shares/notes…）零觸＝完全零行為變。
+ *
+ * 全站登入計數（J7 觀測面）：globalLoginBump＝固定鍵 'global' 單列 UPSERT（同構；
+ * 呼叫端須建表＋GC 承載）——每呼叫 +1 全站計數、回窗內真值；本層只做計數面，
+ * 告警通道（閾值觸發 webhook/log 行）由呼叫端承載（無現成通道則 log JSON 一行）。
+ *
  * 呼叫端須自建表（無 GC 機制：舊 IP 列不清，表隨活躍 IP 數緩慢增長——
- * 每列 ~40 bytes，量級可忽略；如需回收見下方 GC 註記）：
+ * 每列 ~40 bytes，量級可忽略；GC 由呼叫端承載（tacet maintenance 母型——schema.sql 表
+ * 清單真相源＋固定形 SQL_RATE_GC_<表> 常數＋runRateTablesGc batch 接線））：
  *   CREATE TABLE IF NOT EXISTS {table} (ip TEXT PRIMARY KEY, window_start INTEGER, count INTEGER);
  * 可選 GC（未內建）：定期 DELETE WHERE window_start < {now} - windowMs。
  */
@@ -41,25 +58,50 @@ export const SQL_RATE_BUMP = `INSERT INTO {table} (ip, window_start, count) VALU
 export function isRateAllowed(count, max) {
     return count <= max;
 }
-async function bumpRate(env, w, ip) {
+/** @internal（0.4.1 J7）。per-isolate 記憶體退避計數器（module-scope；isolate 生命週期恆有效、
+ * 跨 isolate 失效＝攻擊者換 isolate 也重置的誠實面）。key＝`${table}:${rateKey}`。
+ * 只在 fallbackInMemory 且 D1 故障/異形時觸碰——健康路徑零成本、零寫入面。
+ * 無上限/無掃尾收口（r1 MINOR-2）：D1 長故障期大 IPv6 段攻擊者可造大量 distinct 粗/細鍵推
+ * isolate 記憶體——size 過 MEM_FALLBACK_MAX（65536）整 Map 清（＝攻擊者換 isolate 同向重置，
+ * 語意一致；誠實面：清後計數從 0 重起＝D1 故障期短暫退避失效窗，故障期本就非封鎖面）。 */
+const MEM_FALLBACK_MAX = 65536;
+const memFallback = new Map();
+function memBump(key, windowMs, max, now) {
+    const e = memFallback.get(key);
+    const start = e && now - e.start < windowMs ? e.start : now;
+    const count = e && now - e.start < windowMs ? e.count + 1 : 1;
+    memFallback.set(key, { start, count });
+    if (memFallback.size > MEM_FALLBACK_MAX)
+        memFallback.clear();
+    return isRateAllowed(count, max);
+}
+/**
+ * 單窗計數（0.1.6 公開面走 index.ts checkRate；ip 已正規化）。
+ * opts.fallbackInMemory（0.4.1 J7，opt-in）：D1 出錯或 RETURNING 異形時退 per-isolate
+ * 記憶體計數（比完全放行嚴；auth 面才傳——limit 表故障≠全站登入狂、亦非全站 429）。
+ * 未傳 opts＝原 fail-open 完全放行（其他端點零行為變鐵律）。
+ */
+export async function bumpRate(env, w, ip, opts) {
     assertSafeTable(w.table);
     const now = Date.now();
+    const mem = () => memBump(`${w.table}:${ip}`, w.windowMs, w.max, now);
     try {
         const { results } = await env.DB.prepare(SQL_RATE_BUMP.replaceAll('{table}', w.table)).bind(ip, now, now - w.windowMs).run();
         const first = results[0];
         const n = first?.n;
         if (typeof n !== 'number' || !Number.isFinite(n)) {
-            // 異形回應（results 空／alias 斷裂）與儲存故障同向 fail-open（2026-09-06 裁定：
-            // 缺陷偏向放行，不反向成 deny）；真 D1 不產生（探針實證）——守衛照實回報。
+            // 異形回應（results 空／alias 斷裂）：原 fail-open 放行（2026-09-06 裁定）；
+            // fallbackInMemory 面同退記憶體計數（異形＝本窗判準不可信，仍擋明確超額）。
             console.error(`[ratelimit] ${w.table} unexpected RETURNING shape:`, first);
-            return true;
+            return opts?.fallbackInMemory ? mem() : true;
         }
         return isRateAllowed(n, w.max);
     }
     catch (e) {
-        // fail-open 裁定（2026-09-06）：儲存故障時放行，只擋明確超額
+        // fail-open 裁定（2026-09-06）：儲存故障時放行，只擋明確超額；
+        // fallbackInMemory 面退 per-isolate 記憶體計數（J7 auth 收口——非全站 429 亦非全放行）。
         console.error(`[ratelimit] ${w.table} update failed:`, e);
-        return true;
+        return opts?.fallbackInMemory ? mem() : true;
     }
 }
 const HEXTET = /^[0-9a-f]{1,4}$/i;
@@ -112,6 +154,80 @@ export function normalizeRateIp(ip) {
         net.pop();
     return net.map((h) => h.toString(16)).join(':') + '::/64';
 }
-export function checkRate(env, w, ip) {
-    return bumpRate(env, w, normalizeRateIp(ip));
+export function checkRate(env, w, ip, opts) {
+    return bumpRate(env, w, normalizeRateIp(ip), opts);
+}
+/**
+ * 限流粗鍵正規化（J7 第二層；純函式、零 throw）：
+ * - IPv6 → /48 前綴＋`/48` 標記（同 normalizeRateIp 的 RFC 5952 規範形：前導零摘除、小寫、
+ *   零串壓縮；前綴取前 3 組 hextet），例 `2001:db8:1234:5678::1` → `2001:db8:1234::/48`、
+ *   `::1` → `::/48`；zone id（`%…`）先剝除。
+ * - IPv4-mapped → 先還原點分 IPv4（同 §2.5.5.2 裁定）再 /24：`::ffff:192.0.2.1` →
+ *   `192.0.2.0/24`——mapped 位址回 IPv4 粗桶，禁併入 `::/48` 全域桶（同 /64 層裁定）。
+ * - IPv4 → 前三組 octet＋`0/24`：`192.0.2.33` → `192.0.2.0/24`。
+ * - `'unknown'`／空串／無法解析形／octet 越界：原樣返回（與細層同律：鍵照樣進表＝可見面）。
+ * - 粗層是**第二層非取代**：細層 /64 鍵（t_b30cbc5f 定案）與本層 /48|/24 鍵各入各表、
+ *   各自計數——同 /48 輪換 50 個 /64 的分散攻擊（PoC F）被本層 60/min 帽收斂。
+ */
+export function normalizeRateIpCoarse(ip) {
+    if (typeof ip !== 'string')
+        return ip;
+    if (ip.includes(':')) {
+        const pct = ip.indexOf('%');
+        const g = parseIpv6(pct >= 0 ? ip.slice(0, pct) : ip);
+        // 非法 IPv6 形原樣返回（同細層律；本行不與細層 needle 同字面——[12] 毒化錨恰 1 契約）。
+        if (g === null)
+            return ip;
+        if (g[0] === 0 && g[1] === 0 && g[2] === 0 && g[3] === 0 && g[4] === 0 && g[5] === 0xffff) {
+            const a = g[6] >> 8, b = g[6] & 255, c = g[7] >> 8;
+            return `${a}.${b}.${c}.0/24`;
+        }
+        const net = g.slice(0, 3);
+        while (net.length > 0 && net[net.length - 1] === 0)
+            net.pop();
+        return net.map((h) => h.toString(16)).join(':') + '::/48';
+    }
+    const q = ip.split('.');
+    if (q.length === 4 && q.every((o) => IPV4_OCTET.test(o) && Number(o) <= 255)) {
+        return `${q[0]}.${q[1]}.${q[2]}.0/24`;
+    }
+    return ip;
+}
+/**
+ * 雙窗 ladder（J7 第二層；0.4.1）：同 IP 兩窗**各計**——細窗 w（/64 帽照舊）＋粗窗 w2
+ * （粗鍵 normalizeRateIpCoarse＋粗桶表）。任一窗超額即 false（計數不封頂語意兩窗照舊，
+ * 超額發兩窗皆照實累計＝審計可見）。兩窗須為**不同表**（同表＝雙 UPSERT 同鍵＝計數翻倍，
+ * 呼叫端配置錯誤由 assertSafeTable 外的表面自證——本層不代判表異，契約由呼叫端常數承載）。
+ * opts.fallbackInMemory：任一窗 D1 故障/異形時該窗退 per-isolate 記憶體計數（同
+ * bumpRate 裁定——非全站 429 亦非全放行；auth 面 opt-in，其他端點零行為變）。
+ */
+export async function checkRateLadder(env, w, w2, ip, opts) {
+    const okFine = await bumpRate(env, w, normalizeRateIp(ip), opts);
+    const okCoarse = await bumpRate(env, w2, normalizeRateIpCoarse(ip), opts);
+    return okFine && okCoarse;
+}
+/**
+ * 全站登入計數（J7 觀測面；0.4.1）：固定鍵 `'global'` 單列 UPSERT（同構 fixed window）——
+ * 每呼叫 +1、回**窗內實際 count**（計數不封頂、超額照實累計＝審計面）。本層只做計數面
+ * 與故障 fail-open 放行（回 null＝本發計數不可信，呼叫端跳過告警判斷）；告警通道
+ * （閾值觸發 webhook／log JSON 行 `{'evt':'login_rate_global','n':N}`）由呼叫端承載——
+ * 本層零 I/O 副作用（console.error 除外的既有裁定）。
+ */
+export async function globalLoginBump(env, w) {
+    assertSafeTable(w.table);
+    const now = Date.now();
+    try {
+        const { results } = await env.DB.prepare(SQL_RATE_BUMP.replaceAll('{table}', w.table)).bind('global', now, now - w.windowMs).run();
+        const n = results[0]?.n;
+        if (typeof n !== 'number' || !Number.isFinite(n)) {
+            console.error(`[ratelimit] ${w.table} unexpected RETURNING shape (global):`, results[0]);
+            return null;
+        }
+        return n;
+    }
+    catch (e) {
+        // fail-open：計數面故障不得反噬登入主功能（2026-09-06 裁定同向）。
+        console.error(`[ratelimit] ${w.table} global bump failed:`, e);
+        return null;
+    }
 }

package/package.json

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