huaweicloud-devkit 1.1.2-next.0 → 1.1.2-next.2

package/plugins/huaweicloud-core/skills/huaweicloud-troubleshooting/SKILL.md

@@ -11,12 +11,12 @@ Use evidence before fixes. Do not guess service behavior when request IDs, regio
 
 ## Critical Warnings
 
-| Trap | Why |
-|------|-----|
-| Error in response body, not HTTP status | Many APIs return HTTP 200 with error in JSON body. Always check `error_code` and `error_msg` |
-| Missing `project_id` is common | New users often omit project_id from API path or CLI. Get it from `IAM KeystoneListProjects` |
-| Sandbox may block hcloud | OpenCode/Codex sandbox can block hcloud metadata files in `~/.hcloud/`. Use `dangerouslyDisableSandbox` or Bash tool |
-| KooCLI param prefix varies | VPC params need `--vpc.x`, ECS params need `--server.x`, ALWAYS check `--help` first |
+| Trap                                    | Why                                                                                                                  |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Error in response body, not HTTP status | Many APIs return HTTP 200 with error in JSON body. Always check `error_code` and `error_msg`                         |
+| Missing `project_id` is common          | New users often omit project_id from API path or CLI. Get it from `IAM KeystoneListProjects`                         |
+| Sandbox may block hcloud                | OpenCode/Codex sandbox can block hcloud metadata files in `~/.hcloud/`. Use `dangerouslyDisableSandbox` or Bash tool |
+| KooCLI param prefix varies              | VPC params need `--vpc.x`, ECS params need `--server.x`, ALWAYS check `--help` first                                 |
 
 ## Workflow
 
@@ -36,42 +36,44 @@ Use evidence before fixes. Do not guess service behavior when request IDs, regio
 
 ## Common Checks
 
-| Check | Command |
-|-------|---------|
-| Authentication | `hcloud configure list` (redacted) |
-| Region | Match CLI region, endpoint, and resource region |
-| Project ID | `hcloud IAM KeystoneListProjects` |
-| Pagination | Add `--limit=100` and check `marker` |
-| Quota | Check service quotas in console or API |
-| IAM Permission | Verify user/role has required action — see `huawei-iam` skill |
-| KooCLI version | `hcloud version` |
+| Check                      | Command                                                                                                                                                                                                                                                                                                                       |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Authentication             | `hcloud configure list` (redacted)                                                                                                                                                                                                                                                                                            |
+| Region                     | Match CLI region, endpoint, and resource region                                                                                                                                                                                                                                                                               |
+| Project ID                 | `hcloud IAM KeystoneListProjects`                                                                                                                                                                                                                                                                                             |
+| Pagination                 | Add `--limit=100` and check `marker`                                                                                                                                                                                                                                                                                          |
+| Quota                      | Check service quotas in console or API                                                                                                                                                                                                                                                                                        |
+| IAM Permission             | Verify user/role has required action — see `huawei-iam` skill                                                                                                                                                                                                                                                                 |
+| KooCLI version             | `hcloud version`                                                                                                                                                                                                                                                                                                              |
+| Public IP (outbound)       | **必须绕过系统代理 + 多源交叉验证**：PowerShell `Invoke-WebRequest` 会走系统代理返回代理出口 IP（实测 167.x vs 真实 117.x，SSH 白名单放错 IP）。正确姿势：`node -e "fetch('https://cip.cc').then(r=>r.text()).then(console.log)"`（node 直连国内源，不继承 IE 代理）+ `curl --noproxy '*' ifconfig.me` 交叉比对；不一致即告警 |
+| SSH 超时但安全组规则"正确" | 先怀疑探测到的公网 IP 走了代理 → 按上行方法重取真实出口 IP，删旧规则加新规则                                                                                                                                                                                                                                                  |
 
 ## Common Error Codes
 
-| Error | Likely Cause | Fix |
-|-------|-------------|-----|
-| AuthFailure / 401 | AK/SK invalid or expired | Regenerate AK/SK, re-run `npx huaweicloud-devkit auth init` |
-| AccessDenied / 403 | IAM permission missing | Check `huawei-iam` skill, add required policy action |
-| NoSuchKey / 404 | Resource not found | Verify resource ID, region, and project_id |
-| QuotaExceeded | Account limit reached | Request quota increase in console |
-| [USE_ERROR] 不正确的参数 | Wrong param name | Run `--help`, check `--param=value` format and nested prefix |
-| Ecs.0005 | Flavor-image mismatch | Check image `__support_*` against flavor virtualization type |
-| FSS.0400 | FunctionGraph latest version error | Strip `:latest` from function URN |
-| FSS.1417 | DEDICATEDGATEWAY missing params | Add instance_id, group_id, protocol, env_name, env_id |
-| APIC.7201 | Missing security_group_id | Add `--security_group_id` param for APIG CreateInstanceV2 |
-| [NETWORK_ERROR] | Transient network failure | Retry with `maxRetries` param or wait and retry |
+| Error                    | Likely Cause                       | Fix                                                          |
+| ------------------------ | ---------------------------------- | ------------------------------------------------------------ |
+| AuthFailure / 401        | AK/SK invalid or expired           | Regenerate AK/SK, re-run `npx huaweicloud-devkit auth init`  |
+| AccessDenied / 403       | IAM permission missing             | Check `huawei-iam` skill, add required policy action         |
+| NoSuchKey / 404          | Resource not found                 | Verify resource ID, region, and project_id                   |
+| QuotaExceeded            | Account limit reached              | Request quota increase in console                            |
+| [USE_ERROR] 不正确的参数 | Wrong param name                   | Run `--help`, check `--param=value` format and nested prefix |
+| Ecs.0005                 | Flavor-image mismatch              | Check image `__support_*` against flavor virtualization type |
+| FSS.0400                 | FunctionGraph latest version error | Strip `:latest` from function URN                            |
+| FSS.1417                 | DEDICATEDGATEWAY missing params    | Add instance_id, group_id, protocol, env_name, env_id        |
+| APIC.7201                | Missing security_group_id          | Add `--security_group_id` param for APIG CreateInstanceV2    |
+| [NETWORK_ERROR]          | Transient network failure          | Retry with `maxRetries` param or wait and retry              |
 
 ## KooCLI Error Types
 
 KooCLI classifies errors into 5 types. The error type prefix in the message guides initial diagnosis:
 
-| Type | Meaning | First Check |
-|------|---------|-------------|
-| `[NETWORK_ERROR]` | HTTP request exception | Network connectivity, firewall, endpoint reachability |
-| `[CLI_ERROR]` | KooCLI internal error | Contact KooCLI support |
-| `[USE_ERROR]` | Incorrect command parameters | Run `--help`, check param names and format |
-| `[OPENAPI_ERROR]` | Cloud service API error | Check service docs, contact service support |
-| `[APIE_ERROR]` | API Explorer metadata error | Contact API Explorer support |
+| Type              | Meaning                      | First Check                                           |
+| ----------------- | ---------------------------- | ----------------------------------------------------- |
+| `[NETWORK_ERROR]` | HTTP request exception       | Network connectivity, firewall, endpoint reachability |
+| `[CLI_ERROR]`     | KooCLI internal error        | Contact KooCLI support                                |
+| `[USE_ERROR]`     | Incorrect command parameters | Run `--help`, check param names and format            |
+| `[OPENAPI_ERROR]` | Cloud service API error      | Check service docs, contact service support           |
+| `[APIE_ERROR]`    | API Explorer metadata error  | Contact API Explorer support                          |
 
 Enable debug with `--cli-debug=true` to see the underlying HTTP request/response and pinpoint network or endpoint issues.
 

package/plugins/huaweicloud-core/skills/huaweicloud-troubleshooting/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "Huawei Cloud Troubleshooting"
-  short_description: "Diagnose Huawei Cloud errors using evidence and read-only checks."
-  default_prompt: "Use $huaweicloud-troubleshooting to diagnose this Huawei Cloud error."
+  display_name: 'Huawei Cloud Troubleshooting'
+  short_description: 'Diagnose Huawei Cloud errors using evidence and read-only checks.'
+  default_prompt: 'Use $huaweicloud-troubleshooting to diagnose this Huawei Cloud error.'

package/plugins/huaweicloud-core/src/auth/agent-registration.mjs

@@ -1,9 +1,22 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
 
-export const SUPPORTED_AGENT_TARGETS = ['opencode', 'codex', 'codex-desktop', 'codearts', 'workbuddy', 'dsh'];
+export const SUPPORTED_AGENT_TARGETS = [
+  'opencode',
+  'codex',
+  'codex-desktop',
+  'codearts',
+  'codearts-work',
+  'workbuddy',
+  'dsh',
+  'officeace',
+  'hermes',
+  'openclaw',
+  'atomcode',
+];
 
 function baseHome() {
   return process.env.HUAWEICLOUD_HOME || homedir();
@@ -66,6 +79,12 @@ function codeartsRegistered() {
   });
 }
 
+function codeartsWorkRegistered() {
+  const path = join(baseHome(), '.codeartswork', 'mcp', 'mcp_settings.json');
+  const cfg = readJsonSafe(path);
+  return Boolean(cfg?.mcp?.['huaweicloud-devkit']);
+}
+
 function workbuddyRegistered() {
   const cfg = readJsonSafe(join(baseHome(), '.workbuddy', 'mcp.json'));
   return Boolean(cfg?.mcpServers?.['huaweicloud-devkit']);
@@ -80,9 +99,122 @@ function dshRegistered() {
   if (!existsSync(patchPath)) return false;
   try {
     const patch = readFileSync(patchPath, 'utf8');
-    return patch.includes('id: mcp-huaweicloud')
-      && patch.includes("@deepseek-ai/dsh-mcp-client")
-      && patch.includes('serverName: huaweicloud');
+    return (
+      (patch.includes('id: huaweicloud-devkit') || patch.includes('id: mcp-huaweicloud')) &&
+      patch.includes('@deepseek-ai/dsh-mcp-client') &&
+      patch.includes('serverName: huaweicloud')
+    );
+  } catch {
+    return false;
+  }
+}
+
+function readOfficeaceRegistryInstallDir() {
+  if (process.platform !== 'win32') return null;
+  try {
+    const r = spawnSync('reg', ['query', 'HKCU\\SOFTWARE\\OfficeAce\\OfficeAce', '/v', 'InstallDir'], {
+      encoding: 'utf8',
+      windowsHide: true,
+      timeout: 5000,
+    });
+    if (r.status === 0) {
+      const m = r.stdout.match(/InstallDir\s+REG_SZ\s+(.+)/);
+      if (m) return m[1].trim();
+    }
+  } catch {}
+  return null;
+}
+
+function officeaceCapabilitiesDir() {
+  const configRoot = process.env.OFFICE_CLAW_CONFIG_ROOT;
+  if (configRoot && existsSync(join(configRoot, 'capabilities.json'))) return configRoot;
+  const regDir = readOfficeaceRegistryInstallDir();
+  if (regDir) {
+    const dir = join(regDir, '.office-claw');
+    if (existsSync(join(dir, 'capabilities.json'))) return dir;
+  }
+  if (process.platform === 'win32') {
+    const bases = [process.env.ProgramFiles, 'C:\\Program Files', 'D:\\Program Files'];
+    if (process.env.LOCALAPPDATA) bases.push(join(process.env.LOCALAPPDATA, 'Programs'));
+    for (const base of bases) {
+      if (!base) continue;
+      const dir = join(base, 'OfficeAce', '.office-claw');
+      if (existsSync(join(dir, 'capabilities.json'))) return dir;
+    }
+  }
+  return null;
+}
+
+function officeaceCapabilitiesDirSafe() {
+  return officeaceCapabilitiesDir() || join(baseHome(), '.office-claw');
+}
+
+function officeaceSqlitePath() {
+  const capDir = officeaceCapabilitiesDirSafe();
+  return join(resolve(capDir, '..'), 'data', 'mcp-connectors.sqlite');
+}
+
+function officeaceRegistered() {
+  let hasMcp = false;
+  const dbPath = officeaceSqlitePath();
+  if (existsSync(dbPath)) {
+    const nodeMajor = Number(process.versions.node.split('.')[0]);
+    if (nodeMajor >= 22) {
+      try {
+        const { DatabaseSync } = createRequire(import.meta.url)('node:sqlite');
+        const db = new DatabaseSync(dbPath, { readonly: true });
+        const row = db.prepare("SELECT enabled FROM mcp_connectors WHERE name = 'huaweicloud-devkit'").get();
+        db.close();
+        hasMcp = Boolean(row?.enabled);
+      } catch {}
+    }
+  }
+
+  const capFile = join(officeaceCapabilitiesDirSafe(), 'capabilities.json');
+  const cfg = readJsonSafe(capFile);
+  const hasSkills = cfg?.capabilities?.some((c) => c.id === 'huaweicloud-core' && c.type === 'skill') ?? false;
+
+  return hasMcp || hasSkills;
+}
+
+function atomcodeHome() {
+  return process.env.ATOMCODE_HOME || join(baseHome(), '.atomcode');
+}
+
+function atomcodeRegistered() {
+  const cfg = readJsonSafe(join(atomcodeHome(), 'mcp.json'));
+  return Boolean(cfg?.mcpServers?.['huaweicloud-devkit']);
+}
+
+function openclawMcpConfigured(cfg) {
+  if (!cfg) return false;
+  if (cfg.mcpServers?.['huaweicloud-devkit']) return true;
+  if (cfg.mcp?.servers?.['huaweicloud-devkit']) return true;
+  return false;
+}
+
+function openclawRegistered() {
+  const pluginCfg = readJsonSafe(join(baseHome(), '.agents', 'huaweicloud-plugins', '.mcp.json'));
+  if (openclawMcpConfigured(pluginCfg)) return true;
+  const nativeCfg = readJsonSafe(join(baseHome(), '.openclaw', 'openclaw.json'));
+  return openclawMcpConfigured(nativeCfg);
+}
+
+function hermesHome() {
+  if (process.env.HERMES_HOME) return process.env.HERMES_HOME;
+  // Hermes on Windows stores under LOCALAPPDATA, not ~/.hermes
+  if (process.platform === 'win32' && process.env.LOCALAPPDATA) {
+    return join(process.env.LOCALAPPDATA, 'hermes');
+  }
+  return join(baseHome(), '.hermes');
+}
+
+function hermesRegistered() {
+  const configPath = join(hermesHome(), 'config.yaml');
+  if (!existsSync(configPath)) return false;
+  try {
+    const content = readFileSync(configPath, 'utf8');
+    return content.includes('mcp_servers:') && content.includes('huaweicloud-devkit');
   } catch {
     return false;
   }
@@ -97,8 +229,13 @@ export function getAgentRegistrationStatuses(target = 'all') {
     if (agent === 'codex-desktop') configured = codexDesktopRegistered();
     if (agent === 'codex') configured = codexCliRegistered();
     if (agent === 'codearts') configured = codeartsRegistered();
+    if (agent === 'codearts-work') configured = codeartsWorkRegistered();
     if (agent === 'workbuddy') configured = workbuddyRegistered();
     if (agent === 'dsh') configured = dshRegistered();
+    if (agent === 'officeace') configured = officeaceRegistered();
+    if (agent === 'hermes') configured = hermesRegistered();
+    if (agent === 'openclaw') configured = openclawRegistered();
+    if (agent === 'atomcode') configured = atomcodeRegistered();
     result.agents[agent] = { configured };
   }
   return result;

package/plugins/huaweicloud-core/src/auth/credentials.mjs

@@ -1,4 +1,13 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 
@@ -7,14 +16,20 @@ import { homedir } from 'node:os';
 // Native Windows has no POSIX modes (statSync always reports 0666), so skip the check there.
 function ensurePrivateMode(path) {
   if (process.platform === 'win32') return;
-  try { chmodSync(path, 0o600); } catch {}
+  try {
+    chmodSync(path, 0o600);
+  } catch {}
   try {
     const mode = statSync(path).mode & 0o777;
     if (mode !== 0o600) {
-      console.warn(`\x1b[33m[WARN]\x1b[0m Could not set 0600 on ${path} (current mode ${mode.toString(8)}). Credentials may be readable by other users.`);
+      console.warn(
+        `\x1b[33m[WARN]\x1b[0m Could not set 0600 on ${path} (current mode ${mode.toString(8)}). Credentials may be readable by other users.`,
+      );
       console.warn(`\x1b[33m       If running under WSL, move the credential home to the Linux filesystem:\x1b[0m`);
       console.warn(`\x1b[33m         export HUAWEICLOUD_HOME=$HOME  (then re-run auth init)\x1b[0m`);
-      console.warn(`\x1b[33m       Or skip file storage entirely with HW_ACCESS_KEY/HW_SECRET_KEY environment variables.\x1b[0m`);
+      console.warn(
+        `\x1b[33m       Or skip file storage entirely with HW_ACCESS_KEY/HW_SECRET_KEY environment variables.\x1b[0m`,
+      );
     }
   } catch {}
 }
@@ -49,12 +64,21 @@ export function writeGlobalCredentials(credentials = {}) {
     sk: String(credentials.sk || ''),
     securityToken: String(credentials.securityToken || ''),
     region: String(credentials.region || ''),
+    ...(credentials.configuredBySession === undefined
+      ? {}
+      : { configuredBySession: Boolean(credentials.configuredBySession) }),
   };
   writeFileSync(path, JSON.stringify(payload, null, 2), { encoding: 'utf8', mode: 0o600 });
   ensurePrivateMode(path);
   return path;
 }
 
+export function setConfiguredBySession(flag) {
+  const stored = readGlobalCredentials();
+  const next = { ...(stored || {}), configuredBySession: Boolean(flag) };
+  writeGlobalCredentials(next);
+}
+
 export function writeObsConfig(credentials = {}) {
   const region = String(credentials.region || '');
   const ak = String(credentials.ak || '');
@@ -78,6 +102,13 @@ export function resolveCredentials(options = {}) {
   let securityToken = process.env.HW_SECURITY_TOKEN;
   let region = process.env.HW_REGION || process.env.HUAWEICLOUD_REGION || '';
 
+  const codeartsCreds = isCodeArtsContext() ? readCodeArtsCredentials() : null;
+  if (codeartsCreds) {
+    if (!ak && codeartsCreds.ak) ak = codeartsCreds.ak;
+    if (!sk && codeartsCreds.sk) sk = codeartsCreds.sk;
+    if (!region && codeartsCreds.region) region = codeartsCreds.region;
+  }
+
   const stored = readGlobalCredentials();
   if (stored) {
     if (!ak && stored.ak) ak = stored.ak;
@@ -86,10 +117,191 @@ export function resolveCredentials(options = {}) {
     if (!region && stored.region) region = stored.region;
   }
 
+  // R9: S1 written by `auth_switch persist` (configuredBySession) is the session's
+  // source of truth and wins over env-injected defaults. Plain S1 (`auth init`)
+  // still yields to env so devspace-style env injection keeps working.
+  if (stored && stored.configuredBySession === true && stored.ak && stored.sk) {
+    ak = stored.ak;
+    sk = stored.sk;
+    if (!securityToken) securityToken = stored.securityToken || '';
+    if (!region) region = stored.region || '';
+  }
+
+  // Sandbox/platform-injected temporary STS credentials (env vars carrying a
+  // security token) must not shadow the user's explicit permanent credentials
+  // from `auth init`. Prefer the stored file when both exist.
+  if (
+    process.env.HW_ACCESS_KEY &&
+    process.env.HW_SECRET_KEY &&
+    process.env.HW_SECURITY_TOKEN &&
+    stored &&
+    stored.ak &&
+    stored.sk
+  ) {
+    ak = stored.ak;
+    sk = stored.sk;
+    securityToken = stored.securityToken || '';
+    region = stored.region || region;
+  }
+
   if (!ak || !sk) {
     if (options.allowMissing) return null;
-    throw new Error('Huawei Cloud credentials are not configured. Run "npx huaweicloud-devkit auth init" or set HW_ACCESS_KEY/HW_SECRET_KEY.');
+    throw new Error(
+      'Huawei Cloud credentials are not configured. Run "npx huaweicloud-devkit auth init" or set HW_ACCESS_KEY/HW_SECRET_KEY.',
+    );
   }
 
   return { ak, sk, securityToken, region };
 }
+
+let _parentCwd = undefined;
+
+export function getParentCwd() {
+  if (_parentCwd !== undefined) return _parentCwd;
+  try {
+    _parentCwd = readlinkSync(`/proc/${process.ppid}/cwd`);
+    return _parentCwd;
+  } catch {
+    _parentCwd = null;
+    return null;
+  }
+}
+
+function isCodeArtsContext() {
+  return (
+    existsSync(join(process.cwd(), '.codeartsdoer')) ||
+    existsSync(join(homedir(), '.codeartsdoer')) ||
+    existsSync(join(homedir(), '.codeartswork'))
+  );
+}
+
+export function readCodeArtsCredentials() {
+  const parentCwd = getParentCwd();
+  const searchDirs = [process.env.CODEARTS_PROJECT_DIR, parentCwd, process.cwd(), homedir()];
+
+  for (const dir of searchDirs) {
+    if (!dir) continue;
+    const path = join(dir, '.codeartsdoer', 'mcp', 'mcp_settings.json');
+    try {
+      if (!existsSync(path)) continue;
+      const config = JSON.parse(readFileSync(path, 'utf8'));
+      const server = config?.mcpServers?.['huaweicloud-devkit'];
+      if (!server?.env) continue;
+
+      const ak = server.env.HW_ACCESS_KEY;
+      const sk = server.env.HW_SECRET_KEY;
+      if (ak && sk) {
+        return {
+          ak,
+          sk,
+          securityToken: server.env.HW_SECURITY_TOKEN || '',
+          region: server.env.HW_REGION || server.env.HUAWEICLOUD_REGION || '',
+        };
+      }
+    } catch {
+      // mcp_settings.json missing or invalid — skip
+    }
+  }
+
+  // CodeArts Work — user-level only
+  {
+    const path = join(homedir(), '.codeartswork', 'mcp', 'mcp_settings.json');
+    try {
+      if (existsSync(path)) {
+        const config = JSON.parse(readFileSync(path, 'utf8'));
+        const server = config?.mcp?.['huaweicloud-devkit'];
+        if (server?.environment) {
+          const ak = server.environment.HW_ACCESS_KEY;
+          const sk = server.environment.HW_SECRET_KEY;
+          if (ak && sk) {
+            return {
+              ak,
+              sk,
+              securityToken: server.environment.HW_SECURITY_TOKEN || '',
+              region: server.environment.HW_REGION || server.environment.HUAWEICLOUD_REGION || '',
+            };
+          }
+        }
+      }
+    } catch {
+      // mcp_settings.json missing or invalid — skip
+    }
+  }
+
+  return null;
+}
+
+let runtimeCredentials = null;
+
+export function setRuntimeCredentials(ak, sk, securityToken, region) {
+  runtimeCredentials = { ak, sk, securityToken: securityToken || '', region: region || '' };
+}
+
+export function clearRuntimeCredentials() {
+  runtimeCredentials = null;
+}
+
+export function hasRuntimeCredentials() {
+  return runtimeCredentials !== null;
+}
+
+export function resolveCredentialsWithRuntime(options = {}) {
+  if (runtimeCredentials) {
+    return {
+      ak: runtimeCredentials.ak,
+      sk: runtimeCredentials.sk,
+      securityToken: runtimeCredentials.securityToken,
+      region: runtimeCredentials.region,
+    };
+  }
+
+  return resolveCredentials(options);
+}
+
+export function lastSyncPath() {
+  return join(baseHome(), '.config', 'huaweicloud', '.last_sync');
+}
+
+export function readLastSync() {
+  const path = lastSyncPath();
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeLastSync() {
+  const path = lastSyncPath();
+  mkdirSync(dirname(path), { recursive: true });
+  const payload = { ts: Date.now() };
+  writeFileSync(path, JSON.stringify(payload), { encoding: 'utf8', mode: 0o600 });
+  ensurePrivateMode(path);
+}
+
+export function backupGlobalCredentials() {
+  const path = globalCredentialsPath();
+  if (!existsSync(path)) return null;
+  const bakPath = `${path}.bak`;
+  try {
+    copyFileSync(path, bakPath);
+    ensurePrivateMode(bakPath);
+    return bakPath;
+  } catch {
+    return null;
+  }
+}
+
+export function restoreGlobalCredentialsBackup() {
+  const path = globalCredentialsPath();
+  const bakPath = `${path}.bak`;
+  if (!existsSync(bakPath)) return false;
+  try {
+    copyFileSync(bakPath, path);
+    ensurePrivateMode(path);
+    return true;
+  } catch {
+    return false;
+  }
+}