Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.2 KB
Raw Blame
/**
 * #7004/#7073: which account a Google credential belongs to, and which of the
 * Gmail, Calendar and People APIs it can reach.
 *
 * `probeGoogleAccount` asks each enabled service to name the account (Gmail
 * profile, Calendar primary calendar) and, when none can, the OAuth userinfo
 * endpoint (the `email` scope is always requested). People only proves the
 * token reaches the API by listing one connection (#7490): `people/me`
 * needs the `profile` scope, which connect never requests. Every
 * per-service failure stays in the result: the managed sync uses the first
 * address it finds, while `gbrain google setup` and `gbrain google status`
 * probe every service and name each disabled API or missing scope at once.
 */
import { CredentialError } from '../creds/errors.ts';
import { GOOGLE_SERVICE_SCOPES, fetchUserinfoEmail } from '../creds/providers/google.ts';
import type { Action } from '../agent-output.ts';
import type { GoogleAccessProvider } from './access.ts';
import { CalendarClient, GmailClient, GoogleApiDisabledError, PeopleClient, type FetchImpl } from './google-clients.ts';
import { ALL_GOOGLE_SERVICES, GOOGLE_SERVICE_API, type GoogleApiProblem, type GoogleService } from './types.ts';

export interface GoogleIdentityClients {
  gmail: Pick<GmailClient, 'getProfile'>;
  calendar: Pick<CalendarClient, 'fetchJSON'>;
  people: Pick<PeopleClient, 'fetchJSON'>;
  userinfo: () => Promise<string | undefined>;
}

export interface GoogleAccountProbe {
  /** Lower-cased address, or null when nothing named the account. */
  email: string | null;
  via: GoogleService | 'userinfo' | null;
  /** Each attempt that threw, in attempt order. */
  errors: Partial<Record<GoogleService | 'userinfo', unknown>>;
}

/** The clients a probe needs for one token source. */
export function googleIdentityClients(tokens: GoogleAccessProvider, clientId: string | undefined, fetchImpl: FetchImpl = fetch): GoogleIdentityClients {
  const args = [tokens, fetchImpl, () => {}, clientId] as const;
  return { gmail: new GmailClient(...args), calendar: new CalendarClient(...args), people: new PeopleClient(...args), userinfo: googleUserinfo(tokens, fetchImpl) };
}

export function googleUserinfo(tokens: GoogleAccessProvider, fetchImpl: FetchImpl = fetch): () => Promise<string> {
  return async () => fetchUserinfoEmail(await tokens.getAccessToken(), fetchImpl);
}

/**
 * Each listed service in order, stopping at the first address unless `every`
 * is set; userinfo only when no service named the account. Aborts propagate;
 * every other failure is recorded under its attempt.
 */
export async function probeGoogleAccount(clients: GoogleIdentityClients, services: readonly GoogleService[],
  opts: { signal?: AbortSignal; every?: boolean } = {}): Promise<GoogleAccountProbe> {
  const { signal } = opts;
  const request = signal ? { signal } : {};
  const attempts: Array<[GoogleService | 'userinfo', () => Promise<string | undefined>]> = [
    ['gmail', async () => (await clients.gmail.getProfile(request)).emailAddress],
    ['calendar', async () => (await clients.calendar.fetchJSON<{ id?: string }>('https://www.googleapis.com/calendar/v3/calendars/primary', 'calendar-json', request)).id],
    ['contacts', async () => {
      await clients.people.fetchJSON('https://people.googleapis.com/v1/people/me/connections?pageSize=1&personFields=emailAddresses', 'people', request);
      return undefined;
    }],
    ['userinfo', clients.userinfo],
  ];
  const probe: GoogleAccountProbe = { email: null, via: null, errors: {} };
  for (const [attempt, run] of attempts) {
    if (attempt === 'userinfo' ? probe.email !== null : !services.includes(attempt)) continue;
    signal?.throwIfAborted();
    try {
      const email = (await run())?.trim().toLowerCase();
      if (email?.includes('@') && probe.email === null) {
        probe.email = email;
        probe.via = attempt;
        if (!opts.every) return probe;
      }
    } catch (error) {
      if (signal?.aborted) throw error;
      probe.errors[attempt] = error;
    }
  }
  return probe;
}

/** The problem behind one service failure, or null when the failure is something else. */
export function googleApiProblem(service: GoogleService, error: unknown): GoogleApiProblem | null {
  if (error instanceof GoogleApiDisabledError) {
    return { service, code: 'api_not_enabled', api: error.api, api_title: error.apiTitle, project: error.project, enable_url: error.enableUrl };
  }
  if (error instanceof CredentialError && error.code === 'scope_missing') {
    return { service, code: 'scope_missing', api: GOOGLE_SERVICE_API[service].api, api_title: GOOGLE_SERVICE_API[service].title, project: null, enable_url: null };
  }
  return null;
}

export interface GoogleApiAccessReport {
  account: string;
  /** The address the probe resolved, and how; null when nothing named the account. */
  resolved_account: string | null;
  resolved_via: GoogleAccountProbe['via'];
  services: Partial<Record<GoogleService, { status: 'ok' | GoogleApiProblem['code'] | 'error'; error?: string }>>;
  problems: GoogleApiProblem[];
  fix?: Action;
}

/**
 * Probe every service in `services`: one not in a known grant is
 * `scope_missing` without a request; the rest are read live.
 */
export async function probeGoogleApiAccess(clients: GoogleIdentityClients, account: string, services: readonly GoogleService[],
  grantedScopes: readonly string[], signal?: AbortSignal): Promise<GoogleApiAccessReport> {
  const ordered = ALL_GOOGLE_SERVICES.filter(service => services.includes(service));
  const ungranted = grantedScopes.length > 0 ? ordered.filter(service => !grantedScopes.includes(GOOGLE_SERVICE_SCOPES[service])) : [];
  const probe = await probeGoogleAccount(clients, ordered.filter(service => !ungranted.includes(service)), { every: true, ...(signal ? { signal } : {}) });
  const report: GoogleApiAccessReport = { account, resolved_account: probe.email, resolved_via: probe.via, services: {}, problems: [] };
  for (const service of ordered) {
    const problem = ungranted.includes(service) ? googleApiProblem(service, new CredentialError('scope_missing')) : googleApiProblem(service, probe.errors[service]);
    const error = probe.errors[service];
    if (problem) report.problems.push(problem);
    report.services[service] = problem ? { status: problem.code }
      : error === undefined ? { status: 'ok' } : { status: 'error', error: error instanceof Error ? error.message : String(error) };
  }
  if (report.problems.length > 0) report.fix = googleApiAccessFix(account, report.problems);
  return report;
}

/**
 * One fix naming every problem: enabling an API is the user's step in the
 * Cloud console (`ask_user` with each link); a missing grant alone is the
 * user's reauth command (`tell_user_to_run`).
 */
export function googleApiAccessFix(account: string, problems: readonly GoogleApiProblem[]): Action {
  const verify = ['gbrain', 'google', 'status', '--json'];
  const disabled = problems.filter(problem => problem.code === 'api_not_enabled');
  const ungranted = problems.filter(problem => problem.code === 'scope_missing');
  const reauth = ['gbrain', 'google', 'connect', '--reauth', account];
  const steps = [
    ...disabled.map(problem => `enable the ${problem.api_title} (${problem.api}) for Google Cloud project ${problem.project ?? 'that owns the OAuth client'}: ${problem.enable_url}`),
    ...(ungranted.length ? [`grant ${ungranted.map(problem => problem.service).join(', ')} access: ${reauth.join(' ')}`] : []),
  ];
  const userMessage = `Google account ${account} cannot reach ${problems.map(problem => problem.service).join(', ')}. To fix it, ${steps.join('; ')}. `
    + `Then re-check with: ${verify.join(' ')}`;
  const shared = { consent: [], actor: 'user' as const, user_message: userMessage, verify: { argv: verify }, docs: 'docs/guides/google-connect.md#api-access', requires_exclusive: false };
  if (disabled.length > 0) {
    return { ask_user: true, ...shared,
      why: `${disabled.map(problem => problem.api_title).join(', ')} ${disabled.length === 1 ? 'is' : 'are'} disabled for the OAuth client's Google Cloud project; only the project owner can enable ${disabled.length === 1 ? 'it' : 'them'} in the console.` };
  }
  return { argv: reauth, ...shared, why: `The credential was granted without the ${ungranted.map(problem => problem.service).join(', ')} scope; a reauth asks the user to grant it.` };
}