dsh-connect-workbuddy 2.0.5 → 2.0.10

package/lib/{host-heartbeat-BOrNj3pY.js → host-heartbeat-DPbL9oi2.js}

@@ -1,10 +1,249 @@
 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 } from "node:fs";
+//#region src/at-rest.ts
+/**
+* WorkBuddy desktop "at-rest" credential decryption.
+*
+* The WorkBuddy desktop app (2.x, Windows builds first) no longer stores
+* `auth.accessToken` / `auth.refreshToken` as plain strings. It now 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.
+*
+* @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, per platform. */
+const APP_EXECUTABLE_NAME = "WorkBuddy.exe";
+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");
+}
+/**
+* Candidate paths of the WorkBuddy desktop executable, in probe order.
+*
+* The Windows build is the one that encrypts credentials, so Windows leads;
+* the macOS bundle is listed because the same native module ships there and a
+* future build may enable the policy, and `undefined` entries (an unset env
+* variable) are dropped.
+*/
+function workbuddyAppExecutableCandidates(platform = process.platform, home = homedir(), env = process.env) {
+	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), 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") candidates.push("/Applications/WorkBuddy.app/Contents/MacOS/WorkBuddy", join(home, "Applications", "WorkBuddy.app", "Contents", "MacOS", "WorkBuddy"));
+	return candidates.filter((candidate) => candidate !== void 0 && candidate !== "");
+}
+/**
+* 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 {}
+}
+/**
+* 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 +474,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 +519,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)}`);
 }
@@ -701,15 +975,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 +1043,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 +1074,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,16 +1184,72 @@ 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
 * discovery.
 *
@@ -864,6 +1267,7 @@ var WorkBuddyCredentialStore = class {
 	legacyOwnPath;
 	legacyOwnPathExplicit;
 	authDirs;
+	resolveAtRestKey;
 	desktopPathOverride;
 	accountId;
 	inflight;
@@ -876,6 +1280,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 +1410,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 +1464,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,6 +1495,18 @@ 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();
@@ -1190,6 +1606,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
@@ -1440,10 +1916,36 @@ function applyContextBudgets(catalog, budgets = {}) {
 function deriveCatalog(catalog, enabled, budgets = {}) {
 	return applyContextBudgets(enabled.size === 0 ? catalog : catalog.filter((model) => enabled.has(model.id)), budgets);
 }
-/** Mutable catalog shared by the shim's `/v1/models` and the adapter. */
+/**
+* Mutable catalog shared by the shim's `/v1/models` and the adapter.
+*
+* The static fallback exists so an OFFLINE upstream never leaves a provider
+* empty — but "offline" presumes the region is usable at all. A region with no
+* local sign-in cannot serve one single request, so seeding it with a roster
+* puts models in the picker that are guaranteed to 401 (issue #12). The host
+* distinguishes the two cases through {@link WorkBuddyCatalog.setRegionUsable}.
+*/
 var WorkBuddyCatalog = class {
 	models;
 	/**
+	* Whether this region has any local sign-in. Defaults to `true` — the
+	* permissive direction — so a scan that has not run yet (or failed) keeps
+	* serving the fallback rather than blanking a region that may be fine.
+	*/
+	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.
@@ -1451,9 +1953,57 @@ var WorkBuddyCatalog = class {
 	constructor(region = "cn") {
 		this.models = fallbackModelsFor(region);
 	}
-	/** Current entries; the fallback list until the upstream answer lands. */
+	/**
+	* Current entries; the fallback list until the upstream answer lands.
+	*
+	* 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.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.
+	*
+	* Separate from {@link set} on purpose: `set()` carries a live upstream
+	* answer and must never be empty, while "this region has no account" is a
+	* legitimate empty state that must survive across refreshes. Keeping them
+	* apart is what lets the non-empty guard stay strict.
+	*
+	* @returns whether the value changed, so the caller can skip invalidating
+	*   its adapter snapshots when nothing moved.
+	*/
+	setRegionUsable(usable) {
+		if (this.usable === usable) return false;
+		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) {
@@ -1464,7 +2014,7 @@ var WorkBuddyCatalog = class {
 //#endregion
 //#region src/version.ts
 /** The npm package version this build was produced from. */
-const WORKBUDDY_CONNECT_VERSION = "2.0.5";
+const WORKBUDDY_CONNECT_VERSION = "2.0.10";
 //#endregion
 //#region src/host-heartbeat.ts
 /**
@@ -1570,4 +2120,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 { isCredentialRejectedError as A, fetchAtRestKeyPayload as B, parseWorkBuddyAuth as C, WorkBuddyCredentialRejectedError as D, CREDENTIAL_REJECTED_CODE as E, regionOf as F, workbuddyAppExecutableCandidates as G, isEncryptedFieldWrapper as H, WORKBUDDY_APP_EXECUTABLE_ENV as I, clearAtRestKeyCache as L, parseReasoning as M, parseUpstreamModel as N, WorkBuddyUpstreamClient as O, prepareChatBody as P, deriveAtRestKey as R, legacyWorkbuddyOwnAuthPath as S, workbuddyOwnAuthPath as T, openEncryptedField as U, findWorkbuddyAppExecutable as V, readAtRestKey as W, 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, parseCreditMultiplier as j, classifyUpstreamError 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, workbuddyAccountId as w, hasEncryptedCredentialFields as x, defaultDesktopAuthDirs as y, deriveAtRestKeyId as z };