<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-04-19-1-cli-auth-uses-encrypted-file-only-session-storage/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-19-1-cli-auth-uses-encrypted-file-only-session-storage/</id>
  <title>CLI Auth Uses Browser-Mediated OAuth With Encrypted File-Only Session Storage</title>
  <updated>2026-04-19T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-04-19-1-cli-auth-uses-encrypted-file-only-session-storage/"/>
  <summary>Keeps browser-mediated OAuth but drops OS keyring persistence: CLI sessions live in an encrypted file, giving one cross-platform recovery and test surface.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The April 9 auth ADR made the correct high-level product call and the wrong
local persistence call.&lt;/p&gt;
&lt;p&gt;The correct parts remain true:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;human CLI auth must use the SaaS browser identity surface, not password
prompts in the terminal,&lt;/li&gt;
&lt;li&gt;the CLI must use a centralized token manager,&lt;/li&gt;
&lt;li&gt;long-running sync, tracker, transport, and websocket paths must share one
renewable session model.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The part we are reversing is local session persistence. The prior ADR chose
OS-backed secret stores where available:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;macOS Keychain&lt;/li&gt;
&lt;li&gt;Windows Credential Manager&lt;/li&gt;
&lt;li&gt;Linux Secret Service / GNOME Keyring / KWallet&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;That storage direction proved to be the wrong product fit for Spec Kitty:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;on macOS the requesting identity is often an unstable Python process rather
than a stable signed app, causing repeated friction and trust prompts,&lt;/li&gt;
&lt;li&gt;background sync, websocket startup, and other non-interactive runtime paths
can touch auth storage outside an explicit &lt;code dir=&quot;auto&quot;&gt;auth login&lt;/code&gt; moment,&lt;/li&gt;
&lt;li&gt;Linux and Windows users should not need desktop credential infrastructure
for a normal CLI session model,&lt;/li&gt;
&lt;li&gt;multiple backend paths create more test matrix, more support surface, and
more ambiguous recovery instructions.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The team also confirmed there is no compatibility burden worth preserving here:
the new browser-auth rollout has had zero user adoption, so we do not need to
migrate or preserve keychain-backed local state. Developers can re-authenticate.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Keep the browser-auth product model&lt;/strong&gt; — the CLI continues to authenticate
through the SaaS, not by collecting passwords locally.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One durable local storage model on every OS&lt;/strong&gt; — macOS, Linux, and Windows
should all persist sessions the same way.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No dependency on desktop credential infrastructure&lt;/strong&gt; — runtime auth must
work in terminals, SSH, CI-like shells, and long-lived background flows
without keychain/credential-manager integration.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Centralized token management remains mandatory&lt;/strong&gt; — callers still do not
read raw tokens directly.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No backend-selection knob&lt;/strong&gt; — storage mode is a product decision, not a
runtime preference.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No migration layer&lt;/strong&gt; — stale local auth state may be discarded.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cross-platform predictability&lt;/strong&gt; — Linux and Windows are first-class targets,
not macOS exceptions.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1:&lt;/strong&gt; Keep browser-mediated OAuth but continue OS-keychain-first local storage&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Keep browser-mediated OAuth and move all persisted session storage to one encrypted file-backed store (chosen)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Keep browser-mediated OAuth but store tokens in plaintext local files&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Introduce a signed native helper/app solely to stabilize keychain identity&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: Option 2&lt;/strong&gt;, because it preserves the correct browser-auth and
token-manager architecture while removing the wrong dependency on OS secret
stores. It gives the CLI one recovery model, one testable persistence surface,
and one cross-platform behavior profile.&lt;/p&gt;
&lt;h3 id=&quot;core-decision&quot;&gt;Core Decision&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;Human CLI authentication to &lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas&lt;/code&gt; MUST continue to use
browser-mediated OAuth/OIDC, not username/password entry in the CLI.&lt;/li&gt;
&lt;li&gt;The default interactive flow remains Authorization Code + PKCE via a local
loopback callback.&lt;/li&gt;
&lt;li&gt;The headless fallback remains Device Authorization Flow.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; MUST continue to centralize access-token acquisition, refresh,
retry, and invalidation behind one token manager. Callers MUST NOT read raw
access tokens directly from storage.&lt;/li&gt;
&lt;li&gt;Persisted CLI session material MUST be stored only in an encrypted local
file-backed store rooted at &lt;code dir=&quot;auto&quot;&gt;Path.home() / &quot;.spec-kitty&quot; / &quot;auth&quot;&lt;/code&gt; on all
supported platforms.&lt;/li&gt;
&lt;li&gt;The canonical persisted files are:
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty/auth/session.json&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty/auth/session.salt&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty/auth/session.lock&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;OS secret stores are not supported runtime backends for CLI auth:
&lt;ul&gt;
&lt;li&gt;no macOS Keychain&lt;/li&gt;
&lt;li&gt;no Windows Credential Manager&lt;/li&gt;
&lt;li&gt;no Linux Secret Service / GNOME Keyring / KWallet&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;The encrypted file format continues to use AES-256-GCM with a scrypt-derived
key and a random per-store salt.&lt;/li&gt;
&lt;li&gt;The scrypt passphrase remains bound to &lt;code dir=&quot;auto&quot;&gt;f&quot;{hostname}:{uid}&quot;&lt;/code&gt;; on platforms
without &lt;code dir=&quot;auto&quot;&gt;os.getuid()&lt;/code&gt; support, the UID component resolves to &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;There is no backend-selection flag, env var, or config option.&lt;/li&gt;
&lt;li&gt;There is no migration layer for pre-cutover keychain-backed state. Recovery
guidance is to run &lt;code dir=&quot;auto&quot;&gt;spec-kitty auth login --force&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;User-facing status surfaces MUST present this as the canonical encrypted
session file backend, not as a fallback or degraded mode.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Browser auth remains the sole human login surface.&lt;/li&gt;
&lt;li&gt;Password handling remains out of the CLI.&lt;/li&gt;
&lt;li&gt;All supported platforms use the same persistence behavior.&lt;/li&gt;
&lt;li&gt;Runtime and background paths no longer depend on OS credential daemons.&lt;/li&gt;
&lt;li&gt;Support and troubleshooting simplify to one local-state model.&lt;/li&gt;
&lt;li&gt;Test coverage can focus on one persistence mechanism instead of a backend
matrix.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The CLI no longer benefits from OS-native secret-store UX where those stores
are well-behaved.&lt;/li&gt;
&lt;li&gt;File-permission enforcement differs by platform; Windows cannot rely on the
same POSIX-mode checks used on Unix.&lt;/li&gt;
&lt;li&gt;Existing mission-080 docs/tests that described keychain-backed behavior must
be rewritten or removed.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;This does not change the SaaS OAuth contract.&lt;/li&gt;
&lt;li&gt;This does not introduce a machine/service-account auth model.&lt;/li&gt;
&lt;li&gt;Host-owned persistence remains the rule; only the storage substrate changes.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h2&gt;
&lt;p&gt;This decision is validated when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty auth login&lt;/code&gt; persists only to &lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty/auth/...&lt;/code&gt;,&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty auth status&lt;/code&gt; reports the encrypted session-file backend,&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; no longer depends on &lt;code dir=&quot;auto&quot;&gt;keyring&lt;/code&gt;,&lt;/li&gt;
&lt;li&gt;runtime, sync, tracker, transport, and websocket code paths do not touch OS
secret stores in steady state,&lt;/li&gt;
&lt;li&gt;Linux and Windows continue to work without Secret Service or Credential
Manager,&lt;/li&gt;
&lt;li&gt;stale local state is recoverable by re-running
&lt;code dir=&quot;auto&quot;&gt;spec-kitty auth login --force&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-keep-os-keychain-first-storage&quot;&gt;Option 1: Keep OS-keychain-first storage&lt;/h3&gt;
&lt;p&gt;Retain the browser-auth/token-manager architecture but store secrets in the OS
keystore when possible.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Reuses native OS facilities.&lt;/li&gt;
&lt;li&gt;Avoids on-disk bearer-token ciphertext files on machines with a usable
keychain.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Reintroduces backend-specific behavior and support burden.&lt;/li&gt;
&lt;li&gt;Performs badly for Python-launched CLI processes on macOS.&lt;/li&gt;
&lt;li&gt;Keeps Linux and Windows tied to desktop credential services.&lt;/li&gt;
&lt;li&gt;Leaves runtime behavior dependent on infrastructure the user may not expect.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-encrypted-file-only-storage&quot;&gt;Option 2: Encrypted file-only storage&lt;/h3&gt;
&lt;p&gt;Keep browser-mediated OAuth and the token manager, but persist sessions only in
the encrypted file-backed store under &lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty/auth/&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;One storage model across macOS, Linux, and Windows.&lt;/li&gt;
&lt;li&gt;Predictable runtime behavior for background and non-interactive flows.&lt;/li&gt;
&lt;li&gt;Simpler docs, tests, and recovery guidance.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires careful file-locking and permission handling.&lt;/li&gt;
&lt;li&gt;Gives up OS-keychain integration entirely.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-plaintext-files&quot;&gt;Option 3: Plaintext files&lt;/h3&gt;
&lt;p&gt;Persist renewable sessions in an unencrypted local file.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Simplest possible implementation.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Unacceptable security posture for bearer and refresh credentials.&lt;/li&gt;
&lt;li&gt;Rejected.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-4-signed-helper-for-keychain-stabilization&quot;&gt;Option 4: Signed helper for keychain stabilization&lt;/h3&gt;
&lt;p&gt;Keep OS keychains, but add an additional native component to stabilize process
identity.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Could reduce macOS prompt friction.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Solves only one platform symptom, not the broader product mismatch.&lt;/li&gt;
&lt;li&gt;Adds packaging, signing, and distribution complexity.&lt;/li&gt;
&lt;li&gt;Still leaves a multi-backend persistence model.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;This ADR supersedes and replaces:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-09-2-cli-saas-auth-is-browser-mediated-oauth-not-password.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Issue lineage:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/559&quot;&gt;Priivacy-ai/spec-kitty#559&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/562&quot;&gt;Priivacy-ai/spec-kitty#562&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/603&quot;&gt;Priivacy-ai/spec-kitty#603&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Implementation seams this ADR governs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/auth/secure_storage/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/auth/token_manager.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/auth/flows/authorization_code.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/auth/flows/device_code.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/_auth_status.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tracker/saas_client.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/client.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/body_transport.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/background.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/auth/websocket/token_provisioning.py&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
