@shipfox/api-integration-linear 2.0.0

package/src/core/disconnect.test.ts

@@ -0,0 +1,45 @@
+import {disconnectLinearInstallation} from './disconnect.js';
+
+vi.mock('#db/installations.js', () => ({
+  deleteLinearInstallationByConnectionId: vi.fn(() => Promise.resolve(true)),
+}));
+
+const {deleteLinearInstallationByConnectionId} = await import('#db/installations.js');
+const deleteLinearInstallationByConnectionIdMock = vi.mocked(
+  deleteLinearInstallationByConnectionId,
+);
+
+describe('disconnectLinearInstallation', () => {
+  beforeEach(() => {
+    deleteLinearInstallationByConnectionIdMock.mockClear();
+  });
+
+  it('deletes stored tokens before deleting connection records', async () => {
+    const tx = Symbol('tx');
+    const calls: string[] = [];
+    const deleteSecrets = vi.fn(() => {
+      calls.push('secrets');
+      return Promise.resolve(2);
+    });
+    const deleteConnection = vi.fn(() => {
+      calls.push('connection');
+      return Promise.resolve(true);
+    });
+
+    await disconnectLinearInstallation({
+      connectionId: 'connection-1',
+      getConnection: vi.fn(() => Promise.resolve({workspaceId: 'workspace-1'})),
+      deleteSecrets,
+      transaction: async (fn) => await fn(tx),
+      deleteConnection,
+    });
+
+    expect(deleteSecrets).toHaveBeenCalledWith({
+      workspaceId: 'workspace-1',
+      namespace: 'system/integrations/linear/connection-1',
+    });
+    expect(deleteLinearInstallationByConnectionIdMock).toHaveBeenCalledWith('connection-1', {tx});
+    expect(deleteConnection).toHaveBeenCalledWith({connectionId: 'connection-1'}, {tx});
+    expect(calls).toEqual(['secrets', 'connection']);
+  });
+});

package/src/core/disconnect.ts

@@ -0,0 +1,27 @@
+import {deleteLinearInstallationByConnectionId} from '#db/installations.js';
+import {linearSecretsNamespace} from './tokens.js';
+
+export interface DisconnectLinearInstallationParams<Tx = unknown> {
+  connectionId: string;
+  getConnection(connectionId: string): Promise<{workspaceId: string} | undefined>;
+  deleteSecrets(params: {workspaceId: string; namespace: string}): Promise<number>;
+  transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
+  deleteConnection(params: {connectionId: string}, options: {tx: Tx}): Promise<boolean>;
+}
+
+export async function disconnectLinearInstallation<Tx = unknown>(
+  params: DisconnectLinearInstallationParams<Tx>,
+): Promise<void> {
+  const connection = await params.getConnection(params.connectionId);
+  if (connection) {
+    await params.deleteSecrets({
+      workspaceId: connection.workspaceId,
+      namespace: linearSecretsNamespace(params.connectionId),
+    });
+  }
+
+  await params.transaction(async (tx) => {
+    await deleteLinearInstallationByConnectionId(params.connectionId, {tx});
+    await params.deleteConnection({connectionId: params.connectionId}, {tx});
+  });
+}

package/src/core/errors.ts

@@ -0,0 +1,71 @@
+import {IntegrationProviderError} from '@shipfox/api-integration-core-dto';
+
+export class LinearIntegrationProviderError extends IntegrationProviderError {}
+
+export class LinearInstallStateError extends Error {
+  constructor(message = 'Invalid Linear install state') {
+    super(message);
+    this.name = 'LinearInstallStateError';
+  }
+}
+
+export class LinearInstallStateActorMismatchError extends Error {
+  constructor() {
+    super('Linear install state was created by a different user');
+    this.name = 'LinearInstallStateActorMismatchError';
+  }
+}
+
+export class LinearOAuthCallbackError extends Error {
+  constructor(
+    public readonly providerError: string,
+    public readonly providerDescription: string | undefined,
+  ) {
+    super(providerDescription ?? `Linear OAuth callback failed: ${providerError}`);
+    this.name = 'LinearOAuthCallbackError';
+  }
+}
+
+export class LinearAuthorizationScopeMismatchError extends Error {
+  constructor(public readonly missingScopes: string[]) {
+    super(`Linear authorization is missing required scopes: ${missingScopes.join(', ')}`);
+    this.name = 'LinearAuthorizationScopeMismatchError';
+  }
+}
+
+export class LinearInstallationAlreadyLinkedError extends Error {
+  constructor(organizationId: string) {
+    super(`Linear organization is already linked to another Shipfox workspace: ${organizationId}`);
+    this.name = 'LinearInstallationAlreadyLinkedError';
+  }
+}
+
+export class LinearConnectionAlreadyLinkedError extends Error {
+  constructor(connectionId: string) {
+    super(
+      `Integration connection is already linked to another Linear organization: ${connectionId}`,
+    );
+    this.name = 'LinearConnectionAlreadyLinkedError';
+  }
+}
+
+export class LinearConnectionNotFoundError extends Error {
+  constructor(connectionId: string) {
+    super(`Linear integration connection was not found: ${connectionId}`);
+    this.name = 'LinearConnectionNotFoundError';
+  }
+}
+
+export class LinearAccessTokenMissingError extends Error {
+  constructor(connectionId: string) {
+    super(`Linear access token is missing for connection: ${connectionId}`);
+    this.name = 'LinearAccessTokenMissingError';
+  }
+}
+
+export class LinearTokenUnrefreshableError extends Error {
+  constructor(public readonly connectionId: string) {
+    super(`Linear token cannot be refreshed; reconnect is required: ${connectionId}`);
+    this.name = 'LinearTokenUnrefreshableError';
+  }
+}

package/src/core/install.ts

@@ -0,0 +1,162 @@
+import type {UserContextMembership} from '@shipfox/api-auth-context';
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {LinearApiClient} from '#api/client.js';
+import type {LinearTokenStore} from '#core/tokens.js';
+import {
+  LinearInstallationAlreadyLinkedError,
+  LinearInstallStateActorMismatchError,
+  LinearOAuthCallbackError,
+} from './errors.js';
+import {assertLinearAuthorizationScopes} from './scopes.js';
+import {verifyLinearInstallState} from './state.js';
+
+export interface ConnectLinearInstallationInput {
+  workspaceId: string;
+  organizationId: string;
+  organizationUrlKey: string;
+  appUserId: string;
+  scopes: string[];
+  tokenExpiresAt: Date | null;
+  displayName: string;
+}
+
+export interface HandleLinearCallbackParams {
+  linear: LinearApiClient;
+  tokenStore: Pick<LinearTokenStore, 'storeTokens'>;
+  code: string;
+  state: string;
+  sessionUserId: string;
+  sessionMemberships: ReadonlyArray<UserContextMembership>;
+  requireWorkspaceMembership: (params: {
+    workspaceId: string;
+    userId: string;
+    memberships: ReadonlyArray<UserContextMembership>;
+  }) => Promise<unknown>;
+  getExistingLinearConnection: (input: {
+    organizationId: string;
+  }) => Promise<IntegrationConnection<'linear'> | undefined>;
+  connectLinearInstallation: (
+    input: ConnectLinearInstallationInput,
+  ) => Promise<IntegrationConnection<'linear'>>;
+  disconnectLinearInstallation: (input: {connectionId: string}) => Promise<void>;
+}
+
+export async function handleLinearCallback(
+  params: HandleLinearCallbackParams,
+): Promise<IntegrationConnection<'linear'>> {
+  if (typeof params.disconnectLinearInstallation !== 'function') {
+    throw new Error('Linear installation cleanup is not configured');
+  }
+
+  const claims = verifyLinearInstallState(params.state);
+  if (claims.userId !== params.sessionUserId) {
+    throw new LinearInstallStateActorMismatchError();
+  }
+  await params.requireWorkspaceMembership({
+    workspaceId: claims.workspaceId,
+    userId: claims.userId,
+    memberships: params.sessionMemberships,
+  });
+
+  const authorization = await params.linear.exchangeAuthorizationCode({code: params.code});
+  let connectedConnectionId: string | undefined;
+  let shouldDisconnectConnection = false;
+  try {
+    const identity = await params.linear.getIdentity({accessToken: authorization.accessToken});
+    const existing = await params.getExistingLinearConnection({
+      organizationId: identity.organizationId,
+    });
+    if (existing && existing.workspaceId !== claims.workspaceId) {
+      throw new LinearInstallationAlreadyLinkedError(identity.organizationId);
+    }
+
+    assertLinearAuthorizationScopes(authorization.scopes);
+
+    const connection = await params.connectLinearInstallation({
+      workspaceId: claims.workspaceId,
+      organizationId: identity.organizationId,
+      organizationUrlKey: identity.organizationUrlKey,
+      appUserId: identity.appUserId,
+      scopes: authorization.scopes,
+      tokenExpiresAt: authorization.expiresAt ?? null,
+      displayName: `Linear ${identity.organizationName}`,
+    });
+    connectedConnectionId = connection.id;
+    shouldDisconnectConnection = !existing;
+    await params.tokenStore.storeTokens({
+      connectionId: connection.id,
+      accessToken: authorization.accessToken,
+      refreshToken: authorization.refreshToken,
+      editedBy: claims.userId,
+    });
+
+    return connection;
+  } catch (error) {
+    await bestEffortRevokeAuthorization(params.linear, authorization);
+    if (connectedConnectionId && shouldDisconnectConnection) {
+      await bestEffortDisconnectLinearInstallation(params, connectedConnectionId);
+    }
+    throw error;
+  }
+}
+
+export async function handleLinearOAuthCallbackError(params: {
+  state: string;
+  error: string;
+  errorDescription?: string | undefined;
+  sessionUserId: string;
+  sessionMemberships: ReadonlyArray<UserContextMembership>;
+  requireWorkspaceMembership: (input: {
+    workspaceId: string;
+    userId: string;
+    memberships: ReadonlyArray<UserContextMembership>;
+  }) => Promise<unknown>;
+}): Promise<never> {
+  const claims = verifyLinearInstallState(params.state);
+  if (claims.userId !== params.sessionUserId) throw new LinearInstallStateActorMismatchError();
+  await params.requireWorkspaceMembership({
+    workspaceId: claims.workspaceId,
+    userId: claims.userId,
+    memberships: params.sessionMemberships,
+  });
+  throw new LinearOAuthCallbackError(params.error, params.errorDescription);
+}
+
+async function bestEffortRevokeAuthorization(
+  linear: LinearApiClient,
+  authorization: {accessToken: string; refreshToken?: string | undefined},
+): Promise<void> {
+  await Promise.all([
+    authorization.refreshToken
+      ? revokeToken(linear, authorization.refreshToken, 'refresh_token')
+      : Promise.resolve(),
+    revokeToken(linear, authorization.accessToken, 'access_token'),
+  ]);
+}
+
+async function revokeToken(
+  linear: LinearApiClient,
+  token: string,
+  tokenTypeHint: 'access_token' | 'refresh_token',
+): Promise<void> {
+  try {
+    await linear.revokeToken({token, tokenTypeHint});
+  } catch (error) {
+    logger().warn({err: error, tokenTypeHint}, 'Linear OAuth token revocation failed');
+  }
+}
+
+async function bestEffortDisconnectLinearInstallation(
+  params: HandleLinearCallbackParams,
+  connectionId: string,
+): Promise<void> {
+  try {
+    await params.disconnectLinearInstallation({connectionId});
+  } catch (error) {
+    logger().warn(
+      {err: error, connectionId},
+      'Linear connect compensation failed after token storage rejection',
+    );
+  }
+}

package/src/core/scopes.ts

@@ -0,0 +1,18 @@
+import {LinearAuthorizationScopeMismatchError} from './errors.js';
+
+export const LINEAR_OAUTH_SCOPES = Object.freeze([
+  'read',
+  'write',
+  'app:assignable',
+  'app:mentionable',
+]);
+
+export function formatLinearOAuthScopes(scopes = LINEAR_OAUTH_SCOPES): string {
+  return scopes.join(',');
+}
+
+export function assertLinearAuthorizationScopes(scopes: string[]): void {
+  const grantedScopes = new Set(scopes);
+  const missingScopes = LINEAR_OAUTH_SCOPES.filter((scope) => !grantedScopes.has(scope));
+  if (missingScopes.length > 0) throw new LinearAuthorizationScopeMismatchError(missingScopes);
+}

package/src/core/state.test.ts

@@ -0,0 +1,51 @@
+import {LinearInstallStateError} from './errors.js';
+import {signLinearInstallState, verifyLinearInstallState} from './state.js';
+
+describe('Linear install state', () => {
+  it('round-trips signed workspace and user claims', () => {
+    const state = signLinearInstallState({
+      workspaceId: 'workspace-1',
+      userId: 'user-1',
+      nonce: 'nonce-1',
+      now: new Date('2026-07-07T12:00:00.000Z'),
+    });
+
+    const result = verifyLinearInstallState(state, new Date('2026-07-07T12:05:00.000Z'));
+
+    expect(result).toEqual({workspaceId: 'workspace-1', userId: 'user-1'});
+  });
+
+  it('rejects tampered payloads', () => {
+    const state = signLinearInstallState({
+      workspaceId: 'workspace-1',
+      userId: 'user-1',
+      nonce: 'nonce-1',
+      now: new Date('2026-07-07T12:00:00.000Z'),
+    });
+    const [encodedPayload, signature] = state.split('.');
+    const payload = JSON.parse(Buffer.from(encodedPayload ?? '', 'base64url').toString('utf8'));
+    payload.workspaceId = 'workspace-2';
+    const tamperedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
+
+    const result = () =>
+      verifyLinearInstallState(
+        `${tamperedPayload}.${signature}`,
+        new Date('2026-07-07T12:05:00.000Z'),
+      );
+
+    expect(result).toThrow(LinearInstallStateError);
+  });
+
+  it('rejects expired states', () => {
+    const state = signLinearInstallState({
+      workspaceId: 'workspace-1',
+      userId: 'user-1',
+      nonce: 'nonce-1',
+      now: new Date('2026-07-07T12:00:00.000Z'),
+    });
+
+    const result = () => verifyLinearInstallState(state, new Date('2026-07-07T12:31:00.000Z'));
+
+    expect(result).toThrow(LinearInstallStateError);
+  });
+});

package/src/core/state.ts

@@ -0,0 +1,85 @@
+import {createHmac, randomUUID, timingSafeEqual} from 'node:crypto';
+import {config} from '#config.js';
+import {LinearInstallStateError} from './errors.js';
+
+const STATE_TTL_SECONDS = 30 * 60;
+
+interface LinearInstallStatePayload {
+  workspaceId: string;
+  userId: string;
+  nonce: string;
+  expiresAt: number;
+}
+
+export interface LinearInstallStateClaims {
+  workspaceId: string;
+  userId: string;
+}
+
+export function signLinearInstallState(params: {
+  workspaceId: string;
+  userId: string;
+  nonce?: string | undefined;
+  now?: Date | undefined;
+}): string {
+  const now = params.now ?? new Date();
+  const payload: LinearInstallStatePayload = {
+    workspaceId: params.workspaceId,
+    userId: params.userId,
+    nonce: params.nonce ?? randomUUID(),
+    expiresAt: Math.floor(now.getTime() / 1000) + STATE_TTL_SECONDS,
+  };
+  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  return `${encodedPayload}.${sign(encodedPayload)}`;
+}
+
+export function verifyLinearInstallState(
+  state: string,
+  now: Date = new Date(),
+): LinearInstallStateClaims {
+  const [encodedPayload, signature, extra] = state.split('.');
+  if (!encodedPayload || !signature || extra !== undefined) {
+    throw new LinearInstallStateError('Invalid Linear install state');
+  }
+
+  if (!constantTimeEqual(signature, sign(encodedPayload))) {
+    throw new LinearInstallStateError('Invalid Linear install state signature');
+  }
+
+  const payload = parsePayload(encodedPayload);
+  if (payload.expiresAt < Math.floor(now.getTime() / 1000)) {
+    throw new LinearInstallStateError('Expired Linear install state');
+  }
+
+  return {workspaceId: payload.workspaceId, userId: payload.userId};
+}
+
+function sign(encodedPayload: string): string {
+  return createHmac('sha256', config.LINEAR_OAUTH_CLIENT_SECRET)
+    .update(encodedPayload)
+    .digest('base64url');
+}
+
+function constantTimeEqual(a: string, b: string): boolean {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  if (left.length !== right.length) return false;
+  return timingSafeEqual(left, right);
+}
+
+function parsePayload(encodedPayload: string): LinearInstallStatePayload {
+  try {
+    const parsed = JSON.parse(Buffer.from(encodedPayload, 'base64url').toString('utf8'));
+    if (
+      typeof parsed.workspaceId !== 'string' ||
+      typeof parsed.userId !== 'string' ||
+      typeof parsed.nonce !== 'string' ||
+      typeof parsed.expiresAt !== 'number'
+    ) {
+      throw new Error('Invalid payload shape');
+    }
+    return parsed;
+  } catch (_error) {
+    throw new LinearInstallStateError('Invalid Linear install state payload');
+  }
+}