Documentation
¶
Overview ¶
Package sso refreshes the EVE SSO tokens that authenticated ESI calls need.
A stored token is a refresh token plus a short-lived access token, and the refresh token is the valuable half: it survives until the user revokes consent, and losing it means asking them to log in again. So the write path here is careful — a token is only ever disabled on evidence that it is permanently dead, never on a transient failure.
Scopes are the subtle part, and the reason this package is more than an HTTP call. See RevokedScopes below.
Index ¶
- Constants
- Variables
- func CharacterIDFromAccessToken(accessToken string) (int32, error)
- func Disable(ctx context.Context, pool *pgxpool.Pool, characterID int32, clearScopes bool) error
- func RecordCharacterKillmailFailure(ctx context.Context, pool *pgxpool.Pool, characterID int32) error
- func ResetCharacterKillmailFailures(ctx context.Context, pool *pgxpool.Pool, characterID int32) error
- func RevokeScope(ctx context.Context, pool *pgxpool.Pool, characterID int32, scope string) error
- func ScopesFromAccessToken(accessToken string) ([]string, error)
- func StaleTokens(ctx context.Context, pool *pgxpool.Pool, within time.Duration, limit int) ([]int32, error)
- func StoreRefreshed(ctx context.Context, pool *pgxpool.Pool, characterID int32, ...) (bool, error)
- type AccessClaims
- type AuthorizationCodeTokens
- type Client
- type OAuthClient
- type Token
Constants ¶
const ( // AuthorizationURL is EVE SSO's authorization-code endpoint. AuthorizationURL = "https://login.eveonline.com/v2/oauth/authorize" // JWKSURL publishes the keys used to sign EVE access tokens. JWKSURL = "https://login.eveonline.com/oauth/jwks" )
const ( ScopeCharacterKillmails = "esi-killmails.read_killmails.v1" ScopeCorporationKillmails = "esi-killmails.read_corporation_killmails.v1" ScopeCorporationWallet = "esi-wallet.read_corporation_wallets.v1" )
Scopes worth naming, because a job is dispatched for each.
const TokenURL = "https://login.eveonline.com/v2/oauth/token"
TokenURL is where a refresh token is exchanged for an access token.
Variables ¶
var ErrPermanentlyDead = errors.New("refresh token is permanently dead")
ErrPermanentlyDead means the refresh token will never work again — the user revoked consent, or CCP invalidated it. Distinct from a transient failure because the response is different: disable the token rather than retry it.
Functions ¶
func CharacterIDFromAccessToken ¶
CharacterIDFromAccessToken reads the EVE character id from the JWT subject.
Like ScopesFromAccessToken, this decodes a token received directly from SSO over TLS. The wallet worker uses it to ensure a rotated refresh token did not unexpectedly change owners.
func RecordCharacterKillmailFailure ¶
func RecordCharacterKillmailFailure( ctx context.Context, pool *pgxpool.Pool, characterID int32, ) error
RecordCharacterKillmailFailure counts consecutive 403s from a character's own killmail endpoint.
A single 403 is not enough evidence to retire a token: role and ESI state can briefly disagree. Once five consecutive requests fail, the token is disabled only if its corporation-killmail side is unusable too. This preserves tokens that can still contribute corporation kills.
func ResetCharacterKillmailFailures ¶
func ResetCharacterKillmailFailures( ctx context.Context, pool *pgxpool.Pool, characterID int32, ) error
ResetCharacterKillmailFailures clears the consecutive-403 streak after a successful character request.
func RevokeScope ¶
RevokeScope records that a scope SSO grants cannot actually be exercised.
This exists because of a specific, expensive failure. SSO re-grants every scope the user ever consented to on every refresh, with no idea whether the character can still use it — the corporation killmail endpoint additionally requires an in-game role that the user may have lost. Before this existed the 403 handler stripped the scope, the next refresh wrote it straight back from the JWT, and the cycle repeated: 180 characters produced 525,000 403s in a month, all against the shared ESI error budget.
The revocation is therefore stored separately from the granted list, so a refresh cannot undo it.
func ScopesFromAccessToken ¶
ScopesFromAccessToken reads the granted scopes out of the access token.
The access token is a JWT and carries its scopes in the `scp` claim, so they can be read without a second request. CCP removed the /oauth/verify endpoint that used to answer this in March 2026, which is what forced the change.
The signature is deliberately NOT verified here. That sounds alarming and is not: this token was received over TLS directly from SSO in the response to our own authenticated request moments ago, so its provenance is already established — there is no untrusted party in between to forge it. Verifying would mean fetching and caching CCP's JWKS and failing refreshes whenever that endpoint is unwell, for no gain. A token that is somehow malformed fails at the first ESI call instead, which is a cheaper and more honest place to find out.
func StaleTokens ¶
func StaleTokens(ctx context.Context, pool *pgxpool.Pool, within time.Duration, limit int) ([]int32, error)
StaleTokens returns tokens due for a refresh, soonest expiry first.
A token is refreshed before it expires rather than after: an access token lasts twenty minutes and a job that picks one up at nineteen would spend its whole run racing the clock.
func StoreRefreshed ¶
func StoreRefreshed( ctx context.Context, pool *pgxpool.Pool, characterID int32, previousRefreshToken string, r *refreshResponse, usable []string, ) (bool, error)
StoreRefreshed writes a successful refresh if the row still contains the refresh token we exchanged.
EVE rotates refresh tokens. A user can re-authorize while a refresh worker is in flight; without the compare-and-swap predicate, the older worker can overwrite the brand-new authorization with its stale token lineage. False means another writer won and its newer credentials must be left untouched.
Types ¶
type AccessClaims ¶
type AccessClaims struct {
CharacterID int32
CharacterName string
CharacterOwnerHash string
Scopes []string
}
AccessClaims is the identity and scope subset carried by EVE's access JWT.
type AuthorizationCodeTokens ¶
type AuthorizationCodeTokens struct {
AccessToken string
RefreshToken string
ExpiresIn int
TokenType string
}
AuthorizationCodeTokens is the successful authorization-code response. Refresh tokens are deliberately never exposed by an HTTP API; this type is only passed to the transactional login store.
type Client ¶
type Client struct {
ClientID string
ClientSecret string
UserAgent string
HTTP *http.Client
// TokenURL is overridable for tests.
TokenURL string
}
Client refreshes tokens against EVE SSO.
func (*Client) Refresh ¶
Refresh exchanges a refresh token for a new access token.
Returns ErrPermanentlyDead when SSO says the grant is gone, which the caller turns into a disabled token. Any other failure is transient and worth retrying: SSO has bad minutes, and disabling a live token on one of them costs the user a re-login.
type OAuthClient ¶
type OAuthClient struct {
ClientID string
ClientSecret string
CallbackURL string
UserAgent string
HTTP *http.Client
// Endpoint overrides exist for deterministic tests.
AuthorizeURL string
TokenURL string
JWKSURL string
// contains filtered or unexported fields
}
OAuthClient implements EVE's confidential authorization-code flow.
The remote key set is process-local and long-lived. coreos/go-oidc refreshes it when a token references an unknown key, so ordinary requests do not make a JWKS round trip.
func (*OAuthClient) BuildAuthorizationURL ¶
func (c *OAuthClient) BuildAuthorizationURL(state string, scopes []string) (string, error)
BuildAuthorizationURL creates an EVE SSO authorization URL for a state that has already been browser-bound by the caller.
func (*OAuthClient) ExchangeCode ¶
func (c *OAuthClient) ExchangeCode( ctx context.Context, code string, ) (AuthorizationCodeTokens, error)
ExchangeCode exchanges a one-time authorization code using HTTP Basic client authentication, matching EVE's confidential web-application flow.
func (*OAuthClient) VerifyAccessToken ¶
func (c *OAuthClient) VerifyAccessToken( ctx context.Context, accessToken string, ) (AccessClaims, error)
VerifyAccessToken verifies signature, expiry, audience, issuer, and EVE's character subject before returning identity claims.
type Token ¶
type Token struct {
CharacterID int32
AccessToken string
RefreshToken string
Expiry time.Time
Scopes []string
DelayHours int
// RevokedScopes are scopes SSO keeps granting that this character cannot
// actually exercise. See Refresh for why they are tracked separately.
RevokedScopes []string
CharacterFailureCount int
Disabled bool
}
Token is a stored SSO token.