<?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-09-2-cli-saas-auth-is-browser-mediated-oauth-not-password/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-09-2-cli-saas-auth-is-browser-mediated-oauth-not-password/</id>
  <title>CLI-to-SaaS Authentication Is Browser-Mediated OAuth, Not Password Login</title>
  <updated>2026-04-09T00: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-09-2-cli-saas-auth-is-browser-mediated-oauth-not-password/"/>
  <summary>Replaced CLI password login with browser-mediated OAuth (PKCE plus loopback callback, device flow headless); later superseded on local session persistence.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;Superseded on 2026-04-19 by
&lt;code dir=&quot;auto&quot;&gt;2026-04-19-1-cli-auth-uses-encrypted-file-only-session-storage.md&lt;/code&gt;.
Keep this ADR for historical context only; do not implement from it.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;The current CLI-to-SaaS authentication implementation drifted into a password
login flow:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty auth login&lt;/code&gt; prompts for username and password,&lt;/li&gt;
&lt;li&gt;the CLI exchanges those credentials for JWTs through SaaS endpoints intended
only for the CLI,&lt;/li&gt;
&lt;li&gt;refresh and token reuse are implemented independently in multiple CLI paths,&lt;/li&gt;
&lt;li&gt;long-running sync and tracker clients can hold stale bearer tokens,&lt;/li&gt;
&lt;li&gt;the implementation no longer matches the product direction that the SaaS is
the human authentication surface.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This is the wrong architectural seam for human users.&lt;/p&gt;
&lt;p&gt;Spec Kitty already has browser-based authentication on &lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas&lt;/code&gt;. Human
CLI authentication should reuse that existing SaaS identity surface, not bypass
it with a second password step. The CLI should open the browser onto the
SaaS, let the user authenticate using normal SaaS login methods, and then store
renewable session credentials locally in a host-owned store.&lt;/p&gt;
&lt;p&gt;The new design must also correct the current token freshness problem. A logged
in CLI should remain authenticated until one of two things happens:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;the user explicitly logs out, or&lt;/li&gt;
&lt;li&gt;the SaaS invalidates the session.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;One human authentication surface&lt;/strong&gt; — SaaS browser auth is the source of
truth for human identity.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No password handling in the CLI&lt;/strong&gt; — CLI must not prompt for or transmit SaaS
passwords.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Renewable long-lived CLI sessions&lt;/strong&gt; — interactive CLI auth must stay fresh
without repeated login prompts during normal operation.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Host-owned secret persistence&lt;/strong&gt; — CLI session storage remains in
&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt;, but with a centralized token manager and OS-backed secret
storage.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Compatibility with existing SaaS auth&lt;/strong&gt; — the solution should build on the
current SaaS/browser stack unless buying identity infrastructure materially
improves the result.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Headless support&lt;/strong&gt; — remote shells and SSH sessions still need a supported
login path.&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 password-based CLI login and patch refresh bugs&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Build first-party OAuth/OIDC on &lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas&lt;/code&gt; and use browser-mediated CLI login with PKCE (chosen)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Migrate human auth to an external identity platform now&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 restores the intended product model,
reuses the SaaS as the single human authentication surface, and avoids the cost
and migration risk of moving the whole identity system to a third party before
that is justified.&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 use browser-mediated
OAuth/OIDC, not username/password entry in the CLI.&lt;/li&gt;
&lt;li&gt;The default interactive flow MUST be Authorization Code with PKCE using a
localhost loopback callback opened from the CLI into the SaaS.&lt;/li&gt;
&lt;li&gt;The CLI MUST also support a headless fallback. Device Authorization Flow is
the preferred fallback for SSH and non-browser environments.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas&lt;/code&gt; MUST issue renewable CLI session credentials whose lifetime
is effectively indefinite under normal use and rotation, ending only on
explicit logout or server-side invalidation.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; MUST centralize all access-token acquisition, refresh, retry,
and invalidation handling behind one token manager. Callers MUST NOT read raw
access tokens directly from storage.&lt;/li&gt;
&lt;li&gt;CLI secret material MUST be stored in a host-owned store backed by the OS
keychain where available. Plain-file metadata may remain for non-secret
session state, but bearer or refresh credentials are not the primary storage
location.&lt;/li&gt;
&lt;li&gt;Existing password-based CLI token endpoints and command flows are deprecated
immediately and MUST be removed after the browser-based flow is fully cut
over.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;buy-vs-build-interpretation&quot;&gt;Buy-vs-Build Interpretation&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;The default implementation path is first-party OAuth/OIDC on the existing
SaaS stack.&lt;/li&gt;
&lt;li&gt;If Spec Kitty later chooses to buy rather than build for human identity,
Auth0 is the preferred external option for CLI/native-app semantics because
it has stronger fit for PKCE, device flow, and rotating renewable sessions.&lt;/li&gt;
&lt;li&gt;Clerk is not the preferred path for this CLI problem because current product
constraints are a weaker fit for scoped CLI/API authorization.&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;Human users authenticate once through the same SaaS browser surface they
already use.&lt;/li&gt;
&lt;li&gt;Password handling is removed from the CLI.&lt;/li&gt;
&lt;li&gt;Token freshness becomes a centralized concern instead of a scattered
implementation detail.&lt;/li&gt;
&lt;li&gt;Long-running sync, tracker, and websocket flows can share one renewable
session model.&lt;/li&gt;
&lt;li&gt;The decision aligns the implementation with the original OAuth-first product
intent.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Coordinated changes are required across both repositories.&lt;/li&gt;
&lt;li&gt;SaaS must expose an authorization surface intended for public/native CLI
clients.&lt;/li&gt;
&lt;li&gt;CLI auth, websocket, sync, and tracker clients all need migration away from
direct token usage.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Service-account or machine-to-machine automation may still require a separate
auth model; this ADR only governs human CLI authentication.&lt;/li&gt;
&lt;li&gt;Host-owned persistence remains the architectural rule; only the credential
model changes.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&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; opens the browser and no longer asks for username or
password,&lt;/li&gt;
&lt;li&gt;the CLI can remain authenticated across long-running sync and tracker usage
without re-login under normal operation,&lt;/li&gt;
&lt;li&gt;all HTTP and websocket callers obtain credentials through a centralized token
manager rather than reading raw tokens directly,&lt;/li&gt;
&lt;li&gt;explicit logout and server-side invalidation both terminate the local CLI
session cleanly,&lt;/li&gt;
&lt;li&gt;the legacy &lt;code dir=&quot;auto&quot;&gt;/api/v1/token/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;/api/v1/token/refresh/&lt;/code&gt; CLI password/JWT
path is removed.&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-password-login-and-patch-refresh-bugs&quot;&gt;Option 1: Keep password login and patch refresh bugs&lt;/h3&gt;
&lt;p&gt;Continue prompting for SaaS credentials in the CLI and incrementally harden the
current JWT refresh model.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Lowest immediate implementation cost.&lt;/li&gt;
&lt;li&gt;Minimal short-term protocol change.&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;Preserves the wrong product and security boundary.&lt;/li&gt;
&lt;li&gt;Leaves the CLI responsible for password collection.&lt;/li&gt;
&lt;li&gt;Encourages continued token-handling sprawl across callers.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-first-party-browser-mediated-oauthoidc-on-the-saas&quot;&gt;Option 2: First-party browser-mediated OAuth/OIDC on the SaaS&lt;/h3&gt;
&lt;p&gt;Use SaaS browser auth as the human login surface, with CLI-native PKCE and
headless device flow semantics.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Matches the intended product experience.&lt;/li&gt;
&lt;li&gt;Reuses existing SaaS identity surface.&lt;/li&gt;
&lt;li&gt;Solves login UX and refresh architecture together.&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 server and client implementation work.&lt;/li&gt;
&lt;li&gt;Requires a migration path off existing CLI token endpoints.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-migrate-identity-to-an-external-platform-now&quot;&gt;Option 3: Migrate identity to an external platform now&lt;/h3&gt;
&lt;p&gt;Adopt a third-party identity provider for both SaaS and CLI login before
addressing the local architecture.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Offloads part of the identity implementation burden.&lt;/li&gt;
&lt;li&gt;May provide mature token/session features.&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;Larger migration scope than required for the immediate problem.&lt;/li&gt;
&lt;li&gt;Couples a CLI auth redesign to a broader SaaS identity platform decision.&lt;/li&gt;
&lt;li&gt;Still requires CLI transport and storage cleanup locally.&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 the password-era human CLI auth direction encoded in:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty/kitty-specs/027-cli-authentication-module-commands/spec.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty/kitty-specs/059-saas-mediated-cli-tracker-reflow/spec.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;This ADR clarifies and extends, but does not replace, the following accepted ADRs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-02-27-2-host-owned-tracker-persistence-boundary.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-04-1-tracker-binding-context-is-discovered-not-user-supplied.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;architecture/1.x/notes/adr-connector-auth-binding-separation.md&lt;/code&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;spec-kitty/src/specify_cli/cli/commands/auth.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty/src/specify_cli/sync/auth.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty/src/specify_cli/tracker/saas_client.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty/src/specify_cli/sync/background.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty/src/specify_cli/sync/batch.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty/src/specify_cli/sync/body_transport.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty/src/specify_cli/sync/client.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas/spec_kitty_saas/urls.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas/apps/sync/jwt_views.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas/apps/sync/views.py&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
