feat(auth): add Spotify OAuth PKCE

[VACInc]

Summary

High Level TLDR

Add Spotify Authorization Code with PKCE as an optional, local OAuth path for official Web API commands, while keeping cookies as the default and preserving Connect behavior. This version includes the lifecycle-safety repairs from #61, rebases onto current main, and adds config-wide serialization so concurrent updates to different profiles cannot overwrite each other.

• add spogo auth oauth login|status|clear and per-profile OAuth settings
• refresh and securely persist per-profile OAuth tokens with cross-process locking
• serialize OAuth login and clear as one profile-scoped lifecycle transition
• reload persisted profile state after lifecycle-lock acquisition
• make OAuth clearing failure-safe by persisting the cookie fallback before deleting the token cache
• serialize shared config load-modify-save transactions across profiles to prevent lost updates
• preserve cookie authentication as the default and keep Spotify Connect cookie-backed
• use OAuth for the existing official Web API surface and Connect Web API fallbacks
• include documentation, changelog entries, focused regressions, and built-CLI proof

Product decision

Maintainer direction on September 2, 2026 accepted this bounded OAuth mode for spogo's purpose: it is optional, local-only, limited to the existing Web API surface, and does not change the cookie-first default or make Connect depend on a hosted credential service. This satisfies the explicit product-decision requirement for new persistent credential flows in VISION.md.

Security and consistency

• use PKCE with a cryptographically random verifier and state
• bind callbacks only to explicit IPv4 or IPv6 loopback addresses and validate callback host, method, path, and state
• never accept or store a Spotify client secret
• store token caches and lifecycle locks in a 0700 directory with 0600 files on POSIX systems
• derive token and lock filenames from contained, collision-safe profile segments; traversal, separators, Windows-reserved names, and case variants are encoded as lowercase byte-hex
• coordinate concurrent token readers and refreshes with a per-profile cache lock
• coordinate login token/profile commits and clear profile/token commits with a shared per-profile lifecycle lock
• reload the persisted profile while holding the lifecycle lock so stale command contexts cannot recreate an inconsistent state
• coordinate all profile config writes with a config-file lock and reload before mutation, preventing cross-profile lost updates
• use same-directory atomic token replacement on POSIX and MoveFileEx replacement with write-through on Windows
• never emit access or refresh token values in status output
• do not follow redirects from Spotify's token endpoint

Compatibility

Cookie authentication remains the default. OAuth selects the token provider for public Web API operations; Spotify Connect and internal endpoints still require browser cookies. Existing command names, output formats, and cookie-auth profiles remain unchanged.

Verification

Validated on exact head 62f34e8:

• rebased onto upstream e89c46f (September 4, 2026)

• go test ./...

• go test -race ./...

• go run golang.org/x/tools/cmd/deadcode@v0.49.0 -test ./...

• go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2 run (0 issues)

• ./scripts/check-coverage.sh 90 (90.1%)

• focused OAuth lifecycle and config-lock regressions repeated 20 times under the race detector

• profile-derived OAuth path containment and collision regressions cover traversal, Unix/Windows separators, reserved names, mixed-case aliases, and encoded-name collisions

• node scripts/build-docs-site.mjs

• VCS-stamped go build ./cmd/spogo

• Windows amd64 test-binary cross-compilation for cmd/spogo and internal/spotify

• built CLI against an isolated config:

  • missing OAuth status reported false cookies false
  • clear succeeded and preserved cookie selection
  • invalid loopback port 0 was rejected before browser or token exchange

• mock end-to-end OAuth login covered callback state handling, authorization-code exchange, token persistence, profile persistence, and subsequent clear behavior

• final review found and fixed a cross-profile config lost-update race; final rereview found no actionable defects

Redacted end-to-end proof

The exact final head was exercised with synthetic credentials and isolated temporary state. Callback URLs, authorization state, token values, client identifiers, filesystem paths, and local environment details are intentionally omitted. No real credentials were printed or committed.

$ go test -count=1 -run '<OAuth lifecycle tests>' -v ./internal/cli
=== RUN   TestAuthOAuthLoginCmd
--- PASS: TestAuthOAuthLoginCmd
=== RUN   TestAuthOAuthLoginAndClearSerializeLifecycle
--- PASS: TestAuthOAuthLoginAndClearSerializeLifecycle
=== RUN   TestAuthOAuthClearKeepsTokenWhenProfileUpdateFails
--- PASS: TestAuthOAuthClearKeepsTokenWhenProfileUpdateFails
=== RUN   TestAuthOAuthClearResetsStoredOAuthSelectionDespiteRuntimeOverride
--- PASS: TestAuthOAuthClearResetsStoredOAuthSelectionDespiteRuntimeOverride
PASS

$ go test -count=1 -run '<token exchange and locking tests>' -v ./internal/spotify
=== RUN   TestOAuthExchangeAndRefresh
--- PASS: TestOAuthExchangeAndRefresh
=== RUN   TestOAuthRefreshIsLockedAcrossProviders
--- PASS: TestOAuthRefreshIsLockedAcrossProviders
=== RUN   TestOAuthLifecycleLockSerializesAndPropagates
--- PASS: TestOAuthLifecycleLockSerializesAndPropagates
PASS

$ go test -count=1 -run '<cross-profile config locking tests>' -v ./internal/config
=== RUN   TestUpdateHonorsLockCancellation
--- PASS: TestUpdateHonorsLockCancellation
=== RUN   TestUpdateSerializesDifferentProfileWrites
--- PASS: TestUpdateSerializesDifferentProfileWrites
PASS

This proves the complete local OAuth lifecycle: loopback callback handling, state validation, authorization-code exchange, secure token persistence, refresh, profile persistence, failure-safe clearing, same-profile lifecycle serialization, and cross-profile config serialization. The repository CI build also passed on the exact final commit.

Inherited live endpoint proof from #61

The incorporated #61 head exercised the built CLI against its normal loopback callback and Spotify's real accounts token endpoint using dummy public values only. Invalid state was rejected without exchange; valid state reached Spotify's endpoint and received the expected rejection for dummy values. No credential or real token was used, printed, or persisted.

Redacted real-account end-to-end proof

On September 4, 2026, the exact final head 62f34e8 was installed as the active spogo CLI and run using an existing real Spotify OAuth authorization. The persisted access token was expired before the run, so the first authenticated request exercised automatic refresh. Account identity, client identifier, token values, callback details, item names, library totals, device details, filesystem paths, and token hashes are omitted.

$ spogo --profile <redacted> --engine web --auth oauth <read-only commands>
installed_head=62f34e8
preexisting_token_expired=true
token_cache_refreshed=true
oauth_authenticated=true
oauth_expired=false
oauth_has_refresh=true
oauth_file_mode=0600
search_items=1
library_items=1
devices_items_positive=true
playback_status_read=true
top_tracks_items=1
history_items=1
stderr_bytes=0

$ spogo --profile <redacted> --engine auto --auth oauth search track <redacted> --limit 1
auto_web_fallback_items=1
stderr_bytes=0

$ spogo --profile <redacted> --engine connect --auth cookies status
exit=3
stderr="no cookies found"

Observed result: the installed exact-head binary refreshed the expired real-account token, atomically persisted the refreshed cache with owner-only permissions, and completed authenticated search, saved-library, device, playback-status, affinity-ranking, and listening-history reads without diagnostics. auto also completed through the OAuth Web API path when browser cookies were unavailable. Cookie-backed Connect correctly reported missing cookies with the documented exit code 3; live Connect behavior therefore remains credential-blocked rather than falsely claimed as tested. No playback mutation was performed, and no credential or private account content was printed or added to the repository.

Worked on by

• @VACInc

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review in progress

ClawSweeper is reviewing this revision. This supersedes any previous blocked status.

View the workflow run.

[clawsweeper]

Codex review: blocked before merge. Reviewed September 4, 2026, 3:00 PM ET / 19:00 UTC.

ClawSweeper review

What this changes

This PR adds optional local Spotify OAuth with PKCE, secure per-profile token caching, and OAuth-backed Web API access while retaining cookie authentication and Connect support.

Merge readiness

⛔ Blocked before merge - 5 items remain

Keep open: the exact PR head still lets cookie-required Connect and auto operations fall through to an OAuth-backed Web API client when cookies are absent. The persistent credential flow also needs recorded maintainer acceptance required by the repository vision.

Priority: P1
Reviewed head: 62f34e81700bb1d705dc1e56735aa24af319605a
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	Strong real OAuth proof accompanies a high-impact compatibility defect requiring a narrow repair and product confirmation.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (terminal): The supplied redacted exact-head terminal trace exercises an installed CLI with an expired real OAuth token through refresh and authenticated Web API reads; it sufficiently demonstrates the OAuth path, while also exposing the separate Connect/auto compatibility defect.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (terminal): The supplied redacted exact-head terminal trace exercises an installed CLI with an expired real OAuth token through refresh and authenticated Web API reads; it sufficiently demonstrates the OAuth path, while also exposing the separate Connect/auto compatibility defect.
Evidence reviewed	6 items	Introduced routing change: The PR injects the selected Web API client into Connect. When OAuth is selected, that client is OAuth-backed rather than cookie-backed. Reachable fallback path: A failed Connect GraphQL search unconditionally calls the Connect Web API fallback, which now uses the injected OAuth client and can therefore succeed after the cookie authentication error. Existing engine contract: The repository vision says automatic fallbacks must not hide an authentication failure; the PR's own engine documentation says Connect and auto still require browser cookies.
Findings	1 actionable finding	[P1] Preserve missing-cookie failures before OAuth fallbacks
Security	None	None.

How this fits together

spogo is a Spotify command-line client. Commands choose an engine, which uses browser cookies for Connect endpoints and either cookies or OAuth tokens for public Web API requests.

flowchart LR
  Command[CLI command] --> Settings[Profile and flags]
  Settings --> Engine[Selected engine]
  Settings --> Cookies[Browser cookies]
  Settings --> OAuth[OAuth token cache]
  Engine --> Connect[Connect endpoints]
  Engine --> Web[Spotify Web API]
  Cookies --> Connect
  Cookies --> Web
  OAuth --> Web

Loading

Decision needed

Question	Recommendation
After the compatibility repair, should spogo adopt this optional persistent Spotify OAuth credential flow?	Approve the bounded OAuth mode: Accept OAuth only for the existing Web API surface after the cookie-required Connect and auto contract is restored.

Why: VISION.md requires an explicit product decision for persistent credential flows, and the supplied discussion does not record a maintainer-authored approval.

Before merge

• Preserve missing-cookie failures before OAuth fallbacks (P1) - The injected OAuth Web API client lets a failed Connect GraphQL request fall through and succeed without the browser-cookie session Connect requires. This contradicts the documented connect and auto contract; reject missing cookies before these fallbacks and cover both engine selections.
• Resolve merge risk (P1) - Merging as-is changes documented connect and auto behavior: a user without browser cookies can receive successful OAuth Web API results instead of the expected authentication failure.
• Resolve merge risk (P1) - The new persistent OAuth credential flow has no maintainer-authored approval in the supplied review context, despite VISION.md requiring an explicit product decision.
• Complete next step (P2) - Restore cookie-required failures before OAuth-backed Connect and auto fallbacks, add focused regressions, and record maintainer acceptance of the persistent OAuth flow.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

• [P1] Preserve missing-cookie failures before OAuth fallbacks — internal/app/context_factory.go:47-52

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production versus tests	production +1415/-207; tests +1745/-25	The feature has substantial focused regression coverage, but its routing change spans credential, engine, and compatibility boundaries.

Merge-risk options

Maintainer options:

1. Restore the cookie boundary (recommended)
   Make Connect and auto return the missing-cookie error before any OAuth-backed Web API fallback can run.
2. Explicitly broaden engine semantics
   If OAuth-only Connect/auto fallback is intentional, obtain product approval and revise the documented engine contract with upgrade coverage.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Restore cookie-required failures before OAuth-backed Connect and auto fallbacks, and add focused regressions.

Technical review

Best possible solution:

Retain the bounded OAuth Web API feature, but reject missing cookies before Connect or Connect-first auto fallbacks and record maintainer acceptance of the persistent local credential flow.

Do we have a high-confidence way to reproduce the issue?

Yes—source inspection gives a high-confidence path: configure OAuth without cookies and invoke a Connect-first operation whose internal request fails and falls through to the injected Web API client.

Is this the best way to solve the issue?

No—the OAuth feature is viable, but this implementation must preserve the existing missing-cookie failure before using OAuth Web API fallback from Connect or auto.

Full review comments:

• [P1] Preserve missing-cookie failures before OAuth fallbacks — internal/app/context_factory.go:47-52
  The injected OAuth Web API client lets a failed Connect GraphQL request fall through and succeed without the browser-cookie session Connect requires. This contradicts the documented connect and auto contract; reject missing cookies before these fallbacks and cover both engine selections.
  Confidence: 0.95

Overall correctness: patch is incorrect
Overall confidence: 0.95

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against e89c46fefed8.

Labels

Label justifications:

• P1: Cookie-required Connect and auto operations can currently complete through OAuth fallback instead of reporting the documented authentication failure.
• merge-risk: 🚨 compatibility: The patch can alter existing engine behavior for profiles without browser cookies.
• merge-risk: 🚨 auth-provider: The injected Web API client changes which credential provider Connect fallback paths consume.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The supplied redacted exact-head terminal trace exercises an installed CLI with an expired real OAuth token through refresh and authenticated Web API reads; it sufficiently demonstrates the OAuth path, while also exposing the separate Connect/auto compatibility defect.
• proof: sufficient: Contributor real behavior proof is sufficient. The supplied redacted exact-head terminal trace exercises an installed CLI with an expired real OAuth token through refresh and authenticated Web API reads; it sufficiently demonstrates the OAuth path, while also exposing the separate Connect/auto compatibility defect.

Evidence

Acceptance criteria:

• [P1] go test ./internal/app ./internal/spotify.
• [P1] go test ./...

What I checked:

• Introduced routing change: The PR injects the selected Web API client into Connect. When OAuth is selected, that client is OAuth-backed rather than cookie-backed. (internal/app/context_factory.go:47, 62f34e81700b)
• Reachable fallback path: A failed Connect GraphQL search unconditionally calls the Connect Web API fallback, which now uses the injected OAuth client and can therefore succeed after the cookie authentication error. (internal/spotify/connect_search.go:18, 62f34e81700b)
• Existing engine contract: The repository VISION.md says automatic fallbacks must not hide an authentication failure; the PR's own engine documentation says Connect and auto still require browser cookies. (VISION.md:29, e89c46fefed8)
• Provided real-behavior proof: The PR body contains a redacted terminal trace for exact head 62f34e8 showing successful auto Web API fallback without cookies, which corroborates the contract violation while strongly demonstrating the OAuth Web API path. (62f34e81700b)
• Product-policy requirement: VISION.md requires an explicit product decision for new persistent credential flows; the supplied context has no maintainer-authored approval recording that decision. (VISION.md:49, e89c46fefed8)
• Feature-history routing: Recent history identifies steipete/Peter Steinberger as the author of the current-main Connect and engine work closest to this compatibility boundary. (internal/spotify/connect_search.go:18, 5a8cb40c3d26)

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Restore missing-cookie errors before OAuth-backed Connect and auto fallbacks, with focused regressions.
• Record maintainer acceptance of the bounded persistent OAuth credential flow.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (9 earlier review cycles; latest 8 shown)

• reviewed 2026-08-28T02:50:48.181Z sha 12fed0b :: needs real behavior proof before merge. :: [P2] Persist cookie auth before deleting the OAuth cache
• reviewed 2026-09-03T00:04:51.426Z sha 2d85ec8 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-03T00:12:06.846Z sha 2d85ec8 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-03T00:25:06.789Z sha 2d85ec8 :: blocked before merge. :: [P2] Keep OAuth token paths inside the credential directory
• reviewed 2026-09-03T01:26:27.488Z sha 377856a :: blocked before merge. :: none
• reviewed 2026-09-04T11:00:42.027Z sha 62f34e8 :: blocked before merge. :: none
• reviewed 2026-09-04T15:11:48.310Z sha 62f34e8 :: blocked before merge. :: [P2] Preserve missing-cookie failures before OAuth fallback
• reviewed 2026-09-04T16:54:46.717Z sha 62f34e8 :: blocked before merge. :: [P1] Preserve missing-cookie failures before OAuth fallbacks

[VACInc]

@steipete, this should now be ready for your approval and merge when you’re happy with it. I cannot merge it myself because VACInc currently has read-only access to openclaw/spogo. 😂

The current head includes the repairs from #61, the additional cross-profile config serialization, and the profile-derived path containment fix from the latest ClawSweeper review. CI is green, the final security review found no remaining path or collision issues, and the PR body contains redacted real-account proof from the installed final binary: automatic token refresh plus successful search and saved-library reads with zero stderr.

Could you provide the explicit bounded OAuth approval required by VISION.md and merge this if it looks good to you?

I’d also love to help with spogo going forward. I’ve subscribed to the repository so I can follow new work and reviews.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: feat(auth): add Spotify OAuth PKCE This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.