docs(audit): add report, google auth runbook, and agent repo map

2026-02-23 17:12:41 -08:00
parent 092a9baeae
commit d8188b5425
7 changed files with 344 additions and 1 deletions
@@ -0,0 +1,68 @@
+# 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:
+
+```bash
+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.