From 9d274c01d11f1fa9556e9afad7eddc54569e2a46 Mon Sep 17 00:00:00 2001
From: tfrommen <info@tfrommen.de>
Date: Wed, 28 Jun 2017 19:45:02 +0200
Subject: [PATCH] House cleaning.

---
 README.md                               |  2 +-
 bin/readme.txt                          | 10 +++---
 bin/release.sh                          |  4 +--
 book.json                               |  4 +--
 composer.json                           | 21 ++++++------
 inc/admin/class-admin.php               | 16 ++++++---
 inc/admin/class-listtable.php           | 11 +++++++
 inc/authentication/namespace.php        | 34 +++++++++++++++++--
 inc/class-client.php                    | 11 +++----
 inc/endpoints/class-authorization.php   | 16 ++++-----
 inc/endpoints/class-token.php           | 14 ++++++++
 inc/tokens/class-access-token.php       | 24 ++++++++++++--
 inc/tokens/class-authorization-code.php | 31 +++++++++++++++--
 inc/tokens/class-token.php              | 44 ++++++++++++++++++-------
 inc/tokens/namespace.php                |  6 ++++
 inc/types/class-authorization-code.php  | 11 ++++++-
 inc/types/class-base.php                |  3 +-
 inc/types/class-implicit.php            |  9 +++++
 plugin.php                              |  2 +-
 theme/oauth2-authorize.php              |  3 ++
 20 files changed, 214 insertions(+), 62 deletions(-)

diff --git a/README.md b/README.md
index ef83ebf..92000b9 100755
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ This is in extremely early beta, and does not work yet. Please help us out and c
 
 This plugin is licensed under the GNU General Public License v2 or later:
 
-> Copyright 2016 by the contributors.
+> Copyright 2017 by the contributors.
 >
 > This program is free software; you can redistribute it and/or modify
 > it under the terms of the GNU General Public License as published by
diff --git a/bin/readme.txt b/bin/readme.txt
index 0f532a9..17b0d27 100644
--- a/bin/readme.txt
+++ b/bin/readme.txt
@@ -1,8 +1,8 @@
-=== WordPress REST API - OAuth 1.0a Server ===
+=== WordPress REST API - OAuth 2 Server ===
 Contributors: rmccue, rachelbaker, danielbachhuber, joehoyle
 Tags: json, rest, api, rest-api
-Requires at least: 4.4
-Tested up to: 4.7-alpha
+Requires at least: 4.8
+Tested up to: 4.8
 Stable tag: {{TAG}}
 License: GPLv2 or later
 License URI: http://www.gnu.org/licenses/gpl-2.0.html
@@ -10,6 +10,6 @@ License URI: http://www.gnu.org/licenses/gpl-2.0.html
 == Description ==
 Connect applications to your WordPress site without ever giving away your password.
 
-This plugin uses the OAuth 1.0a protocol to allow delegated authorization; that is, to allow applications to access a site using a set of secondary credentials. This allows server administrators to control which applications can access the site, as well as allowing users to control which applications have access to their data.
+This plugin uses the OAuth 2 protocol to allow delegated authorization; that is, to allow applications to access a site using a set of secondary credentials. This allows server administrators to control which applications can access the site, as well as allowing users to control which applications have access to their data.
 
-This plugin only supports WordPress >= 4.4.
+This plugin only supports WordPress >= 4.8.
diff --git a/bin/release.sh b/bin/release.sh
index d055cee..a00e806 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -4,8 +4,8 @@
 
 TAG=$1
 
-PLUGIN="rest-api-oauth1"
-TMPDIR=/tmp/rest-api-oauth1-release-svn
+PLUGIN="rest-api-oauth2"
+TMPDIR=/tmp/rest-api-oauth2-release-svn
 PLUGINDIR="$PWD"
 PLUGINSVN="https://plugins.svn.wordpress.org/$PLUGIN"
 
diff --git a/book.json b/book.json
index aae65b9..53aa259 100644
--- a/book.json
+++ b/book.json
@@ -6,11 +6,11 @@
   "plugins": ["edit-link", "github"],
   "pluginsConfig": {
     "edit-link": {
-      "base": "https://github.com/WP-API/OAuth1/tree/master",
+      "base": "https://github.com/WP-API/OAuth2/tree/master",
       "label": "Edit This Page"
     },
     "github": {
-      "url": "https://github.com/WP-API/OAuth1/"
+      "url": "https://github.com/WP-API/OAuth2/"
     }
   }
 }
diff --git a/composer.json b/composer.json
index 39cce50..4267408 100644
--- a/composer.json
+++ b/composer.json
@@ -1,13 +1,12 @@
 {
-    "name": "wp-api/oauth1",
-    "description": "OAuth 1.0a Server for WordPress",
-    "type": "wordpress-plugin",
-    "license": "GPL2+",
-    "authors": [
-        {
-            "name": "WP-API Team",
-            "homepage": "http://wp-api.org/"
-        }
-    ],
-    "require": {}
+  "name": "wp-api/oauth2",
+  "description": "OAuth 2 Server for WordPress",
+  "type": "wordpress-plugin",
+  "license": "GPL2+",
+  "authors": [
+    {
+      "name": "WP-API Team",
+      "homepage": "http://wp-api.org/"
+    }
+  ]
 }
diff --git a/inc/admin/class-admin.php b/inc/admin/class-admin.php
index 0d7571a..051d98d 100644
--- a/inc/admin/class-admin.php
+++ b/inc/admin/class-admin.php
@@ -3,7 +3,6 @@
 namespace WP\OAuth2\Admin;
 
 use WP\OAuth2\Client;
-use WP\OAuth2\Types;
 use WP_Error;
 
 class Admin {
@@ -136,6 +135,12 @@ class="add-new-h2"><?php echo esc_html_x( 'Add New', 'application', 'rest_oauth2
 		<?php
 	}
 
+	/**
+	 * Validates given parameters.
+	 *
+	 * @param array $params RAW parameters.
+	 * @return array|WP_Error Validated parameters, or error on failure.
+	 */
 	protected static function validate_parameters( $params ) {
 		$valid = [];
 
@@ -167,11 +172,11 @@ protected static function validate_parameters( $params ) {
 	/**
 	 * Handle submission of the add page
 	 *
-	 * @param $consumer
+	 * @param Client $consumer
 	 *
 	 * @return array|null List of errors. Issues a redirect and exits on success.
 	 */
-	protected static function handle_edit_submit( $consumer ) {
+	protected static function handle_edit_submit( Client $consumer = null ) {
 		$messages = [];
 		if ( empty( $consumer ) ) {
 			$did_action = 'add';
@@ -243,8 +248,9 @@ public static function render_edit_page() {
 		}
 
 		// Are we editing?
-		$consumer    = null;
-		$form_action = self::get_url( 'action=add' );
+		$consumer          = null;
+		$form_action       = self::get_url( 'action=add' );
+		$regenerate_action = '';
 		if ( ! empty( $_REQUEST['id'] ) ) {
 			$id       = absint( $_REQUEST['id'] );
 			$consumer = Client::get_by_post_id( $id );
diff --git a/inc/admin/class-listtable.php b/inc/admin/class-listtable.php
index fe90ca2..d43d230 100644
--- a/inc/admin/class-listtable.php
+++ b/inc/admin/class-listtable.php
@@ -56,6 +56,9 @@ public function get_columns() {
 		return $c;
 	}
 
+	/**
+	 * @param \WP_Post $item Post object.
+	 */
 	public function column_cb( $item ) {
 		?>
 		<label class="screen-reader-text"
@@ -67,6 +70,10 @@ public function column_cb( $item ) {
 		<?php
 	}
 
+	/**
+	 * @param \WP_Post $item Post object.
+	 * @return string Name of the column.
+	 */
 	protected function column_name( $item ) {
 		$title = get_the_title( $item->ID );
 		if ( empty( $title ) ) {
@@ -100,6 +107,10 @@ protected function column_name( $item ) {
 		return $title . ' ' . $action_html;
 	}
 
+	/**
+	 * @param \WP_Post $item Post object.
+	 * @return string Content of the column.
+	 */
 	protected function column_description( $item ) {
 		return $item->post_content;
 	}
diff --git a/inc/authentication/namespace.php b/inc/authentication/namespace.php
index 0b7d7cc..2807888 100644
--- a/inc/authentication/namespace.php
+++ b/inc/authentication/namespace.php
@@ -2,6 +2,8 @@
 
 namespace WP\OAuth2\Authentication;
 
+use WP_Error;
+use WP_User;
 use WP\OAuth2\Tokens;
 
 /**
@@ -33,6 +35,11 @@ function get_authorization_header() {
 	return null;
 }
 
+/**
+ * Extracts the token from the authorization header or the current request.
+ *
+ * @return string|null Token on success, null on failure.
+ */
 function get_provided_token() {
 	$header = get_authorization_header();
 	if ( $header ) {
@@ -47,6 +54,13 @@ function get_provided_token() {
 	return null;
 }
 
+/**
+ * Extracts the token from the given authorization header.
+ *
+ * @param string $header Authorization header.
+ *
+ * @return string|null Token on succes, null on failure.
+ */
 function get_token_from_bearer_header( $header ) {
 	if ( is_string( $header ) && preg_match( '/Bearer ([a-zA-Z0-9\-._~\+\/=]+)/', trim( $header ), $matches ) ) {
 		return $matches[1];
@@ -55,6 +69,11 @@ function get_token_from_bearer_header( $header ) {
 	return null;
 }
 
+/**
+ * Extracts the token from the current request.
+ *
+ * @return string|null Token on succes, null on failure.
+ */
 function get_token_from_request() {
 	if ( empty( $_GET['access_token'] ) ) {
 		return null;
@@ -74,9 +93,9 @@ function get_token_from_request() {
 /**
  * Try to authenticate if possible.
  *
- * @param \WP_User|null $user Existing authenticated user.
+ * @param WP_User|null $user Existing authenticated user.
  *
- * @return \WP_User|int|\WP_Error
+ * @return WP_User|int|WP_Error
  */
 function attempt_authentication( $user = null ) {
 	// Lock against infinite loops when querying the token itself.
@@ -115,6 +134,8 @@ function attempt_authentication( $user = null ) {
  * Attached to the rest_authentication_errors filter. Passes through existing
  * errors registered on the filter.
  *
+ * @param WP_Error|null Current error, or null.
+ *
  * @return WP_Error|null Error if one is set, otherwise null.
  */
 function maybe_report_errors( $error = null ) {
@@ -126,8 +147,15 @@ function maybe_report_errors( $error = null ) {
 	return $oauth2_error;
 }
 
+/**
+ * Creates an error object for the given invalid token.
+ *
+ * @param mixed $token Invalid token.
+ *
+ * @return WP_Error
+ */
 function create_invalid_token_error( $token ) {
-	return new \WP_Error(
+	return new WP_Error(
 		'oauth2.authentication.attempt_authentication.invalid_token',
 		__( 'Supplied token is invalid.', 'oauth2' ),
 		array(
diff --git a/inc/class-client.php b/inc/class-client.php
index 37c8422..28022d7 100644
--- a/inc/class-client.php
+++ b/inc/class-client.php
@@ -5,7 +5,6 @@
 use WP\OAuth2\Tokens\Access_Token;
 use WP\OAuth2\Tokens\Authorization_Code;
 use WP_Error;
-use WP_Http;
 use WP_Post;
 use WP_Query;
 use WP_User;
@@ -224,17 +223,17 @@ public function check_redirect_uri( $uri ) {
 			$valid = apply_filters( 'rest_oauth.check_callback', $valid, $uri, $registered_uri, $this );
 			if ( $valid ) {
 				// Stop checking, we have a match.
-				break;
+				return true;
 			}
 		}
 
-		return $valid;
+		return false;
 	}
 
 	/**
 	 * @param WP_User $user
 	 *
-	 * @return string|WP_Error
+	 * @return Authorization_Code|WP_Error
 	 */
 	public function generate_authorization_code( WP_User $user ) {
 		return Authorization_Code::create( $this, $user );
@@ -244,7 +243,7 @@ public function generate_authorization_code( WP_User $user ) {
 	 * Get data stored for an authorization code.
 	 *
 	 * @param string $code Authorization code to fetch.
-	 * @return array|WP_Error Data if available, error if invalid code.
+	 * @return Authorization_Code|WP_Error Data if available, error if invalid code.
 	 */
 	public function get_authorization_code( $code ) {
 		return Authorization_Code::get_by_code( $this, $code );
@@ -266,7 +265,7 @@ public function regenerate_secret() {
 	 * Issue token for a user.
 	 *
 	 * @param \WP_User $user
-	 * 
+	 *
 	 * @return Access_Token
 	 */
 	public function issue_token( WP_User $user ) {
diff --git a/inc/endpoints/class-authorization.php b/inc/endpoints/class-authorization.php
index b6bc63b..6f8931d 100644
--- a/inc/endpoints/class-authorization.php
+++ b/inc/endpoints/class-authorization.php
@@ -4,8 +4,6 @@
 
 use WP_Error;
 use WP\OAuth2;
-use WP\OAuth2\Client;
-use WP\OAuth2\Types;
 
 class Authorization {
 	const LOGIN_ACTION = 'oauth2_authorize';
@@ -27,19 +25,21 @@ public function handle_request() {
 
 		// Match type to a handler.
 		$grant_types = OAuth2\get_grant_types();
-		foreach ( $grant_types as $type_handler ) {
-			if ( $type_handler->get_response_type_code() === $type ) {
-				$handler = $type_handler;
+		if ( $grant_types ) {
+			foreach ( array_reverse( $grant_types ) as $type_handler ) {
+				if ( $type_handler->get_response_type_code() === $type ) {
+					$handler = $type_handler;
+					break;
+				}
 			}
 		}
+
 		if ( empty( $handler ) ) {
 			$result = new WP_Error(
 				'oauth2.endpoints.authorization.handle_request.invalid_type',
 				__( 'Invalid response type specified.', 'oauth2' )
 			);
-		}
-
-		if ( empty( $result ) ) {
+		} else {
 			$result = $handler->handle_authorisation();
 		}
 
diff --git a/inc/endpoints/class-token.php b/inc/endpoints/class-token.php
index 2177016..e97914b 100644
--- a/inc/endpoints/class-token.php
+++ b/inc/endpoints/class-token.php
@@ -35,10 +35,24 @@ public function register_routes() {
 		));
 	}
 
+	/**
+	 * Validates the given grant type.
+	 *
+	 * @param string $type Grant type.
+	 *
+	 * @return bool Whether or not the grant type is valid.
+	 */
 	public function validate_grant_type( $type ) {
 		return $type === 'authorization_code';
 	}
 
+	/**
+	 * Validates the token given in the request, and issues a new token for the user.
+	 *
+	 * @param WP_REST_Request $request Request object.
+	 *
+	 * @return array|WP_Error Token data on success, or error on failure.
+	 */
 	public function exchange_token( WP_REST_Request $request ) {
 		$client = Client::get_by_id( $request['client_id'] );
 		if ( empty( $client ) ) {
diff --git a/inc/tokens/class-access-token.php b/inc/tokens/class-access-token.php
index 03090ac..a2b4929 100644
--- a/inc/tokens/class-access-token.php
+++ b/inc/tokens/class-access-token.php
@@ -11,7 +11,10 @@ class Access_Token extends Token {
 	const META_PREFIX = '_oauth2_access_';
 	const KEY_LENGTH = 12;
 
-	protected static function get_meta_prefix() {
+	/**
+	 * @return string Meta prefix.
+	 */
+	protected function get_meta_prefix() {
 		return static::META_PREFIX;
 	}
 
@@ -66,6 +69,14 @@ public static function get_by_id( $id ) {
 		return new static( $key, $value[0] );
 	}
 
+	/**
+	 * Creates a new token for the given client and user.
+	 *
+	 * @param Client  $client
+	 * @param WP_User $user
+	 *
+	 * @return Access_Token|WP_Error Token instance, or error on failure.
+	 */
 	public static function create( Client $client, WP_User $user ) {
 		if ( ! $user->exists() ) {
 			return new WP_Error(
@@ -90,4 +101,13 @@ public static function create( Client $client, WP_User $user ) {
 
 		return new static( $key, $data );
 	}
-}
\ No newline at end of file
+
+	/**
+	 * Check if the token is valid.
+	 *
+	 * @return bool True if the token is valid, false otherwise.
+	 */
+	public function is_valid() {
+		return true;
+	}
+}
diff --git a/inc/tokens/class-authorization-code.php b/inc/tokens/class-authorization-code.php
index cb566eb..7aa3b9a 100644
--- a/inc/tokens/class-authorization-code.php
+++ b/inc/tokens/class-authorization-code.php
@@ -31,6 +31,10 @@ class Authorization_Code {
 	 */
 	protected $client;
 
+	/**
+	 * @param Client $client
+	 * @param string $code
+	 */
 	public function __construct( Client $client, $code ) {
 		$this->client = $client;
 		$this->code = $code;
@@ -87,16 +91,21 @@ public function get_user() {
 		return get_user_by( 'id', (int) $value['user'] );
 	}
 
+	/**
+	 * Get the expiration.
+	 *
+	 * @return int|WP_Error Expiration, or error on failure.
+	 */
 	public function get_expiration() {
 		$value = $this->get_value();
-		if ( empty( $value ) || empty( $value['expiration'] ) ) {
+		if ( empty( $value ) || empty( $value['expiration'] ) || ! is_numeric( $value['expiration'] ) ) {
 			return new WP_Error(
 				'oauth2.tokens.authorization_code.get_user.invalid_data',
 				__( 'Authorization code data is not valid.', 'oauth2' )
 			);
 		}
 
-		return $value['expiration'];
+		return (int) $value['expiration'];
 	}
 
 	/**
@@ -140,6 +149,14 @@ public function delete() {
 		return true;
 	}
 
+	/**
+	 * Creates a new authorization code instance for the given client and code.
+	 *
+	 * @param Client $client
+	 * @param string $code
+	 *
+	 * @return Authorization_Code|WP_Error Authorization code instance, or error on failure.
+	 */
 	public static function get_by_code( Client $client, $code ) {
 		$key = static::KEY_PREFIX . $code;
 		$value = get_post_meta( $client->get_post_id(), wp_slash( $key ), false );
@@ -158,6 +175,14 @@ public static function get_by_code( Client $client, $code ) {
 		return new static( $client, $code );
 	}
 
+	/**
+	 * Creates a new authorization code instance for the given client and user.
+	 *
+	 * @param Client $client
+	 * @param WP_User $user
+	 *
+	 * @return Authorization_Code|WP_Error Authorization code instance, or error on failure.
+	 */
 	public static function create( Client $client, WP_User $user ) {
 		$code = wp_generate_password( static::KEY_LENGTH, false );
 		$meta_key = static::KEY_PREFIX . $code;
@@ -175,4 +200,4 @@ public static function create( Client $client, WP_User $user ) {
 
 		return new static( $client, $code );
 	}
-}
\ No newline at end of file
+}
diff --git a/inc/tokens/class-token.php b/inc/tokens/class-token.php
index a3442a9..570afbe 100644
--- a/inc/tokens/class-token.php
+++ b/inc/tokens/class-token.php
@@ -3,14 +3,45 @@
 namespace WP\OAuth2\Tokens;
 
 abstract class Token {
+
+	/**
+	 * @var string
+	 */
 	protected $key;
+
+	/**
+	 * @var mixed
+	 */
 	protected $value;
 
+	/**
+	 * @param string $key
+	 * @param mixed $value
+	 */
 	protected function __construct( $key, $value ) {
 		$this->key = $key;
 		$this->value = $value;
 	}
 
+	/**
+	 * Get the meta prefix.
+	 *
+	 * @return string Meta prefix.
+	 */
+	abstract protected function get_meta_prefix();
+
+	/**
+	 * Check if the token is valid.
+	 *
+	 * @return bool True if the token is valid, false otherwise.
+	 */
+	abstract public function is_valid();
+
+	/**
+	 * Get the token's key.
+	 *
+	 * @return string Token
+	 */
 	public function get_key() {
 		return $this->key;
 	}
@@ -18,27 +49,18 @@ public function get_key() {
 	/**
 	 * Get the token's value.
 	 *
-	 * @return mixed $value Token value, specific to the token type.
+	 * @return mixed Token value, specific to the token type.
 	 */
 	public function get_value() {
 		return $this->value;
 	}
 
-	/**
-	 * Check if the token is valid.
-	 *
-	 * @return bool True if the token is valid, false otherwise.
-	 */
-	public function is_valid() {
-		return true;
-	}
-
 	/**
 	 * Get the meta key for the token.
 	 *
 	 * @return string Meta key, including type-specific prefix.
 	 */
 	public function get_meta_key() {
-		return static::get_meta_prefix() . $this->get_key();
+		return $this->get_meta_prefix() . $this->get_key();
 	}
 }
diff --git a/inc/tokens/namespace.php b/inc/tokens/namespace.php
index 3e7b28e..0cc8cb0 100644
--- a/inc/tokens/namespace.php
+++ b/inc/tokens/namespace.php
@@ -2,6 +2,12 @@
 
 namespace WP\OAuth2\Tokens;
 
+/**
+ * Get a token by ID.
+ *
+ * @param string $id Token ID.
+ * @return Access_Token|null Token if ID is found, null otherwise.
+ */
 function get_by_id( $id ) {
 	return Access_Token::get_by_id( $id );
 }
diff --git a/inc/types/class-authorization-code.php b/inc/types/class-authorization-code.php
index a9c063c..9e8c700 100644
--- a/inc/types/class-authorization-code.php
+++ b/inc/types/class-authorization-code.php
@@ -2,7 +2,7 @@
 
 namespace WP\OAuth2\Types;
 
-use WP_Http;
+use WP_Error;
 use WP\OAuth2\Client;
 
 class AuthorizationCode extends Base {
@@ -17,6 +17,15 @@ public function get_response_type_code() {
 		return 'code';
 	}
 
+	/**
+	 * Handles the authorization.
+	 *
+	 * @param string $submit
+	 * @param Client $client
+	 * @param array  $data
+	 *
+	 * @return WP_Error
+	 */
 	protected function handle_authorization_submission( $submit, Client $client, $data ) {
 		$redirect_uri = $data['redirect_uri'];
 
diff --git a/inc/types/class-base.php b/inc/types/class-base.php
index 5c27191..2ffdbaf 100644
--- a/inc/types/class-base.php
+++ b/inc/types/class-base.php
@@ -17,7 +17,7 @@ abstract class Base implements Type {
 	 *     @var string $scope Requested scope.
 	 *     @var string $state State parameter from the client.
 	 * }
-	 * @return void Method should output form and exit.
+	 * @return WP_Error|void Method should output form and exit, or return encountered error.
 	 */
 	abstract protected function handle_authorization_submission( $submit, Client $client, $data );
 
@@ -147,6 +147,7 @@ protected function render_form( Client $client, WP_Error $errors = null ) {
 	 * Get the nonce action for a client.
 	 *
 	 * @param Client $client Client to generate nonce for.
+	 * @return string Nonce action for given client.
 	 */
 	protected function get_nonce_action( Client $client ) {
 		return sprintf( 'oauth2_authorize:%s', $client->get_id() );
diff --git a/inc/types/class-implicit.php b/inc/types/class-implicit.php
index 7a2d6d1..519b15f 100644
--- a/inc/types/class-implicit.php
+++ b/inc/types/class-implicit.php
@@ -17,6 +17,15 @@ public function get_response_type_code() {
 		return 'token';
 	}
 
+	/**
+	 * Handles the authorization.
+	 *
+	 * @param string $submit
+	 * @param Client $client
+	 * @param array  $data
+	 *
+	 * @return WP_Error
+	 */
 	protected function handle_authorization_submission( $submit, Client $client, $data ) {
 		$redirect_uri = $data['redirect_uri'];
 
diff --git a/plugin.php b/plugin.php
index bb8e78c..57d577c 100644
--- a/plugin.php
+++ b/plugin.php
@@ -83,7 +83,7 @@ function get_grant_types() {
  *
  * Callback for the oauth2.grant_types hook.
  *
- * @param array Existing grant types.
+ * @param array $types Existing grant types.
  * @return array Grant types with additional types registered.
  */
 function register_grant_types( $types ) {
diff --git a/theme/oauth2-authorize.php b/theme/oauth2-authorize.php
index cdbcb55..9b5c9d4 100644
--- a/theme/oauth2-authorize.php
+++ b/theme/oauth2-authorize.php
@@ -1,4 +1,7 @@
 <?php
+
+/** @var \WP\OAuth2\Client $client */
+
 login_header(
 	__( 'Authorize', 'oauth2' ),
 	'',