docs/gcal-verify.md

# Verifying the Google Calendar connection end-to-end

> **Private-Space gotcha (the OAuth popup 404):** while the Space is private,
> `*.hf.space` URLs answer Hugging Face's 404 page for any request that lacks
> the signed access cookie. The app viewed EMBEDDED on huggingface.co
> authenticates its iframe with a short-lived signed URL, but the OAuth POPUP
> is a separate top-level window — when the subdomain cookie is missing or
> expired, **Connect opens a 404**. Fix: always open
> `https://paretooptimal-offgridschedula.hf.space` directly in its own tab
> (the redirect re-mints the cookie for the whole subdomain), then connect
> from there. Making the Space public would remove this entirely, at the cost
> of the deployed source tree becoming publicly browsable — deliberately NOT
> done (2026-06-12).

Two layers of verification exist:

1. **In-app, automatic** — on every page load, `wireGcal()` round-trips the stored
   token to `POST /oauth2/check`, which makes one real (scope-compatible) Google
   API call. The Step 2a row and the export-bar badge upgrade from
   "✓ connected" to **"✓ connected · verified"** when Google answers; a
   *definitive* rejection (revoked/invalid token) clears the stored token and
   flips everything to "not connected". Transient problems (OAuth env unset,
   network down, `SERVE=gradio` mode where FastAPI routes aren't served) never
   destroy the token — the UI just stays at the local shape-check state.
2. **Scripted E2E** — `scripts/verify_gcal_e2e.py` proves the whole chain:
   agent-extracted event → real push → API readback (title/location/start/
   reminder) → cleanup.

## Browser loop (manual)

1. Run locally with OAuth configured:
   ```
   set GOOGLE_OAUTH_CLIENT_ID=...        # a Google Cloud OAuth "Web application" client
   set GOOGLE_OAUTH_CLIENT_SECRET=...
   set SERVE=uvicorn
   python app.py
   ```
2. Open http://localhost:7860, switch to **☁️ Online**, open Step 2a
   **"🔗 Connect your calendar"** → click **Connect** on the Google row →
   consent in the popup. The row flips to "✓ connected", then upgrades to
   **"✓ connected · verified"** within ~1s (the `/oauth2/check` round-trip).
3. Paste the appointment text (the CANON sample in `tests/test_agent.py`) →
   **Run the agents** → the export toolbar appears with the badge
   **"Google: ✓ connected · verified"** next to the three buttons.
4. Click **Add to Google Calendar** → the status line shows the created event
   link; open it: *Mon Jun 22 2026, 10:15–11:00, 112A West 72nd Street,
   New York, NY 10023*, 60-minute reminder.
5. **Reload the page** → still verified, no re-prompt (the acceptance test for
   "never asks again").

### Negative paths

- Revoke access at https://myaccount.google.com/permissions → reload → the
  check is definitive: token is cleared, every surface shows "not connected".
- Unset the OAuth env vars (or kill the network) → reload → stays at plain
  "✓ connected" — transient failures never log the user out.
- Click **disconnect** in Step 2a → flips everywhere instantly.

## Scripted loop

One-time: after connecting in the browser, copy the `gcal_token` value from
DevTools → Application → Local Storage into a file (e.g. `tok.json` — it's
gitignored territory; don't commit it).

```
python scripts/verify_gcal_e2e.py --token-file tok.json --check-only   # liveness only
python scripts/verify_gcal_e2e.py --token-file tok.json               # full E2E
```

The full run pushes the CANON event with a nonce in the title (`[e2e-xxxxxx]`),
reads it back through the API, asserts summary/location/start-instant/reminder,
and deletes it (use `--keep` to inspect it in the calendar first). Exit code 0
= all checks passed.