@withone/connect 0.10.0 → 0.11.0

package/README.md

@@ -166,6 +166,8 @@ export const oneConnect = createOneConnect({
     saveTokens: (userId, tokens) => db.oneTokens.upsert(userId, tokens),
     loadTokens: (userId) => db.oneTokens.find(userId),
     clearTokens: (userId) => db.oneTokens.delete(userId),
+    // Required when you run more than one server or a worker. See "Tokens" below.
+    withLock: (userId, run) => db.withUserLock(userId, run),
   },
 });
 ```
@@ -207,7 +209,7 @@ What the routes do for you: mint `state` and a PKCE verifier, keep them in a per
 
 ## 4 · Using the grant
 
-Everything runs on your server through the same client. Tokens are refreshed for you before they expire; a refresh One refuses clears the stored tokens and throws `OneConnectError` with code `refresh_failed`, which means "ask the user to connect again".
+Everything runs on your server through the same client. Every call refreshes the tokens first when they are about to expire (see [Tokens](#5--tokens-storing-refreshing-keeping-alive)).
 
 ```ts
 // What the grant reaches, each connection with its access
@@ -231,7 +233,88 @@ const reply = await oneConnect.runAction(userId, {
 
 `blockedByGrant` is true when One refused the call because it is outside what the user granted. The provider was never called. Do not retry; the user chose that. Anything else on One's `/v1` API: `oneConnect.fetch(userId, "/connections", init)` adds the bearer and the tenancy headers for you.
 
-Other calls on the client: `isConnected`, `getAccessToken`, `getTokens`, `refreshTokens`, `disconnect`.
+Other calls on the client: `isConnected`, `getAccessToken`, `getTokens`, `refreshTokens`, `refreshIfExpiring`, `disconnect`.
+
+## 5 · Tokens: storing, refreshing, keeping alive
+
+Your app owns the tokens. The SDK never stores anything itself: it calls your `tokenStore`, and it refreshes through it.
+
+**What One issues**
+
+| | Lifetime | On refresh |
+|---|---|---|
+| Access token | The lifetime set on your app: 1 hour by default, or 7, 30, 90 or 365 days | Replaced |
+| Refresh token | 30 days | Replaced, with a fresh 30 days |
+
+Every refresh returns a **new pair** and retires the old refresh token. If the old refresh token is ever used again, One treats it as stolen and **revokes the whole grant**. The user then has to connect again.
+
+**Store them in your database, encrypted, keyed by your user id**
+
+```sql
+create table one_tokens (
+  user_id       text primary key,
+  access_token  text not null,          -- encrypted
+  refresh_token text not null,          -- encrypted
+  expires_at    timestamptz not null    -- tokens.expiresAt
+);
+```
+
+**Give the store a lock when more than one process can refresh**
+
+Serverless functions, several instances, a background worker: any two of them can decide to refresh the same user at the same moment.
+
+```
+without a lock                              with withLock
+web ──refresh(R1)──► One: here is R2         web ──lock──refresh(R1)──► R2 ──save──unlock
+worker ─refresh(R1)─► One: R1 reused!        worker ──wait─────────────────────────────┐
+                      revoke everything ✗                   reload: R2 is fresh, use it ✓
+```
+
+The SDK takes the lock around every refresh and around the save in the callback. It re-reads the store inside the lock, so the process that waited uses the pair the first one saved instead of spending the old refresh token again. The SDK never takes the lock twice for the same call. Postgres, with a transaction-scoped advisory lock:
+
+```ts
+withLock: async (userId, run) => {
+  const client = await pool.connect();
+  try {
+    await client.query("begin");
+    await client.query("select pg_advisory_xact_lock(hashtextextended($1, 0))", [`one-connect:${userId}`]);
+    return await run();
+  } finally {
+    await client.query("commit").catch(() => {});
+    client.release();
+  }
+},
+```
+
+A single long-running process can leave `withLock` out; the SDK already runs one refresh per user at a time inside a process. If your lock has a timeout, make it at least 60 seconds, because it spans one call to One.
+
+**Refreshing ahead of time**
+
+`getAccessToken`, `runAction`, `listConnections` and `fetch` refresh on their own when the access token has less than a minute left. For work that runs in the background, refresh ahead with `refreshIfExpiring`. It refreshes only when the access token **or** the refresh token expires within the window, and otherwise returns the stored pair without calling One.
+
+```ts
+// Every 10 minutes: users whose access token expires in the next 15 minutes
+// (your table knows expires_at).
+await oneConnect.refreshIfExpiring(userId, { withinMs: 15 * 60_000 });
+
+// Once a day, for every connected user: renews refresh tokens before their
+// 30 days run out, so a user who has not been active stays connected.
+await oneConnect.refreshIfExpiring(userId, { withinMs: 7 * 24 * 3_600_000 });
+```
+
+**When a refresh fails**
+
+| `OneConnectError.code` | What happened | Tokens | What to do |
+|---|---|---|---|
+| `refresh_failed` | One declared the grant dead: the user revoked it, the refresh token expired, or it was reused | Cleared | Show "Reconnect", which runs Connect again |
+| `request_failed` | One could not be reached, answered with a server error, or refused your client credentials | **Kept** | Retry later. Check `status` for a 401, which means your client secret is wrong. |
+| `not_connected` | No tokens are stored for this user | — | Show "Connect" |
+
+The SDK clears tokens only when One says the grant is dead (`invalid_grant`), or when the refresh token's own expiry has passed. It calls `clearTokens(userId, failed)` with the pair that failed. Just before that, it re-reads the store: if a newer pair has landed (the user reconnected while an old refresh was failing), it keeps and returns the newer pair. To make that check atomic, delete only when the stored refresh token is still `failed.refreshToken`. `disconnect(userId)` calls `clearTokens(userId)` without `failed`, and always deletes.
+
+**Asking for more tools later**
+
+Edit the app's permission set in the dashboard (Developers → Connect). The next time a user presses the button, One shows them the new tools as "{your app} needs one more connection", with what they already granted pre-selected. Authorizing replaces the user's grant and old tokens at once, and the callback saves the new pair.
 
 ## What your users see
 
@@ -243,7 +326,7 @@ In *your* dashboard the app lists every user who said yes, what each one granted
 
 - The client secret is used on your server only, for the code exchange and refresh, over HTTP Basic.
 - The authorization code is single use and expires ten minutes after consent.
-- Refresh tokens rotate on every use. Reusing an old one revokes the whole family, which is why the client serialises refreshes per user.
+- Refresh tokens rotate on every use. Reusing an old one revokes the whole family, which is why the client refreshes one user at a time: inside a process on its own, and across processes through `tokenStore.withLock`.
 - The browser half of this package never sees a token. It navigates and reads one query parameter.
 
 ## Development

package/dist/server/index.cjs.js

@@ -72,6 +72,18 @@ function tenancyHeaders(accessToken) {
   }
 }
 
+/** When a refresh token stops working, in epoch milliseconds, from its
+ *  `exp` claim. Null when the token carries no readable expiry, in which
+ *  case only One can say whether it still works. */
+function refreshTokenExpiresAt(refreshToken) {
+  try {
+    const payload = JSON.parse(Buffer.from(refreshToken.split(".")[1], "base64url").toString());
+    return typeof payload.exp === "number" && Number.isFinite(payload.exp) ? payload.exp * 1000 : null;
+  } catch {
+    return null;
+  }
+}
+
 /** The scopes the token was granted, from its claims. Display only. */
 function tokenScopes(accessToken) {
   try {
@@ -91,8 +103,8 @@ function tokenScopes(accessToken) {
 
 /**
  * Where the app keeps each user's tokens: its database, a cache, an
- * encrypted cookie. The SDK never sees a token outside these three
- * calls. `userId` is the app's own id for its user.
+ * encrypted cookie. The SDK never sees a token outside these calls.
+ * `userId` is the app's own id for its user.
  */
 
 /** The transaction cookie the authorize leg sets and the callback reads. */
@@ -101,6 +113,14 @@ function tokenScopes(accessToken) {
 
 /** One catalog action for a platform. */
 
+/**
+ * - `not_connected`: no tokens are stored for this user.
+ * - `refresh_failed`: One declared the grant dead (revoked, expired or
+ *   reused). The tokens were cleared; ask the user to connect again.
+ * - `request_failed`: One answered with an error or could not be
+ *   reached. During a refresh the tokens are kept, so retry later.
+ */
+
 class OneConnectError extends Error {
   constructor(code, message, status) {
     super(message);
@@ -128,12 +148,26 @@ class OneConnectError extends Error {
  *   const reply = await oneConnect.runAction(userId, { connectionKey, actionId, method, path });
  *
  * The Next.js and Node adapters turn the first two into route handlers.
+ *
+ * Refresh. One's access token lives an hour by default, its refresh token 30
+ * days; every refresh rotates both, and One treats a second use of a
+ * rotated refresh token as theft and revokes the whole grant. So the
+ * client refreshes one user at a time (in this process always, across
+ * processes through `tokenStore.withLock`), re-reads the store before
+ * spending a refresh token, clears tokens only when One declares the
+ * grant dead, and never lets a failing old pair delete a newer one.
  */
 
 /** Refresh this long before expiry, so a call never races the clock. */
 const REFRESH_MARGIN_MS = 60_000;
 const CATALOG_PAGE_SIZE = 100;
 const CATALOG_MAX_PAGES = 20;
+
+/** What One's token endpoint answered. A network failure throws instead. */
+
+/** The one refusal that means the grant is gone for good: revoked by the
+ *  user, expired, or burned by a reused refresh token (RFC 6749 §5.2). */
+const isDeadGrant = answer => !answer.ok && answer.status === 400 && answer.error === "invalid_grant";
 function createOneConnect(config) {
   const oneApiUrl = (config.oneApiUrl ?? DEFAULT_ONE_API_URL).replace(/\/+$/, "");
   const authorizeUrl = `${oneApiUrl}/oauth/authorize`;
@@ -154,7 +188,7 @@ function createOneConnect(config) {
     if (message) url.searchParams.set(RETURN_MESSAGE_PARAM, message);
     return url.toString();
   };
-  const exchange = async body => {
+  const postToken = async body => {
     const response = await fetch(tokenUrl, {
       method: "POST",
       headers: {
@@ -163,10 +197,40 @@ function createOneConnect(config) {
       },
       body
     });
-    if (!response.ok) {
-      throw new OneConnectError("request_failed", `One refused the token request (HTTP ${response.status}).`, response.status);
+    if (response.ok) return {
+      ok: true,
+      body: await response.json()
+    };
+    let error;
+    try {
+      const refusal = await response.json();
+      if (typeof refusal.error === "string") error = refusal.error;
+    } catch {
+      /* not an OAuth error body: a proxy page or a server error */
+    }
+    return {
+      ok: false,
+      status: response.status,
+      error
+    };
+  };
+  const exchange = async body => {
+    const answer = await postToken(body);
+    if (!answer.ok) {
+      throw new OneConnectError("request_failed", `One refused the token request (HTTP ${answer.status}).`, answer.status);
     }
-    return await response.json();
+    return answer.body;
+  };
+
+  /** Runs `run` under the app's cross-process lock for this user, when
+   *  the store has one. */
+  const locked = (userId, run) => tokenStore.withLock ? tokenStore.withLock(userId, run) : run();
+
+  /** Whether either token of the pair stops working within `withinMs`. */
+  const expiresWithin = (tokens, withinMs) => {
+    const horizon = Date.now() + withinMs;
+    const refreshExpiresAt = refreshTokenExpiresAt(tokens.refreshToken);
+    return tokens.expiresAt <= horizon || refreshExpiresAt !== null && refreshExpiresAt <= horizon;
   };
   const toTokens = response => ({
     accessToken: response.access_token,
@@ -216,7 +280,9 @@ function createOneConnect(config) {
         redirect_uri: config.redirectUri,
         code_verifier: verifier
       })));
-      await tokenStore.saveTokens(input.userId, tokens);
+      // Under the lock, so a refresh in flight on another server cannot
+      // interleave with this save.
+      await locked(input.userId, () => tokenStore.saveTokens(input.userId, tokens));
     } catch (error) {
       const status = error instanceof OneConnectError ? error.status : undefined;
       return fail("failed", status ? `One rejected the code exchange (HTTP ${status}).` : "One could not be reached to complete the connection.");
@@ -227,39 +293,81 @@ function createOneConnect(config) {
       clearCookieName: cookieName
     };
   };
-  const refreshTokens = userId => {
+  const notConnected = () => new OneConnectError("not_connected", "This user is not connected.");
+
+  /**
+   * The grant behind `failed` is dead. Clears it, unless a newer pair
+   * landed while it was failing (a reconnect's callback, another
+   * server's refresh): that pair is returned instead, because the user
+   * did nothing wrong and deleting it would disconnect them.
+   */
+  const retire = async (userId, failed, status) => {
+    const latest = await tokenStore.loadTokens(userId);
+    if (latest && latest.refreshToken !== failed.refreshToken) return latest;
+    await tokenStore.clearTokens(userId, failed);
+    throw new OneConnectError("refresh_failed", "The connection to One has expired or was revoked. Ask the user to connect again.", status);
+  };
+
+  /**
+   * The one place a refresh token is spent. Under the app's lock it
+   * re-reads the store, and refreshes only when `stillNeeded` says the
+   * stored pair still needs it: another process may have refreshed while
+   * this one waited, and spending the same refresh token twice makes One
+   * revoke the grant.
+   */
+  const refreshUnderLock = (userId, stillNeeded) => locked(userId, async () => {
+    const current = await tokenStore.loadTokens(userId);
+    if (!current) throw notConnected();
+    if (!stillNeeded(current)) return current;
+
+    // An expired refresh token cannot work, and One answers one with a
+    // server error rather than invalid_grant, so settle it here.
+    const refreshExpiresAt = refreshTokenExpiresAt(current.refreshToken);
+    if (refreshExpiresAt !== null && refreshExpiresAt <= Date.now()) return retire(userId, current);
+    let answer;
+    try {
+      answer = await postToken(new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: current.refreshToken
+      }));
+    } catch {
+      throw new OneConnectError("request_failed", "One could not be reached to refresh the connection. The tokens were kept; try again.");
+    }
+    if (answer.ok) {
+      // Both tokens: One rotates the pair on every refresh.
+      const next = toTokens(answer.body);
+      await tokenStore.saveTokens(userId, next);
+      return next;
+    }
+    if (isDeadGrant(answer)) return retire(userId, current, answer.status);
+    // A server error, a rate limit, a misconfigured secret: nothing says
+    // the grant is gone, so keep the tokens and let the caller retry.
+    throw new OneConnectError("request_failed", `One could not refresh the connection (HTTP ${answer.status}). The tokens were kept; try again.`, answer.status);
+  });
+
+  /** One refresh per user in this process; concurrent callers share it. */
+  const singleFlight = (userId, job) => {
     const inFlight = refreshing.get(userId);
     if (inFlight) return inFlight;
-    const job = (async () => {
-      const current = await tokenStore.loadTokens(userId);
-      if (!current) throw new OneConnectError("not_connected", "This user is not connected.");
-      try {
-        const next = toTokens(await exchange(new URLSearchParams({
-          grant_type: "refresh_token",
-          refresh_token: current.refreshToken
-        })));
-        // Both tokens: One rotates the pair on every refresh.
-        await tokenStore.saveTokens(userId, next);
-        return next;
-      } catch (error) {
-        // The family is dead: revoked, expired or reused. Keeping the
-        // pair would only fail again; the user has to reconnect.
-        await tokenStore.clearTokens(userId);
-        const status = error instanceof OneConnectError ? error.status : undefined;
-        throw new OneConnectError("refresh_failed", "The connection to One has expired or was revoked. Ask the user to connect again.", status);
-      } finally {
-        refreshing.delete(userId);
-      }
-    })();
-    refreshing.set(userId, job);
-    return job;
+    const running = job().finally(() => refreshing.delete(userId));
+    refreshing.set(userId, running);
+    return running;
   };
-  const getAccessToken = async userId => {
+  const refreshTokens = userId => singleFlight(userId, async () => {
+    const before = await tokenStore.loadTokens(userId);
+    if (!before) throw notConnected();
+    // Rotate the pair seen now; a pair someone else rotated since is
+    // already fresh.
+    return refreshUnderLock(userId, current => current.refreshToken === before.refreshToken);
+  });
+  const refreshIfExpiring = async (userId, options = {}) => {
+    const withinMs = options.withinMs ?? REFRESH_MARGIN_MS;
     const tokens = await tokenStore.loadTokens(userId);
-    if (!tokens) throw new OneConnectError("not_connected", "This user is not connected.");
-    if (Date.now() < tokens.expiresAt - REFRESH_MARGIN_MS) return tokens.accessToken;
-    return (await refreshTokens(userId)).accessToken;
+    if (!tokens) throw notConnected();
+    if (!expiresWithin(tokens, withinMs)) return tokens;
+    return singleFlight(userId, () => refreshUnderLock(userId, current => expiresWithin(current, withinMs)));
   };
+  const getAccessToken = async userId => (await refreshIfExpiring(userId)).accessToken;
   const oneFetch = async (userId, path, init = {}) => {
     const accessToken = await getAccessToken(userId);
     const headers = new Headers(init.headers);
@@ -335,6 +443,7 @@ function createOneConnect(config) {
     getAccessToken,
     getTokens: userId => tokenStore.loadTokens(userId),
     refreshTokens,
+    refreshIfExpiring,
     disconnect: userId => tokenStore.clearTokens(userId),
     listConnections,
     listActions,
@@ -345,5 +454,6 @@ function createOneConnect(config) {
 
 exports.OneConnectError = OneConnectError;
 exports.createOneConnect = createOneConnect;
+exports.refreshTokenExpiresAt = refreshTokenExpiresAt;
 exports.tenancyHeaders = tenancyHeaders;
 exports.tokenScopes = tokenScopes;

package/dist/server/index.d.ts

@@ -1,6 +1,6 @@
-import { type CompleteAuthorizationInput, type CompleteAuthorizationResult, type OneConnectServerConfig, type OneConnectTokens, type PlatformAction, type ReachableConnection, type RunActionInput, type RunActionResult, type StartAuthorizationInput, type StartAuthorizationResult } from "./types";
+import { type CompleteAuthorizationInput, type CompleteAuthorizationResult, type OneConnectServerConfig, type OneConnectTokens, type PlatformAction, type ReachableConnection, type RefreshIfExpiringOptions, type RunActionInput, type RunActionResult, type StartAuthorizationInput, type StartAuthorizationResult } from "./types";
 export * from "./types";
-export { tenancyHeaders, tokenScopes } from "./oauth";
+export { refreshTokenExpiresAt, tenancyHeaders, tokenScopes } from "./oauth";
 export interface OneConnect {
     /** The authorize leg: where to send the browser and the cookie to set. */
     startAuthorization: (input?: StartAuthorizationInput) => StartAuthorizationResult;
@@ -14,8 +14,16 @@ export interface OneConnect {
     getAccessToken: (userId: string) => Promise<string>;
     /** The stored tokens, for display. Null when not connected. */
     getTokens: (userId: string) => Promise<OneConnectTokens | null>;
-    /** Forces a refresh now. */
+    /** Refreshes now and returns the new pair. When another caller rotated
+     *  the pair a moment earlier, returns that pair instead of rotating it
+     *  a second time. */
     refreshTokens: (userId: string) => Promise<OneConnectTokens>;
+    /** Refreshes only when the access token or the refresh token expires
+     *  within `withinMs`, and returns the pair that is current afterwards.
+     *  For background jobs: a frequent run keeps access tokens warm, and a
+     *  daily run with a window of days keeps idle users' 30-day refresh
+     *  tokens from running out. */
+    refreshIfExpiring: (userId: string, options?: RefreshIfExpiringOptions) => Promise<OneConnectTokens>;
     /** Drops the app's copy of the tokens. The user revokes the grant
      *  itself from their One dashboard. */
     disconnect: (userId: string) => Promise<void>;

package/dist/server/index.esm.js

@@ -70,6 +70,18 @@ function tenancyHeaders(accessToken) {
   }
 }
 
+/** When a refresh token stops working, in epoch milliseconds, from its
+ *  `exp` claim. Null when the token carries no readable expiry, in which
+ *  case only One can say whether it still works. */
+function refreshTokenExpiresAt(refreshToken) {
+  try {
+    const payload = JSON.parse(Buffer.from(refreshToken.split(".")[1], "base64url").toString());
+    return typeof payload.exp === "number" && Number.isFinite(payload.exp) ? payload.exp * 1000 : null;
+  } catch {
+    return null;
+  }
+}
+
 /** The scopes the token was granted, from its claims. Display only. */
 function tokenScopes(accessToken) {
   try {
@@ -89,8 +101,8 @@ function tokenScopes(accessToken) {
 
 /**
  * Where the app keeps each user's tokens: its database, a cache, an
- * encrypted cookie. The SDK never sees a token outside these three
- * calls. `userId` is the app's own id for its user.
+ * encrypted cookie. The SDK never sees a token outside these calls.
+ * `userId` is the app's own id for its user.
  */
 
 /** The transaction cookie the authorize leg sets and the callback reads. */
@@ -99,6 +111,14 @@ function tokenScopes(accessToken) {
 
 /** One catalog action for a platform. */
 
+/**
+ * - `not_connected`: no tokens are stored for this user.
+ * - `refresh_failed`: One declared the grant dead (revoked, expired or
+ *   reused). The tokens were cleared; ask the user to connect again.
+ * - `request_failed`: One answered with an error or could not be
+ *   reached. During a refresh the tokens are kept, so retry later.
+ */
+
 class OneConnectError extends Error {
   constructor(code, message, status) {
     super(message);
@@ -126,12 +146,26 @@ class OneConnectError extends Error {
  *   const reply = await oneConnect.runAction(userId, { connectionKey, actionId, method, path });
  *
  * The Next.js and Node adapters turn the first two into route handlers.
+ *
+ * Refresh. One's access token lives an hour by default, its refresh token 30
+ * days; every refresh rotates both, and One treats a second use of a
+ * rotated refresh token as theft and revokes the whole grant. So the
+ * client refreshes one user at a time (in this process always, across
+ * processes through `tokenStore.withLock`), re-reads the store before
+ * spending a refresh token, clears tokens only when One declares the
+ * grant dead, and never lets a failing old pair delete a newer one.
  */
 
 /** Refresh this long before expiry, so a call never races the clock. */
 const REFRESH_MARGIN_MS = 60_000;
 const CATALOG_PAGE_SIZE = 100;
 const CATALOG_MAX_PAGES = 20;
+
+/** What One's token endpoint answered. A network failure throws instead. */
+
+/** The one refusal that means the grant is gone for good: revoked by the
+ *  user, expired, or burned by a reused refresh token (RFC 6749 §5.2). */
+const isDeadGrant = answer => !answer.ok && answer.status === 400 && answer.error === "invalid_grant";
 function createOneConnect(config) {
   const oneApiUrl = (config.oneApiUrl ?? DEFAULT_ONE_API_URL).replace(/\/+$/, "");
   const authorizeUrl = `${oneApiUrl}/oauth/authorize`;
@@ -152,7 +186,7 @@ function createOneConnect(config) {
     if (message) url.searchParams.set(RETURN_MESSAGE_PARAM, message);
     return url.toString();
   };
-  const exchange = async body => {
+  const postToken = async body => {
     const response = await fetch(tokenUrl, {
       method: "POST",
       headers: {
@@ -161,10 +195,40 @@ function createOneConnect(config) {
       },
       body
     });
-    if (!response.ok) {
-      throw new OneConnectError("request_failed", `One refused the token request (HTTP ${response.status}).`, response.status);
+    if (response.ok) return {
+      ok: true,
+      body: await response.json()
+    };
+    let error;
+    try {
+      const refusal = await response.json();
+      if (typeof refusal.error === "string") error = refusal.error;
+    } catch {
+      /* not an OAuth error body: a proxy page or a server error */
+    }
+    return {
+      ok: false,
+      status: response.status,
+      error
+    };
+  };
+  const exchange = async body => {
+    const answer = await postToken(body);
+    if (!answer.ok) {
+      throw new OneConnectError("request_failed", `One refused the token request (HTTP ${answer.status}).`, answer.status);
     }
-    return await response.json();
+    return answer.body;
+  };
+
+  /** Runs `run` under the app's cross-process lock for this user, when
+   *  the store has one. */
+  const locked = (userId, run) => tokenStore.withLock ? tokenStore.withLock(userId, run) : run();
+
+  /** Whether either token of the pair stops working within `withinMs`. */
+  const expiresWithin = (tokens, withinMs) => {
+    const horizon = Date.now() + withinMs;
+    const refreshExpiresAt = refreshTokenExpiresAt(tokens.refreshToken);
+    return tokens.expiresAt <= horizon || refreshExpiresAt !== null && refreshExpiresAt <= horizon;
   };
   const toTokens = response => ({
     accessToken: response.access_token,
@@ -214,7 +278,9 @@ function createOneConnect(config) {
         redirect_uri: config.redirectUri,
         code_verifier: verifier
       })));
-      await tokenStore.saveTokens(input.userId, tokens);
+      // Under the lock, so a refresh in flight on another server cannot
+      // interleave with this save.
+      await locked(input.userId, () => tokenStore.saveTokens(input.userId, tokens));
     } catch (error) {
       const status = error instanceof OneConnectError ? error.status : undefined;
       return fail("failed", status ? `One rejected the code exchange (HTTP ${status}).` : "One could not be reached to complete the connection.");
@@ -225,39 +291,81 @@ function createOneConnect(config) {
       clearCookieName: cookieName
     };
   };
-  const refreshTokens = userId => {
+  const notConnected = () => new OneConnectError("not_connected", "This user is not connected.");
+
+  /**
+   * The grant behind `failed` is dead. Clears it, unless a newer pair
+   * landed while it was failing (a reconnect's callback, another
+   * server's refresh): that pair is returned instead, because the user
+   * did nothing wrong and deleting it would disconnect them.
+   */
+  const retire = async (userId, failed, status) => {
+    const latest = await tokenStore.loadTokens(userId);
+    if (latest && latest.refreshToken !== failed.refreshToken) return latest;
+    await tokenStore.clearTokens(userId, failed);
+    throw new OneConnectError("refresh_failed", "The connection to One has expired or was revoked. Ask the user to connect again.", status);
+  };
+
+  /**
+   * The one place a refresh token is spent. Under the app's lock it
+   * re-reads the store, and refreshes only when `stillNeeded` says the
+   * stored pair still needs it: another process may have refreshed while
+   * this one waited, and spending the same refresh token twice makes One
+   * revoke the grant.
+   */
+  const refreshUnderLock = (userId, stillNeeded) => locked(userId, async () => {
+    const current = await tokenStore.loadTokens(userId);
+    if (!current) throw notConnected();
+    if (!stillNeeded(current)) return current;
+
+    // An expired refresh token cannot work, and One answers one with a
+    // server error rather than invalid_grant, so settle it here.
+    const refreshExpiresAt = refreshTokenExpiresAt(current.refreshToken);
+    if (refreshExpiresAt !== null && refreshExpiresAt <= Date.now()) return retire(userId, current);
+    let answer;
+    try {
+      answer = await postToken(new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: current.refreshToken
+      }));
+    } catch {
+      throw new OneConnectError("request_failed", "One could not be reached to refresh the connection. The tokens were kept; try again.");
+    }
+    if (answer.ok) {
+      // Both tokens: One rotates the pair on every refresh.
+      const next = toTokens(answer.body);
+      await tokenStore.saveTokens(userId, next);
+      return next;
+    }
+    if (isDeadGrant(answer)) return retire(userId, current, answer.status);
+    // A server error, a rate limit, a misconfigured secret: nothing says
+    // the grant is gone, so keep the tokens and let the caller retry.
+    throw new OneConnectError("request_failed", `One could not refresh the connection (HTTP ${answer.status}). The tokens were kept; try again.`, answer.status);
+  });
+
+  /** One refresh per user in this process; concurrent callers share it. */
+  const singleFlight = (userId, job) => {
     const inFlight = refreshing.get(userId);
     if (inFlight) return inFlight;
-    const job = (async () => {
-      const current = await tokenStore.loadTokens(userId);
-      if (!current) throw new OneConnectError("not_connected", "This user is not connected.");
-      try {
-        const next = toTokens(await exchange(new URLSearchParams({
-          grant_type: "refresh_token",
-          refresh_token: current.refreshToken
-        })));
-        // Both tokens: One rotates the pair on every refresh.
-        await tokenStore.saveTokens(userId, next);
-        return next;
-      } catch (error) {
-        // The family is dead: revoked, expired or reused. Keeping the
-        // pair would only fail again; the user has to reconnect.
-        await tokenStore.clearTokens(userId);
-        const status = error instanceof OneConnectError ? error.status : undefined;
-        throw new OneConnectError("refresh_failed", "The connection to One has expired or was revoked. Ask the user to connect again.", status);
-      } finally {
-        refreshing.delete(userId);
-      }
-    })();
-    refreshing.set(userId, job);
-    return job;
+    const running = job().finally(() => refreshing.delete(userId));
+    refreshing.set(userId, running);
+    return running;
   };
-  const getAccessToken = async userId => {
+  const refreshTokens = userId => singleFlight(userId, async () => {
+    const before = await tokenStore.loadTokens(userId);
+    if (!before) throw notConnected();
+    // Rotate the pair seen now; a pair someone else rotated since is
+    // already fresh.
+    return refreshUnderLock(userId, current => current.refreshToken === before.refreshToken);
+  });
+  const refreshIfExpiring = async (userId, options = {}) => {
+    const withinMs = options.withinMs ?? REFRESH_MARGIN_MS;
     const tokens = await tokenStore.loadTokens(userId);
-    if (!tokens) throw new OneConnectError("not_connected", "This user is not connected.");
-    if (Date.now() < tokens.expiresAt - REFRESH_MARGIN_MS) return tokens.accessToken;
-    return (await refreshTokens(userId)).accessToken;
+    if (!tokens) throw notConnected();
+    if (!expiresWithin(tokens, withinMs)) return tokens;
+    return singleFlight(userId, () => refreshUnderLock(userId, current => expiresWithin(current, withinMs)));
   };
+  const getAccessToken = async userId => (await refreshIfExpiring(userId)).accessToken;
   const oneFetch = async (userId, path, init = {}) => {
     const accessToken = await getAccessToken(userId);
     const headers = new Headers(init.headers);
@@ -333,6 +441,7 @@ function createOneConnect(config) {
     getAccessToken,
     getTokens: userId => tokenStore.loadTokens(userId),
     refreshTokens,
+    refreshIfExpiring,
     disconnect: userId => tokenStore.clearTokens(userId),
     listConnections,
     listActions,
@@ -341,4 +450,4 @@ function createOneConnect(config) {
   };
 }
 
-export { OneConnectError, createOneConnect, tenancyHeaders, tokenScopes };
+export { OneConnectError, createOneConnect, refreshTokenExpiresAt, tenancyHeaders, tokenScopes };

package/dist/server/oauth.d.ts

@@ -20,5 +20,9 @@ export declare function basicAuthorization(clientId: string, clientSecret: strin
  *  these headers, and without them the call runs in the user's personal
  *  space. The access token's claims name the tenant, so echo them. */
 export declare function tenancyHeaders(accessToken: string): Record<string, string>;
+/** When a refresh token stops working, in epoch milliseconds, from its
+ *  `exp` claim. Null when the token carries no readable expiry, in which
+ *  case only One can say whether it still works. */
+export declare function refreshTokenExpiresAt(refreshToken: string): number | null;
 /** The scopes the token was granted, from its claims. Display only. */
 export declare function tokenScopes(accessToken: string): string[];

package/dist/server/types.d.ts

@@ -11,13 +11,44 @@ export interface OneConnectTokens {
 }
 /**
  * Where the app keeps each user's tokens: its database, a cache, an
- * encrypted cookie. The SDK never sees a token outside these three
- * calls. `userId` is the app's own id for its user.
+ * encrypted cookie. The SDK never sees a token outside these calls.
+ * `userId` is the app's own id for its user.
  */
 export interface OneConnectTokenStore {
     saveTokens: (userId: string, tokens: OneConnectTokens) => Promise<void>;
     loadTokens: (userId: string) => Promise<OneConnectTokens | null>;
-    clearTokens: (userId: string) => Promise<void>;
+    /**
+     * Deletes the user's tokens.
+     *
+     * `failed` is set when the SDK clears because One declared that pair
+     * dead. Delete only when the stored refresh token is still
+     * `failed.refreshToken`: a newer pair saved in the meantime (a
+     * reconnect, another server's refresh) must survive. `failed` is
+     * undefined for `disconnect`, which always deletes.
+     */
+    clearTokens: (userId: string, failed?: OneConnectTokens) => Promise<void>;
+    /**
+     * Runs `run` while holding a lock on this user that every server and
+     * worker of the app shares: a Postgres advisory lock, a Redis lock, a
+     * row lock. The SDK loads, refreshes and saves the user's tokens
+     * inside it.
+     *
+     * Required when the app runs more than one process (serverless,
+     * several instances, a background worker). One rotates the refresh
+     * token on every use and treats a second use of the old one as theft,
+     * revoking the whole grant, so two processes refreshing the same user
+     * at once disconnect that user. Without a lock the SDK can only stop
+     * that inside a single process.
+     *
+     * Hold it for at least 60 seconds before any timeout: it spans one
+     * call to One's token endpoint.
+     */
+    withLock?: <T>(userId: string, run: () => Promise<T>) => Promise<T>;
+}
+export interface RefreshIfExpiringOptions {
+    /** Refresh when the access token or the refresh token expires within
+     *  this many milliseconds. One minute when omitted. */
+    withinMs?: number;
 }
 export interface OneConnectServerConfig {
     /** The app's client id from the dashboard. */
@@ -128,6 +159,13 @@ export interface RunActionResult {
     blockedByGrant: boolean;
     data: unknown;
 }
+/**
+ * - `not_connected`: no tokens are stored for this user.
+ * - `refresh_failed`: One declared the grant dead (revoked, expired or
+ *   reused). The tokens were cleared; ask the user to connect again.
+ * - `request_failed`: One answered with an error or could not be
+ *   reached. During a refresh the tokens are kept, so retry later.
+ */
 export type OneConnectErrorCode = "not_connected" | "refresh_failed" | "request_failed";
 export declare class OneConnectError extends Error {
     readonly code: OneConnectErrorCode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/connect",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "One Connect for your app: the button your users press, the two backend routes as one import, and a server client that calls One with the grant. Users keep their connections in One; your app holds only what they granted.",
   "files": [
     "dist",

package/skills/one-connect/SKILL.md

@@ -72,7 +72,9 @@ export const oneConnect = createOneConnect({
   tokenStore: {
     saveTokens: (userId, tokens) => /* write to this app's database, encrypted, keyed by its user */,
     loadTokens: (userId) => /* read; null when the user never connected */,
-    clearTokens: (userId) => /* delete */,
+    clearTokens: (userId, failed) => /* delete; when `failed` is set, only if the stored refreshToken is still failed.refreshToken */,
+    // Required when the app runs more than one process (serverless, several instances, a worker):
+    withLock: (userId, run) => /* run() while holding a per-user lock all processes share, e.g. pg_advisory_xact_lock */,
   },
 });
 ```
@@ -81,6 +83,14 @@ export const oneConnect = createOneConnect({
 id as the key. Implement the store on whatever the app already uses; do not
 add a database for it.
 
+One rotates the refresh token on every refresh and revokes the whole grant if
+an old one is used again. So when two processes could refresh the same user,
+`withLock` is not optional: without it, a web request and a worker refreshing
+together disconnect the user. The README's "Tokens" section has a Postgres
+version. For background work, call `refreshIfExpiring(userId, { withinMs })`:
+every few minutes with a window of minutes to keep access tokens warm, and
+once a day with a window of days so idle users' 30-day refresh tokens renew.
+
 ## 4 - The two routes
 
 Next.js App Router (also Remix, SvelteKit, Hono, Bun: anything with the web `Request`):
@@ -170,14 +180,22 @@ grant; the provider was never called. Do not retry. Any other `/v1` call:
 `oneConnect.fetch(userId, "/connections", init)`.
 
 `OneConnectError` codes: `not_connected` (no tokens stored), `refresh_failed`
-(One refused the refresh; the tokens were cleared; ask the user to connect
-again), `request_failed` (One answered with an error; `status` carries it).
+(One declared the grant dead: revoked, expired or reused; the tokens were
+cleared; ask the user to connect again), `request_failed` (One answered with
+an error or could not be reached; `status` carries it; during a refresh the
+tokens are KEPT, so retry later rather than asking the user to reconnect).
+
+To ask users for more tools later, edit the app's permission set in the
+dashboard. The next Connect shows only the new tools as "needs one more
+connection" and the callback stores the new pair; no code change.
 
 ## 7 - Rules
 
 - Never put the secret in a client bundle, a log line or an error report.
 - Store tokens encrypted, keyed by the app's user. Delete them when the user
-  is deleted. The client deletes them itself when a refresh fails.
+  is deleted. The client deletes them itself only when One declares the
+  grant dead, and never deletes a newer pair saved in the meantime.
+- Give the store `withLock` whenever more than one process can refresh.
 - The registered redirect URI and `ONE_REDIRECT_URI` must be the same string.
 - Do not build a completion page. The callback redirect is the completion.
 - Do not write the OAuth steps by hand when the package exposes them.

package/src/server/index.ts

@@ -16,6 +16,14 @@
  *   const reply = await oneConnect.runAction(userId, { connectionKey, actionId, method, path });
  *
  * The Next.js and Node adapters turn the first two into route handlers.
+ *
+ * Refresh. One's access token lives an hour by default, its refresh token 30
+ * days; every refresh rotates both, and One treats a second use of a
+ * rotated refresh token as theft and revokes the whole grant. So the
+ * client refreshes one user at a time (in this process always, across
+ * processes through `tokenStore.withLock`), re-reads the store before
+ * spending a refresh token, clears tokens only when One declares the
+ * grant dead, and never lets a failing old pair delete a newer one.
  */
 import { DEFAULT_ONE_API_URL, RETURN_MESSAGE_PARAM, RETURN_STATUS_PARAM } from "../constants";
 import {
@@ -24,6 +32,7 @@ import {
   createPkceVerifier,
   createState,
   pkceChallenge,
+  refreshTokenExpiresAt,
   tenancyHeaders,
   txCookie,
   txCookieName,
@@ -36,6 +45,7 @@ import {
   type OneConnectTokens,
   type PlatformAction,
   type ReachableConnection,
+  type RefreshIfExpiringOptions,
   type RunActionInput,
   type RunActionResult,
   type StartAuthorizationInput,
@@ -43,7 +53,7 @@ import {
 } from "./types";
 
 export * from "./types";
-export { tenancyHeaders, tokenScopes } from "./oauth";
+export { refreshTokenExpiresAt, tenancyHeaders, tokenScopes } from "./oauth";
 
 /** Refresh this long before expiry, so a call never races the clock. */
 const REFRESH_MARGIN_MS = 60_000;
@@ -56,6 +66,16 @@ interface TokenResponse {
   expires_in: number;
 }
 
+/** What One's token endpoint answered. A network failure throws instead. */
+type TokenAnswer =
+  | { ok: true; body: TokenResponse }
+  | { ok: false; status: number; error?: string };
+
+/** The one refusal that means the grant is gone for good: revoked by the
+ *  user, expired, or burned by a reused refresh token (RFC 6749 §5.2). */
+const isDeadGrant = (answer: TokenAnswer): boolean =>
+  !answer.ok && answer.status === 400 && answer.error === "invalid_grant";
+
 export interface OneConnect {
   /** The authorize leg: where to send the browser and the cookie to set. */
   startAuthorization: (
@@ -73,8 +93,19 @@ export interface OneConnect {
   getAccessToken: (userId: string) => Promise<string>;
   /** The stored tokens, for display. Null when not connected. */
   getTokens: (userId: string) => Promise<OneConnectTokens | null>;
-  /** Forces a refresh now. */
+  /** Refreshes now and returns the new pair. When another caller rotated
+   *  the pair a moment earlier, returns that pair instead of rotating it
+   *  a second time. */
   refreshTokens: (userId: string) => Promise<OneConnectTokens>;
+  /** Refreshes only when the access token or the refresh token expires
+   *  within `withinMs`, and returns the pair that is current afterwards.
+   *  For background jobs: a frequent run keeps access tokens warm, and a
+   *  daily run with a window of days keeps idle users' 30-day refresh
+   *  tokens from running out. */
+  refreshIfExpiring: (
+    userId: string,
+    options?: RefreshIfExpiringOptions,
+  ) => Promise<OneConnectTokens>;
   /** Drops the app's copy of the tokens. The user revokes the grant
    *  itself from their One dashboard. */
   disconnect: (userId: string) => Promise<void>;
@@ -113,7 +144,7 @@ export function createOneConnect(config: OneConnectServerConfig): OneConnect {
     return url.toString();
   };
 
-  const exchange = async (body: URLSearchParams): Promise<TokenResponse> => {
+  const postToken = async (body: URLSearchParams): Promise<TokenAnswer> => {
     const response = await fetch(tokenUrl, {
       method: "POST",
       headers: {
@@ -122,14 +153,43 @@ export function createOneConnect(config: OneConnectServerConfig): OneConnect {
       },
       body,
     });
-    if (!response.ok) {
+    if (response.ok)
+      return { ok: true, body: (await response.json()) as TokenResponse };
+    let error: string | undefined;
+    try {
+      const refusal = (await response.json()) as { error?: unknown };
+      if (typeof refusal.error === "string") error = refusal.error;
+    } catch {
+      /* not an OAuth error body: a proxy page or a server error */
+    }
+    return { ok: false, status: response.status, error };
+  };
+
+  const exchange = async (body: URLSearchParams): Promise<TokenResponse> => {
+    const answer = await postToken(body);
+    if (!answer.ok) {
       throw new OneConnectError(
         "request_failed",
-        `One refused the token request (HTTP ${response.status}).`,
-        response.status,
+        `One refused the token request (HTTP ${answer.status}).`,
+        answer.status,
       );
     }
-    return (await response.json()) as TokenResponse;
+    return answer.body;
+  };
+
+  /** Runs `run` under the app's cross-process lock for this user, when
+   *  the store has one. */
+  const locked = <T>(userId: string, run: () => Promise<T>): Promise<T> =>
+    tokenStore.withLock ? tokenStore.withLock(userId, run) : run();
+
+  /** Whether either token of the pair stops working within `withinMs`. */
+  const expiresWithin = (tokens: OneConnectTokens, withinMs: number): boolean => {
+    const horizon = Date.now() + withinMs;
+    const refreshExpiresAt = refreshTokenExpiresAt(tokens.refreshToken);
+    return (
+      tokens.expiresAt <= horizon ||
+      (refreshExpiresAt !== null && refreshExpiresAt <= horizon)
+    );
   };
 
   const toTokens = (response: TokenResponse): OneConnectTokens => ({
@@ -200,7 +260,9 @@ export function createOneConnect(config: OneConnectServerConfig): OneConnect {
           }),
         ),
       );
-      await tokenStore.saveTokens(input.userId, tokens);
+      // Under the lock, so a refresh in flight on another server cannot
+      // interleave with this save.
+      await locked(input.userId, () => tokenStore.saveTokens(input.userId, tokens));
     } catch (error) {
       const status = error instanceof OneConnectError ? error.status : undefined;
       return fail(
@@ -218,51 +280,123 @@ export function createOneConnect(config: OneConnectServerConfig): OneConnect {
     };
   };
 
-  const refreshTokens = (userId: string): Promise<OneConnectTokens> => {
-    const inFlight = refreshing.get(userId);
-    if (inFlight) return inFlight;
-    const job = (async () => {
+  const notConnected = () =>
+    new OneConnectError("not_connected", "This user is not connected.");
+
+  /**
+   * The grant behind `failed` is dead. Clears it, unless a newer pair
+   * landed while it was failing (a reconnect's callback, another
+   * server's refresh): that pair is returned instead, because the user
+   * did nothing wrong and deleting it would disconnect them.
+   */
+  const retire = async (
+    userId: string,
+    failed: OneConnectTokens,
+    status?: number,
+  ): Promise<OneConnectTokens> => {
+    const latest = await tokenStore.loadTokens(userId);
+    if (latest && latest.refreshToken !== failed.refreshToken) return latest;
+    await tokenStore.clearTokens(userId, failed);
+    throw new OneConnectError(
+      "refresh_failed",
+      "The connection to One has expired or was revoked. Ask the user to connect again.",
+      status,
+    );
+  };
+
+  /**
+   * The one place a refresh token is spent. Under the app's lock it
+   * re-reads the store, and refreshes only when `stillNeeded` says the
+   * stored pair still needs it: another process may have refreshed while
+   * this one waited, and spending the same refresh token twice makes One
+   * revoke the grant.
+   */
+  const refreshUnderLock = (
+    userId: string,
+    stillNeeded: (current: OneConnectTokens) => boolean,
+  ): Promise<OneConnectTokens> =>
+    locked(userId, async () => {
       const current = await tokenStore.loadTokens(userId);
-      if (!current)
-        throw new OneConnectError("not_connected", "This user is not connected.");
+      if (!current) throw notConnected();
+      if (!stillNeeded(current)) return current;
+
+      // An expired refresh token cannot work, and One answers one with a
+      // server error rather than invalid_grant, so settle it here.
+      const refreshExpiresAt = refreshTokenExpiresAt(current.refreshToken);
+      if (refreshExpiresAt !== null && refreshExpiresAt <= Date.now())
+        return retire(userId, current);
+
+      let answer: TokenAnswer;
       try {
-        const next = toTokens(
-          await exchange(
-            new URLSearchParams({
-              grant_type: "refresh_token",
-              refresh_token: current.refreshToken,
-            }),
-          ),
+        answer = await postToken(
+          new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: current.refreshToken,
+          }),
+        );
+      } catch {
+        throw new OneConnectError(
+          "request_failed",
+          "One could not be reached to refresh the connection. The tokens were kept; try again.",
         );
+      }
+
+      if (answer.ok) {
         // Both tokens: One rotates the pair on every refresh.
+        const next = toTokens(answer.body);
         await tokenStore.saveTokens(userId, next);
         return next;
-      } catch (error) {
-        // The family is dead: revoked, expired or reused. Keeping the
-        // pair would only fail again; the user has to reconnect.
-        await tokenStore.clearTokens(userId);
-        const status = error instanceof OneConnectError ? error.status : undefined;
-        throw new OneConnectError(
-          "refresh_failed",
-          "The connection to One has expired or was revoked. Ask the user to connect again.",
-          status,
-        );
-      } finally {
-        refreshing.delete(userId);
       }
-    })();
-    refreshing.set(userId, job);
-    return job;
+      if (isDeadGrant(answer)) return retire(userId, current, answer.status);
+      // A server error, a rate limit, a misconfigured secret: nothing says
+      // the grant is gone, so keep the tokens and let the caller retry.
+      throw new OneConnectError(
+        "request_failed",
+        `One could not refresh the connection (HTTP ${answer.status}). The tokens were kept; try again.`,
+        answer.status,
+      );
+    });
+
+  /** One refresh per user in this process; concurrent callers share it. */
+  const singleFlight = (
+    userId: string,
+    job: () => Promise<OneConnectTokens>,
+  ): Promise<OneConnectTokens> => {
+    const inFlight = refreshing.get(userId);
+    if (inFlight) return inFlight;
+    const running = job().finally(() => refreshing.delete(userId));
+    refreshing.set(userId, running);
+    return running;
   };
 
-  const getAccessToken = async (userId: string): Promise<string> => {
+  const refreshTokens = (userId: string): Promise<OneConnectTokens> =>
+    singleFlight(userId, async () => {
+      const before = await tokenStore.loadTokens(userId);
+      if (!before) throw notConnected();
+      // Rotate the pair seen now; a pair someone else rotated since is
+      // already fresh.
+      return refreshUnderLock(
+        userId,
+        (current) => current.refreshToken === before.refreshToken,
+      );
+    });
+
+  const refreshIfExpiring = async (
+    userId: string,
+    options: RefreshIfExpiringOptions = {},
+  ): Promise<OneConnectTokens> => {
+    const withinMs = options.withinMs ?? REFRESH_MARGIN_MS;
     const tokens = await tokenStore.loadTokens(userId);
-    if (!tokens)
-      throw new OneConnectError("not_connected", "This user is not connected.");
-    if (Date.now() < tokens.expiresAt - REFRESH_MARGIN_MS) return tokens.accessToken;
-    return (await refreshTokens(userId)).accessToken;
+    if (!tokens) throw notConnected();
+    if (!expiresWithin(tokens, withinMs)) return tokens;
+    return singleFlight(userId, () =>
+      refreshUnderLock(userId, (current) => expiresWithin(current, withinMs)),
+    );
   };
 
+  const getAccessToken = async (userId: string): Promise<string> =>
+    (await refreshIfExpiring(userId)).accessToken;
+
   const oneFetch = async (
     userId: string,
     path: string,
@@ -373,6 +507,7 @@ export function createOneConnect(config: OneConnectServerConfig): OneConnect {
     getAccessToken,
     getTokens: (userId) => tokenStore.loadTokens(userId),
     refreshTokens,
+    refreshIfExpiring,
     disconnect: (userId) => tokenStore.clearTokens(userId),
     listConnections,
     listActions,

package/src/server/oauth.ts

@@ -85,6 +85,22 @@ export function tenancyHeaders(accessToken: string): Record<string, string> {
   }
 }
 
+/** When a refresh token stops working, in epoch milliseconds, from its
+ *  `exp` claim. Null when the token carries no readable expiry, in which
+ *  case only One can say whether it still works. */
+export function refreshTokenExpiresAt(refreshToken: string): number | null {
+  try {
+    const payload = JSON.parse(
+      Buffer.from(refreshToken.split(".")[1], "base64url").toString(),
+    ) as { exp?: unknown };
+    return typeof payload.exp === "number" && Number.isFinite(payload.exp)
+      ? payload.exp * 1000
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 /** The scopes the token was granted, from its claims. Display only. */
 export function tokenScopes(accessToken: string): string[] {
   try {

package/src/server/types.ts

@@ -13,13 +13,45 @@ export interface OneConnectTokens {
 
 /**
  * Where the app keeps each user's tokens: its database, a cache, an
- * encrypted cookie. The SDK never sees a token outside these three
- * calls. `userId` is the app's own id for its user.
+ * encrypted cookie. The SDK never sees a token outside these calls.
+ * `userId` is the app's own id for its user.
  */
 export interface OneConnectTokenStore {
   saveTokens: (userId: string, tokens: OneConnectTokens) => Promise<void>;
   loadTokens: (userId: string) => Promise<OneConnectTokens | null>;
-  clearTokens: (userId: string) => Promise<void>;
+  /**
+   * Deletes the user's tokens.
+   *
+   * `failed` is set when the SDK clears because One declared that pair
+   * dead. Delete only when the stored refresh token is still
+   * `failed.refreshToken`: a newer pair saved in the meantime (a
+   * reconnect, another server's refresh) must survive. `failed` is
+   * undefined for `disconnect`, which always deletes.
+   */
+  clearTokens: (userId: string, failed?: OneConnectTokens) => Promise<void>;
+  /**
+   * Runs `run` while holding a lock on this user that every server and
+   * worker of the app shares: a Postgres advisory lock, a Redis lock, a
+   * row lock. The SDK loads, refreshes and saves the user's tokens
+   * inside it.
+   *
+   * Required when the app runs more than one process (serverless,
+   * several instances, a background worker). One rotates the refresh
+   * token on every use and treats a second use of the old one as theft,
+   * revoking the whole grant, so two processes refreshing the same user
+   * at once disconnect that user. Without a lock the SDK can only stop
+   * that inside a single process.
+   *
+   * Hold it for at least 60 seconds before any timeout: it spans one
+   * call to One's token endpoint.
+   */
+  withLock?: <T>(userId: string, run: () => Promise<T>) => Promise<T>;
+}
+
+export interface RefreshIfExpiringOptions {
+  /** Refresh when the access token or the refresh token expires within
+   *  this many milliseconds. One minute when omitted. */
+  withinMs?: number;
 }
 
 export interface OneConnectServerConfig {
@@ -137,6 +169,13 @@ export interface RunActionResult {
   data: unknown;
 }
 
+/**
+ * - `not_connected`: no tokens are stored for this user.
+ * - `refresh_failed`: One declared the grant dead (revoked, expired or
+ *   reused). The tokens were cleared; ask the user to connect again.
+ * - `request_failed`: One answered with an error or could not be
+ *   reached. During a refresh the tokens are kept, so retry later.
+ */
 export type OneConnectErrorCode =
   | "not_connected"
   | "refresh_failed"