provider

type AccessToken struct {
	// Type is the authorization scheme; "Bearer" when empty.
	Type  string
	Value cf.Secret
	// ExpiresAt is when the token stops working. A zero value means the
	// source does not say, and the token is used once and not kept.
	ExpiresAt time.Time
}

type AuthMethod struct {
	// Key identifies the method, for example "api_token".
	Key    string  `json:"key"`
	Fields []Field `json:"fields"`
	Scopes []Scope `json:"scopes,omitempty"`
	// AccountSelection says how the account is chosen: "discovered" from the
	// credential, or "chosen" by the person from a list.
	AccountSelection string `json:"accountSelection,omitempty"`
	HelpURL          string `json:"helpUrl,omitempty"`
	// Setup is what a person does, in order, to create the credential at
	// the service before entering it.
	Setup []SetupStep `json:"setup,omitempty"`
	// Rotation lists the ways the credential can be replaced over its life,
	// with what each needs. Empty means the method does not describe
	// rotation; a person replaces the credential by reconnecting.
	Rotation []RotationMode `json:"rotation,omitempty"`
}

type Field struct {
	Name     string `json:"name"`
	Label    string `json:"label"`
	Secret   bool   `json:"secret"`
	Required bool   `json:"required"`
	Help     string `json:"help,omitempty"`
}

type Manifest struct {
	// Key identifies the provider, for example "cloudflare".
	Key         string `json:"key"`
	DisplayName string `json:"displayName"`
	// BaseURLs are the only origins a request for this provider may reach.
	BaseURLs    []string     `json:"baseUrls"`
	AuthMethods []AuthMethod `json:"authMethods"`
	HelpURL     string       `json:"helpUrl,omitempty"`
}

type Material struct {
	// Kind names the structure, for example "api_token".
	Kind string
	// Fields holds the credential's values by field name.
	Fields map[string]cf.Secret
	// ExpiresAt is when an access token expires, if it does.
	ExpiresAt *time.Time
}

type Provider interface {
	// Manifest describes the provider. It is data and never changes.
	Manifest() Manifest
	// Validate checks the credential with the provider, using hc, which the
	// caller has restricted to the manifest's hosts, and returns the account
	// it belongs to. A rejection wraps a connectforge provider error.
	Validate(ctx context.Context, hc *http.Client, m Material) (Result, error)
	// Authenticate adds the credential to an outgoing request. The request
	// is the caller's copy.
	Authenticate(r *http.Request, m Material) error
}

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

type Result struct {
	AccountID    string
	AccountLabel string
	// Scopes are the permissions the provider reports for the credential,
	// if it reports them.
	Scopes []string
	// ExpiresAt is when the credential stops working, if the provider
	// reports it; nil when it does not expire or the provider does not say.
	ExpiresAt *time.Time
}

type RotationMode struct {
	Key         string `json:"key"`
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
	// Scopes are the permissions the credential needs in this mode in
	// addition to the method's.
	Scopes []Scope `json:"scopes,omitempty"`
	// Risks say what those extra permissions also allow, so a person can
	// weigh the mode before choosing it.
	Risks []string `json:"risks,omitempty"`
	// ExpiryDays is the lifetime to give the credential when creating it,
	// for services that support one; 0 means no expiry.
	ExpiryDays int `json:"expiryDays,omitempty"`
	// Recommended marks the mode to offer first. At most one mode is.
	Recommended bool `json:"recommended,omitempty"`
}

type Scope struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`
}

type SetupStep struct {
	Title string `json:"title"`
	// Detail explains the step in plain text.
	Detail string `json:"detail,omitempty"`
	// URL opens the page at the service where the step is done.
	URL string `json:"url,omitempty"`
	// Rotation limits the step to these rotation mode keys; empty means
	// every mode.
	Rotation []string `json:"rotation,omitempty"`
}

type StatusError struct {
	Provider  string
	Status    int
	RequestID string
	Class     error
}

type TokenSource interface {
	// Token exchanges the credential for an access token. hc is restricted to
	// the manifest's hosts, so the manifest must list the token endpoint's
	// origin as well as the service's. A rejection wraps a connectforge
	// provider error; an error never contains the credential.
	Token(ctx context.Context, hc *http.Client, m Material) (AccessToken, error)
}