Oauth Connection Health

Why the silence is the product

Sync code is written to be resilient: it catches, retries, logs at debug, carries on. That is right for a rate limit and catastrophic for an auth failure, because an auth failure is permanent — and retrying it forever looks exactly like working. Busy queue, full logs, green dashboard, nothing syncing.

The first person to find out is the customer, asking why a report is empty.

  classifyFailure({ oauthError: "invalid_grant" });
  // { klass: "terminal", stopRetrying: true,
  //   detail: "…the grant is gone (revoked, expired, or the refresh token was rotated and the
  //            old one used). Retrying cannot recover it; the user must reconnect" }

An unclassified failure stops retrying, which is the opposite of the usual default and is deliberate. Stopping on something you can't classify is recoverable — a human looks at it. Retrying it silently is not.

The five ways a connection dies quietly

| cause | what it looks like | |---|---| | refresh token expired | works until it doesn't; often a fixed idle timeout nobody recorded | | user revoked access | your DB holds a token with a valid shape and a future expiry | | rotated refresh token not saved | works until the access token expires, then dies permanently | | scopes changed | authenticates fine, 403s on exactly the endpoint the feature needs | | password changed | some providers treat it as a global revocation |

The rotation one is the cruellest: the failure appears weeks after the mistake, with nothing connecting the two.

  tokensToPersist(current, response, now);
  // warnings: ["the provider returned a NEW refresh token — the previous one is now invalid.
  //            Persist this or the integration dies when the current access token expires"]

It also reports scopes silently dropped during a refresh, which is the quiet start of a 403.

unknown is never healthy

A connection that can't be assessed is not a working one. The whole failure mode here is a system reporting health it never established, so unknown is its own state and at_risk fires before an expiry rather than after — prompting a user while the connection still works costs one click; prompting after costs a support ticket and a re-auth.

What it does not do

| not included | why | |---|---| | Performing OAuth, refreshing, or storing tokens | it judges records you already have | | Talking to any provider | zero network — it works from stored state | | Per-provider quirk tables | idle-expiry windows differ wildly; you supply yours | | Consent-grant risk scoring | oauth-consent-risk |

Provider behaviour varies more than the specs suggest. refreshTokenIdleExpiryDays and rotatesRefreshTokens are inputs precisely because no library can keep an accurate table of them.