From 5e22704f7e59c054cf1f0fca0a459dbbc07fc79e Mon Sep 17 00:00:00 2001
From: Michael <heluecht@pirati.ca>
Date: Wed, 16 Jun 2021 19:24:44 +0000
Subject: [PATCH] API: Added OAuth revoke, adding documentation to parameters

---
 src/Module/OAuth/Authorize.php |  9 +++++----
 src/Module/OAuth/Revoke.php    | 20 +++++++++++++++++++-
 src/Module/OAuth/Token.php     | 11 ++++++-----
 3 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/src/Module/OAuth/Authorize.php b/src/Module/OAuth/Authorize.php
index b2792c598f..cf5187d947 100644
--- a/src/Module/OAuth/Authorize.php
+++ b/src/Module/OAuth/Authorize.php
@@ -41,11 +41,12 @@ class Authorize extends BaseApi
 	public static function rawContent(array $parameters = [])
 	{
 		$request = self::getRequest([
-			'response_type' => '',
-			'client_id'     => '',
+			'force_login'   => '', // Forces the user to re-login, which is necessary for authorizing with multiple accounts from the same instance.
+			'response_type' => '', // Should be set equal to "code".
+			'client_id'     => '', // Client ID, obtained during app registration.
 			'client_secret' => '', // Isn't normally provided. We will use it if present.
-			'redirect_uri'  => '',
-			'scope'         => 'read',
+			'redirect_uri'  => '', // Set a URI to redirect the user to. If this parameter is set to "urn:ietf:wg:oauth:2.0:oob" then the authorization code will be shown instead. Must match one of the redirect URIs declared during app registration.
+			'scope'         => 'read', // List of requested OAuth scopes, separated by spaces (or by pluses, if using query parameters). Must be a subset of scopes declared during app registration. If not provided, defaults to "read".
 			'state'         => '',
 		]);
 
diff --git a/src/Module/OAuth/Revoke.php b/src/Module/OAuth/Revoke.php
index c641932437..519e79db01 100644
--- a/src/Module/OAuth/Revoke.php
+++ b/src/Module/OAuth/Revoke.php
@@ -21,6 +21,10 @@
 
 namespace Friendica\Module\OAuth;
 
+use Friendica\Core\Logger;
+use Friendica\Core\System;
+use Friendica\Database\DBA;
+use Friendica\DI;
 use Friendica\Module\BaseApi;
 
 /**
@@ -30,6 +34,20 @@ class Revoke extends BaseApi
 {
 	public static function post(array $parameters = [])
 	{
-		self::unsupported('post');
+		$request = self::getRequest([
+			'client_id'     => '', // Client ID, obtained during app registration
+			'client_secret' => '', // Client secret, obtained during app registration
+			'token'         => '', // The previously obtained token, to be invalidated
+		]);
+
+		$condition = ['client_id' => $request['client_id'], 'client_secret' => $request['client_secret'], 'access_token' => $request['token']];
+		$token = DBA::selectFirst('application-view', ['id'], $condition);
+		if (empty($token['id'])) {
+			Logger::warning('Token not found', $condition);
+			DI::mstdnError()->Unauthorized();
+		}
+
+		DBA::delete('application-token', ['application-id' => $token['id']]);
+		System::jsonExit([]);
 	}
 }
diff --git a/src/Module/OAuth/Token.php b/src/Module/OAuth/Token.php
index 3a8be825ff..715cabeaf2 100644
--- a/src/Module/OAuth/Token.php
+++ b/src/Module/OAuth/Token.php
@@ -37,11 +37,12 @@ class Token extends BaseApi
 	public static function post(array $parameters = [])
 	{
 		$request = self::getRequest([
-			'grant_type'    => '',
-			'code'          => '',
-			'redirect_uri'  => '',
-			'client_id'     => '',
-			'client_secret' => '',
+			'client_id'     => '', // Client ID, obtained during app registration
+			'client_secret' => '', // Client secret, obtained during app registration
+			'redirect_uri'  => '', // Set a URI to redirect the user to. If this parameter is set to "urn:ietf:wg:oauth:2.0:oob" then the token will be shown instead. Must match one of the redirect URIs declared during app registration.
+			'scope'         => 'read', // List of requested OAuth scopes, separated by spaces. Must be a subset of scopes declared during app registration. If not provided, defaults to "read".
+			'code'          => '', // A user authorization code, obtained via /oauth/authorize
+			'grant_type'    => '', // Set equal to "authorization_code" if code is provided in order to gain user-level access. Otherwise, set equal to "client_credentials" to obtain app-level access only.
 		]);
 
 		// AndStatus transmits the client data in the AUTHORIZATION header field, see https://github.com/andstatus/andstatus/issues/530