friendica/include/api.php

<?php
/**
 * @copyright Copyright (C) 2020, Friendica
 *
 * @license GNU AGPL version 3 or any later version
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 *
 * Friendica implementation of statusnet/twitter API
 *
 * @file include/api.php
 * @todo Automatically detect if incoming data is HTML or BBCode
 */

use Friendica\App;
use Friendica\Content\ContactSelector;
use Friendica\Content\Text\BBCode;
use Friendica\Content\Text\HTML;
use Friendica\Core\Hook;
use Friendica\Core\Logger;
use Friendica\Core\Protocol;
use Friendica\Core\Session;
use Friendica\Core\System;
use Friendica\Core\Worker;
use Friendica\Database\DBA;
use Friendica\DI;
use Friendica\Model\Contact;
use Friendica\Model\Group;
use Friendica\Model\Item;
use Friendica\Model\Mail;
use Friendica\Model\Notify;
use Friendica\Model\Photo;
use Friendica\Model\Post;
use Friendica\Model\User;
use Friendica\Model\UserItem;
use Friendica\Model\Verb;
use Friendica\Security\FKOAuth1;
use Friendica\Network\HTTPException;
use Friendica\Network\HTTPException\BadRequestException;
use Friendica\Network\HTTPException\ExpectationFailedException;
use Friendica\Network\HTTPException\ForbiddenException;
use Friendica\Network\HTTPException\InternalServerErrorException;
use Friendica\Network\HTTPException\MethodNotAllowedException;
use Friendica\Network\HTTPException\NotFoundException;
use Friendica\Network\HTTPException\NotImplementedException;
use Friendica\Network\HTTPException\TooManyRequestsException;
use Friendica\Network\HTTPException\UnauthorizedException;
use Friendica\Object\Image;
use Friendica\Protocol\Activity;
use Friendica\Protocol\Diaspora;
use Friendica\Security\OAuth1\OAuthRequest;
use Friendica\Security\OAuth1\OAuthUtil;
use Friendica\Util\DateTimeFormat;
use Friendica\Util\Images;
use Friendica\Util\Network;
use Friendica\Util\Proxy as ProxyUtils;
use Friendica\Util\Strings;
use Friendica\Util\XML;

require_once __DIR__ . '/../mod/item.php';
require_once __DIR__ . '/../mod/wall_upload.php';

define('API_METHOD_ANY', '*');
define('API_METHOD_GET', 'GET');
define('API_METHOD_POST', 'POST,PUT');
define('API_METHOD_DELETE', 'POST,DELETE');

define('API_LOG_PREFIX', 'API {action} - ');

$API = [];
$called_api = [];

/**
 * Auth API user
 *
 * It is not sufficient to use local_user() to check whether someone is allowed to use the API,
 * because this will open CSRF holes (just embed an image with src=friendicasite.com/api/statuses/update?status=CSRF
 * into a page, and visitors will post something without noticing it).
 */
function api_user()
{
	if (!empty($_SESSION['allow_api'])) {
		return local_user();
	}

	return false;
}

/**
 * Get source name from API client
 *
 * Clients can send 'source' parameter to be show in post metadata
 * as "sent via <source>".
 * Some clients doesn't send a source param, we support ones we know
 * (only Twidere, atm)
 *
 * @return string
 *        Client source name, default to "api" if unset/unknown
 * @throws Exception
 */
function api_source()
{
	if (requestdata('source')) {
		return requestdata('source');
	}

	// Support for known clients that doesn't send a source name
	if (!empty($_SERVER['HTTP_USER_AGENT'])) {
		if(strpos($_SERVER['HTTP_USER_AGENT'], "Twidere") !== false) {
			return "Twidere";
		}

		Logger::info(API_LOG_PREFIX . 'Unrecognized user-agent', ['module' => 'api', 'action' => 'source', 'http_user_agent' => $_SERVER['HTTP_USER_AGENT']]);
	} else {
		Logger::info(API_LOG_PREFIX . 'Empty user-agent', ['module' => 'api', 'action' => 'source']);
	}

	return "api";
}

/**
 * Format date for API
 *
 * @param string $str Source date, as UTC
 * @return string Date in UTC formatted as "D M d H:i:s +0000 Y"
 * @throws Exception
 */
function api_date($str)
{
	// Wed May 23 06:01:13 +0000 2007
	return DateTimeFormat::utc($str, "D M d H:i:s +0000 Y");
}

/**
 * Register a function to be the endpoint for defined API path.
 *
 * @param string $path   API URL path, relative to DI::baseUrl()
 * @param string $func   Function name to call on path request
 * @param bool   $auth   API need logged user
 * @param string $method HTTP method reqiured to call this endpoint.
 *                       One of API_METHOD_ANY, API_METHOD_GET, API_METHOD_POST.
 *                       Default to API_METHOD_ANY
 */
function api_register_func($path, $func, $auth = false, $method = API_METHOD_ANY)
{
	global $API;

	$API[$path] = [
		'func'   => $func,
		'auth'   => $auth,
		'method' => $method,
	];

	// Workaround for hotot
	$path = str_replace("api/", "api/1.1/", $path);

	$API[$path] = [
		'func'   => $func,
		'auth'   => $auth,
		'method' => $method,
	];
}

/**
 * Log in user via OAuth1 or Simple HTTP Auth.
 * Simple Auth allow username in form of <pre>user@server</pre>, ignoring server part
 *
 * @param App $a App
 * @throws ForbiddenException
 * @throws InternalServerErrorException
 * @throws UnauthorizedException
 * @hook  'authenticate'
 *               array $addon_auth
 *               'username' => username from login form
 *               'password' => password from login form
 *               'authenticated' => return status,
 *               'user_record' => return authenticated user record
 */
function api_login(App $a)
{
	// workaround for HTTP-auth in CGI mode
	if (!empty($_SERVER['REDIRECT_REMOTE_USER'])) {
		$userpass = base64_decode(substr($_SERVER["REDIRECT_REMOTE_USER"], 6));
		if (strlen($userpass)) {
			list($name, $password) = explode(':', $userpass);
			$_SERVER['PHP_AUTH_USER'] = $name;
			$_SERVER['PHP_AUTH_PW'] = $password;
		}
	}

	if (empty($_SERVER['PHP_AUTH_USER'])) {
		// Try OAuth when no user is provided
		$oauth1 = new FKOAuth1();
		// login with oauth
		try {
			$request = OAuthRequest::from_request();
			list($consumer, $token) = $oauth1->verify_request($request);
			if (!is_null($token)) {
				$oauth1->loginUser($token->uid);
				Session::set('allow_api', true);
				return;
			}
			echo __FILE__.__LINE__.__FUNCTION__ . "<pre>";
			var_dump($consumer, $token);
			die();
		} catch (Exception $e) {
			Logger::warning(API_LOG_PREFIX . 'OAuth error', ['module' => 'api', 'action' => 'login', 'exception' => $e->getMessage()]);
		}

		Logger::debug(API_LOG_PREFIX . 'failed', ['module' => 'api', 'action' => 'login', 'parameters' => $_SERVER]);
		header('WWW-Authenticate: Basic realm="Friendica"');
		throw new UnauthorizedException("This API requires login");
	}

	$user = $_SERVER['PHP_AUTH_USER'] ?? '';
	$password = $_SERVER['PHP_AUTH_PW'] ?? '';

	// allow "user@server" login (but ignore 'server' part)
	$at = strstr($user, "@", true);
	if ($at) {
		$user = $at;
	}

	// next code from mod/auth.php. needs better solution
	$record = null;

	$addon_auth = [
		'username' => trim($user),
		'password' => trim($password),
		'authenticated' => 0,
		'user_record' => null,
	];

	/*
	* An addon indicates successful login by setting 'authenticated' to non-zero value and returning a user record
	* Addons should never set 'authenticated' except to indicate success - as hooks may be chained
	* and later addons should not interfere with an earlier one that succeeded.
	*/
	Hook::callAll('authenticate', $addon_auth);

	if ($addon_auth['authenticated'] && count($addon_auth['user_record'])) {
		$record = $addon_auth['user_record'];
	} else {
		$user_id = User::authenticate(trim($user), trim($password), true);
		if ($user_id !== false) {
			$record = DBA::selectFirst('user', [], ['uid' => $user_id]);
		}
	}

	if (!DBA::isResult($record)) {
		Logger::debug(API_LOG_PREFIX . 'failed', ['module' => 'api', 'action' => 'login', 'parameters' => $_SERVER]);
		header('WWW-Authenticate: Basic realm="Friendica"');
		//header('HTTP/1.0 401 Unauthorized');
		//die('This api requires login');
		throw new UnauthorizedException("This API requires login");
	}

	// Don't refresh the login date more often than twice a day to spare database writes
	$login_refresh = strcmp(DateTimeFormat::utc('now - 12 hours'), $record['login_date']) > 0;

	DI::auth()->setForUser($a, $record, false, false, $login_refresh);

	$_SESSION["allow_api"] = true;

	Hook::callAll('logged_in', $a->user);
}

/**
 * Check HTTP method of called API
 *
 * API endpoints can define which HTTP method to accept when called.
 * This function check the current HTTP method agains endpoint
 * registered method.
 *
 * @param string $method Required methods, uppercase, separated by comma
 * @return bool
 */
function api_check_method($method)
{
	if ($method == "*") {
		return true;
	}
	return (stripos($method, $_SERVER['REQUEST_METHOD'] ?? 'GET') !== false);
}

/**
 * Main API entry point
 *
 * Authenticate user, call registered API function, set HTTP headers
 *
 * @param App $a App
 * @param App\Arguments $args The app arguments (optional, will retrieved by the DI-Container in case of missing)
 * @return string|array API call result
 * @throws Exception
 */
function api_call(App $a, App\Arguments $args = null)
{
	global $API, $called_api;

	if ($args == null) {
		$args = DI::args();
	}

	$type = "json";
	if (strpos($args->getCommand(), ".xml") > 0) {
		$type = "xml";
	}
	if (strpos($args->getCommand(), ".json") > 0) {
		$type = "json";
	}
	if (strpos($args->getCommand(), ".rss") > 0) {
		$type = "rss";
	}
	if (strpos($args->getCommand(), ".atom") > 0) {
		$type = "atom";
	}

	try {
		foreach ($API as $p => $info) {
			if (strpos($args->getCommand(), $p) === 0) {
				if (!api_check_method($info['method'])) {
					throw new MethodNotAllowedException();
				}

				$called_api = explode("/", $p);

				if (!empty($info['auth']) && api_user() === false) {
					api_login($a);
					Logger::info(API_LOG_PREFIX . 'username {username}', ['module' => 'api', 'action' => 'call', 'username' => $a->user['username']]);
				}

				Logger::debug(API_LOG_PREFIX . 'parameters', ['module' => 'api', 'action' => 'call', 'parameters' => $_REQUEST]);

				$stamp =  microtime(true);
				$return = call_user_func($info['func'], $type);
				$duration = floatval(microtime(true) - $stamp);

				Logger::info(API_LOG_PREFIX . 'duration {duration}', ['module' => 'api', 'action' => 'call', 'duration' => round($duration, 2)]);

				DI::profiler()->saveLog(DI::logger(), API_LOG_PREFIX . 'performance');

				if (false === $return) {
					/*
						* api function returned false withour throw an
						* exception. This should not happend, throw a 500
						*/
					throw new InternalServerErrorException();
				}

				switch ($type) {
					case "xml":
						header("Content-Type: text/xml");
						break;
					case "json":
						header("Content-Type: application/json");
						if (!empty($return)) {
							$json = json_encode(end($return));
							if (!empty($_GET['callback'])) {
								$json = $_GET['callback'] . "(" . $json . ")";
							}
							$return = $json;
						}
						break;
					case "rss":
						header("Content-Type: application/rss+xml");
						$return  = '<?xml version="1.0" encoding="UTF-8"?>' . "\n" . $return;
						break;
					case "atom":
						header("Content-Type: application/atom+xml");
						$return = '<?xml version="1.0" encoding="UTF-8"?>' . "\n" . $return;
						break;
				}
				return $return;
			}
		}

		Logger::warning(API_LOG_PREFIX . 'not implemented', ['module' => 'api', 'action' => 'call', 'query' => DI::args()->getQueryString()]);
		throw new NotFoundException();
	} catch (HTTPException $e) {
		header("HTTP/1.1 {$e->getCode()} {$e->httpdesc}");
		return api_error($type, $e, $args);
	}
}

/**
 * Format API error string
 *
 * @param string $type Return type (xml, json, rss, as)
 * @param object $e    HTTPException Error object
 * @param App\Arguments $args The App arguments
 * @return string|array error message formatted as $type
 */
function api_error($type, $e, App\Arguments $args)
{
	$error = ($e->getMessage() !== "" ? $e->getMessage() : $e->httpdesc);
	/// @TODO:  https://dev.twitter.com/overview/api/response-codes

	$error = ["error" => $error,
			"code" => $e->getCode() . " " . $e->httpdesc,
			"request" => $args->getQueryString()];

	$return = api_format_data('status', $type, ['status' => $error]);

	switch ($type) {
		case "xml":
			header("Content-Type: text/xml");
			break;
		case "json":
			header("Content-Type: application/json");
			$return = json_encode($return);
			break;
		case "rss":
			header("Content-Type: application/rss+xml");
			break;
		case "atom":
			header("Content-Type: application/atom+xml");
			break;
	}

	return $return;
}

/**
 * Set values for RSS template
 *
 * @param App   $a
 * @param array $arr       Array to be passed to template
 * @param array $user_info User info
 * @return array
 * @throws BadRequestException
 * @throws ImagickException
 * @throws InternalServerErrorException
 * @throws UnauthorizedException
 * @todo  find proper type-hints
 */
function api_rss_extra(App $a, $arr, $user_info)
{
	if (is_null($user_info)) {
		$user_info = api_get_user($a);
	}

	$arr['$user'] = $user_info;
	$arr['$rss'] = [
		'alternate'    => $user_info['url'],
		'self'         => DI::baseUrl() . "/" . DI::args()->getQueryString(),
		'base'         => DI::baseUrl(),
		'updated'      => api_date(null),
		'atom_updated' => DateTimeFormat::utcNow(DateTimeFormat::ATOM),
		'language'     => $user_info['lang'],
		'logo'         => DI::baseUrl() . "/images/friendica-32.png",
	];

	return $arr;
}


/**
 * Unique contact to contact url.
 *
 * @param int $id Contact id
 * @return bool|string
 *                Contact url or False if contact id is unknown
 * @throws Exception
 */
function api_unique_id_to_nurl($id)
{
	$r = DBA::selectFirst('contact', ['nurl'], ['id' => $id]);

	if (DBA::isResult($r)) {
		return $r["nurl"];
	} else {
		return false;
	}
}

/**
 * Get user info array.
 *
 * @param App        $a          App
 * @param int|string $contact_id Contact ID or URL
 * @return array|bool
 * @throws BadRequestException
 * @throws ImagickException
 * @throws InternalServerErrorException
 * @throws UnauthorizedException
 */
function api_get_user(App $a, $contact_id = null)
{
	global $called_api;

	$user = null;
	$extra_query = "";
	$url = "";

	Logger::info(API_LOG_PREFIX . 'Fetching data for user {user}', ['module' => 'api', 'action' => 'get_user', 'user' => $contact_id]);

	// Searching for contact URL
	if (!is_null($contact_id) && (intval($contact_id) == 0)) {
		$user = DBA::escape(Strings::normaliseLink($contact_id));
		$url = $user;
		$extra_query = "AND `contact`.`nurl` = '%s' ";
		if (api_user() !== false) {
			$extra_query .= "AND `contact`.`uid`=" . intval(api_user());
		}
	}

	// Searching for contact id with uid = 0
	if (!is_null($contact_id) && (intval($contact_id) != 0)) {
		$user = DBA::escape(api_unique_id_to_nurl(intval($contact_id)));

		if ($user == "") {
			throw new BadRequestException("User ID ".$contact_id." not found.");
		}

		$url = $user;
		$extra_query = "AND `contact`.`nurl` = '%s' ";
		if (api_user() !== false) {
			$extra_query .= "AND `contact`.`uid`=" . intval(api_user());
		}
	}

	if (is_null($user) && !empty($_GET['user_id'])) {
		$user = DBA::escape(api_unique_id_to_nurl($_GET['user_id']));

		if ($user == "") {
			throw new BadRequestException("User ID ".$_GET['user_id']." not found.");
		}

		$url = $user;
		$extra_query = "AND `contact`.`nurl` = '%s' ";
		if (api_user() !== false) {
			$extra_query .= "AND `contact`.`uid`=" . intval(api_user());
		}
	}
	if (is_null($user) && !empty($_GET['screen_name'])) {
		$user = DBA::escape($_GET['screen_name']);
		$extra_query = "AND `contact`.`nick` = '%s' ";
		if (api_user() !== false) {
			$extra_query .= "AND `contact`.`uid`=".intval(api_user());
		}
	}

	if (is_null($user) && !empty($_GET['profileurl'])) {
		$user = DBA::escape(Strings::normaliseLink($_GET['profileurl']));
		$extra_query = "AND `contact`.`nurl` = '%s' ";
		if (api_user() !== false) {
			$extra_query .= "AND `contact`.`uid`=".intval(api_user());
		}
	}

	// $called_api is the API path exploded on / and is expected to have at least 2 elements
	if (is_null($user) && ($a->argc > (count($called_api) - 1)) && (count($called_api) > 0)) {
		$argid = count($called_api);
		if (!empty($a->argv[$argid])) {
			$data = explode(".", $a->argv[$argid]);