create-byan-agent 2.26.0 → 2.27.0

package/CHANGELOG.md

@@ -9,6 +9,153 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed - Portable MCP config: the server resolves its own credentials
+
+The byan MCP server now resolves its config (`BYAN_API_URL` / `BYAN_API_TOKEN`
+and the Leantime pair) instead of depending on `.mcp.json` `${...}` expansion,
+which silently passed a literal `"${BYAN_API_URL}"` to the server when the
+launcher could not expand it — breaking every byan_web call (projects/memory/
+strict sync). This makes the MCP portable across zsh/fish/bash x Linux/Windows/
+macOS and covers Claude Code AND Codex with one mechanism.
+
+- `_byan/mcp/byan-mcp-server/lib/resolve-config.js` (new): per-key precedence
+  `process.env -> ~/.byan/credentials.json -> localhost default`. An unexpanded
+  `${...}` env value is treated as ABSENT (so a stale `.mcp.json` no longer
+  poisons the config), and a missing/invalid credentials file degrades to
+  defaults rather than throwing at boot. `server.js` wires it and backfills
+  `process.env` so downstream readers (Leantime) see the resolved values.
+- The yanstaller now writes a global, gitignored, chmod-600
+  `~/.byan/credentials.json` (`byan-platform-config`'s new `credentials.js`,
+  wired into `setupByanWebIntegration`) — one file for all the user's projects,
+  via `os.homedir()` so it is truly cross-OS with no shell-profile editing.
+- `.mcp.json` no longer carries byan config env: the template drops the `env`
+  block and `mergeByanEntry` stops writing `BYAN_API_URL` (and repairs a stale
+  entry by stripping any `BYAN_API_URL`/`BYAN_API_TOKEN` it carried). The token
+  stays out of `.mcp.json` (it lives only in the gitignored credentials file
+  and .env / settings.local.json).
+- Precedence summary for operators: a real `BYAN_API_URL` env var still wins
+  (prod sidecar / Docker / CI unaffected); the global credentials file is the
+  local-dev fallback; `http://localhost:3737` is the last resort.
+- Reviewed by Quinn + `bmad-compliance` (security domain): a TOCTOU on the
+  credentials file (write-then-chmod exposed the token at 0644 for a window)
+  was fixed by creating the file at mode 0600 directly, with a regression test.
+- Tests: `resolve-config` (8) + `credentials` (8, incl. the TOCTOU + overwrite
+  cases) + the realigned `mcp-config` suite; connector suite 635/635 green.
+
+### Added - OAuth 2.1 per-member identity for the Claude Team org connector
+
+The remote connector now carries per-member identity through OAuth 2.1
+(authorization-code + PKCE S256), so a single Claude.ai Team org connector
+authenticates each member as themselves. This is the only per-member path: a
+Claude.ai org connector sends no custom auth header and has no per-member token
+passthrough, so the API-key-paste channel (kept as a fallback) cannot identify
+members on its own.
+
+- Connector (`server-http.js`) becomes an OAuth protected resource (RFC 9728):
+  serves `/.well-known/oauth-protected-resource` (+ the path-suffixed `/mcp`
+  variant) advertising the byan_web authorization server, and validates every
+  caller's Bearer per-request against byan_web `/api/auth/me` (loopback) BEFORE
+  any tool runs — fail-closed on non-2xx, network error, or timeout. An
+  unauthenticated `/mcp` hit returns `401` with
+  `WWW-Authenticate: Bearer resource_metadata=...` to bootstrap the flow.
+  `BYAN_OAUTH_ISSUER` (falls back to `BYAN_API_URL`) and
+  `BYAN_MCP_BEARER_TIMEOUT_MS` configure it.
+- byan_web (separate repo, committed on its own branch) gains the authorization
+  server: `/.well-known/oauth-authorization-server`, `/authorize` (auto-consent
+  from the Authentik SSO session), `/token` (PKCE S256, `application/x-www-form-urlencoded`,
+  short-TTL revocable `byan_` access token), and the single-use `oauth_codes`
+  table. The shared JSON body parser is untouched (Content-Type gating).
+- `docs/oauth-connector.md`: the OAuth runbook — env vars, the proposed Traefik
+  host-split diff (`/authorize` via forwardauth, `/token` + well-known via
+  strip-trust), and the one-member pilot procedure with the five Claude.ai
+  behaviors to live-verify.
+- Reviewed by Quinn (qualitative) and `bmad-compliance` (adversarial, security
+  domain): a loopback `redirect_uri` hardening (reject userinfo/query/fragment)
+  and RFC 6749 §5.1 token-response cache headers were applied and re-verified
+  with no residual bypass.
+- Deferred, documented (not silently cut): Dynamic Client Registration
+  (pre-registered `claude-ai` client id), refresh tokens (~1h re-auth),
+  server-side `connector:read` scope enforcement (carried RBAC gap; TTL +
+  revocation bound the blast radius), and `/token` rate-limiting.
+- Operator-owned to go live: deploy, the Traefik host-split, the Claude.ai org
+  connector registration, and the pilot.
+
+### Added - Remote MCP connector enabling layer (BYAN native to Claude Team)
+
+The MCP server can now serve a remote HTTP transport so BYAN can be added as a
+Claude.ai Team Org Connector (which also syncs down to Claude Code), without
+changing the local stdio path.
+
+- `createByanServer({ token, remoteOnly })` factory extracted from `server.js`;
+  the stdio entrypoint is guarded so importing the module no longer grabs stdio.
+- `server-http.js`: a stateless streamable-HTTP transport on `/mcp` (+ `/health`),
+  built on the bundled SDK transport (no new dependency). Streamable-HTTP carries
+  the SSE streaming leg itself, so no separate legacy `/sse` endpoint is mounted.
+- Per-request identity: the caller's token is read from each request's
+  `Authorization` header and threaded through the byan_web calls (the module-global
+  token becomes the local stdio fallback), so concurrent Team members reach
+  byan_web with their own token instead of a shared one.
+- Remote-safe surface: `remoteOnly` exposes only `REMOTE_SAFE_TOOLS`, a read-only
+  byan_web-backed allowlist; filesystem-local / stateful / write tools stay
+  stdio-only and are refused over the remote transport. `bin/byan-lint-remote-safe.js`
+  (wired into pre-commit) guards the allowlist.
+- Skill bundles: `bin/byan-build-skill-bundles.js` packages each `.claude/skills`
+  SKILL.md as its own `.zip` into `dist/skill-bundles/` (zero-dep stored ZIP) — one
+  archive per skill, shaped as a single top-level folder + SKILL.md, which is what
+  Claude.ai org Skills accepts (a flat SKILL.md or a multi-skill archive is
+  rejected). `skill-bundles-manifest.json` is the tracked drift ledger with a
+  `--check` pre-commit gate.
+- Tests: per-request auth isolation (two tokens reach byan_web with distinct
+  headers), remote-surface filtering, and the skill bundler.
+- Admin runbook: `docs/connector-admin-runbook.md`. The byan_web hosting track it
+  depended on is now built (see the next entry); a true OAuth flow remains deferred.
+  Projects/Artifacts have no external API so byan_web stays the state authority.
+
+### Added - Remote connector hosting layer (byan_web sidecar + per-member enrollment)
+
+The cross-repo byan_web track the enabling layer depended on is now built: the
+connector runs as a hosted sidecar and each Claude Team member enrolls with their
+own byan_web key.
+
+- Sidecar image: `_byan/mcp/byan-mcp-server/Dockerfile` (node:22-slim + tini PID1,
+  `npm ci --omit=dev`, `CMD node server-http.js`, wget-backed HEALTHCHECK on
+  `/health`) plus a `.dockerignore`. byan_web references the image by tag and does
+  not build the connector source (anti-vendoring boundary).
+- Startup guard: `assertNoAmbientToken` fails the connector boot if `BYAN_API_TOKEN`
+  is present, so a sidecar carries per-request identity only (defense-in-depth on
+  top of `resolveCallerToken`, which ignores the env token in remote mode).
+- Per-member enrollment (byan_web repo): `POST /api/connector/link` mints a personal
+  `byan_` key (idempotent per user, raw returned once, sha256-at-rest, 90-day TTL)
+  that the member pastes into the Claude.ai connector config. The minted key is a
+  full-capability byan_web credential whose read-only behaviour is enforced at the
+  MCP transport only, so it must be treated as a secret. byan_web changes:
+  `routes/connector-link.js` + test, the `byan-mcp-connector` compose service, and a
+  `byan-mcp.<domain>` Traefik route reusing `byan-strip-trust` with no SSO forwardauth.
+- Connector smoke test (`/health` 200, import without binding a port), kept on the
+  BYAN side so byan_web CI stays PostgreSQL-free.
+- Runbook expanded: the hosting build, the per-member enrollment flow, the
+  one-member 48h pilot gate, the security invariants, and the operator-only steps
+  (DNS, image build, compose up, Claude.ai registration) that remain manual.
+
+### Added - Leantime opt-in block in the installer (yanstaller)
+
+`npx create-byan-agent` now offers an optional, opt-in Leantime board
+connection (after the byan_web step, Claude Code targets only; defaults to no).
+When accepted it prompts for the backend URL (with the wrong-host warning), the
+`lt_` API key (masked), and an optional user id, then writes the vars to
+`.claude/settings.local.json` + `.env` (both gitignored), adds the
+`${LEANTIME_API_URL}` / `${LEANTIME_API_TOKEN}` references to the `byan` entry in
+`.mcp.json` (references only, the secret stays out of tracked files), and runs a
+reachability probe that flags the wrong-host case (`non_json`) at install time.
+
+The Leantime token is per-instance: each user configures their own instance and
+key, so it is not shared across installs. Mirrors the existing byan_web block and
+reuses the shared `byan-platform-config` secret-writing primitives. New
+`promptForLeantime` / `LEANTIME_ENV_KEYS` (token-prompt), `mergeLeantimeRefs` /
+`ensureLeantimeRefs` (mcp-config), `validateLeantimeReachability` (validate), and
+the `install/lib/byan-leantime-integration.js` wrapper. Scoped to
+create-byan-agent; update-byan-agent parity is a follow-up.
+
 ## [2.26.0] - 2026-06-16
 
 ### Added - Leantime FD auto-sync hook (FD lifecycle -> board, automatic)

package/install/bin/create-byan-agent-v2.js

@@ -15,6 +15,7 @@ const { getDomainQuestions, buildPhase2Prompt } = require('../lib/domain-questio
 const { generateProjectAgentsDoc } = require('../lib/project-agents-generator');
 const { launchPhase2Chat, generateDefaultConfig } = require('../lib/phase2-chat');
 const { setupByanWebIntegration, validateByanWebReachability } = require('../lib/byan-web-integration');
+const { setupLeantimeIntegration, validateLeantimeReachability } = require('../lib/byan-leantime-integration');
 const { setupClaudeNative } = require('../lib/claude-native-setup');
 const { setupCodexNative } = require('../lib/codex-native-setup');
 const { setupMcpExtensions } = require('../lib/mcp-extensions');
@@ -1368,6 +1369,38 @@ async function install(options = {}) {
     }
   }
 
+  if (needsClaude) {
+    console.log();
+    console.log(chalk.cyan('Leantime board sync (optional — self-hosted)'));
+    let leantimeResult = { configured: false };
+    try {
+      leantimeResult = await setupLeantimeIntegration(projectRoot);
+    } catch (error) {
+      console.log(chalk.yellow(`  ⚠ Leantime setup skipped: ${error.message}`));
+    }
+
+    if (leantimeResult && leantimeResult.configured) {
+      try {
+        const check = await validateLeantimeReachability({
+          apiUrl: leantimeResult.apiUrl,
+          token: leantimeResult.token,
+        });
+        if (check.reachable && !check.reason) {
+          console.log(chalk.green(`  ✓ Leantime reachable (${check.latencyMs}ms)`));
+        } else if (check.reason === 'non_json') {
+          console.log(chalk.yellow(`  ⚠ Leantime responded with non-JSON — ${check.hint}`));
+        } else if (check.reachable) {
+          console.log(chalk.yellow(`  ⚠ Leantime responded (${check.reason}) — check URL/token`));
+        } else {
+          console.log(chalk.yellow(`  ⚠ Leantime UNREACHABLE (${check.reason})`));
+          console.log(chalk.gray(`    Re-run installer or edit .env / .mcp.json to fix later.`));
+        }
+      } catch (_) {
+        // reachability check must never block install
+      }
+    }
+  }
+
   // Step 8: Create config.yaml
   const configSpinner = ora('Generating configuration...').start();
   

package/install/lib/byan-leantime-integration.js

@@ -0,0 +1,104 @@
+/**
+ * Leantime board integration — opt-in installer block.
+ *
+ * Mirror of byan-web-integration.js, for the OPTIONAL self-hosted Leantime
+ * board that the FD -> board sync hook drives. Leantime is per-instance : the
+ * URL + API key are the user's own, never shared. When the user declines, this
+ * is a no-op that writes nothing.
+ *
+ * Persistence (same channels as byan_web, both gitignored) :
+ *   - .claude/settings.local.json env  -> Claude Code injects into the MCP server
+ *   - .env                             -> shell tools / Codex CLI
+ *   - .mcp.json byan entry             -> ${LEANTIME_*} REFERENCES only (never the
+ *                                         secret value); see mcp-config.ensureLeantimeRefs
+ *
+ * The token NEVER lands in a tracked file : settings.local.json and .env are
+ * gitignored, and .mcp.json carries only the `${...}` expansion placeholders.
+ */
+const path = require('path');
+const chalk = require('chalk');
+const {
+  mcpConfig: { ensureLeantimeRefs },
+  envConfig: { updateSettingsLocal: sharedUpdateSettingsLocal, updateDotenv: sharedUpdateDotenv },
+  tokenPrompt: { promptForLeantime },
+  validate: { validateLeantimeReachability },
+} = require('byan-platform-config');
+
+// Shared writers return { path } — unwrap to a plain string path for the
+// console report, matching byan-web-integration's surface.
+async function updateSettingsLocal(projectRoot, env) {
+  const result = await sharedUpdateSettingsLocal(projectRoot, env);
+  return result.path;
+}
+
+async function updateDotenv(projectRoot, env) {
+  const result = await sharedUpdateDotenv(projectRoot, env);
+  return result.path;
+}
+
+/**
+ * Prompt for (or accept preset) Leantime config and persist it.
+ *
+ * @param {string} projectRoot
+ * @param {{ skipPrompts?: boolean, presetInputs?: object, quiet?: boolean }} options
+ *   skipPrompts + presetInputs drive the non-interactive path (tests / CI),
+ *   exactly like setupStagingConsent / setupByanWebIntegration.
+ * @returns {Promise<{ configured: boolean, settingsPath?: string, envPath?: string, mcpPath?: string, apiUrl?: string, token?: string, assignUserId?: string }>}
+ */
+async function setupLeantimeIntegration(projectRoot, options = {}) {
+  const skip = options.skipPrompts === true;
+  const inputs = skip
+    ? options.presetInputs || { configured: false }
+    : await promptForLeantime();
+
+  if (!inputs.configured) {
+    if (!options.quiet) {
+      console.log(
+        chalk.gray(
+          '  ℹ Leantime board sync skipped. Re-run installer or edit .env / .claude/settings.local.json to enable later.'
+        )
+      );
+    }
+    return { configured: false };
+  }
+
+  // Only non-empty vars are written : an absent assign-id must not leave a
+  // dangling LEANTIME_ASSIGN_USER_ID= line.
+  const env = {
+    LEANTIME_API_URL: inputs.apiUrl,
+    LEANTIME_API_TOKEN: inputs.token,
+  };
+  if (inputs.assignUserId) {
+    env.LEANTIME_ASSIGN_USER_ID = String(inputs.assignUserId);
+  }
+
+  const settingsPath = await updateSettingsLocal(projectRoot, env);
+  const envPath = await updateDotenv(projectRoot, env);
+  const mcpResult = await ensureLeantimeRefs(projectRoot);
+  const mcpPath = mcpResult.path;
+
+  if (!options.quiet) {
+    console.log(chalk.green('  ✓ Leantime board sync configured'));
+    console.log(chalk.gray(`    - Token (Claude Code) -> ${path.relative(projectRoot, settingsPath)}`));
+    console.log(chalk.gray(`    - Token (shell / env) -> ${path.relative(projectRoot, envPath)}`));
+    console.log(chalk.gray(`    - Refs (\${LEANTIME_*}) -> ${path.relative(projectRoot, mcpPath)}`));
+  }
+
+  return {
+    configured: true,
+    settingsPath,
+    envPath,
+    mcpPath,
+    apiUrl: inputs.apiUrl,
+    token: inputs.token,
+    assignUserId: inputs.assignUserId,
+  };
+}
+
+module.exports = {
+  setupLeantimeIntegration,
+  updateSettingsLocal,
+  updateDotenv,
+  promptForLeantime,
+  validateLeantimeReachability,
+};

package/install/lib/byan-web-integration.js

@@ -11,6 +11,8 @@ const {
   envConfig: { updateSettingsLocal: sharedUpdateSettingsLocal, updateDotenv: sharedUpdateDotenv },
   tokenPrompt: { promptForToken, ENV_KEYS },
   validate: { validateByanWebReachability },
+  credentials: { writeCredentials: sharedWriteCredentials },
+  urlUtils: { stripApiSuffix },
 } = require('byan-platform-config');
 
 // Shared primitives return { path: string } — unwrap to plain string for
@@ -54,12 +56,18 @@ async function setupByanWebIntegration(projectRoot, options = {}) {
   const settingsPath = await updateSettingsLocal(projectRoot, env);
   const envPath = await updateDotenv(projectRoot, env);
   const mcpPath = await ensureMcpConfig(projectRoot, inputs.apiUrl, inputs.token);
+  // Global per-user credentials file: the source the MCP server resolves at
+  // boot (env -> ~/.byan/credentials.json -> localhost). This is what makes the
+  // MCP portable across shells/OSes and Claude Code AND Codex, instead of
+  // relying on .mcp.json ${} expansion or settings.local.json env injection.
+  const credsResult = await sharedWriteCredentials({ BYAN_API_URL: stripApiSuffix(inputs.apiUrl), BYAN_API_TOKEN: inputs.token });
 
   if (!options.quiet) {
     console.log(chalk.green(`  ✓ byan_web integration configured`));
     console.log(chalk.gray(`    - Token (Claude Code) → ${path.relative(projectRoot, settingsPath)}`));
     console.log(chalk.gray(`    - Token (shell / env) → ${path.relative(projectRoot, envPath)}`));
     console.log(chalk.gray(`    - MCP server registered in ${path.relative(projectRoot, mcpPath)}`));
+    console.log(chalk.gray(`    - MCP credentials (all shells/OS) → ${credsResult.path}`));
   }
 
   return {
@@ -67,6 +75,7 @@ async function setupByanWebIntegration(projectRoot, options = {}) {
     settingsPath,
     envPath,
     mcpPath,
+    credentialsPath: credsResult.path,
     apiUrl: inputs.apiUrl,
     token: inputs.token,
   };

package/install/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-byan-agent",
-  "version": "2.26.0",
-  "description": "BYAN v2.2.2 - Intelligent AI agent installer with multi-platform native support (GitHub Copilot CLI, Claude Code, Codex/OpenCode)",
+  "version": "2.27.0",
+  "description": "BYAN - Intelligent AI agent installer with multi-platform native support (Claude Code, Codex/OpenCode)",
   "bin": {
     "create-byan-agent": "bin/create-byan-agent-v2.js"
   },

package/install/packages/platform-config/README.md

@@ -22,6 +22,7 @@ const {
   tokenPrompt,
   validate,
   urlUtils,
+  credentials,
 } = require('byan-platform-config');
 ```
 
@@ -92,6 +93,27 @@ urlUtils.buildAuthHeader('byan_abc');       // → { Authorization: 'ApiKey byan
 urlUtils.buildAuthHeader('eyJ...');         // → { Authorization: 'Bearer eyJ...' }
 ```
 
+### credentials — global `~/.byan/credentials.json`
+
+The byan MCP server resolves its own config (`BYAN_API_URL`, `BYAN_API_TOKEN`,
+`LEANTIME_API_URL`, `LEANTIME_API_TOKEN`) at boot. `credentials.writeCredentials`
+persists those to a global, per-user, gitignored, chmod-600 file so the config
+is portable across shells (zsh/fish/bash) and OSes (`os.homedir()` resolves `~`
+on Unix and `%USERPROFILE%` on Windows) and reaches Claude Code AND Codex —
+without depending on `.mcp.json` `${...}` expansion.
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `writeCredentials` | `(values, { homedir? }) -> { path, written }` | merge-write the known keys; created at mode 0600; idempotent; ignores `${...}`/empty |
+| `readCredentials` | `(homedir?) -> object` | `{}` on a missing/invalid file (does not throw) |
+| `credentialsPath` | `(homedir?) -> string` | `<homedir>/.byan/credentials.json` |
+
+**Resolution precedence (server side):** `process.env` (a real value; an
+unexpanded `${...}` is treated as absent) `->` `~/.byan/credentials.json` `->`
+`http://localhost:3737`. A real `BYAN_API_URL` env var therefore still wins
+(prod sidecar / Docker / CI), the global file is the local-dev fallback, and the
+token is kept out of `.mcp.json`.
+
 ## Test
 
 ```bash
@@ -101,7 +123,8 @@ npm test
 ## Design invariants
 
 - READ-MERGE-WRITE on every file operation — unknown keys are preserved.
-- `ensureMcpConfig` keeps `mcpServers.byan.command` and `.args` if already set.
+- `ensureMcpConfig` keeps `mcpServers.byan.command` and `.args` if already set; it writes NO byan config env (the server resolves its own).
+- `writeCredentials` creates the file at mode 0600 (no group/other read window) and is a no-op-safe merge.
 - `validateByanWebReachability` resolves instead of rejecting — errors surface in the result object.
 - `stripApiSuffix` is idempotent and leaves URLs without a `/api` suffix untouched.
 - `buildAuthHeader` returns `{}` (not `{ Authorization: undefined }`) when token is missing.

package/install/packages/platform-config/index.js

@@ -13,4 +13,5 @@ module.exports = {
   tokenPrompt: require('./lib/token-prompt'),
   validate: require('./lib/validate'),
   urlUtils: require('./lib/url-utils'),
+  credentials: require('./lib/credentials'),
 };

package/install/packages/platform-config/lib/credentials.js

@@ -0,0 +1,101 @@
+/**
+ * Global per-user credentials file: ~/.byan/credentials.json.
+ *
+ * The byan MCP server resolves its config (BYAN_API_URL / BYAN_API_TOKEN /
+ * LEANTIME_API_URL / LEANTIME_API_TOKEN) from this file when the matching env
+ * var is absent (see _byan/mcp/byan-mcp-server/lib/resolve-config.js). Writing
+ * it here with Node fs is cross-shell AND cross-OS: os.homedir() resolves ~ on
+ * Unix and %USERPROFILE% on Windows, so a yanstaller install configures the MCP
+ * for every shell (zsh/fish/bash) with no profile editing and no reliance on
+ * the fragile .mcp.json ${} expansion.
+ *
+ * The file holds a secret (the token), so it lives OUTSIDE any repo (under the
+ * user HOME, never committed) and is chmod 600 on Unix.
+ */
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs-extra');
+
+// Keys the credentials file understands. Any other key passed in is ignored.
+const KNOWN_KEYS = ['BYAN_API_URL', 'BYAN_API_TOKEN', 'LEANTIME_API_URL', 'LEANTIME_API_TOKEN'];
+
+function credentialsDir(homedir = os.homedir()) {
+  return path.join(homedir, '.byan');
+}
+
+function credentialsPath(homedir = os.homedir()) {
+  return path.join(credentialsDir(homedir), 'credentials.json');
+}
+
+// A value worth persisting: a non-empty string that is NOT an unexpanded
+// ${..} placeholder (persisting a placeholder would defeat the whole point).
+function usable(v) {
+  return typeof v === 'string' && v.trim().length > 0 && !/^\$\{.+\}$/.test(v.trim());
+}
+
+/**
+ * Read the credentials file. Missing file or invalid JSON yields {} -- never
+ * throws, so a first run or a corrupted file does not break the installer.
+ *
+ * @param {string} [homedir=os.homedir()]
+ * @returns {Promise<object>}
+ */
+async function readCredentials(homedir = os.homedir()) {
+  try {
+    const data = await fs.readJson(credentialsPath(homedir));
+    return data && typeof data === 'object' ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Merge-write the global credentials file. Only the known, usable keys in
+ * `values` are written; existing keys are preserved (idempotent: re-running
+ * with the same values leaves the content unchanged). The directory is created
+ * if absent and the file is chmod 600 on Unix (best-effort: a platform without
+ * POSIX modes, e.g. Windows, swallows the chmod rather than failing the install).
+ *
+ * @param {object} values  subset of KNOWN_KEYS -> string
+ * @param {{ homedir?: string }} [opts]
+ * @returns {Promise<{ path: string, written: string[] }>}
+ */
+async function writeCredentials(values = {}, opts = {}) {
+  const homedir = opts.homedir || os.homedir();
+  const dir = credentialsDir(homedir);
+  const file = credentialsPath(homedir);
+
+  const current = await readCredentials(homedir);
+  const next = { ...current };
+  const written = [];
+  for (const key of KNOWN_KEYS) {
+    if (usable(values[key])) {
+      next[key] = values[key];
+      written.push(key);
+    }
+  }
+
+  await fs.mkdirp(dir);
+  // Create restrictively AT THE SOURCE: the `mode` option makes a NEW file land
+  // at 0600 directly, closing the TOCTOU window where a write-then-chmod would
+  // expose the token at the umask default (0644, group/other-readable) between
+  // the two syscalls. `mode` only applies when the file is created, so the
+  // chmod below still runs to tighten a pre-existing file on overwrite.
+  await fs.writeFile(file, JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+  try {
+    await fs.chmod(file, 0o600);
+  } catch {
+    // POSIX modes unsupported (e.g. Windows / exotic FS): the file is still
+    // written, just without the 600 tightening. Do not fail the install.
+  }
+  return { path: file, written };
+}
+
+module.exports = {
+  writeCredentials,
+  readCredentials,
+  credentialsPath,
+  credentialsDir,
+  KNOWN_KEYS,
+};