webAuthN authentication challenge and attestation endpoints added to API docs generation

Author: NickOvt

lib/api/2fa/webauthn.js

@@ -383,22 +383,68 @@ module.exports = (db, server, userHandler) => {
 
     // Get webauthn challenge
     server.post(
-        '/users/:user/2fa/webauthn/authentication-challenge',
+        {
+            path: '/users/:user/2fa/webauthn/authentication-challenge',
+            tags: ['TwoFactorAuth'],
+            summary: 'Begin WebAuthN authentication challenge',
+            description: 'This method retrieves the WebAuthN PublicKeyCredentialRequestOptions object to use it for authentication',
+            validationObjs: {
+                requestBody: {
+                    origin: Joi.string().empty('').uri().required().description('Origin domain'),
+                    authenticatorAttachment: Joi.string()
+                        .valid('platform', 'cross-platform')
+                        .example('cross-platform')
+                        .default('cross-platform')
+                        .description(
+                            'Indicates whether authenticators should be part of the OS ("platform"), or can be roaming authenticators ("cross-platform")'
+                        ),
+
+                    rpId: Joi.string().hostname().empty('').description('Relaying party ID. Domain'),
+
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                queryParams: {},
+                pathParams: { user: userId },
+                response: {
+                    200: {
+                        description: 'Success',
+                        model: Joi.object({
+                            success: successRes,
+                            authenticationOptions: Joi.object({
+                                challenge: Joi.string().hex().required().description('Challenge as hex string'),
+                                allowCredentials: Joi.array()
+                                    .items(
+                                        Joi.object({
+                                            rawId: Joi.string().hex().required().description('RawId of the credential as hex string'),
+                                            type: Joi.string().required().description('Credential type')
+                                        })
+                                    )
+                                    .required()
+                                    .description('Allowed credential(s) based on the request'),
+                                rpId: Joi.string().description('Relaying Party ID. Domain'),
+                                rawChallenge: Joi.string().description('Raw challenge bytes. ArrayBuffer'),
+                                attestation: Joi.string().description('Attestation string. `direct`/`indirect`/`none`'),
+                                extensions: Joi.object({}).description('Any credential extensions'),
+                                userVerification: Joi.string().description('User verification type. `required`/`preferred`/`discouraged`'),
+                                timeout: Joi.number().description('Timeout in milliseconds (ms)')
+                            })
+                                .required()
+                                .description('PublicKeyCredentialRequestOptions object')
+                        })
+                    }
+                }
+            }
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');
-            const schema = Joi.object().keys({
-                user: Joi.string().hex().lowercase().length(24).required(),
-                origin: Joi.string().empty('').uri().required(),
-                authenticatorAttachment: Joi.string()
-                    .valid('platform', 'cross-platform')
-                    .example('cross-platform')
-                    .default('cross-platform')
-                    .description('Indicates whether authenticators should be part of the OS ("platform"), or can be roaming authenticators ("cross-platform")'),
-
-                rpId: Joi.string().hostname().empty(''),
-
-                sess: sessSchema,
-                ip: sessIPSchema
+
+            const { pathParams, requestBody, queryParams } = req.route.spec.validationObjs;
+
+            const schema = Joi.object({
+                ...pathParams,
+                ...requestBody,
+                ...queryParams
             });
 
             const result = schema.validate(req.params, {
@@ -433,37 +479,70 @@ module.exports = (db, server, userHandler) => {
     );
 
     server.post(
-        '/users/:user/2fa/webauthn/authentication-assertion',
+        {
+            path: '/users/:user/2fa/webauthn/authentication-assertion',
+            tags: ['TwoFactorAuth'],
+            summary: 'WebAuthN authentication Assertion',
+            description: 'Assert WebAuthN authentication request and actually authenticate the user',
+            validationObjs: {
+                requestBody: {
+                    challenge: Joi.string().empty('').hex().max(2048).required().description('Challenge of the credential as hex string'),
+                    rawId: Joi.string().empty('').hex().max(2048).required().description('RawId of the credential'),
+                    clientDataJSON: Joi.string()
+                        .empty('')
+                        .hex()
+                        .max(1024 * 1024)
+                        .required()
+                        .description('Client data JSON as hex string'),
+                    authenticatorData: Joi.string()
+                        .empty('')
+                        .hex()
+                        .max(1024 * 1024)
+                        .required()
+                        .description('Authentication data as hex string'),
+
+                    signature: Joi.string()
+                        .empty('')
+                        .hex()
+                        .max(1024 * 1024)
+                        .required()
+                        .description('Private key encrypted signature to verify with public key on the server. Hex string'),
+
+                    rpId: Joi.string().hostname().empty('').description('Relaying party ID. Domain'),
+
+                    token: booleanSchema.default(false).description('If true response will contain the user auth token'),
+
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                queryParams: {},
+                pathParams: { user: userId },
+                response: {
+                    200: {
+                        description: 'Success',
+                        model: Joi.object({
+                            success: successRes,
+                            response: Joi.object({
+                                authenticated: booleanSchema.required().description('Authentication status'),
+                                credential: Joi.string().required().description('WebAuthN credential ID')
+                            })
+                                .required()
+                                .description('Auth data'),
+                            token: Joi.string().description('User auth token')
+                        })
+                    }
+                }
+            }
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');
-            const schema = Joi.object().keys({
-                user: Joi.string().hex().lowercase().length(24).required(),
-
-                challenge: Joi.string().empty('').hex().max(2048).required(),
-                rawId: Joi.string().empty('').hex().max(2048).required(),
-                clientDataJSON: Joi.string()
-                    .empty('')
-                    .hex()
-                    .max(1024 * 1024)
-                    .required(),
-                authenticatorData: Joi.string()
-                    .empty('')
-                    .hex()
-                    .max(1024 * 1024)
-                    .required(),
-
-                signature: Joi.string()
-                    .empty('')
-                    .hex()
-                    .max(1024 * 1024)
-                    .required(),
-
-                rpId: Joi.string().hostname().empty(''),
-
-                token: booleanSchema.default(false),
-
-                sess: sessSchema,
-                ip: sessIPSchema
+
+            const { pathParams, requestBody, queryParams } = req.route.spec.validationObjs;
+
+            const schema = Joi.object({
+                ...pathParams,
+                ...requestBody,
+                ...queryParams
             });
 
             const result = schema.validate(req.params, {