pal-e-docs

Review: Automate Gmail OAuth re-auth lifecycle v4

review-359-2026-03-27-v4 Review

review ready
Project

Verdict: READY

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Standalone, discovered. Prereq gmail-mcp#6 done (closed).
  • [x] Repo -- forgejo_admin/pal-e-platform
  • [x] User Story -- "As a platform operator I want a single script that re-authenticates Gmail OAuth and syncs the refreshed token..."
  • [x] Context -- Detailed: 7-day expiry policy, 3 consumers enumerated, prereq satisfied, resolved decisions inline.
  • [x] File Targets -- 3 create/modify + 3 do-not-touch. All verified (see below).
  • [x] Acceptance Criteria -- 7 criteria. All verifiable.
  • [x] Test Expectations -- 3 items (manual, dry-run, error handling).
  • [x] Constraints -- 4 items (typo bridge, mount pattern, script style, repo scope). 3 Resolved decisions inline.
  • [x] Checklist -- 5 items.
  • [x] Related -- 5 references including prior review notes.
All required template-issue-feature sections are present. All 3 v3 NEEDS_REFINEMENT mechanical fixes have been applied: monitoring/main.tf added to File Targets, PrometheusRule AC added, stale secret deletion AC added.

Traceability

  • [ ] story:X label -- MISSING on board item #359. Labels are arch:google-oauth,type:feature,scope:discovered. Issue body acknowledges this: "NOTE: needs story:platform-reliability label added (Betty Sue action)." This is a board-level label fix, not a spec deficiency -- the issue itself is complete.
  • [x] arch:google-oauth label -- present on board item #359.
  • [x] Forgejo issue -- forgejo_admin/pal-e-platform#162, confirmed open.

File Targets

  • [x] scripts/gmail-reauth.sh (new) -- scripts/ directory verified with 3 existing scripts. Convention reference update-kustomize-tag.sh exists (uses set -eu). Consistent placement.
  • [x] salt/pillar/secrets_registry.sls (modify) -- verified exists (287 lines). platform: section at line 8. No existing Gmail OAuth entry. Adding is straightforward and consistent.
  • [x] terraform/modules/monitoring/main.tf (modify) -- verified exists (700+ lines). Existing PrometheusRule resources: blackbox_alerts (line 387) and embedding_alerts (line 681). Pattern is well-established for adding gmail-oauth-expiry.
  • [x] Do-not-touch files verified: ~/gmail-sdk/src/gmail_sdk/auth.py exists, ~/gmail-mcp/ exists, ~/pal-e-deployments/ exists.

Repo Placement

OK. pal-e-platform is the correct repo for all 3 file targets: re-auth script (scripts/), secrets registry (salt/pillar/), and PrometheusRule (terraform/modules/monitoring/). The pal-e-mail PVC-to-secret migration is correctly scoped out to a separate pal-e-deployments ticket.

Dependencies

  • Board item #361 (gmail-mcp SSH reauth, forgejo_admin/gmail-mcp#6) -- in done column. Issue confirmed closed. Prerequisite satisfied.
  • No blockers -- nothing in in_progress or next_up conflicts with this work.
  • Downstream: pal-e-mail PVC migration -- explicitly scoped out. Not a blocker. Discovered scope to create after this lands.
  • Stale secret cleanup -- gmail-oauth-westsidebasketball (9 days old) confirmed present alongside gmail-oauth-token (18 days old). Basketball-api deployment mounts gmail-oauth-token only. Cleanup is scoped in AC7.

Acceptance Criteria

7 ACs, all verifiable by an agent:
  • AC1: End-to-end script execution (reauth + k8s secret update + rollout restart) -- verifiable via dry-run + live test.
  • AC2: secrets_registry.sls entry with rotation_days: 7 -- verifiable via grep.
  • AC3: kubectl get secret verification command provided verbatim -- directly executable.
  • AC4: Scope validation (4 Gmail scopes) -- verifiable programmatically against token JSON.
  • AC5: Typo bridge (local gmail-westsidebasktball.json to k8s key gmail-westsidebasketball.json) -- verified: local file exists at ~/secrets/google-oauth/gmail-westsidebasktball.json, k8s secret key confirmed as gmail-westsidebasketball.json. Mismatch documented in Constraints.
  • AC6: PrometheusRule gmail-oauth-expiry in monitoring/main.tf, fires at 6-day secret age -- verifiable via tofu plan output.
  • AC7: Stale secret gmail-oauth-westsidebasketball deleted -- verifiable via kubectl.
All ACs are concrete, testable, and agent-executable. No ambiguity.

Blast Radius

  • Token filename typo bridge -- fully documented in AC5 + Constraints. Verified both sides of the mapping against live filesystem and k8s. No risk.
  • pal-e-mail PVC -- correctly scoped out. After this ticket, pal-e-mail still reads from PVC (manual sync needed until migration ticket). Acceptable.
  • gmail-mcp -- reads directly from local filesystem at same path the reauth tool writes to. Automatic pickup. No blast radius.
  • PrometheusRule addition -- requires tofu apply (standard for this repo). No blast radius to existing rules.
  • Stale secret deletion -- confirmed gmail-oauth-westsidebasketball is not referenced by any deployment. Safe to delete.

Decomposition

3 file targets in 1 repo, 7 ACs. Estimated agent work: ~5 minutes. All targets are in the same repo, PrometheusRule follows established patterns. No decomposition needed.

Recommendation

Ticket is READY for execution. The spec is complete, all file targets verified, all ACs are concrete and testable.
One board-level action remains (not blocking execution):
  • [LABEL] Add story:platform-reliability label to board item #359. The issue body itself flags this as a Betty Sue action. Should be applied before or when the ticket moves to next_up.

Prior Review Lineage

  • review-359-2026-03-27 -- v1, NEEDS_REFINEMENT (4 issues: missing alerting mechanism, pal-e-mail PVC unclear, typo undocumented, stale secret ambiguous)
  • review-359-2026-03-27-v2 -- v2, BLOCK (issue body was literal $NEW_BODY)
  • review-359-2026-03-27-v3 -- v3, NEEDS_REFINEMENT (3 issues: missing label, missing monitoring/main.tf file target, missing 2 ACs)
  • review-359-2026-03-27-v4 -- this review. All 3 v3 body fixes applied. Label still outstanding (board-level, not blocking). READY.