Add an endpoint to validate a PIN for a given conversation

Signed-off-by: Joas Schilling <coding@schilljs.com>

appinfo/routes.php

@@ -353,6 +353,16 @@ return [
 				'token' => '^[a-z0-9]{4,30}$',
 			],
 		],
+		[
+			'name' => 'Room#getParticipantByDialInPin',
+			'url' => '/api/{apiVersion}/room/{token}/pin/{pin}',
+			'verb' => 'GET',
+			'requirements' => [
+				'apiVersion' => 'v2',
+				'token' => '^[a-z0-9]{4,30}$',
+				'pin' => '^\d{7,32}$',
+			],
+		],
 		[
 			'name' => 'Room#setNotificationLevel',
 			'url' => '/api/{apiVersion}/room/{token}/notify',

docs/participant.md

@@ -190,6 +190,21 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
         + `404 Not Found` When the conversation could not be found for the participant
         + `404 Not Found` When the participant to demote could not be found
 
+## Get a participant by their pin
+
+Note: This is only allowed with validate SIP bridge requests
+
+* Method: `GET`
+* Endpoint: `/room/{token}/pin/{pin}`
+
+* Response:
+    - Status code:
+        + `200 OK`
+        + `401 Unauthorized` When the validation as SIP bridge failed
+        + `404 Not Found` When the conversation or participant could not be found
+
+    - Data: See array definition in `Get user´s conversations`
+
 ## Set display name as a guest
 
 * Method: `POST`

lib/Controller/RoomController.php

@@ -1442,6 +1442,30 @@ class RoomController extends AEnvironmentAwareController {
 		return new DataResponse($this->formatRoom($room, $participant));
 	}
 
+	/**
+	 * @PublicPage
+	 *
+	 * @param string $pin
+	 * @return DataResponse
+	 */
+	public function getParticipantByDialInPin(string $pin): DataResponse {
+		try {
+			if (!$this->validateSIPBridgeRequest($this->room->getToken())) {
+				return new DataResponse([], Http::STATUS_UNAUTHORIZED);
+			}
+		} catch (UnauthorizedException $e) {
+			return new DataResponse([], Http::STATUS_UNAUTHORIZED);
+		}
+
+		try {
+			$participant = $this->room->getParticipantByPin($pin);
+		} catch (ParticipantNotFoundException $e) {
+			return new DataResponse([], Http::STATUS_NOT_FOUND);
+		}
+
+		return new DataResponse($this->formatRoom($this->room, $participant));
+	}
+
 	/**
 	 * @PublicPage
 	 * @UseSession

lib/Room.php

@@ -402,6 +402,32 @@ class Room {
 		return $this->manager->createParticipantObject($this, $row);
 	}
 
+	/**
+	 * @param string $pin
+	 * @return Participant
+	 * @throws ParticipantNotFoundException When the pin is not valid (has no participant assigned)
+	 */
+	public function getParticipantByPin(string $pin): Participant {
+		$query = $this->db->getQueryBuilder();
+		$query->select('*')
+			->selectAlias('a.id', 'a_id')
+			->selectAlias('s.id', 's_id')
+			->from('talk_attendees', 'a')
+			->leftJoin('a', 'talk_sessions', 's', $query->expr()->eq('a.id', 's.attendee_id'))
+			->andWhere($query->expr()->eq('a.pin', $query->createNamedParameter($pin)))
+			->andWhere($query->expr()->eq('a.room_id', $query->createNamedParameter($this->getId())))
+			->setMaxResults(1);
+		$result = $query->execute();
+		$row = $result->fetch();
+		$result->closeCursor();
+
+		if ($row === false) {
+			throw new ParticipantNotFoundException('User is not a participant');
+		}
+
+		return $this->manager->createParticipantObject($this, $row);
+	}
+
 	public function deleteRoom(): void {
 		$event = new RoomEvent($this);
 		$this->dispatcher->dispatch(self::EVENT_BEFORE_ROOM_DELETE, $event);