From 82592e1f6cac53434ceefa07c5fe321344ca521e Mon Sep 17 00:00:00 2001 From: juancarmore Date: Fri, 11 Jul 2025 01:45:11 +0200 Subject: [PATCH] openapi: add x-participant-role header parameter and error response for invalid roles. Update related paths to include role validation. --- .../parameters/internal/x-participant-role.yaml | 12 ++++++++++++ .../openapi/components/parameters/x-signature.yaml | 6 +++--- .../openapi/components/parameters/x-timestamp.yaml | 4 ++-- .../internal/error-invalid-participant-role.yaml | 8 ++++++++ .../schemas/internal/meet-room-role-permissions.yaml | 2 +- backend/openapi/paths/internal/meetings.yaml | 6 ++++++ backend/openapi/paths/internal/recordings.yaml | 7 +++++++ backend/openapi/paths/internal/rooms.yaml | 3 +++ backend/openapi/paths/rooms.yaml | 3 +++ 9 files changed, 45 insertions(+), 6 deletions(-) create mode 100644 backend/openapi/components/parameters/internal/x-participant-role.yaml create mode 100644 backend/openapi/components/responses/internal/error-invalid-participant-role.yaml diff --git a/backend/openapi/components/parameters/internal/x-participant-role.yaml b/backend/openapi/components/parameters/internal/x-participant-role.yaml new file mode 100644 index 0000000..7b381c7 --- /dev/null +++ b/backend/openapi/components/parameters/internal/x-participant-role.yaml @@ -0,0 +1,12 @@ +name: x-participant-role +in: header +description: | + The role of the participant in the meeting. It can be one of the following values: + - `moderator`: Can manage the room and its participants. + - `publisher`: Can publish media streams to the room. + + This is required to distinguish roles when multiple are present in the participant token +required: true +schema: + type: string + enum: ['moderator', 'publisher'] diff --git a/backend/openapi/components/parameters/x-signature.yaml b/backend/openapi/components/parameters/x-signature.yaml index dff3175..b935e28 100644 --- a/backend/openapi/components/parameters/x-signature.yaml +++ b/backend/openapi/components/parameters/x-signature.yaml @@ -1,9 +1,9 @@ name: x-signature in: header description: > - HMAC-SHA256 signature of the request body, created using your webhook secret. + HMAC-SHA256 signature of the request body, created using your webhook secret. - Use this to verify the webhook came from OpenVidu Meet and wasn't tampered with. + Use this to verify the webhook came from OpenVidu Meet and wasn't tampered with. required: true schema: - type: string + type: string diff --git a/backend/openapi/components/parameters/x-timestamp.yaml b/backend/openapi/components/parameters/x-timestamp.yaml index 0498fb6..7208875 100644 --- a/backend/openapi/components/parameters/x-timestamp.yaml +++ b/backend/openapi/components/parameters/x-timestamp.yaml @@ -1,9 +1,9 @@ name: x-timestamp in: header description: > - Unix timestamp (in seconds) when the webhook was sent. + Unix timestamp (in seconds) when the webhook was sent. - Can be used to validate webhook age and prevent replay attacks. + Can be used to validate webhook age and prevent replay attacks. required: true schema: type: string diff --git a/backend/openapi/components/responses/internal/error-invalid-participant-role.yaml b/backend/openapi/components/responses/internal/error-invalid-participant-role.yaml new file mode 100644 index 0000000..f8007dc --- /dev/null +++ b/backend/openapi/components/responses/internal/error-invalid-participant-role.yaml @@ -0,0 +1,8 @@ +description: Invalid participant role provided +content: + application/json: + schema: + $ref: '../../schemas/error.yaml' + example: + error: Participant Error + message: 'No valid participant role provided' diff --git a/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml b/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml index 8aa2f81..e304b96 100644 --- a/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml +++ b/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml @@ -3,7 +3,7 @@ properties: role: type: string enum: ['moderator', 'publisher'] - description: > + description: | A role that a participant can have in a room. The role determines the permissions of the participant in the room. - `moderator`: Can manage the room and its participants. diff --git a/backend/openapi/paths/internal/meetings.yaml b/backend/openapi/paths/internal/meetings.yaml index 7b0a4c2..c087c9a 100644 --- a/backend/openapi/paths/internal/meetings.yaml +++ b/backend/openapi/paths/internal/meetings.yaml @@ -12,9 +12,12 @@ - participantTokenCookie: [] parameters: - $ref: '../../components/parameters/room-id-path.yaml' + - $ref: '../../components/parameters/internal/x-participant-role.yaml' responses: '200': $ref: '../../components/responses/internal/success-end-meeting.yaml' + '400': + $ref: '../../components/responses/internal/error-invalid-participant-role.yaml' '401': $ref: '../../components/responses/unauthorized-error.yaml' '403': @@ -36,9 +39,12 @@ parameters: - $ref: '../../components/parameters/room-id-path.yaml' - $ref: '../../components/parameters/internal/participant-name.yaml' + - $ref: '../../components/parameters/internal/x-participant-role.yaml' responses: '200': $ref: '../../components/responses/internal/success-delete-participant.yaml' + '400': + $ref: '../../components/responses/internal/error-invalid-participant-role.yaml' '401': $ref: '../../components/responses/unauthorized-error.yaml' '403': diff --git a/backend/openapi/paths/internal/recordings.yaml b/backend/openapi/paths/internal/recordings.yaml index fa62849..ec92ab0 100644 --- a/backend/openapi/paths/internal/recordings.yaml +++ b/backend/openapi/paths/internal/recordings.yaml @@ -8,11 +8,15 @@ - Internal API - Recordings security: - participantTokenCookie: [] + parameters: + - $ref: '../../components/parameters/internal/x-participant-role.yaml' requestBody: $ref: '../../components/requestBodies/internal/start-recording-request.yaml' responses: '201': $ref: '../../components/responses/internal/success-start-recording.yaml' + '400': + $ref: '../../components/responses/internal/error-invalid-participant-role.yaml' '401': $ref: '../../components/responses/unauthorized-error.yaml' '403': @@ -40,9 +44,12 @@ - participantTokenCookie: [] parameters: - $ref: '../../components/parameters/recording-id.yaml' + - $ref: '../../components/parameters/internal/x-participant-role.yaml' responses: '202': $ref: '../../components/responses/internal/success-stop-recording.yaml' + '400': + $ref: '../../components/responses/internal/error-invalid-participant-role.yaml' '401': $ref: '../../components/responses/unauthorized-error.yaml' '403': diff --git a/backend/openapi/paths/internal/rooms.yaml b/backend/openapi/paths/internal/rooms.yaml index 53ee5f9..45acc75 100644 --- a/backend/openapi/paths/internal/rooms.yaml +++ b/backend/openapi/paths/internal/rooms.yaml @@ -37,9 +37,12 @@ - participantTokenCookie: [] parameters: - $ref: '../../components/parameters/room-id-path.yaml' + - $ref: '../../components/parameters/internal/x-participant-role.yaml' responses: '200': $ref: '../../components/responses/internal/success-get-room-preferences.yaml' + '400': + $ref: '../../components/responses/internal/error-invalid-participant-role.yaml' '401': $ref: '../../components/responses/unauthorized-error.yaml' '403': diff --git a/backend/openapi/paths/rooms.yaml b/backend/openapi/paths/rooms.yaml index c59e3ae..9c8a304 100644 --- a/backend/openapi/paths/rooms.yaml +++ b/backend/openapi/paths/rooms.yaml @@ -101,9 +101,12 @@ parameters: - $ref: '../components/parameters/room-id-path.yaml' - $ref: '../components/parameters/room-fields.yaml' + - $ref: '../components/parameters/internal/x-participant-role.yaml' responses: '200': $ref: '../components/responses/success-get-room.yaml' + '400': + $ref: '../components/responses/internal/error-invalid-participant-role.yaml' '401': $ref: '../components/responses/unauthorized-error.yaml' '403':