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.
@@ -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