prose review

Author: minrk

docs/source/changelog.rst

@@ -25,18 +25,19 @@ For more detailed information, see `GitHub <https://github.com/jupyter/notebook>
   where malicious forms could create untitled files and start kernels
   (no remote execution or modification of existing files)
   for users of certain browsers (Firefox, Internet Explorer / Edge).
+  All previous notebook releases are affected.
 
 Bug fixes:
 
 - Fix carriage return handling
-- Make the font size more robust against fickle brow
+- Make the font size more robust against fickle browsers
 - Ignore resize events that bubbled up and didn't come from window
+- Add Authorization to allowed CORS headers
 
 Other improvements:
 
 - Better docs for token-based authentication
 - Further highlight token info in log output when autogenerated
-- Add Authorization to allowed CORS headers
 
 See the 4.3.1 milestone on GitHub for a complete list of
 `issues <https://github.com/jupyter/notebook/issues?utf8=%E2%9C%93&q=is%3Aissue%20milestone%3A4.3.1>`__

notebook/auth/login.py

@@ -117,17 +117,21 @@ def get_token(cls, handler):
     @classmethod
     def should_check_origin(cls, handler):
         """Should the Handler check for CORS origin validation?
-        
+
         Origin check should be skipped for token-authenticated requests.
+
+        Returns:
+        - True, if Handler must check for valid CORS origin.
+        - False, if Handler should skip origin check since requests are token-authenticated.
         """
         return not cls.is_token_authenticated(handler)
-    
+
     @classmethod
     def is_token_authenticated(cls, handler):
-        """Check if the handler has been authenticated by a token.
-        
-        This is used to signal certain things, such as:
-        
+        """Returns True if handler has been token authenticated. Otherwise, False.
+
+        Login with a token is used to signal certain things, such as:
+
         - permit access to REST API
         - xsrf protection
         - skip origin-checks for scripts
@@ -152,8 +156,8 @@ def get_user(cls, handler):
             user_id = handler.get_secure_cookie(handler.cookie_name)
         else:
             cls.set_login_cookie(handler, user_id)
-            # Record that we've been authenticated with a token.
-            # Used in should_check_origin above.
+            # Record that the current request has been authenticated with a token.
+            # Used in is_token_authenticated above.
             handler._token_authenticated = True
         if user_id is None:
             # prevent extra Invalid cookie sig warnings:
@@ -169,7 +173,12 @@ def get_user(cls, handler):
 
     @classmethod
     def get_user_token(cls, handler):
-        """Identify the user based on a token in the URL or Authorization header"""
+        """Identify the user based on a token in the URL or Authorization header
+        
+        Returns:
+        - uuid if authenticated
+        - None if not
+        """
         token = handler.token
         if not token:
             return

notebook/base/handlers.py

@@ -292,7 +292,7 @@ def check_origin(self, origin_to_satisfy_tornado=""):
         host = self.request.headers.get("Host")
         origin = self.request.headers.get("Origin")
 
-        # If no header is provided, allow it.
+        # If no header is provided, let the request through.
         # Origin can be None for:
         # - same-origin (IE, Firefox)
         # - Cross-site POST form (IE, Firefox)
@@ -323,7 +323,7 @@ def check_origin(self, origin_to_satisfy_tornado=""):
         return allow
 
     def check_xsrf_cookie(self):
-        """Bypass xsrf checks when token-authenticated"""
+        """Bypass xsrf cookie checks when token-authenticated"""
         if self.token_authenticated or self.settings.get('disable_check_xsrf', False):
             # Token-authenticated requests do not need additional XSRF-check
             # Servers without authentication are vulnerable to XSRF

notebook/notebookapp.py

@@ -567,7 +567,7 @@ def _token_changed(self, name, old, new):
         Jupyter notebook 4.3.1 introduces protection from cross-site request forgeries,
         requiring API requests to either:
 
-        - originate from the (validated with XSRF cookie and token), or
+        - originate from pages served by this server (validated with XSRF cookie and token), or
         - authenticate with a token
 
         Some anonymous compute resources still desire the ability to run code,