feat(kimi-code): store OAuth credentials in the OS keychain

Store OAuth credentials (managed provider logins and MCP server grants)
in the OS keychain (macOS Keychain, Windows Credential Manager, Linux
Secret Service) whenever it is usable, with the plaintext file store as
the automatic fallback. The credentials_store key in config.toml picks
the mode: auto (default; keychain preferred, plaintext kept in sync as
a compatibility bridge for file-only peers), keyring (authoritative,
plaintext pruned after migration), or file (plaintext only).
KIMI_DISABLE_KEYRING=1 overrides the config and forces the file store.

Author: 7Sageer

.changeset/keyring-credential-storage.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": minor
+---
+
+Store OAuth credentials in the operating system keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service) when available, keeping the plaintext files in sync for compatibility; set `credentials_store` in `config.toml` (`auto` / `keyring` / `file`) to control the behavior, or `KIMI_DISABLE_KEYRING=1` to force the file store.

apps/kimi-code/package.json

@@ -79,6 +79,7 @@
   },
   "optionalDependencies": {
     "@mariozechner/clipboard": "^0.3.9",
+    "@napi-rs/keyring": "1.3.0",
     "node-pty": "^1.1.0"
   },
   "devDependencies": {

apps/kimi-code/scripts/native/check-bundle.mjs

@@ -20,6 +20,9 @@ const optionalRuntimeRequires = new Set([
   'fast-json-stringify/lib/validator',
   'utf-8-validate',
 ]);
+// Native bindings that stay external on purpose: installNativeModuleHook
+// resolves them from the SEA native-asset cache (or node_modules outside SEA).
+const handledNativeRuntimeRequires = new Set(['@napi-rs/keyring']);
 const optionalRelativeRuntimeRequires = new Set(['./crypto/build/Release/sshcrypto.node']);
 
 function executableLines(text) {
@@ -37,7 +40,9 @@ function checkBundle(bundlePath, { worker = false } = {}) {
   if (!existsSync(bundlePath)) return [`bundle does not exist: ${bundlePath}`];
   const text = readFileSync(bundlePath, 'utf-8');
   const errors = [];
-  const allowedExternal = worker ? new Set() : optionalRuntimeRequires;
+  const allowedExternal = worker
+    ? new Set()
+    : new Set([...optionalRuntimeRequires, ...handledNativeRuntimeRequires]);
   const allowedRelative = worker ? new Set() : optionalRelativeRuntimeRequires;
 
   const checkSpecifier = (specifier, kind) => {

apps/kimi-code/scripts/native/native-deps.mjs

@@ -27,6 +27,15 @@ const clipboardSubpackageByTarget = Object.freeze({
   'win32-x64': '@mariozechner/clipboard-win32-x64-msvc',
 });
 
+const keyringSubpackageByTarget = Object.freeze({
+  'darwin-arm64': '@napi-rs/keyring-darwin-arm64',
+  'darwin-x64': '@napi-rs/keyring-darwin-x64',
+  'linux-arm64': '@napi-rs/keyring-linux-arm64-gnu',
+  'linux-x64': '@napi-rs/keyring-linux-x64-gnu',
+  'win32-arm64': '@napi-rs/keyring-win32-arm64-msvc',
+  'win32-x64': '@napi-rs/keyring-win32-x64-msvc',
+});
+
 // pi-tui ships platform-specific native helpers (no Linux build):
 // - darwin: Shift-modifier detection for Terminal.app Shift+Enter
 // - win32: enable ENABLE_VIRTUAL_TERMINAL_INPUT so Shift+Tab is distinguishable
@@ -73,6 +82,18 @@ export const nativeDeps = Object.freeze([
     collect: 'native-files',
     parent: 'clipboard-host',
   },
+  {
+    id: 'keyring-host',
+    name: () => '@napi-rs/keyring',
+    collect: 'js-only',
+    parent: null,
+  },
+  {
+    id: 'keyring-target',
+    name: (target) => keyringSubpackageByTarget[target],
+    collect: 'native-files',
+    parent: 'keyring-host',
+  },
   {
     id: 'pi-tui',
     name: () => '@moonshot-ai/pi-tui',

apps/kimi-code/src/cli/sub/web/remote-control.ts

@@ -5,8 +5,8 @@ import { setTimeout as sleep } from 'node:timers/promises';
 
 import {
   createKimiDeviceId,
-  FileTokenStorage,
   KIMI_CODE_PROVIDER_NAME,
+  resolveTokenStorage,
   resolveKimiTokenStorageName,
 } from '@moonshot-ai/kimi-code-oauth';
 import { WebSocket, type RawData } from 'ws';
@@ -293,7 +293,7 @@ export async function startRemoteControl(
   if (options.localServerToken.length === 0) {
     throw new Error('Remote Control requires local server authentication.');
   }
-  const storage = new FileTokenStorage(join(options.homeDir, 'credentials'));
+  const storage = resolveTokenStorage(join(options.homeDir, 'credentials'));
   const token = await storage.load(
     resolveKimiTokenStorageName({ providerName: KIMI_CODE_PROVIDER_NAME }),
   );

apps/kimi-code/src/main.ts

@@ -40,6 +40,7 @@ import { maybeRelaunchWithStagedNativeUpdate } from './cli/update/native-swap';
 import { createKimiCodeHostIdentity, getVersion } from './cli/version';
 import { CLI_SHUTDOWN_TIMEOUT_MS, CLI_UI_MODE, PROCESS_NAME } from './constant/app';
 import { cleanupStaleNativeCacheForCurrent } from './native/native-assets';
+import { installKeyringBackend } from './native/keyring';
 import { installMinidbTextBuildWorker } from './native/minidb-worker';
 import { installKapSearchWorker } from './native/search-worker';
 import { installNativeModuleHook } from './native/module-hook';
@@ -170,6 +171,11 @@ function bootstrap(): void {
   // invalid proxy URL is reported and ignored rather than aborting startup.
   installGlobalProxyDispatcher();
   installNativeModuleHook();
+  // Register the OS keychain as an OAuth token-store backend. Whether it is
+  // actually used is decided inside packages/oauth (the credentials_store
+  // config, KIMI_DISABLE_KEYRING, and a capability probe); a load failure
+  // only warns and the file store stays in charge.
+  installKeyringBackend();
   // Best-effort SEA worker installation. Diagnostics are trace-only and avoid
   // exposing the user's cache path; failure keeps MiniDb's bounded inline mode.
   const workerInstall = installMinidbTextBuildWorker();

apps/kimi-code/src/native/keyring.ts

@@ -0,0 +1,69 @@
+/**
+ * OS keychain backend registration for OAuth token storage.
+ *
+ * `@napi-rs/keyring` is an optional native dependency owned by this app (the
+ * packages/ layer stays pure TypeScript and receives the binding through
+ * `registerKeyringBackend`). In a SEA binary the require below is redirected
+ * to the extracted native-asset cache by `installNativeModuleHook`; outside
+ * SEA it resolves from node_modules. When the binding cannot be loaded we
+ * warn and skip registration, and the OAuth toolkit keeps the plaintext-file
+ * token store. Whether the keychain is actually used is decided per process
+ * by the toolkit's `resolveTokenStorage` (the `credentials_store` config,
+ * the `KIMI_DISABLE_KEYRING` kill switch, and a capability probe) —
+ * registration here is unconditional.
+ */
+
+import { createRequire } from 'node:module';
+
+import type {
+  KeyringApi,
+  KeyringEntry,
+  KeyringStorageObserver,
+} from '@moonshot-ai/kimi-code-oauth';
+import { registerKeyringBackend } from '@moonshot-ai/kimi-code-oauth';
+import { log } from '@moonshot-ai/kimi-code-sdk';
+import { track } from '@moonshot-ai/kimi-telemetry';
+
+/** The slice of the `@napi-rs/keyring` module shape the storage contract needs. */
+interface NapiKeyringModule {
+  Entry: new (service: string, account: string) => KeyringEntry;
+  findCredentials: (service: string) => Array<{ account: string; password: string }>;
+}
+
+function adaptNapiKeyring(mod: NapiKeyringModule): KeyringApi {
+  return {
+    createEntry(service, account) {
+      return new mod.Entry(service, account);
+    },
+    findAccounts(service) {
+      return mod.findCredentials(service).map((credential) => credential.account);
+    },
+  };
+}
+
+const keyringObserver: KeyringStorageObserver = {
+  onBackendSelected(backend, reason) {
+    log.info('oauth token storage backend selected', { backend, reason });
+    track('keyring_backend_selected', { backend, reason });
+  },
+  onKeyringDegraded(operation, message) {
+    log.warn('oauth keyring backend degraded to file storage', { operation, message });
+    track('keyring_degraded', { operation });
+  },
+  onMigrated(name) {
+    log.info('oauth token migrated to the OS keychain', { name });
+    track('keyring_token_migrated');
+  },
+};
+
+export function installKeyringBackend(): void {
+  let mod: NapiKeyringModule;
+  try {
+    const require = createRequire(import.meta.url);
+    mod = require('@napi-rs/keyring') as NapiKeyringModule;
+  } catch (error) {
+    log.warn('@napi-rs/keyring native binding failed to load; oauth tokens stay in the file store', { error });
+    return;
+  }
+  registerKeyringBackend(adaptNapiKeyring(mod), keyringObserver);
+}

apps/kimi-code/src/native/module-hook.ts

@@ -3,6 +3,7 @@ import { createRequire } from 'node:module';
 import { join } from 'node:path';
 
 import { getNativePackageRoot } from './native-assets';
+import { loadNativePackage } from './native-require';
 
 type ModuleLoad = (request: string, parent: unknown, isMain: boolean) => unknown;
 
@@ -11,7 +12,17 @@ interface ModuleWithLoad {
 }
 
 const nodeRequire = createRequire(import.meta.url);
+
+// Bare-specifier native packages that ship as SEA native assets. In a SEA
+// binary there is no node_modules next to the executable, so redirect the
+// require to the extracted native-asset cache; loadNativePackage returns null
+// outside SEA and the normal resolution below takes over. The reentrancy
+// guard lets the cache-root require inside loadNativePackage fall through to
+// the original loader.
+const NATIVE_ASSET_PACKAGES = new Set(['@napi-rs/keyring']);
+
 let installed = false;
+let loadingNativePackage = false;
 
 // pi-tui loads its platform-specific native helpers via an absolute-path
 // require() computed from import.meta.url / process.execPath
@@ -37,6 +48,15 @@ export function installNativeModuleHook(): void {
     parent: unknown,
     isMain: boolean,
   ): unknown {
+    if (NATIVE_ASSET_PACKAGES.has(request) && !loadingNativePackage) {
+      loadingNativePackage = true;
+      try {
+        const pkg = loadNativePackage<unknown>(request);
+        if (pkg !== null) return pkg;
+      } finally {
+        loadingNativePackage = false;
+      }
+    }
     if (
       typeof request === 'string' &&
       PI_TUI_NATIVE_PATTERN.test(request) &&

apps/kimi-code/src/native/smoke.ts

@@ -13,7 +13,7 @@ import {
   getNativePackageRoot,
 } from './native-assets';
 
-const smokePackages = ['@mariozechner/clipboard', '@moonshot-ai/pi-tui'];
+const smokePackages = ['@mariozechner/clipboard', '@moonshot-ai/pi-tui', '@napi-rs/keyring'];
 
 function smokePiTuiNativeLoad(): void {
   const platform = process.platform;

apps/kimi-code/test/cli/web/remote-control.test.ts

@@ -1,3 +1,9 @@
+/**
+ * Remote Control CLI integration: flags, links, tunnel auth/lifecycle, and process locking.
+ * Public entry points use local HTTP/WebSocket relays; the OS keyring boundary is faked.
+ * Run: pnpm --filter @moonshot-ai/kimi-code exec vitest run test/cli/web/remote-control.test.ts
+ */
+
 import { createServer, type IncomingMessage } from 'node:http';
 import { spawn } from 'node:child_process';
 import { mkdtempSync, rmSync } from 'node:fs';
@@ -8,8 +14,14 @@ import { join } from 'node:path';
 import {
   FileTokenStorage,
   KIMI_CODE_PROVIDER_NAME,
+  keyringServiceForCredentialsDir,
+  registerKeyringBackend,
   resolveKimiTokenStorageName,
+  resolveTokenStorage,
   type TokenInfo,
+  type KeyringApi,
+  type KeyringEntry,
+  unregisterKeyringBackend,
 } from '@moonshot-ai/kimi-code-oauth';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { WebSocketServer, type RawData, type WebSocket } from 'ws';
@@ -41,9 +53,32 @@ const cleanups: Array<() => Promise<void> | void> = [];
 
 afterEach(async () => {
   vi.unstubAllEnvs();
+  unregisterKeyringBackend();
   while (cleanups.length > 0) await cleanups.pop()!();
 });
 
+class FakeKeyring implements KeyringApi {
+  private readonly store = new Map<string, string>();
+
+  createEntry(service: string, account: string): KeyringEntry {
+    const key = `${service}\u0000${account}`;
+    return {
+      getPassword: () => this.store.get(key) ?? null,
+      setPassword: (password) => {
+        this.store.set(key, password);
+      },
+      deleteCredential: () => this.store.delete(key),
+    };
+  }
+
+  findAccounts(service: string): string[] {
+    const prefix = `${service}\u0000`;
+    return [...this.store.keys()]
+      .filter((key) => key.startsWith(prefix))
+      .map((key) => key.slice(prefix.length));
+  }
+}
+
 describe('Remote Control experimental flag', () => {
   it('is off unless the per-feature env or the master switch is truthy', () => {
     expect(isRemoteControlEnabled({})).toBe(false);
@@ -202,6 +237,44 @@ describe('Remote Control HTTP forwarding', () => {
 });
 
 describe('Remote Control tunnel', () => {
+  it('authenticates the relay when the Kimi login exists only in the keychain', async () => {
+    // The suite-level KIMI_DISABLE_KEYRING=1 (vitest.config.ts) would force the
+    // file store; this test exercises the keychain path specifically.
+    vi.stubEnv('KIMI_DISABLE_KEYRING', '0');
+    const homeDir = mkdtempSync(join(tmpdir(), 'kimi-rc-keyring-'));
+    cleanups.push(() => rmSync(homeDir, { recursive: true, force: true }));
+    const keyring = new FakeKeyring();
+    registerKeyringBackend(keyring);
+    const credentialsDir = join(homeDir, 'credentials');
+    const storage = resolveTokenStorage(credentialsDir);
+    await storage.save(
+      resolveKimiTokenStorageName({ providerName: KIMI_CODE_PROVIDER_NAME }),
+      TOKEN,
+    );
+    expect(keyring.findAccounts(keyringServiceForCredentialsDir(credentialsDir))).toContain(
+      resolveKimiTokenStorageName({ providerName: KIMI_CODE_PROVIDER_NAME }),
+    );
+
+    const relay = await startAuthRelay();
+    let handle: RemoteControlHandle | undefined;
+    cleanups.push(async () => handle?.close());
+    handle = await startRemoteControl({
+      homeDir,
+      localOrigin: 'http://127.0.0.1:1',
+      localServerToken: 'local-server-token',
+      relayOrigin: `http://127.0.0.1:${relay.port}/coding-relay`,
+      stderr: { write: () => true },
+    });
+
+    expect(
+      relay.requests.some(
+        (request) =>
+          request.authorization === 'Bearer refresh-token' ||
+          request.protocol === 'kimi-code.bearer.refresh-token',
+      ),
+    ).toBe(true);
+  });
+
   it('surfaces register_nak details', async () => {
     const homeDir = mkdtempSync(join(tmpdir(), 'kimi-rc-nak-'));
     cleanups.push(() => rmSync(homeDir, { recursive: true, force: true }));