sso

package
v0.1.49 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 31, 2026 License: MIT Imports: 17 Imported by: 0

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

View Source
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"
)
View Source
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.

View Source
const TokenURL = "https://login.eveonline.com/v2/oauth/token"

TokenURL is where a refresh token is exchanged for an access token.

Variables

View Source
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

func CharacterIDFromAccessToken(accessToken string) (int32, error)

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 Disable

func Disable(ctx context.Context, pool *pgxpool.Pool, characterID int32, clearScopes bool) error

Disable stops a token being refreshed again.

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

func RevokeScope(ctx context.Context, pool *pgxpool.Pool, characterID int32, scope string) error

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

func ScopesFromAccessToken(accessToken string) ([]string, error)

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

func (c *Client) Refresh(ctx context.Context, refreshToken string) (*refreshResponse, error)

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.

func LoadToken

func LoadToken(ctx context.Context, pool *pgxpool.Pool, characterID int32) (*Token, error)

LoadToken reads a stored token.

func (Token) Has

func (t Token) Has(scope string) bool

Has reports whether a usable scope is present.

func (Token) Usable

func (t Token) Usable() []string

Usable reports the scopes worth acting on — granted and not locally revoked.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL