Harden token refresh fallback

Author: sionsmith

docs/auth.md

@@ -194,7 +194,7 @@ Tokens are stored in the operating system keyring:
 
 The config file stores profile settings, not access tokens.
 
-Current known gap: automatic refresh-token handling is not yet release-grade. If a token expires and refresh does not happen, commands return `AUTH_TOKEN_EXPIRED` and the user must run `teams auth login` again.
+The CLI automatically redeems the stored refresh token when an access token is expired or near expiry, then updates the keyring with the refreshed token. If no refresh token is stored, or the identity platform rejects the refresh request, commands return `AUTH_TOKEN_EXPIRED` and the user must run `teams auth login` again.
 
 ## Diagnostics
 

docs/man/teams-auth.7

@@ -122,8 +122,9 @@ Tenant ID or tenant domain.
 Test-only switch used to avoid OS keyring access in automated tests. Do not use
 for real login sessions.
 .SH KNOWN GAPS
-Automatic refresh-token handling must be completed and validated before public
-commercial release. If a stored access token expires today, run:
+Stored access tokens are refreshed automatically when a refresh token is
+available. If the refresh token is missing, expired, revoked, or rejected by
+the identity platform, run:
 .PP
 .nf
 teams auth login --device-code

docs/release-readiness.md

@@ -29,7 +29,7 @@ Live read-only validation passed against the OSO profile:
 Known live behavior:
 
 - Some meeting chats can appear in `chat list` but reject message reads with `403` if the user is no longer in the roster.
-- Stored token expiry currently requires manual re-login.
+- Stored token expiry is handled through refresh-token redemption when a refresh token is available. `AUTH_TOKEN_EXPIRED` still means the refresh token is missing, expired, revoked, or rejected by the identity platform.
 
 Entra app registration status as of 2026-05-27:
 
@@ -120,15 +120,14 @@ Dependabot is configured to group GitHub Actions updates into one PR so the comp
 These must be resolved before marketing this as production-ready for external customers:
 
 1. Publisher verification for the OSO Entra app.
-2. Automatic refresh-token handling and tests.
-3. Windows live validation using Windows Credential Manager.
-4. Controlled write/read smoke test in a dedicated Teams test channel.
-5. Documented admin-consent onboarding flow for customer tenants.
-6. Clear policy for unsupported Graph operations, tenant restrictions, and destructive commands.
-7. Security review of token storage, logs, and exported token behavior.
-8. Versioned release notes and upgrade guidance.
-9. Public website HTTPS fixed for `https://msteamscli.com/`; HTTP is live, but the current TLS certificate does not cover the hostname.
-10. Terms of service URL published and added to the Entra app branding.
+2. Windows live validation using Windows Credential Manager.
+3. Controlled write/read smoke test in a dedicated Teams test channel.
+4. Documented admin-consent onboarding flow for customer tenants.
+5. Clear policy for unsupported Graph operations, tenant restrictions, and destructive commands.
+6. Security review of token storage, logs, and exported token behavior.
+7. Versioned release notes and upgrade guidance.
+8. Public website HTTPS fixed for `https://msteamscli.com/`; HTTP is live, but the current TLS certificate does not cover the hostname.
+9. Terms of service URL published and added to the Entra app branding.
 
 ## Microsoft official trust checklist
 

src/auth/mod.rs

@@ -40,14 +40,12 @@ pub async fn resolve_token(profile: &str) -> Result<TokenInfo> {
                 return Ok(info);
             }
             // Token is at/near expiry: attempt a silent refresh-token
-            // redemption. Any failure falls back to the original behaviour
-            // (TokenExpired) so the observable exit code is unchanged.
+            // redemption. If the token is still inside the skew window, keep
+            // using it on refresh failure; only hard-expired tokens become
+            // TokenExpired.
             match attempt_refresh(profile, &info).await {
                 Ok(refreshed) => Ok(refreshed),
-                Err(e) => {
-                    tracing::debug!("Silent token refresh failed, treating as expired: {e}");
-                    Err(TeamsError::TokenExpired)
-                }
+                Err(e) => handle_refresh_failure(&info, e),
             }
         }
         Err(_) => Err(TeamsError::AuthError(
@@ -66,6 +64,16 @@ fn needs_refresh(info: &TokenInfo) -> bool {
         )
 }
 
+fn handle_refresh_failure(info: &TokenInfo, error: TeamsError) -> Result<TokenInfo> {
+    if info.is_expired() {
+        tracing::debug!("Silent token refresh failed for expired token: {error}");
+        Err(TeamsError::TokenExpired)
+    } else {
+        tracing::debug!("Silent token refresh failed before expiry, using current token: {error}");
+        Ok(info.clone())
+    }
+}
+
 /// Silently redeem the stored refresh token for a fresh access token and persist
 /// it. Returns an error (mapped to `TokenExpired` by the caller) when the token
 /// cannot be refreshed — e.g. no refresh token, undecodable claims, or the
@@ -89,14 +97,32 @@ async fn attempt_refresh(profile: &str, info: &TokenInfo) -> Result<TokenInfo> {
 
     let response =
         refresh::refresh_access_token(&client_id, &tenant_id, refresh_token, &scope).await?;
-    let refreshed = response.into_token_info(profile);
+    let refreshed = refreshed_token_info(profile, info, response);
 
     // Best-effort persistence so the next invocation reuses the new token.
     let _ = keyring::store_token(profile, &refreshed);
 
     Ok(refreshed)
 }
 
+fn refreshed_token_info(
+    profile: &str,
+    previous: &TokenInfo,
+    response: token::MsTokenResponse,
+) -> TokenInfo {
+    let mut refreshed = response.into_token_info(profile);
+
+    if refreshed.refresh_token.is_none() {
+        refreshed.refresh_token.clone_from(&previous.refresh_token);
+    }
+
+    if refreshed.scope.is_none() {
+        refreshed.scope.clone_from(&previous.scope);
+    }
+
+    refreshed
+}
+
 /// Build the scope string for the refresh request: reuse the originally granted
 /// scope (ensuring `offline_access` so future refreshes keep working), or fall
 /// back to the default delegated scopes.
@@ -191,6 +217,83 @@ mod tests {
         );
     }
 
+    #[test]
+    fn refresh_failure_returns_current_token_inside_skew_window() {
+        let info = token_with(
+            Some(Utc::now() + Duration::seconds(30)),
+            Some("a-refresh-token"),
+            Some("User.Read offline_access"),
+        );
+
+        let resolved =
+            handle_refresh_failure(&info, TeamsError::AuthError("temporary failure".into()))
+                .unwrap();
+
+        assert_eq!(resolved.access_token, info.access_token);
+        assert_eq!(resolved.refresh_token, info.refresh_token);
+    }
+
+    #[test]
+    fn refresh_failure_expires_hard_expired_token() {
+        let info = token_with(
+            Some(Utc::now() - Duration::seconds(1)),
+            Some("a-refresh-token"),
+            Some("User.Read offline_access"),
+        );
+
+        let err =
+            handle_refresh_failure(&info, TeamsError::AuthError("rejected".into())).unwrap_err();
+
+        assert!(matches!(err, TeamsError::TokenExpired));
+    }
+
+    #[test]
+    fn refreshed_token_info_preserves_previous_refresh_token_and_scope_when_missing() {
+        let previous = token_with(
+            Some(Utc::now() - Duration::hours(1)),
+            Some("old-refresh"),
+            Some("User.Read offline_access"),
+        );
+        let response = token::MsTokenResponse {
+            access_token: "new-access".into(),
+            token_type: "Bearer".into(),
+            expires_in: 3600,
+            scope: None,
+            refresh_token: None,
+        };
+
+        let refreshed = refreshed_token_info("work", &previous, response);
+
+        assert_eq!(refreshed.access_token, "new-access");
+        assert_eq!(refreshed.profile, "work");
+        assert_eq!(refreshed.scope.as_deref(), Some("User.Read offline_access"));
+        assert_eq!(refreshed.refresh_token.as_deref(), Some("old-refresh"));
+    }
+
+    #[test]
+    fn refreshed_token_info_uses_rotated_refresh_token_and_scope_when_present() {
+        let previous = token_with(
+            Some(Utc::now() - Duration::hours(1)),
+            Some("old-refresh"),
+            Some("User.Read offline_access"),
+        );
+        let response = token::MsTokenResponse {
+            access_token: "new-access".into(),
+            token_type: "Bearer".into(),
+            expires_in: 3600,
+            scope: Some("User.Read Chat.ReadWrite offline_access".into()),
+            refresh_token: Some("new-refresh".into()),
+        };
+
+        let refreshed = refreshed_token_info("work", &previous, response);
+
+        assert_eq!(
+            refreshed.scope.as_deref(),
+            Some("User.Read Chat.ReadWrite offline_access")
+        );
+        assert_eq!(refreshed.refresh_token.as_deref(), Some("new-refresh"));
+    }
+
     #[tokio::test]
     async fn attempt_refresh_without_refresh_token_is_token_expired() {
         // Expired token, no refresh token: must fail fast as TokenExpired with

src/auth/refresh.rs

@@ -16,10 +16,19 @@ pub async fn refresh_access_token(
     scope: &str,
 ) -> Result<MsTokenResponse> {
     let token_url = format!("https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token");
+    refresh_access_token_at(&token_url, client_id, refresh_token, scope).await
+}
+
+async fn refresh_access_token_at(
+    token_url: &str,
+    client_id: &str,
+    refresh_token: &str,
+    scope: &str,
+) -> Result<MsTokenResponse> {
     let http = Client::new();
 
     let resp = http
-        .post(&token_url)
+        .post(token_url)
         .form(&[
             ("grant_type", "refresh_token"),
             ("client_id", client_id),
@@ -41,3 +50,85 @@ pub async fn refresh_access_token(
         .await
         .map_err(|e| TeamsError::AuthError(format!("Failed to parse refresh response: {e}")))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use wiremock::matchers::{method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    #[tokio::test]
+    async fn refresh_access_token_posts_refresh_grant_and_parses_response() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/token"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "access_token": "new-access",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+                "scope": "User.Read offline_access",
+                "refresh_token": "new-refresh"
+            })))
+            .mount(&server)
+            .await;
+
+        let response = refresh_access_token_at(
+            &format!("{}/token", server.uri()),
+            "client-id",
+            "old-refresh",
+            "User.Read offline_access",
+        )
+        .await
+        .unwrap();
+
+        let requests = server.received_requests().await.unwrap();
+        assert_eq!(requests.len(), 1);
+
+        let body = std::str::from_utf8(&requests[0].body).unwrap();
+        let form: std::collections::HashMap<String, String> =
+            url::form_urlencoded::parse(body.as_bytes())
+                .into_owned()
+                .collect();
+
+        assert_eq!(
+            form.get("grant_type").map(String::as_str),
+            Some("refresh_token")
+        );
+        assert_eq!(form.get("client_id").map(String::as_str), Some("client-id"));
+        assert_eq!(
+            form.get("refresh_token").map(String::as_str),
+            Some("old-refresh")
+        );
+        assert_eq!(
+            form.get("scope").map(String::as_str),
+            Some("User.Read offline_access")
+        );
+
+        assert_eq!(response.access_token, "new-access");
+        assert_eq!(response.token_type, "Bearer");
+        assert_eq!(response.expires_in, 3600);
+        assert_eq!(response.scope.as_deref(), Some("User.Read offline_access"));
+        assert_eq!(response.refresh_token.as_deref(), Some("new-refresh"));
+    }
+
+    #[tokio::test]
+    async fn refresh_access_token_maps_non_success_to_auth_error() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/token"))
+            .respond_with(ResponseTemplate::new(400).set_body_string("invalid_grant"))
+            .mount(&server)
+            .await;
+
+        let err = refresh_access_token_at(
+            &format!("{}/token", server.uri()),
+            "client-id",
+            "old-refresh",
+            "User.Read offline_access",
+        )
+        .await
+        .unwrap_err();
+
+        assert!(matches!(err, TeamsError::AuthError(message) if message.contains("invalid_grant")));
+    }
+}