acebase-server 1.7.0 → 1.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +6 -4
- package/src/acebase-server.js +94 -52
- package/src/routes/docs.js +97 -0
- package/src/ts/routes/auth-change-password.yaml +76 -0
- package/src/ts/routes/auth-delete.yaml +78 -0
- package/src/ts/routes/auth-forgot-password.yaml +50 -0
- package/src/ts/routes/auth-reset-password.yaml +54 -0
- package/src/ts/routes/auth-signin.yaml +130 -0
- package/src/ts/routes/auth-signout.yaml +46 -0
- package/src/ts/routes/auth-signup.yaml +121 -0
- package/src/ts/routes/auth-state.yaml +29 -0
- package/src/ts/routes/auth-update.yaml +132 -0
- package/src/ts/routes/auth-verify-email.yaml +53 -0
- package/src/ts/routes/docs.ts +100 -0
- package/src/ts/routes/oauth2-init.yaml +63 -0
- package/src/ts/routes/oauth2-refresh.yaml +65 -0
- package/src/ts/routes/oauth2-signin.yaml +66 -0
- package/src/webmanager/index.html +1 -1
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/auth/{dbname}/signin:
|
|
2
|
+
post:
|
|
3
|
+
tags:
|
|
4
|
+
- auth
|
|
5
|
+
summary: Sign in a user
|
|
6
|
+
description: Signs in an existing user
|
|
7
|
+
parameters:
|
|
8
|
+
- name: dbname
|
|
9
|
+
in: path
|
|
10
|
+
description: name of the database
|
|
11
|
+
required: true
|
|
12
|
+
schema:
|
|
13
|
+
type: string
|
|
14
|
+
example: mydb
|
|
15
|
+
requestBody:
|
|
16
|
+
description: sign in details
|
|
17
|
+
content:
|
|
18
|
+
'application/json':
|
|
19
|
+
schema:
|
|
20
|
+
oneOf:
|
|
21
|
+
- type: object
|
|
22
|
+
properties:
|
|
23
|
+
client_id:
|
|
24
|
+
description: ID of the connected websocket
|
|
25
|
+
type: string
|
|
26
|
+
method:
|
|
27
|
+
description: Method of authentication (email)
|
|
28
|
+
type: string
|
|
29
|
+
value: email
|
|
30
|
+
email:
|
|
31
|
+
description: User email address
|
|
32
|
+
type: string
|
|
33
|
+
password:
|
|
34
|
+
description: Password
|
|
35
|
+
type: string
|
|
36
|
+
format: password
|
|
37
|
+
required:
|
|
38
|
+
- method
|
|
39
|
+
- email
|
|
40
|
+
- password
|
|
41
|
+
example:
|
|
42
|
+
method: email
|
|
43
|
+
email: user@example.com
|
|
44
|
+
password: sup3rs3cr3t
|
|
45
|
+
- type: object
|
|
46
|
+
properties:
|
|
47
|
+
client_id:
|
|
48
|
+
description: ID of the connected websocket
|
|
49
|
+
type: string
|
|
50
|
+
method:
|
|
51
|
+
description: Method of authentication (username)
|
|
52
|
+
type: string
|
|
53
|
+
value: username
|
|
54
|
+
username:
|
|
55
|
+
description: Username
|
|
56
|
+
type: string
|
|
57
|
+
password:
|
|
58
|
+
description: Password
|
|
59
|
+
type: string
|
|
60
|
+
format: password
|
|
61
|
+
required:
|
|
62
|
+
- method
|
|
63
|
+
- username
|
|
64
|
+
- password
|
|
65
|
+
example:
|
|
66
|
+
method: username
|
|
67
|
+
username: user
|
|
68
|
+
password: sup3rs3cr3t
|
|
69
|
+
- type: object
|
|
70
|
+
properties:
|
|
71
|
+
client_id:
|
|
72
|
+
type: string
|
|
73
|
+
description: ID of the connected websocket
|
|
74
|
+
method:
|
|
75
|
+
type: string
|
|
76
|
+
value: token
|
|
77
|
+
description: Method of authentication (token)
|
|
78
|
+
token:
|
|
79
|
+
type: string
|
|
80
|
+
description: Previously acquired access token to sign in with
|
|
81
|
+
required:
|
|
82
|
+
- method
|
|
83
|
+
- token
|
|
84
|
+
example:
|
|
85
|
+
method: token
|
|
86
|
+
token: ewufh387f3fyubqwekrjbcqwkuiec7gq3euyfbqwkuyebqjk..
|
|
87
|
+
responses:
|
|
88
|
+
200:
|
|
89
|
+
description: When signin succeeds, it returns an object with the result
|
|
90
|
+
content:
|
|
91
|
+
'application/json':
|
|
92
|
+
schema:
|
|
93
|
+
type: object
|
|
94
|
+
properties:
|
|
95
|
+
access_token:
|
|
96
|
+
description: The access token that provides access to API calls that require authentication. This access token should be added to the Authorization header of those requests. The token is allowed to be cached by the client to sign in witht the token method later
|
|
97
|
+
type: string
|
|
98
|
+
example: ewufh387f3fyubqwekrjbcqwkuiec7gq3euyfbqwkuyebqjk..
|
|
99
|
+
user:
|
|
100
|
+
$ref: '#/components/schemas/User'
|
|
101
|
+
401:
|
|
102
|
+
description: When the sent request details are incorrect, this "401 Unauthorized" is returned
|
|
103
|
+
content:
|
|
104
|
+
'application/json':
|
|
105
|
+
schema:
|
|
106
|
+
type: object
|
|
107
|
+
properties:
|
|
108
|
+
code:
|
|
109
|
+
type: string
|
|
110
|
+
description: The exact error code
|
|
111
|
+
enum:
|
|
112
|
+
- invalid_token
|
|
113
|
+
- not_found
|
|
114
|
+
- duplicate
|
|
115
|
+
- token_mismatch
|
|
116
|
+
- wrong_password
|
|
117
|
+
example: not_found
|
|
118
|
+
message:
|
|
119
|
+
type: string
|
|
120
|
+
description: Description of the error
|
|
121
|
+
example: Incorrect email
|
|
122
|
+
example:
|
|
123
|
+
code: wrong_password
|
|
124
|
+
message: Incorrect password
|
|
125
|
+
500:
|
|
126
|
+
description: An unenexpected error occurred on the server
|
|
127
|
+
content:
|
|
128
|
+
'application/json':
|
|
129
|
+
schema:
|
|
130
|
+
$ref: '#/components/schemas/UnexpectedError'
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/auth/{dbname}/signout:
|
|
2
|
+
post:
|
|
3
|
+
tags:
|
|
4
|
+
- auth
|
|
5
|
+
summary: Sign out current user
|
|
6
|
+
description: Signs out the currently signed in user
|
|
7
|
+
parameters:
|
|
8
|
+
- name: dbname
|
|
9
|
+
in: path
|
|
10
|
+
description: name of the database
|
|
11
|
+
required: true
|
|
12
|
+
schema:
|
|
13
|
+
type: string
|
|
14
|
+
example: mydb
|
|
15
|
+
requestBody:
|
|
16
|
+
description: Sign out details
|
|
17
|
+
content:
|
|
18
|
+
'application/json':
|
|
19
|
+
schema:
|
|
20
|
+
type: object
|
|
21
|
+
properties:
|
|
22
|
+
client_id:
|
|
23
|
+
type: string
|
|
24
|
+
description: ID of the connected websocket
|
|
25
|
+
everywhere:
|
|
26
|
+
type: boolean
|
|
27
|
+
description: Whether the user should sign out on ALL clients
|
|
28
|
+
example:
|
|
29
|
+
client_id: x8WIv7-mJelg7on_ALbx
|
|
30
|
+
everywhere: false
|
|
31
|
+
responses:
|
|
32
|
+
200:
|
|
33
|
+
description: Returns `"Bye!"` if signout is successful
|
|
34
|
+
content:
|
|
35
|
+
'text/plain':
|
|
36
|
+
schema:
|
|
37
|
+
type: string
|
|
38
|
+
value: Bye!
|
|
39
|
+
example: Bye!
|
|
40
|
+
500:
|
|
41
|
+
description: Returns an object describing an unexpected error
|
|
42
|
+
content:
|
|
43
|
+
'application/json':
|
|
44
|
+
schema:
|
|
45
|
+
$ref: '#/components/schemas/Error'
|
|
46
|
+
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
/auth/{dbname}/signup:
|
|
2
|
+
post:
|
|
3
|
+
tags:
|
|
4
|
+
- auth
|
|
5
|
+
summary: Create a new user
|
|
6
|
+
description: Signs up a new user (must be enabled in the server config)
|
|
7
|
+
parameters:
|
|
8
|
+
- name: dbname
|
|
9
|
+
in: path
|
|
10
|
+
description: name of the database
|
|
11
|
+
required: true
|
|
12
|
+
schema:
|
|
13
|
+
type: string
|
|
14
|
+
example: mydb
|
|
15
|
+
requestBody:
|
|
16
|
+
description: new user details
|
|
17
|
+
content:
|
|
18
|
+
'application/json':
|
|
19
|
+
schema:
|
|
20
|
+
type: object
|
|
21
|
+
properties:
|
|
22
|
+
username:
|
|
23
|
+
type: string
|
|
24
|
+
description: Requested username (optional if `email` provided)
|
|
25
|
+
email:
|
|
26
|
+
type: string
|
|
27
|
+
description: Email address (optional if `username` provided)
|
|
28
|
+
displayName:
|
|
29
|
+
type: string
|
|
30
|
+
description: Name of the user for public displaying purposes. Consider this a real name, alias or handle
|
|
31
|
+
password:
|
|
32
|
+
type: string
|
|
33
|
+
format: password
|
|
34
|
+
description: Password to set for the account
|
|
35
|
+
settings:
|
|
36
|
+
type: object
|
|
37
|
+
otherProperties: true
|
|
38
|
+
desciption: (optional) miscellanious other info to store with the user account
|
|
39
|
+
required:
|
|
40
|
+
- username
|
|
41
|
+
- email
|
|
42
|
+
- displayName
|
|
43
|
+
- password
|
|
44
|
+
example:
|
|
45
|
+
email: user@example.com
|
|
46
|
+
displayName: Real Name
|
|
47
|
+
password: sup3rs3cr3t
|
|
48
|
+
responses:
|
|
49
|
+
200:
|
|
50
|
+
description: When signup succeeds, it returns an object with the result
|
|
51
|
+
content:
|
|
52
|
+
'application/json':
|
|
53
|
+
schema:
|
|
54
|
+
type: object
|
|
55
|
+
properties:
|
|
56
|
+
access_token:
|
|
57
|
+
description: The access token that provides access to API calls that require authentication. This access token should be added to the Authorization header of those requests. The token is allowed to be cached by the client to sign in witht the token method later
|
|
58
|
+
type: string
|
|
59
|
+
example: ewufh387f3fyubqwekrjbcqwkuiec7gq3euyfbqwkuyebqjk..
|
|
60
|
+
user:
|
|
61
|
+
$ref: '#/components/schemas/User'
|
|
62
|
+
403:
|
|
63
|
+
description: If user signup is disabled in the server config, only the admin user can create new accounts and `"403 Forbidden"` is returned
|
|
64
|
+
content:
|
|
65
|
+
'application/json':
|
|
66
|
+
schema:
|
|
67
|
+
type: object
|
|
68
|
+
properties:
|
|
69
|
+
code:
|
|
70
|
+
type: string
|
|
71
|
+
value: admin_only
|
|
72
|
+
message:
|
|
73
|
+
type: string
|
|
74
|
+
value: Only admin is allowed to create users
|
|
75
|
+
example:
|
|
76
|
+
code: admin_only
|
|
77
|
+
message: Only admin is allowed to create users
|
|
78
|
+
409:
|
|
79
|
+
description: An account with the same username or email address exists already
|
|
80
|
+
content:
|
|
81
|
+
'application/json':
|
|
82
|
+
schema:
|
|
83
|
+
type: object
|
|
84
|
+
properties:
|
|
85
|
+
code:
|
|
86
|
+
type: string
|
|
87
|
+
value: conflict
|
|
88
|
+
message:
|
|
89
|
+
type: string
|
|
90
|
+
value: Account with username and/or email already exists
|
|
91
|
+
422:
|
|
92
|
+
description: When the sent request details are incorrect, `"422 Unprocessable Entity"` is returned
|
|
93
|
+
content:
|
|
94
|
+
'application/json':
|
|
95
|
+
schema:
|
|
96
|
+
type: object
|
|
97
|
+
properties:
|
|
98
|
+
code:
|
|
99
|
+
type: string
|
|
100
|
+
description: The exact error code
|
|
101
|
+
enum:
|
|
102
|
+
- missing_details
|
|
103
|
+
- invalid_email
|
|
104
|
+
- invalid_username
|
|
105
|
+
- invalid_display_name
|
|
106
|
+
- invalid_password
|
|
107
|
+
- invalid_settings
|
|
108
|
+
example: missing_details
|
|
109
|
+
message:
|
|
110
|
+
type: string
|
|
111
|
+
description: Description of the error
|
|
112
|
+
example: No username or email provided
|
|
113
|
+
example:
|
|
114
|
+
code: invalid_password
|
|
115
|
+
message: Invalid password, must be at least 8 characters and cannot contain spaces
|
|
116
|
+
500:
|
|
117
|
+
description: An unenexpected error occurred on the server
|
|
118
|
+
content:
|
|
119
|
+
'application/json':
|
|
120
|
+
schema:
|
|
121
|
+
$ref: '#/components/schemas/UnexpectedError'
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/auth/{dbname}/state:
|
|
2
|
+
get:
|
|
3
|
+
tags:
|
|
4
|
+
- auth
|
|
5
|
+
summary: Get authentication state
|
|
6
|
+
description: Gets current auth state
|
|
7
|
+
parameters:
|
|
8
|
+
- name: dbname
|
|
9
|
+
in: path
|
|
10
|
+
description: name of the database
|
|
11
|
+
required: true
|
|
12
|
+
schema:
|
|
13
|
+
type: string
|
|
14
|
+
example: mydb
|
|
15
|
+
responses:
|
|
16
|
+
200:
|
|
17
|
+
description: returns whether the request was authenticated and by which user (determined by the sent Authorization header)
|
|
18
|
+
content:
|
|
19
|
+
'application/json':
|
|
20
|
+
schema:
|
|
21
|
+
type: object
|
|
22
|
+
properties:
|
|
23
|
+
signed_in:
|
|
24
|
+
type: boolean
|
|
25
|
+
example: true
|
|
26
|
+
user:
|
|
27
|
+
$ref: '#/components/schemas/User'
|
|
28
|
+
required:
|
|
29
|
+
- signed_in
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
/auth/{dbname}/update:
|
|
2
|
+
post:
|
|
3
|
+
tags:
|
|
4
|
+
- auth
|
|
5
|
+
summary: Update user details
|
|
6
|
+
description: Updates user account details
|
|
7
|
+
parameters:
|
|
8
|
+
- name: dbname
|
|
9
|
+
in: path
|
|
10
|
+
description: name of the database
|
|
11
|
+
required: true
|
|
12
|
+
schema:
|
|
13
|
+
type: string
|
|
14
|
+
example: mydb
|
|
15
|
+
requestBody:
|
|
16
|
+
description: user details to update
|
|
17
|
+
content:
|
|
18
|
+
'application/json':
|
|
19
|
+
schema:
|
|
20
|
+
type: object
|
|
21
|
+
properties:
|
|
22
|
+
uid:
|
|
23
|
+
type: string
|
|
24
|
+
description: (admin user only) to change a user's account settings, the target account `uid` must be passed with the request
|
|
25
|
+
is_disabled:
|
|
26
|
+
type: boolean
|
|
27
|
+
description: (admin user only) whether the target account should be disabled to enable/disable signin
|
|
28
|
+
email:
|
|
29
|
+
type: string
|
|
30
|
+
description: New email address
|
|
31
|
+
username:
|
|
32
|
+
type: string
|
|
33
|
+
description: New username
|
|
34
|
+
display_name:
|
|
35
|
+
type: string
|
|
36
|
+
description: Name of the user for public displaying purposes. Consider this a real name, alias or handle. (NOTE this property is called `displayName` in the signup endpoint, both will be allowed to be used from acebase-server v1.8.1)
|
|
37
|
+
picture:
|
|
38
|
+
type: object
|
|
39
|
+
properties:
|
|
40
|
+
url:
|
|
41
|
+
type: string
|
|
42
|
+
width:
|
|
43
|
+
type: number
|
|
44
|
+
height:
|
|
45
|
+
type: number
|
|
46
|
+
example:
|
|
47
|
+
url: https://my.profile.pic/me.jpg
|
|
48
|
+
width: 500
|
|
49
|
+
height: 500
|
|
50
|
+
settings:
|
|
51
|
+
type: object
|
|
52
|
+
otherProperties: true
|
|
53
|
+
desciption: (optional) miscellanious other info to store with the user account
|
|
54
|
+
required:
|
|
55
|
+
- username
|
|
56
|
+
- email
|
|
57
|
+
- displayName
|
|
58
|
+
- password
|
|
59
|
+
responses:
|
|
60
|
+
200:
|
|
61
|
+
description: When update succeeds, it returns an object with the new user details
|
|
62
|
+
content:
|
|
63
|
+
'application/json':
|
|
64
|
+
schema:
|
|
65
|
+
type: object
|
|
66
|
+
properties:
|
|
67
|
+
user:
|
|
68
|
+
$ref: '#/components/schemas/User'
|
|
69
|
+
401:
|
|
70
|
+
description: If this is an unauthenticated request (not signed in), `"401 Unauthorized"` is returned
|
|
71
|
+
content:
|
|
72
|
+
'application/json':
|
|
73
|
+
schema:
|
|
74
|
+
type: object
|
|
75
|
+
properties:
|
|
76
|
+
code:
|
|
77
|
+
type: string
|
|
78
|
+
value: unauthenticated_update
|
|
79
|
+
message:
|
|
80
|
+
type: string
|
|
81
|
+
value: Sign in to change details
|
|
82
|
+
example:
|
|
83
|
+
code: unauthenticated_update
|
|
84
|
+
message: Sign in to change details
|
|
85
|
+
403:
|
|
86
|
+
description: If a non-admin user tries to update a user's account details, `"403 Forbidden"` is returned
|
|
87
|
+
content:
|
|
88
|
+
'application/json':
|
|
89
|
+
schema:
|
|
90
|
+
type: object
|
|
91
|
+
properties:
|
|
92
|
+
code:
|
|
93
|
+
type: string
|
|
94
|
+
value: unauthorized_update
|
|
95
|
+
message:
|
|
96
|
+
type: string
|
|
97
|
+
value: You are not authorized to perform this update. This attempt has been logged.
|
|
98
|
+
example:
|
|
99
|
+
code: unauthorized_update
|
|
100
|
+
message: You are not authorized to perform this update. This attempt has been logged.
|
|
101
|
+
422:
|
|
102
|
+
description: When the sent request details are incorrect, this "422 Unprocessable Entity" is returned
|
|
103
|
+
content:
|
|
104
|
+
'application/json':
|
|
105
|
+
schema:
|
|
106
|
+
type: object
|
|
107
|
+
properties:
|
|
108
|
+
code:
|
|
109
|
+
type: string
|
|
110
|
+
description: The exact error code
|
|
111
|
+
enum:
|
|
112
|
+
- invalid_email
|
|
113
|
+
- email_conflict
|
|
114
|
+
- invalid_username
|
|
115
|
+
- username_conflict
|
|
116
|
+
- invalid_display_name
|
|
117
|
+
- invalid_picture
|
|
118
|
+
- invalid_settings
|
|
119
|
+
example: missing_details
|
|
120
|
+
message:
|
|
121
|
+
type: string
|
|
122
|
+
description: Description of the error
|
|
123
|
+
example: Account with email address exists already
|
|
124
|
+
example:
|
|
125
|
+
code: username_conflict
|
|
126
|
+
message: Account with username exists already
|
|
127
|
+
500:
|
|
128
|
+
description: An unenexpected error occurred on the server
|
|
129
|
+
content:
|
|
130
|
+
'application/json':
|
|
131
|
+
schema:
|
|
132
|
+
$ref: '#/components/schemas/UnexpectedError'
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/auth/{dbname}/verify_email:
|
|
2
|
+
post:
|
|
3
|
+
tags:
|
|
4
|
+
- auth
|
|
5
|
+
summary: Verifies an email address
|
|
6
|
+
description: Verifies an email address with a code sent through their email address
|
|
7
|
+
parameters:
|
|
8
|
+
- name: dbname
|
|
9
|
+
in: path
|
|
10
|
+
description: name of the database
|
|
11
|
+
required: true
|
|
12
|
+
schema:
|
|
13
|
+
type: string
|
|
14
|
+
example: mydb
|
|
15
|
+
requestBody:
|
|
16
|
+
description: verification object
|
|
17
|
+
content:
|
|
18
|
+
'application/json':
|
|
19
|
+
schema:
|
|
20
|
+
type: object
|
|
21
|
+
properties:
|
|
22
|
+
code:
|
|
23
|
+
type: string
|
|
24
|
+
description: Verification code that was sent to the user's email address
|
|
25
|
+
required:
|
|
26
|
+
- code
|
|
27
|
+
example:
|
|
28
|
+
code: ewrg235235g23gwrvsdb34g524rvqewwrv425gervqew...
|
|
29
|
+
responses:
|
|
30
|
+
200:
|
|
31
|
+
description: If the email address is successfully verified, returns the string `"OK"`
|
|
32
|
+
content:
|
|
33
|
+
'text/plain':
|
|
34
|
+
schema:
|
|
35
|
+
type: 'string'
|
|
36
|
+
value: OK
|
|
37
|
+
example: OK
|
|
38
|
+
description: The string `"OK"`
|
|
39
|
+
401:
|
|
40
|
+
description: Returns a `"401 Bad Request"` if the code sent with the request is invalid
|
|
41
|
+
content:
|
|
42
|
+
'application/json':
|
|
43
|
+
schema:
|
|
44
|
+
$ref: '#/components/schemas/Error'
|
|
45
|
+
example:
|
|
46
|
+
code: invalid_code
|
|
47
|
+
message: Invalid token
|
|
48
|
+
500:
|
|
49
|
+
description: An unexpected error occurred
|
|
50
|
+
content:
|
|
51
|
+
'application/json':
|
|
52
|
+
schema:
|
|
53
|
+
$ref: '#/components/schemas/UnexpectedError'
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import { Express } from 'express';
|
|
2
|
+
import path = require('path');
|
|
3
|
+
import * as swaggerJsdoc from 'swagger-jsdoc';
|
|
4
|
+
import * as swaggerUi from 'swagger-ui-express';
|
|
5
|
+
// import config from '../config';
|
|
6
|
+
|
|
7
|
+
const addRoute = (app: Express) => {
|
|
8
|
+
// Generate docs from all yaml files
|
|
9
|
+
const options:swaggerJsdoc.Options = {
|
|
10
|
+
definition: {
|
|
11
|
+
openapi: '3.0.0',
|
|
12
|
+
info: {
|
|
13
|
+
title: 'AceBase Server API',
|
|
14
|
+
description: 'AceBase Server API',
|
|
15
|
+
version: '1.0.0',
|
|
16
|
+
contact: {
|
|
17
|
+
name: 'Ewout Stortenbeker',
|
|
18
|
+
email: 'me@appy.one'
|
|
19
|
+
},
|
|
20
|
+
// servers: [`http://${config.server.host}:${config.server.port}`]
|
|
21
|
+
},
|
|
22
|
+
tags: [{
|
|
23
|
+
name: 'auth',
|
|
24
|
+
description: 'User authentication endpoints'
|
|
25
|
+
}, {
|
|
26
|
+
name: 'oauth2',
|
|
27
|
+
description: 'User authentication using 3rd party OAuth2 providers'
|
|
28
|
+
}],
|
|
29
|
+
components: {
|
|
30
|
+
securitySchemes: {
|
|
31
|
+
bearerAuth: {
|
|
32
|
+
type: 'http',
|
|
33
|
+
scheme: 'bearer',
|
|
34
|
+
bearerFormat: 'token' // switch to JWT in the future?
|
|
35
|
+
}
|
|
36
|
+
},
|
|
37
|
+
schemas: {
|
|
38
|
+
User: {
|
|
39
|
+
type: 'object',
|
|
40
|
+
properties: {
|
|
41
|
+
uid: { type: 'string', example: 'jpx0k53u0002ecr7s354c51l' },
|
|
42
|
+
username: { type: 'string', example: 'someuser' },
|
|
43
|
+
email: { type: 'string', example: 'email@domain.com' },
|
|
44
|
+
displayName: { type: 'string', example: 'Some User' },
|
|
45
|
+
picture: {
|
|
46
|
+
type: 'object',
|
|
47
|
+
properties: {
|
|
48
|
+
width: { type: 'number', example: 500 },
|
|
49
|
+
height: { type: 'number', example: 500 },
|
|
50
|
+
url: { type: 'string', example: 'https://profile.pic/user.jpg' }
|
|
51
|
+
}
|
|
52
|
+
},
|
|
53
|
+
emailVerified: { type: 'boolean', example: true },
|
|
54
|
+
created: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
|
|
55
|
+
prevSignin: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
|
|
56
|
+
prevSigninIp: { type: 'string', example: '127.0.0.1' },
|
|
57
|
+
lastSignin: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
|
|
58
|
+
lastSigninIp: { type: 'string', example: '127.0.0.1' },
|
|
59
|
+
changePassword: { type: 'boolean', example: false },
|
|
60
|
+
changePasswordRequested: { type: 'boolean', example: false },
|
|
61
|
+
changePasswordBefore: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
|
|
62
|
+
settings: { type: 'object' }
|
|
63
|
+
}
|
|
64
|
+
},
|
|
65
|
+
Error: {
|
|
66
|
+
type: 'object',
|
|
67
|
+
properties: {
|
|
68
|
+
code: { type: 'string', description: 'error code', example: 'invalid_request' },
|
|
69
|
+
message: { type: 'string', description: 'The error message', example: 'Invalid request for this endpoint' }
|
|
70
|
+
}
|
|
71
|
+
},
|
|
72
|
+
UnexpectedError: {
|
|
73
|
+
type: 'object',
|
|
74
|
+
properties: {
|
|
75
|
+
code: { type: 'string', value: 'unexpected', description: 'The string `"unexpected"`' },
|
|
76
|
+
message: { type: 'string', description: 'The server error message' }
|
|
77
|
+
}
|
|
78
|
+
},
|
|
79
|
+
UnknownError: {
|
|
80
|
+
type: 'object',
|
|
81
|
+
properties: {
|
|
82
|
+
code: { type: 'string', value: 'unknown', description: 'The string `"unknown"`' },
|
|
83
|
+
message: { type: 'string', description: 'The server error message' }
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
},
|
|
88
|
+
security: [
|
|
89
|
+
// Enable bearer auth globally
|
|
90
|
+
{ bearerAuth: [] }
|
|
91
|
+
],
|
|
92
|
+
},
|
|
93
|
+
apis: [path.resolve(__dirname, '../ts/routes/*.yaml')]
|
|
94
|
+
};
|
|
95
|
+
|
|
96
|
+
const swaggerDocs = swaggerJsdoc(options);
|
|
97
|
+
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
export default addRoute;
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/oauth2/{dbname}/init:
|
|
2
|
+
get:
|
|
3
|
+
tags:
|
|
4
|
+
- auth
|
|
5
|
+
- oauth2
|
|
6
|
+
summary: Starts an OAuth2 flow
|
|
7
|
+
description: Starts a 3rd party OAuth2 authentication flow. This allows a user to sign in (and sign up) using an external auth provider such as Facebook, Google etc. The client app has to call this endpoint to get an url to redirect the user to kick off the OAuth2 flow. If the client is already authenticated, the external account will be linked to the existing user. The provider used must have been added to the server configuration with `server.configAuthProvider(provider, config)`. In the Javascript client, this OAuth2 flow can be kicked off with `client.auth.startAuthProviderSignIn(provider, callbackUrl, options)` or (browser only) `client.auth.signInWithRedirect(provider)` which uses the current url as `callbackUrl`.
|
|
8
|
+
parameters:
|
|
9
|
+
- name: dbname
|
|
10
|
+
in: path
|
|
11
|
+
description: name of the database
|
|
12
|
+
required: true
|
|
13
|
+
schema:
|
|
14
|
+
type: string
|
|
15
|
+
example: mydb
|
|
16
|
+
- name: provider
|
|
17
|
+
in: query
|
|
18
|
+
description: External OAuth2 provider name
|
|
19
|
+
required: true
|
|
20
|
+
schema:
|
|
21
|
+
type: string
|
|
22
|
+
example: facebook
|
|
23
|
+
- name: callbackUrl
|
|
24
|
+
in: query
|
|
25
|
+
description: The url to redirect the user to after they successfully authenticated, or canceled. If the signin is successful, this url is called with a `result` query parameter (eg `https://my.website.com/oauth2/callback?result=eufy3f73gfvjbwe314f...`) that can be used by the AceBase client to finish the OAuth2 flow with `client.auth.finishAuthProviderSignIn(result)`, or `client.auth.getRedirectResult()`. If the signin fails, this url will be called with query parameters `provider`, `error`, and optionally an additional `reason` and `description`, eg `https://my.website.com/oauth2/callback?error=canceled&reason=user_canceled&description=The+user+canceled+the+auth+request`
|
|
26
|
+
required: true
|
|
27
|
+
schema:
|
|
28
|
+
type: string
|
|
29
|
+
format: url
|
|
30
|
+
example: https://my.website.com/oauth2/callback
|
|
31
|
+
- name: option_[name]
|
|
32
|
+
in: query
|
|
33
|
+
description: Additional option to pass to the auth provider. For example `force_reauthentication` can be set for Dropbox by setting `option_force_reauthentication` to `true`
|
|
34
|
+
required: false
|
|
35
|
+
schema:
|
|
36
|
+
type: string
|
|
37
|
+
example: true
|
|
38
|
+
- name: option_force_reauthentication
|
|
39
|
+
in: query
|
|
40
|
+
required: false
|
|
41
|
+
description: Example option, triggers Dropbox to force the user to sign in instead of using the currently signed in user
|
|
42
|
+
schema:
|
|
43
|
+
type: string
|
|
44
|
+
example: true
|
|
45
|
+
responses:
|
|
46
|
+
200:
|
|
47
|
+
description: Returns a JSON object containing the redirectUrl to send the end user to
|
|
48
|
+
content:
|
|
49
|
+
'application/json':
|
|
50
|
+
schema:
|
|
51
|
+
type: object
|
|
52
|
+
properties:
|
|
53
|
+
redirectUrl:
|
|
54
|
+
type: string
|
|
55
|
+
example:
|
|
56
|
+
redirectUrl: https://www.facebook.com/v7.0/dialog/oauth?response_type=code&client_id=[configured facebook client id]&scope=[configured scopes]&redirect_uri=[url set by AceBase]&state=[state set by AceBase]}
|
|
57
|
+
500:
|
|
58
|
+
description: If anything goes wrong on the server, it returns the actual error text in plain text
|
|
59
|
+
content:
|
|
60
|
+
'text/plain':
|
|
61
|
+
schema:
|
|
62
|
+
type: string
|
|
63
|
+
example: Some error text
|