playertoken

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 13 Imported by: 0

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

View Source
const Algorithm = "EdDSA"

Algorithm is the only JWS algorithm a token may name.

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

View Source
const JWKSPath = "/lobby/v1/jwks.json"

JWKSPath is where the lobby publishes its keys, under its URL.

View Source
const Leeway = 30 * time.Second

Leeway is how long after exp a Verifier still accepts a token, for clocks that differ a little.

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

View Source
const RefreshInterval = time.Minute

RefreshInterval is how often a JWKSSource fetches the keys at most.

Variables

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

func FromAuthorization(authorization string) (string, bool)

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.

func (*JWKSSource) PublicKey

func (source *JWKSSource) PublicKey(ctx context.Context, keyID string) (ed25519.PublicKey, error)

PublicKey returns the key with keyID, fetching the JWKS first when the keys are stale, and again when they don't have keyID.

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

func ParseKeySet(value string) (*KeySet, error)

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.

func (*KeySet) JWKS

func (set *KeySet) JWKS() JWKS

JWKS returns every key's public half, the signing key first.

func (*KeySet) PublicKey

func (set *KeySet) PublicKey(_ context.Context, keyID string) (ed25519.PublicKey, error)

PublicKey makes the set the in-process KeySource.

func (*KeySet) Sign

func (set *KeySet) Sign(claims Claims) (string, error)

Sign returns claims as a token signed with the set's first key.

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

func (verifier *Verifier) Verify(ctx context.Context, token, audience string) (Player, error)

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.

Jump to

Keyboard shortcuts

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