Documentation
¶
Overview ¶
Package playertoken signs and verifies the lobby's player tokens: short-lived JWTs that tell a game which player sends a request, so the game needs neither the lobby's database nor a call to the lobby for each request.
A token is a compact JWS signed with Ed25519 (alg EdDSA, RFC 8037), whose header names the signing key with kid. Its claims are iss, the lobby's public URL; sub, the player ID; aud, the game key; iat and exp, in Unix seconds; and name, the player's display name.
The lobby signs with a KeySet and publishes its public keys as a JWKS. A game verifies tokens with a Verifier, which reads the public keys from a KeySource: a JWKSSource that fetches and caches the lobby's JWKS over HTTP, or the lobby's KeySet itself while the lobby and the game run in one process. The package is game-neutral and has no dependency on the rest of the lobby.
Index ¶
Constants ¶
const Algorithm = "EdDSA"
Algorithm is the only JWS algorithm a token may name.
const DefaultMaxAge = 5 * time.Minute
DefaultMaxAge is how long a JWKSSource keeps keys whose response names no max-age. The lobby's JWKS says max-age=300.
const JWKSPath = "/lobby/v1/jwks.json"
JWKSPath is where the lobby publishes its keys, under its URL.
const Leeway = 30 * time.Second
Leeway is how long after exp a Verifier still accepts a token, for clocks that differ a little.
const MaxLifetime = 15 * time.Minute
MaxLifetime is how long a token lasts at most. The lobby may issue shorter ones, and never one that outlives the player's session.
const RefreshInterval = time.Minute
RefreshInterval is how often a JWKSSource fetches the keys at most.
Variables ¶
var ErrInvalid = errors.New("the player token is not valid")
ErrInvalid is returned for a token that is malformed, not signed by a current key of the lobby, of another issuer or audience, or expired. It says no more, on purpose.
Functions ¶
func FromAuthorization ¶
FromAuthorization returns the credential of an Authorization header with the Bearer scheme, and false for any other header.
Types ¶
type Claims ¶
type Claims struct {
Issuer string `json:"iss"`
Subject string `json:"sub"`
Audience string `json:"aud"`
IssuedAt int64 `json:"iat"`
Expires int64 `json:"exp"`
Name string `json:"name"`
}
Claims are a token's claims, as they are signed.
type JWK ¶
type JWK struct {
KeyType string `json:"kty" enum:"OKP" doc:"Always OKP."`
Curve string `json:"crv" enum:"Ed25519" doc:"Always Ed25519."`
X string `json:"x" doc:"The 32-byte public key, base64url without padding."`
KeyID string `json:"kid" doc:"The key's ID, which a token's header names as kid."`
Algorithm string `json:"alg" enum:"EdDSA" doc:"Always EdDSA."`
Use string `json:"use" enum:"sig" doc:"Always sig."`
}
JWK is one Ed25519 public key (RFC 8037).
type JWKS ¶
type JWKS struct {
Keys []JWK `` /* 153-byte string literal not displayed */
}
JWKS is a JSON Web Key Set (RFC 7517) of the lobby's public keys.
type JWKSOption ¶
type JWKSOption func(*JWKSSource)
JWKSOption configures a JWKSSource.
func WithHTTPClient ¶
func WithHTTPClient(client *http.Client) JWKSOption
WithHTTPClient fetches with client instead of one with a 10 s timeout.
func WithSourceClock ¶
func WithSourceClock(now func() time.Time) JWKSOption
WithSourceClock replaces time.Now; tests use it.
type JWKSSource ¶
type JWKSSource struct {
// contains filtered or unexported fields
}
JWKSSource is the KeySource of a game that runs apart from the lobby: it fetches the lobby's JWKS, GET /lobby/v1/jwks.json, and keeps its keys for the response's max-age. A token that names a key it doesn't have makes it fetch the keys again, so a new key works at once, but it fetches at most once every RefreshInterval. When a fetch fails, it keeps using the keys it has.
func NewJWKSSource ¶
func NewJWKSSource(url string, options ...JWKSOption) (*JWKSSource, error)
NewJWKSSource returns a source that reads the JWKS at url, such as https://lobby.example.org/lobby/v1/jwks.json. It fetches nothing until a key is needed.
type KeySet ¶
type KeySet struct {
// contains filtered or unexported fields
}
KeySet holds the lobby's signing keys. The first signs; all are published and verify. It is also the in-process KeySource for a game that runs in the lobby's process.
func ParseKeySet ¶
ParseKeySet reads a comma-separated list of kid:seed pairs, where seed is an Ed25519 seed of 32 bytes in base64url without padding, as the lobby's LOBBY_PLAYER_TOKEN_KEYS holds them. The first key signs.
type KeySource ¶
type KeySource interface {
// PublicKey returns the public key with keyID. A key the source doesn't
// know is ErrInvalid (wrapped); any other error means the keys couldn't be
// read, such as an unreachable lobby.
PublicKey(ctx context.Context, keyID string) (ed25519.PublicKey, error)
}
KeySource finds the public key a token names with its kid.
type Player ¶
type Player struct {
// ID is the lobby's player ID, the token's sub.
ID string
// Name is the player's display name when the token was issued.
Name string
}
Player is who a valid token stands for.
type Verifier ¶
type Verifier struct {
// contains filtered or unexported fields
}
Verifier checks the tokens of one lobby.
func NewVerifier ¶
func NewVerifier(issuer string, source KeySource, options ...VerifierOption) (*Verifier, error)
NewVerifier returns a Verifier for the tokens that issuer, the lobby's public URL, signs with the keys of source.
func (*Verifier) Verify ¶
Verify checks token for audience, the game's key, and returns its player. It checks the header's alg (only EdDSA) and kid, the Ed25519 signature with that key, iss, aud, and exp with Leeway. A token that fails any check is ErrInvalid; an error reading the keys is returned as it is.
type VerifierOption ¶
type VerifierOption func(*Verifier)
VerifierOption configures a Verifier.
func WithVerifierClock ¶
func WithVerifierClock(now func() time.Time) VerifierOption
WithVerifierClock replaces time.Now; tests use it.