Documentation
¶
Overview ¶
Package auth implements the Spotify OAuth 2.0 PKCE flow for Aria.
Flow: SignIn generates a PKCE verifier/challenge, opens the system browser to Spotify's consent page, runs a loopback HTTP server on the registered redirect URI to catch the auth code, and exchanges that code for an access+refresh token pair. The refresh token (and its rotated successors) persists in the OS keyring so the user only signs in once per machine.
Index ¶
Constants ¶
const ( // SessionClientID is librespot's KEYMASTER_CLIENT_ID — the id its own // OAuth flow uses, and the one whose tokens spclient accepts. SessionClientID = "65b708073fc0480ea92a077233ca87bd" // SessionRedirectURI is the loopback URI registered for // SessionClientID. librespot uses this exact host, port and path; it // is not ours to choose. SessionRedirectURI = "http://127.0.0.1:5588/login" )
The librespot session needs its own grant, minted by the client-id librespot itself uses. Aria's registered client-id cannot serve it: Spotify binds the access point's reusable credential to whichever client-id produced the OAuth token, login5's /v3/login only honours first-party ids, and spclient's connect-state PUT — the call that registers Aria as a Connect device — 403s for a third-party bearer regardless of scopes (verified 2026-08-10 with app-remote-control granted). Conversely this id is heavily rate-limited on the Web API (429 on every call, while the Aria-id token succeeds), so it is used ONLY for lrs_start_with_token. Two grants, each where it is accepted.
const ( // WebAPITokenKey holds the Web API grant. WebAPITokenKey = "web-api-token" // SessionTokenKey holds the librespot grant (see SessionClientID). SessionTokenKey = "session-token" // CredentialsKey holds the librespot credential blob (credentials.go). CredentialsKey = "librespot-credentials" )
The secret keys this package stores under, in the provider's own space. The host keeps them (Services.Secrets); spotify.Registration claims the keyring entries they lived in before the provider existed.
const DefaultClientID = "1c4416e8bb8a4a09979dd5d7638c83a6"
DefaultClientID is the OAuth client_id registered for Aria.fm on the Spotify developer dashboard. It is not a secret (PKCE doesn't use a client secret; the redirect URI plus PKCE verifier provide proof of possession), so committing it to source is fine.
const DefaultRedirectURI = "http://127.0.0.1:8888/callback"
DefaultRedirectURI matches the loopback URL registered in the Spotify dashboard for DefaultClientID. listenCallback binds to the host:port portion.
Variables ¶
var DefaultScopes = []string{
"user-read-playback-state",
"user-modify-playback-state",
"user-read-currently-playing",
"streaming",
"user-library-read",
"user-library-modify",
"user-follow-read",
"user-follow-modify",
"playlist-read-private",
"playlist-read-collaborative",
"playlist-modify-private",
"playlist-modify-public",
"user-read-private",
"user-read-email",
}
DefaultScopes covers everything Aria touches through M2: playback control, currently-playing readout, library + follow reads and writes (the right-click Save / Follow context-menu actions), playlist reads and modifies, and the "streaming" scope required for Spotify Connect device emission.
ErrKeyringUnavailable means there is no usable OS keyring in this session — distinct from the keyring working and holding no token (ErrNotSignedIn), and from it failing for a real reason.
On Linux this is the freedesktop Secret Service being absent: a minimal WM session, a container, or a Flatpak without --talk-name=org.freedesktop.secrets. Startup treats it as "not signed in" rather than fatal, because the alternative is the app refusing to open at all; see the comment on keyringUnavailable and the handling in New.
Sign-in will still fail at save() on such a session, which is the right place for it to fail: the user is doing something that genuinely requires persistence, and gets an error naming the keyring.
var ErrNoCredentials = errors.New("auth: no stored librespot credentials")
ErrNoCredentials means the keyring holds no stored credential — the ordinary state before the first successful librespot session, and after one is discarded. Callers fall back to the OAuth grant.
var ErrNotACredential = errors.New("auth: not a librespot credential")
ErrNotACredential means the blob is not a serialized librespot Credentials object with usable auth_data. Storing it would guarantee a failed login on the next launch, and the FFI would reject it anyway.
var ErrNotSignedIn = errors.New("auth: not signed in")
ErrNotSignedIn means no persisted token was found.
var ErrRefreshTokenRevoked = errors.New("auth: refresh token revoked")
ErrRefreshTokenRevoked means the persisted refresh token is no longer valid — the token endpoint answered 400 invalid_grant (revoked, password change, scope revocation). Unlike a transient failure this can't be retried; the user must sign in again. Callers should treat it as a sign-out + re-auth prompt, not a reconnect.
var SessionScopes = []string{
"streaming",
"app-remote-control",
"user-read-playback-state",
"user-modify-playback-state",
"user-read-currently-playing",
"user-read-private",
"user-read-email",
}
SessionScopes is what the librespot session needs and nothing more — the account reads and library writes stay on the Web API grant.
Functions ¶
func ValidateCredentialBlob ¶
ValidateCredentialBlob reports whether a blob is a serialized librespot Credentials object Aria can replay: parseable, with a username and a non-empty auth_data. It deliberately does NOT reject unknown keys — discovery adds "source":"zeroconf" and the Rust side ignores extras, so rejecting them here would refuse the phone handoff for being well documented.
Exported because the app layer validates before it decides to store, and duplicating the shape check is how the two drift.
Types ¶
type Config ¶
type Config struct {
ClientID string
RedirectURI string
Scopes []string
// Secrets is where the grant is kept: the provider's own secrets, from
// the host (Services.Secrets). Required.
Secrets host.Secrets
// SecretKey names the entry this Manager reads and writes. Empty means
// WebAPITokenKey; the librespot grant uses SessionTokenKey so the two
// coexist.
SecretKey string
}
Config configures a Manager. RedirectURI must match exactly one of the Redirect URIs registered in the Spotify developer dashboard for ClientID.
type CredentialStore ¶
type CredentialStore struct {
// contains filtered or unexported fields
}
CredentialStore persists one credential blob in the provider's secrets.
It reaches storage only through host.Secrets, never the OS keyring directly. That is what keeps tests honest: a test that reached the real Secret Service would edit the machine it runs on, and once left a `{}` entry in the developer's own keyring, written by a test asserting that Save rejects `{}`. Tests hand it in-memory secrets instead.
func NewCredentialStore ¶
func NewCredentialStore(secrets host.Secrets) *CredentialStore
NewCredentialStore returns the store over the provider's secrets.
func (*CredentialStore) Clear ¶
func (c *CredentialStore) Clear() error
Clear removes the stored blob. Absent is success — the caller wanted it gone, and it is.
func (*CredentialStore) Load ¶
func (c *CredentialStore) Load() (string, error)
Load returns the stored blob verbatim — byte-identical to what the FFI emitted, because that is what lrs_start_with_credentials must be handed. Returns ErrNoCredentials when there is none, and ErrKeyringUnavailable on a session with no Secret Service (same distinction the token store draws: "nothing stored" is not "storage is broken").
func (*CredentialStore) Save ¶
func (c *CredentialStore) Save(blob string) (changed bool, err error)
Save replaces the stored blob. Validates first: the only thing worth keeping is something the FFI will accept.
Reports whether it actually wrote. The caller logs the difference, because "stored your credentials" on a launch that stored nothing is a log line that lies about what the process did.
Idempotent. The FFI emits CREDENTIALS_STORED after EVERY successful login, so without this the same bytes would be written to the keyring on every launch (aria.fm-togj). A read is the cheaper of the two operations and the one least likely to prompt, duplicate an item, or wake a locked keyring — this project has already been bitten by a keyring backend that duplicated on write rather than replacing.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager is the auth surface used by app.App. Methods are goroutine-safe.
func (*Manager) GetAccessToken ¶
GetAccessToken returns a non-expired access token, refreshing if needed. At most one refresh round-trip is in flight at a time; concurrent callers block on it and reuse its result.
func (*Manager) IsSignedIn ¶
IsSignedIn reports whether a refresh token is held. It does not validate the token against Spotify.
func (*Manager) SignIn ¶
SignIn drives the full interactive flow, opening the browser itself. Blocks until the user completes or denies consent. Safe to call when already signed in (replaces token). The host's sign-in goes through StartSignIn instead, so the host opens the page.
func (*Manager) StartSignIn ¶
StartSignIn binds the callback listener and returns the consent page to open, and a wait that blocks until the callback arrives (or ctx ends), exchanges the code, and persists the grant. The listener is bound before this returns, so the page can't redirect to a closed port. wait must be called exactly once; it closes the listener.
type Token ¶
type Token struct {
AccessToken string `json:"access_token"`
RefreshToken string `json:"refresh_token"`
ExpiresAt time.Time `json:"expires_at"`
Scope string `json:"scope"`
}
Token is the persisted shape. Access token is included so we can avoid a refresh round-trip on every cold start, but it's short-lived (1h) so callers must check ExpiresAt before use.