{server,storage}: add LoggedIn flag to AuthRequest and improve storage docs

Currently, whether or not a user has authenticated themselves through
a connector is indicated by a pointer being nil or non-nil. Instead
add an explicit flag that marks this.

storage/storage.go

@@ -70,28 +70,41 @@ type Storage interface {
 	DeleteRefresh(id string) error
 
 	// Update functions are assumed to be a performed within a single object transaction.
+	//
+	// updaters may be called multiple times.
 	UpdateClient(id string, updater func(old Client) (Client, error)) error
 	UpdateKeys(updater func(old Keys) (Keys, error)) error
 	UpdateAuthRequest(id string, updater func(a AuthRequest) (AuthRequest, error)) error
+
+	// TODO(ericchiang): Add a GarbageCollect(now time.Time) method so conformance tests
+	// can test implementations.
 }
 
-// Client is an OAuth2 client.
+// Client represents an OAuth2 client.
 //
 // For further reading see:
 //   * Trusted peers: https://developers.google.com/identity/protocols/CrossClientAuth
 //   * Public clients: https://developers.google.com/api-client-library/python/auth/installed-app
 type Client struct {
-	ID           string   `json:"id" yaml:"id"`
-	Secret       string   `json:"secret" yaml:"secret"`
+	// Client ID and secret used to identify the client.
+	ID     string `json:"id" yaml:"id"`
+	Secret string `json:"secret" yaml:"secret"`
+
+	// A registered set of redirect URIs. When redirecting from dex to the client, the URI
+	// requested to redirect to MUST match one of these values, unless the client is "public".
 	RedirectURIs []string `json:"redirectURIs" yaml:"redirectURIs"`
 
-	// TrustedPeers are a list of peers which can issue tokens on this client's behalf.
+	// TrustedPeers are a list of peers which can issue tokens on this client's behalf using
+	// the dynamic "oauth2:server:client_id:(client_id)" scope. If a peer makes such a request,
+	// this client's ID will appear as the ID Token's audience.
+	//
 	// Clients inherently trust themselves.
 	TrustedPeers []string `json:"trustedPeers" yaml:"trustedPeers"`
 
 	// Public clients must use either use a redirectURL 127.0.0.1:X or "urn:ietf:wg:oauth:2.0:oob"
 	Public bool `json:"public" yaml:"public"`
 
+	// Name and LogoURL used when displaying this client to the end user.
 	Name    string `json:"name" yaml:"name"`
 	LogoURL string `json:"logoURL" yaml:"logoURL"`
 }
@@ -109,53 +122,79 @@ type Claims struct {
 // AuthRequest represents a OAuth2 client authorization request. It holds the state
 // of a single auth flow up to the point that the user authorizes the client.
 type AuthRequest struct {
-	ID       string
+	// ID used to identify the authorization request.
+	ID string
+
+	// ID of the client requesting authorization from a user.
 	ClientID string
 
+	// Values parsed from the initial request. These describe the resources the client is
+	// requesting as well as values describing the form of the response.
 	ResponseTypes []string
 	Scopes        []string
 	RedirectURI   string
-
-	Nonce string
-	State string
+	Nonce         string
+	State         string
 
 	// The client has indicated that the end user must be shown an approval prompt
 	// on all requests. The server cannot cache their initial action for subsequent
 	// attempts.
 	ForceApprovalPrompt bool
 
+	Expiry time.Time
+
+	// Has the user proved their identity through a backing identity provider?
+	//
+	// If false, the following fields are invalid.
+	LoggedIn bool
+
 	// The identity of the end user. Generally nil until the user authenticates
 	// with a backend.
-	Claims *Claims
+	Claims Claims
 
 	// The connector used to login the user and any data the connector wishes to persists.
 	// Set when the user authenticates.
 	ConnectorID   string
 	ConnectorData []byte
-
-	Expiry time.Time
 }
 
 // AuthCode represents a code which can be exchanged for an OAuth2 token response.
+//
+// This value is created once an end user has authorized a client, the server has
+// redirect the end user back to the client, but the client hasn't exchanged the
+// code for an access_token and id_token.
 type AuthCode struct {
+	// Actual string returned as the "code" value.
 	ID string
 
-	ClientID    string
+	// The client this code value is valid for. When exchanging the code for a
+	// token response, the client must use its client_secret to authenticate.
+	ClientID string
+
+	// As part of the OAuth2 spec when a client makes a token request it MUST
+	// present the same redirect_uri as the initial redirect. This values is saved
+	// to make this check.
+	//
+	// https://tools.ietf.org/html/rfc6749#section-4.1.3
 	RedirectURI string
 
-	ConnectorID   string
-	ConnectorData []byte
-
+	// If provided by the client in the initial request, the provider MUST create
+	// a ID Token with this nonce in the JWT payload.
 	Nonce string
 
+	// Scopes authorized by the end user for the client.
 	Scopes []string
 
-	Claims Claims
+	// Authentication data provided by an upstream source.
+	ConnectorID   string
+	ConnectorData []byte
+	Claims        Claims
 
 	Expiry time.Time
 }
 
-// RefreshToken is an OAuth2 refresh token.
+// RefreshToken is an OAuth2 refresh token which allows a client to request new
+// tokens on the end user's behalf.
 type RefreshToken struct {
 	// The actual refresh token.
 	RefreshToken string
@@ -163,17 +202,19 @@ type RefreshToken struct {
 	// Client this refresh token is valid for.
 	ClientID string
 
+	// Authentication data provided by an upstream source.
 	ConnectorID   string
 	ConnectorData []byte
+	Claims        Claims
 
 	// Scopes present in the initial request. Refresh requests may specify a set
 	// of scopes different from the initial request when refreshing a token,
 	// however those scopes must be encompassed by this set.
 	Scopes []string
 
+	// Nonce value supplied during the initial redirect. This is required to be part
+	// of the claims of any future id_token generated by the client.
 	Nonce string
-
-	Claims Claims
 }
 
 // VerificationKey is a rotated signing key which can still be used to verify
@@ -188,6 +229,7 @@ type Keys struct {
 	// Key for creating and verifying signatures. These may be nil.
 	SigningKey    *jose.JSONWebKey
 	SigningKeyPub *jose.JSONWebKey
+
 	// Old signing keys which have been rotated but can still be used to validate
 	// existing signatures.
 	VerificationKeys []VerificationKey