feat(request-headers): Document request headers

lib/Controller/AEnvironmentAwareOCSController.php

@@ -63,7 +63,7 @@ public function getResponseFormat(): string {
 
 		// if none is given try the first Accept header
 		if ($format === null) {
-			$headers = $this->request->getHeader('Accept');
+			$headers = $this->request->getHeader('accept');
 			/**
 			 * Default value of
 			 * @see OCSController::buildResponse()

lib/Controller/AvatarController.php

@@ -25,6 +25,7 @@
 use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
 use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
+use OCP\AppFramework\Http\Attribute\RequestHeader;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Http\FileDisplayResponse;
 use OCP\Federation\ICloudIdManager;
@@ -129,6 +130,7 @@ public function emojiAvatar(string $emoji, ?string $color): DataResponse {
 	#[NoCSRFRequired]
 	#[AllowWithoutParticipantWhenPendingInvitation]
 	#[RequireParticipantOrLoggedInAndListedConversation]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function getAvatar(bool $darkTheme = false): FileDisplayResponse {
 		// Cache for 1 day
 		$cacheDuration = 60 * 60 * 24;
@@ -162,6 +164,7 @@ public function getAvatar(bool $darkTheme = false): FileDisplayResponse {
 	#[NoCSRFRequired]
 	#[AllowWithoutParticipantWhenPendingInvitation]
 	#[RequireParticipantOrLoggedInAndListedConversation]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function getAvatarDark(): FileDisplayResponse {
 		return $this->getAvatar(true);
 	}
@@ -181,6 +184,7 @@ public function getAvatarDark(): FileDisplayResponse {
 	#[OpenAPI(scope: OpenAPI::SCOPE_FEDERATION)]
 	#[NoAdminRequired]
 	#[NoCSRFRequired]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function getUserProxyAvatarWithoutRoom(int $size, string $cloudId, bool $darkTheme = false): FileDisplayResponse {
 		return $this->getUserProxyAvatar($size, $cloudId, $darkTheme);
 	}
@@ -199,6 +203,7 @@ public function getUserProxyAvatarWithoutRoom(int $size, string $cloudId, bool $
 	#[OpenAPI(scope: OpenAPI::SCOPE_FEDERATION)]
 	#[NoAdminRequired]
 	#[NoCSRFRequired]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function getUserProxyAvatarDarkWithoutRoom(int $size, string $cloudId): FileDisplayResponse {
 		return $this->getUserProxyAvatar($size, $cloudId, true);
 	}
@@ -221,6 +226,7 @@ public function getUserProxyAvatarDarkWithoutRoom(int $size, string $cloudId): F
 	#[NoCSRFRequired]
 	#[AllowWithoutParticipantWhenPendingInvitation]
 	#[RequireLoggedInParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function getUserProxyAvatar(int $size, string $cloudId, bool $darkTheme = false): FileDisplayResponse {
 		try {
 			$resolvedCloudId = $this->cloudIdManager->resolveCloudId($cloudId);
@@ -281,6 +287,7 @@ public function getUserProxyAvatar(int $size, string $cloudId, bool $darkTheme =
 	#[NoCSRFRequired]
 	#[AllowWithoutParticipantWhenPendingInvitation]
 	#[RequireLoggedInParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function getUserProxyAvatarDark(int $size, string $cloudId): FileDisplayResponse {
 		return $this->getUserProxyAvatar($size, $cloudId, true);
 	}

lib/Controller/BotController.php

@@ -36,6 +36,7 @@
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
 use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
+use OCP\AppFramework\Http\Attribute\RequestHeader;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Utility\ITimeFactory;
 use OCP\Comments\MessageTooLongException;
@@ -73,13 +74,15 @@ public function __construct(
 	 * @return Bot
 	 * @throws \InvalidArgumentException When the request could not be linked with a bot
 	 */
+	#[RequestHeader(name: 'x-nextcloud-talk-bot-random', description: 'Random seed used to generate the request signature')]
+	#[RequestHeader(name: 'x-nextcloud-talk-bot-signature', description: 'Signature over the request body to verify authenticity')]
 	protected function getBotFromHeaders(string $token, string $message): Bot {
-		$random = $this->request->getHeader('X-Nextcloud-Talk-Bot-Random');
+		$random = $this->request->getHeader('x-nextcloud-talk-bot-random');
 		if (empty($random) || strlen($random) < 32) {
 			$this->logger->error('Invalid Random received from bot response');
 			throw new \InvalidArgumentException('Invalid Random received from bot response', Http::STATUS_BAD_REQUEST);
 		}
-		$checksum = $this->request->getHeader('X-Nextcloud-Talk-Bot-Signature');
+		$checksum = $this->request->getHeader('x-nextcloud-talk-bot-signature');
 		if (empty($checksum)) {
 			$this->logger->error('Invalid Signature received from bot response');
 			throw new \InvalidArgumentException('Invalid Signature received from bot response', Http::STATUS_BAD_REQUEST);

lib/Controller/CallController.php

@@ -33,7 +33,9 @@
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\BruteForceProtection;
+use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
 use OCP\AppFramework\Http\Attribute\PublicPage;
+use OCP\AppFramework\Http\Attribute\RequestHeader;
 use OCP\AppFramework\Http\DataDownloadResponse;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Http\Response;
@@ -77,6 +79,7 @@ public function __construct(
 	#[RequireModeratorOrNoLobby]
 	#[RequireParticipant]
 	#[RequireReadWriteConversation]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function getPeersForCall(): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\CallController $proxy */
@@ -129,7 +132,7 @@ public function getPeersForCall(): DataResponse {
 	 */
 	#[PublicPage]
 	#[RequireModeratorParticipant]
-	#[Http\Attribute\NoCSRFRequired]
+	#[NoCSRFRequired]
 	public function downloadParticipantsForCall(string $format = 'csv'): DataDownloadResponse|Response {
 		$callStart = $this->room->getActiveSince()?->getTimestamp() ?? 0;
 		if ($callStart === 0) {
@@ -223,6 +226,7 @@ protected function escapeFormulae(string $value): string {
 	#[RequireModeratorOrNoLobby]
 	#[RequireParticipant]
 	#[RequireReadWriteConversation]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function joinCall(?int $flags = null, bool $silent = false, bool $recordingConsent = false, array $silentFor = []): DataResponse {
 		try {
 			$this->validateRecordingConsent($recordingConsent);
@@ -344,6 +348,7 @@ public function joinFederatedCall(string $sessionId, ?int $flags = null, bool $s
 	#[RequireCallEnabled]
 	#[RequireParticipant]
 	#[RequirePermission(permission: RequirePermission::START_CALL)]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function ringAttendee(int $attendeeId): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\CallController $proxy */
@@ -424,6 +429,7 @@ public function sipDialOut(int $attendeeId): DataResponse {
 	#[FederationSupported]
 	#[PublicPage]
 	#[RequireParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function updateCallFlags(int $flags): DataResponse {
 		$session = $this->participant->getSession();
 		if (!$session instanceof Session) {
@@ -496,6 +502,7 @@ public function updateFederatedCallFlags(string $sessionId, int $flags): DataRes
 	#[FederationSupported]
 	#[PublicPage]
 	#[RequireParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function leaveCall(bool $all = false): DataResponse {
 		$session = $this->participant->getSession();
 		if (!$session instanceof Session) {

lib/Controller/ChatController.php

@@ -53,6 +53,7 @@
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
 use OCP\AppFramework\Http\Attribute\PublicPage;
+use OCP\AppFramework\Http\Attribute\RequestHeader;
 use OCP\AppFramework\Http\Attribute\UserRateLimit;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Services\IAppConfig;
@@ -215,6 +216,7 @@ protected function parseCommentToResponse(IComment $comment, ?Message $parentMes
 	#[RequireParticipant]
 	#[RequirePermission(permission: RequirePermission::CHAT)]
 	#[RequireReadWriteConversation]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function sendMessage(string $message, string $actorDisplayName = '', string $referenceId = '', int $replyTo = 0, bool $silent = false): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\ChatController $proxy */
@@ -392,6 +394,7 @@ public function shareObjectToChat(string $objectType, string $objectId, string $
 	#[PublicPage]
 	#[RequireModeratorOrNoLobby]
 	#[RequireParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function receiveMessages(int $lookIntoFuture,
 		int $limit = 100,
 		int $lastKnownMessageId = 0,
@@ -749,6 +752,7 @@ protected function prepareCommentsAsDataResponse(array $comments, int $lastCommo
 	#[PublicPage]
 	#[RequireModeratorOrNoLobby]
 	#[RequireParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function getMessageContext(
 		int $messageId,
 		int $limit = 50): DataResponse {
@@ -839,6 +843,7 @@ protected function loadSelfReactions(array $messages, array $commentIdToIndex):
 	#[RequireAuthenticatedParticipant]
 	#[RequirePermission(permission: RequirePermission::CHAT)]
 	#[RequireReadWriteConversation]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function deleteMessage(int $messageId): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\ChatController $proxy */
@@ -931,6 +936,7 @@ public function deleteMessage(int $messageId): DataResponse {
 	#[RequireAuthenticatedParticipant]
 	#[RequirePermission(permission: RequirePermission::CHAT)]
 	#[RequireReadWriteConversation]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function editMessage(int $messageId, string $message): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\ChatController $proxy */
@@ -1037,6 +1043,7 @@ public function editMessage(int $messageId, string $message): DataResponse {
 	#[RequireModeratorOrNoLobby]
 	#[RequireLoggedInParticipant]
 	#[UserRateLimit(limit: 60, period: 3600)]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function setReminder(int $messageId, int $timestamp): DataResponse {
 		try {
 			// FIXME fail 400 when reminder is after expiration
@@ -1071,6 +1078,7 @@ public function setReminder(int $messageId, int $timestamp): DataResponse {
 	#[NoAdminRequired]
 	#[RequireModeratorOrNoLobby]
 	#[RequireLoggedInParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function getReminder(int $messageId): DataResponse {
 		try {
 			$this->validateMessageExists($messageId);
@@ -1104,6 +1112,7 @@ public function getReminder(int $messageId): DataResponse {
 	#[NoAdminRequired]
 	#[RequireModeratorOrNoLobby]
 	#[RequireLoggedInParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function deleteReminder(int $messageId): DataResponse {
 		try {
 			$this->validateMessageExists($messageId);
@@ -1290,6 +1299,7 @@ public function clearHistory(): DataResponse {
 	#[FederationSupported]
 	#[PublicPage]
 	#[RequireAuthenticatedParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function setReadMarker(?int $lastReadMessage = null): DataResponse {
 		$setToMessage = $lastReadMessage ?? $this->room->getLastMessageId();
 		if ($setToMessage === 0) {
@@ -1339,6 +1349,7 @@ public function setReadMarker(?int $lastReadMessage = null): DataResponse {
 	#[FederationSupported]
 	#[PublicPage]
 	#[RequireAuthenticatedParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function markUnread(): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\ChatController $proxy */
@@ -1515,6 +1526,7 @@ protected function getMessagesForRoom(array $messageIds): array {
 	#[RequireParticipant]
 	#[RequirePermission(permission: RequirePermission::CHAT)]
 	#[RequireReadWriteConversation]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function mentions(string $search, int $limit = 20, bool $includeStatus = false): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\ChatController $proxy */

lib/Controller/FederationController.php

@@ -52,7 +52,7 @@ public function getResponseFormat(): string {
 
 		// if none is given try the first Accept header
 		if ($format === null) {
-			$headers = $this->request->getHeader('Accept');
+			$headers = $this->request->getHeader('accept');
 			/**
 			 * Default value of
 			 * @see OCSController::buildResponse()

lib/Controller/PollController.php

@@ -28,6 +28,7 @@
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\PublicPage;
+use OCP\AppFramework\Http\Attribute\RequestHeader;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Utility\ITimeFactory;
 use OCP\IRequest;
@@ -73,6 +74,7 @@ public function __construct(
 	#[RequireParticipant]
 	#[RequirePermission(permission: RequirePermission::CHAT)]
 	#[RequireReadWriteConversation]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function createPoll(string $question, array $options, int $resultMode, int $maxVotes, bool $draft = false): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */
@@ -158,6 +160,7 @@ public function createPoll(string $question, array $options, int $resultMode, in
 	#[RequireParticipant]
 	#[RequirePermission(permission: RequirePermission::CHAT)]
 	#[RequireReadWriteConversation]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function updateDraftPoll(int $pollId, string $question, array $options, int $resultMode, int $maxVotes): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */
@@ -220,6 +223,7 @@ public function updateDraftPoll(int $pollId, string $question, array $options, i
 	#[FederationSupported]
 	#[PublicPage]
 	#[RequireModeratorParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function getAllDraftPolls(): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */
@@ -250,6 +254,7 @@ public function getAllDraftPolls(): DataResponse {
 	#[PublicPage]
 	#[RequireModeratorOrNoLobby]
 	#[RequireParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function showPoll(int $pollId): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */
@@ -292,6 +297,7 @@ public function showPoll(int $pollId): DataResponse {
 	#[PublicPage]
 	#[RequireModeratorOrNoLobby]
 	#[RequireParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function votePoll(int $pollId, array $optionIds = []): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */
@@ -358,6 +364,7 @@ public function votePoll(int $pollId, array $optionIds = []): DataResponse {
 	#[PublicPage]
 	#[RequireModeratorOrNoLobby]
 	#[RequireParticipant]
+	#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
 	public function closePoll(int $pollId): DataResponse {
 		if ($this->room->isFederatedConversation()) {
 			/** @var \OCA\Talk\Federation\Proxy\TalkV1\Controller\PollController $proxy */