feat(ocm-cli): add file and keychain credential backends with auth commands (#327)

* feat(ocm-cli): add file and keychain credential backends with auth commands

* feat(ocm-cli): refactor credentials into async TokenStore architecture

Replace the credential-backend module with a TokenStore interface and
file/keychain implementations behind an internal facade. Convert token
get/set/delete to async, add env-token precedence warnings on login and
logout, and surface store availability in status. Add token-store tests
and helpers; remove the old credential modules and tests. Bump to 0.2.6.

* fix(ocm-cli): keep tokens out of security argv and stop masking config read errors

Route every macOS Keychain call through `security -i`, sending the quoted
command on stdin so the token is never visible in process arguments. Reject
arguments containing line breaks, which would otherwise inject additional
security commands.

Let unexpected state file read failures propagate so a broken config dir is
reported instead of being reduced to "no manager configured", and stop
consuming the install notice when reading it fails unexpectedly.

---------

Co-authored-by: CS <chris@chriswritescode.dev>

Author: chriswritescode-dev

docs/ocm-cli.md

@@ -76,7 +76,9 @@ ocm login https://your-manager-url
 # paste your Manager internal token when prompted
 ```
 
-The token is stored in the macOS Keychain under the manager URL. The manager URL is persisted to `~/.config/opencode-manager/state.json`.
+The token is stored in a platform-specific token store: the macOS Keychain (service `opencode-manager`, account = manager URL) on macOS, or `~/.config/opencode-manager/credentials.json` at mode `0600` on Linux. On Linux the token is plaintext JSON protected only by file permissions. Run `ocm status` to see the active store. The manager URL itself is persisted to `~/.config/opencode-manager/state.json`.
+
+Windows is not supported: the CLI falls back to the same file store, but the `0600` mode is not enforced there and hidden token entry requires `bash`.
 
 Generate or rotate your internal token from **Settings → Manager Token** in the Manager web UI (Settings cog in the sidebar, then **Manager Token**).
 
@@ -88,7 +90,7 @@ Generate or rotate your internal token from **Settings → Manager Token** in th
 ocm                       Attach to the Manager repo matching $PWD's git origin,
                           or fall back to the last selected repo
 ocm login <url> [token]   Save manager URL + token (token via stdin if omitted)
-ocm logout                Forget saved token (Keychain) and state
+ocm logout                Forget saved token and state
 ocm status                Show current manager URL, repo, and whether token is set
 ocm list                  List ready repos from the manager
 ocm use <repoId|name>     Attach to a specific repo and remember it as last
@@ -141,14 +143,15 @@ When the TUI plugin entry is installed, `/ocm-move` is available in local OpenCo
 
 ## 4. Environment variables
 
-Both can be used in place of `ocm login`:
+The CLI's environment and token inputs:
 
 | Variable | Description |
 |---|---|
 | `OPENCODE_MANAGER_URL` | Manager base URL (e.g., `https://manager.example.com`). Not currently consumed by the CLI — use `ocm login`. |
 | `OCM_REMOTE_MANAGER_URL` | Internal child-process context set by `ocm attach`; controls the remote TUI indicator. Not a login setting. |
 | `OCM_REMOTE_REPO_NAME` | Internal child-process context set by `ocm attach`; labels the remote TUI indicator. Not a login setting. |
-| Keychain entry under `https://manager.example.com` | Token used for Bearer auth on Manager API calls and Basic auth on the OpenCode proxy. |
+| `OCM_TOKEN` | Read-only override for the stored token; takes priority over the platform token store. `ocm login` never writes it, and `ocm logout` cannot remove it. Because the manager URL still comes from `state.json`, CI must run `ocm login` first, so this override does not yet avoid writing a token to disk. |
+| Token store entry under `<manager url>` | Token used for Bearer auth on Manager API calls and Basic auth on the OpenCode proxy. macOS Keychain (service `opencode-manager`) or `~/.config/opencode-manager/credentials.json` (mode `0600`) on Linux. |
 
 ---
 

ocm-cli/README.md

@@ -22,10 +22,24 @@ also create a best-effort `~/.local/bin/ocm` symlink.
 ocm login <manager-url> [token]
 ```
 
-The token is stored in macOS Keychain under the `opencode-manager` service. CLI
-state is stored at `~/.config/opencode-manager/state.json`.
+The token is stored in a platform-specific token store:
 
-If `[token]` is omitted, `ocm login` reads it from hidden TTY input or stdin.
+| Platform | Store |
+|---|---|
+| macOS | Keychain, service `opencode-manager`, account = manager URL |
+| Linux | `~/.config/opencode-manager/credentials.json`, mode `0600` |
+
+On Linux the token is stored as plaintext JSON protected only by file
+permissions. CLI state is stored at `~/.config/opencode-manager/state.json`.
+Windows is unsupported: the same file store is used, but the `0600` mode is not
+enforced there.
+
+`OCM_TOKEN` overrides the token store for reads; `ocm login` always writes to
+the platform store and `ocm logout` cannot remove the override. Run `ocm status`
+to see the active store.
+
+If `[token]` is omitted, `ocm login` reads it from hidden TTY input (requires
+`bash`) or stdin.
 
 ## Commands
 
@@ -92,7 +106,9 @@ global installs); the plugin surface is TUI-only.
 
 ## Requirements
 
+- macOS or Linux (Windows is unsupported)
 - `opencode` available on `PATH`
 - `git` and `tar` (with gzip support, i.e. the `-z` flag) available on `PATH`
-- macOS `security` CLI for Keychain-backed token storage
+- `bash`, used for hidden token entry and interactive confirmations
+- macOS only: `/usr/bin/security`, used for Keychain-backed token storage (Linux uses a mode-`0600` file under the user config dir `~/.config/opencode-manager`)
 - An OpenCode Manager URL and bearer token

ocm-cli/bin/ocm.ts

@@ -1,7 +1,7 @@
 import { spawn, spawnSync } from 'child_process'
 import { basename } from 'path'
 import { readState, writeState, clearState, getStatePath, type OcmState } from '../src/state.js'
-import { getToken, setToken, deleteToken, KeychainError } from '../src/keychain.js'
+import { getToken, setToken, deleteToken, hasStoredToken, describeTokenStore, describeTokenWriteTarget, envToken, TOKEN_ENV, TokenStoreError } from '../src/internal-token-store.js'
 import { ManagerApi, ManagerApiError } from '../src/manager-api.js'
 import { mirrorUp, mirrorDown, mirrorUpFast, mirrorDownFast, prepareMirror, MirrorAbort, checkPushDivergence, checkPullDivergence } from '../src/mirror.js'
 import type { RemoteRepoSummary, MirrorProgress, PushDivergence, PullDivergence } from '../src/mirror.js'
@@ -22,7 +22,7 @@ Usage:
                             fall back to the last selected repo, or launch local
                             opencode when no Manager target applies
   ocm login <url> [token]   Save manager URL + token (token via stdin if omitted)
-  ocm logout                Forget saved token (Keychain) and state
+  ocm logout                Forget saved token and state
   ocm status                Show current manager URL, repo, and whether token is set
   ocm list                  List ready repos from the manager
   ocm use <repoId|name>     Attach to a specific repo and remember it as last
@@ -108,10 +108,17 @@ function requireState(): OcmState {
   return state
 }
 
-function requireToken(state: OcmState): string {
-  const token = getToken(state.managerUrl)
+async function requireToken(state: OcmState): Promise<string> {
+  const store = describeTokenStore()
+  let token: string | null
+  try {
+    token = await getToken(state.managerUrl)
+  } catch (err) {
+    if (!(err instanceof TokenStoreError)) throw err
+    die(`token store error (${store.kind}: ${store.location}): ${err.message}. Run \`ocm login ${state.managerUrl}\` after fixing the store.`)
+  }
   if (!token) {
-    die(`no token in Keychain for ${state.managerUrl}. Run \`ocm login ${state.managerUrl}\`.`)
+    die(`no token stored for ${state.managerUrl} (${store.kind}: ${store.location}). Run \`ocm login ${state.managerUrl}\`.`)
   }
   return token
 }
@@ -164,7 +171,7 @@ function findRepo(repos: ManagerRepo[], needle: string | number): ManagerRepo |
   return repos.find((r) => r.name === needle) ?? repos.find((r) => r.name.toLowerCase() === needle.toLowerCase())
 }
 
-async function cmdLogin(args: string[]): Promise<void> {
+export async function cmdLogin(args: string[]): Promise<void> {
   const url = args[0]
   if (!url) die('usage: ocm login <url> [token]')
   const normalisedUrl = url.replace(/\/+$/, '')
@@ -190,9 +197,9 @@ async function cmdLogin(args: string[]): Promise<void> {
   if (!token) die('no token provided')
 
   try {
-    setToken(normalisedUrl, token)
+    await setToken(normalisedUrl, token)
   } catch (err) {
-    if (err instanceof KeychainError) die(`Keychain error: ${err.message}`)
+    if (err instanceof TokenStoreError) die(`token store error: ${err.message}`)
     throw err
   }
 
@@ -202,32 +209,65 @@ async function cmdLogin(args: string[]): Promise<void> {
     managerUrl: normalisedUrl,
   })
 
-  info(`Saved token for ${normalisedUrl} in Keychain.`)
+  const store = describeTokenWriteTarget()
+  info(`Saved token for ${normalisedUrl} (${store.kind}: ${store.location}).`)
   info(`State file: ${getStatePath()}`)
+  warnEnvTokenPrecedence()
 }
 
-async function cmdLogout(): Promise<void> {
+export async function cmdLogout(): Promise<void> {
   const state = readState()
   if (!state || !state.managerUrl) {
     info('Nothing to log out from.')
     return
   }
-  const deleted = deleteToken(state.managerUrl)
+  let deleted = false
+  let storeError: TokenStoreError | undefined
+  try {
+    deleted = await deleteToken(state.managerUrl)
+  } catch (err) {
+    if (!(err instanceof TokenStoreError)) throw err
+    storeError = err
+  }
   clearState()
-  info(deleted ? `Removed Keychain entry for ${state.managerUrl}.` : `No Keychain entry found.`)
+  if (storeError) {
+    info('State cleared.')
+    die(`token store error: ${storeError.message}. The stored token may still exist.`)
+  }
+  info(deleted ? `Removed stored token for ${state.managerUrl}.` : 'No stored token found.')
   info('State cleared.')
+  warnEnvTokenPrecedence()
+}
+
+function warnEnvTokenPrecedence(): void {
+  if (envToken()) {
+    info(`note: ${TOKEN_ENV} is set and takes precedence over the stored token; unset it to use the token store.`)
+  }
+}
+
+async function describeTokenPresence(account: string | undefined): Promise<string> {
+  try {
+    return (await hasStoredToken(account)) ? 'yes' : 'no'
+  } catch (err) {
+    if (!(err instanceof TokenStoreError)) throw err
+    return `unavailable (${err.message})`
+  }
 }
 
-async function cmdStatus(): Promise<void> {
+export async function cmdStatus(): Promise<void> {
+  const store = describeTokenStore()
   const state = readState()
   if (!state) {
     info(`version:      ${VERSION}`)
+    info(`token store:  ${store.kind} (${store.location})`)
+    info(`token:        ${await describeTokenPresence(undefined)}`)
     info('no state. run: ocm login <url>')
     return
   }
   info(`version:      ${VERSION}`)
   info(`manager url:  ${state.managerUrl}`)
-  info(`token in kc:  ${getToken(state.managerUrl) ? 'yes' : 'no'}`)
+  info(`token:        ${await describeTokenPresence(state.managerUrl)}`)
+  info(`token store:  ${store.kind} (${store.location})`)
   if (state.lastRepoId !== undefined) {
     info(`last repo:    ${state.lastRepoName} (id=${state.lastRepoId}, branch=${state.lastRepoBranch ?? 'n/a'})`)
     info(`last repo dir: ${state.lastRepoDir}`)
@@ -239,7 +279,7 @@ async function cmdStatus(): Promise<void> {
 
 async function cmdList(): Promise<void> {
   const state = requireState()
-  const token = requireToken(state)
+  const token = await requireToken(state)
   const repos = await fetchRepos(state.managerUrl, token)
   if (repos.length === 0) {
     info('No ready repos.')
@@ -259,7 +299,7 @@ async function cmdUse(args: string[]): Promise<void> {
   const needle = args[0]
   if (!needle) die('usage: ocm use <repoId|name>')
   const state = requireState()
-  const token = requireToken(state)
+  const token = await requireToken(state)
   const repos = await fetchRepos(state.managerUrl, token)
   const repo = findRepo(repos, needle)
   if (!repo) die(`repo not found: ${needle}`)
@@ -278,7 +318,7 @@ async function cmdUse(args: string[]): Promise<void> {
 async function cmdDefault(): Promise<void> {
   info(`ocm v${VERSION}`)
   const state = requireState()
-  const token = requireToken(state)
+  const token = await requireToken(state)
 
   const last = state.lastRepoId !== undefined && state.lastRepoDir
     ? {
@@ -361,7 +401,7 @@ export async function cmdPush(args: string[]): Promise<void> {
   }
 
   const state = requireState()
-  const token = requireToken(state)
+  const token = await requireToken(state)
   const api = new ManagerApi(state.managerUrl, token)
   const repos = await fetchRepos(state.managerUrl, token)
 
@@ -439,7 +479,7 @@ async function cmdPull(args: string[]): Promise<void> {
   }
 
   const state = requireState()
-  const token = requireToken(state)
+  const token = await requireToken(state)
   const api = new ManagerApi(state.managerUrl, token)
   const repos = await fetchRepos(state.managerUrl, token)
 

ocm-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-manager/ocm-cli",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "OpenCode Manager CLI: attach a local OpenCode TUI to a Manager-hosted repo.",
   "license": "MIT",
   "repository": {

ocm-cli/src/internal-token-store.ts

@@ -0,0 +1,94 @@
+import type { TokenStore, TokenStoreDescription } from './token-store.js'
+import { TokenStoreError } from './token-store.js'
+import { createFileTokenStore } from './token-store-file.js'
+import { createKeychainTokenStore } from './token-store-keychain.js'
+
+export const TOKEN_ENV = 'OCM_TOKEN'
+
+export function selectTokenStore(platform: NodeJS.Platform = process.platform): TokenStore {
+  return platform === 'darwin'
+    ? createKeychainTokenStore()
+    : createFileTokenStore()
+}
+
+function memoizeReads(store: TokenStore): TokenStore {
+  const cache = new Map<string, string>()
+  return {
+    describe: () => store.describe(),
+    async get(account: string): Promise<string | null> {
+      const cached = cache.get(account)
+      if (cached) return cached
+      const token = await store.get(account)
+      if (token) cache.set(account, token)
+      return token
+    },
+    async set(account: string, token: string): Promise<void> {
+      await store.set(account, token)
+      cache.set(account, token)
+    },
+    async delete(account: string): Promise<boolean> {
+      cache.delete(account)
+      return store.delete(account)
+    },
+  }
+}
+
+let active: TokenStore | undefined
+function defaultStore(): TokenStore {
+  active ??= memoizeReads(selectTokenStore())
+  return active
+}
+
+export function envToken(): string | null {
+  const raw = process.env[TOKEN_ENV]?.trim()
+  return raw ? raw : null
+}
+
+export async function getToken(
+  account: string,
+  store: TokenStore = defaultStore(),
+): Promise<string | null> {
+  return envToken() ?? (await store.get(account))
+}
+
+export async function setToken(
+  account: string,
+  token: string,
+  store: TokenStore = defaultStore(),
+): Promise<void> {
+  const normalised = token.trim()
+  if (!normalised) {
+    throw new TokenStoreError('refusing to store an empty token', store.describe().kind)
+  }
+  await store.set(account, normalised)
+}
+
+export async function deleteToken(
+  account: string,
+  store: TokenStore = defaultStore(),
+): Promise<boolean> {
+  return store.delete(account)
+}
+
+export async function hasStoredToken(
+  account: string | undefined,
+  store: TokenStore = defaultStore(),
+): Promise<boolean> {
+  if (envToken()) return true
+  if (!account) return false
+  return (await store.get(account)) !== null
+}
+
+export function describeTokenStore(
+  store: TokenStore = defaultStore(),
+): TokenStoreDescription {
+  return envToken() ? { kind: 'env', location: TOKEN_ENV } : store.describe()
+}
+
+export function describeTokenWriteTarget(
+  store: TokenStore = defaultStore(),
+): TokenStoreDescription {
+  return store.describe()
+}
+
+export { TokenStoreError } from './token-store.js'