fix(cli): refresh Bazel credential-helper token before the expiry boundary

What changed

The tuist bazel credential-helper now refreshes a user’s access token proactively when it is within a 60s safety margin of expiring, and reports expires to Bazel brought forward by that same margin (exp − 60s). Project tokens (no expiry) and account tokens (cannot be refreshed) are reported unchanged.

Why

Bazel remote-cache builds against Kura burst with UNAUTHENTICATED a few minutes into a build — on whichever operation dominates at that instant — and then recover. In two captured gRPC logs:

• bazel-grpc-4: 104× UNAUTHENTICATED on Write in a 2.0s burst at +348s
• bazel-grpc-6: 1089× UNAUTHENTICATED on Read in a 0.6s burst at +414s

Both bursts are tight and land on the access token’s 10-minute (600s) TTL boundary (the token was already partially aged at build start).

Root cause

Bazel’s CredentialCacheExpiry caches the credential-helper response until exactly the expires we report and only re-invokes the helper lazily, on the first request issued after that timestamp — it never refreshes early (the --credential_helper_cache_duration flag is only the no-expires fallback). The helper reported the access token’s exact exp, leaving zero margin, so Bazel kept attaching the token to requests right up to the boundary. The in-flight batch of remote-cache RPCs around the boundary then reached Kura after exp and was rejected.

Kura validates the Tuist JWT statelessly (signature + exp, locally, via kura.jwt_verify), so issuing a new access token via refresh never revokes a previously issued one — the only thing that produces UNAUTHENTICATED is exp passing. This rules out the alternative theory (parallel credential-helper calls minting tokens that invalidate each other): stateless JWTs are not revoked on refresh.

Why this solution

The boundary failure is fundamentally that Bazel reuses a cached credential up to the instant it expires. Reporting an earlier expires makes Bazel reload the helper ~60s before the real expiry; pairing that with a proactive refresh at the same threshold means the helper hands back a token with a full lifetime ahead of it. The result: no in-flight request can ever carry a token within 60s of being rejected, which comfortably covers request latency and clock skew between a developer machine and the cache. The 60s margin is well under the 600s TTL, so it costs roughly one extra refresh per ~9 minutes of continuous building.

The refresh is best-effort: if it fails (e.g. a transient network error) the helper falls back to the token it already has, which is still valid for up to the safety margin, rather than failing the request outright.

User impact

Developers running long Bazel builds against the Tuist/Kura remote cache no longer hit a mid-build wave of UNAUTHENTICATED errors (and the costly stall/retry that followed) when their short-lived access token crosses its expiry.

Validation

• Unit tests cover the margin reporting, the proactive refresh within the margin, and the best-effort fallback when the refresh fails (plus existing project/account/error paths). All pass; swiftformat + swiftlint clean.
• The built binary against staging returns a freshly refreshed token and reports expires exactly 60s before the JWT exp.
• A real build issuing 2400+ authenticated gRPC requests across a token reported-expiry boundary completed with zero UNAUTHENTICATED.

🤖 Generated with Claude Code