bug: Contact extraction fails after Google OAuth consent

[baderdean]

Summary

Contact extraction breaks after the user grants Google OAuth consent. The extraction process does not properly handle the post-consent flow.

Tasks

• Reproduce the bug: trigger contact extraction after Google consent
• Identify the root cause in the extraction pipeline
• Design and implement a fix
• Add tests to prevent regression

Context

Bug identified on 2026-03-25. Design approach was being discussed but not finalized. The issue affects the Google mining source flow where contacts should be extracted after the user grants consent.

Acceptance Criteria

• Contact extraction completes successfully after Google OAuth consent
• No data loss or partial extraction
• Error handling covers consent-related edge cases

[baderdean]

Implementation Plan

Problem

Contact extraction breaks after user grants Google OAuth consent. Pipeline analysis reveals 3 root causes.

Root Causes

Cause 1 — Email matching too strict (high probability)

mining.controller.ts:399-415 looks for a Google source with s.type === 'google' && s.email === sanitizedEmail where sanitizedEmail is the IMAP source email. If the user's Google account email differs from their IMAP email → googleSource is undefined → 403 error "Google Contacts: OAuth permissions not granted".

Cause 2 — refreshToken potentially undefined (medium probability)

GoogleContactsFetchTask.ts:79: this.refreshToken ?? '' — if the refresh token wasn't persisted correctly in the OAuth callback, an empty string is sent to the microservice, causing the People API call to fail.

Cause 3 — Fresh token not refreshed by fetch-mining-source (low probability)

fetch-mining-source/index.ts:216-218 uses isTokenExpired(credentials) to decide on refresh. If the token is freshly obtained and valid (not expired), but scopes don't cover contacts, no refresh occurs and the People API call fails.

Step 1 — Fix Google source matching in mining.controller.ts

// Lines 399-415 — Replace strict matching with fallback
let googleContactsCredentials;
if (googleContactsSync) {
  const allSources = await miningSourceService.getSourcesForUser(user.id);
  
  // 1. Try exact email match
  let googleSource = allSources.find(
    (s) => s.type === 'google' && s.email === sanitizedEmail
  );
  
  // 2. Fallback to any Google source if no exact match
  if (!googleSource) {
    googleSource = allSources.find((s) => s.type === 'google');
    if (googleSource) {
      logger.info(
        'Fell back to Google source with different email for contacts sync',
        { imapEmail: sanitizedEmail, googleEmail: googleSource.email }
      );
    }
  }
  
  // 3. Validate credentials
  if (googleSource?.credentials && 'accessToken' in googleSource.credentials) {
    googleContactsCredentials = {
      accessToken: googleSource.credentials.accessToken,
      refreshToken: googleSource.credentials.refreshToken,
      userEmail: sanitizedEmail
    };
  }
}

Step 2 — Validate refreshToken in GoogleContactsFetchTask.ts

// Lines 66-82 — Add validation before calling fetcher
async start(): Promise<TaskResult> {
  if (!this.refreshToken) {
    logger.error('Missing refresh token for Google Contacts sync', {
      miningId: this.miningId,
      userEmail: this.userEmail
    });
    return {
      success: false,
      error: 'Missing refresh token — user must re-authenticate with Google'
    };
  }

  const result = await this.fetcherClient.startGoogleContactsSync({
    miningId: this.miningId,
    contactStream: this.outputStream,
    userId: this.userId,
    userEmail: this.userEmail,
    accessToken: this.accessToken,
    refreshToken: this.refreshToken  // no more ?? ''
  });
  // ...
}

Step 3 — Add diagnostic logging in OAuth callback

// mining.controller.ts:221-231 — Log received tokens
const exchangedTokens = await exchangeForToken(code, provider);

logger.info('OAuth token exchange result', {
  userId,
  provider,
  email: exchangedTokens.email,
  hasAccessToken: !!exchangedTokens.accessToken,
  hasRefreshToken: !!exchangedTokens.refreshToken,
  hasExpiresAt: !!exchangedTokens.expiresAt
});

Step 4 — Add unit test for fallback behavior

File: backend/test/unit/mining/googleContactsFallback.test.ts

• Test case where Google email differs from IMAP email → extraction succeeds
• Test case where no Google source exists → 403 returned
• Test case where exact email matches → no fallback needed

Files

File	Action
backend/src/controllers/mining.controller.ts	Modify — lines 399-427 (fallback matching + logging)
backend/src/services/tasks-manager-v2/tasks/GoogleContactsFetchTask.ts	Modify — line 79 (validate refreshToken)
backend/test/unit/mining/googleContactsFallback.test.ts	Create — fallback test

Acceptance Criteria

• Google Contacts extraction succeeds even when Google email ≠ IMAP email
• Clear error message in logs when refresh token is missing
• No regression when emails match exactly
• No crash if Google source doesn't exist at all (403 preserved)
• Unit tests cover new fallback behavior

[baderdean]

Implementation Plan

Problem

Contact extraction breaks after user grants Google OAuth consent. Pipeline analysis reveals 3 root causes.

Root Causes

Cause 1 — Email matching too strict (high probability)

mining.controller.ts:399-415 looks for a Google source with s.type === 'google' && s.email === sanitizedEmail where sanitizedEmail is the IMAP source email. If the user's Google account email differs from their IMAP email → googleSource is undefined → 403 error "Google Contacts: OAuth permissions not granted".

Cause 2 — refreshToken potentially undefined (medium probability)

GoogleContactsFetchTask.ts:79: this.refreshToken ?? '' — if the refresh token wasn't persisted correctly in the OAuth callback, an empty string is sent to the microservice, causing the People API call to fail.

Cause 3 — Fresh token not refreshed by fetch-mining-source (low probability)

fetch-mining-source/index.ts:216-218 uses isTokenExpired(credentials) to decide on refresh. If the token is freshly obtained and valid (not expired), but scopes don't cover contacts, no refresh occurs and the People API call fails.

Step 1 — Fix Google source matching in mining.controller.ts

// Lines 399-415 — Replace strict matching with fallback
let googleContactsCredentials;
if (googleContactsSync) {
  const allSources = await miningSourceService.getSourcesForUser(user.id);
  
  // 1. Try exact email match
  let googleSource = allSources.find(
    (s) => s.type === 'google' && s.email === sanitizedEmail
  );
  
  // 2. Fallback to any Google source if no exact match
  if (!googleSource) {
    googleSource = allSources.find((s) => s.type === 'google');
    if (googleSource) {
      logger.info(
        'Fell back to Google source with different email for contacts sync',
        { imapEmail: sanitizedEmail, googleEmail: googleSource.email }
      );
    }
  }
  
  // 3. Validate credentials
  if (googleSource?.credentials && 'accessToken' in googleSource.credentials) {
    googleContactsCredentials = {
      accessToken: googleSource.credentials.accessToken,
      refreshToken: googleSource.credentials.refreshToken,
      userEmail: sanitizedEmail
    };
  }
}

Step 2 — Validate refreshToken in GoogleContactsFetchTask.ts

// Lines 66-82 — Add validation before calling fetcher
async start(): Promise<TaskResult> {
  if (!this.refreshToken) {
    logger.error('Missing refresh token for Google Contacts sync', {
      miningId: this.miningId,
      userEmail: this.userEmail
    });
    return {
      success: false,
      error: 'Missing refresh token — user must re-authenticate with Google'
    };
  }

  const result = await this.fetcherClient.startGoogleContactsSync({
    miningId: this.miningId,
    contactStream: this.outputStream,
    userId: this.userId,
    userEmail: this.userEmail,
    accessToken: this.accessToken,
    refreshToken: this.refreshToken  // no more ?? ''
  });
  // ...
}

Step 3 — Add diagnostic logging in OAuth callback

// mining.controller.ts:221-231 — Log received tokens
const exchangedTokens = await exchangeForToken(code, provider);

logger.info('OAuth token exchange result', {
  userId,
  provider,
  email: exchangedTokens.email,
  hasAccessToken: !!exchangedTokens.accessToken,
  hasRefreshToken: !!exchangedTokens.refreshToken,
  hasExpiresAt: !!exchangedTokens.expiresAt
});

Step 4 — Add unit test for fallback behavior

File: backend/test/unit/mining/googleContactsFallback.test.ts

• Test case where Google email differs from IMAP email → extraction succeeds
• Test case where no Google source exists → 403 returned
• Test case where exact email matches → no fallback needed

Files

File	Action
backend/src/controllers/mining.controller.ts	Modify — lines 399-427 (fallback matching + logging)
backend/src/services/tasks-manager-v2/tasks/GoogleContactsFetchTask.ts	Modify — line 79 (validate refreshToken)
backend/test/unit/mining/googleContactsFallback.test.ts	Create — fallback test

Acceptance Criteria

• Google Contacts extraction succeeds even when Google email ≠ IMAP email
• Clear error message in logs when refresh token is missing
• No regression when emails match exactly
• No crash if Google source doesn't exist at all (403 preserved)
• Unit tests cover new fallback behavior