Add a package for authenticating via OAuth2.

pkg/oauth2/lib/src/credentials.dart

+// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library credentials;
+
+import 'dart:json';
+import 'dart:uri';
+
+import '../../../http/lib/http.dart' as http;
+import 'handle_access_token_response.dart';
+import 'utils.dart';
+
+/// Credentials that prove that a client is allowed to access a resource on the
+/// resource owner's behalf. These credentials are long-lasting and can be
+/// safely persisted across multiple runs of the program.
+///
+/// Many authorization servers will attach an expiration date to a set of
+/// credentials, along with a token that can be used to refresh the credentials
+/// once they've expired. The [Client] will automatically refresh its
+/// credentials when necessary. It's also possible to explicitly refresh them
+/// via [Client.refreshCredentials] or [Credentials.refresh].
+///
+/// Note that a given set of credentials can only be refreshed once, so be sure
+/// to save the refreshed credentials for future use.

[Bob Nystrom, 2012/11/16 19:53:30]

Given this, maybe client should raise some sort of event/notification/stream
when it has refreshed the credentials so you can save them?

I know the normal case is that you just save once right before exiting, but I
worry about the case where your app dies after refreshing but before you've had
a chance to save them.

[nweiz, 2012/11/17 01:06:27]

That's a good idea. I've added a TODO to do so once we have event
infrastructure.

+class Credentials {
+  /// The token that is sent to the resource server to prove the authorization
+  /// of a client.
+  final String accessToken;
+
+  /// The token that is sent to the authorization server to refresh the
+  /// credentials. This is optional.
+  final String refreshToken;
+
+  /// The URL of the authorization server endpoint that's used to refresh the
+  /// credentials. This is optional.
+  final Uri tokenEndpoint;
+
+  /// The specific permissions being requested from the authorization server may
+  /// be specified via `scopes`. The scope strings are specific to the

[Bob Nystrom, 2012/11/16 19:53:30]

Just me, but I'd probably italicize scopes and not code font.

[nweiz, 2012/11/17 01:06:27]

This shouldn't mention the field name at all. It was a holdover from copied
parameter documentation.

+  /// authorization server and may be found in its documentation.
+  final List<String> scopes;
+
+  /// The date at which these credentials will expire. This is likely to be a
+  /// few seconds earlier than the server's idea of the expiration date.
+  final Date expiration;
+
+  /// Whether or not these credentials have expired. Note that it's possible the
+  /// credentials will expire shortly after this is called. However, since the
+  /// client's expiration date is kept a few seconds earlier than the server's,
+  /// there should be enough leeway to rely on this.
+  bool get isExpired => expiration != null && new Date.now() > expiration;
+
+  /// Whether it's possible to refresh these credentials.
+  bool get canRefresh => refreshToken != null && tokenEndpoint != null;
+
+  /// Creates a new set of credentials.
+  ///
+  /// This class is usually not constructed directly; rather, it's accessed via
+  /// [Client.credentials] after a [Client] is created by
+  /// [AuthorizationCodeGrant]. Alternately, it may be loaded from a serialized
+  /// form via [Credentials.fromJson].
+  Credentials(
+      this.accessToken,
+      [this.refreshToken,
+       this.tokenEndpoint,
+       this.scopes,
+       this.expiration]);
+
+  /// Loads a set of credentials from a JSON-serialized form.
+  factory Credentials.fromJson(String json) {
+    var parsed = JSON.parse(json);
+    var tokenEndpoint = parsed['tokenEndpoint'];
+    if (tokenEndpoint != null) tokenEndpoint = new Uri.fromString(tokenEndpoint);

[Bob Nystrom, 2012/11/16 19:53:30]

Long line.

[nweiz, 2012/11/17 01:06:27]

My kingdom for ||=.

+    var expiration = parsed['expiration'];
+    if (expiration != null) {
+      expiration = new Date.fromMillisecondsSinceEpoch(expiration);
+    }
+
+    return new Credentials(
+        parsed['accessToken'],

[Bob Nystrom, 2012/11/16 19:53:30]

Throw a FormatException if this is missing?

[nweiz, 2012/11/17 01:06:27]

Done. I've added a bunch more format checking here.

+        parsed['refreshToken'],
+        tokenEndpoint,
+        parsed['scopes'],
+        expiration);
+  }
+
+  /// Serializes a set of credentials to JSON. Nothing is guaranteed about the
+  /// output except that it's valid JSON and compatible with
+  /// [Credentials.toJson].
+  String toJson() => JSON.stringify({
+    'accessToken': accessToken,
+    'refreshToken': refreshToken,
+    'tokenEndpoint': tokenEndpoint == null ? null : tokenEndpoint.toString(),
+    'scopes': scopes,
+    'expiration': expiration == null ? null : expiration.millisecondsSinceEpoch
+  });
+
+  /// Returns a new set of refreshed credentials. See [Client.identifier] and
+  /// [Client.secret] for explanations of those parameters.
+  ///
+  /// You may request different scopes than the default by passing in
+  /// `newScopes`. These must be a subset of [scopes].
+  ///
+  /// This will throw a [StateError] if these credentials can't be refreshed, an
+  /// [AuthorizationException] if refreshing the credentials fails, or a
+  /// [FormatError] if the authorization server returns invalid responses.
+  Future<Credentials> refresh(
+      String identifier,
+      String secret,
+      {List<String> newScopes,
+       http.BaseClient httpClient}) {
+    var scopes = this.scopes;
+    if (newScopes != null) scopes = newScopes;
+    if (scopes == null) scopes = <String>[];
+    if (httpClient == null) httpClient = new http.Client();
+
+    var startTime = new Date.now();
+    return async.chain((_) {
+      if (refreshToken == null) {
+        throw new StateError("Can't refresh credentials without a refresh "
+            "token.");
+      } else if (tokenEndpoint == null) {
+        throw new StateError("Can't refresh credentials without a token "
+            "endpoint.");
+      }
+
+      return httpClient.post(tokenEndpoint, fields: {
+        "grant_type": "refresh_token",
+        "refresh_token": refreshToken,
+        "scope": Strings.join(scopes, ' '),
+          // TODO(nweiz): the spec recommends that HTTP basic auth be used in
+          // preference to form parameters, but Google doesn't support that. Should

[Bob Nystrom, 2012/11/16 19:53:30]

Long line.

[nweiz, 2012/11/17 01:06:27]

Done.

+          // it be configurable?
+        "client_id": identifier,
+        "client_secret": secret
+      });
+    }).transform((response) {
+      return handleAccessTokenResponse(
+          response, tokenEndpoint, startTime, scopes);
+    });
+  }
+}