refactor: migrate to @napi-rs/keyring and env-paths

.env.example

@@ -8,7 +8,7 @@
 # CLERK_PLATFORM_API_URL=https://api.clerk.com
 
 # ── Config / credentials storage ─────────────────────────────────────────────
-# CLERK_CONFIG_DIR=~/.clerk
+# CLERK_CONFIG_DIR=/path/to/custom/dir
 
 # ── Auth callback ────────────────────────────────────────────────────────────
 # CLERK_AUTH_TIMEOUT_MS=120000

package.json

@@ -7,7 +7,7 @@
   },
   "type": "module",
   "scripts": {
-    "build": "bun build ./src/cli.ts --outfile ./dist/cli.js --target node",
+    "build": "bun build ./src/cli.ts --outfile ./dist/cli.js --target node --external @napi-rs/keyring",
     "dev": "bun run ./src/cli.ts",
     "test": "bun test",
     "lint": "oxlint src/",
@@ -17,7 +17,9 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.2.0",
+    "@napi-rs/keyring": "^1.2.0",
     "commander": "^14.0.3",
+    "env-paths": "^4.0.0",
     "yaml": "^2.8.2"
   },
   "devDependencies": {

src/lib/config.ts

@@ -1,5 +1,5 @@
 /**
- * Config file management for ~/.clerk/config.json.
+ * Config file management for the Clerk CLI config file.
  * Stores auth identity and path-keyed project profiles.
  */
 

src/lib/constants.ts

@@ -3,14 +3,16 @@
  * Centralizes configuration values that are used across multiple modules.
  */
 
-import { homedir } from "node:os";
 import { join } from "node:path";
+import envPaths from "env-paths";
 
 // ── File paths ──────────────────────────────────────────────────────────────
 
-export const CLERK_HOME_DIR = process.env.CLERK_CONFIG_DIR ?? join(homedir(), ".clerk");
-export const CONFIG_FILE = join(CLERK_HOME_DIR, "config.json");
-export const CREDENTIALS_FILE = join(CLERK_HOME_DIR, "credentials");
+const clerkConfigDir = process.env.CLERK_CONFIG_DIR;
+const paths = envPaths("clerk-cli", { suffix: false });
+
+export const CONFIG_FILE = join(clerkConfigDir ?? paths.config, "config.json");
+export const CREDENTIALS_FILE = join(clerkConfigDir ?? paths.data, "credentials");
 
 // ── OAuth ───────────────────────────────────────────────────────────────────
 
@@ -46,10 +48,5 @@ export const OPENAPI_SPEC_URLS = {
 
 // ── Cache ────────────────────────────────────────────────────────────────
 
-export const CLERK_CACHE_DIR = join(CLERK_HOME_DIR, "cache");
+export const CLERK_CACHE_DIR = clerkConfigDir ? join(clerkConfigDir, "cache") : paths.cache;
 export const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
-
-// ── Keychain ────────────────────────────────────────────────────────────────
-
-export const KEYCHAIN_SERVICE = "clerk-cli";
-export const KEYCHAIN_ACCOUNT = "oauth-access-token";

src/lib/credential-store.test.ts

@@ -1,5 +1,8 @@
-import { test, expect, describe, beforeEach, afterAll, mock } from "bun:test";
-import { mkdtemp, rm, mkdir, chmod } from "node:fs/promises";
+import { test, expect, describe, beforeEach, afterAll, mock, setDefaultTimeout } from "bun:test";
+
+// Keyring initialization can be slow on first access (macOS Keychain, etc.)
+setDefaultTimeout(5_000);
+import { mkdtemp, rm, mkdir, chmod, unlink } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -8,18 +11,26 @@ const tempDir = await mkdtemp(join(tmpdir(), "clerk-cred-test-"));
 // Redirect file-based credential storage to temp dir via env var
 process.env.CLERK_CONFIG_DIR = tempDir;
 
-// Re-register real credential-store to override any stale mocks from other test files
-const isMacOS = process.platform === "darwin";
-const KEYCHAIN_SERVICE = "clerk-cli";
-const KEYCHAIN_ACCOUNT = "oauth-access-token";
+// Import constants from the source module to avoid duplication
+const { KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT } = await import("./credential-store.ts");
 const credFile = () =>
   join(process.env.CLERK_CONFIG_DIR ?? join(require("os").homedir(), ".clerk"), "credentials");
 
+let keyringModule: typeof import("@napi-rs/keyring") | null;
+try {
+  keyringModule = await import("@napi-rs/keyring");
+} catch {
+  keyringModule = null;
+}
+
 mock.module("./credential-store.ts", () => ({
+  KEYCHAIN_SERVICE,
+  KEYCHAIN_ACCOUNT,
   async storeToken(token: string) {
-    if (isMacOS) {
+    if (keyringModule) {
       try {
-        await Bun.$`security add-generic-password -a ${KEYCHAIN_ACCOUNT} -s ${KEYCHAIN_SERVICE} -w ${token} -U`.quiet();
+        const entry = new keyringModule.Entry(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+        entry.setPassword(token);
         return;
       } catch {}
     }
@@ -29,13 +40,10 @@ mock.module("./credential-store.ts", () => ({
     await chmod(f, 0o600);
   },
   async getToken() {
-    if (isMacOS) {
+    if (keyringModule) {
       try {
-        return (
-          await Bun.$`security find-generic-password -a ${KEYCHAIN_ACCOUNT} -s ${KEYCHAIN_SERVICE} -w`.quiet()
-        )
-          .text()
-          .trim();
+        const entry = new keyringModule.Entry(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+        return entry.getPassword();
       } catch {}
     }
     const file = Bun.file(credFile());
@@ -44,13 +52,17 @@ mock.module("./credential-store.ts", () => ({
     return content.trim() || null;
   },
   async deleteToken() {
-    if (isMacOS) {
+    if (keyringModule) {
       try {
-        await Bun.$`security delete-generic-password -a ${KEYCHAIN_ACCOUNT} -s ${KEYCHAIN_SERVICE}`.quiet();
+        const entry = new keyringModule.Entry(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+        entry.deletePassword();
       } catch {}
     }
-    const file = Bun.file(credFile());
-    if (await file.exists()) await Bun.write(credFile(), "");
+    try {
+      await unlink(credFile());
+    } catch {
+      // File doesn't exist, nothing to delete
+    }
   },
 }));
 
@@ -59,8 +71,8 @@ const { storeToken, getToken, deleteToken } = await import("./credential-store.t
 let savedToken: string | null = null;
 
 afterAll(async () => {
-  // Restore any pre-existing keychain token on macOS
-  if (process.platform === "darwin" && savedToken !== null) {
+  // Restore any pre-existing keyring token
+  if (keyringModule && savedToken !== null) {
     await storeToken(savedToken);
   }
   delete process.env.CLERK_CONFIG_DIR;
@@ -69,8 +81,8 @@ afterAll(async () => {
 
 describe("credential-store", () => {
   beforeEach(async () => {
-    // On first run, save any existing keychain token so we can restore it later
-    if (process.platform === "darwin" && savedToken === null) {
+    // On first run, save any existing keyring token so we can restore it later
+    if (keyringModule && savedToken === null) {
       savedToken = await getToken();
     }
     await deleteToken();

src/lib/credential-store.ts

@@ -1,40 +1,57 @@
 /**
  * Credential store for persisting the OAuth access token.
- * Uses macOS Keychain as primary, falls back to a plaintext file with chmod 600.
+ * Uses platform keyring as primary (via @napi-rs/keyring), falls back to a plaintext file with chmod 600.
  */
 
 import { dirname } from "node:path";
-import { mkdir, chmod } from "node:fs/promises";
-import { CREDENTIALS_FILE, KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT } from "./constants.ts";
+import { mkdir, chmod, unlink } from "node:fs/promises";
+import { CREDENTIALS_FILE } from "./constants.ts";
 
-const isMacOS = process.platform === "darwin";
+export const KEYCHAIN_SERVICE = "clerk-cli";
+export const KEYCHAIN_ACCOUNT = "oauth-access-token";
 
-async function keychainStore(token: string): Promise<boolean> {
-  if (!isMacOS) return false;
+let keyringModule: typeof import("@napi-rs/keyring") | null | undefined;
+
+async function getKeyring(): Promise<typeof import("@napi-rs/keyring") | null> {
+  if (keyringModule !== undefined) return keyringModule;
   try {
-    // -U flag updates existing entry if present
-    await Bun.$`security add-generic-password -a ${KEYCHAIN_ACCOUNT} -s ${KEYCHAIN_SERVICE} -w ${token} -U`.quiet();
+    keyringModule = await import("@napi-rs/keyring");
+    return keyringModule;
+  } catch {
+    keyringModule = null;
+    return null;
+  }
+}
+
+async function keyringStore(token: string): Promise<boolean> {
+  const mod = await getKeyring();
+  if (!mod) return false;
+  try {
+    const entry = new mod.Entry(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+    entry.setPassword(token);
     return true;
   } catch {
     return false;
   }
 }
 
-async function keychainGet(): Promise<string | null> {
-  if (!isMacOS) return null;
+async function keyringGet(): Promise<string | null> {
+  const mod = await getKeyring();
+  if (!mod) return null;
   try {
-    const result =
-      await Bun.$`security find-generic-password -a ${KEYCHAIN_ACCOUNT} -s ${KEYCHAIN_SERVICE} -w`.quiet();
-    return result.text().trim();
+    const entry = new mod.Entry(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+    return entry.getPassword();
   } catch {
     return null;
   }
 }
 
-async function keychainDelete(): Promise<boolean> {
-  if (!isMacOS) return false;
+async function keyringDelete(): Promise<boolean> {
+  const mod = await getKeyring();
+  if (!mod) return false;
   try {
-    await Bun.$`security delete-generic-password -a ${KEYCHAIN_ACCOUNT} -s ${KEYCHAIN_SERVICE}`.quiet();
+    const entry = new mod.Entry(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+    entry.deletePassword();
     return true;
   } catch {
     return false;
@@ -55,17 +72,22 @@ async function fileGet(): Promise<string | null> {
 }
 
 async function fileDelete(): Promise<void> {
-  const file = Bun.file(CREDENTIALS_FILE);
-  if (await file.exists()) {
-    await Bun.write(CREDENTIALS_FILE, "");
+  try {
+    await unlink(CREDENTIALS_FILE);
+  } catch {
+    // File doesn't exist, nothing to delete
   }
 }
 
 export async function storeToken(token: string): Promise<void> {
-  const stored = await keychainStore(token);
-  if (!stored) {
-    await fileStore(token);
+  const stored = await keyringStore(token);
+  if (stored) {
+    // Clean up any stale plaintext credentials from a previous file-based storage
+    await fileDelete();
+    return;
   }
+
+  await fileStore(token);
 }
 
 let tokenOverride: string | null | undefined;
@@ -77,12 +99,12 @@ export function _setTokenOverride(value: string | null | undefined): void {
 
 export async function getToken(): Promise<string | null> {
   if (tokenOverride !== undefined) return tokenOverride;
-  const token = await keychainGet();
+  const token = await keyringGet();
   if (token) return token;
   return fileGet();
 }
 
 export async function deleteToken(): Promise<void> {
-  await keychainDelete();
+  await keyringDelete();
   await fileDelete();
 }