docs: document manual external-service provisioning (GCP OAuth project isolation, Deno Deploy cron, Heroku env, IMAP/API keys)

[JoshuaVSherman]

Goal: capture every manual external-service provisioning step (the ones a human does in a browser/console, not in code) in one durable doc, so we stop re-discovering them — and so we never repeat a costly mistake like the OAuth-project-isolation one below.

Where it lives: new doc in this repo — web-jam-tools/docs/external-services-provisioning.md (the workspace docs hub; sits alongside ai-assistant-google-setup.md, api-integrations.md, rclone-setup.md).

🔴 #1 lesson to capture first (cost us rework 2026-06-24)

Every sensitive/restricted-scope Google integration gets its OWN Google Cloud project. Keep the login project (Web Jam LLC, used by JaMmusic + CollegeLutheran "Sign in with Google") on basic scopes only (email/profile/openid) — those never trigger Google's "unverified app" warning. Adding a sensitive scope (e.g. calendar.events) to a project's OAuth consent screen makes every sign-in through that project show "Google hasn't verified this app." We hit this by putting webjam-outreach-calendar in the shared Web Jam LLC project. Rule: one isolated GCP project per sensitive integration (Calendar, future venue-MCP OAuth, etc.); login project stays basic-scopes-only.

Steps to document

• Google OAuth client provisioning (the Calendar pattern): dedicated GCP project → enable the API → consent screen External + In production (so the refresh token does NOT expire) → add only the needed scope → create OAuth client → mint refresh token via OAuth Playground → set Heroku env (GOOGLE_OAUTH_CLIENT_ID / _SECRET / _REFRESH_TOKEN). Note gmail.metadata/readonly are restricted (CASA assessment) — avoid; we use Gmail IMAP app-password for reply-detection (#825) instead.
• Deno Deploy cron provisioning (new console.deno.com, NOT classic dash.deno.com which retires 2026-07-20): New App (not "Project"), link GitHub repo + main, entrypoint via Edit app config, env vars via the separate Add Environment variables button, deploy-from-main green. Example: webjam-outreach-cron (entrypoint src/outreach-cron/advance_cadence.ts, env WEB_JAM_LLM_TOKEN). Org verification banner = optional 100x-limits upsell, skip for low-traffic.
• web-jam-llm AI-agent service token: stored at ~/WebJamApps/web-jam-llms/web-jam-llm.token (gitignored); long-lived (mintToken, no 24h expiry); re-mint via POST /admin/.../:id/token after a HashString rotation; used by the Deno cron + agent API calls.
• Gmail IMAP app-password (for #825 reply-detection): enable 2FA + IMAP, generate app password, set Heroku GMAIL_IMAP_USER / GMAIL_IMAP_APP_PASSWORD. App passwords bypass OAuth scope verification entirely.
• Anthropic API key (for #825 Haiku classification): set Heroku ANTHROPIC_API_KEY.
• Heroku env-var reference: list which app (webjamsalem) holds which secret + how to rotate.

Related

• web-jam-back#825 (Calendar/Gmail), web-jam-tools#100 (Deno cron done + venue-MCP OAuth pending), web-jam-back#818 (epic).
• The OAuth-project-isolation fix itself (move webjam-outreach-calendar to its own project + strip calendar.events from Web Jam LLC) should be done first; document the steps as we do them.

---

⏳ OPEN FOLLOW-UP — REVALIDATE THE FIX (do not close this issue until confirmed)

Fix applied 2026-06-24: webjam-outreach-calendar moved to its own GCP project (WebJam Outreach Calendar, under joshua.v.sherman@gmail.com, External + In production, scope calendar.events only); new refresh token minted + verified (Google token endpoint returned a valid access_token with scope=calendar.events); Heroku webjamsalem GOOGLE_OAUTH_CLIENT_ID/_SECRET/_REFRESH_TOKEN swapped to the new client; old calendar client deleted from Web Jam LLC; calendar.events removed from the Web Jam LLC consent screen (Data Access → sensitive scopes now empty). Login confirmed to request basic sign-in only (no Calendar/sensitive).

🔴 STILL TO CONFIRM — Josh must revalidate the warning has cleared:

• Re-test JaMmusic Google login in a fresh incognito window — confirm the "Google hasn't verified this app / sensitive info" screen is GONE (it was a stale verification flag lagging the scope removal; expected to clear within hours–1 day).
• Re-test CollegeLutheran Google login the same way (shared Web Jam LLC login project — was also affected).
• If the warning persists past ~2026-06-25: go to Google Auth Platform → Verification Center for web-jam-llc and cancel/clear the no-longer-needed pending verification request (no sensitive scopes remain, so verification isn't required).
• Confirm the Calendar call-task integration still works once the first real call-touch fires (~2026-06-30 for the current sends) — events should land on joshua.v.sherman@gmail.com's calendar.