@shipfox/api-integration-linear 2.0.0

package/src/core/tokens.test.ts

@@ -0,0 +1,281 @@
+import {getLinearInstallationByConnectionId, upsertLinearInstallation} from '#db/installations.js';
+import {
+  LinearAccessTokenMissingError,
+  LinearConnectionNotFoundError,
+  LinearTokenUnrefreshableError,
+} from './errors.js';
+import {
+  createLinearTokenStore,
+  type LinearConnectionResolverResult,
+  type LinearSecretsStore,
+  linearSecretsNamespace,
+} from './tokens.js';
+
+let secrets: LinearSecretsStore;
+
+beforeAll(async () => {
+  secrets = await import('@shipfox/api-secrets');
+});
+
+function createConnectionContext() {
+  const workspaceId = crypto.randomUUID();
+  const connectionId = crypto.randomUUID();
+  const resolveConnection = vi
+    .fn<(connectionId: string) => Promise<LinearConnectionResolverResult | undefined>>()
+    .mockResolvedValue({workspaceId});
+  const refreshAccessToken = vi.fn();
+  const store = createLinearTokenStore({
+    resolveConnection,
+    secrets,
+    client: {
+      exchangeAuthorizationCode: vi.fn(),
+      getIdentity: vi.fn(),
+      refreshAccessToken,
+      revokeToken: vi.fn(),
+    },
+  });
+
+  return {workspaceId, connectionId, resolveConnection, refreshAccessToken, store};
+}
+
+function createInstallation(input: {
+  connectionId: string;
+  tokenExpiresAt?: Date | null | undefined;
+  scopes?: string[] | undefined;
+}) {
+  return upsertLinearInstallation({
+    connectionId: input.connectionId,
+    organizationId: `org-${crypto.randomUUID()}`,
+    organizationUrlKey: 'acme',
+    appUserId: 'app-user-id',
+    scopes: input.scopes ?? ['read'],
+    tokenExpiresAt: input.tokenExpiresAt,
+    status: 'installed',
+  });
+}
+
+function storedToken(input: {
+  workspaceId: string;
+  connectionId: string;
+  key: 'ACCESS_TOKEN' | 'REFRESH_TOKEN';
+}) {
+  return secrets.getSecret({
+    workspaceId: input.workspaceId,
+    namespace: linearSecretsNamespace(input.connectionId),
+    key: input.key,
+  });
+}
+
+describe('createLinearTokenStore.storeTokens', () => {
+  it('stores access and refresh tokens in the Linear system namespace', async () => {
+    const {workspaceId, connectionId, store} = createConnectionContext();
+
+    await store.storeTokens({
+      connectionId,
+      accessToken: 'access-token',
+      refreshToken: 'refresh-token',
+      editedBy: crypto.randomUUID(),
+    });
+
+    await expect(storedToken({workspaceId, connectionId, key: 'ACCESS_TOKEN'})).resolves.toBe(
+      'access-token',
+    );
+    await expect(storedToken({workspaceId, connectionId, key: 'REFRESH_TOKEN'})).resolves.toBe(
+      'refresh-token',
+    );
+  });
+
+  it('stores only the access token when no refresh token was issued', async () => {
+    const {workspaceId, connectionId, store} = createConnectionContext();
+
+    await store.storeTokens({connectionId, accessToken: 'access-token'});
+
+    await expect(storedToken({workspaceId, connectionId, key: 'ACCESS_TOKEN'})).resolves.toBe(
+      'access-token',
+    );
+    await expect(
+      storedToken({workspaceId, connectionId, key: 'REFRESH_TOKEN'}),
+    ).resolves.toBeNull();
+  });
+
+  it('throws a typed error when the connection cannot be resolved', async () => {
+    const {store, resolveConnection, connectionId} = createConnectionContext();
+    resolveConnection.mockResolvedValue(undefined);
+
+    const result = store.storeTokens({connectionId, accessToken: 'access-token'});
+
+    await expect(result).rejects.toBeInstanceOf(LinearConnectionNotFoundError);
+  });
+});
+
+describe('createLinearTokenStore.getAccessToken', () => {
+  it('returns the stored token when no refresh is needed', async () => {
+    const {connectionId, refreshAccessToken, store} = createConnectionContext();
+    await store.storeTokens({connectionId, accessToken: 'access-token'});
+    await createInstallation({
+      connectionId,
+      tokenExpiresAt: new Date(Date.now() + 60 * 60 * 1000),
+    });
+
+    const result = await store.getAccessToken({connectionId});
+
+    expect(result).toBe('access-token');
+    expect(refreshAccessToken).not.toHaveBeenCalled();
+  });
+
+  it('refreshes an expired token and writes the new secret and metadata', async () => {
+    const {workspaceId, connectionId, refreshAccessToken, store} = createConnectionContext();
+    const expiresAt = new Date('2026-07-07T13:00:00.000Z');
+    await store.storeTokens({
+      connectionId,
+      accessToken: 'old-access-token',
+      refreshToken: 'old-refresh-token',
+    });
+    await createInstallation({
+      connectionId,
+      tokenExpiresAt: new Date('2026-07-07T11:00:00.000Z'),
+      scopes: ['read'],
+    });
+    refreshAccessToken.mockResolvedValue({
+      accessToken: 'new-access-token',
+      refreshToken: 'new-refresh-token',
+      expiresAt,
+      scopes: ['read', 'write'],
+    });
+
+    const result = await store.getAccessToken({connectionId});
+
+    const installation = await getLinearInstallationByConnectionId(connectionId);
+    expect(result).toBe('new-access-token');
+    await expect(storedToken({workspaceId, connectionId, key: 'ACCESS_TOKEN'})).resolves.toBe(
+      'new-access-token',
+    );
+    await expect(storedToken({workspaceId, connectionId, key: 'REFRESH_TOKEN'})).resolves.toBe(
+      'new-refresh-token',
+    );
+    expect(installation?.tokenExpiresAt?.toISOString()).toBe(expiresAt.toISOString());
+    expect(installation?.scopes).toEqual(['read', 'write']);
+  });
+
+  it('force refreshes even when the token expiry is unknown', async () => {
+    const {connectionId, refreshAccessToken, store} = createConnectionContext();
+    await store.storeTokens({
+      connectionId,
+      accessToken: 'old-access-token',
+      refreshToken: 'refresh-token',
+    });
+    await createInstallation({connectionId, tokenExpiresAt: null});
+    refreshAccessToken.mockResolvedValue({
+      accessToken: 'new-access-token',
+      expiresAt: new Date('2026-07-07T13:00:00.000Z'),
+      scopes: [],
+    });
+
+    const result = await store.getAccessToken({connectionId, forceRefresh: true});
+
+    expect(result).toBe('new-access-token');
+  });
+
+  it('returns the stored token for proactive refresh when no refresh token exists', async () => {
+    const {connectionId, refreshAccessToken, store} = createConnectionContext();
+    await store.storeTokens({connectionId, accessToken: 'access-token'});
+    await createInstallation({
+      connectionId,
+      tokenExpiresAt: new Date('2026-07-07T11:00:00.000Z'),
+    });
+
+    const result = await store.getAccessToken({connectionId});
+
+    expect(result).toBe('access-token');
+    expect(refreshAccessToken).not.toHaveBeenCalled();
+  });
+
+  it('preserves the stored refresh token when Linear omits a rotated replacement', async () => {
+    const {workspaceId, connectionId, refreshAccessToken, store} = createConnectionContext();
+    await store.storeTokens({
+      connectionId,
+      accessToken: 'old-access-token',
+      refreshToken: 'old-refresh-token',
+    });
+    await createInstallation({
+      connectionId,
+      tokenExpiresAt: new Date('2026-07-07T11:00:00.000Z'),
+    });
+    refreshAccessToken.mockResolvedValue({
+      accessToken: 'new-access-token',
+      expiresAt: new Date('2026-07-07T13:00:00.000Z'),
+      scopes: ['read'],
+    });
+
+    await store.getAccessToken({connectionId});
+
+    await expect(storedToken({workspaceId, connectionId, key: 'REFRESH_TOKEN'})).resolves.toBe(
+      'old-refresh-token',
+    );
+  });
+
+  it('shares one in-process refresh across concurrent callers', async () => {
+    const {connectionId, refreshAccessToken, store} = createConnectionContext();
+    await store.storeTokens({
+      connectionId,
+      accessToken: 'old-access-token',
+      refreshToken: 'refresh-token',
+    });
+    await createInstallation({
+      connectionId,
+      tokenExpiresAt: new Date('2026-07-07T11:00:00.000Z'),
+    });
+    refreshAccessToken.mockResolvedValue({
+      accessToken: 'new-access-token',
+      refreshToken: 'new-refresh-token',
+      expiresAt: new Date('2026-07-07T13:00:00.000Z'),
+      scopes: ['read'],
+    });
+
+    const results = await Promise.all([
+      store.getAccessToken({connectionId}),
+      store.getAccessToken({connectionId}),
+    ]);
+
+    expect(refreshAccessToken).toHaveBeenCalledTimes(1);
+    expect(results).toEqual(['new-access-token', 'new-access-token']);
+  });
+
+  it('throws reconnect-needed when a forced refresh has no refresh token', async () => {
+    const {connectionId, store} = createConnectionContext();
+    await store.storeTokens({connectionId, accessToken: 'dead-access-token'});
+    await createInstallation({connectionId, tokenExpiresAt: null});
+
+    const result = store.getAccessToken({connectionId, forceRefresh: true});
+
+    await expect(result).rejects.toBeInstanceOf(LinearTokenUnrefreshableError);
+  });
+
+  it('throws a typed error when the connection cannot be resolved', async () => {
+    const {store, resolveConnection, connectionId} = createConnectionContext();
+    resolveConnection.mockResolvedValue(undefined);
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toBeInstanceOf(LinearConnectionNotFoundError);
+  });
+
+  it('throws a typed error when no access token is stored', async () => {
+    const {connectionId, store} = createConnectionContext();
+    await createInstallation({connectionId, tokenExpiresAt: null});
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toBeInstanceOf(LinearAccessTokenMissingError);
+  });
+
+  it('skips proactive refresh when the installation row is missing', async () => {
+    const {connectionId, refreshAccessToken, store} = createConnectionContext();
+    await store.storeTokens({connectionId, accessToken: 'access-token'});
+
+    const result = await store.getAccessToken({connectionId});
+
+    expect(result).toBe('access-token');
+    expect(refreshAccessToken).not.toHaveBeenCalled();
+  });
+});

package/src/core/tokens.ts

@@ -0,0 +1,219 @@
+import {createLinearApiClient, type LinearApiClient} from '#api/client.js';
+import {
+  LinearAccessTokenMissingError,
+  LinearConnectionNotFoundError,
+  LinearIntegrationProviderError,
+  LinearTokenUnrefreshableError,
+} from '#core/errors.js';
+import {
+  getLinearInstallationByConnectionId,
+  updateLinearInstallationTokenExpiry,
+  withLinearRefreshLock,
+} 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 LinearConnectionResolverResult {
+  workspaceId: string;
+}
+
+export interface CreateLinearTokenStoreParams {
+  resolveConnection(connectionId: string): Promise<LinearConnectionResolverResult | undefined>;
+  secrets: LinearSecretsStore;
+  client?: LinearApiClient | undefined;
+}
+
+export interface LinearSecretsStore {
+  getSecret(params: {workspaceId: string; namespace: string; key: string}): Promise<string | null>;
+  setSecrets(params: {
+    workspaceId: string;
+    namespace: string;
+    values: Record<string, string>;
+    editedBy?: string | null | undefined;
+  }): Promise<void>;
+}
+
+export interface StoreLinearTokensParams {
+  connectionId: string;
+  accessToken: string;
+  refreshToken?: string | undefined;
+  editedBy?: string | null | undefined;
+}
+
+export interface GetLinearAccessTokenParams {
+  connectionId: string;
+  forceRefresh?: boolean | undefined;
+}
+
+export interface LinearTokenStore {
+  storeTokens(params: StoreLinearTokensParams): Promise<void>;
+  getAccessToken(params: GetLinearAccessTokenParams): Promise<string>;
+}
+
+export function linearSecretsNamespace(connectionId: string): string {
+  return `system/integrations/linear/${connectionId}`;
+}
+
+export function createLinearTokenStore(params: CreateLinearTokenStoreParams): LinearTokenStore {
+  const client = params.client ?? createLinearApiClient();
+
+  async function resolveWorkspaceId(connectionId: string): Promise<string> {
+    const connection = await params.resolveConnection(connectionId);
+    if (!connection) throw new LinearConnectionNotFoundError(connectionId);
+    return connection.workspaceId;
+  }
+
+  function readSecretToken(
+    workspaceId: string,
+    connectionId: string,
+    key: typeof ACCESS_TOKEN_KEY | typeof REFRESH_TOKEN_KEY,
+  ): Promise<string | null> {
+    return params.secrets.getSecret({
+      workspaceId,
+      namespace: linearSecretsNamespace(connectionId),
+      key,
+    });
+  }
+
+  async function readAccessToken(workspaceId: string, connectionId: string): Promise<string> {
+    const token = await readSecretToken(workspaceId, connectionId, ACCESS_TOKEN_KEY);
+    if (!token) throw new LinearAccessTokenMissingError(connectionId);
+    return token;
+  }
+
+  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: linearSecretsNamespace(input.connectionId),
+        values,
+        editedBy: input.editedBy,
+      });
+    },
+
+    async getAccessToken(input) {
+      const forceRefresh = input.forceRefresh === true;
+      const workspaceId = await resolveWorkspaceId(input.connectionId);
+      const installation = await getLinearInstallationByConnectionId(input.connectionId);
+      const accessToken = await readAccessToken(workspaceId, input.connectionId);
+
+      if (!forceRefresh && !shouldRefresh(installation?.tokenExpiresAt ?? null)) {
+        return accessToken;
+      }
+
+      const inFlightRefresh = tokenRefreshes.get(input.connectionId);
+      if (inFlightRefresh) return inFlightRefresh;
+
+      const refresh = refreshAccessTokenWithLock({
+        connectionId: input.connectionId,
+        workspaceId,
+        originalAccessToken: accessToken,
+        forceRefresh,
+        client,
+        secrets: params.secrets,
+        readAccessToken,
+        readSecretToken,
+      });
+      tokenRefreshes.set(input.connectionId, refresh);
+      void refresh.then(
+        () => clearTokenRefresh(input.connectionId, refresh),
+        () => clearTokenRefresh(input.connectionId, refresh),
+      );
+      return refresh;
+    },
+  };
+}
+
+function shouldRefresh(expiresAt: Date | null): boolean {
+  return expiresAt !== null && expiresAt.getTime() <= Date.now() + TOKEN_REFRESH_MARGIN_MS;
+}
+
+async function refreshAccessTokenWithLock(params: {
+  connectionId: string;
+  workspaceId: string;
+  originalAccessToken: string;
+  forceRefresh: boolean;
+  client: LinearApiClient;
+  secrets: LinearSecretsStore;
+  readAccessToken(workspaceId: string, connectionId: string): Promise<string>;
+  readSecretToken(
+    workspaceId: string,
+    connectionId: string,
+    key: typeof ACCESS_TOKEN_KEY | typeof REFRESH_TOKEN_KEY,
+  ): Promise<string | null>;
+}): Promise<string> {
+  const lock = await withLinearRefreshLock(params.connectionId, async () =>
+    refreshAccessTokenForConnection(params),
+  );
+
+  if (lock.acquired) return lock.value;
+
+  const rereadToken = await params.readAccessToken(params.workspaceId, params.connectionId);
+  if (rereadToken !== params.originalAccessToken) return rereadToken;
+  if (params.forceRefresh) {
+    throw new LinearIntegrationProviderError(
+      'provider-unavailable',
+      'Linear token refresh is already in progress',
+    );
+  }
+  return params.originalAccessToken;
+}
+
+function clearTokenRefresh(connectionId: string, refresh: Promise<string>): void {
+  if (tokenRefreshes.get(connectionId) === refresh) tokenRefreshes.delete(connectionId);
+}
+
+async function refreshAccessTokenForConnection(params: {
+  connectionId: string;
+  workspaceId: string;
+  originalAccessToken: string;
+  forceRefresh: boolean;
+  client: LinearApiClient;
+  secrets: LinearSecretsStore;
+  readAccessToken(workspaceId: string, connectionId: string): Promise<string>;
+  readSecretToken(
+    workspaceId: string,
+    connectionId: string,
+    key: typeof ACCESS_TOKEN_KEY | typeof REFRESH_TOKEN_KEY,
+  ): Promise<string | null>;
+}): Promise<string> {
+  const currentAccessToken = await params.readAccessToken(params.workspaceId, params.connectionId);
+  const currentInstallation = await getLinearInstallationByConnectionId(params.connectionId);
+  const tokenChanged = currentAccessToken !== params.originalAccessToken;
+  const isFresh =
+    !params.forceRefresh && !shouldRefresh(currentInstallation?.tokenExpiresAt ?? null);
+  if (tokenChanged || isFresh) return currentAccessToken;
+
+  const refreshToken = await params.readSecretToken(
+    params.workspaceId,
+    params.connectionId,
+    REFRESH_TOKEN_KEY,
+  );
+  if (!refreshToken) {
+    if (params.forceRefresh) throw new LinearTokenUnrefreshableError(params.connectionId);
+    return currentAccessToken;
+  }
+
+  const refreshed = await params.client.refreshAccessToken({refreshToken});
+  const values: Record<string, string> = {[ACCESS_TOKEN_KEY]: refreshed.accessToken};
+  if (refreshed.refreshToken) values[REFRESH_TOKEN_KEY] = refreshed.refreshToken;
+  await params.secrets.setSecrets({
+    workspaceId: params.workspaceId,
+    namespace: linearSecretsNamespace(params.connectionId),
+    values,
+  });
+  await updateLinearInstallationTokenExpiry({
+    connectionId: params.connectionId,
+    tokenExpiresAt: refreshed.expiresAt ?? null,
+    scopes: refreshed.scopes.length > 0 ? refreshed.scopes : undefined,
+  });
+
+  return refreshed.accessToken;
+}