auth

type Identity struct {
	// UserID is a stable unique identifier for the user.  This may be a large
	// integer or a UUID, rather than something human-readable.
	//
	// For KeyCloak, this is `sub`.
	UserID string
	// HumanName is a human-readable name.  Because humans are fickle, these may
	// not be unique or stable over time, though they should be unique at any
	// particular time.  For example, Alex may change their handle from
	// "alexsmith" to "alexawesome" after a life change, and someone else might
	// enroll the "alexsmith" handle.  If you are storing data, you want UserID,
	// not HumanName.  If you are presenting data, you probably want HumanName.
	//
	// For KeyCloak, this is `preferred_username`.  For some other providers,
	// this might be an email address.
	HumanName string
	// Provider is the identity provider that vended this identity.  Note that
	// UserID and HumanName are only unique within the context of a single
	// identity provider.
	Provider IdentityProvider
	// FirstName and LastName are optional fields that may be provided by the
	// identity provider. These are not guaranteed to be present, and may be
	// empty.
	FirstName string
	LastName  string
}

type IdentityClient struct {
	// contains filtered or unexported fields
}

type IdentityProvider interface {
	Resolver

	// String returns the name of the identity provider.  This should be a short
	// one-word string suitable for presentation.  As a special case, a _single_
	// provider may use the empty string as its name to act as a default / fallback
	// provider.
	String() string
	// URL returns the `iss` URL of the identity provider.
	URL() url.URL
}

type Resolver interface {

	// Validate validates a token and returns an underlying identity representation
	// suitable for use in authz calls.  This _probably_ reads data from the token,
	// but could fetch from an external provider.
	Validate(ctx context.Context, token jwt.Token) (*Identity, error)

	// Resolve takes either a human-readable identifier or a stable identifier and
	// returns the underlying identity.  This may involve looking up or defining
	// the identity in the remote identity provider.
	//
	// For Keycloak + GitHub, this may define a new user in Keycloak based on
	// GitHub user data if the user is not already known to Keycloak.
	Resolve(ctx context.Context, id string) (*Identity, error)
}