dsh-connect-workbuddy 2.0.6 → 2.0.11

package/lib/{host-heartbeat--iKDuwr5.js → host-heartbeat-BJdDmMSn.js}

@@ -1,10 +1,379 @@
 import { readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
-import { createHash } from "node:crypto";
+import { createDecipheriv, createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+//#region src/at-rest.ts
+/**
+* WorkBuddy desktop "at-rest" credential decryption.
+*
+* From 5.6.0 the WorkBuddy desktop app no longer stores `auth.accessToken` /
+* `auth.refreshToken` as plain strings. It writes a field wrapper:
+*
+*   { "$wbEncrypted": 1, "envelope": "<base64 of a JSON envelope>" }
+*
+* where the envelope is `{suite, keyId, nonce, authTag, ciphertext}` for
+* AES-256-GCM with a 12-byte nonce and a 16-byte tag. The authenticated
+* additional data is a length-prefixed transcript over the scheme, suite,
+* keyId and framing, so the ciphertext can only be opened for the exact field
+* shape it was sealed for.
+*
+* The field key itself is NOT a user secret: it is a build-time constant
+* compiled into the app's own Electron native module
+* (`electron_browser_workbuddy_storage`). The app fetches it through
+* `loggerGet()` and hashes the returned base64 STRING (not the decoded bytes)
+* to obtain the 32-byte key; `keyId` is the first 16 hex characters of that
+* key's SHA-256.
+*
+* This module re-derives the same key by asking the installed app for the same
+* payload, and caches it in memory for the process lifetime. Nothing is ever
+* written to disk, and the payload is never logged.
+*
+* 改动：**「macOS 也加密」这一事实**（issue #15 真机取证）。本模块原先假设该
+*   policy 是 Windows 先行、macOS 只是「将来可能」，于是 macOS 的可执行文件
+*   路径用 App 名拼成 `<bundle>/Contents/MacOS/WorkBuddy`——而两个真实 bundle
+*   的 `CFBundleExecutable` 都是 `Electron`，该路径并不存在。结果是 macOS 上
+*   加密凭据**永远**取不到密钥，用户却被报成「未登录」。现在二进制名向 bundle
+*   自己问（`macosBundleExecutable()`），候选含国际版 `WorkBuddy AI.app`，
+*   并允许 App 被归入 applications 目录的子目录——扫到的候选必须先用
+*   `CFBundleIdentifier` 确认身份才 `execFile`，因为**每个 Electron 应用的
+*   二进制都叫 `Electron`**，只按名字匹配就可能启动另一个产品。
+*
+* @module dsh-connect-workbuddy/at-rest
+*/
+/** Envelope framing names, mapped to the single-byte AAD framing code. */
+const FRAMING_CODE = {
+	file: 1,
+	field: 2,
+	record: 3,
+	stream: 4
+};
+/** Standard (symmetric) format identifiers, transcripted into the AAD. */
+const STANDARD_FORMAT_ID = {
+	file: "WBEF1",
+	field: "WBEV1",
+	record: "WBER1",
+	stream: "WBES1"
+};
+/** Domain separator the AAD transcript starts with. */
+const AAD_DOMAIN = Buffer.from("WB-AAD\0", "ascii");
+/** Scheme name of the symmetric envelope this module opens. */
+const SYMMETRIC_SCHEME = "sym-v1";
+/** Env override pointing at the WorkBuddy desktop executable. */
+const WORKBUDDY_APP_EXECUTABLE_ENV = "WORKBUDDY_APP_EXECUTABLE";
+/** How long the app is given to answer with its key payload. */
+const KEY_FETCH_TIMEOUT_MS = 1e4;
+/** File name of the WorkBuddy desktop executable on Windows. */
+const APP_EXECUTABLE_NAME = "WorkBuddy.exe";
+/**
+* macOS bundles the desktop app may be installed as, in probe order.
+*
+* `WorkBuddy.app` is the domestic build; `WorkBuddy AI.app` is the
+* international one, and a machine may carry either or both. The user-level
+* `~/Applications` location is included because macOS lets an app live there,
+* and installs have been observed under a subdirectory of /Applications too —
+* hence {@link findWorkbuddyAppExecutable}'s parent scan, which covers those
+* without guessing any particular folder name.
+*/
+const MACOS_APP_BUNDLE_NAMES = ["WorkBuddy.app", "WorkBuddy AI.app"];
+function encodeUint32(value) {
+	const bytes = Buffer.allocUnsafe(4);
+	bytes.writeUInt32BE(value);
+	return bytes;
+}
+/** Length-prefixed UTF-8 string: uint32 big-endian length followed by the bytes. */
+function encodeLengthPrefixed(value) {
+	const bytes = Buffer.from(value, "utf8");
+	return Buffer.concat([encodeUint32(bytes.length), bytes]);
+}
+/**
+* The authenticated additional data for one `sym-v1` FIELD-framed envelope.
+*
+* Only the field framing is implemented: it is the shape the desktop app uses
+* for credential fields, and it is also the shape that cannot be confused with
+* a whole-file envelope, so an unexpected framing is a parse error rather than
+* a silently wrong transcript.
+*/
+function fieldAad(keyId, suite, scheme = SYMMETRIC_SCHEME) {
+	if (!/^[0-9a-f]{16}$/u.test(keyId)) throw new Error(`workbuddy: envelope keyId is malformed`);
+	return Buffer.concat([
+		AAD_DOMAIN,
+		Buffer.from([1]),
+		encodeLengthPrefixed(STANDARD_FORMAT_ID["field"]),
+		encodeLengthPrefixed(scheme),
+		encodeUint32(suite),
+		encodeLengthPrefixed(keyId),
+		Buffer.from([FRAMING_CODE["field"]]),
+		Buffer.from([0]),
+		Buffer.from([0])
+	]);
+}
+/** Whether a value is the app's encrypted-field wrapper. */
+function isEncryptedFieldWrapper(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const wrapper = value;
+	const keys = Object.keys(wrapper).sort();
+	return keys.length === 2 && keys[0] === "$wbEncrypted" && keys[1] === "envelope" && wrapper["$wbEncrypted"] === 1 && typeof wrapper["envelope"] === "string";
+}
+/**
+* The at-rest key id for a derived 32-byte key: the first 16 hex characters of
+* its SHA-256. This is what the envelope's `keyId` is checked against, so a
+* mismatched key fails loudly instead of returning garbage.
+*/
+function deriveAtRestKeyId(key) {
+	return createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+/**
+* Derive the 32-byte field key from the app's key payload JSON.
+*
+* The app hashes the payload's base64 STRING — not its decoded bytes — so the
+* same spelling is required here; hashing the decoded secret would produce a
+* different key and every field would fail to open.
+*/
+function deriveAtRestKey(payloadJson) {
+	let payload;
+	try {
+		payload = JSON.parse(payloadJson);
+	} catch {
+		throw new Error("workbuddy: at-rest key payload is not valid JSON");
+	}
+	if (typeof payload !== "object" || payload === null || Array.isArray(payload)) throw new Error("workbuddy: at-rest key payload is not an object");
+	const secret = payload["atRestSecretKey"];
+	if (typeof secret !== "string" || secret === "") throw new Error("workbuddy: at-rest key payload carries no atRestSecretKey");
+	return createHash("sha256").update(secret, "utf8").digest();
+}
+/**
+* Open one encrypted field with a derived key and return its plaintext.
+*
+* Throws when the envelope is malformed, belongs to another key, or fails
+* authentication — a GCM tag mismatch is the signal that the transcript or the
+* key is wrong, and it must never degrade into a truncated token.
+*/
+function openEncryptedField(field, key) {
+	let envelope;
+	try {
+		envelope = JSON.parse(Buffer.from(field.envelope, "base64").toString("utf8"));
+	} catch {
+		throw new Error("workbuddy: encrypted field envelope is not valid JSON");
+	}
+	if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) throw new Error("workbuddy: encrypted field envelope is not an object");
+	const record = envelope;
+	const suite = record["suite"];
+	const keyId = record["keyId"];
+	const nonce = record["nonce"];
+	const authTag = record["authTag"];
+	const ciphertext = record["ciphertext"];
+	if (typeof suite !== "number" || typeof keyId !== "string") throw new Error("workbuddy: encrypted field envelope is missing suite or keyId");
+	if (typeof nonce !== "string" || typeof authTag !== "string" || typeof ciphertext !== "string") throw new Error("workbuddy: encrypted field envelope is missing nonce, authTag or ciphertext");
+	const expectedKeyId = deriveAtRestKeyId(key);
+	if (keyId !== expectedKeyId) throw new Error(`workbuddy: encrypted field belongs to key ${keyId}, not the available key ${expectedKeyId}`);
+	const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(nonce, "base64"), { authTagLength: 16 });
+	decipher.setAAD(fieldAad(keyId, suite));
+	decipher.setAuthTag(Buffer.from(authTag, "base64"));
+	return Buffer.concat([decipher.update(Buffer.from(ciphertext, "base64")), decipher.final()]).toString("utf8");
+}
+/**
+* The executable inside a macOS app bundle, read from the bundle's own
+* `Info.plist`.
+*
+* The binary is NOT reliably named after the app: the WorkBuddy bundles ship
+* with `CFBundleExecutable` set to `Electron`, so a path assembled as
+* `<bundle>/Contents/MacOS/WorkBuddy` does not exist and the app looks absent
+* even when it is installed in the default location. Because the bundle
+* documents the real name, asking it is both correct and robust to a future
+* build that renames the binary.
+*
+* Returns undefined when the plist is absent, unreadable, or carries no usable
+* name — never a guessed path, so a caller can keep probing.
+*/
+function macosBundleExecutable(bundle) {
+	let plist;
+	try {
+		plist = readFileSync(join(bundle, "Contents", "Info.plist"), "utf8");
+	} catch {
+		return;
+	}
+	const name = /<key>\s*CFBundleExecutable\s*<\/key>\s*<string>([^<]*)<\/string>/u.exec(plist)?.[1]?.trim();
+	if (name === void 0 || name === "" || name.includes("/") || name.includes("\\") || name === "." || name === "..") return;
+	return join(bundle, "Contents", "MacOS", name);
+}
+/**
+* Candidate paths of the WorkBuddy desktop executable, in probe order.
+*
+* The Windows build is the one that encrypts credentials, so Windows leads;
+* the macOS bundles are listed because the same native module ships there and
+* the encryption policy is enabled on macOS builds too (observed from 5.6.x),
+* and `undefined` entries (an unset env variable) are dropped.
+*
+* On macOS the executable name comes from each bundle (see
+* {@link macosBundleExecutable}) rather than being assembled from the app name.
+*
+* `readBundleExecutable` is injectable, in the same spirit as `platform`/`home`/
+* `env`: the macOS branch consults the real filesystem, so without a seam the
+* expected candidates would depend on whether the host machine happens to have
+* the app installed — and the test would pass on a developer's Mac while
+* failing in CI.
+*/
+function workbuddyAppExecutableCandidates(platform = process.platform, home = homedir(), env = process.env, readBundleExecutable = macosBundleExecutable) {
+	const candidates = [env[WORKBUDDY_APP_EXECUTABLE_ENV]?.trim()];
+	if (platform === "win32") {
+		const local = env["LOCALAPPDATA"]?.trim();
+		const programFiles = env["ProgramFiles"]?.trim();
+		const programFilesX86 = env["ProgramFiles(x86)"]?.trim();
+		candidates.push(local === void 0 || local === "" ? void 0 : join(local, "Programs", "WorkBuddy", APP_EXECUTABLE_NAME), local === void 0 || local === "" ? void 0 : join(local, "WorkBuddy", APP_EXECUTABLE_NAME), programFiles === void 0 || programFiles === "" ? void 0 : join(programFiles, "WorkBuddy", APP_EXECUTABLE_NAME), programFilesX86 === void 0 || programFilesX86 === "" ? void 0 : join(programFilesX86, "WorkBuddy", APP_EXECUTABLE_NAME));
+	} else if (platform === "darwin") for (const name of MACOS_APP_BUNDLE_NAMES) candidates.push(readBundleExecutable(join("/Applications", name)), readBundleExecutable(join(home, "Applications", name)));
+	return candidates.filter((candidate) => candidate !== void 0 && candidate !== "");
+}
+/**
+* Bundle identifier PREFIXES the desktop app is signed with — `com.tencent.
+* workbuddy` (domestic, observed as `…workbuddy.mac`) and `com.workbuddy`
+* (international, observed as `com.workbuddy.workbuddy-ai`).
+*
+* Used to CONFIRM that a discovered bundle really is WorkBuddy before it is
+* launched. This matters because the discovery below scans directories and then
+* execs what it finds: every Electron app is built around a binary called
+* `Electron`, so a name-only match could pick a different product's bundle and
+* run it. The identifier is the app's own claim about itself, so it is the
+* check that makes the scan safe.
+*/
+const APP_BUNDLE_IDENTIFIER_PREFIXES = ["com.tencent.workbuddy", "com.workbuddy"];
+/**
+* Whether a bundle identifies itself as the WorkBuddy desktop app.
+*
+* The match is on dot boundaries, so a hypothetical `com.workbuddyish` cannot
+* pass as `com.workbuddy`.
+*
+* An unreadable or identifier-less plist is treated as NOT WorkBuddy: refusing
+* a candidate only costs a fallback to another path, whereas accepting the
+* wrong one would execute an unrelated application.
+*/
+function isWorkbuddyBundle(bundle) {
+	let plist;
+	try {
+		plist = readFileSync(join(bundle, "Contents", "Info.plist"), "utf8");
+	} catch {
+		return false;
+	}
+	const identifier = /<key>\s*CFBundleIdentifier\s*<\/key>\s*<string>([^<]*)<\/string>/u.exec(plist)?.[1]?.trim().toLowerCase();
+	if (identifier === void 0 || identifier === "") return false;
+	return APP_BUNDLE_IDENTIFIER_PREFIXES.some((prefix) => identifier === prefix || identifier.startsWith(`${prefix}.`));
+}
+/**
+* Bundles of the desktop app found one level BELOW a macOS applications
+* directory.
+*
+* Users do file apps into subfolders (`/Applications/IDE/WorkBuddy.app`), and
+* a hardcoded `/Applications/<name>` then reports the app as missing while it
+* is installed and signed in. The scan is deliberately ONE level deep and
+* matches the known bundle names only, so it stays predictable and cheap; each
+* candidate is then confirmed by {@link isWorkbuddyBundle} before use.
+*
+* Returns [] when the parent is absent or unreadable — a missing directory is
+* the normal case, not an error.
+*/
+function macosNestedAppBundles(parent) {
+	let entries;
+	try {
+		entries = readdirSync(parent);
+	} catch {
+		return [];
+	}
+	const bundles = [];
+	for (const entry of entries) {
+		const nested = join(parent, entry);
+		for (const name of MACOS_APP_BUNDLE_NAMES) {
+			const bundle = join(nested, name);
+			try {
+				if (!statSync(bundle).isDirectory()) continue;
+			} catch {
+				continue;
+			}
+			if (isWorkbuddyBundle(bundle)) bundles.push(bundle);
+		}
+	}
+	return bundles;
+}
+/**
+* The first candidate that exists as a file, or undefined when the desktop app
+* is not installed where this platform expects it.
+*/
+function findWorkbuddyAppExecutable(platform = process.platform, home = homedir(), env = process.env) {
+	for (const candidate of workbuddyAppExecutableCandidates(platform, home, env)) try {
+		if (existsSync(candidate)) return candidate;
+	} catch {}
+	if (platform === "darwin") for (const parent of ["/Applications", join(home, "Applications")]) for (const bundle of macosNestedAppBundles(parent)) {
+		const executable = macosBundleExecutable(bundle);
+		if (executable === void 0) continue;
+		try {
+			if (existsSync(executable)) return executable;
+		} catch {}
+	}
+}
+/**
+* Ask the installed desktop app for its key payload by running its own binary
+* as plain Node (`ELECTRON_RUN_AS_NODE`) and calling the native binding.
+*
+* The binding is the app's own public surface for this value, so the plugin
+* never has to carry a copy of a build-specific constant: it asks the very
+* build that wrote the file. The child is given no stdin and a hard timeout,
+* and its stdout is the only thing read.
+*/
+function fetchAtRestKeyPayload(executable) {
+	return new Promise((resolve, reject) => {
+		execFile(executable, ["-e", "try{process.stdout.write(process._linkedBinding('electron_browser_workbuddy_storage').loggerGet())}catch(e){process.exitCode=3;process.stderr.write(String(e&&e.message||e))}"], {
+			env: {
+				...process.env,
+				ELECTRON_RUN_AS_NODE: "1"
+			},
+			timeout: KEY_FETCH_TIMEOUT_MS,
+			windowsHide: true,
+			maxBuffer: 1048576
+		}, (error, stdout, stderr) => {
+			if (error !== null) {
+				reject(/* @__PURE__ */ new Error(`workbuddy: the desktop app did not provide its at-rest key (${stderr.trim() || error.message})`));
+				return;
+			}
+			const payload = stdout.trim();
+			if (payload === "") {
+				reject(/* @__PURE__ */ new Error("workbuddy: the desktop app returned an empty at-rest key payload"));
+				return;
+			}
+			resolve(payload);
+		});
+	});
+}
+/** Process-lifetime cache of the derived key; never persisted. */
+let cachedKey;
+let inflightKey;
+/**
+* The desktop app's at-rest field key, or undefined when it cannot be obtained
+* (app not installed, an older build without the native module, or a future
+* build that rotates the payload). Cached after the first success so the app is
+* spawned at most once per process; a failure is retried on the next call,
+* because the user may install or start the app between reads.
+*/
+function readAtRestKey() {
+	if (cachedKey !== void 0) return Promise.resolve(cachedKey);
+	inflightKey ??= (async () => {
+		const executable = findWorkbuddyAppExecutable();
+		if (executable === void 0) return void 0;
+		const key = deriveAtRestKey(await fetchAtRestKeyPayload(executable));
+		cachedKey = key;
+		return key;
+	})().finally(() => {
+		inflightKey = void 0;
+	});
+	return inflightKey;
+}
+/** Drop the cached key; tests and diagnostics only. */
+function clearAtRestKeyCache() {
+	cachedKey = void 0;
+	inflightKey = void 0;
+}
+//#endregion
 //#region src/upstream.ts
 const CN_CHAT_BASE = "https://copilot.tencent.com";
 const CN_BILLING_BASE = "https://www.codebuddy.cn";
@@ -235,13 +604,41 @@ function isGatewayAuthRejection(status, text) {
 	const lower = text.toLowerCase();
 	return lower.includes("openresty") || lower.includes("apisix") || lower.includes("authorization required");
 }
+/** Marker carried by {@link WorkBuddyCredentialRejectedError}; survives bundling. */
+const CREDENTIAL_REJECTED_CODE = "WORKBUDDY_CREDENTIAL_REJECTED";
+/**
+* The upstream refused the CREDENTIAL itself rather than failing the request.
+*
+* This is a distinct, actionable class: the token is not usable and no retry
+* with the same token will help. Callers use it to tell the user what to do
+* about it (switch accounts, or sign in again) instead of showing a raw HTTP
+* error, and the card must never confuse it with a transient upstream fault.
+*
+* Identified by {@link CREDENTIAL_REJECTED_CODE} rather than `instanceof`, so
+* the check keeps working when the caller and the thrower end up in different
+* module instances (bundled host half vs. a test's source import).
+*/
+var WorkBuddyCredentialRejectedError = class extends Error {
+	code = CREDENTIAL_REJECTED_CODE;
+	/** HTTP status the upstream answered with (401 or 403). */
+	status;
+	constructor(status) {
+		super(`workbuddy: the signed-in credential was rejected by the upstream gateway (http ${status}). The stored token is no longer accepted — most likely a stale credential file from an earlier sign-in was selected. Re-sign in to the WorkBuddy desktop app, then pick that account in the plugin card. Run \`dsh-connect-workbuddy doctor\` to list every discovered credential.`);
+		this.name = "WorkBuddyCredentialRejectedError";
+		this.status = status;
+	}
+};
+/** Whether an error reports that the upstream refused the credential itself. */
+function isCredentialRejectedError(value) {
+	return typeof value === "object" && value !== null && value.code === "WORKBUDDY_CREDENTIAL_REJECTED";
+}
 async function readEnvelope(response) {
 	const text = await response.text();
 	let parsed;
 	try {
 		parsed = JSON.parse(text);
 	} catch {
-		if (isGatewayAuthRejection(response.status, text)) throw new Error(`workbuddy: the signed-in credential was rejected by the upstream gateway (http ${response.status}). The stored token is no longer accepted — most likely a stale credential file from an earlier sign-in was selected. Re-sign in to the WorkBuddy desktop app, then pick that account in the plugin card. Run \`dsh-connect-workbuddy doctor\` to list every discovered credential.`);
+		if (isGatewayAuthRejection(response.status, text)) throw new WorkBuddyCredentialRejectedError(response.status);
 		throw new Error(`workbuddy upstream returned non-JSON (http ${response.status}): ${text.slice(0, 160)}`);
 	}
 	if (typeof parsed !== "object" || parsed === null) throw new Error(`workbuddy upstream returned an unexpected document (http ${response.status})`);
@@ -252,8 +649,15 @@ async function readEnvelope(response) {
 		data: "data" in document ? document["data"] : void 0
 	};
 }
-/** Fail an envelope whose business code is non-zero, classified like HTTP errors. */
+/**
+* Fail an envelope whose business code is non-zero, classified like HTTP errors.
+*
+* A JSON body on a 401/403 is still a credential refusal: the edge answered in
+* the business shape, but the token is just as unusable, so it maps to the same
+* actionable error instead of a generic "client" failure.
+*/
 function envelopeError(status, envelope) {
+	if (status === 401 || status === 403) return new WorkBuddyCredentialRejectedError(status);
 	const kind = classifyUpstreamError(status, envelope.msg);
 	return /* @__PURE__ */ new Error(`workbuddy upstream ${kind} (http ${status}): ${envelope.msg.slice(0, 160)}`);
 }
@@ -631,9 +1035,52 @@ var WorkBuddyUpstreamClient = class {
 *   一个 store，账号、刷新、选择完全隔离；插件自有刷新副本也按区域分
 *   文件（`.workbuddy-auth.<region>.json`），双账号同时在线互不覆盖，
 *   旧的单文件 `.workbuddy-auth.json` 作为迁移源保留读取。
+*   另（issue #15）：`resolve()` 不再把「没登录」与「有登录但凭据读不出来」
+*   合并成同一句话。后者（加密字段 + 取不到密钥）改为抛
+*   `WorkBuddyEncryptedCredentialError`，给出「装 App / 用
+*   WORKBUDDY_APP_EXECUTABLE 指定」这条**可执行**的建议——对已登录的用户说
+*   「请重新登录一次」指向的是唯一无效的动作。判定只在失败路径上跑一次
+*   `diagnose()`，健康路径不付任何代价。
 *
 * @module dsh-connect-workbuddy/auth
 */
+/**
+* Marker for a credential that EXISTS but could not be decrypted.
+*
+* Identified by {@link ENCRYPTED_CREDENTIAL_CODE} rather than `instanceof`, so
+* the check keeps working when the thrower and the caller end up in different
+* module instances (bundled host half vs. a test's source import) — the same
+* convention `WorkBuddyCredentialRejectedError` uses.
+*/
+const ENCRYPTED_CREDENTIAL_CODE = "WORKBUDDY_ENCRYPTED_CREDENTIAL";
+/**
+* The user IS signed in, but the credential file cannot be read.
+*
+* This exists because "signed out" and "signed in with an unreadable credential"
+* resolve to the same observable state — zero accounts — and were therefore
+* reported with the same message. That message told a correctly signed-in user
+* to sign in again, which cannot possibly help: from WorkBuddy 5.6.x the desktop
+* app encrypts its token fields, and reading them requires asking the installed
+* app for its key. If that app cannot be located, the fix is to point the plugin
+* at it (`WORKBUDDY_APP_EXECUTABLE`), never to sign in again.
+*
+* No token material is carried: only the paths and the environment variable.
+*/
+var WorkBuddyEncryptedCredentialError = class extends Error {
+	code = ENCRYPTED_CREDENTIAL_CODE;
+	/** Files that hold an encrypted credential, for the user to recognize. */
+	paths;
+	constructor(paths) {
+		const where = paths.length > 0 ? paths.join(", ") : "the credential file";
+		super(`workbuddy: your WorkBuddy sign-in is present but encrypted, so it cannot be read (${where}). The WorkBuddy desktop app must be present to hand over its key; install it, or set ${WORKBUDDY_APP_EXECUTABLE_ENV} to its executable if it lives elsewhere. Signing in again will not change this.`);
+		this.name = "WorkBuddyEncryptedCredentialError";
+		this.paths = paths;
+	}
+};
+/** Whether an error reports an unreadable (encrypted) credential. */
+function isEncryptedCredentialError(value) {
+	return typeof value === "object" && value !== null && value.code === "WORKBUDDY_ENCRYPTED_CREDENTIAL";
+}
 /** Legacy single-copy basename (pre-dual-provider); kept as migration source. */
 const WORKBUDDY_AUTH_FILENAME = ".workbuddy-auth.json";
 /** Env variable that overrides the desktop auth-file location. */
@@ -701,15 +1148,57 @@ function expiryToMs(value) {
 	if (value <= 0) return 0;
 	return value > 0xe8d4a51000 ? value : value * 1e3;
 }
-function optionalString(value) {
-	return typeof value === "string" && value !== "" ? value : void 0;
+/**
+* Resolve one string field, transparently opening the desktop app's
+* encrypted-field wrapper when present.
+*
+* Windows builds of the WorkBuddy desktop app store `accessToken` and
+* `refreshToken` as `{$wbEncrypted:1,envelope}` instead of plain strings; a
+* reader that only accepts strings sees no credential at all and reports the
+* account as signed out. The SAME treatment applies to `nickname`: it is
+* encrypted in those builds too, so a strings-only reader silently degrades the
+* account's display name to its uin (a bare number) even after tokens start
+* working — which reads as "the plugin does not know who this is".
+*
+* `key` is undefined when the at-rest key could not be obtained, in which case
+* an encrypted field resolves to undefined rather than to a fabricated value.
+*/
+function credentialField(value, key) {
+	if (typeof value === "string") return value;
+	if (!isEncryptedFieldWrapper(value)) return void 0;
+	if (key === void 0) return void 0;
+	return openEncryptedField(value, key);
+}
+/**
+* An optional field that may legitimately be absent: an absent value, a
+* non-string that is not a wrapper, and an unopenable wrapper all mean
+* "unknown", which must not fail the whole document. Only the REQUIRED token
+* fields treat an unopenable wrapper as fatal (see {@link parseWorkBuddyAuth}).
+*
+* `account.phoneNumber` is deliberately never read: it is encrypted in these
+* builds, and the card's privacy contract admits nickname, masked uin, expiry
+* and credits only — a phone number is none of the plugin's business.
+*/
+function optionalCredentialField(value, key) {
+	if (typeof value === "string") return value === "" ? void 0 : value;
+	if (!isEncryptedFieldWrapper(value)) return void 0;
+	if (key === void 0) return void 0;
+	try {
+		return openEncryptedField(value, key);
+	} catch {
+		return;
+	}
 }
 /**
 * Parse a WorkBuddy auth document in either on-disk shape: the plugin OAuth
 * nested form `{"auth":{...},"account":{...}}` and the flat panel form.
 * Returns undefined when the document carries no access token.
+*
+* `atRestKey` is required to read documents whose fields are encrypted
+* (see {@link credentialField}); pass the key obtained from
+* `readAtRestKey()` when the plain read reports no token.
 */
-function parseWorkBuddyAuth(text, filePath) {
+function parseWorkBuddyAuth(text, filePath, atRestKey) {
 	let parsed;
 	try {
 		parsed = JSON.parse(text);
@@ -727,21 +1216,28 @@ function parseWorkBuddyAuth(text, filePath) {
 		auth = document;
 		identity = document;
 	}
-	const accessToken = typeof auth["accessToken"] === "string" ? auth["accessToken"] : "";
-	if (accessToken === "") return void 0;
+	let accessToken;
+	let refreshToken;
+	try {
+		accessToken = credentialField(auth["accessToken"], atRestKey);
+		refreshToken = credentialField(auth["refreshToken"], atRestKey);
+	} catch {
+		return;
+	}
+	if (accessToken === void 0 || accessToken === "") return void 0;
 	const expiresAtMs = typeof auth["expiresAt"] === "number" ? expiryToMs(auth["expiresAt"]) : 0;
 	const refreshExpiresAtMs = typeof auth["refreshExpiresAt"] === "number" ? expiryToMs(auth["refreshExpiresAt"]) : void 0;
 	const lastRefreshAtMs = typeof auth["lastRefreshTime"] === "number" ? expiryToMs(auth["lastRefreshTime"]) : void 0;
-	const enterpriseId = optionalString(identity["enterpriseId"]);
-	const nickname = optionalString(identity["nickname"]);
-	const uin = optionalString(identity["uin"]);
+	const enterpriseId = optionalCredentialField(identity["enterpriseId"], atRestKey);
+	const nickname = optionalCredentialField(identity["nickname"], atRestKey);
+	const uin = optionalCredentialField(identity["uin"], atRestKey);
 	return {
 		accessToken,
-		refreshToken: typeof auth["refreshToken"] === "string" ? auth["refreshToken"] : "",
+		refreshToken: refreshToken ?? "",
 		expiresAtMs,
 		...refreshExpiresAtMs === void 0 ? {} : { refreshExpiresAtMs },
-		domain: optionalString(auth["domain"]) ?? "",
-		uid: optionalString(identity["uid"]) ?? "",
+		domain: optionalCredentialField(auth["domain"], atRestKey) ?? "",
+		uid: optionalCredentialField(identity["uid"], atRestKey) ?? "",
 		...enterpriseId === void 0 ? {} : { enterpriseId },
 		...nickname === void 0 ? {} : { nickname },
 		...uin === void 0 ? {} : { uin },
@@ -751,6 +1247,30 @@ function parseWorkBuddyAuth(text, filePath) {
 	};
 }
 /**
+* Whether a document carries any field the reader must decrypt — the token
+* fields or the identity fields — i.e. whether reading it needs the at-rest key
+* at all.
+*
+* Deciding this BEFORE asking the app for its key keeps the plain case (macOS
+* and older Windows builds, and every plugin-owned copy) from paying for a
+* child process on every credential read. Identity fields are included because
+* a future build could encrypt the display name while leaving tokens plain;
+* gating on tokens alone would then silently drop the name again.
+*/
+function hasEncryptedCredentialFields(text) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return false;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false;
+	const document = parsed;
+	const auth = typeof document["auth"] === "object" && document["auth"] !== null ? document["auth"] : document;
+	const identity = typeof document["account"] === "object" && document["account"] !== null ? document["account"] : document;
+	return isEncryptedFieldWrapper(auth["accessToken"]) || isEncryptedFieldWrapper(auth["refreshToken"]) || isEncryptedFieldWrapper(identity["nickname"]) || isEncryptedFieldWrapper(identity["uin"]) || isEncryptedFieldWrapper(identity["uid"]) || isEncryptedFieldWrapper(identity["enterpriseId"]) || isEncryptedFieldWrapper(auth["domain"]);
+}
+/**
 * Rank two candidate files for the same account.
 *
 * The live `workbuddy-desktop.info` always wins: it is the app's current
@@ -837,14 +1357,70 @@ function parseOwnDocument(text, filePath) {
 function isENOENT(error) {
 	return error?.code === "ENOENT";
 }
-/** Read one auth file, tolerating absence and unparsable content. */
-async function readAuthFile(path) {
+/**
+* Probe one auth file, reporting WHY it yielded no credential.
+*
+* The desktop app encrypts its token fields on Windows builds. The plain read
+* is tried first and the app is only asked for its at-rest key when the
+* document actually carries encrypted wrappers, so the common case costs no
+* child process. `resolveAtRestKey` is injectable so the encrypted path is
+* testable without a real desktop install.
+*/
+async function probeAuthFile(path, resolveAtRestKey) {
+	let text;
 	try {
-		return parseWorkBuddyAuth(await readFile(path, "utf8"), path);
+		text = await readFile(path, "utf8");
 	} catch (error) {
-		if (isENOENT(error)) return void 0;
-		return;
+		const missing = isENOENT(error);
+		return { failure: {
+			reason: missing ? "missing" : "unreadable",
+			...missing ? {} : { message: error instanceof Error ? error.message : String(error) }
+		} };
+	}
+	const plain = parseWorkBuddyAuth(text, path);
+	if (plain !== void 0) return { credential: plain };
+	if (!hasEncryptedCredentialFields(text)) return isParseableJson(text) ? { failure: {
+		reason: "invalid",
+		message: "no access token in the document"
+	} } : { failure: {
+		reason: "invalid",
+		message: "the file is not valid JSON"
+	} };
+	let key;
+	try {
+		key = await resolveAtRestKey();
+	} catch (error) {
+		return { failure: {
+			reason: "encrypted",
+			message: error instanceof Error ? error.message : String(error)
+		} };
 	}
+	if (key === void 0) return { failure: {
+		reason: "encrypted",
+		message: `the credential fields are encrypted and no key was available; the WorkBuddy desktop app must be present (or set ${WORKBUDDY_APP_EXECUTABLE_ENV})`
+	} };
+	const decrypted = parseWorkBuddyAuth(text, path, key);
+	return decrypted === void 0 ? { failure: {
+		reason: "invalid",
+		message: "the encrypted credential fields could not be opened with the desktop app's key"
+	} } : { credential: decrypted };
+}
+/** Whether text parses as JSON at all; distinguishes "wrong shape" from "not JSON". */
+function isParseableJson(text) {
+	try {
+		JSON.parse(text);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Read one auth file, tolerating absence and unparsable content. Kept as the
+* credential-only view for callers that do not need the failure reason.
+*/
+async function readAuthFile(path, resolveAtRestKey) {
+	const probe = await probeAuthFile(path, resolveAtRestKey);
+	return "credential" in probe ? probe.credential : void 0;
 }
 /**
 * Read-only credential store with demand-driven refresh and multi-account
@@ -864,6 +1440,7 @@ var WorkBuddyCredentialStore = class {
 	legacyOwnPath;
 	legacyOwnPathExplicit;
 	authDirs;
+	resolveAtRestKey;
 	desktopPathOverride;
 	accountId;
 	inflight;
@@ -876,6 +1453,7 @@ var WorkBuddyCredentialStore = class {
 		this.legacyOwnPathExplicit = options.legacyOwnPath;
 		this.authDirs = options.authDirs;
 		this.desktopPathOverride = options.desktopPath;
+		this.resolveAtRestKey = options.resolveAtRestKey ?? readAtRestKey;
 	}
 	/** Whether a credential's login domain belongs to this store's region. */
 	matchesRegion(domain) {
@@ -1005,7 +1583,7 @@ var WorkBuddyCredentialStore = class {
 		const files = await this.candidateFiles();
 		const byId = /* @__PURE__ */ new Map();
 		for (const file of files) {
-			const credential = await readAuthFile(file);
+			const credential = await readAuthFile(file, this.resolveAtRestKey);
 			if (credential === void 0 || !this.matchesRegion(credential.domain)) continue;
 			const id = workbuddyAccountId(credential);
 			const existing = byId.get(id);
@@ -1059,8 +1637,7 @@ var WorkBuddyCredentialStore = class {
 			const id = workbuddyAccountId(credential);
 			return {
 				id,
-				accountName: credential.nickname ?? credential.uin ?? credential.uid,
-				...credential.uin === void 0 ? {} : { uin: credential.uin },
+				accountName: credential.nickname ?? "",
 				domain: credential.domain,
 				source: credential.source,
 				tokenExpiresAtMs: credential.expiresAtMs,
@@ -1091,20 +1668,53 @@ var WorkBuddyCredentialStore = class {
 		if (this.accountId === void 0) return this.preferred(credentials);
 		return credentials.find((credential) => workbuddyAccountId(credential) === this.accountId);
 	}
+	/**
+	* One account's stored credential by id, WITHOUT consulting or changing the
+	* current selection.
+	*
+	* Exists so a recovery probe can test whether some OTHER local account is
+	* still accepted upstream while a rejected one stays selected: mutating the
+	* live selection to find that out would be exactly the silent account switch
+	* this store refuses to perform (it would bill the wrong account mid-probe).
+	*/
+	async credentialFor(accountId) {
+		return (await this.readAll()).find((credential) => workbuddyAccountId(credential) === accountId);
+	}
 	/** The credential to send upstream: {@link current}, refreshed on demand. */
 	async resolve() {
 		const credential = await this.current();
-		if (credential === void 0) {
-			const candidates = this.resolveDesktopCandidates();
-			const desktop = candidates.length > 0 ? candidates.join(" or ") : "(no desktop path on this platform)";
-			throw new Error(`workbuddy: no signed-in WorkBuddy account found; sign in once in the WorkBuddy desktop app (expected ${desktop} or ${WORKBUDDY_AUTH_FILE_ENV}), or refresh an existing session`);
-		}
+		if (credential === void 0) throw await this.describeMissingCredential();
 		if (!this.needsRefresh(credential)) return credential;
 		this.inflight ??= this.refreshNow(credential).finally(() => {
 			this.inflight = void 0;
 		});
 		return this.inflight;
 	}
+	/**
+	* WHY no credential resolved, as the error to throw.
+	*
+	* `resolve()` seeing zero accounts has two very different causes, and the
+	* generic "sign in once" message is only correct for one of them. When a
+	* probe finds a credential file whose fields are encrypted and the key could
+	* not be obtained, the user is signed in and re-authenticating cannot help —
+	* so that case gets {@link WorkBuddyEncryptedCredentialError} instead, naming
+	* the file and the environment variable that actually fixes it.
+	*
+	* The probe is only run on the failure path, so the healthy case pays nothing.
+	* A probe that itself throws must not replace the real error, hence the
+	* fallback to the generic message.
+	*/
+	async describeMissingCredential() {
+		let failures = [];
+		try {
+			failures = (await this.diagnose()).failures;
+		} catch {}
+		const encrypted = failures.filter((failure) => failure.reason === "encrypted").map((failure) => failure.path);
+		if (encrypted.length > 0) return new WorkBuddyEncryptedCredentialError(encrypted);
+		const candidates = this.resolveDesktopCandidates();
+		const desktop = candidates.length > 0 ? candidates.join(" or ") : "(no desktop path on this platform)";
+		return /* @__PURE__ */ new Error(`workbuddy: no signed-in WorkBuddy account found; sign in once in the WorkBuddy desktop app (expected ${desktop} or ${WORKBUDDY_AUTH_FILE_ENV}), or refresh an existing session`);
+	}
 	/** Read-only sign-in summary; never refreshes and never throws. */
 	async status() {
 		try {
@@ -1190,6 +1800,66 @@ var WorkBuddyCredentialStore = class {
 		} catch {}
 		return false;
 	}
+	/**
+	* Which paths were probed and why each one yielded no credential.
+	*
+	* Read-only and token-free: it exists so a signed-out card can explain
+	* itself. A bare "not signed in" is undiagnosable on a machine whose layout
+	* differs from the ones this plugin was written against — and on Windows it
+	* is actively misleading, because encrypted token fields need the desktop app
+	* present to be read at all. Only paths this store actually consults are
+	* reported, and only files that failed: one healthy sibling would make the
+	* whole list noise.
+	*/
+	async diagnose() {
+		const candidates = [];
+		for (const path of await this.candidateFiles()) {
+			const probe = await probeAuthFile(path, this.resolveAtRestKey);
+			if ("credential" in probe) {
+				if (!this.matchesRegion(probe.credential.domain)) candidates.push({
+					path,
+					source: "desktop",
+					reason: "wrong-region",
+					message: `holds a ${regionOf(probe.credential.domain)} sign-in, but this tab reads the ${this.region} region`
+				});
+				continue;
+			}
+			candidates.push({
+				path,
+				source: "desktop",
+				...probe.failure
+			});
+		}
+		for (const path of this.ownCandidates()) {
+			let text;
+			try {
+				text = await readFile(path, "utf8");
+			} catch (error) {
+				if (isENOENT(error)) continue;
+				candidates.push({
+					path,
+					source: "dsh",
+					reason: "unreadable",
+					message: error instanceof Error ? error.message : String(error)
+				});
+				continue;
+			}
+			const parsed = parseOwnDocument(text, path);
+			if (parsed === void 0 || !this.matchesRegion(parsed.domain)) {
+				candidates.push({
+					path,
+					source: "dsh",
+					reason: "invalid",
+					message: "not a readable plugin-owned credential"
+				});
+				continue;
+			}
+		}
+		return {
+			tried: [...await this.candidateFiles(), ...this.ownCandidates()],
+			failures: candidates
+		};
+	}
 };
 //#endregion
 //#region src/catalog.ts
@@ -1458,6 +2128,18 @@ var WorkBuddyCatalog = class {
 	*/
 	usable = true;
 	/**
+	* Whether the user has switched this region's provider ON. Opt-out: defaults
+	* to `true`, so a config predating this switch (and the pre-region-split flat
+	* fields, which never carry `enabled`) keeps both providers running. Set to
+	* `false` by `setRegionEnabled` to withdraw the region from DSH's model
+	* picker entirely (its adapter route and configurable-provider entry are
+	* pulled by the Host via `AdapterRegistrationHandle.replace([])` /
+	* `DirectoryRegistrationHandle.replace([])`). This is a USER choice, distinct
+	* from {@link usable}: a region the user switched off keeps its catalog,
+	* accounts, and model picks intact and reappears the moment they re-check it.
+	*/
+	enabled = true;
+	/**
 	* @param region Seeds the static fallback for this region; each region's
 	* provider must never serve the other region's roster before its first
 	* live refresh lands.
@@ -1468,19 +2150,25 @@ var WorkBuddyCatalog = class {
 	/**
 	* Current entries; the fallback list until the upstream answer lands.
 	*
-	* Empty while this region has no local sign-in: the provider stays
-	* registered (its row still hosts the settings card and the account picker),
-	* but it advertises nothing to pick. DSH drops empty provider groups from
-	* the picker (`buildModelCatalog` filters `models.length > 0`), so the group
-	* disappears exactly when it would be pure noise.
+	* Empty while this region has no local sign-in OR the user has switched it
+	* off: the provider stays registered (its row still hosts the settings card
+	* and the account picker), but it advertises nothing to pick. DSH drops empty
+	* provider groups from the picker (`buildModelCatalog` filters
+	* `models.length > 0`), so the group disappears exactly when it would be pure
+	* noise. The two empty causes are independent: `usable` is the automatic
+	* "no account" gate (issue #12), `enabled` is the user's explicit on/off.
 	*/
 	current() {
-		return this.usable ? this.models : [];
+		return this.usable && this.enabled ? this.models : [];
 	}
 	/** Whether this region currently advertises any model. */
 	isRegionUsable() {
 		return this.usable;
 	}
+	/** Whether the user has this region's provider switched on. */
+	isRegionEnabled() {
+		return this.enabled;
+	}
 	/**
 	* Record whether this region has a local sign-in.
 	*
@@ -1497,6 +2185,20 @@ var WorkBuddyCatalog = class {
 		this.usable = usable;
 		return true;
 	}
+	/**
+	* Record the user's explicit on/off choice for this region's provider.
+	*
+	* Distinct from {@link setRegionUsable}: that is the automatic "no local
+	* account" gate, while this is a deliberate user action (issue #11-style
+	* region switch). The Host reads the same `enabled` flag through
+	* `regionStateOf(config, region).enabled !== false`, so the two halves never
+	* disagree. Returns whether the value changed.
+	*/
+	setRegionEnabled(enabled) {
+		if (this.enabled === enabled) return false;
+		this.enabled = enabled;
+		return true;
+	}
 	/** Replace the list; callers invalidate their adapter snapshot after this. */
 	set(models) {
 		if (models.length === 0) throw new Error("workbuddy model catalog cannot be empty");
@@ -1506,7 +2208,7 @@ var WorkBuddyCatalog = class {
 //#endregion
 //#region src/version.ts
 /** The npm package version this build was produced from. */
-const WORKBUDDY_CONNECT_VERSION = "2.0.6";
+const WORKBUDDY_CONNECT_VERSION = "2.0.11";
 //#endregion
 //#region src/host-heartbeat.ts
 /**
@@ -1612,4 +2314,4 @@ async function clearHostHeartbeat() {
 	await rm(workbuddyHostHeartbeatPath(), { force: true });
 }
 //#endregion
-export { prepareChatBody as A, workbuddyAccountId as C, parseCreditMultiplier as D, classifyUpstreamError as E, parseReasoning as O, parseWorkBuddyAuth as S, WorkBuddyUpstreamClient as T, authFileName as _, readHostHeartbeat as a, defaultDesktopAuthPath as b, WORKBUDDY_CONNECT_VERSION as c, WorkBuddyCatalog as d, deriveCatalog as f, WorkBuddyCredentialStore as g, WORKBUDDY_AUTH_FILE_ENV as h, processStartTimeMs as i, regionOf as j, parseUpstreamModel as k, FALLBACK_WORKBUDDY_MODELS as l, WORKBUDDY_AUTH_FILENAME as m, clearHostHeartbeat as n, workbuddyHostHeartbeatPath as o, fallbackModelsFor as p, isHeartbeatProcessAlive as r, writeHostHeartbeat as s, WORKBUDDY_HOST_HEARTBEAT_FILENAME as t, FALLBACK_WORKBUDDY_MODELS_GLOBAL as u, defaultDesktopAuthCandidates as v, workbuddyOwnAuthPath as w, legacyWorkbuddyOwnAuthPath as x, defaultDesktopAuthDirs as y };
+export { WorkBuddyCredentialRejectedError as A, clearAtRestKeyCache as B, hasEncryptedCredentialFields as C, workbuddyAccountId as D, parseWorkBuddyAuth as E, parseReasoning as F, isEncryptedFieldWrapper as G, deriveAtRestKeyId as H, parseUpstreamModel as I, macosNestedAppBundles as J, isWorkbuddyBundle as K, prepareChatBody as L, classifyUpstreamError as M, isCredentialRejectedError as N, workbuddyOwnAuthPath as O, parseCreditMultiplier as P, regionOf as R, defaultDesktopAuthPath as S, legacyWorkbuddyOwnAuthPath as T, fetchAtRestKeyPayload as U, deriveAtRestKey as V, findWorkbuddyAppExecutable as W, readAtRestKey as X, openEncryptedField as Y, workbuddyAppExecutableCandidates as Z, WorkBuddyCredentialStore as _, readHostHeartbeat as a, defaultDesktopAuthCandidates as b, WORKBUDDY_CONNECT_VERSION as c, WorkBuddyCatalog as d, deriveCatalog as f, WORKBUDDY_AUTH_FILE_ENV as g, WORKBUDDY_AUTH_FILENAME as h, processStartTimeMs as i, WorkBuddyUpstreamClient as j, CREDENTIAL_REJECTED_CODE as k, FALLBACK_WORKBUDDY_MODELS as l, ENCRYPTED_CREDENTIAL_CODE as m, clearHostHeartbeat as n, workbuddyHostHeartbeatPath as o, fallbackModelsFor as p, macosBundleExecutable as q, isHeartbeatProcessAlive as r, writeHostHeartbeat as s, WORKBUDDY_HOST_HEARTBEAT_FILENAME as t, FALLBACK_WORKBUDDY_MODELS_GLOBAL as u, WorkBuddyEncryptedCredentialError as v, isEncryptedCredentialError as w, defaultDesktopAuthDirs as x, authFileName as y, WORKBUDDY_APP_EXECUTABLE_ENV as z };