flynn/docs/operations/GOOGLE_AUTH.md

Google OAuth Runbook

This runbook describes how Flynn acquires, stores, refreshes, and rotates Google OAuth tokens for Gmail, Calendar, Docs, Drive, and Tasks.

Scope Policy (Least Privilege)

Service	Command	Scope(s)
Gmail	flynn gmail-auth	https://www.googleapis.com/auth/gmail.settings.basic, https://www.googleapis.com/auth/gmail.readonly
Calendar	flynn gcal-auth	https://www.googleapis.com/auth/calendar.readonly
Docs	flynn gdocs-auth	https://www.googleapis.com/auth/documents.readonly, https://www.googleapis.com/auth/drive.metadata.readonly
Drive	flynn gdrive-auth	https://www.googleapis.com/auth/drive.readonly
Tasks	flynn gtasks-auth	https://www.googleapis.com/auth/tasks.readonly

Unified entrypoint:

flynn google-auth --service gmail
flynn google-auth --service gcal
flynn google-auth --service gdocs
flynn google-auth --service gdrive
flynn google-auth --service gtasks

Add --manual for copy/paste flow, or --config <path> for non-default config.

Storage Model

• Canonical token store: ~/.config/flynn/auth.json
  • Path: google.services.<service>.token
  • Metadata: scopes, token file path, credentials file path, updated_at
• Compatibility token files remain supported:
  • ~/.config/flynn/gmail-token.json
  • ~/.config/flynn/gcal-token.json
  • ~/.config/flynn/gdocs-token.json
  • ~/.config/flynn/gdrive-token.json
  • ~/.config/flynn/gtasks-token.json

Runtime behavior:

1. Flynn checks auth store first.
2. If missing, Flynn loads legacy token file and migrates it into auth store.
3. If both are missing, tools/watchers fail with a service-specific re-auth command hint.

Refresh and Rotation Behavior

• OAuth client refresh events write back to:
  • auth store (auth.json)
  • service token file (compatibility)
• If auth store write is blocked (for example EACCES), Flynn keeps operating from token files.
• Re-auth is required when Google returns insufficient-scope errors for a service.

Local Operation Checklist

1. Configure automation.<service>.credentials_file in Flynn config.
2. Run service auth command (or flynn google-auth --service <service>).
3. Run flynn doctor and verify service checks:
   • Gmail configured
   • Google Calendar configured
   • Google Docs configured
   • Google Drive configured
   • Google Tasks configured

Failure and Renewal Signals

• Missing credentials file: hard failure with path.
• Missing tokens (store + file): doctor warning + runtime auth error with command hint.
• Scope mismatch: runtime error includes explicit re-auth command for the affected service.