Hardening the 'url::Origin' implementation.

url/origin.h

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef URL_ORIGIN_H_
 #define URL_ORIGIN_H_
 
 #include <string>
 
+#include "base/basictypes.h"
 #include "url/url_export.h"
 
+class GURL;
+
 namespace url {
 
-// Origin represents a Web Origin serialized to a string.
-// See RFC6454 for details.
+// An Origin is a tuple of (scheme, host, port), as described in RFC 6454.
+//
+// Origins are the fundamental component of the web's security model, and
+// represent the boundries within which user agents generally compartmentalize
+// information, and between which user agents enforce access controls. That is,
+// "same-origin" resources are generally more able to directly share information
+// than "cross-origin" resources.
+//
+// This class represents a standard interface which ought to be used when code
+// needs to determine if two resources are "same-origin", and when a canonical
+// serialization of an origin is required.
+//
+// Some origins are "unique", meaning that they are not same-origin with any
+// other origin (including themselves). These are represented as ('', '', 0).
+//
+// There are a few subtleties to note:
+//
+// * Invalid and non-standard GURLs are parsed as unique origins. This includes
+//   non-hierarchical URLs like 'data:text/html,...' and 'javascript:alert(1)'.
+//
+// * GURLs with a scheme of 'file' are parsed as ('file', '', 0), and are
+//   same-origin with any other 'file'-based URL.
+//
+//   TODO(mkwst): When this changes in Blinke should change it here
+//   as well. See https://www.chromestatus.com/features/5755326842273792.
+//
+// * Unique origins all serialize to the string "null"; this means that the
+//   serialization of two unique origins will be '==' to each other, though the
+//   origins themselves are not "same-origin". This means that origins'
+//   serializations should not be relied upon for security checks.
+//
+// * GURLs with a scheme of 'filesystem' parse the origin out of the "internal
+//   URL". That is 'filesystem:https://example.com/temporary/file.png' is
+//   parsed as ('https', 'example.com', 443).
+//
+// * The host component of an IPv6 address includes brackets, just like the
+//   URL representation.
+//
+// Usage:
+//
+// * To answer the question "Are |this| and |that| "same-origin" with each
+//   other?", use |Origin::IsSameOriginWith|:
+//
+//       if (this.IsSameOriginWith(that)) {
+//         // Do something amazing here.
+//       }
+//
+// * To get the serialization of |origin|, use the |serialize| method:
+//
+//       std::string serialization = origin.serialize();
+//
+//   Note that unique origins all serialize to "null". This means that the
+//   serialization of two origins may '==' each other, even through the origins
+//   themselves are not "same-origin". This might be a useful property to use in
+//   some cases; origin-based caches might wish to fold unique origins into an
+//   "everything else" bucket, rather than creating new buckets for each unique
+//   origin. Be aware of the difference, and choose wisely.
 class URL_EXPORT Origin {
  public:
+  // Creates a unique Origin.
   Origin();
+
+  // Creates an origin from a scheme/host/port tuple. If the scheme, host, or
+  // port are invalid, a unique origin will be created.
+  //
+  // The constructor expects the host's A-label to be provided here. That is,
+  // 'http://☃.net/' should be provided as ('http', 'xn--n3h.net', 80).
+  Origin(const std::string& scheme, const std::string& host, uint16 port);
+
+  // The mechanism for extracting an origin from a URL is defined in the URL
+  // specification (https://url.spec.whatwg.org/#origin). In particular, note
+  // that:
+  //
+  // * invalid and non-standard URLs are parsed as unique origins
+  // * URLs whose scheme is 'file' are parsed as ('file', '', 0)
+  // * 'filesystem' URLs parse the origin out of the "internal URL"
+  //
+  // TODO(mkwst): 'blob' URLs are incorrectly handled. Perhaps this is an
+  // argument for moving this concept elsewhere, as //url doesn't know anything
+  // about 'blob' URLs at the moment (other than the bare fact that 'blob' is a
+  // scheme that exists).
+  explicit Origin(const GURL& url);
+
+  // This is a shortcut constructor that has the same effect as
+  // 'Origin(GURL([string]))'.
+  //
+  // TODO(mkwst): Remove this once 'blink::WebSerializedOrigin' is gone.
+  // https://crbug.com/490074
   explicit Origin(const std::string& origin);
 
-  const std::string& string() const { return string_; }
+  // Returns true if the origin is "the same" as |other|, as defined in Section
+  // 5 of RFC6454: https://tools.ietf.org/html/rfc6454#section-5. Note that
+  // unique origins are not "the same" as any other origin, including
+  // themselves.
+  bool IsSameOriginWith(const Origin& other) const;
 
-  bool IsSameAs(const Origin& that) const {
-    return string_ == that.string_;
-  }
+  std::string scheme() const { return scheme_; }
+  std::string host() const { return host_; }
+  uint16 port() const { return port_; }
+  bool is_valid() const { return valid_; }
+
+  // Returns a serialization of the origin as defined in Section 6 of RFC 6454
+  // (https://tools.ietf.org/html/rfc6454#section-6).
+  //
+  // This is _not_ the serialization of the origin which ought to be displayed
+  // to a user: the guidelines for such display are covered in detail at
+  // https://www.chromium.org/Home/chromium-security/enamel#TOC-Presenting-Origins-To-Users.
+  std::string serialize() const;
+
+  // TODO(mkwst): Remove this once blink::WebSerializedOrigin is gone.
+  // https://crbug.com/490074
+  std::string string() const { return serialize(); }
 
  private:
+  void Init(const GURL& url);
+
+  std::string scheme_;
+  std::string host_;
+  uint16 port_;
+  bool unique_;
+  bool serialization_requires_port_;
+  bool valid_;
+
   std::string string_;
 };
 
+// Stream operator so Origin can be used in assertion statements.
+URL_EXPORT std::ostream& operator<<(std::ostream& out, const url::Origin& url);
+
 }  // namespace url
 
 #endif  // URL_ORIGIN_H_