@co0ontty/wand 3.1.1 → 4.0.0

package/dist/auth.d.ts

@@ -1,4 +1,6 @@
-import { WandStorage } from "./storage.js";
+import { WandStorage, type AuthPrincipal, type AuthScope } from "./storage.js";
+export declare const BROWSER_ADMIN_PRINCIPAL: AuthPrincipal;
+export declare const CONNECTED_APP_PRINCIPAL: AuthPrincipal;
 /**
  * Cookie 名按 scheme 隔离 —— 解决浏览器 Strict Secure Cookies 在 HTTPS↔HTTP 切换时
  * "新 Set-Cookie 被同名 Secure 旧 cookie 静默丢弃"导致登录后立刻 401 的问题。
@@ -19,7 +21,19 @@ export declare function readSessionCookie(req: {
         cookie?: string;
     };
 }, useHttps: boolean): string | undefined;
-export declare function createSession(): string;
-export declare function validateSession(token: string | undefined): boolean;
-export declare function revokeSession(token: string | undefined): void;
-export declare function setAuthStorage(nextStorage: WandStorage): void;
+export declare class AuthService {
+    private readonly storage;
+    private readonly sessionTtlMs;
+    private readonly sessions;
+    private readonly cleanupTimer;
+    private disposed;
+    constructor(storage: WandStorage, sessionTtlMs?: number, cleanupIntervalMs?: number);
+    createSession(principal?: AuthPrincipal): string;
+    authenticateSession(token: string | undefined): AuthPrincipal | null;
+    validateSession(token: string | undefined): boolean;
+    revokeSession(token: string | undefined): void;
+    revokeAllSessions(): void;
+    dispose(): void;
+    private cleanupExpiredSessions;
+}
+export declare function principalHasScope(principal: AuthPrincipal, scope: AuthScope): boolean;

package/dist/auth.js

@@ -1,7 +1,13 @@
 import crypto from "node:crypto";
-const sessions = new Map();
 const SESSION_TTL_MS = 1000 * 60 * 60 * 12;
-let storage = null;
+export const BROWSER_ADMIN_PRINCIPAL = {
+    kind: "browser-admin",
+    scopes: ["admin"],
+};
+export const CONNECTED_APP_PRINCIPAL = {
+    kind: "connected-app",
+    scopes: ["sessions", "files", "password-vault", "session-preferences"],
+};
 /**
  * Cookie 名按 scheme 隔离 —— 解决浏览器 Strict Secure Cookies 在 HTTPS↔HTTP 切换时
  * "新 Set-Cookie 被同名 Secure 旧 cookie 静默丢弃"导致登录后立刻 401 的问题。
@@ -33,54 +39,86 @@ export function readSessionCookie(req, useHttps) {
     }
     return undefined;
 }
-// Periodic cleanup every 10 minutes
-const sessionCleanupTimer = setInterval(() => {
-    cleanupExpiredSessions();
-}, 1000 * 60 * 10);
-sessionCleanupTimer.unref();
-export function createSession() {
-    const token = crypto.randomBytes(24).toString("hex");
-    const expiresAt = Date.now() + SESSION_TTL_MS;
-    sessions.set(token, expiresAt);
-    storage?.saveAuthSession(token, expiresAt);
-    return token;
-}
-export function validateSession(token) {
-    if (!token) {
-        return false;
+export class AuthService {
+    storage;
+    sessionTtlMs;
+    sessions = new Map();
+    cleanupTimer;
+    disposed = false;
+    constructor(storage, sessionTtlMs = SESSION_TTL_MS, cleanupIntervalMs = 1000 * 60 * 10) {
+        this.storage = storage;
+        this.sessionTtlMs = sessionTtlMs;
+        this.cleanupTimer = setInterval(() => this.cleanupExpiredSessions(), cleanupIntervalMs);
+        this.cleanupTimer.unref?.();
     }
-    let expiresAt = sessions.get(token);
-    if (typeof expiresAt === "undefined") {
-        const persisted = storage?.getAuthSession(token);
-        if (persisted) {
-            sessions.set(token, persisted.expiresAt);
-            expiresAt = persisted.expiresAt;
-        }
+    createSession(principal = BROWSER_ADMIN_PRINCIPAL) {
+        if (this.disposed)
+            throw new Error("AuthService has been disposed.");
+        const token = crypto.randomBytes(24).toString("hex");
+        const expiresAt = Date.now() + this.sessionTtlMs;
+        const cached = { expiresAt, principal: clonePrincipal(principal) };
+        this.sessions.set(token, cached);
+        this.storage.saveAuthSession(token, expiresAt, cached.principal);
+        return token;
     }
-    if (!expiresAt || expiresAt < Date.now()) {
-        if (expiresAt) {
-            sessions.delete(token);
-            storage?.deleteAuthSession(token);
+    authenticateSession(token) {
+        if (!token || this.disposed)
+            return null;
+        let cached = this.sessions.get(token);
+        if (!cached) {
+            const persisted = this.storage.getAuthSession(token);
+            if (persisted) {
+                cached = { expiresAt: persisted.expiresAt, principal: clonePrincipal(persisted.principal) };
+                this.sessions.set(token, cached);
+            }
+        }
+        if (!cached || cached.expiresAt < Date.now()) {
+            if (cached) {
+                this.sessions.delete(token);
+                this.storage.deleteAuthSession(token);
+            }
+            return null;
         }
-        return false;
+        return clonePrincipal(cached.principal);
     }
-    return true;
-}
-export function revokeSession(token) {
-    if (token) {
-        sessions.delete(token);
-        storage?.deleteAuthSession(token);
+    validateSession(token) {
+        return this.authenticateSession(token) !== null;
     }
-}
-export function setAuthStorage(nextStorage) {
-    storage = nextStorage;
-}
-function cleanupExpiredSessions() {
-    const now = Date.now();
-    for (const [token, expiresAt] of sessions) {
-        if (expiresAt < now) {
-            sessions.delete(token);
+    revokeSession(token) {
+        if (!token || this.disposed)
+            return;
+        this.sessions.delete(token);
+        this.storage.deleteAuthSession(token);
+    }
+    revokeAllSessions() {
+        if (this.disposed)
+            return;
+        this.sessions.clear();
+        this.storage.deleteAllAuthSessions();
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        clearInterval(this.cleanupTimer);
+        this.sessions.clear();
+    }
+    cleanupExpiredSessions() {
+        if (this.disposed)
+            return;
+        const now = Date.now();
+        for (const [token, cached] of this.sessions) {
+            if (cached.expiresAt < now)
+                this.sessions.delete(token);
         }
+        this.storage.deleteExpiredAuthSessions(now);
     }
-    storage?.deleteExpiredAuthSessions(now);
+}
+export function principalHasScope(principal, scope) {
+    return principal.kind === "browser-admin"
+        || principal.scopes.includes("admin")
+        || principal.scopes.includes(scope);
+}
+function clonePrincipal(principal) {
+    return { kind: principal.kind, scopes: [...principal.scopes] };
 }

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "commit": "18597f5a51ca36892eed295095956a44bb3da2c8",
-  "builtAt": "2026-07-13T08:34:48.768Z",
-  "version": "3.1.1",
+  "commit": "876fe5a6a89ec103eb7707fc1304592910640c35",
+  "builtAt": "2026-07-14T13:56:32.839Z",
+  "version": "4.0.0",
   "channel": "stable"
 }

package/dist/cert.d.ts

@@ -18,6 +18,6 @@ export interface EnsureCertificatesOptions {
  *   1. options.userCertPath / userKeyPath（config.tls）
  *   2. 配置目录下已存在的 server.crt + server.key
  *   3. 用 openssl 现场生成自签
- *   4. node crypto 兜底（产出非法证书，主要避免崩溃）
+ * 无法可靠生成时明确失败；绝不写入无效或与私钥不匹配的占位证书。
  */
 export declare function ensureCertificates(configDir: string, options?: EnsureCertificatesOptions): SSLConfig;

package/dist/cert.js

@@ -1,8 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { execSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { createHash, createPrivateKey, randomUUID, X509Certificate } from "node:crypto";
+import { isIP } from "node:net";
 import os from "node:os";
 import path from "node:path";
+import { createSecureContext } from "node:tls";
 function getCertificatePaths(configDir) {
     return {
         keyPath: path.join(configDir, "server.key"),
@@ -19,6 +21,38 @@ function readPair(keyPath, certPath) {
         return null;
     }
 }
+function validateCertificatePair(pair) {
+    try {
+        // createSecureContext performs OpenSSL's full PEM parsing and key/certificate
+        // consistency checks. checkPrivateKey keeps the mismatch failure explicit.
+        createSecureContext({ key: pair.key, cert: pair.cert });
+        const certificate = new X509Certificate(pair.cert);
+        const privateKey = createPrivateKey(pair.key);
+        if (!certificate.checkPrivateKey(privateKey))
+            return "证书与私钥不匹配";
+        const now = Date.now();
+        const validFrom = Date.parse(certificate.validFrom);
+        const validTo = Date.parse(certificate.validTo);
+        if (!Number.isFinite(validFrom) || !Number.isFinite(validTo))
+            return "证书有效期无法解析";
+        if (now < validFrom)
+            return "证书尚未生效";
+        if (now >= validTo)
+            return "证书已过期";
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+function ensurePrivateDirectory(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+}
+function hardenGeneratedPair(paths) {
+    chmodSync(paths.keyPath, 0o600);
+    chmodSync(paths.certPath, 0o600);
+}
 /**
  * 收集本机所有可外部访问的 IPv4 地址 + hostname，作为自签证书的 SAN。
  * 之前 SAN 只有 `localhost,127.0.0.1`，从手机/局域网用 `https://192.168.x.x` 访问
@@ -27,7 +61,15 @@ function readPair(keyPath, certPath) {
 function collectSanEntries() {
     const dns = new Set(["localhost"]);
     const ip = new Set(["127.0.0.1", "::1"]);
-    const hostname = os.hostname();
+    const rawHostname = os.hostname().trim().toLowerCase().replace(/\.$/, "");
+    // Hostnames originate outside this process and become part of OpenSSL's
+    // extension grammar. Keep only RFC-style ASCII DNS labels.
+    const hostname = rawHostname.length <= 253
+        && rawHostname.split(".").every((label) => (label.length >= 1
+            && label.length <= 63
+            && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label)))
+        ? rawHostname
+        : "";
     if (hostname && hostname !== "localhost") {
         dns.add(hostname);
         // 部分 mDNS 环境下 hostname.local 也能解析
@@ -44,7 +86,9 @@ function collectSanEntries() {
             // Node 18+ entry.family 是 "IPv4" | "IPv6"，旧版本是 4 | 6
             const fam = entry.family;
             if (fam === "IPv4" || fam === 4 || fam === "IPv6" || fam === 6) {
-                ip.add(entry.address.split("%")[0]); // 去掉 zone-id
+                const address = entry.address.split("%")[0]; // 去掉 zone-id
+                if (isIP(address) !== 0)
+                    ip.add(address);
             }
         }
     }
@@ -73,91 +117,101 @@ function computeFingerprint(certPem) {
  * 这样从手机/局域网设备访问 `https://<LAN IP>:port/` 时不会撞 SAN 不匹配。
  */
 function generateWithOpenSSL(paths) {
+    const dir = path.dirname(paths.keyPath);
+    ensurePrivateDirectory(dir);
+    const suffix = `${process.pid}-${randomUUID()}`;
+    const temporaryKeyPath = path.join(dir, `.server.key.${suffix}.tmp`);
+    const temporaryCertPath = path.join(dir, `.server.crt.${suffix}.tmp`);
+    const execOptions = {
+        stdio: "pipe",
+        timeout: 15_000,
+        windowsHide: true,
+    };
     try {
-        execSync("openssl version", { stdio: "pipe" });
-        const dir = path.dirname(paths.keyPath);
-        if (!existsSync(dir))
-            mkdirSync(dir, { recursive: true });
-        execSync(`openssl genrsa -out "${paths.keyPath}" 2048`, { stdio: "pipe" });
-        const san = buildSanArg();
-        execSync(`openssl req -new -x509 -key "${paths.keyPath}" -out "${paths.certPath}" -days 825 ` +
-            `-subj "/CN=wand-local/O=Wand Local Development" ` +
-            `-addext "subjectAltName=${san}" ` +
-            `-addext "extendedKeyUsage=serverAuth" ` +
-            `-addext "basicConstraints=critical,CA:FALSE"`, { stdio: "pipe" });
-        return {
-            key: readFileSync(paths.keyPath),
-            cert: readFileSync(paths.certPath),
+        // Pre-create with private modes. OpenSSL truncates existing output files and
+        // preserves their mode, so neither artifact is briefly world-readable.
+        writeFileSync(temporaryKeyPath, "", { flag: "wx", mode: 0o600 });
+        writeFileSync(temporaryCertPath, "", { flag: "wx", mode: 0o600 });
+        execFileSync("openssl", ["version"], execOptions);
+        execFileSync("openssl", ["genrsa", "-out", temporaryKeyPath, "2048"], execOptions);
+        execFileSync("openssl", [
+            "req",
+            "-new",
+            "-x509",
+            "-key", temporaryKeyPath,
+            "-out", temporaryCertPath,
+            "-days", "825",
+            "-subj", "/CN=wand-local/O=Wand Local Development",
+            "-addext", `subjectAltName=${buildSanArg()}`,
+            "-addext", "extendedKeyUsage=serverAuth",
+            "-addext", "basicConstraints=critical,CA:FALSE",
+        ], execOptions);
+        chmodSync(temporaryKeyPath, 0o600);
+        chmodSync(temporaryCertPath, 0o600);
+        const pair = {
+            key: readFileSync(temporaryKeyPath),
+            cert: readFileSync(temporaryCertPath),
         };
+        const validationError = validateCertificatePair(pair);
+        if (validationError) {
+            throw new Error(`OpenSSL 生成了不可用的证书：${validationError}`);
+        }
+        renameSync(temporaryKeyPath, paths.keyPath);
+        renameSync(temporaryCertPath, paths.certPath);
+        hardenGeneratedPair(paths);
+        return pair;
     }
-    catch {
-        return null;
+    finally {
+        rmSync(temporaryKeyPath, { force: true });
+        rmSync(temporaryCertPath, { force: true });
     }
 }
-/**
- * 没有 openssl 时的兜底：用 node 内置 crypto 生成 RSA 密钥，证书部分写一个
- * 明显的 placeholder PEM。这条路径产出的证书**无法被浏览器接受**，主要是为了
- * 不让 HTTPS 监听直接崩；启动日志会强烈建议用户装 openssl 或自备证书。
- */
-function generateWithoutOpenSSL(paths) {
-    const dir = path.dirname(paths.keyPath);
-    if (!existsSync(dir))
-        mkdirSync(dir, { recursive: true });
-    const { generateKeyPairSync } = require("node:crypto");
-    const { privateKey } = generateKeyPairSync("rsa", {
-        modulusLength: 2048,
-        publicKeyEncoding: { type: "spki", format: "pem" },
-        privateKeyEncoding: { type: "pkcs8", format: "pem" },
-    });
-    const cert = "-----BEGIN CERTIFICATE-----\n" +
-        "MIIBkTCB+wIJAKHBfPOPlvfoMA0GCSqGSIb3DQEBCwUAMBExDzANBgNVBAMMBnNh\n" +
-        "bmRib3gwHhcNMjQwMTAxMDAwMDAwWhcNMjUwMTAxMDAwMDAwWjARMQ8wDQYDVQQD\n" +
-        "DAZzYW5kYm94MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBALLgGbUPZxEvLPLXZQrz\n" +
-        "KxLhP5EoaUuB7V8FYA5JQZbRE6RkxEKkR8jFQHOcQYevGQYEbXvKZ0WxR2BqMJsC\n" +
-        "AwEAAaMgMB4wDQYJKoZIhvcNAQELBQADQQBpMq0NweMwF7fh0TiMwFCTzC/wK7fR\n" +
-        "e0WxR2BqMJsC\n" +
-        "-----END CERTIFICATE-----\n";
-    writeFileSync(paths.keyPath, privateKey, { mode: 0o600 });
-    writeFileSync(paths.certPath, cert, { mode: 0o644 });
-    process.stderr.write("\x1b[33m[wand] 警告：未检测到 openssl，写出的是无效占位证书。\n" +
-        "[wand] 请安装 openssl，或在 config.json 里配 tls.certPath / tls.keyPath\n" +
-        "[wand] 指向自备证书（推荐 mkcert：mkcert -install && mkcert localhost <hostname> <LAN-IP>）。\x1b[0m\n");
-    return { key: Buffer.from(privateKey), cert: Buffer.from(cert) };
-}
 /**
  * 主入口：装载 TLS 证书。优先级（高 → 低）：
  *   1. options.userCertPath / userKeyPath（config.tls）
  *   2. 配置目录下已存在的 server.crt + server.key
  *   3. 用 openssl 现场生成自签
- *   4. node crypto 兜底（产出非法证书，主要避免崩溃）
+ * 无法可靠生成时明确失败；绝不写入无效或与私钥不匹配的占位证书。
  */
 export function ensureCertificates(configDir, options = {}) {
     // 1. 用户自备证书
     if (options.userCertPath && options.userKeyPath) {
         const pair = readPair(options.userKeyPath, options.userCertPath);
         if (pair) {
-            const fingerprint = computeFingerprint(pair.cert);
-            process.stdout.write(`[wand] 使用 config.tls 指定的证书：${options.userCertPath}\n` +
-                `[wand] SHA-256 指纹: ${fingerprint}\n`);
-            return { ...pair, certPath: options.userCertPath, fingerprint, userProvided: true };
+            const validationError = validateCertificatePair(pair);
+            if (!validationError) {
+                const fingerprint = computeFingerprint(pair.cert);
+                process.stdout.write(`[wand] 使用 config.tls 指定的证书：${options.userCertPath}\n` +
+                    `[wand] SHA-256 指纹: ${fingerprint}\n`);
+                return { ...pair, certPath: options.userCertPath, fingerprint, userProvided: true };
+            }
+            process.stderr.write(`\x1b[33m[wand] 警告：config.tls 指向的证书不可用（${validationError}），回退到默认自签流程。\x1b[0m\n`);
+        }
+        else {
+            process.stderr.write(`\x1b[33m[wand] 警告：config.tls 指向的证书文件无法读取（cert=${options.userCertPath}, key=${options.userKeyPath}），回退到默认自签流程。\x1b[0m\n`);
         }
-        process.stderr.write(`\x1b[33m[wand] 警告：config.tls 指向的证书文件无法读取（cert=${options.userCertPath}, key=${options.userKeyPath}），回退到默认自签流程。\x1b[0m\n`);
     }
     const paths = getCertificatePaths(configDir);
     // 2. 已存在的自签
     const existing = readPair(paths.keyPath, paths.certPath);
     if (existing) {
-        return {
-            ...existing,
-            certPath: paths.certPath,
-            fingerprint: computeFingerprint(existing.cert),
-            userProvided: false,
-        };
+        const validationError = validateCertificatePair(existing);
+        if (!validationError) {
+            ensurePrivateDirectory(path.dirname(paths.keyPath));
+            hardenGeneratedPair(paths);
+            return {
+                ...existing,
+                certPath: paths.certPath,
+                fingerprint: computeFingerprint(existing.cert),
+                userProvided: false,
+            };
+        }
+        process.stderr.write(`\x1b[33m[wand] 警告：已有自签证书不可用（${validationError}），正在重新生成。\x1b[0m\n`);
     }
     process.stdout.write("[wand] 正在生成 self-signed HTTPS 证书…\n");
     // 3. OpenSSL
-    const ssl = generateWithOpenSSL(paths);
-    if (ssl) {
+    try {
+        const ssl = generateWithOpenSSL(paths);
         const fingerprint = computeFingerprint(ssl.cert);
         process.stdout.write(`[wand] 证书已写入 ${paths.certPath}\n` +
             `[wand] SHA-256 指纹: ${fingerprint}\n` +
@@ -165,13 +219,9 @@ export function ensureCertificates(configDir, options = {}) {
             `[wand] HTTPS 启用后可通过 GET /cert/server.crt 在客户端下载安装。\n`);
         return { ...ssl, certPath: paths.certPath, fingerprint, userProvided: false };
     }
-    // 4. 兜底
-    process.stdout.write("[wand] 未检测到 openssl，使用 node crypto 兜底（产出占位证书，仅防崩）。\n");
-    const fallback = generateWithoutOpenSSL(paths);
-    return {
-        ...fallback,
-        certPath: paths.certPath,
-        fingerprint: computeFingerprint(fallback.cert),
-        userProvided: false,
-    };
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error("无法生成 HTTPS 证书：需要可用的 OpenSSL，或在 config.tls 中配置有效且匹配的 certPath/keyPath。" +
+            ` OpenSSL 错误：${detail}`, { cause: error });
+    }
 }

package/dist/config.js

@@ -1,6 +1,6 @@
 import crypto from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 import { isRunningAsRoot } from "./env-utils.js";
@@ -122,9 +122,12 @@ async function atomicWriteFile(filePath, content) {
     const dir = path.dirname(filePath);
     const base = path.basename(filePath);
     const tmpPath = path.join(dir, `.${base}.tmp-${crypto.randomBytes(6).toString("hex")}`);
-    await writeFile(tmpPath, content, "utf8");
+    await writeFile(tmpPath, content, { encoding: "utf8", mode: 0o600 });
     try {
         await rename(tmpPath, filePath);
+        // rename preserves the temporary file mode, but chmod also repairs an
+        // existing config created by older versions or a permissive umask.
+        await chmod(filePath, 0o600);
     }
     catch (err) {
         try {
@@ -136,7 +139,9 @@ async function atomicWriteFile(filePath, content) {
 }
 /** saveConfig 写出时去掉偏好字段——这些已经移到 SQLite。 */
 export async function saveConfig(configPath, config) {
-    await mkdir(path.dirname(configPath), { recursive: true });
+    const dir = path.dirname(configPath);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
     await atomicWriteFile(configPath, `${JSON.stringify(stripPreferenceFields(config), null, 2)}\n`);
 }
 /**
@@ -149,7 +154,8 @@ export async function saveConfig(configPath, config) {
  */
 export async function loadConfigWithStorage(configPath, storage) {
     const dir = path.dirname(configPath);
-    await mkdir(dir, { recursive: true });
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
     let rawInput = {};
     let hadFile = false;
     try {
@@ -175,7 +181,8 @@ export async function loadConfigWithStorage(configPath, storage) {
     applyStoragePassword(config, storage);
     // 如果 JSON 里有偏好字段（说明是老版本配置或刚迁移），重写一次干净版本
     const hasLegacyPrefs = PREFERENCE_KEYS.some((key) => key in rawInput);
-    if (!hadFile || hasLegacyPrefs) {
+    const hasLegacySecrets = "password" in rawInput || "appSecret" in rawInput;
+    if (!hadFile || hasLegacyPrefs || hasLegacySecrets) {
         await saveConfig(configPath, config);
     }
     return config;
@@ -226,6 +233,10 @@ function stripPreferenceFields(config) {
     for (const key of PREFERENCE_KEYS) {
         delete out[key];
     }
+    // These values are DB-owned runtime secrets. They must never be copied back
+    // into config.json when a deployment setting is updated.
+    delete out.password;
+    delete out.appSecret;
     return out;
 }
 /**
@@ -387,13 +398,17 @@ export function writePreferenceToStorage(config, storage, key, value) {
             break;
         }
         case "defaultThinkingEffort": {
-            const v = isThinkingEffort(value) ? value : "off";
+            if (!isThinkingEffort(value))
+                throw new Error(`无效思考深度: ${String(value)}`);
+            const v = value;
             storage.setPreference(dbKey, v);
             config.defaultThinkingEffort = v;
             break;
         }
         case "structuredRunner": {
-            const v = value === "cli" ? "cli" : "sdk";
+            if (value !== "cli" && value !== "sdk")
+                throw new Error(`无效 structured runner: ${String(value)}`);
+            const v = value;
             storage.setPreference(dbKey, v);
             config.structuredRunner = v;
             break;
@@ -411,7 +426,9 @@ export function writePreferenceToStorage(config, storage, key, value) {
             break;
         }
         case "inheritEnv": {
-            const v = value === false ? false : true;
+            if (typeof value !== "boolean")
+                throw new Error(`inheritEnv 必须是布尔值: ${String(value)}`);
+            const v = value;
             storage.setPreference(dbKey, v);
             config.inheritEnv = v;
             break;

package/dist/express-async.d.ts

@@ -0,0 +1,6 @@
+import type { ErrorRequestHandler, NextFunction, Request, RequestHandler, Response } from "express";
+export type AsyncRouteHandler = (req: Request, res: Response, next: NextFunction) => unknown | Promise<unknown>;
+/** Forward both synchronous throws and rejected route promises to Express. */
+export declare function asyncRoute(handler: AsyncRouteHandler): RequestHandler;
+/** Keep API failures JSON-shaped, including body-parser and async route errors. */
+export declare const jsonErrorHandler: ErrorRequestHandler;

package/dist/express-async.js

@@ -0,0 +1,28 @@
+import { getErrorMessage } from "./error-utils.js";
+/** Forward both synchronous throws and rejected route promises to Express. */
+export function asyncRoute(handler) {
+    return (req, res, next) => {
+        try {
+            void Promise.resolve(handler(req, res, next)).catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+}
+/** Keep API failures JSON-shaped, including body-parser and async route errors. */
+export const jsonErrorHandler = (error, _req, res, next) => {
+    if (res.headersSent) {
+        next(error);
+        return;
+    }
+    const status = typeof error?.status === "number"
+        ? error.status
+        : 500;
+    if (status === 413 || error?.type === "entity.too.large") {
+        res.status(413).json({ error: "请求内容过大。" });
+        return;
+    }
+    console.error("[wand] Unhandled request error:", getErrorMessage(error));
+    res.status(status >= 400 && status < 600 ? status : 500).json({ error: "请求处理失败。" });
+};

package/dist/git-quick-commit.d.ts

@@ -1,6 +1,8 @@
 import { GitStatusResult, PushResult, QuickCommitResult, SessionProvider, SessionSnapshot, TagHeadResult } from "./types.js";
 export type QuickCommitErrorCode = "CWD_MISSING" | "NO_CWD" | "NOT_A_GIT_REPO" | "NO_COMMIT" | "NOTHING_TO_COMMIT" | "NOTHING_TO_PUSH" | "EMPTY_MESSAGE" | "EMPTY_TAG" | "EMPTY_AI_MESSAGE" | "INVALID_AI_TAG" | "TAG_EXISTS" | "GIT_ADD_FAILED" | "GIT_DIFF_FAILED" | "GIT_COMMIT_FAILED" | "GIT_TAG_FAILED" | "CLAUDE_CLI_MISSING" | "CLAUDE_CLI_FAILED" | "CLAUDE_TIMEOUT";
 export declare function getGitStatus(cwd: string): GitStatusResult;
+/** Non-blocking status implementation used by HTTP routes. */
+export declare function getGitStatusAsync(cwd: string): Promise<GitStatusResult>;
 interface QuickCommitOptions {
     cwd: string;
     language: string;