<?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-26-2-auth-transport-boundary/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-26-2-auth-transport-boundary/</id>
  <title>ADR: Centralized Auth Transport Boundary</title>
  <updated>2026-04-26T00: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-26-2-auth-transport-boundary/"/>
  <summary>Makes one module the sole owner of authenticated HTTP: bearer injection, 401 refresh-and-retry-once, and deduplicated failure reporting behind singleton clients.</summary>
  <content type="html">&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/stability-and-hygiene-hardening-2026-04-01KQ4ARB/research.md&lt;/code&gt; (D9, D12)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/stability-and-hygiene-hardening-2026-04-01KQ4ARB/contracts/tracker-public-imports.md&lt;/code&gt;
(“Auth transport adoption (FR-030)”)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_auth_transport_singleton.py&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;Before this mission, every HTTP-using subsystem inside &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;
implemented its own auth handling:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tracker/saas_client.py&lt;/code&gt; instantiated &lt;code dir=&quot;auto&quot;&gt;httpx.Client&lt;/code&gt;
directly, ran its own &lt;code dir=&quot;auto&quot;&gt;_force_refresh_sync()&lt;/code&gt; bridge, and handled
401 retry-once locally.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/auth/http/transport.py&lt;/code&gt; exposed an async-only
&lt;code dir=&quot;auto&quot;&gt;OAuthHttpClient&lt;/code&gt; with similar refresh semantics.&lt;/li&gt;
&lt;li&gt;The websocket client at &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/client.py&lt;/code&gt; consumed
the token via &lt;code dir=&quot;auto&quot;&gt;provision_ws_token()&lt;/code&gt; but then maintained its own
reconnect/backoff loop.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The result was three implementations of “401 → refresh → retry” with
three different log paths. When refresh failed, each subsystem printed
its own user-facing line, producing the duplicate-message symptom that
FR-029 / NFR-007 explicitly prohibits (≤ 1 user-facing token-refresh
failure line per command invocation).&lt;/p&gt;
&lt;p&gt;The contract for &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker.bidirectional_sync()&lt;/code&gt; (frozen in
&lt;code dir=&quot;auto&quot;&gt;contracts/tracker-public-imports.md&lt;/code&gt;) further mandates that
&lt;code dir=&quot;auto&quot;&gt;TrackerClient&lt;/code&gt; MUST acquire its HTTP transport from a single
spec-kitty-side surface. That contract is the load-bearing test for the
boundary defined in this ADR.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;A new module — &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/auth/transport.py&lt;/code&gt; — is the single
owner of authenticated HTTP transports inside &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;public-surface&quot;&gt;Public surface&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;AuthenticatedClient&lt;/code&gt; (sync) wraps &lt;code dir=&quot;auto&quot;&gt;httpx.Client&lt;/code&gt; and performs:
&lt;ul&gt;
&lt;li&gt;bearer injection via the process-wide &lt;code dir=&quot;auto&quot;&gt;TokenManager&lt;/code&gt;,&lt;/li&gt;
&lt;li&gt;401 → forced refresh → retry-once,&lt;/li&gt;
&lt;li&gt;structured failure surface via &lt;code dir=&quot;auto&quot;&gt;AuthRefreshFailed&lt;/code&gt; (cause chain
preserved on &lt;code dir=&quot;auto&quot;&gt;__cause__&lt;/code&gt;),&lt;/li&gt;
&lt;li&gt;per-invocation user-facing failure dedup (FR-029, NFR-007) keyed
on a module-level boolean.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;AsyncAuthenticatedClient&lt;/code&gt; is the async analog; today it delegates
to the existing &lt;code dir=&quot;auto&quot;&gt;OAuthHttpClient&lt;/code&gt; and shares the dedup state.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;get_client()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;get_async_client()&lt;/code&gt; are process-scoped singleton
accessors with double-checked-locking init.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;AuthRefreshFailed&lt;/code&gt; extends &lt;code dir=&quot;auto&quot;&gt;AuthenticationError&lt;/code&gt; with a stable
&lt;code dir=&quot;auto&quot;&gt;error_code&lt;/code&gt; so structured logging / SaaS sync surfaces can branch
on it without string-matching the message.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;architectural-enforcement&quot;&gt;Architectural enforcement&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_auth_transport_singleton.py&lt;/code&gt; walks
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tracker/&lt;/code&gt;, and
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/auth/websocket/&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;ast&lt;/code&gt;, asserting that NO module
under those subsystems contains a direct &lt;code dir=&quot;auto&quot;&gt;httpx.Client(...)&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;httpx.AsyncClient(...)&lt;/code&gt; constructor call. The only allowlisted modules
are &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/auth/transport.py&lt;/code&gt; (this ADR’s home) and
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/auth/http/transport.py&lt;/code&gt; (the SaaS-fallback layer the
new transport delegates to).&lt;/p&gt;
&lt;p&gt;The architectural test also includes a negative-control case that
synthesizes a forbidden call into &lt;code dir=&quot;auto&quot;&gt;tmp_path&lt;/code&gt; and asserts the scanner
flags it. This guards against silent passes when the AST shape changes
under us.&lt;/p&gt;
&lt;h3 id=&quot;token-refresh-log-dedup-fr-029-nfr-007&quot;&gt;Token-refresh log dedup (FR-029, NFR-007)&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;AuthenticatedClient&lt;/code&gt; emits at most one user-facing token-refresh
failure line per process invocation. Subsequent failures within the
same command are accumulated to a debug log only. The dedup state
lives at module scope (&lt;code dir=&quot;auto&quot;&gt;_user_facing_failure_emitted&lt;/code&gt;) because CLI
processes are short-lived; a long-running daemon would need
per-request scoping which is explicitly out of scope here (see
&lt;code dir=&quot;auto&quot;&gt;tasks/WP06-sync-and-auth.md&lt;/code&gt; Risks).&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;required-of-every-new-http-using-subsystem&quot;&gt;Required of every new HTTP-using subsystem&lt;/h3&gt;
&lt;p&gt;Any new code path that opens an authenticated HTTP connection MUST
acquire its client via &lt;code dir=&quot;auto&quot;&gt;from specify_cli.auth.transport import get_client&lt;/code&gt; (or the async accessor). Direct &lt;code dir=&quot;auto&quot;&gt;httpx.Client(...)&lt;/code&gt; calls
in the walked subsystems will fail
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_auth_transport_singleton.py&lt;/code&gt; at CI time and
block the merge.&lt;/p&gt;
&lt;p&gt;If a subsystem has a legitimate need for non-authenticated HTTP (e.g.
the OAuth login flows, where there is no session yet), it must keep
its calls under &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/auth/flows/&lt;/code&gt; — that path is outside
the walked subsystems by construction. New top-level subsystems that
need HTTP MUST either:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;import &lt;code dir=&quot;auto&quot;&gt;get_client()&lt;/code&gt; and route through it, or&lt;/li&gt;
&lt;li&gt;get explicit allowlist entries in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_auth_transport_singleton.py&lt;/code&gt; with an
accompanying ADR amendment.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;operator-visible-behavior&quot;&gt;Operator-visible behavior&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty sync now&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;spec-kitty tracker run&lt;/code&gt;, and websocket
reconnection paths all emit at most one “Authentication expired”
line per command invocation.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;AuthRefreshFailed&lt;/code&gt; is a structured error type carrying an
&lt;code dir=&quot;auto&quot;&gt;error_code&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;refresh_token_invalid&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;post_refresh_401&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;not_authenticated&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;refresh_no_token&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;refresh_unexpected&lt;/code&gt;),
enabling downstream tooling to differentiate failure modes without
string-matching.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;test-impact&quot;&gt;Test impact&lt;/h3&gt;
&lt;p&gt;The existing tracker tests under &lt;code dir=&quot;auto&quot;&gt;tests/sync/tracker/&lt;/code&gt; continue to
work unchanged: their autouse conftest patches the legacy
&lt;code dir=&quot;auto&quot;&gt;_fetch_access_token_sync&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;_force_refresh_sync&lt;/code&gt; module-level
helpers, which are still called by &lt;code dir=&quot;auto&quot;&gt;SaaSTrackerClient._request&lt;/code&gt; for
backward compatibility (the helpers fetch the token; the architectural
boundary is enforced at the &lt;em&gt;transport&lt;/em&gt; layer via
&lt;code dir=&quot;auto&quot;&gt;request_with_fallback_sync&lt;/code&gt;).&lt;/p&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives considered&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Adopt a third-party auth library&lt;/strong&gt; (e.g. &lt;code dir=&quot;auto&quot;&gt;httpx-auth&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;requests-oauthlib&lt;/code&gt;). Rejected — introduces a new dependency, and
the existing httpx-based stack already provides every primitive we
need.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Per-client refresh with a shared &lt;code dir=&quot;auto&quot;&gt;TokenManager&lt;/code&gt;&lt;/strong&gt; (status quo).
Rejected — that is the existing bug. The single refresh lock
inside &lt;code dir=&quot;auto&quot;&gt;TokenManager&lt;/code&gt; already prevents thundering-herd refreshes,
but the absence of a single transport boundary still meant three
different log paths and three different 401-retry implementations.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Move sync into the auth subsystem entirely.&lt;/strong&gt; Rejected as too
invasive for this mission; the sync subsystem is large and owns
its own routing semantics. The narrower change here (centralize
the &lt;em&gt;transport&lt;/em&gt;, leave the routing in place) is sufficient to
close FR-030 and pin the invariant in CI.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;ADR &lt;code dir=&quot;auto&quot;&gt;2026-04-19-1-cli-auth-uses-encrypted-file-only-session-storage.md&lt;/code&gt; —
underlying session storage decision.&lt;/li&gt;
&lt;li&gt;ADR &lt;code dir=&quot;auto&quot;&gt;2026-04-09-2-cli-saas-auth-is-browser-mediated-oauth-not-password.md&lt;/code&gt; —
underlying auth flow.&lt;/li&gt;
&lt;li&gt;Mission &lt;code dir=&quot;auto&quot;&gt;stability-and-hygiene-hardening-2026-04-01KQ4ARB&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;tasks/WP06-sync-and-auth.md&lt;/code&gt; — implementation tasks T032 through
T038.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
