Document the Connect Drive / Supabase refresh-token flow

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

README.md

@@ -25,19 +25,30 @@ The app works fully anonymously with no setup. Logging in with Google (button
 in the sidebar) additionally persists your players and round history to a
 Google Sheet -- created directly in **your own Drive**, owned by you.
 
-There's no service account and no shared storage involved: Streamlit's login
-requests the `drive.file` scope alongside identity, so the app gets a
-short-lived OAuth token that lets it create/edit only the one spreadsheet it
-creates for you (`BoardGameTracker - {your email}`), nothing else in your
+There's no service account and no shared storage involved: Drive access uses
+the `drive.file` scope, so the app can only create/edit the one spreadsheet
+it creates for you (`BoardGameTracker - {your email}`), nothing else in your
 Drive. Because it's created by your own account, it uses your own storage --
 there's no "service account has 0 storage quota" issue to work around.
 
 Trade-off: since the app stays in Google's "Testing" publishing status
 (no Google security review needed for a small friend group), each person who
-wants to log in must first be added as a **test user** in the OAuth consent
+connects Drive must first be added as a **test user** in the OAuth consent
 screen, and will see an "unverified app" warning the first time they
 click through.
 
+**Login vs. Drive access are two separate steps.** `st.login()` (sidebar
+button) only ever handles identity -- it deliberately never exposes a
+`refresh_token` to app code, no matter what scope you ask for. So once
+logged in, a separate one-time **Connect Google Drive** button appears in the
+sidebar; clicking it runs its own OAuth exchange (`access_type=offline` +
+`prompt=consent`) to force Google to hand back a `refresh_token`, which gets
+encrypted and stored in a Supabase Postgres table keyed by email. From then
+on -- even after closing the browser, or logging in from a different device
+-- the app silently mints a fresh access token from that stored refresh_token
+on every login; the Connect Drive button only reappears if that stored token
+is ever revoked (e.g. you remove the app's access in your Google account).
+
 ### One-time Google Cloud setup
 1. Create an OAuth 2.0 **Web application** Client ID; add your app's URL(s)
    **with the `/oauth2callback` path** as authorized redirect URIs (e.g.
@@ -61,12 +72,15 @@ cookie_secret = "<random string>"
 client_id = "<oauth client id>"
 client_secret = "<oauth client secret>"
 server_metadata_url = "https://accounts.google.com/.well-known/openid-configuration"
-expose_tokens = ["access"]
 
-[auth.client_kwargs]
-scope = "openid email profile https://www.googleapis.com/auth/drive.file"
-prompt = "consent select_account"
+[supabase]
+db_url = "postgresql://..."          # Supabase connection string
+encryption_key = "<Fernet.generate_key() output>"
 ```
+The `[supabase]` table (`user_refresh_tokens`) is created automatically on
+first use -- no manual migration needed. Rotate the DB password in Supabase's
+dashboard if it's ever been pasted somewhere outside a secrets file (e.g.
+chat, a ticket, a terminal history you don't control).
 
 ### Hugging Face Space deploy
 `st.login()` only reads `st.secrets`, so `src/bootstrap_secrets.py` assembles
@@ -74,4 +88,5 @@ prompt = "consent select_account"
 Variables and secrets), so nothing sensitive needs to live in the repo or the
 image: `AUTH_CLIENT_ID`, `AUTH_CLIENT_SECRET`, `AUTH_COOKIE_SECRET`,
 `AUTH_REDIRECT_URI` (your Space's public URL **with `/oauth2callback`
-appended**, e.g. `https://randomcatlover-boardgames-tracker.hf.space/oauth2callback`).
+appended**, e.g. `https://randomcatlover-boardgames-tracker.hf.space/oauth2callback`),
+`SUPABASE_DB_URL`, `SUPABASE_ENCRYPTION_KEY`.