refresh-guard 🔐

Concurrency-safe OAuth2 token refresh. Zero dependencies.

When several requests (or several agents/CLIs sharing one credential) hit an expired access token at once, the naive code refreshes N times in parallel — which trips refresh-token rotation/reuse detection (Okta, Auth0, Salesforce), drops the refresh token entirely (Google omits it on refresh), or corrupts the token file via a read-modify-write race. The symptoms: random invalid_grant, surprise re-auth, "works locally, fails under load."

refresh-guard makes one refresh happen, correctly:

import { createTokenManager, fileStore } from "refresh-guard";

const tokens = createTokenManager({
  provider: "google",                 // optional: pick a quirks profile
  store: fileStore("~/.myapp/creds.json"),   // atomic temp-file+rename persistence
  refresh: async (prev) => {
    const r = await fetch("https://oauth2.googleapis.com/token", { method: "POST", body: form(prev.refresh_token) });
    return await r.json();            // { access_token, expires_in→expires_at, refresh_token? }
  }
});

// Call from anywhere, as often as you like — exactly ONE refresh happens:
const accessToken = await tokens.getValidToken();

What it guarantees

• Single-flight refresh — N concurrent callers detecting expiry trigger exactly one refresh; all await the same result. (Tested with 50 concurrent callers → 1 refresh.)
• Correct rotation/merge — if the provider returns a new refresh_token, it's used; if it omits one (Google), the old one is kept, not lost.
• Atomic persistence — fileStore writes to a temp file then renames, so a crash or racing reader never sees a half-written token.
• Proactive refresh — refreshes skewMs (default 60s) before expiry, with no thundering herd.
• Self-healing — a failed refresh rejects all current waiters and clears the in-flight lock, so the next call retries cleanly (no stuck promise).

Provider quirks registry

A typed table of real, documented behaviors (QUIRKS): Google (omits refresh_token on refresh → keep it), Okta/Auth0/Salesforce (rotation + reuse detection → concurrency is fatal, single-flight required), GitHub (OAuth-app non-expiring same-token), Microsoft (rotation). The core is correct-by-default; the profile adds polish.

API

createTokenManager({ refresh, store?, provider?, skewMs?, initial?, onRefresh? }) → { getValidToken(), getCredentials(), invalidate(), current(), provider }. Stores: memoryStore(), fileStore(path), or bring your own { get, set }. Full types in index.d.ts.

Why not just use my OAuth client?

simple-oauth2, framework auth, and most clients implement the flow — none own concurrency-safe refresh + rotation-merge + atomic persistence as an installable primitive. This is the boring building block that's been missing.

12/12 tests (npm test) cover the concurrency + rotation + persistence guarantees. MIT.