@shipfox/api-integration-jira 4.0.0 → 6.0.0

package/src/core/install.ts

@@ -0,0 +1,191 @@
+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 {JiraAccessibleResource, JiraApiClient, JiraAuthorization} from '#api/client.js';
+import type {JiraPendingSelectionStore} from '#core/pending.js';
+import type {JiraTokenStore} from '#core/tokens.js';
+import {
+  JiraInstallationAlreadyLinkedError,
+  JiraInstallStateActorMismatchError,
+  JiraIntegrationProviderError,
+  JiraOAuthCallbackError,
+  JiraOfflineAccessNotGrantedError,
+  JiraPendingSelectionNotFoundError,
+  JiraSiteSelectionMismatchError,
+} from './errors.js';
+import {assertJiraAuthorizationScopes} from './scopes.js';
+import {verifyJiraInstallState} from './state.js';
+
+export interface ConnectJiraInstallationInput {
+  workspaceId: string;
+  cloudId: string;
+  siteUrl: string;
+  siteName: string;
+  authorizingAccountId: string;
+  scopes: string[];
+  tokenExpiresAt: Date | null;
+  displayName: string;
+}
+
+export interface HandleJiraCallbackParams {
+  jira: JiraApiClient;
+  tokenStore: Pick<JiraTokenStore, 'storeTokens'>;
+  pendingStore: Pick<JiraPendingSelectionStore, 'save' | 'load' | 'clear'>;
+  code: string;
+  state: string;
+  sessionUserId: string;
+  sessionMemberships: ReadonlyArray<UserContextMembership>;
+  requireWorkspaceMembership(input: {
+    workspaceId: string;
+    userId: string;
+    memberships: ReadonlyArray<UserContextMembership>;
+  }): Promise<unknown>;
+  getExistingJiraConnection(input: {
+    cloudId: string;
+  }): Promise<IntegrationConnection<'jira'> | undefined>;
+  connectJiraInstallation(
+    input: ConnectJiraInstallationInput,
+  ): Promise<IntegrationConnection<'jira'>>;
+  disconnectJiraInstallation(input: {connectionId: string}): Promise<void>;
+}
+
+export async function handleJiraCallback(
+  params: HandleJiraCallbackParams,
+): Promise<IntegrationConnection<'jira'> | {sites: JiraAccessibleResource[]}> {
+  const claims = await verifyClaims(params, params.state);
+  const authorization = await params.jira.exchangeAuthorizationCode({code: params.code});
+  if (!authorization.refreshToken) throw new JiraOfflineAccessNotGrantedError();
+  const sites = await params.jira.getAccessibleResources({accessToken: authorization.accessToken});
+  if (sites.length === 0)
+    throw new JiraIntegrationProviderError(
+      'access-denied',
+      'Jira authorization did not grant access to a site',
+    );
+  if (sites.length > 1) {
+    await params.pendingStore.save({
+      workspaceId: claims.workspaceId,
+      state: params.state,
+      authorization,
+      sites,
+    });
+    return {sites};
+  }
+  const site = sites[0];
+  if (!site) {
+    throw new JiraIntegrationProviderError(
+      'malformed-provider-response',
+      'Jira accessible-resources response did not contain a selected site',
+    );
+  }
+  assertJiraAuthorizationScopes(site.scopes);
+  return resolveJiraSite({...params, authorization, site, claims});
+}
+
+export async function handleJiraSiteSelection(
+  params: Omit<HandleJiraCallbackParams, 'code'> & {cloudId: string},
+): Promise<IntegrationConnection<'jira'>> {
+  const claims = await verifyClaims(params, params.state);
+  const pending = await params.pendingStore.load({
+    workspaceId: claims.workspaceId,
+    state: params.state,
+  });
+  if (!pending) throw new JiraPendingSelectionNotFoundError();
+  const site = pending.sites.find((candidate) => candidate.cloudId === params.cloudId);
+  if (!site) throw new JiraSiteSelectionMismatchError(params.cloudId);
+  assertJiraAuthorizationScopes(site.scopes);
+  const connection = await resolveJiraSite({
+    ...params,
+    authorization: pending.authorization,
+    site,
+    claims,
+  });
+  await params.pendingStore.clear({workspaceId: claims.workspaceId, state: params.state});
+  return connection;
+}
+
+export async function handleJiraOAuthCallbackError(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> {
+  await verifyClaims(params, params.state);
+  throw new JiraOAuthCallbackError(params.error, params.errorDescription);
+}
+
+async function verifyClaims(
+  params: Pick<
+    HandleJiraCallbackParams,
+    'sessionUserId' | 'sessionMemberships' | 'requireWorkspaceMembership'
+  >,
+  state: string,
+) {
+  const claims = verifyJiraInstallState(state);
+  if (claims.userId !== params.sessionUserId) throw new JiraInstallStateActorMismatchError();
+  await params.requireWorkspaceMembership({
+    workspaceId: claims.workspaceId,
+    userId: claims.userId,
+    memberships: params.sessionMemberships,
+  });
+  return claims;
+}
+
+async function resolveJiraSite(
+  params: Omit<HandleJiraCallbackParams, 'code'> & {
+    authorization: JiraAuthorization;
+    site: JiraAccessibleResource;
+    claims: {workspaceId: string; userId: string};
+  },
+): Promise<IntegrationConnection<'jira'>> {
+  const existing = await params.getExistingJiraConnection({cloudId: params.site.cloudId});
+  if (existing && existing.workspaceId !== params.claims.workspaceId)
+    throw new JiraInstallationAlreadyLinkedError(params.site.cloudId);
+  let connectionId: string | undefined;
+  try {
+    const identity = await params.jira.getMyself({
+      accessToken: params.authorization.accessToken,
+      cloudId: params.site.cloudId,
+    });
+    const connection = await params.connectJiraInstallation({
+      workspaceId: params.claims.workspaceId,
+      cloudId: params.site.cloudId,
+      siteUrl: params.site.url,
+      siteName: params.site.name,
+      authorizingAccountId: identity.accountId,
+      scopes: params.site.scopes,
+      tokenExpiresAt: params.authorization.expiresAt ?? null,
+      displayName: `Jira ${params.site.name}`,
+    });
+    connectionId = connection.id;
+    await params.tokenStore.storeTokens({
+      connectionId: connection.id,
+      accessToken: params.authorization.accessToken,
+      refreshToken: params.authorization.refreshToken,
+      editedBy: params.claims.userId,
+    });
+    return connection;
+  } catch (error) {
+    if (connectionId && !existing) await bestEffortDisconnect(params, connectionId);
+    throw error;
+  }
+}
+
+async function bestEffortDisconnect(
+  params: Pick<HandleJiraCallbackParams, 'disconnectJiraInstallation'>,
+  connectionId: string,
+): Promise<void> {
+  try {
+    await params.disconnectJiraInstallation({connectionId});
+  } catch (error) {
+    logger().warn(
+      {err: error, connectionId},
+      'Jira connect compensation failed after token storage rejection',
+    );
+  }
+}

package/src/core/pending.ts

@@ -0,0 +1,146 @@
+import {createHash} from 'node:crypto';
+import type {JiraAccessibleResource, JiraAuthorization} from '#api/client.js';
+import {
+  deleteJiraPendingSelection,
+  getJiraPendingSelection,
+  listExpiredJiraPendingSelections,
+  saveJiraPendingSelection,
+} from '#db/pending-selections.js';
+
+const PENDING_SELECTION_TTL_MS = 30 * 60 * 1000;
+const ACCESS_TOKEN_KEY = 'ACCESS_TOKEN';
+const REFRESH_TOKEN_KEY = 'REFRESH_TOKEN';
+const TOKEN_EXPIRES_AT_KEY = 'TOKEN_EXPIRES_AT';
+
+export interface JiraPendingSelectionSecretsStore {
+  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>;
+  deleteSecrets(params: {workspaceId: string; namespace: string}): Promise<number>;
+}
+
+export interface JiraPendingSelectionStore {
+  save(params: {
+    workspaceId: string;
+    state: string;
+    authorization: JiraAuthorization;
+    sites: JiraAccessibleResource[];
+  }): Promise<void>;
+  load(params: {
+    workspaceId: string;
+    state: string;
+  }): Promise<{authorization: JiraAuthorization; sites: JiraAccessibleResource[]} | undefined>;
+  clear(params: {workspaceId: string; state: string}): Promise<void>;
+  pruneExpiredPendingSelections(now: Date): Promise<void>;
+}
+
+export function jiraPendingSecretsNamespace(state: string): string {
+  return `system/integrations/jira/pending/${stateHash(state)}`;
+}
+
+export function createJiraPendingSelectionStore(params: {
+  secrets: JiraPendingSelectionSecretsStore;
+}): JiraPendingSelectionStore {
+  async function clear(input: {workspaceId: string; state: string}): Promise<void> {
+    const hash = stateHash(input.state);
+    await Promise.all([
+      deleteJiraPendingSelection({stateHash: hash, workspaceId: input.workspaceId}),
+      params.secrets.deleteSecrets({
+        workspaceId: input.workspaceId,
+        namespace: jiraPendingSecretsNamespace(input.state),
+      }),
+    ]);
+  }
+
+  return {
+    async save(input) {
+      const expiresAt = new Date(Date.now() + PENDING_SELECTION_TTL_MS);
+      const values: Record<string, string> = {[ACCESS_TOKEN_KEY]: input.authorization.accessToken};
+      if (input.authorization.refreshToken)
+        values[REFRESH_TOKEN_KEY] = input.authorization.refreshToken;
+      if (input.authorization.expiresAt)
+        values[TOKEN_EXPIRES_AT_KEY] = input.authorization.expiresAt.toISOString();
+      await params.secrets.setSecrets({
+        workspaceId: input.workspaceId,
+        namespace: jiraPendingSecretsNamespace(input.state),
+        values,
+      });
+      await saveJiraPendingSelection({
+        stateHash: stateHash(input.state),
+        workspaceId: input.workspaceId,
+        expiresAt,
+        sites: input.sites,
+      });
+    },
+
+    async load(input) {
+      const pending = await getJiraPendingSelection({
+        stateHash: stateHash(input.state),
+        workspaceId: input.workspaceId,
+      });
+      if (!pending) return undefined;
+      if (pending.expiresAt < new Date()) {
+        await clear(input);
+        return undefined;
+      }
+      const namespace = jiraPendingSecretsNamespace(input.state);
+      const [accessToken, refreshToken, tokenExpiresAt] = await Promise.all([
+        params.secrets.getSecret({
+          workspaceId: input.workspaceId,
+          namespace,
+          key: ACCESS_TOKEN_KEY,
+        }),
+        params.secrets.getSecret({
+          workspaceId: input.workspaceId,
+          namespace,
+          key: REFRESH_TOKEN_KEY,
+        }),
+        params.secrets.getSecret({
+          workspaceId: input.workspaceId,
+          namespace,
+          key: TOKEN_EXPIRES_AT_KEY,
+        }),
+      ]);
+      if (!accessToken || !refreshToken) {
+        await clear(input);
+        return undefined;
+      }
+      const expiresAt = tokenExpiresAt ? new Date(tokenExpiresAt) : undefined;
+      return {
+        authorization: {
+          accessToken,
+          refreshToken,
+          expiresAt: expiresAt && !Number.isNaN(expiresAt.getTime()) ? expiresAt : undefined,
+          scopes: [],
+        },
+        sites: pending.sites,
+      };
+    },
+
+    clear,
+
+    async pruneExpiredPendingSelections(now) {
+      const expired = await listExpiredJiraPendingSelections(now);
+      await Promise.all(
+        expired.map(async (pending) => {
+          await params.secrets.deleteSecrets({
+            workspaceId: pending.workspaceId,
+            namespace: `system/integrations/jira/pending/${pending.stateHash}`,
+          });
+          await deleteJiraPendingSelection({
+            stateHash: pending.stateHash,
+            workspaceId: pending.workspaceId,
+          });
+        }),
+      );
+    },
+  };
+}
+
+function stateHash(state: string): string {
+  return createHash('sha256').update(state).digest('hex');
+}

package/src/core/scopes.test.ts

@@ -0,0 +1,19 @@
+import {JiraAuthorizationScopeMismatchError} from './errors.js';
+import {assertJiraAuthorizationScopes, formatJiraOAuthScopes, JIRA_OAUTH_SCOPES} from './scopes.js';
+
+describe('Jira OAuth scopes', () => {
+  it('formats the requested classic scopes and accepts both classic and granular site scopes', () => {
+    const classic = () => assertJiraAuthorizationScopes(['read:jira-work']);
+    const granular = () => assertJiraAuthorizationScopes(['read:issue:jira']);
+
+    expect(formatJiraOAuthScopes()).toBe(JIRA_OAUTH_SCOPES.join(' '));
+    expect(classic).not.toThrow();
+    expect(granular).not.toThrow();
+  });
+
+  it('rejects an unusable accessible-resource scope list', () => {
+    const result = () => assertJiraAuthorizationScopes([]);
+
+    expect(result).toThrow(JiraAuthorizationScopeMismatchError);
+  });
+});

package/src/core/scopes.ts

@@ -0,0 +1,20 @@
+import {logger} from '@shipfox/node-opentelemetry';
+import {JiraAuthorizationScopeMismatchError} from './errors.js';
+
+export const JIRA_OAUTH_SCOPES = [
+  'read:jira-work',
+  'write:jira-work',
+  'read:jira-user',
+  'manage:jira-webhook',
+  'offline_access',
+] as const;
+
+export function formatJiraOAuthScopes(): string {
+  return JIRA_OAUTH_SCOPES.join(' ');
+}
+
+export function assertJiraAuthorizationScopes(scopes: readonly string[]): void {
+  const usableScopes = scopes.filter((scope) => scope.trim().length > 0);
+  if (usableScopes.length === 0) throw new JiraAuthorizationScopeMismatchError(['site scopes']);
+  logger().info({scopes: usableScopes}, 'Jira site authorization scopes granted');
+}

package/src/core/state.test.ts

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

package/src/core/state.ts

@@ -0,0 +1,79 @@
+import {createHmac, randomUUID, timingSafeEqual} from 'node:crypto';
+import {config} from '#config.js';
+import {JiraInstallStateError} from './errors.js';
+
+const STATE_TTL_SECONDS = 30 * 60;
+
+interface JiraInstallStatePayload {
+  workspaceId: string;
+  userId: string;
+  nonce: string;
+  expiresAt: number;
+}
+
+export interface JiraInstallStateClaims {
+  workspaceId: string;
+  userId: string;
+}
+
+export function signJiraInstallState(params: {
+  workspaceId: string;
+  userId: string;
+  nonce?: string | undefined;
+  now?: Date | undefined;
+}): string {
+  const now = params.now ?? new Date();
+  const payload: JiraInstallStatePayload = {
+    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 verifyJiraInstallState(
+  state: string,
+  now: Date = new Date(),
+): JiraInstallStateClaims {
+  const [encodedPayload, signature, extra] = state.split('.');
+  if (!encodedPayload || !signature || extra !== undefined) throw new JiraInstallStateError();
+  if (!constantTimeEqual(signature, sign(encodedPayload))) {
+    throw new JiraInstallStateError('Invalid Jira install state signature');
+  }
+  const payload = parsePayload(encodedPayload);
+  if (payload.expiresAt < Math.floor(now.getTime() / 1000)) {
+    throw new JiraInstallStateError('Expired Jira install state');
+  }
+  return {workspaceId: payload.workspaceId, userId: payload.userId};
+}
+
+function sign(encodedPayload: string): string {
+  return createHmac('sha256', config.JIRA_OAUTH_CLIENT_SECRET)
+    .update(encodedPayload)
+    .digest('base64url');
+}
+
+function constantTimeEqual(a: string, b: string): boolean {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+function parsePayload(encodedPayload: string): JiraInstallStatePayload {
+  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 {
+    throw new JiraInstallStateError('Invalid Jira install state payload');
+  }
+}

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

@@ -0,0 +1,106 @@
+const {getInstallation, updateExpiry, withRefreshLock} = vi.hoisted(() => ({
+  getInstallation: vi.fn(),
+  updateExpiry: vi.fn(),
+  withRefreshLock: vi.fn(async (_connectionId: string, fn: () => Promise<string>) => ({
+    acquired: true as const,
+    value: await fn(),
+  })),
+}));
+
+vi.mock('#db/installations.js', () => ({
+  getJiraInstallationByConnectionId: getInstallation,
+  updateJiraInstallationTokenExpiry: updateExpiry,
+  withJiraRefreshLock: withRefreshLock,
+}));
+
+import {JiraIntegrationProviderError, JiraTokenUnrefreshableError} from './errors.js';
+import {createJiraTokenStore} from './tokens.js';
+
+function createStore() {
+  const values = new Map<string, string>();
+  const secrets = {
+    getSecret: vi.fn(async ({key}: {key: string}) => values.get(key) ?? null),
+    setSecrets: vi.fn(({values: next}: {values: Record<string, string>}) => {
+      for (const [key, value] of Object.entries(next)) values.set(key, value);
+      return Promise.resolve();
+    }),
+  };
+  const client = {
+    exchangeAuthorizationCode: vi.fn(),
+    refreshAccessToken: vi.fn(),
+    getAccessibleResources: vi.fn(),
+    getMyself: vi.fn(),
+  };
+  const markConnectionError = vi.fn().mockResolvedValue(undefined);
+  const connectionId = crypto.randomUUID();
+  const store = createJiraTokenStore({
+    resolveConnection: vi.fn().mockResolvedValue({workspaceId: crypto.randomUUID()}),
+    secrets,
+    client,
+    markConnectionError,
+  });
+  return {client, connectionId, markConnectionError, secrets, store, values};
+}
+
+describe('Jira token refresh', () => {
+  beforeEach(() => {
+    getInstallation.mockResolvedValue({tokenExpiresAt: new Date(0)});
+    updateExpiry.mockResolvedValue(undefined);
+    withRefreshLock.mockImplementation(async (_connectionId, fn) => ({
+      acquired: true,
+      value: await fn(),
+    }));
+  });
+
+  it('rotates and persists both tokens when the access token expires', async () => {
+    const {client, connectionId, secrets, store, values} = createStore();
+    await store.storeTokens({connectionId, accessToken: 'access-0', refreshToken: 'refresh-0'});
+    client.refreshAccessToken.mockResolvedValue({
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+      expiresAt: new Date('2030-01-01'),
+      scopes: ['read:jira-work'],
+    });
+
+    const result = await store.getAccessToken({connectionId});
+
+    expect(result).toBe('access-1');
+    expect(client.refreshAccessToken).toHaveBeenCalledWith({refreshToken: 'refresh-0'});
+    expect(values.get('ACCESS_TOKEN')).toBe('access-1');
+    expect(values.get('REFRESH_TOKEN')).toBe('refresh-1');
+    expect(secrets.setSecrets).toHaveBeenCalledTimes(2);
+    expect(updateExpiry).toHaveBeenCalledWith(expect.objectContaining({connectionId}));
+  });
+
+  it('marks only credential failures as connection errors', async () => {
+    const {client, connectionId, markConnectionError, store} = createStore();
+    await store.storeTokens({connectionId, accessToken: 'access-0', refreshToken: 'refresh-0'});
+    client.refreshAccessToken.mockRejectedValue(
+      new JiraIntegrationProviderError('access-denied', 'invalid grant'),
+    );
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toBeInstanceOf(JiraIntegrationProviderError);
+    expect(markConnectionError).toHaveBeenCalledWith({connectionId});
+  });
+
+  it('requires a refresh token once the access token expires', async () => {
+    const {connectionId, store} = createStore();
+    await store.storeTokens({connectionId, accessToken: 'access-0'});
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toBeInstanceOf(JiraTokenUnrefreshableError);
+  });
+
+  it('does not return an expired token when another process owns the refresh lock', async () => {
+    const {connectionId, store} = createStore();
+    await store.storeTokens({connectionId, accessToken: 'access-0', refreshToken: 'refresh-0'});
+    withRefreshLock.mockResolvedValue({acquired: false} as never);
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toMatchObject({reason: 'provider-unavailable'});
+  });
+});

package/src/core/tokens.test.ts

@@ -8,8 +8,8 @@ import {
 
 let secrets: JiraSecretsStore;
 
-beforeAll(async () => {
-  secrets = await import('@shipfox/api-secrets');
+beforeEach(() => {
+  secrets = createInMemorySecretsStore();
 });
 
 function createConnectionContext() {
@@ -35,6 +35,20 @@ function storedToken(input: {
   });
 }
 
+function createInMemorySecretsStore(): JiraSecretsStore {
+  const values = new Map<string, string>();
+  const id = (params: {workspaceId: string; namespace: string; key: string}) =>
+    `${params.workspaceId}\0${params.namespace}\0${params.key}`;
+  return {
+    getSecret: async (params) => values.get(id(params)) ?? null,
+    setSecrets: async (params) => {
+      await Promise.resolve();
+      for (const [key, value] of Object.entries(params.values))
+        values.set(id({...params, key}), value);
+    },
+  };
+}
+
 describe('createJiraTokenStore.storeTokens', () => {
   it('stores access and refresh tokens in the Jira system namespace', async () => {
     const {workspaceId, connectionId, store} = createConnectionContext();