// Copyright 2015 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Package identity defines interfaces for Vanadium identity providers.
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.
//
// TODO(ataly): Get rid of this service once all clients have been
// switched to use the HTTP OAuthBlessingHandler service.
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)
  BlessUsingAccessTokenWithCaveats(token string, caveats []security.Caveat) (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
}