pal-e-docs

Review: Automate Gmail OAuth re-auth lifecycle (7-day token expiry)

review-359-2026-03-27 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related

Traceability

  • [ ] story:X label — MISSING. Board item has arch:google-oauth,type:feature,scope:discovered but no story label. User story is defined in the issue body but not reflected as a board label. Recommend adding story:platform-reliability or a new story:superuser-secrets.
  • [x] arch:google-oauth label — present, maps to Gmail OAuth lifecycle component.
  • [x] Forgejo issue — forgejo_admin/pal-e-platform#162, confirmed open.

File Targets

  • [x] salt/pillar/secrets_registry.sls — verified exists. Confirmed no Gmail OAuth entry present. Currently has platform, services, forgejo, sops, gpg, and removed sections. Adding a Gmail OAuth entry is straightforward.
  • [x] scripts/gmail-reauth.sh (new) — scripts/ directory exists with 3 existing scripts (update-kustomize-tag.sh, woodpecker-update-tag-step.yaml, test-update-kustomize-tag.sh). Location is consistent.
  • [x] ~/gmail-sdk/src/gmail_sdk/auth.py — verified exists at /home/ldraney/gmail-sdk/src/gmail_sdk/auth.py. Correctly listed as "do not touch."
  • [x] ~/gmail-mcp/ — correctly listed as "do not touch."
  • [ ] Cron/scheduled agent config — ISSUE: "location TBD" is too vague. Agent won't know where to put the day-6 alert. Options: Prometheus alert rule (in terraform monitoring module), CronJob (in pal-e-deployments), or Salt scheduled job. This must be specified before the ticket is actionable.

Repo Placement

Issue filed on forgejo_admin/pal-e-platform. Core work (secrets_registry.sls, re-auth script) correctly scoped to pal-e-platform. Issue mentions forgejo_admin/gmail-mcp as secondary, but gmail-mcp#6 (SSH-compatible reauth tool) is already closed — that dependency is satisfied. Single-repo PR is correct for pal-e-platform scope.

Dependencies

  • Board item #361 (gmail-mcp SSH reauth, forgejo_admin/gmail-mcp#6) — in done column. Prerequisite satisfied.
  • No blockers in in_progress or next_up that would conflict.
  • Undocumented dependency: The re-auth script needs to know which k8s secrets to update. The deployment patches in pal-e-deployments mount gmail-oauth-token (basketball-api) and gmail-oauth PVC (pal-e-mail). The script must handle both patterns (k8s secret vs PVC) or explicitly scope out the PVC path.

Acceptance Criteria

  • AC #1 (one-command reauth + sync) — Testable. Clear pass/fail.
  • AC #2 (day-6 alert) — NOT testable without specifying the alerting mechanism. Where does this alert fire? Prometheus? A CronJob? Manual calendar reminder? File target is TBD.
  • AC #3 (k8s secrets updated) — AMBIGUOUS. Lists gmail-oauth-token and gmail-oauth-westsidebasketball in basketball-api. Both confirmed to exist in k8s. But says "and pal-e-mail secrets if applicable" — pal-e-mail uses a PVC (gmail-oauth), not a k8s secret. The PVC mount path needs clarification: does pal-e-mail read from a file on a PVC or from a k8s secret? This ambiguity will block the agent.
  • AC #4 (secrets_registry entry) — Testable. Clear.
  • AC #5 (4 scopes after reauth) — Testable. Clear.

Blast Radius

  • pal-e-mail deployment (pal-e-deployments/overlays/pal-e-mail/prod/) mounts a PVC named gmail-oauth, not a k8s secret. Sync script must account for this different pattern or explicitly scope it out.
  • Token file naming mismatch: Local file is gmail-westsidebasktball.json (typo: no 'e' in basketball). K8s secret is gmail-oauth-westsidebasketball (correct spelling). The sync script must bridge this naming gap correctly. This is a landmine for any agent that assumes consistent naming.
  • Two k8s secrets in basketball-api: gmail-oauth-token (17 days old) and gmail-oauth-westsidebasketball (8 days old). The issue should clarify whether both are needed or if one is stale/redundant.
  • gmail-mcp also consumes the token file — the re-auth script needs to ensure gmail-mcp picks up the refreshed token (likely via file path, not k8s secret).

Recommendation

Four items must be resolved before this ticket is READY:
  • Add story label to board item #359 — suggest story:platform-reliability.
  • Specify the alerting mechanism for day-6 expiry warning — pick one: Prometheus alert rule (checking token age), k8s CronJob, or Salt scheduled task. Add the specific file target.
  • Clarify pal-e-mail sync path — pal-e-mail uses PVC gmail-oauth, not a k8s secret. Either: (a) add PVC update to the sync script scope, (b) explicitly scope it out with rationale, or (c) create a separate ticket for pal-e-mail token sync.
  • Document the naming mismatch — the token file typo (westsidebasktball) vs k8s secret correct spelling (westsidebasketball) must be explicitly called out in the File Targets or Constraints section so the agent doesn't assume they match.