@withone/connect 0.9.0 → 0.11.0

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"

package/src/types.ts

@@ -42,8 +42,7 @@ export interface OneConnectReturn {
  * object to override either.
  */
 export type ConnectButtonPlatformInput =
-  | string
-  | { slug?: string; name?: string; imageUrl?: string };
+  string | { slug?: string; name?: string; imageUrl?: string };
 
 /** A normalized chip: what the button actually draws. */
 export interface ConnectButtonPlatform {
@@ -66,11 +65,9 @@ export interface ConnectButtonOptions {
   variant?: ConnectButtonVariant;
   /** Matches the host page, not One's page (that is connect.appTheme). */
   theme?: OneConnectTheme;
-  /** Connector chips. The first three render; the rest fold into the
-   *  "+N" chip together with moreCount. */
+  /** Connector chips. The first three render; the rest fold into a "+N"
+   *  chip, so that count only ever describes this list. */
   platforms?: ConnectButtonPlatformInput[];
-  /** Extra count for the "+N" chip, e.g. 274 for "the whole catalog". */
-  moreCount?: number;
   /** Sub-line on the block variant, shown while idle. */
   description?: string;
   /** Fill of the accent variant; One's lime when omitted. */

package/src/vue.ts

@@ -44,7 +44,6 @@ export const ConnectButton = defineComponent({
       type: Array as PropType<ConnectButtonPlatformInput[]>,
       default: undefined,
     },
-    moreCount: { type: Number, default: undefined },
     description: { type: String, default: undefined },
     accentColor: { type: String, default: undefined },
     connectedLabel: { type: String, default: undefined },

package/src/wrapper-options.ts

@@ -21,7 +21,6 @@ export interface ConnectButtonProps {
   theme?: OneConnectTheme;
   /** Connector slugs, or objects to override name or logo. */
   platforms?: ConnectButtonPlatformInput[];
-  moreCount?: number;
   description?: string;
   accentColor?: string;
   connectedLabel?: string;
@@ -47,7 +46,6 @@ export function optionsFromProps(
     variant: props.variant,
     theme: props.theme,
     platforms: props.platforms,
-    moreCount: props.moreCount,
     description: props.description,
     accentColor: props.accentColor,
     connectedLabel: props.connectedLabel,
@@ -63,7 +61,6 @@ export function propsIdentity(props: ConnectButtonProps): string {
     props.variant,
     props.theme,
     props.platforms ?? [],
-    props.moreCount,
     props.description,
     props.accentColor,
     props.connectedLabel,