@shipfox/api-integration-jira 12.0.0 → 12.1.0

package/src/core/tokens-refresh.test.ts

@@ -1,20 +1,22 @@
-const {getInstallation, updateExpiry, withRefreshLock} = vi.hoisted(() => ({
+const {getInstallation, updateExpiry, withRefreshLock, withRefreshLockAndWait} = vi.hoisted(() => ({
   getInstallation: vi.fn(),
   updateExpiry: vi.fn(),
   withRefreshLock: vi.fn(async (_connectionId: string, fn: () => Promise<string>) => ({
     acquired: true as const,
     value: await fn(),
   })),
+  withRefreshLockAndWait: vi.fn(async (_connectionId: string, fn: () => Promise<void>) => fn()),
 }));
 
 vi.mock('#db/installations.js', () => ({
   getJiraInstallationByConnectionId: getInstallation,
   updateJiraInstallationTokenExpiry: updateExpiry,
   withJiraRefreshLock: withRefreshLock,
+  withJiraRefreshLockAndWait: withRefreshLockAndWait,
 }));
 
 import {JiraIntegrationProviderError, JiraTokenUnrefreshableError} from './errors.js';
-import {createJiraTokenStore} from './tokens.js';
+import {createJiraTokenStore, type JiraConnectionResolverResult} from './tokens.js';
 
 function createStore() {
   const values = new Map<string, string>();
@@ -35,13 +37,24 @@ function createStore() {
   };
   const markConnectionError = vi.fn().mockResolvedValue(undefined);
   const connectionId = crypto.randomUUID();
+  const workspaceId = crypto.randomUUID();
+  const resolveConnection = vi.fn().mockResolvedValue({workspaceId, lifecycleStatus: 'active'});
   const store = createJiraTokenStore({
-    resolveConnection: vi.fn().mockResolvedValue({workspaceId: crypto.randomUUID()}),
+    resolveConnection,
     secrets,
     client,
     markConnectionError,
   });
-  return {client, connectionId, markConnectionError, secrets, store, values};
+  return {
+    client,
+    connectionId,
+    markConnectionError,
+    resolveConnection,
+    secrets,
+    store,
+    values,
+    workspaceId,
+  };
 }
 
 describe('Jira token refresh', () => {
@@ -52,6 +65,7 @@ describe('Jira token refresh', () => {
       acquired: true,
       value: await fn(),
     }));
+    withRefreshLockAndWait.mockImplementation(async (_connectionId, fn) => fn());
   });
 
   it('rotates and persists both tokens when the access token expires', async () => {
@@ -87,6 +101,209 @@ describe('Jira token refresh', () => {
     expect(markConnectionError).toHaveBeenCalledWith({connectionId});
   });
 
+  it('marks timeout failures as requiring reconnect because refresh state is unknown', async () => {
+    const {client, connectionId, markConnectionError, store} = createStore();
+    await store.storeTokens({connectionId, accessToken: 'access-0', refreshToken: 'refresh-0'});
+    client.refreshAccessToken.mockRejectedValue(
+      new JiraIntegrationProviderError('timeout', 'refresh timed out'),
+    );
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toMatchObject({reason: 'timeout'});
+    expect(markConnectionError).toHaveBeenCalledWith({connectionId});
+  });
+
+  it('does not retry a refresh after the connection enters an error state', async () => {
+    const {client, connectionId, store} = createStore();
+    await store.storeTokens({connectionId, accessToken: 'access-0', refreshToken: 'refresh-0'});
+    client.refreshAccessToken.mockRejectedValue(
+      new JiraIntegrationProviderError('timeout', 'refresh timed out'),
+    );
+
+    await expect(store.getAccessToken({connectionId})).rejects.toMatchObject({reason: 'timeout'});
+
+    await expect(store.getAccessToken({connectionId})).rejects.toBeInstanceOf(
+      JiraTokenUnrefreshableError,
+    );
+    expect(client.refreshAccessToken).toHaveBeenCalledOnce();
+  });
+
+  it('allows a reconnect to clear the unknown refresh state', async () => {
+    const {client, connectionId, store} = createStore();
+    await store.storeTokens({connectionId, accessToken: 'access-0', refreshToken: 'refresh-0'});
+    client.refreshAccessToken.mockRejectedValue(
+      new JiraIntegrationProviderError('timeout', 'refresh timed out'),
+    );
+
+    await expect(store.getAccessToken({connectionId})).rejects.toMatchObject({reason: 'timeout'});
+
+    await store.storeTokens({connectionId, accessToken: 'access-1', refreshToken: 'refresh-1'});
+    getInstallation.mockResolvedValue({tokenExpiresAt: null});
+
+    await expect(store.getAccessToken({connectionId})).resolves.toBe('access-1');
+  });
+
+  it('ignores a terminal refresh result from before a reconnect', async () => {
+    const {client, connectionId, markConnectionError, store} = createStore();
+    await store.storeTokens({connectionId, accessToken: 'access-0', refreshToken: 'refresh-0'});
+    let rejectRefresh!: (error: unknown) => void;
+    client.refreshAccessToken.mockImplementation(
+      () =>
+        new Promise<never>((_resolve, reject) => {
+          rejectRefresh = reject;
+        }),
+    );
+
+    const staleRefresh = store.getAccessToken({connectionId});
+    await vi.waitFor(() => expect(client.refreshAccessToken).toHaveBeenCalledOnce());
+
+    await store.storeTokens({connectionId, accessToken: 'access-1', refreshToken: 'refresh-1'});
+    getInstallation.mockResolvedValue({tokenExpiresAt: null});
+    await expect(store.getAccessToken({connectionId})).resolves.toBe('access-1');
+
+    rejectRefresh(new JiraIntegrationProviderError('timeout', 'refresh timed out'));
+    await expect(staleRefresh).rejects.toMatchObject({reason: 'timeout'});
+    expect(markConnectionError).not.toHaveBeenCalled();
+    await expect(store.getAccessToken({connectionId})).resolves.toBe('access-1');
+  });
+
+  it('serializes connection error updates with reconnect credential writes', async () => {
+    const {client, connectionId, markConnectionError, store} = createStore();
+    await store.storeTokens({connectionId, accessToken: 'access-0', refreshToken: 'refresh-0'});
+    let releaseError!: () => void;
+    let errorStarted!: () => void;
+    const errorCanFinish = new Promise<void>((resolve) => {
+      releaseError = resolve;
+    });
+    const errorUpdateStarted = new Promise<void>((resolve) => {
+      errorStarted = resolve;
+    });
+    markConnectionError.mockImplementation(async () => {
+      errorStarted();
+      await errorCanFinish;
+    });
+    client.refreshAccessToken.mockRejectedValue(
+      new JiraIntegrationProviderError('access-denied', 'invalid grant'),
+    );
+
+    const staleRefresh = store.getAccessToken({connectionId});
+    await errorUpdateStarted;
+
+    let reconnectFinished = false;
+    const reconnect = store
+      .storeTokens({connectionId, accessToken: 'access-1', refreshToken: 'refresh-1'})
+      .then(() => {
+        reconnectFinished = true;
+      });
+    await Promise.resolve();
+    expect(reconnectFinished).toBe(false);
+
+    releaseError();
+    await expect(staleRefresh).rejects.toMatchObject({reason: 'access-denied'});
+    await reconnect;
+    expect(markConnectionError).toHaveBeenCalledOnce();
+  });
+
+  it('waits for the shared refresh lock before storing reconnect credentials', async () => {
+    const {connectionId, store, values} = createStore();
+    let releaseLock!: () => void;
+    let lockStarted!: () => void;
+    const lockCanFinish = new Promise<void>((resolve) => {
+      releaseLock = resolve;
+    });
+    const lockEntered = new Promise<void>((resolve) => {
+      lockStarted = resolve;
+    });
+    withRefreshLockAndWait.mockImplementationOnce(async (_connectionId, fn) => {
+      lockStarted();
+      await lockCanFinish;
+      return fn();
+    });
+
+    const reconnect = store.storeTokens({
+      connectionId,
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+    });
+    await lockEntered;
+
+    expect(values.get('ACCESS_TOKEN')).toBeUndefined();
+    releaseLock();
+    await reconnect;
+    expect(values.get('ACCESS_TOKEN')).toBe('access-1');
+    expect(values.get('REFRESH_TOKEN')).toBe('refresh-1');
+    expect(withRefreshLockAndWait).toHaveBeenCalledWith(connectionId, expect.any(Function));
+  });
+
+  it('waits for reconnect credentials before starting another refresh', async () => {
+    const {client, connectionId, resolveConnection, secrets, store, values, workspaceId} =
+      createStore();
+    await store.storeTokens({connectionId, accessToken: 'access-0', refreshToken: 'refresh-0'});
+    let releaseConnection!: () => void;
+    let connectionStarted!: () => void;
+    const connectionCanFinish = new Promise<void>((resolve) => {
+      releaseConnection = resolve;
+    });
+    const connectionLookupStarted = new Promise<void>((resolve) => {
+      connectionStarted = resolve;
+    });
+    resolveConnection.mockImplementationOnce(async () => {
+      connectionStarted();
+      await connectionCanFinish;
+      return {workspaceId, lifecycleStatus: 'active'};
+    });
+    let releaseReconnect!: () => void;
+    let reconnectStarted!: () => void;
+    const reconnectCanFinish = new Promise<void>((resolve) => {
+      releaseReconnect = resolve;
+    });
+    const reconnectWriteStarted = new Promise<void>((resolve) => {
+      reconnectStarted = resolve;
+    });
+    secrets.setSecrets.mockImplementation(
+      async ({values: next}: {values: Record<string, string>}) => {
+        if (next.ACCESS_TOKEN === 'access-1') {
+          reconnectStarted();
+          await reconnectCanFinish;
+        }
+        for (const [key, value] of Object.entries(next)) values.set(key, value);
+      },
+    );
+
+    const accessToken = store.getAccessToken({connectionId});
+    await connectionLookupStarted;
+    const reconnect = store.storeTokens({
+      connectionId,
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+    });
+    await reconnectWriteStarted;
+
+    releaseConnection();
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(client.refreshAccessToken).not.toHaveBeenCalled();
+
+    getInstallation.mockResolvedValue({tokenExpiresAt: null});
+    releaseReconnect();
+    await reconnect;
+    await expect(accessToken).resolves.toBe('access-1');
+    expect(client.refreshAccessToken).not.toHaveBeenCalled();
+  });
+
+  it('fails closed when a connection resolver omits its lifecycle status', async () => {
+    const {connectionId, resolveConnection, store} = createStore();
+    await store.storeTokens({connectionId, accessToken: 'access-0', refreshToken: 'refresh-0'});
+    resolveConnection.mockResolvedValue({
+      workspaceId: crypto.randomUUID(),
+    } as unknown as JiraConnectionResolverResult);
+
+    await expect(store.getAccessToken({connectionId})).rejects.toBeInstanceOf(
+      JiraTokenUnrefreshableError,
+    );
+  });
+
   it('requires a refresh token once the access token expires', async () => {
     const {connectionId, store} = createStore();
     await store.storeTokens({connectionId, accessToken: 'access-0'});

package/src/core/tokens.test.ts

@@ -17,7 +17,7 @@ function createConnectionContext() {
   const connectionId = crypto.randomUUID();
   const resolveConnection = vi
     .fn<(connectionId: string) => Promise<JiraConnectionResolverResult | undefined>>()
-    .mockResolvedValue({workspaceId});
+    .mockResolvedValue({workspaceId, lifecycleStatus: 'active'});
   const store = createJiraTokenStore({resolveConnection, secrets});
 
   return {workspaceId, connectionId, resolveConnection, store};

package/src/core/tokens.ts

@@ -1,3 +1,5 @@
+import type {IntegrationConnectionLifecycleStatus} from '@shipfox/api-integration-spi';
+import {logger} from '@shipfox/node-opentelemetry';
 import {createJiraApiClient, type JiraApiClient} from '#api/client.js';
 import {
   JiraAccessTokenMissingError,
@@ -9,15 +11,16 @@ import {
   getJiraInstallationByConnectionId,
   updateJiraInstallationTokenExpiry,
   withJiraRefreshLock,
+  withJiraRefreshLockAndWait,
 } from '#db/installations.js';
 
 const ACCESS_TOKEN_KEY = 'ACCESS_TOKEN';
 const REFRESH_TOKEN_KEY = 'REFRESH_TOKEN';
 const TOKEN_REFRESH_MARGIN_MS = 5 * 60 * 1000;
-const tokenRefreshes = new Map<string, Promise<string>>();
 
 export interface JiraConnectionResolverResult {
   workspaceId: string;
+  lifecycleStatus: IntegrationConnectionLifecycleStatus;
 }
 
 export interface JiraSecretsStore {
@@ -60,10 +63,44 @@ export function jiraSecretsNamespace(connectionId: string): string {
 
 export function createJiraTokenStore(params: CreateJiraTokenStoreParams): JiraTokenStore {
   const client = params.client ?? createJiraApiClient();
-  async function resolveWorkspaceId(connectionId: string): Promise<string> {
+  const tokenRefreshes = new Map<string, Promise<string>>();
+  const refreshStateUnknownConnections = new Set<string>();
+  const credentialGenerations = new Map<string, number>();
+  const credentialWriteQueues = new Map<string, Promise<void>>();
+  const currentCredentialGeneration = (connectionId: string): number =>
+    credentialGenerations.get(connectionId) ?? 0;
+  const advanceCredentialGeneration = (connectionId: string): number => {
+    const generation = currentCredentialGeneration(connectionId) + 1;
+    credentialGenerations.set(connectionId, generation);
+    return generation;
+  };
+  function withCredentialWrite<T>(connectionId: string, operation: () => Promise<T>): Promise<T> {
+    const previous = credentialWriteQueues.get(connectionId) ?? Promise.resolve();
+    const operationResult = previous.then(operation);
+    const completion = operationResult.then(
+      () => undefined,
+      () => undefined,
+    );
+    credentialWriteQueues.set(connectionId, completion);
+    return operationResult.finally(() => {
+      if (credentialWriteQueues.get(connectionId) === completion) {
+        credentialWriteQueues.delete(connectionId);
+      }
+    });
+  }
+  async function waitForCredentialWrites(connectionId: string): Promise<void> {
+    await credentialWriteQueues.get(connectionId);
+  }
+  async function resolveConnection(connectionId: string): Promise<JiraConnectionResolverResult> {
     const connection = await params.resolveConnection(connectionId);
     if (!connection) throw new JiraConnectionNotFoundError(connectionId);
-    return connection.workspaceId;
+    return connection;
+  }
+  async function resolveWorkspaceId(connectionId: string): Promise<string> {
+    return (await resolveConnection(connectionId)).workspaceId;
+  }
+  function clearTokenRefresh(connectionId: string, refresh: Promise<string>): void {
+    if (tokenRefreshes.get(connectionId) === refresh) tokenRefreshes.delete(connectionId);
   }
   const readSecretToken = (
     workspaceId: string,
@@ -78,18 +115,39 @@ export function createJiraTokenStore(params: CreateJiraTokenStoreParams): JiraTo
 
   return {
     async storeTokens(input) {
-      const workspaceId = await resolveWorkspaceId(input.connectionId);
-      const values: Record<string, string> = {[ACCESS_TOKEN_KEY]: input.accessToken};
-      if (input.refreshToken) values[REFRESH_TOKEN_KEY] = input.refreshToken;
-      await params.secrets.setSecrets({
-        workspaceId,
-        namespace: jiraSecretsNamespace(input.connectionId),
-        values,
-        editedBy: input.editedBy,
-      });
+      const credentialGeneration = advanceCredentialGeneration(input.connectionId);
+      tokenRefreshes.delete(input.connectionId);
+      await withJiraRefreshLockAndWait(input.connectionId, () =>
+        withCredentialWrite(input.connectionId, async () => {
+          if (currentCredentialGeneration(input.connectionId) !== credentialGeneration) return;
+          const workspaceId = await resolveWorkspaceId(input.connectionId);
+          if (currentCredentialGeneration(input.connectionId) !== credentialGeneration) return;
+          const values: Record<string, string> = {[ACCESS_TOKEN_KEY]: input.accessToken};
+          if (input.refreshToken) values[REFRESH_TOKEN_KEY] = input.refreshToken;
+          await params.secrets.setSecrets({
+            workspaceId,
+            namespace: jiraSecretsNamespace(input.connectionId),
+            values,
+            editedBy: input.editedBy,
+          });
+          if (currentCredentialGeneration(input.connectionId) === credentialGeneration) {
+            refreshStateUnknownConnections.delete(input.connectionId);
+          }
+        }),
+      );
     },
     async getAccessToken(input) {
-      const workspaceId = await resolveWorkspaceId(input.connectionId);
+      await waitForCredentialWrites(input.connectionId);
+      const connection = await resolveConnection(input.connectionId);
+      if (connection.lifecycleStatus !== 'active') {
+        throw new JiraTokenUnrefreshableError(input.connectionId);
+      }
+      await waitForCredentialWrites(input.connectionId);
+      if (refreshStateUnknownConnections.has(input.connectionId)) {
+        throw new JiraTokenUnrefreshableError(input.connectionId);
+      }
+      const credentialGeneration = currentCredentialGeneration(input.connectionId);
+      const workspaceId = connection.workspaceId;
       const accessToken = await readAccessToken(workspaceId, input.connectionId);
       if (
         !input.forceRefresh &&
@@ -110,11 +168,23 @@ export function createJiraTokenStore(params: CreateJiraTokenStoreParams): JiraTo
         readAccessToken,
         readSecretToken,
         markConnectionError: params.markConnectionError,
+        withCredentialWrite,
+        waitForCredentialWrites,
+        isCurrentCredentialGeneration: () =>
+          currentCredentialGeneration(input.connectionId) === credentialGeneration,
       });
       tokenRefreshes.set(input.connectionId, refresh);
       void refresh.then(
         () => clearTokenRefresh(input.connectionId, refresh),
-        () => clearTokenRefresh(input.connectionId, refresh),
+        (error) => {
+          if (
+            isTerminalRefreshFailure(error) &&
+            currentCredentialGeneration(input.connectionId) === credentialGeneration
+          ) {
+            refreshStateUnknownConnections.add(input.connectionId);
+          }
+          clearTokenRefresh(input.connectionId, refresh);
+        },
       );
       return refresh;
     },
@@ -125,10 +195,6 @@ function shouldRefresh(expiresAt: Date | null): boolean {
   return expiresAt !== null && expiresAt.getTime() <= Date.now() + TOKEN_REFRESH_MARGIN_MS;
 }
 
-function clearTokenRefresh(connectionId: string, refresh: Promise<string>): void {
-  if (tokenRefreshes.get(connectionId) === refresh) tokenRefreshes.delete(connectionId);
-}
-
 async function refreshAccessTokenWithLock(params: {
   connectionId: string;
   workspaceId: string;
@@ -143,11 +209,17 @@ async function refreshAccessTokenWithLock(params: {
     key: typeof ACCESS_TOKEN_KEY | typeof REFRESH_TOKEN_KEY,
   ): Promise<string | null>;
   markConnectionError?: ((params: {connectionId: string}) => Promise<void>) | undefined;
+  withCredentialWrite<T>(connectionId: string, operation: () => Promise<T>): Promise<T>;
+  waitForCredentialWrites(connectionId: string): Promise<void>;
+  isCurrentCredentialGeneration(): boolean;
 }): Promise<string> {
   const lock = await withJiraRefreshLock(params.connectionId, () =>
     refreshAccessTokenForConnection(params),
   );
   if (lock.acquired) return lock.value;
+  if (!params.isCurrentCredentialGeneration()) {
+    return params.readAccessToken(params.workspaceId, params.connectionId);
+  }
   const reread = await params.readAccessToken(params.workspaceId, params.connectionId);
   if (reread !== params.originalAccessToken) return reread;
   throw new JiraIntegrationProviderError(
@@ -170,7 +242,13 @@ async function refreshAccessTokenForConnection(params: {
     key: typeof ACCESS_TOKEN_KEY | typeof REFRESH_TOKEN_KEY,
   ): Promise<string | null>;
   markConnectionError?: ((params: {connectionId: string}) => Promise<void>) | undefined;
+  withCredentialWrite<T>(connectionId: string, operation: () => Promise<T>): Promise<T>;
+  waitForCredentialWrites(connectionId: string): Promise<void>;
+  isCurrentCredentialGeneration(): boolean;
 }): Promise<string> {
+  if (!params.isCurrentCredentialGeneration()) {
+    return params.readAccessToken(params.workspaceId, params.connectionId);
+  }
   const current = await params.readAccessToken(params.workspaceId, params.connectionId);
   const installation = await getJiraInstallationByConnectionId(params.connectionId);
   if (
@@ -190,25 +268,67 @@ async function refreshAccessTokenForConnection(params: {
   }
   try {
     const refreshed = await params.client.refreshAccessToken({refreshToken});
-    if (!refreshed.refreshToken) throw new JiraTokenUnrefreshableError(params.connectionId);
-    await params.secrets.setSecrets({
-      workspaceId: params.workspaceId,
-      namespace: jiraSecretsNamespace(params.connectionId),
-      values: {
-        [ACCESS_TOKEN_KEY]: refreshed.accessToken,
-        [REFRESH_TOKEN_KEY]: refreshed.refreshToken,
-      },
-    });
-    await updateJiraInstallationTokenExpiry({
-      connectionId: params.connectionId,
-      tokenExpiresAt: refreshed.expiresAt ?? null,
-      scopes: refreshed.scopes.length > 0 ? refreshed.scopes : undefined,
+    const refreshedRefreshToken = refreshed.refreshToken;
+    if (!refreshedRefreshToken) throw new JiraTokenUnrefreshableError(params.connectionId);
+    const persisted = await params.withCredentialWrite(params.connectionId, async () => {
+      if (!params.isCurrentCredentialGeneration()) return false;
+      await params.secrets.setSecrets({
+        workspaceId: params.workspaceId,
+        namespace: jiraSecretsNamespace(params.connectionId),
+        values: {
+          [ACCESS_TOKEN_KEY]: refreshed.accessToken,
+          [REFRESH_TOKEN_KEY]: refreshedRefreshToken,
+        },
+      });
+      if (!params.isCurrentCredentialGeneration()) return false;
+      await updateJiraInstallationTokenExpiry({
+        connectionId: params.connectionId,
+        tokenExpiresAt: refreshed.expiresAt ?? null,
+        scopes: refreshed.scopes.length > 0 ? refreshed.scopes : undefined,
+      });
+      return true;
     });
+    if (!persisted || !params.isCurrentCredentialGeneration()) {
+      await params.waitForCredentialWrites(params.connectionId);
+      return params.readAccessToken(params.workspaceId, params.connectionId);
+    }
     return refreshed.accessToken;
   } catch (error) {
-    if (error instanceof JiraIntegrationProviderError && error.reason === 'access-denied') {
-      await params.markConnectionError?.({connectionId: params.connectionId});
+    if (isTerminalRefreshFailure(error)) {
+      await markConnectionError({
+        callback: params.markConnectionError,
+        connectionId: params.connectionId,
+        isCurrentCredentialGeneration: params.isCurrentCredentialGeneration,
+        withCredentialWrite: params.withCredentialWrite,
+      });
     }
     throw error;
   }
 }
+
+function isTerminalRefreshFailure(error: unknown): boolean {
+  return (
+    error instanceof JiraIntegrationProviderError &&
+    (error.reason === 'access-denied' || error.reason === 'timeout')
+  );
+}
+
+async function markConnectionError(params: {
+  callback: CreateJiraTokenStoreParams['markConnectionError'];
+  connectionId: string;
+  isCurrentCredentialGeneration(): boolean;
+  withCredentialWrite<T>(connectionId: string, operation: () => Promise<T>): Promise<T>;
+}): Promise<void> {
+  if (!params.isCurrentCredentialGeneration()) return;
+  try {
+    await params.withCredentialWrite(params.connectionId, async () => {
+      if (!params.isCurrentCredentialGeneration()) return;
+      await params.callback?.({connectionId: params.connectionId});
+    });
+  } catch (error) {
+    logger().warn(
+      {err: error, connectionId: params.connectionId},
+      'Jira connection error-state update failed after token refresh failure',
+    );
+  }
+}

package/src/db/installations.test.ts

@@ -7,7 +7,9 @@ import {
   getJiraInstallationByCloudId,
   getJiraInstallationByConnectionId,
   getJiraInstallationByWebhookId,
+  listJiraInstallationsDueForTokenRefresh,
   markJiraInstallationRevoked,
+  markJiraInstallationTokenRefreshAttempt,
   updateJiraInstallationTokenExpiry,
   updateJiraInstallationWebhook,
   upsertJiraInstallation,
@@ -121,10 +123,19 @@ describe('jira installations', () => {
   });
 
   it('updates token metadata and deletes an installation', async () => {
-    const input = createInstallationInput();
-    await upsertJiraInstallation(input);
+    const input = createInstallationInput({
+      refreshTokenLastUsedAt: new Date('2020-01-01T00:00:00.000Z'),
+      refreshTokenLastAttemptedAt: new Date('2020-01-01T00:00:00.000Z'),
+    });
+    const initial = await upsertJiraInstallation(input);
     const tokenExpiresAt = new Date('2030-01-01T00:00:00.000Z');
 
+    const attempted = await markJiraInstallationTokenRefreshAttempt(input.connectionId);
+
+    expect(attempted?.refreshTokenLastAttemptedAt.getTime()).toBeGreaterThan(
+      initial.refreshTokenLastAttemptedAt.getTime(),
+    );
+
     const updated = await updateJiraInstallationTokenExpiry({
       connectionId: input.connectionId,
       tokenExpiresAt,
@@ -133,10 +144,81 @@ describe('jira installations', () => {
     const deleted = await deleteJiraInstallationByConnectionId(input.connectionId);
 
     expect(updated).toMatchObject({tokenExpiresAt, scopes: ['read:jira-work', 'write:jira-work']});
+    expect(updated?.refreshTokenLastUsedAt.getTime()).toBeGreaterThan(
+      initial.refreshTokenLastUsedAt.getTime(),
+    );
     expect(deleted).toBe(true);
     await expect(getJiraInstallationByConnectionId(input.connectionId)).resolves.toBeUndefined();
   });
 
+  it('lists only installed installations whose refresh tokens are nearing idle expiry', async () => {
+    const due = createInstallationInput({
+      refreshTokenLastUsedAt: new Date('2026-01-01T00:00:00.000Z'),
+    });
+    const fresh = createInstallationInput({
+      refreshTokenLastUsedAt: new Date('2026-07-01T00:00:00.000Z'),
+    });
+    const boundary = createInstallationInput({
+      refreshTokenLastUsedAt: new Date('2026-06-01T00:00:00.000Z'),
+    });
+    const revoked = createInstallationInput({
+      refreshTokenLastUsedAt: new Date('2026-01-01T00:00:00.000Z'),
+      status: 'revoked',
+    });
+    await upsertJiraInstallation(due);
+    await upsertJiraInstallation(fresh);
+    await upsertJiraInstallation(boundary);
+    await upsertJiraInstallation(revoked);
+
+    const result = await listJiraInstallationsDueForTokenRefresh({
+      before: new Date('2026-06-01T00:00:00.000Z'),
+    });
+
+    expect(result.map((installation) => installation.connectionId)).toContain(due.connectionId);
+    expect(result.map((installation) => installation.connectionId)).toContain(
+      boundary.connectionId,
+    );
+    expect(result.map((installation) => installation.connectionId)).not.toContain(
+      fresh.connectionId,
+    );
+    expect(result.map((installation) => installation.connectionId)).not.toContain(
+      revoked.connectionId,
+    );
+  });
+
+  it('orders due installations by their latest refresh attempt', async () => {
+    const refreshTokenLastUsedAt = new Date('1970-01-01T00:00:00.000Z');
+    const attemptBase = Date.now();
+    const latestAttempt = createInstallationInput({
+      refreshTokenLastUsedAt,
+      refreshTokenLastAttemptedAt: new Date(attemptBase + 3_000),
+    });
+    const middleAttempt = createInstallationInput({
+      refreshTokenLastUsedAt,
+      refreshTokenLastAttemptedAt: new Date(attemptBase + 2_000),
+    });
+    const oldestAttempt = createInstallationInput({
+      refreshTokenLastUsedAt,
+      refreshTokenLastAttemptedAt: new Date(attemptBase + 1_000),
+    });
+    await upsertJiraInstallation(latestAttempt);
+    await upsertJiraInstallation(middleAttempt);
+    await upsertJiraInstallation(oldestAttempt);
+
+    const result = await listJiraInstallationsDueForTokenRefresh({
+      before: new Date('2000-01-01T00:00:00.000Z'),
+      limit: 1_000,
+    });
+    const connectionIds = result.map((installation) => installation.connectionId);
+
+    expect(connectionIds.indexOf(oldestAttempt.connectionId)).toBeLessThan(
+      connectionIds.indexOf(middleAttempt.connectionId),
+    );
+    expect(connectionIds.indexOf(middleAttempt.connectionId)).toBeLessThan(
+      connectionIds.indexOf(latestAttempt.connectionId),
+    );
+  });
+
   it('returns undefined for unknown connection and webhook ids', async () => {
     const connectionId = crypto.randomUUID();
     const webhookId = Number.MAX_SAFE_INTEGER;