ContextQMD
Back to Codexbar

Keychain prompts

docs/keychain-prompts.md

0.52.05.6 KB
Original Source

Keychain prompts

CodexBar uses several credential sources, but two foreign-owned Keychain items are the common authorization surfaces:

  • Chromium cookie import needs the browser's Safe Storage secret to decrypt its cookie database. Examples include Chrome Safe Storage, Brave Safe Storage, and Microsoft Edge Safe Storage.
  • Claude OAuth repair can read Claude Code's Claude Code-credentials item. Direct access to that foreign item is off by default and requires explicit consent in Claude's provider settings. The default prompt policy reserves interactive repair for a user action.

CodexBar does not need the browser or Claude account password. macOS owns the authorization prompt and should name the requesting app or binary. Never send a Keychain item value, cookie header, OAuth token, API key, or password in a support report.

When CodexBar can prompt

Background CodexBar paths are intended to fail or skip when a Keychain read would require interaction. This includes scheduled Chromium imports: CodexBar scopes the actual Safe Storage read as non-interactive, not just the preflight. A user-initiated import or acknowledged Claude repair may attempt interactive authorization because the user has chosen to continue. Denials temporarily suppress repeated Chromium-family attempts so one browser cannot lead to a prompt storm across the others.

Provider-owned child processes are a separate boundary. CodexBar may intentionally launch a provider CLI such as Claude for usage. That executable owns its credential behavior, which CodexBar cannot constrain or fully inspect.

Why permission can be requested again

Keychain access control evaluates the requesting executable's code signature and designated requirement, not just its filename or install path. A stable, properly signed CodexBar bundle makes grants more durable, while ad-hoc development builds or a materially changed identity may need authorization again. The Keychain item's owner can also recreate or rotate a foreign item. Chromium or Claude Code updates can therefore replace the previous access-control entry even when CodexBar itself has not changed.

The item's accessibility class controls when its data is available, such as after the first unlock. It does not grant a changed executable access and does not repair a code-signature ACL mismatch.

Allow Once and Always Allow

  • Allow Once authorizes the current request or session. A later explicit import or repair may ask again.
  • Always Allow adds the current CodexBar identity to that item's access control and is the better choice when you intentionally use automatic browser import or Claude's direct Keychain repair.
  • Deny leaves the source unavailable. CodexBar should fail soft and use another configured source where possible.

Only authorize a prompt whose requested item and requesting app match the action you just started. Avoid “Allow all applications.” In Keychain Access, adding only the installed, stably signed CodexBar.app is the narrower grant.

Disable CodexBar Keychain access

Open CodexBar → Settings → Advanced and enable Disable Keychain access. The stored setting is applied immediately; relaunching is useful when diagnosing another already-running copy.

This setting blocks CodexBar-owned Security.framework item reads and writes, including foreign-item readers such as Zed, and disables Chromium Safe Storage decryption. Browser-cookie import that needs Keychain is skipped. It does not promise that a provider-owned CLI launched by CodexBar will avoid its own credential store; Claude's owner-CLI policy is intentionally unchanged.

Alternatives depend on the provider:

  • Paste a Cookie header manually instead of importing it from a browser.
  • Configure an API key or OAuth/device flow that does not depend on browser Safe Storage.
  • Use a supported file-backed or local provider source.
  • For Claude, leave direct foreign-item consent off and choose a CLI, Web, or usable credentials-file path.

Safe troubleshooting

If a prompt appears unexpectedly, first read the full item name and requesting app/path. Quit CodexBar, then check for another running or installed copy:

bash
pgrep -fl 'CodexBar|CodexBarCLI'
ls -ld /Applications/CodexBar.app
brew info --cask codexbar
mdfind 'kMDItemCFBundleIdentifier == "com.steipete.codexbar"'

Also inspect Activity Monitor and System Settings → General → Login Items. Deleting an app does not terminate an already-running process, and another copy may have launched from a different path. Do not use command-line tools to dump Keychain contents while troubleshooting.

For a support report, include:

  • CodexBar and macOS versions, installation source, and whether this is a development build.
  • The provider action immediately before the prompt and whether it was automatic or explicitly initiated.
  • The requested item name and requesting app/path from the prompt.
  • Whether Activity Monitor, Login Items, Homebrew, or Spotlight found another CodexBar copy.
  • A screenshot of only the prompt, with usernames and unrelated content redacted and no secret values shown.

Authoritative references