docs: lead the OAuth runbook with the Internal-flip fast path + consumer-account fork

76f3426a78ab01d6087708c5fb0b6889cb1bada8 · 2026-07-15 11:33:55 -0700 · Steve

Files touched

M OAUTH-SERVICE-ACCOUNT-RUNBOOK.md

Diff

commit 76f3426a78ab01d6087708c5fb0b6889cb1bada8
Author: Steve <steve@designerwallcoverings.com>
Date:   Wed Jul 15 11:33:55 2026 -0700

    docs: lead the OAuth runbook with the Internal-flip fast path + consumer-account fork
---
 OAUTH-SERVICE-ACCOUNT-RUNBOOK.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/OAUTH-SERVICE-ACCOUNT-RUNBOOK.md b/OAUTH-SERVICE-ACCOUNT-RUNBOOK.md
index 6bef636..df82406 100644
--- a/OAUTH-SERVICE-ACCOUNT-RUNBOOK.md
+++ b/OAUTH-SERVICE-ACCOUNT-RUNBOOK.md
@@ -14,6 +14,44 @@ until the key is present). Nothing breaks the current refresh-token path until y
 
 ---
 
+## ⭐ FASTEST FIX (do this first) — flip the OAuth app to "Internal"  (YOU · ~1 min, ZERO code)
+
+There is **no "expire in 1 year" setting** in Google OAuth. Refresh-token lifetime is set by the
+app's **publishing status**: **Testing = hard 7-day cap**; **Internal = long-lived** (lasts until
+revoked / ~6 months unused — effectively a year+). To stop the 7-day treadmill for the two
+Workspace accounts, just change the status:
+
+> **Cloud Console → APIs & Services → OAuth consent screen → User Type → change to `Internal` → Save.**
+
+- Works only if that Cloud project lives in the **designerwallcoverings.com Workspace org** (it does —
+  steve@/info@ authorize against it).
+- Internal apps **skip Google verification / CASA entirely** AND their refresh tokens **don't hit the
+  7-day cap**. Zero code change. Then re-consent steve@ + info@ once (`/auth/steve-office`, `/auth/info`)
+  to mint the now-long-lived tokens.
+- **Result:** steve@ + info@ stop expiring — the whole fleet send path + the info@ catch-all, solved
+  in ~1 minute.
+
+### ⚠️ The fork this forces (unavoidable)
+Flipping to **Internal BREAKS the two consumer Gmail accounts** — `steveabramsdesigns@gmail.com` and
+`theagentabrams@gmail.com` **cannot authorize an Internal app**. Google does not allow a long-lived,
+unverified token for consumer accounts on restricted scopes (gmail.modify / drive). So for those two,
+pick one:
+1. **Own separate OAuth client, published to Production** → triggers Google verification + CASA
+   (weeks, paid) — the trap. Not recommended just for two mailboxes.
+2. **Stay on the current Testing client** → 7-day re-consent forever (a periodic click).
+3. **Drop them from George** → cleanest if they aren't doing real work. (Remove their entries from the
+   ACCOUNTS map in `server.js` + their `*_REFRESH_TOKEN` from `.env`; I can do this local edit on your go.)
+
+**Recommended:** Internal flip for steve@ + info@ **now** (fastest, permanent, free). Decide 1/2/3 for the
+two consumer accounts separately — and if you don't actively use them through George, **#3 (drop)** ends
+this chore entirely.
+
+The service-account approach below (PART 1–5) is the **alternative** durable fix for the Workspace pair —
+use it instead of the Internal flip only if you specifically want token-less per-request minting (e.g. you
+can't set the consent screen to Internal). For most cases, the Internal flip above is simpler.
+
+---
+
 ## Why this works (30 seconds)
 A service account (SA) with **domain-wide delegation** is authorized, once, in your Workspace
 Admin console to impersonate users in `designerwallcoverings.com` for a fixed scope list. George

← fbeffde docs: service-account + domain-delegation runbook — permanen · back to George Gmail · feat(bridge): painless George token renewal — WARN/CRIT acco 7b49e78 →