⛔ feat(ban): Contract for banning attendees and IP/ranges

appinfo/routes.php

@@ -9,6 +9,7 @@
 
 return array_merge_recursive(
  include(__DIR__ . '/routes/routesAvatarController.php'),
+ include(__DIR__ . '/routes/routesBanController.php'),
  include(__DIR__ . '/routes/routesBotController.php'),
  include(__DIR__ . '/routes/routesBreakoutRoomController.php'),
  include(__DIR__ . '/routes/routesCallController.php'),

appinfo/routes/routesBanController.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+$requirements = [
+ 'apiVersion' => '(v1)',
+ 'token' => '[a-z0-9]{4,30}',
+];
+return [
+ 'ocs' => [
+ /** @see \OCA\Talk\Controller\BanController::banActor() */
+ ['name' => 'Ban#banActor', 'url' => '/api/{apiVersion}/ban/{token}', 'verb' => 'POST', 'requirements' => $requirements],
+ /** @see \OCA\Talk\Controller\BanController::listBans() */
+ ['name' => 'Ban#listBans', 'url' => '/api/{apiVersion}/ban/{token}', 'verb' => 'GET', 'requirements' => $requirements],
+ /** @see \OCA\Talk\Controller\BanController::unbanActor() */
+ ['name' => 'Ban#unbanActor', 'url' => '/api/{apiVersion}/ban/{token}', 'verb' => 'DELETE', 'requirements' => $requirements],
+ ],
+];

docs/capabilities.md

@@ -149,3 +149,6 @@
 * `config => federation => incoming-enabled` - Boolean, whether users are allowed to be invited into federated conversations on other servers
 * `config => federation => outgoing-enabled` - Boolean, whether users are allowed to invited federated users of other servers into conversations
 * `config => federation => only-trusted-servers` - Boolean, whether federation invites are limited to trusted servers
+
+## 20
+* `ban-v1` - Whether the API to ban attendees is available

lib/Capabilities.php

@@ -125,6 +125,7 @@ public function getCapabilities(): array {
  'silent-send-state',
  'chat-read-last',
  'federation-v1',
+ 'ban-v1',
  ],
  'config' => [
  'attachments' => [

lib/Controller/BanController.php

@@ -0,0 +1,123 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Talk\Controller;
+
+use OCA\Talk\Middleware\Attribute\RequireModeratorParticipant;
+use OCA\Talk\Model\Attendee;
+use OCA\Talk\ResponseDefinitions;
+use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\PublicPage;
+use OCP\AppFramework\Http\DataResponse;
+use OCP\IRequest;
+
+/**
+ * @psalm-import-type TalkBan from ResponseDefinitions
+ */
+class BanController extends AEnvironmentAwareController {
+ public function __construct(
+ string $appName,
+ IRequest $request,
+ ) {
+ parent::__construct($appName, $request);
+ }
+
+ /**
+ * Ban an actor or IP address
+ *
+ * Required capability: `ban-v1`
+ *
+ * @param 'users'|'groups'|'circles'|'emails'|'federated_users'|'phones'|'ip' $actorType Type of actor to ban, or `ip` when banning a clients remote address
+ * @psalm-param Attendee::ACTOR_*|'ip' $actorType Type of actor to ban, or `ip` when banning a clients remote address
+ * @param string $actorId Actor ID or the IP address or range in case of type `ip`
+ * @param string $internalNote Optional internal note
+ * @return DataResponse<Http::STATUS_OK, TalkBan, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
+ *
+ * 200: Ban successfully
+ * 400: Actor information is invalid
+ */
+ #[PublicPage]
+ #[RequireModeratorParticipant]
+ public function banActor(string $actorType, string $actorId, string $internalNote = ''): DataResponse {
+ if ($actorId === 'wrong') {
+ return new DataResponse([
+ 'error' => 'actor',
+ ], Http::STATUS_BAD_REQUEST);
+ }
+
+
+ return new DataResponse(
+ [
+ 'id' => random_int(1, 1337),
+ 'actorType' => $this->participant->getAttendee()->getActorType(),
+ 'actorId' => $this->participant->getAttendee()->getActorId(),
+ 'bannedType' => $actorType,
+ 'bannedId' => $actorId,
+ 'bannedTime' => time(),
+ 'internalNote' => $internalNote ?: 'Lorem ipsum',
+ ],
+ Http::STATUS_OK
+ );
+ }
+
+ /**
+ * List the bans of a conversation
+ *
+ * Required capability: `ban-v1`
+ *
+ * @return DataResponse<Http::STATUS_OK, list<TalkBan>, array{}>
+ *
+ * 200: List all bans
+ */
+ #[PublicPage]
+ #[RequireModeratorParticipant]
+ public function listBans(): DataResponse {
+ return new DataResponse([
+ $this->randomBan(Attendee::ACTOR_USERS, 'test'),
+ $this->randomBan(Attendee::ACTOR_USERS, '123456'),
+ $this->randomBan(Attendee::ACTOR_FEDERATED_USERS, 'admin@nextcloud.local'),
+ $this->randomBan('ip', '127.0.0.1'),
+ $this->randomBan('ip', '127.0.0.1/32'),
+ $this->randomBan('ip', '127.0.0.0/24'),
+ $this->randomBan('ip', '::1/24'),
+ $this->randomBan('ip', '2001:0db8:85a3::/48'),
+ ], Http::STATUS_OK);
+ }
+
+ /**
+ * Unban an actor or IP address
+ *
+ * Required capability: `ban-v1`
+ *
+ * @param int $banId ID of the ban to be removed
+ * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+ *
+ * 200: Unban successfully or not found
+ */
+ #[PublicPage]
+ #[RequireModeratorParticipant]
+ public function unbanActor(int $banId): DataResponse {
+ return new DataResponse([], Http::STATUS_OK);
+ }
+
+ /**
+ * @psalm-return TalkBan
+ */
+ protected function randomBan(string $actorType, string $actorId): array {
+ return [
+ 'id' => random_int(1, 1337),
+ 'actorType' => $this->participant->getAttendee()->getActorType(),
+ 'actorId' => $this->participant->getAttendee()->getActorId(),
+ 'bannedType' => $actorType,
+ 'bannedId' => $actorId,
+ 'bannedTime' => random_int(1514747958, 1714747958),
+ 'internalNote' => '#NOTE#' . $actorType . '#' . $actorId . '#' . sha1($actorType . $actorId),
+ ];
+ }
+}

lib/Controller/RoomController.php

@@ -1474,7 +1474,7 @@ public function setPassword(string $password): DataResponse {
  * @param string $token Token of the room
  * @param string $password Password of the room
  * @param bool $force Create a new session if necessary
- * @return DataResponse<Http::STATUS_OK, TalkRoom, array{X-Nextcloud-Talk-Proxy-Hash?: string}>|DataResponse<Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>|DataResponse<Http::STATUS_CONFLICT, array{sessionId: string, inCall: int, lastPing: int}, array{}>
+ * @return DataResponse<Http::STATUS_OK, TalkRoom, array{X-Nextcloud-Talk-Proxy-Hash?: string}>|DataResponse<Http::STATUS_FORBIDDEN, array{error: 'ban'|'password'}, array<empty>>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array<empty>>|DataResponse<Http::STATUS_CONFLICT, array{sessionId: string, inCall: int, lastPing: int}, array<empty>>
  *
  * 200: Room joined successfully
  * 403: Joining room is not allowed
@@ -1512,6 +1512,18 @@ public function joinRoom(string $token, string $password = '', bool $force = tru
  return $response;
  }
 
+ if (strtolower($room->getName()) === 'ban user' && $this->userId === 'banned') {
+ return new DataResponse([
+ 'error' => 'ban',
+ ], Http::STATUS_FORBIDDEN);
+ }
+
+ if (strtolower($room->getName()) === 'ban guest' && !$this->userId) {
+ return new DataResponse([
+ 'error' => 'ban',
+ ], Http::STATUS_FORBIDDEN);
+ }
+
  /** @var Participant|null $previousSession */
  $previousParticipant = null;
  /** @var Session|null $previousSession */
@@ -1585,7 +1597,9 @@ public function joinRoom(string $token, string $password = '', bool $force = tru
  $this->throttler->resetDelay($this->request->getRemoteAddress(), 'talkRoomPassword', ['token' => $token, 'action' => 'talkRoomPassword']);
  $this->throttler->resetDelay($this->request->getRemoteAddress(), 'talkRoomToken', ['token' => $token, 'action' => 'talkRoomToken']);
  } catch (InvalidPasswordException $e) {
- $response = new DataResponse([], Http::STATUS_FORBIDDEN);
+ $response = new DataResponse([
+ 'error' => 'password',
+ ], Http::STATUS_FORBIDDEN);
  $response->throttle(['token' => $token, 'action' => 'talkRoomPassword']);
  return $response;
  } catch (UnauthorizedException $e) {

lib/ResponseDefinitions.php

@@ -10,6 +10,16 @@
 namespace OCA\Talk;
 
 /**
+ * @psalm-type TalkBan = array{
+ * id: int,
+ * actorType: string,
+ * actorId: string,
+ * bannedType: string,
+ * bannedId: string,
+ * bannedTime: int,
+ * internalNote: string,
+ * }
+ *
  * @psalm-type TalkBot = array{
  * description: ?string,
  * id: int,