1// Copyright (c) 2012 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// A GoogleServiceAuthError is immutable, plain old data representing an
6// error from an attempt to authenticate with a Google service.
7// It could be from Google Accounts itself, or any service using Google
8// Accounts (e.g expired credentials).  It may contain additional data such as
9// captcha or OTP challenges.
10
11// A GoogleServiceAuthError without additional data is just a State, defined
12// below. A case could be made to have this relation implicit, to allow raising
13// error events concisely by doing OnAuthError(GoogleServiceAuthError::NONE),
14// for example. But the truth is this class is ever so slightly more than a
15// transparent wrapper around 'State' due to additional Captcha data
16// (e.g consider operator=), and this would violate the style guide. Thus,
17// you must explicitly use the constructor when all you have is a State.
18// The good news is the implementation nests the enum inside a class, so you
19// may forward declare and typedef GoogleServiceAuthError to something shorter
20// in the comfort of your own translation unit.
21
22#ifndef GOOGLE_APIS_GAIA_GOOGLE_SERVICE_AUTH_ERROR_H_
23#define GOOGLE_APIS_GAIA_GOOGLE_SERVICE_AUTH_ERROR_H_
24
25#include <string>
26
27#include "url/gurl.h"
28
29namespace base {
30class DictionaryValue;
31}
32
33class GoogleServiceAuthError {
34 public:
35  //
36  // These enumerations are referenced by integer value in HTML login code and
37  // in UMA histograms. Do not change the numeric values.
38  //
39  enum State {
40    // The user is authenticated.
41    NONE = 0,
42
43    // The credentials supplied to GAIA were either invalid, or the locally
44    // cached credentials have expired.
45    INVALID_GAIA_CREDENTIALS = 1,
46
47    // The GAIA user is not authorized to use the service.
48    USER_NOT_SIGNED_UP = 2,
49
50    // Could not connect to server to verify credentials. This could be in
51    // response to either failure to connect to GAIA or failure to connect to
52    // the service needing GAIA tokens during authentication.
53    CONNECTION_FAILED = 3,
54
55    // The user needs to satisfy a CAPTCHA challenge to unlock their account.
56    // If no other information is available, this can be resolved by visiting
57    // https://accounts.google.com/DisplayUnlockCaptcha. Otherwise, captcha()
58    // will provide details about the associated challenge.
59    CAPTCHA_REQUIRED = 4,
60
61    // The user account has been deleted.
62    ACCOUNT_DELETED = 5,
63
64    // The user account has been disabled.
65    ACCOUNT_DISABLED = 6,
66
67    // The service is not available; try again later.
68    SERVICE_UNAVAILABLE = 7,
69
70    // The password is valid but we need two factor to get a token.
71    TWO_FACTOR = 8,
72
73    // The requestor of the authentication step cancelled the request
74    // prior to completion.
75    REQUEST_CANCELED = 9,
76
77    // The user has provided a HOSTED account, when this service requires
78    // a GOOGLE account.
79    HOSTED_NOT_ALLOWED = 10,
80
81    // Indicates the service responded to a request, but we cannot
82    // interpret the response.
83    UNEXPECTED_SERVICE_RESPONSE = 11,
84
85    // Indicates the service responded and response carried details of the
86    // application error.
87    SERVICE_ERROR = 12,
88
89    // The number of known error states.
90    NUM_STATES = 13,
91  };
92
93  // Additional data for CAPTCHA_REQUIRED errors.
94  struct Captcha {
95    Captcha();
96    Captcha(const std::string& token,
97            const GURL& audio,
98            const GURL& img,
99            const GURL& unlock,
100            int width,
101            int height);
102    ~Captcha();
103    // For test only.
104    bool operator==(const Captcha &b) const;
105
106    std::string token;  // Globally identifies the specific CAPTCHA challenge.
107    GURL audio_url;     // The CAPTCHA audio to use instead of image.
108    GURL image_url;     // The CAPTCHA image to show the user.
109    GURL unlock_url;    // Pretty unlock page containing above captcha.
110    int image_width;    // Width of captcha image.
111    int image_height;   // Height of capture image.
112  };
113
114  // Additional data for TWO_FACTOR errors.
115  struct SecondFactor {
116    SecondFactor();
117    SecondFactor(const std::string& token,
118                 const std::string& prompt,
119                 const std::string& alternate,
120                 int length);
121    ~SecondFactor();
122    // For test only.
123    bool operator==(const SecondFactor &b) const;
124
125    // Globally identifies the specific second-factor challenge.
126    std::string token;
127    // Localised prompt text, eg Enter the verification code sent to your
128    // phone number ending in XXX.
129    std::string prompt_text;
130    // Localized text describing an alternate option, eg Get a verification
131    // code in a text message.
132    std::string alternate_text;
133    // Character length for the challenge field.
134    int field_length;
135  };
136
137  // For test only.
138  bool operator==(const GoogleServiceAuthError &b) const;
139
140  // Construct a GoogleServiceAuthError from a State with no additional data.
141  explicit GoogleServiceAuthError(State s);
142
143  // Construct a GoogleServiceAuthError from a network error.
144  // It will be created with CONNECTION_FAILED set.
145  static GoogleServiceAuthError FromConnectionError(int error);
146
147  // Construct a CAPTCHA_REQUIRED error with CAPTCHA challenge data from the
148  // the ClientLogin endpoint.
149  // TODO(rogerta): once ClientLogin is no longer used, may be able to get
150  // rid of this function.
151  static GoogleServiceAuthError FromClientLoginCaptchaChallenge(
152      const std::string& captcha_token,
153      const GURL& captcha_image_url,
154      const GURL& captcha_unlock_url);
155
156  // Construct a SERVICE_ERROR error, e.g. invalid client ID, with an
157  // |error_message| which provides more information about the service error.
158  static GoogleServiceAuthError FromServiceError(
159      const std::string& error_message);
160
161  // Construct an UNEXPECTED_SERVICE_RESPONSE error, with an |error_message|
162  // detailing the problems with the response.
163  static GoogleServiceAuthError FromUnexpectedServiceResponse(
164      const std::string& error_message);
165
166  // Provided for convenience for clients needing to reset an instance to NONE.
167  // (avoids err_ = GoogleServiceAuthError(GoogleServiceAuthError::NONE), due
168  // to explicit class and State enum relation. Note: shouldn't be inlined!
169  static GoogleServiceAuthError AuthErrorNone();
170
171  // The error information.
172  State state() const;
173  const Captcha& captcha() const;
174  const SecondFactor& second_factor() const;
175  int network_error() const;
176  const std::string& token() const;
177  const std::string& error_message() const;
178
179  // Returns info about this object in a dictionary.  Caller takes
180  // ownership of returned dictionary.
181  base::DictionaryValue* ToValue() const;
182
183  // Returns a message describing the error.
184  std::string ToString() const;
185
186 private:
187  GoogleServiceAuthError(State s, int error);
188
189  // Construct a GoogleServiceAuthError from |state| and |error_message|.
190  GoogleServiceAuthError(State state, const std::string& error_message);
191
192  GoogleServiceAuthError(State s, const std::string& captcha_token,
193                         const GURL& captcha_audio_url,
194                         const GURL& captcha_image_url,
195                         const GURL& captcha_unlock_url,
196                         int image_width,
197                         int image_height);
198
199  State state_;
200  Captcha captcha_;
201  SecondFactor second_factor_;
202  int network_error_;
203  std::string error_message_;
204};
205
206#endif  // GOOGLE_APIS_GAIA_GOOGLE_SERVICE_AUTH_ERROR_H_
207