@tacet-ink/journal-core 0.3.0 → 0.3.1

package/src/client/argon-worker.ts

@@ -0,0 +1,147 @@
+/**
+ * argon-worker.ts — Argon2id Web Worker 載體：登入不卡畫面。
+ *
+ * Worker 本體＝內嵌 blob 形（免 bundle 步）：vendor 工廠 hashWasmArgon2Factory 的原文
+ *（Function#toString）＋訊息膠水組成 Worker 源碼字串 → Blob → object URL → new Worker。
+ * 協定：main → { id, password, salt, iterations, parallelism, memorySize, hashLength }；
+ *       worker → { id, ok: true, out: Uint8Array } | { id, ok: false, error }。
+ * 串行：main 端單一佇列（hash-wasm Argon2 禁並行——argon2.ts deriveKek2Argon 註同理），
+ * worker 端亦以 promise 鏈串行（雙防線）。
+ * 失敗態：建構拋出／error 事件／ok:false 回應＝本載體失效（dead），佇列內與後續請求一律 reject——
+ * 回退與否由 argon-auto.ts 回退鏈決定（本檔不自帶回退，行為顯形）。
+ */
+
+import type { HashWasmArgon2id } from './argon2.ts';
+import { hashWasmArgon2Factory } from './vendor/hash-wasm-argon2.ts';
+
+/** Worker 最小介面（瀏覽器 Worker 直接相容；node worker_threads 等可包轉接層注入）。 */
+export interface ArgonWorkerLike {
+  postMessage(message: unknown, transfer?: Transferable[]): void;
+  terminate(): void;
+  onmessage: ((ev: { data: unknown }) => void) | null;
+  onerror: ((ev: unknown) => void) | null;
+}
+
+/** Worker 源碼字串（self.onmessage 形；瀏覽器 DedicatedWorkerGlobalScope 語意）。 */
+export function argonWorkerSource(): string {
+  return [
+    "'use strict';",
+    'const factory = (' + hashWasmArgon2Factory.toString() + ');',
+    'let mod = null;',
+    'let q = Promise.resolve();',
+    'self.onmessage = (ev) => {',
+    '  const m = ev.data;',
+    '  q = q.then(async () => {',
+    '    try {',
+    '      if (!mod) mod = factory();',
+    "      const r = await mod.argon2id({ password: m.password, salt: m.salt, iterations: m.iterations, parallelism: m.parallelism, memorySize: m.memorySize, hashLength: m.hashLength, outputType: 'binary' });",
+    '      const out = new Uint8Array(r);',
+    '      self.postMessage({ id: m.id, ok: true, out }, [out.buffer]);',
+    '    } catch (e) {',
+    '      self.postMessage({ id: m.id, ok: false, error: String((e && e.message) || e) });',
+    '    }',
+    '  });',
+    '};',
+    '',
+  ].join('\n');
+}
+
+/** 瀏覽器預設 Worker 工廠：blob URL（CSP 需 worker-src blob:；不允許時建構拋出或 error 事件→回退鏈接手）。 */
+export function createBlobArgonWorker(): ArgonWorkerLike {
+  const url = URL.createObjectURL(new Blob([argonWorkerSource()], { type: 'text/javascript' }));
+  let w: Worker;
+  try {
+    w = new Worker(url);
+  } catch (e) {
+    URL.revokeObjectURL(url);
+    throw e;
+  }
+  const like: ArgonWorkerLike = {
+    postMessage: (m, t) => w.postMessage(m, t ?? []),
+    terminate: () => { w.terminate(); URL.revokeObjectURL(url); },
+    onmessage: null,
+    onerror: null,
+  };
+  w.onmessage = (ev) => like.onmessage?.({ data: ev.data });
+  w.onerror = (ev) => like.onerror?.(ev);
+  w.onmessageerror = (ev) => like.onerror?.(ev);
+  return like;
+}
+
+interface Pending {
+  resolve: (v: Uint8Array) => void;
+  reject: (e: unknown) => void;
+}
+
+/** Worker 載體：回 hash-wasm 同形 argon2id（argon2.ts ArgonLoader 契約）＋terminate。 */
+export function makeWorkerArgon2id(createWorker: () => ArgonWorkerLike): { argon2id: HashWasmArgon2id; terminate(): void } {
+  let worker: ArgonWorkerLike | null = null;
+  let dead: unknown = null;
+  let seq = 0;
+  const pending = new Map<number, Pending>();
+  let queue: Promise<unknown> = Promise.resolve();
+
+  const die = (e: unknown): void => {
+    if (!dead) dead = e ?? new Error('ERR_ARGON_WORKER_DEAD');
+    for (const p of pending.values()) p.reject(dead);
+    pending.clear();
+    if (worker) { try { worker.terminate(); } catch { /* 已終止 */ } }
+    worker = null;
+  };
+
+  const boot = (): ArgonWorkerLike => {
+    if (worker) return worker;
+    const w = createWorker();
+    w.onmessage = (ev) => {
+      const d = ev.data as { id?: number; ok?: boolean; out?: Uint8Array; error?: string } | null;
+      const p = d && typeof d.id === 'number' ? pending.get(d.id) : undefined;
+      if (!p || !d) return;
+      pending.delete(d.id!);
+      if (d.ok && d.out instanceof Uint8Array) p.resolve(d.out);
+      else {
+        const err = new Error('ERR_ARGON_WORKER: ' + (d.error ?? 'bad response'));
+        p.reject(err);
+        die(err); // ok:false＝worker 內 wasm 失效（CSP wasm-eval／記憶體）——整載體 dead，交回退鏈
+      }
+    };
+    w.onerror = (ev) => die(new Error('ERR_ARGON_WORKER_ERROR', { cause: ev }));
+    worker = w;
+    return w;
+  };
+
+  const run = (params: Parameters<HashWasmArgon2id>[0]): Promise<Uint8Array> =>
+    new Promise<Uint8Array>((resolve, reject) => {
+      if (dead) { reject(dead); return; }
+      let w: ArgonWorkerLike;
+      try { w = boot(); } catch (e) { die(e); reject(dead); return; }
+      const id = ++seq;
+      pending.set(id, { resolve, reject });
+      try {
+        w.postMessage({
+          id,
+          password: params.password,
+          salt: params.salt,
+          iterations: params.iterations,
+          parallelism: params.parallelism,
+          memorySize: params.memorySize,
+          hashLength: params.hashLength,
+        });
+      } catch (e) {
+        pending.delete(id);
+        die(e);
+        reject(dead);
+      }
+    });
+
+  const argon2id: HashWasmArgon2id = (params) => {
+    const job = queue.then(() => run(params));
+    queue = job.catch(() => undefined);
+    return job.then((out) => {
+      if (params.outputType === 'binary') return out;
+      if (params.outputType === 'hex') return Array.from(out).map((b) => b.toString(16).padStart(2, '0')).join('');
+      throw new Error('ERR_ARGON_WORKER_OUTPUT_TYPE');
+    });
+  };
+
+  return { argon2id, terminate: () => die(new Error('ERR_ARGON_WORKER_TERMINATED')) };
+}

package/src/client/argon2.ts

@@ -140,7 +140,7 @@ export interface Argon3Config {
   wrapDual4?: string;
 }
 
-interface HashWasmArgon2id {
+export interface HashWasmArgon2id {
   (params: {
     password: string | Uint8Array;
     salt: Uint8Array;
@@ -152,7 +152,7 @@ interface HashWasmArgon2id {
   }): Promise<Uint8Array | string>;
 }
 
-type ArgonLoader = () => Promise<{ argon2id: HashWasmArgon2id }>;
+export type ArgonLoader = () => Promise<{ argon2id: HashWasmArgon2id }>;
 
 let injectedLoader: ArgonLoader | null = null;
 
@@ -161,6 +161,11 @@ export function setArgonLoader(loader: ArgonLoader | null): void {
   injectedLoader = loader;
 }
 
+/** 現行注入載體（唯讀查詢；未注入＝null）。argon-auto.ts 據此判「呼叫端覆寫優先」——0.3.1 新增 export。 */
+export function getArgonLoader(): ArgonLoader | null {
+  return injectedLoader;
+}
+
 /**
  * Argon2id 派生 32B。雙載體：injectedLoader（瀏覽器 hash-wasm）優先；
  * 無注入時走 node:crypto 原生（僅 node 執行環境可達）。皆不可得即 throw（禁 fallback）。

package/src/client/vault-error.ts

@@ -0,0 +1,51 @@
+/**
+ * vault-error.ts — 高階 Vault API 的型別化錯誤家族。
+ *
+ * 低階原語面不動（throw 'ERR_*' 字串錯誤＋unwrap 恆 null 的混態照舊）——只在 vault.ts／
+ * argon-auto.ts 邊界轉譯：高階 API 一律 throw VaultError，呼叫端以 `code` 分流，不比對 message。
+ * 失敗面刻意不細分「密語錯」與「密文竄改」（同一 GCM 失敗——細分＝oracle）。
+ */
+
+export type VaultErrorCode =
+  /** 配置缺欄／畸形（app、cipher、argon.wrap4、recovery 兩欄一體…）——opt-in 未配置即拒。 */
+  | 'ERR_VAULT_CONFIG'
+  /** serverRecord 缺 wrapped/salt 欄或形不符（不猜）。 */
+  | 'ERR_VAULT_BAD_RECORD'
+  /** wrapped 前綴不屬任何已配置家族（未知世代／他產品前綴）。 */
+  | 'ERR_VAULT_WRAP_UNKNOWN'
+  /** 家族辨識成功但解包失敗：密語／PIN 錯或包裹竄改（刻意不分）。 */
+  | 'ERR_VAULT_WRAP_MISMATCH'
+  /** 雙因子家族（jr2w./jr3d./jr4d.）缺 PIN。 */
+  | 'ERR_VAULT_PIN_REQUIRED'
+  /** 密語空值／非字串。 */
+  | 'ERR_VAULT_BAD_PASSPHRASE'
+  /** PIN 正規化後為空。 */
+  | 'ERR_VAULT_BAD_PIN'
+  /** Argon2id 載體缺席或失效（zero-fallback：禁 PBKDF2／zeros 兜底）。 */
+  | 'ERR_VAULT_KDF_UNSUPPORTED'
+  /** recordId 非字串或空。 */
+  | 'ERR_VAULT_BAD_RECORD_ID'
+  /** encrypt 資料形不支援（undefined、BigInt、循環 JSON、非 Uint8Array 的 ArrayBuffer 族…）。 */
+  | 'ERR_VAULT_BAD_DATA'
+  /** 密文 blob 形不符（前綴／base64／長度／型別標記）。 */
+  | 'ERR_VAULT_BAD_BLOB'
+  /** 密文解密失敗：recordId（AAD）不符、金鑰不符或密文竄改（刻意不分）。 */
+  | 'ERR_VAULT_DECRYPT'
+  /** 復原套件形不符（recToken 非 hex64、wrappedRec 前綴不符）或解包失敗。 */
+  | 'ERR_VAULT_RECOVERY'
+  /** 未預期的低階錯誤（cause 帶原錯）。 */
+  | 'ERR_VAULT_INTERNAL';
+
+export class VaultError extends Error {
+  readonly code: VaultErrorCode;
+  constructor(code: VaultErrorCode, message?: string, options?: { cause?: unknown }) {
+    super(message ? code + ': ' + message : code, options);
+    this.name = 'VaultError';
+    this.code = code;
+  }
+}
+
+/** 型別守衛：`isVaultError(e)` 或指定碼 `isVaultError(e, 'ERR_VAULT_DECRYPT')`。 */
+export function isVaultError(e: unknown, code?: VaultErrorCode): e is VaultError {
+  return e instanceof VaultError && (code === undefined || e.code === code);
+}