@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/safe-tooling/external-filesystem.ts

@@ -0,0 +1,304 @@
+import { createHash } from 'crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'fs';
+import { basename, dirname, join, relative, resolve } from 'path';
+
+export type ExternalFilesystemGrantMode = 'read' | 'copy_into_repo';
+
+export interface ExternalFilesystemGrant {
+  schemaVersion: 1;
+  key: string;
+  root: string;
+  canonicalRoot: string;
+  mode: ExternalFilesystemGrantMode;
+  reason: string;
+  createdAt: string;
+  createdBy: string;
+  expiresAt?: string;
+}
+
+export interface ExternalFilesystemGrantFile {
+  schemaVersion: 1;
+  updatedAt: string;
+  grants: ExternalFilesystemGrant[];
+}
+
+export interface ExternalFilesystemGrantPreview {
+  schemaVersion: 1;
+  previewTicketId: string;
+  accepted: boolean;
+  key: string;
+  root: string;
+  canonicalRoot?: string;
+  mode: ExternalFilesystemGrantMode;
+  reason: string;
+  expiresAt?: string;
+  risk: 'readonly' | 'denied';
+  denialReason?: string;
+  next: string;
+  safety: {
+    arbitraryPathRead: false;
+    requiresApply: true;
+    secretsPersisted: false;
+    repositorySourceMutation: false;
+  };
+}
+
+export interface ExternalFilesystemSnapshot {
+  targetKey: string;
+  relativePath: string;
+  absolutePathPreview: string;
+  kind: 'file' | 'directory';
+  truncated: boolean;
+  entries?: Array<{ name: string; kind: 'file' | 'directory' | 'other'; size?: number }>;
+  text?: string;
+  byteLength?: number;
+  safety: {
+    grantMode: ExternalFilesystemGrantMode;
+    boundedToGrant: true;
+    writeAllowed: false;
+  };
+}
+
+const CONFIG_PATH = '.forge/external-filesystem-grants.json';
+const DEFAULT_MAX_CHARS = 16_000;
+const MAX_CHARS = 128_000;
+
+function now(): string { return new Date().toISOString(); }
+
+function configPath(repoRoot: string): string {
+  return join(repoRoot, CONFIG_PATH);
+}
+
+function stableTicket(input: Record<string, unknown>): string {
+  return `EFG-${createHash('sha256').update(JSON.stringify(input)).digest('hex').slice(0, 16)}`;
+}
+
+function normalizeKey(value: unknown): string {
+  const raw = String(value ?? '').trim().toLowerCase().replace(/[^a-z0-9_.-]+/g, '_').replace(/^_+|_+$/g, '');
+  if (!raw || raw === '.' || raw === '..' || raw.length > 64) throw new Error('EXTERNAL_FS_KEY_INVALID: grant_key must be 1-64 safe characters');
+  return raw;
+}
+
+function normalizeMode(value: unknown): ExternalFilesystemGrantMode {
+  if (value === undefined || value === null || value === 'read') return 'read';
+  if (value === 'copy_into_repo') return 'copy_into_repo';
+  throw new Error('EXTERNAL_FS_MODE_UNSUPPORTED: only read and copy_into_repo modes are supported in this tool surface');
+}
+
+function expiryFromArgs(value: unknown): string {
+  const minutes = typeof value === 'number' && Number.isFinite(value)
+    ? Math.max(1, Math.min(Math.trunc(value), 24 * 60))
+    : 8 * 60;
+  return new Date(Date.now() + minutes * 60_000).toISOString();
+}
+
+export function externalFilesystemGrantExpired(grant: Pick<ExternalFilesystemGrant, 'expiresAt'>, at = new Date()): boolean {
+  if (!grant.expiresAt) return false;
+  const expires = Date.parse(grant.expiresAt);
+  return !Number.isFinite(expires) || expires <= at.getTime();
+}
+
+function userHome(): string | undefined {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  return home ? resolve(home) : undefined;
+}
+
+function denyReason(canonical: string, repoRoot: string): string | undefined {
+  const normalized = resolve(canonical);
+  const home = userHome();
+  const repo = resolve(repoRoot);
+  const sensitiveExact = new Set(['/','/etc','/private/etc','/System','/Library','/Applications','/Users','/home','/var','/private/var']);
+  if (sensitiveExact.has(normalized)) return 'Grant root is too broad or system-owned.';
+  if (home && normalized === home) return 'Grant root is the whole user home; choose a narrower project/data directory.';
+  const lower = normalized.toLowerCase();
+  const sensitiveFragments = [
+    '/.ssh',
+    '/.gnupg',
+    '/library/keychains',
+    '/library/mail',
+    '/library/messages',
+    '/library/application support/com.apple',
+    '/library/application support/google/chrome/default/cookies',
+    '/library/application support/google/chrome/default/network/cookies',
+    '/library/application support/firefox/profiles',
+    '/library/application support/1password',
+    '/library/group containers/2bua8c4s2c.com.1password',
+    '/.aws',
+    '/.config/gcloud',
+    '/.kube',
+    '/id_rsa',
+    '/id_dsa',
+    '/id_ecdsa',
+    '/id_ed25519',
+  ];
+  if (sensitiveFragments.some((fragment) => lower.includes(fragment))) return 'Grant root appears to contain credentials or personal application data.';
+  const repoRel = relative(repo, normalized);
+  if (!repoRel.startsWith('..') && repoRel !== '') return 'Path is inside the repository; use repository file tools instead of an external filesystem grant.';
+  return undefined;
+}
+
+function canonicalizeRoot(repoRoot: string, rootPath: unknown): { input: string; canonical?: string; denialReason?: string } {
+  const input = String(rootPath ?? '').trim();
+  if (!input) return { input, denialReason: 'root_path is required.' };
+  if (!input.startsWith('/')) return { input, denialReason: 'Only absolute local paths can be previewed for external grants.' };
+  try {
+    if (!existsSync(input)) return { input, denialReason: 'Path does not exist.' };
+    const canonical = realpathSync(input);
+    const stat = lstatSync(canonical);
+    if (!stat.isDirectory()) return { input, denialReason: 'Only directory grants are supported.' };
+    return { input, canonical, denialReason: denyReason(canonical, repoRoot) };
+  } catch (error) {
+    return { input, denialReason: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export function loadExternalFilesystemGrants(repoRoot: string): ExternalFilesystemGrantFile {
+  const path = configPath(repoRoot);
+  if (!existsSync(path)) return { schemaVersion: 1, updatedAt: now(), grants: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Partial<ExternalFilesystemGrantFile>;
+    return {
+      schemaVersion: 1,
+      updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : now(),
+      grants: Array.isArray(parsed.grants) ? parsed.grants.filter((grant): grant is ExternalFilesystemGrant => Boolean(grant && typeof grant.key === 'string' && typeof grant.canonicalRoot === 'string')) : [],
+    };
+  } catch {
+    return { schemaVersion: 1, updatedAt: now(), grants: [] };
+  }
+}
+
+function saveExternalFilesystemGrants(repoRoot: string, file: ExternalFilesystemGrantFile): ExternalFilesystemGrantFile {
+  const path = configPath(repoRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  const updated = { schemaVersion: 1 as const, updatedAt: now(), grants: file.grants.sort((a, b) => a.key.localeCompare(b.key)) };
+  writeFileSync(path, `${JSON.stringify(updated, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  return updated;
+}
+
+export function previewExternalFilesystemGrant(repoRoot: string, args: Record<string, unknown>): ExternalFilesystemGrantPreview {
+  const key = normalizeKey(args.grant_key ?? args.target_key ?? args.key);
+  const mode = normalizeMode(args.mode);
+  const reason = String(args.reason ?? '').trim();
+  const expiresAt = expiryFromArgs(args.expires_in_minutes);
+  const root = canonicalizeRoot(repoRoot, args.root_path ?? args.root);
+  const accepted = !root.denialReason && Boolean(reason);
+  const previewTicketId = stableTicket({ key, canonicalRoot: root.canonical, mode, reason });
+  return {
+    schemaVersion: 1,
+    previewTicketId,
+    accepted,
+    key,
+    root: root.input,
+    canonicalRoot: root.canonical,
+    mode,
+    reason,
+    expiresAt,
+    risk: accepted ? 'readonly' : 'denied',
+    denialReason: !reason ? 'A reason is required for auditability.' : root.denialReason,
+    next: accepted
+      ? 'Call external_filesystem_grant_apply with this preview_ticket_id and confirm_authorization=true.'
+      : 'Choose a narrower existing directory and include an audit reason.',
+    safety: {
+      arbitraryPathRead: false,
+      requiresApply: true,
+      secretsPersisted: false,
+      repositorySourceMutation: false,
+    },
+  };
+}
+
+export function applyExternalFilesystemGrant(repoRoot: string, args: Record<string, unknown>): { grant: ExternalFilesystemGrant; file: ExternalFilesystemGrantFile; preview: ExternalFilesystemGrantPreview } {
+  if (args.confirm_authorization !== true) throw new Error('EXTERNAL_FS_AUTHORIZATION_REQUIRED: confirm_authorization=true is required.');
+  const preview = previewExternalFilesystemGrant(repoRoot, args);
+  if (!preview.accepted || !preview.canonicalRoot) throw new Error(`EXTERNAL_FS_GRANT_DENIED: ${preview.denialReason ?? 'preview not accepted'}`);
+  if (String(args.preview_ticket_id ?? '') !== preview.previewTicketId) throw new Error('EXTERNAL_FS_PREVIEW_TICKET_MISMATCH: run preview again and pass the returned ticket id');
+  const file = loadExternalFilesystemGrants(repoRoot);
+  const grant: ExternalFilesystemGrant = {
+    schemaVersion: 1,
+    key: preview.key,
+    root: preview.root,
+    canonicalRoot: preview.canonicalRoot,
+    mode: preview.mode,
+    reason: preview.reason,
+    createdAt: now(),
+    createdBy: 'external_filesystem_grant_apply',
+    expiresAt: preview.expiresAt,
+  };
+  const grants = file.grants.filter((entry) => entry.key !== grant.key).concat(grant);
+  return { grant, file: saveExternalFilesystemGrants(repoRoot, { ...file, grants }), preview };
+}
+
+export function listExternalFilesystemTargets(repoRoot: string): { targets: Array<Omit<ExternalFilesystemGrant, 'root'> & { exists: boolean; rootPreview: string }>; safety: Record<string, unknown> } {
+  const file = loadExternalFilesystemGrants(repoRoot);
+  return {
+    targets: file.grants.map((grant) => ({
+      ...grant,
+      rootPreview: `<external:${grant.key}>`,
+      exists: existsSync(grant.canonicalRoot),
+    })),
+    safety: {
+      arbitraryPathAccepted: false,
+      operationsRequireTargetKey: true,
+      writeOperationsExposed: false,
+      modes: ['read', 'copy_into_repo'],
+      grantExpiryEnforced: true,
+      configPath: CONFIG_PATH,
+    },
+  };
+}
+
+function resolveGrantedPath(grant: ExternalFilesystemGrant, relativePath: unknown): { absolute: string; relativePath: string } {
+  const raw = String(relativePath ?? '.').trim() || '.';
+  if (raw.startsWith('/')) throw new Error('EXTERNAL_FS_RELATIVE_PATH_REQUIRED: use a path relative to the target key');
+  const normalized = raw.replace(/\\/g, '/').replace(/^\.\//, '');
+  const absolute = resolve(grant.canonicalRoot, normalized);
+  const rel = relative(grant.canonicalRoot, absolute);
+  if (rel.startsWith('..') || rel === '..') throw new Error('EXTERNAL_FS_PATH_ESCAPE_DENIED: path must stay inside the granted root');
+  return { absolute, relativePath: rel || '.' };
+}
+
+function boundedChars(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return DEFAULT_MAX_CHARS;
+  return Math.max(1, Math.min(Math.trunc(value), MAX_CHARS));
+}
+
+export function readExternalFilesystemSnapshot(repoRoot: string, args: Record<string, unknown>): ExternalFilesystemSnapshot {
+  const key = normalizeKey(args.target_key ?? args.grant_key ?? args.key);
+  const grant = loadExternalFilesystemGrants(repoRoot).grants.find((entry) => entry.key === key);
+  if (!grant) throw new Error(`EXTERNAL_FS_TARGET_UNKNOWN: ${key}`);
+  if (externalFilesystemGrantExpired(grant)) throw new Error('EXTERNAL_FS_GRANT_EXPIRED: renew the external filesystem grant');
+  if (grant.mode !== 'read') throw new Error('EXTERNAL_FS_READ_NOT_GRANTED: target does not grant read mode');
+  const resolved = resolveGrantedPath(grant, args.path);
+  if (!existsSync(resolved.absolute)) throw new Error('EXTERNAL_FS_PATH_NOT_FOUND');
+  const stat = statSync(resolved.absolute);
+  if (stat.isDirectory()) {
+    const entries = readdirSync(resolved.absolute, { withFileTypes: true }).slice(0, 200).map((entry) => {
+      const entryPath = join(resolved.absolute, entry.name);
+      let size: number | undefined;
+      try { size = statSync(entryPath).size; } catch { size = undefined; }
+      return { name: entry.name, kind: entry.isDirectory() ? 'directory' as const : entry.isFile() ? 'file' as const : 'other' as const, size };
+    });
+    return {
+      targetKey: key,
+      relativePath: resolved.relativePath,
+      absolutePathPreview: `<external:${key}>/${resolved.relativePath === '.' ? '' : resolved.relativePath}`,
+      kind: 'directory',
+      truncated: entries.length >= 200,
+      entries,
+      safety: { grantMode: grant.mode, boundedToGrant: true, writeAllowed: false },
+    };
+  }
+  if (!stat.isFile()) throw new Error('EXTERNAL_FS_PATH_UNSUPPORTED: only files and directories can be snapshotted');
+  const maxChars = boundedChars(args.max_chars);
+  const content = readFileSync(resolved.absolute, 'utf8');
+  return {
+    targetKey: key,
+    relativePath: resolved.relativePath,
+    absolutePathPreview: `<external:${key}>/${resolved.relativePath}`,
+    kind: 'file',
+    truncated: content.length > maxChars,
+    text: content.slice(0, maxChars),
+    byteLength: Buffer.byteLength(content),
+    safety: { grantMode: grant.mode, boundedToGrant: true, writeAllowed: false },
+  };
+}

package/src/runtime/safe-tooling/google-credential-store.ts

@@ -0,0 +1,95 @@
+import { execFileSync } from 'child_process';
+
+export type StoredGoogleService = 'gmail' | 'calendar' | 'tasks' | 'google-workspace';
+
+export interface GoogleCredentialStoreAdapter {
+  available(): boolean;
+  read(service: StoredGoogleService): string | undefined;
+  write(service: StoredGoogleService, refreshToken: string): void;
+}
+
+const KEYCHAIN_SERVICE_PREFIX = 'forge.google-oauth';
+const KEYCHAIN_ACCOUNT = 'refresh-token';
+const memoryCache = new Map<StoredGoogleService, string>();
+
+function keychainService(service: StoredGoogleService): string {
+  return `${KEYCHAIN_SERVICE_PREFIX}.${service}`;
+}
+
+const macKeychainAdapter: GoogleCredentialStoreAdapter = {
+  available: () => process.platform === 'darwin',
+  read(service) {
+    if (process.platform !== 'darwin') return undefined;
+    try {
+      const value = execFileSync('/usr/bin/security', [
+        'find-generic-password',
+        '-s', keychainService(service),
+        '-a', KEYCHAIN_ACCOUNT,
+        '-w',
+      ], {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 2_000,
+      }).trim();
+      return value || undefined;
+    } catch {
+      return undefined;
+    }
+  },
+  write(service, refreshToken) {
+    if (process.platform !== 'darwin') {
+      throw new Error('GOOGLE_CREDENTIAL_STORE_UNAVAILABLE: macOS Keychain is required for local OAuth credential persistence');
+    }
+    execFileSync('/usr/bin/security', [
+      'add-generic-password',
+      '-U',
+      '-s', keychainService(service),
+      '-a', KEYCHAIN_ACCOUNT,
+      '-w', refreshToken,
+    ], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'ignore', 'pipe'],
+      timeout: 5_000,
+    });
+  },
+};
+
+let adapter: GoogleCredentialStoreAdapter = macKeychainAdapter;
+
+export function setGoogleCredentialStoreAdapterForTest(next?: GoogleCredentialStoreAdapter): void {
+  adapter = next ?? macKeychainAdapter;
+  memoryCache.clear();
+}
+
+export function googleCredentialStoreStatus(): Record<string, unknown> {
+  return {
+    backend: process.platform === 'darwin' ? 'macos-keychain' : 'unavailable',
+    available: adapter.available(),
+    repositoryPersistence: false,
+    controllerStatePersistence: false,
+  };
+}
+
+export function readStoredGoogleRefreshToken(service: StoredGoogleService): { token: string; source: string } | undefined {
+  const candidates: StoredGoogleService[] = service === 'google-workspace'
+    ? ['google-workspace']
+    : [service, 'google-workspace'];
+  for (const candidate of candidates) {
+    const cached = memoryCache.get(candidate);
+    if (cached) return { token: cached, source: `keychain:${candidate}` };
+    if (!adapter.available()) continue;
+    const token = adapter.read(candidate)?.trim();
+    if (!token) continue;
+    memoryCache.set(candidate, token);
+    return { token, source: `keychain:${candidate}` };
+  }
+  return undefined;
+}
+
+export function writeStoredGoogleRefreshToken(service: StoredGoogleService, refreshToken: string): void {
+  const token = refreshToken.trim();
+  if (!token) throw new Error('GOOGLE_REFRESH_TOKEN_REQUIRED');
+  if (!adapter.available()) throw new Error('GOOGLE_CREDENTIAL_STORE_UNAVAILABLE');
+  adapter.write(service, token);
+  memoryCache.set(service, token);
+}

package/src/runtime/safe-tooling/google-oauth-broker.ts

@@ -0,0 +1,286 @@
+import { createHash, randomBytes, randomUUID } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { URLSearchParams } from 'url';
+import { installGoogleAccessToken } from '../plugins/google-shared';
+import {
+  googleCredentialStoreStatus,
+  type StoredGoogleService,
+  writeStoredGoogleRefreshToken,
+} from './google-credential-store';
+
+export type GoogleOAuthService = StoredGoogleService;
+
+export interface GoogleOAuthPrepareInput {
+  service: GoogleOAuthService;
+  scopes: string[];
+  redirectUri: string;
+}
+
+interface GoogleOAuthRequestRecord {
+  schemaVersion: 1;
+  requestId: string;
+  stateHash: string;
+  service: GoogleOAuthService;
+  clientId: string;
+  redirectUri: string;
+  scopes: string[];
+  codeVerifier: string;
+  createdAt: string;
+  expiresAt: string;
+  consumedAt?: string;
+}
+
+const GOOGLE_AUTH_ENDPOINT = 'https://accounts.google.com/o/oauth2/v2/auth';
+const GOOGLE_TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token';
+const REQUEST_TTL_MS = 10 * 60_000;
+const RETAIN_CONSUMED_REQUEST_MS = 24 * 60 * 60_000;
+const ALLOWED_SCOPES: Record<GoogleOAuthService, Set<string>> = {
+  gmail: new Set([
+    'https://www.googleapis.com/auth/gmail.readonly',
+    'https://www.googleapis.com/auth/gmail.compose',
+    'https://www.googleapis.com/auth/gmail.modify',
+    'https://www.googleapis.com/auth/gmail.send',
+  ]),
+  calendar: new Set(['https://www.googleapis.com/auth/calendar']),
+  tasks: new Set(['https://www.googleapis.com/auth/tasks']),
+  'google-workspace': new Set([
+    'https://www.googleapis.com/auth/gmail.readonly',
+    'https://www.googleapis.com/auth/gmail.compose',
+    'https://www.googleapis.com/auth/gmail.modify',
+    'https://www.googleapis.com/auth/gmail.send',
+    'https://www.googleapis.com/auth/calendar',
+    'https://www.googleapis.com/auth/tasks',
+  ]),
+};
+
+function validateRedirectUri(value: string): string {
+  let parsed: URL;
+  try { parsed = new URL(value); } catch { throw new Error('GOOGLE_OAUTH_REDIRECT_INVALID: redirect URI must be a URL'); }
+  if (parsed.protocol !== 'http:' || !['127.0.0.1', 'localhost'].includes(parsed.hostname)) {
+    throw new Error('GOOGLE_OAUTH_REDIRECT_NOT_LOCAL: redirect URI must use loopback HTTP');
+  }
+  if (parsed.pathname !== '/oauth/google/callback' || parsed.username || parsed.password || parsed.hash) {
+    throw new Error('GOOGLE_OAUTH_REDIRECT_INVALID: use the local /oauth/google/callback endpoint');
+  }
+  return parsed.toString();
+}
+
+const OAUTH_SCOPE_ALIASES: Record<string, string> = {
+  'gmail.readonly': 'https://www.googleapis.com/auth/gmail.readonly',
+  'gmail.compose': 'https://www.googleapis.com/auth/gmail.compose',
+  'gmail.modify': 'https://www.googleapis.com/auth/gmail.modify',
+  'gmail.send': 'https://www.googleapis.com/auth/gmail.send',
+  'calendar.events.readonly': 'https://www.googleapis.com/auth/calendar',
+  'calendar.events.write': 'https://www.googleapis.com/auth/calendar',
+  'calendar.events.delete': 'https://www.googleapis.com/auth/calendar',
+  'tasks.readonly': 'https://www.googleapis.com/auth/tasks',
+  'tasks.write': 'https://www.googleapis.com/auth/tasks',
+  'tasks.delete': 'https://www.googleapis.com/auth/tasks',
+};
+
+function validateScopes(service: GoogleOAuthService, scopes: string[]): string[] {
+  const normalized = [...new Set(scopes.map((scope) => OAUTH_SCOPE_ALIASES[scope.trim()] ?? scope.trim()).filter(Boolean))];
+  const invalid = normalized.filter((scope) => !ALLOWED_SCOPES[service].has(scope));
+  if (invalid.length > 0) throw new Error(`GOOGLE_OAUTH_SCOPE_NOT_ALLOWED: ${invalid.join(', ')}`);
+  if (normalized.length === 0) throw new Error('GOOGLE_OAUTH_SCOPE_REQUIRED');
+  return normalized;
+}
+
+function pruneOAuthRequests(controllerHome: string): void {
+  const root = join(oauthRoot(controllerHome), 'requests');
+  try {
+    for (const name of readdirSync(root).filter((entry) => entry.endsWith('.json')).slice(0, 2_000)) {
+      const path = join(root, name);
+      try {
+        const record = JSON.parse(readFileSync(path, 'utf-8')) as Partial<GoogleOAuthRequestRecord>;
+        const expired = Date.parse(String(record.expiresAt ?? '')) <= Date.now();
+        const consumedOld = record.consumedAt && Date.now() - Date.parse(record.consumedAt) > RETAIN_CONSUMED_REQUEST_MS;
+        if (expired || consumedOld) unlinkSync(path);
+      } catch { unlinkSync(path); }
+    }
+  } catch { /* no request store yet */ }
+}
+
+function oauthRoot(controllerHome: string): string {
+  return join(controllerHome, 'auth', 'google-oauth');
+}
+
+function requestPath(controllerHome: string, state: string): string {
+  return join(oauthRoot(controllerHome), 'requests', `${createHash('sha256').update(state).digest('hex')}.json`);
+}
+
+function writeRecord(path: string, value: GoogleOAuthRequestRecord): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+function readRecord(controllerHome: string, state: string): { path: string; record: GoogleOAuthRequestRecord } {
+  const path = requestPath(controllerHome, state);
+  if (!existsSync(path)) throw new Error('GOOGLE_OAUTH_STATE_INVALID: login state was not found');
+  let record: GoogleOAuthRequestRecord;
+  try {
+    record = JSON.parse(readFileSync(path, 'utf-8')) as GoogleOAuthRequestRecord;
+  } catch {
+    throw new Error('GOOGLE_OAUTH_STATE_INVALID: login state is unreadable');
+  }
+  if (record.stateHash !== createHash('sha256').update(state).digest('hex')) {
+    throw new Error('GOOGLE_OAUTH_STATE_INVALID: state hash mismatch');
+  }
+  if (record.consumedAt) throw new Error('GOOGLE_OAUTH_STATE_REPLAYED: login state was already consumed');
+  if (Date.parse(record.expiresAt) <= Date.now()) throw new Error('GOOGLE_OAUTH_STATE_EXPIRED: start a new login');
+  return { path, record };
+}
+
+function base64Url(value: Buffer): string {
+  return value.toString('base64url');
+}
+
+function clientId(): string | undefined {
+  return process.env.FORGE_GOOGLE_WORKSPACE_CLIENT_ID?.trim()
+    || process.env.FORGE_GOOGLE_CLIENT_ID?.trim()
+    || process.env.GOOGLE_CLIENT_ID?.trim();
+}
+
+function clientSecret(): string | undefined {
+  return process.env.FORGE_GOOGLE_WORKSPACE_CLIENT_SECRET?.trim()
+    || process.env.FORGE_GOOGLE_CLIENT_SECRET?.trim()
+    || process.env.GOOGLE_CLIENT_SECRET?.trim();
+}
+
+export function prepareGoogleOAuthLogin(
+  controllerHome: string,
+  input: GoogleOAuthPrepareInput,
+): Record<string, unknown> {
+  pruneOAuthRequests(controllerHome);
+  const redirectUri = validateRedirectUri(input.redirectUri);
+  const scopes = validateScopes(input.service, input.scopes);
+  const configuredClientId = clientId();
+  if (!configuredClientId) {
+    return {
+      schemaVersion: 1,
+      provider: 'google-workspace',
+      service: input.service,
+      readyToOpenBrowser: false,
+      missingConfiguration: ['Set FORGE_GOOGLE_CLIENT_ID or FORGE_GOOGLE_WORKSPACE_CLIENT_ID.'],
+      credentialStore: googleCredentialStoreStatus(),
+    };
+  }
+  const state = base64Url(randomBytes(32));
+  const codeVerifier = base64Url(randomBytes(48));
+  const codeChallenge = base64Url(createHash('sha256').update(codeVerifier).digest());
+  const createdAt = new Date();
+  const expiresAt = new Date(createdAt.getTime() + REQUEST_TTL_MS);
+  const record: GoogleOAuthRequestRecord = {
+    schemaVersion: 1,
+    requestId: `GOAUTH-${Date.now()}-${randomUUID().slice(0, 8)}`,
+    stateHash: createHash('sha256').update(state).digest('hex'),
+    service: input.service,
+    clientId: configuredClientId,
+    redirectUri,
+    scopes,
+    codeVerifier,
+    createdAt: createdAt.toISOString(),
+    expiresAt: expiresAt.toISOString(),
+  };
+  writeRecord(requestPath(controllerHome, state), record);
+  const params = new URLSearchParams({
+    response_type: 'code',
+    access_type: 'offline',
+    prompt: 'consent',
+    include_granted_scopes: 'true',
+    client_id: record.clientId,
+    redirect_uri: record.redirectUri,
+    scope: record.scopes.join(' '),
+    state,
+    code_challenge: codeChallenge,
+    code_challenge_method: 'S256',
+  });
+  return {
+    schemaVersion: 1,
+    provider: 'google-workspace',
+    service: record.service,
+    requestId: record.requestId,
+    readyToOpenBrowser: true,
+    authorizationUrl: `${GOOGLE_AUTH_ENDPOINT}?${params.toString()}`,
+    redirectUri: record.redirectUri,
+    scopes: record.scopes,
+    expiresAt: record.expiresAt,
+    pkce: true,
+    stateProtected: true,
+    credentialStore: googleCredentialStoreStatus(),
+    safety: {
+      credentialMaterialReturned: false,
+      credentialMaterialPersistedInRepository: false,
+      opensBrowserAutomatically: false,
+    },
+  };
+}
+
+export async function completeGoogleOAuthLogin(
+  controllerHome: string,
+  input: { state?: string; code?: string; error?: string; errorDescription?: string },
+): Promise<Record<string, unknown>> {
+  const state = input.state?.trim();
+  if (!state) throw new Error('GOOGLE_OAUTH_STATE_REQUIRED');
+  const selected = readRecord(controllerHome, state);
+  const codeVerifier = selected.record.codeVerifier;
+  if (!codeVerifier) throw new Error('GOOGLE_OAUTH_STATE_INVALID: PKCE verifier is missing');
+  selected.record.codeVerifier = '';
+  selected.record.consumedAt = new Date().toISOString();
+  writeRecord(selected.path, selected.record);
+  if (input.error) {
+    throw new Error(`GOOGLE_OAUTH_DENIED: ${input.errorDescription || input.error}`);
+  }
+  const code = input.code?.trim();
+  if (!code) throw new Error('GOOGLE_OAUTH_CODE_REQUIRED');
+  const configuredSecret = clientSecret();
+  if (!configuredSecret) throw new Error('GOOGLE_OAUTH_CLIENT_SECRET_REQUIRED');
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code,
+    client_id: selected.record.clientId,
+    client_secret: configuredSecret,
+    redirect_uri: selected.record.redirectUri,
+    code_verifier: codeVerifier,
+  });
+  const response = await fetch(GOOGLE_TOKEN_ENDPOINT, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+    body: body.toString(),
+  });
+  const raw = await response.text();
+  let parsed: Record<string, unknown> = {};
+  try { parsed = raw ? JSON.parse(raw) as Record<string, unknown> : {}; } catch { parsed = {}; }
+  const accessToken = typeof parsed.access_token === 'string' ? parsed.access_token.trim() : '';
+  const refreshToken = typeof parsed.refresh_token === 'string' ? parsed.refresh_token.trim() : '';
+  if (!response.ok || !accessToken || !refreshToken) {
+    throw new Error(`GOOGLE_OAUTH_EXCHANGE_FAILED: provider returned HTTP ${response.status}`);
+  }
+  writeStoredGoogleRefreshToken(selected.record.service, refreshToken);
+  const expiresIn = typeof parsed.expires_in === 'number' ? Math.max(60, parsed.expires_in) : 3600;
+  installGoogleAccessToken(
+    selected.record.service === 'google-workspace' ? 'gmail' : selected.record.service,
+    accessToken,
+    expiresIn,
+    `oauth:${selected.record.service}`,
+  );
+  return {
+    schemaVersion: 1,
+    provider: 'google-workspace',
+    service: selected.record.service,
+    requestId: selected.record.requestId,
+    authenticated: true,
+    refreshCredentialStored: true,
+    accessTokenExpiresAt: new Date(Date.now() + expiresIn * 1000).toISOString(),
+    scopes: typeof parsed.scope === 'string' ? parsed.scope.split(/\s+/).filter(Boolean) : selected.record.scopes,
+    credentialStore: googleCredentialStoreStatus(),
+    safety: {
+      credentialMaterialReturned: false,
+      credentialMaterialPersistedInRepository: false,
+      stateConsumed: true,
+    },
+  };
+}