// Package identity defines services for identity providers in the vanadium ecosystem.
package identity

import "v.io/v23/security"

// OAuthBlesser exchanges OAuth access tokens for
// an email address from an OAuth-based identity provider and uses the email
// address obtained to bless the client.
//
// OAuth is described in RFC 6749 (http://tools.ietf.org/html/rfc6749),
// though the Google implementation also has informative documentation at
// https://developers.google.com/accounts/docs/OAuth2
//
// WARNING: There is no binding between the channel over which the access token
// was obtained (typically https) and the channel used to make the RPC (a
// vanadium virtual circuit).
// Thus, if Mallory possesses the access token associated with Alice's account,
// she may be able to obtain a blessing with Alice's name on it.
type OAuthBlesser interface {
  // BlessUsingAccessToken uses the provided access token to obtain the email
  // address and returns a blessing along with the email address.
  BlessUsingAccessToken(token string) (blessing security.WireBlessings, email string | error)
}

// MacaroonBlesser returns a blessing given the provided macaroon string.
type MacaroonBlesser interface {
  // Bless uses the provided macaroon (which contains email and caveats)
  // to return a blessing for the client.
  Bless(macaroon string) (blessing security.WireBlessings | error)
}

// BlessingRootResponse is the struct representing the JSON response provided
// by the "blessing-root" route of the identity service.
type BlessingRootResponse struct {
  // Names of the blessings.
  Names []string
  // Base64 der-encoded public key.
  PublicKey string
}