diff --git a/controllers/core/core.go b/controllers/core/core.go index bb70781..145ba7d 100644 --- a/controllers/core/core.go +++ b/controllers/core/core.go @@ -56,8 +56,7 @@ const JwtHeader = "jwt" // @Description Sign a user up for a new account // @Accept json // @Produce json -// @Param userkey body string true "user email" -// @Param password body string true "user password" +// @Param signup body signup true "The signup information" // @Router /signup [post] // @Success 200 // @Failure 400 "userkey missing, or password missing or not strong enough" @@ -104,9 +103,7 @@ func UserSignup() gin.HandlerFunc { // @Description Secured login for any user accounts // @Accept json // @Produce json -// @Param userkey body string true "user email" -// @Param password body string true "user password" -// @Param twofactorcode body string false "the 2fa token for the user, if activated" +// @Param login body login true "Login information" // @Router /login [post] // @Success 200 // @Failure 401 "not found or credentials invalid" @@ -165,6 +162,14 @@ func UserLogin() gin.HandlerFunc { // Parses a given JWT token and attempts to verify the `sub` in that token IFF // the token role == "verify". Verifying an already-verified user returns // a 200OK{next:"login"} without any action +// @Summary User verify +// @Description Email verification based on a token sent to a registered email +// @Accept json +// @Produce json +// @Param verify query string true "Verification JWT" +// @Router /verify [post] +// @Success 200 +// @Failure 401 "bad token" func UserVerify() gin.HandlerFunc { return func(c *gin.Context) { verifyJwt, _ := c.GetQuery("verify") @@ -222,7 +227,7 @@ func UserVerify() gin.HandlerFunc { // @Description Request a password reset for the provided userkey // @Accept json // @Produce json -// @Param userkey body string true "user email to reset" +// @Param userkey body forgotten true "email to reset" // @Router /forgot [post] // @Success 200 // @Failure 400 "userkey not provided" @@ -251,8 +256,7 @@ func UserForgotPassword() gin.HandlerFunc { // @Description Use a JWT token to validate and reset a password // @Accept json // @Produce json -// @Param token body string true "the token emailed to the user" -// @Param password body string true "the new password value" +// @Param reset body reset true "the reset token and the password" // @Router /reset [post] // @Success 200 // @Failure 400 "token and password not provided" @@ -304,13 +308,11 @@ func UserResetForgottenPassword() gin.HandlerFunc { } // Admin login functionality, similar to user login but requires 2FA to be set up. -// @Summary User login +// @Summary Admin login // @Description Secured login for any user accounts // @Accept json // @Produce json -// @Param userkey body string true "user email" -// @Param password body string true "user password" -// @Param twofactorcode body string true "the 2fa token" +// @Param login body login true "email, password and 2FA code. 2FA code is required" // @Router /admin [post] // @Success 200 // @Failure 401 "not found or credentials invalid" @@ -495,10 +497,10 @@ func StarterAdmin() gin.HandlerFunc { } // Ping functionality -// @Summary ping example -// @Description unauthenticated ping +// @Summary Unauthenticated Ping // @Product json // @Router /doot [get] +// @Success 200 func Doot() gin.HandlerFunc { return func(c *gin.Context) { piCtx, exists := c.Get("principal") @@ -512,20 +514,20 @@ func Doot() gin.HandlerFunc { } } -// @Summary ping example -// @Description user ping and login check +// @Summary User ping // @Product json // @Router /sec/doot [get] // @Param jwt header string true "JWT Cookie set by /login" +// @Success 200 func UserDoot() gin.HandlerFunc { return Doot() } -// @Summary ping example -// @Description admin ping and login check +// @Summary Admin ping // @Product json // @Router /adm/doot [get] // @Param jwt header string true "JWT Cookie set by /admin" +// @Success 200 func AdminDoot() gin.HandlerFunc { return Doot() } diff --git a/docs/docs.go b/docs/docs.go index b662b08..78daeda 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -18,8 +18,7 @@ const docTemplate = `{ "paths": { "/adm/doot": { "get": { - "description": "admin ping and login check", - "summary": "ping example", + "summary": "Admin ming", "parameters": [ { "type": "string", @@ -44,30 +43,12 @@ const docTemplate = `{ "summary": "User login", "parameters": [ { - "description": "user email", - "name": "userkey", + "description": "email, password and 2FA code. 2FA code is required", + "name": "login", "in": "body", "required": true, "schema": { - "type": "string" - } - }, - { - "description": "user password", - "name": "password", - "in": "body", - "required": true, - "schema": { - "type": "string" - } - }, - { - "description": "the 2fa token", - "name": "twofactorcode", - "in": "body", - "required": true, - "schema": { - "type": "string" + "$ref": "#/definitions/core.login" } } ], @@ -92,8 +73,7 @@ const docTemplate = `{ }, "/doot": { "get": { - "description": "unauthenticated ping", - "summary": "ping example", + "summary": "Unauthenticated Ping", "responses": {} } }, @@ -109,12 +89,12 @@ const docTemplate = `{ "summary": "Forgot password", "parameters": [ { - "description": "user email to reset", + "description": "email to reset", "name": "userkey", "in": "body", "required": true, "schema": { - "type": "string" + "$ref": "#/definitions/core.forgotten" } } ], @@ -140,29 +120,12 @@ const docTemplate = `{ "summary": "User login", "parameters": [ { - "description": "user email", - "name": "userkey", + "description": "Login information", + "name": "login", "in": "body", "required": true, "schema": { - "type": "string" - } - }, - { - "description": "user password", - "name": "password", - "in": "body", - "required": true, - "schema": { - "type": "string" - } - }, - { - "description": "the 2fa token for the user, if activated", - "name": "twofactorcode", - "in": "body", - "schema": { - "type": "string" + "$ref": "#/definitions/core.login" } } ], @@ -197,21 +160,12 @@ const docTemplate = `{ "summary": "Password reset", "parameters": [ { - "description": "the token emailed to the user", - "name": "token", + "description": "the reset token and the password", + "name": "reset", "in": "body", "required": true, "schema": { - "type": "string" - } - }, - { - "description": "the new password value", - "name": "password", - "in": "body", - "required": true, - "schema": { - "type": "string" + "$ref": "#/definitions/core.reset" } } ], @@ -230,8 +184,7 @@ const docTemplate = `{ }, "/sec/doot": { "get": { - "description": "user ping and login check", - "summary": "ping example", + "summary": "User ping", "parameters": [ { "type": "string", @@ -256,21 +209,12 @@ const docTemplate = `{ "summary": "User signup", "parameters": [ { - "description": "user email", - "name": "userkey", + "description": "The signup information", + "name": "signup", "in": "body", "required": true, "schema": { - "type": "string" - } - }, - { - "description": "user password", - "name": "password", - "in": "body", - "required": true, - "schema": { - "type": "string" + "$ref": "#/definitions/core.signup" } } ], @@ -283,6 +227,96 @@ const docTemplate = `{ } } } + }, + "/verify": { + "post": { + "description": "Email verification based on a token sent to a registered email", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "summary": "User verify", + "parameters": [ + { + "type": "string", + "description": "Verification JWT", + "name": "verify", + "in": "query", + "required": true + } + ], + "responses": { + "200": { + "description": "" + }, + "401": { + "description": "bad token" + } + } + } + } + }, + "definitions": { + "core.forgotten": { + "type": "object", + "required": [ + "userkey" + ], + "properties": { + "userkey": { + "type": "string" + } + } + }, + "core.login": { + "type": "object", + "required": [ + "password", + "userkey" + ], + "properties": { + "password": { + "type": "string" + }, + "twofactorcode": { + "type": "string" + }, + "userkey": { + "type": "string" + } + } + }, + "core.reset": { + "type": "object", + "required": [ + "password", + "token" + ], + "properties": { + "password": { + "type": "string" + }, + "token": { + "type": "string" + } + } + }, + "core.signup": { + "type": "object", + "required": [ + "password", + "userkey" + ], + "properties": { + "password": { + "type": "string" + }, + "userkey": { + "type": "string" + } + } } } }` diff --git a/docs/swagger.json b/docs/swagger.json index e94ff96..b032fc8 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -9,8 +9,7 @@ "paths": { "/adm/doot": { "get": { - "description": "admin ping and login check", - "summary": "ping example", + "summary": "Admin ming", "parameters": [ { "type": "string", @@ -35,30 +34,12 @@ "summary": "User login", "parameters": [ { - "description": "user email", - "name": "userkey", + "description": "email, password and 2FA code. 2FA code is required", + "name": "login", "in": "body", "required": true, "schema": { - "type": "string" - } - }, - { - "description": "user password", - "name": "password", - "in": "body", - "required": true, - "schema": { - "type": "string" - } - }, - { - "description": "the 2fa token", - "name": "twofactorcode", - "in": "body", - "required": true, - "schema": { - "type": "string" + "$ref": "#/definitions/core.login" } } ], @@ -83,8 +64,7 @@ }, "/doot": { "get": { - "description": "unauthenticated ping", - "summary": "ping example", + "summary": "Unauthenticated Ping", "responses": {} } }, @@ -100,12 +80,12 @@ "summary": "Forgot password", "parameters": [ { - "description": "user email to reset", + "description": "email to reset", "name": "userkey", "in": "body", "required": true, "schema": { - "type": "string" + "$ref": "#/definitions/core.forgotten" } } ], @@ -131,29 +111,12 @@ "summary": "User login", "parameters": [ { - "description": "user email", - "name": "userkey", + "description": "Login information", + "name": "login", "in": "body", "required": true, "schema": { - "type": "string" - } - }, - { - "description": "user password", - "name": "password", - "in": "body", - "required": true, - "schema": { - "type": "string" - } - }, - { - "description": "the 2fa token for the user, if activated", - "name": "twofactorcode", - "in": "body", - "schema": { - "type": "string" + "$ref": "#/definitions/core.login" } } ], @@ -188,21 +151,12 @@ "summary": "Password reset", "parameters": [ { - "description": "the token emailed to the user", - "name": "token", + "description": "the reset token and the password", + "name": "reset", "in": "body", "required": true, "schema": { - "type": "string" - } - }, - { - "description": "the new password value", - "name": "password", - "in": "body", - "required": true, - "schema": { - "type": "string" + "$ref": "#/definitions/core.reset" } } ], @@ -221,8 +175,7 @@ }, "/sec/doot": { "get": { - "description": "user ping and login check", - "summary": "ping example", + "summary": "User ping", "parameters": [ { "type": "string", @@ -247,21 +200,12 @@ "summary": "User signup", "parameters": [ { - "description": "user email", - "name": "userkey", + "description": "The signup information", + "name": "signup", "in": "body", "required": true, "schema": { - "type": "string" - } - }, - { - "description": "user password", - "name": "password", - "in": "body", - "required": true, - "schema": { - "type": "string" + "$ref": "#/definitions/core.signup" } } ], @@ -274,6 +218,96 @@ } } } + }, + "/verify": { + "post": { + "description": "Email verification based on a token sent to a registered email", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "summary": "User verify", + "parameters": [ + { + "type": "string", + "description": "Verification JWT", + "name": "verify", + "in": "query", + "required": true + } + ], + "responses": { + "200": { + "description": "" + }, + "401": { + "description": "bad token" + } + } + } + } + }, + "definitions": { + "core.forgotten": { + "type": "object", + "required": [ + "userkey" + ], + "properties": { + "userkey": { + "type": "string" + } + } + }, + "core.login": { + "type": "object", + "required": [ + "password", + "userkey" + ], + "properties": { + "password": { + "type": "string" + }, + "twofactorcode": { + "type": "string" + }, + "userkey": { + "type": "string" + } + } + }, + "core.reset": { + "type": "object", + "required": [ + "password", + "token" + ], + "properties": { + "password": { + "type": "string" + }, + "token": { + "type": "string" + } + } + }, + "core.signup": { + "type": "object", + "required": [ + "password", + "userkey" + ], + "properties": { + "password": { + "type": "string" + }, + "userkey": { + "type": "string" + } + } } } } \ No newline at end of file diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 18f357a..7f3b50c 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -1,4 +1,44 @@ basePath: /v1 +definitions: + core.forgotten: + properties: + userkey: + type: string + required: + - userkey + type: object + core.login: + properties: + password: + type: string + twofactorcode: + type: string + userkey: + type: string + required: + - password + - userkey + type: object + core.reset: + properties: + password: + type: string + token: + type: string + required: + - password + - token + type: object + core.signup: + properties: + password: + type: string + userkey: + type: string + required: + - password + - userkey + type: object info: contact: {} title: Go-Gin Prepack @@ -6,7 +46,6 @@ info: paths: /adm/doot: get: - description: admin ping and login check parameters: - description: JWT Cookie set by /admin in: header @@ -14,31 +53,19 @@ paths: required: true type: string responses: {} - summary: ping example + summary: Admin ming /admin: post: consumes: - application/json description: Secured login for any user accounts parameters: - - description: user email + - description: email, password and 2FA code. 2FA code is required in: body - name: userkey + name: login required: true schema: - type: string - - description: user password - in: body - name: password - required: true - schema: - type: string - - description: the 2fa token - in: body - name: twofactorcode - required: true - schema: - type: string + $ref: '#/definitions/core.login' produces: - application/json responses: @@ -55,21 +82,20 @@ paths: summary: User login /doot: get: - description: unauthenticated ping responses: {} - summary: ping example + summary: Unauthenticated Ping /forgot: post: consumes: - application/json description: Request a password reset for the provided userkey parameters: - - description: user email to reset + - description: email to reset in: body name: userkey required: true schema: - type: string + $ref: '#/definitions/core.forgotten' produces: - application/json responses: @@ -84,23 +110,12 @@ paths: - application/json description: Secured login for any user accounts parameters: - - description: user email + - description: Login information in: body - name: userkey + name: login required: true schema: - type: string - - description: user password - in: body - name: password - required: true - schema: - type: string - - description: the 2fa token for the user, if activated - in: body - name: twofactorcode - schema: - type: string + $ref: '#/definitions/core.login' produces: - application/json responses: @@ -121,18 +136,12 @@ paths: - application/json description: Use a JWT token to validate and reset a password parameters: - - description: the token emailed to the user + - description: the reset token and the password in: body - name: token + name: reset required: true schema: - type: string - - description: the new password value - in: body - name: password - required: true - schema: - type: string + $ref: '#/definitions/core.reset' produces: - application/json responses: @@ -145,7 +154,6 @@ paths: summary: Password reset /sec/doot: get: - description: user ping and login check parameters: - description: JWT Cookie set by /login in: header @@ -153,25 +161,19 @@ paths: required: true type: string responses: {} - summary: ping example + summary: User ping /signup: post: consumes: - application/json description: Sign a user up for a new account parameters: - - description: user email + - description: The signup information in: body - name: userkey + name: signup required: true schema: - type: string - - description: user password - in: body - name: password - required: true - schema: - type: string + $ref: '#/definitions/core.signup' produces: - application/json responses: @@ -180,4 +182,23 @@ paths: "400": description: userkey missing, or password missing or not strong enough summary: User signup + /verify: + post: + consumes: + - application/json + description: Email verification based on a token sent to a registered email + parameters: + - description: Verification JWT + in: query + name: verify + required: true + type: string + produces: + - application/json + responses: + "200": + description: "" + "401": + description: bad token + summary: User verify swagger: "2.0"