Authentication Token Management#

The Tuist CLI's authentication token system handles credential storage, JWT refresh, race-condition prevention, and graceful degradation when the server is unavailable. The core entry point is ServerAuthenticationController in cli/Sources/TuistServer/Client/.

Token Types#

AuthenticationToken has three variants:

Environment-variable tokens (TUIST_TOKEN, and deprecated TUIST_CONFIG_TOKEN / TUIST_CONFIG_CLOUD_TOKEN) always resolve to .project and are checked first, before any credential store lookup 1.

Credential Storage#

ServerCredentialsStore persists {accessToken, refreshToken?} in a platform-specific backend 2:

• macOS CLI / Linux: JSON file at ~/.config/tuist/credentials/{host}.json (atomic write)
• iOS app: Keychain, keyed by {serverURL}_access_token / {serverURL}_refresh_token

Credentials are accessed via the @TaskLocal ServerCredentialsStore.current 3, allowing test injection without global mutation. An AsyncStream<ServerCredentials?> (credentialsChanged) notifies observers on every store or delete 4.

Token Refresh Flow#

authenticationToken(serverURL:) is the public entry point. It 5:

1. Checks for an environment-variable token first (bypasses all refresh logic).
2. Looks up an in-memory memoized value from CachedValueStore (keyed by authentication-token-{url}), bounded by the token's own JWT expiry minus 60 seconds for .user/.account, or 5 minutes for .project 6.
3. If the memo is absent or expired, calls authenticationTokenRefreshingIfNeeded(...).

Expiry threshold: a token is considered expired when accessToken.expiryDate is ≤ 30 seconds away 7.

Refresh execution matrix#

authenticationTokenRefreshingIfNeeded dispatches based on (tokenStatus, inBackground, locking) 8:

Background refresh is controlled by ServerAuthenticationConfig.backgroundRefresh, a @TaskLocal defaulting to false.

Lock coordination#

To prevent duplicate refresh requests from parallel tuist processes, the foreground path uses a file-system lock at {stateDirectory}/auth-locks/token_{url}.lock 9. The lock implementation polls every 500 ms, up to 30 attempts (15 seconds total), before throwing timedOut 10. A lock file older than 10 seconds is treated as stale and removed 11.

In-process deduplication is handled by CachedValueStore — multiple concurrent callers waiting on the same key coalesce onto a single in-flight Task.

Background refresh subprocess#

When backgroundRefresh == true, the expired-token path spawns 12:

tuist auth refresh-token {serverURL}

The parent waits (via file-system lock) for the subprocess to write fresh credentials, then reads them back.

Network Error Handling#

refreshTokens(serverURL:refreshToken:) makes the HTTP call via RefreshAuthTokenService. Error mapping:

Unauthorized / credential deletion race#

deletingCredentialsOnUnauthorizedError wraps every refresh call. On a 401 from the server:

1. It compares the refresh token before the call to the one on-disk after the call.
2. If they differ, a peer process has already rotated the token — credentials are preserved.
3. If they are the same, the refresh token is genuinely invalid — ServerCredentialsStore.current.delete(serverURL:) is called 15.

This prevents a common race where two parallel tuist invocations both try to refresh the same token: the slower one would get a 401 on an already-rotated token and should not wipe the fresh credentials written by the faster one.

HTTP Middleware Integration#

ServerClientAuthenticationMiddleware intercepts every outgoing request:

1. Calls authenticationToken(serverURL:refreshIfNeeded:true) to obtain a (potentially just-refreshed) token.
2. If ServerAuthenticationConfig.optionalAuthentication is enabled, missing or errored tokens allow the request through unauthenticated 16.
3. Otherwise throws ClientAuthenticationError.notAuthenticated.
4. Injects Authorization: Bearer {token} on success 17.

Key Files#