acebase-server 1.8.0 → 1.9.0

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "acebase-server",
3
- "version": "1.8.0",
3
+ "version": "1.9.0",
4
4
  "description": "AceBase realtime database server (webserver endpoint to allow remote connections)",
5
5
  "main": "./src/index.js",
6
6
  "private": false,
@@ -44,13 +44,15 @@
44
44
  "author": "Ewout Stortenbeker <me@appy.one> (http://appy.one)",
45
45
  "license": "MIT",
46
46
  "dependencies": {
47
- "acebase": "^1.14.0",
48
- "acebase-core": "^1.12.0",
47
+ "acebase": "^1.15.3",
48
+ "acebase-core": "^1.13.1",
49
49
  "express": "^4.17.1",
50
50
  "socket.io": "^2.4.1"
51
51
  },
52
52
  "devDependencies": {
53
53
  "@types/express": "^4.17.13",
54
- "@types/node": "^14.0.14"
54
+ "@types/node": "^14.0.14",
55
+ "swagger-jsdoc": "^6.1.0",
56
+ "swagger-ui-express": "^4.3.0"
55
57
  }
56
58
  }
@@ -1254,11 +1254,11 @@ class AceBaseServer extends EventEmitter {
1254
1254
  if (typeof details !== 'object' || typeof details.uid !== 'string' || typeof details.password !== 'string' || typeof details.new_password !== 'string') {
1255
1255
  logRef.push({ action: 'change_password', success: false, code: 'invalid_details', ip: req.ip, date: new Date() });
1256
1256
  res.status(400).send('Bad Request'); // Bad Request
1257
- return;
1257
+ return;
1258
1258
  }
1259
- if (details.new_password.length < 8 || ~details.new_password.indexOf(' ') || !/[0-9]/.test(details.new_password) || !/[a-z]/.test(details.new_password) || !/[A-Z]/.test(details.new_password)) {
1259
+ if (details.new_password.length < 8 || details.new_password.includes(' ') || !/[0-9]/.test(details.new_password) || !/[a-z]/.test(details.new_password) || !/[A-Z]/.test(details.new_password)) {
1260
1260
  logRef.push({ action: 'change_password', success: false, code: 'new_password_denied', ip: req.ip, date: new Date(), uid: details.uid });
1261
- err = 'Invalid new password, must be at least 8 characters and contain a combination of numbers and letters (both lower and uppercase)';
1261
+ const err = 'Invalid new password, must be at least 8 characters and contain a combination of numbers and letters (both lower and uppercase)';
1262
1262
  res.status(422).send(err);// Unprocessable Entity
1263
1263
  return;
1264
1264
  }
@@ -1369,6 +1369,11 @@ class AceBaseServer extends EventEmitter {
1369
1369
 
1370
1370
  const details = req.body;
1371
1371
 
1372
+ if (typeof details.displayName === 'undefined' && typeof details.display_name === 'string') {
1373
+ // Allow display_name to be sent also (which is used in update endpoint)
1374
+ details.displayName = details.display_name;
1375
+ }
1376
+
1372
1377
  // Check if sent details are ok
1373
1378
  let err;
1374
1379
  if (!details.username && !details.email) {
@@ -1486,6 +1491,11 @@ class AceBaseServer extends EventEmitter {
1486
1491
  return sendUnauthorizedError(res, 'unauthorized_update', 'You are not authorized to perform this update. This attempt has been logged.');
1487
1492
  }
1488
1493
 
1494
+ if (typeof details.display_name === 'undefined' && typeof details.displayName === 'string') {
1495
+ // Allow displayName to be sent also (which is used in signup endpoint)
1496
+ details.display_name = details.displayName;
1497
+ }
1498
+
1489
1499
  // Check if sent details are ok
1490
1500
  let err;
1491
1501
  if (details.email && !isValid.email(details.email)) {
@@ -1580,13 +1590,13 @@ class AceBaseServer extends EventEmitter {
1580
1590
 
1581
1591
  if (req.user.uid !== 'admin' && (details.uid !== req.user.uid || typeof details.is_disabled === 'boolean')) {
1582
1592
  logRef.push({ action: 'delete', success: false, code: 'unauthorized_delete', auth_uid: req.user.uid, delete_uid: details.uid, ip: req.ip, date: new Date() });
1583
- return sendUnauthorizedError(res, 'unauthorized_update', 'You are not authorized to perform this operation, your attempt has been logged');
1593
+ return sendUnauthorizedError(res, 'unauthorized_delete', 'You are not authorized to perform this operation, your attempt has been logged');
1584
1594
  }
1585
1595
 
1586
1596
  const uid = details.uid || req.user.uid;
1587
1597
  if (uid === 'admin') {
1588
1598
  logRef.push({ action: 'delete', success: false, code: 'unauthorized_delete', auth_uid: req.user.uid, delete_uid: details.uid, ip: req.ip, date: new Date() });
1589
- return sendUnauthorizedError(res, 'unauthorized_update', 'The admin account cannot be deleted, your attempt has been logged');
1599
+ return sendUnauthorizedError(res, 'unauthorized_delete', 'The admin account cannot be deleted, your attempt has been logged');
1590
1600
  }
1591
1601
  return authRef.child(uid)
1592
1602
  .remove()
@@ -1863,7 +1873,11 @@ class AceBaseServer extends EventEmitter {
1863
1873
  expires_in: tokens.expires_in
1864
1874
  },
1865
1875
  access_token: createPublicAccessToken(user.uid, req.ip, user.access_token, _secureObjectsSalt),
1866
- user: getPublicAccountDetails(user)
1876
+
1877
+ // Disabled sending user details because:
1878
+ // 1) they might be too big to send as redirect header,
1879
+ // 2) client should verify the sent access token and get user details from the server
1880
+ // user: getPublicAccountDetails(user)
1867
1881
  };
1868
1882
 
1869
1883
  if (state.flow === 'socket') {
@@ -1910,6 +1924,13 @@ class AceBaseServer extends EventEmitter {
1910
1924
  });
1911
1925
  }
1912
1926
 
1927
+ // If environment is development, add API docs
1928
+ if (process.env.NODE_ENV === 'development') {
1929
+ this.debug.warn('DEVELOPMENT MODE: adding API docs endpoint at /docs');
1930
+ const addAPIDocsRoute = require('./routes/docs').default;
1931
+ addAPIDocsRoute(app);
1932
+ }
1933
+
1913
1934
  const webManagerDir = `/webmanager/`;
1914
1935
  app.get('/', (req, res) => {
1915
1936
  res.redirect(webManagerDir);
@@ -1921,24 +1942,6 @@ class AceBaseServer extends EventEmitter {
1921
1942
  // Send default file
1922
1943
  res.sendFile(__dirname + '/webmanager/index.html');
1923
1944
  }
1924
- // else if (filePath === 'TEST') {
1925
- // // apply test
1926
- // let test;
1927
- // if (req.query.type === 'update') {
1928
- // let val = req.query.val;
1929
- // if (val[0] === '{') { val = JSON.parse(val); }
1930
- // test = db.ref(req.query.path || '').update(val);
1931
- // }
1932
- // else {
1933
- // res.send('');
1934
- // }
1935
- // return test && test.then(() => {
1936
- // res.send('ok');
1937
- // })
1938
- // .catch(err => {
1939
- // res.send('fail: ' + err.message);
1940
- // });
1941
- // }
1942
1945
  else {
1943
1946
  res.sendFile(__dirname + '/webmanager/' + filePath);
1944
1947
  }
@@ -1951,7 +1954,7 @@ class AceBaseServer extends EventEmitter {
1951
1954
 
1952
1955
  app.get(`/info/${dbname}`, (req, res) => {
1953
1956
  const info = {
1954
- version: '1.8.0', // TODO: Load from package.json
1957
+ version: '1.9.0', // TODO: Load from package.json
1955
1958
  time: Date.now(),
1956
1959
  process: process.pid
1957
1960
  };
@@ -0,0 +1,90 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ const path = require("path");
4
+ const swaggerJsdoc = require("swagger-jsdoc");
5
+ const swaggerUi = require("swagger-ui-express");
6
+ // import config from '../config';
7
+ const addRoute = (app) => {
8
+ // Generate docs from all yaml files
9
+ const 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
+ },
21
+ components: {
22
+ securitySchemes: {
23
+ bearerAuth: {
24
+ type: 'http',
25
+ scheme: 'bearer',
26
+ bearerFormat: 'token' // switch to JWT in the future?
27
+ }
28
+ },
29
+ schemas: {
30
+ User: {
31
+ type: 'object',
32
+ properties: {
33
+ uid: { type: 'string', example: 'jpx0k53u0002ecr7s354c51l' },
34
+ username: { type: 'string', example: 'someuser' },
35
+ email: { type: 'string', example: 'email@domain.com' },
36
+ displayName: { type: 'string', example: 'Some User' },
37
+ picture: {
38
+ type: 'object',
39
+ properties: {
40
+ width: { type: 'number', example: 500 },
41
+ height: { type: 'number', example: 500 },
42
+ url: { type: 'string', example: 'https://profile.pic/user.jpg' }
43
+ }
44
+ },
45
+ emailVerified: { type: 'boolean', example: true },
46
+ created: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
47
+ prevSignin: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
48
+ prevSigninIp: { type: 'string', example: '127.0.0.1' },
49
+ lastSignin: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
50
+ lastSigninIp: { type: 'string', example: '127.0.0.1' },
51
+ changePassword: { type: 'boolean', example: false },
52
+ changePasswordRequested: { type: 'boolean', example: false },
53
+ changePasswordBefore: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
54
+ settings: { type: 'object' }
55
+ }
56
+ },
57
+ Error: {
58
+ type: 'object',
59
+ properties: {
60
+ code: { type: 'string', description: 'error code', example: 'invalid_request' },
61
+ message: { type: 'string', description: 'The error message', example: 'Invalid request for this endpoint' }
62
+ }
63
+ },
64
+ UnexpectedError: {
65
+ type: 'object',
66
+ properties: {
67
+ code: { type: 'string', value: 'unexpected', description: 'The string `"unexpected"`' },
68
+ message: { type: 'string', description: 'The server error message' }
69
+ }
70
+ },
71
+ UnknownError: {
72
+ type: 'object',
73
+ properties: {
74
+ code: { type: 'string', value: 'unknown', description: 'The string `"unknown"`' },
75
+ message: { type: 'string', description: 'The server error message' }
76
+ }
77
+ }
78
+ }
79
+ },
80
+ security: [
81
+ // Enable bearer auth globally
82
+ { bearerAuth: [] }
83
+ ],
84
+ },
85
+ apis: [path.resolve(__dirname, '../ts/routes/*.yaml')]
86
+ };
87
+ const swaggerDocs = swaggerJsdoc(options);
88
+ app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
89
+ };
90
+ exports.default = addRoute;
@@ -0,0 +1,75 @@
1
+ /auth/{dbname}/change_password:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Changes a user account's password by providing the current and new passwords
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: request object
16
+ content:
17
+ 'application/json':
18
+ schema:
19
+ type: object
20
+ properties:
21
+ uid:
22
+ type: string
23
+ description: Account's uid
24
+ password:
25
+ type: string
26
+ description: Current password set on the account
27
+ new_password:
28
+ type: string
29
+ description: New password to set on the account
30
+ required:
31
+ - uid
32
+ - password
33
+ - new_password
34
+ responses:
35
+ 200:
36
+ description: If the password change is successful, returns an object with a new access token
37
+ content:
38
+ 'application/json':
39
+ schema:
40
+ type: object
41
+ properties:
42
+ access_token:
43
+ description: New access token that provides access to API calls that require authentication.
44
+ type: string
45
+ example: ewufh387f3fyubqwekrjbcqwkuiec7gq3euyfbqwkuyebqjk..
46
+ user:
47
+ $ref: '#/components/schemas/User'
48
+ 400:
49
+ description: Returns a `"400 Bad Request"` if the sent request is invalid. If the request is missing details, response is the string `"Bad Request"`. Otherwise, it's an object with `code` and `message` properties. Possible codes are `"unknown_uid"`, `"wrong_password"`, `"wrong_access_token"` (if not signed in as the user the password change was requested for)
50
+ content:
51
+ 'text/plain':
52
+ schema:
53
+ type: string
54
+ value: Bad Request
55
+ example: Bad Request
56
+ 'application/json':
57
+ schema:
58
+ $ref: '#/components/schemas/Error'
59
+ example:
60
+ code: wrong_access_token
61
+ message: "Cannot change password while signed in as other user, or with an old token"
62
+ 422:
63
+ description: New password does not meet the criteria
64
+ content:
65
+ 'text/plain':
66
+ schema:
67
+ type: string
68
+ value: "Invalid new password, must be at least 8 characters and contain a combination of numbers and letters (both lower and uppercase)"
69
+ example: "Invalid new password, must be at least 8 characters and contain a combination of numbers and letters (both lower and uppercase)"
70
+ 500:
71
+ description: An unexpected error occurred
72
+ content:
73
+ 'application/json':
74
+ schema:
75
+ $ref: '#/components/schemas/UnexpectedError'
@@ -0,0 +1,77 @@
1
+ /auth/{dbname}/delete:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Deletes an existing user account
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: Account to delete
16
+ content:
17
+ 'text/plain':
18
+ schema:
19
+ type: string
20
+ value: ''
21
+ example: ''
22
+ description: Empty content to delete signed in user account
23
+ 'application/json':
24
+ schema:
25
+ type: object
26
+ properties:
27
+ uid:
28
+ type: string
29
+ description: (admin user only) to delete a specific user account, the target account `uid` must be passed with the request
30
+ example: jpx0k53u0002ecr7s354c51l
31
+ responses:
32
+ 200:
33
+ description: When delete succeeds, it returns the string `"Farewell"`
34
+ content:
35
+ 'text/plain':
36
+ schema:
37
+ type: text
38
+ value: Farewell
39
+ example: Farewell
40
+ 401:
41
+ description: If this is an unauthenticated request (not signed in), `"401 Unauthorized"` is returned
42
+ content:
43
+ 'application/json':
44
+ schema:
45
+ type: object
46
+ properties:
47
+ code:
48
+ type: string
49
+ value: unauthenticated_delete
50
+ message:
51
+ type: string
52
+ value: You are not authorized to perform this operation, your attempt has been logged
53
+ example:
54
+ code: unauthenticated_delete
55
+ message: You are not authorized to perform this operation, your attempt has been logged
56
+ 403:
57
+ description: If a non-admin user tries to update a user's account details, `"403 Forbidden"` is returned
58
+ content:
59
+ 'application/json':
60
+ schema:
61
+ type: object
62
+ properties:
63
+ code:
64
+ type: string
65
+ value: unauthorized_delete
66
+ message:
67
+ type: string
68
+ value: You are not authorized to perform this operation. This attempt has been logged.
69
+ example:
70
+ code: unauthorized_delete
71
+ message: You are not authorized to perform this operation. This attempt has been logged.
72
+ 500:
73
+ description: An unenexpected error occurred on the server
74
+ content:
75
+ 'application/json':
76
+ schema:
77
+ $ref: '#/components/schemas/UnexpectedError'
@@ -0,0 +1,49 @@
1
+ /auth/{dbname}/forgot_password:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Issues a password reset for a user that forgot their password. User must have an email address in the database.
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: user details
16
+ content:
17
+ 'application/json':
18
+ schema:
19
+ type: object
20
+ properties:
21
+ email:
22
+ type: string
23
+ description: User's email address. A password reset email will be sent to this address
24
+ required:
25
+ - email
26
+ responses:
27
+ 200:
28
+ description: If a password reset email has been successfully sent, returns the string `"OK"`
29
+ content:
30
+ 'text/plain':
31
+ schema:
32
+ type: 'string'
33
+ value: OK
34
+ description: The string `"OK"`
35
+ 400:
36
+ description: Returns a `"400 Bad Request"` if the server has not been configured properly, or if no or invalid email address was sent with the request
37
+ content:
38
+ 'application/json':
39
+ schema:
40
+ $ref: '#/components/schemas/Error'
41
+ example:
42
+ code: invalid_email
43
+ message: Email address not found, or duplicate entries found
44
+ 500:
45
+ description: An unexpected error occurred
46
+ content:
47
+ 'application/json':
48
+ schema:
49
+ $ref: '#/components/schemas/UnexpectedError'
@@ -0,0 +1,53 @@
1
+ /auth/{dbname}/reset_password:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Completes a password reset request for a user account with a code sent to the email address by the `forgot_password` endpoint
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: verification object
16
+ content:
17
+ 'application/json':
18
+ schema:
19
+ type: object
20
+ properties:
21
+ code:
22
+ type: string
23
+ description: Password reset code that was sent to the user's email address
24
+ password:
25
+ type: string
26
+ description: New password to set on the account
27
+ required:
28
+ - code
29
+ - password
30
+ responses:
31
+ 200:
32
+ description: If the password reset is successful, returns the string `"OK"`
33
+ content:
34
+ 'text/plain':
35
+ schema:
36
+ type: 'string'
37
+ value: OK
38
+ description: The string `"OK"`
39
+ 400:
40
+ description: Returns a `"401 Bad Request"` if the code sent with the request is invalid, or the new password doesn't meet the requirements
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,129 @@
1
+ /auth/{dbname}/signin:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Signs in an existing user
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: sign in details
16
+ content:
17
+ 'application/json':
18
+ schema:
19
+ oneOf:
20
+ - type: object
21
+ properties:
22
+ client_id:
23
+ description: ID of the connected websocket
24
+ type: string
25
+ method:
26
+ description: Method of authentication (email)
27
+ type: string
28
+ value: email
29
+ email:
30
+ description: User email address
31
+ type: string
32
+ password:
33
+ description: Password
34
+ type: string
35
+ format: password
36
+ required:
37
+ - method
38
+ - email
39
+ - password
40
+ example:
41
+ method: email
42
+ email: user@example.com
43
+ password: sup3rs3cr3t
44
+ - type: object
45
+ properties:
46
+ client_id:
47
+ description: ID of the connected websocket
48
+ type: string
49
+ method:
50
+ description: Method of authentication (username)
51
+ type: string
52
+ value: username
53
+ username:
54
+ description: Username
55
+ type: string
56
+ password:
57
+ description: Password
58
+ type: string
59
+ format: password
60
+ required:
61
+ - method
62
+ - username
63
+ - password
64
+ example:
65
+ method: username
66
+ username: user
67
+ password: sup3rs3cr3t
68
+ - type: object
69
+ properties:
70
+ client_id:
71
+ type: string
72
+ description: ID of the connected websocket
73
+ method:
74
+ type: string
75
+ value: token
76
+ description: Method of authentication (token)
77
+ token:
78
+ type: string
79
+ description: Previously acquired access token to sign in with
80
+ required:
81
+ - method
82
+ - token
83
+ example:
84
+ method: token
85
+ token: ewufh387f3fyubqwekrjbcqwkuiec7gq3euyfbqwkuyebqjk..
86
+ responses:
87
+ 200:
88
+ description: When signin succeeds, it returns an object with the result
89
+ content:
90
+ 'application/json':
91
+ schema:
92
+ type: object
93
+ properties:
94
+ access_token:
95
+ 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
96
+ type: string
97
+ example: ewufh387f3fyubqwekrjbcqwkuiec7gq3euyfbqwkuyebqjk..
98
+ user:
99
+ $ref: '#/components/schemas/User'
100
+ 401:
101
+ description: When the sent request details are incorrect, this "401 Unauthorized" is returned
102
+ content:
103
+ 'application/json':
104
+ schema:
105
+ type: object
106
+ properties:
107
+ code:
108
+ type: string
109
+ description: The exact error code
110
+ enum:
111
+ - invalid_token
112
+ - not_found
113
+ - duplicate
114
+ - token_mismatch
115
+ - wrong_password
116
+ example: not_found
117
+ message:
118
+ type: string
119
+ description: Description of the error
120
+ example: Incorrect email
121
+ example:
122
+ code: wrong_password
123
+ message: Incorrect password
124
+ 500:
125
+ description: An unenexpected error occurred on the server
126
+ content:
127
+ 'application/json':
128
+ schema:
129
+ $ref: '#/components/schemas/UnexpectedError'
@@ -0,0 +1,45 @@
1
+ /auth/{dbname}/signout:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Signs in an existing user
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: Sign out details
16
+ content:
17
+ 'application/json':
18
+ schema:
19
+ type: object
20
+ properties:
21
+ client_id:
22
+ type: string
23
+ description: ID of the connected websocket
24
+ everywhere:
25
+ type: boolean
26
+ description: Whether the user should sign out on ALL clients
27
+ example:
28
+ client_id: x8WIv7-mJelg7on_ALbx
29
+ everywhere: false
30
+ responses:
31
+ 200:
32
+ description: Returns `"Bye!"` if signout is successful
33
+ content:
34
+ 'text/plain':
35
+ schema:
36
+ type: string
37
+ value: Bye!
38
+ example: Bye!
39
+ 500:
40
+ description: Returns an object describing an unexpected error
41
+ content:
42
+ 'application/json':
43
+ schema:
44
+ $ref: '#/components/schemas/Error'
45
+
@@ -0,0 +1,120 @@
1
+ /auth/{dbname}/signup:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Signs up a new user (must be enabled in the server config)
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: new user details
16
+ content:
17
+ 'application/json':
18
+ schema:
19
+ type: object
20
+ properties:
21
+ username:
22
+ type: string
23
+ description: Requested username (optional if `email` provided)
24
+ email:
25
+ type: string
26
+ description: Email address (optional if `username` provided)
27
+ displayName:
28
+ type: string
29
+ description: Name of the user for public displaying purposes. Consider this a real name, alias or handle
30
+ password:
31
+ type: string
32
+ format: password
33
+ description: Password to set for the account
34
+ settings:
35
+ type: object
36
+ otherProperties: true
37
+ desciption: (optional) miscellanious other info to store with the user account
38
+ required:
39
+ - username
40
+ - email
41
+ - displayName
42
+ - password
43
+ example:
44
+ email: user@example.com
45
+ displayName: Real Name
46
+ password: sup3rs3cr3t
47
+ responses:
48
+ 200:
49
+ description: When signup succeeds, it returns an object with the result
50
+ content:
51
+ 'application/json':
52
+ schema:
53
+ type: object
54
+ properties:
55
+ access_token:
56
+ 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
57
+ type: string
58
+ example: ewufh387f3fyubqwekrjbcqwkuiec7gq3euyfbqwkuyebqjk..
59
+ user:
60
+ $ref: '#/components/schemas/User'
61
+ 403:
62
+ description: If user signup is disabled in the server config, only the admin user can create new accounts and `"403 Forbidden"` is returned
63
+ content:
64
+ 'application/json':
65
+ schema:
66
+ type: object
67
+ properties:
68
+ code:
69
+ type: string
70
+ value: admin_only
71
+ message:
72
+ type: string
73
+ value: Only admin is allowed to create users
74
+ example:
75
+ code: admin_only
76
+ message: Only admin is allowed to create users
77
+ 409:
78
+ description: An account with the same username or email address exists already
79
+ content:
80
+ 'application/json':
81
+ schema:
82
+ type: object
83
+ properties:
84
+ code:
85
+ type: string
86
+ value: conflict
87
+ message:
88
+ type: string
89
+ value: Account with username and/or email already exists
90
+ 422:
91
+ description: When the sent request details are incorrect, `"422 Unprocessable Entity"` is returned
92
+ content:
93
+ 'application/json':
94
+ schema:
95
+ type: object
96
+ properties:
97
+ code:
98
+ type: string
99
+ description: The exact error code
100
+ enum:
101
+ - missing_details
102
+ - invalid_email
103
+ - invalid_username
104
+ - invalid_display_name
105
+ - invalid_password
106
+ - invalid_settings
107
+ example: missing_details
108
+ message:
109
+ type: string
110
+ description: Description of the error
111
+ example: No username or email provided
112
+ example:
113
+ code: invalid_password
114
+ message: Invalid password, must be at least 8 characters and cannot contain spaces
115
+ 500:
116
+ description: An unenexpected error occurred on the server
117
+ content:
118
+ 'application/json':
119
+ schema:
120
+ $ref: '#/components/schemas/UnexpectedError'
@@ -0,0 +1,28 @@
1
+ /auth/{dbname}/state:
2
+ tags:
3
+ - auth
4
+ get:
5
+ description: Gets current auth state
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ responses:
15
+ 200:
16
+ description: returns whether the request was authenticated and by which user (determined by the sent Authorization header)
17
+ content:
18
+ 'application/json':
19
+ schema:
20
+ type: object
21
+ properties:
22
+ signed_in:
23
+ type: boolean
24
+ example: true
25
+ user:
26
+ $ref: '#/components/schemas/User'
27
+ required:
28
+ - signed_in
@@ -0,0 +1,131 @@
1
+ /auth/{dbname}/update:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Updates user account details
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: user details to update
16
+ content:
17
+ 'application/json':
18
+ schema:
19
+ type: object
20
+ properties:
21
+ uid:
22
+ type: string
23
+ description: (admin user only) to change a user's account settings, the target account `uid` must be passed with the request
24
+ is_disabled:
25
+ type: boolean
26
+ description: (admin user only) whether the target account should be disabled to enable/disable signin
27
+ email:
28
+ type: string
29
+ description: New email address
30
+ username:
31
+ type: string
32
+ description: New username
33
+ display_name:
34
+ type: string
35
+ 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)
36
+ picture:
37
+ type: object
38
+ properties:
39
+ url:
40
+ type: string
41
+ width:
42
+ type: number
43
+ height:
44
+ type: number
45
+ example:
46
+ url: https://my.profile.pic/me.jpg
47
+ width: 500
48
+ height: 500
49
+ settings:
50
+ type: object
51
+ otherProperties: true
52
+ desciption: (optional) miscellanious other info to store with the user account
53
+ required:
54
+ - username
55
+ - email
56
+ - displayName
57
+ - password
58
+ responses:
59
+ 200:
60
+ description: When update succeeds, it returns an object with the new user details
61
+ content:
62
+ 'application/json':
63
+ schema:
64
+ type: object
65
+ properties:
66
+ user:
67
+ $ref: '#/components/schemas/User'
68
+ 401:
69
+ description: If this is an unauthenticated request (not signed in), `"401 Unauthorized"` is returned
70
+ content:
71
+ 'application/json':
72
+ schema:
73
+ type: object
74
+ properties:
75
+ code:
76
+ type: string
77
+ value: unauthenticated_update
78
+ message:
79
+ type: string
80
+ value: Sign in to change details
81
+ example:
82
+ code: unauthenticated_update
83
+ message: Sign in to change details
84
+ 403:
85
+ description: If a non-admin user tries to update a user's account details, `"403 Forbidden"` is returned
86
+ content:
87
+ 'application/json':
88
+ schema:
89
+ type: object
90
+ properties:
91
+ code:
92
+ type: string
93
+ value: unauthorized_update
94
+ message:
95
+ type: string
96
+ value: You are not authorized to perform this update. This attempt has been logged.
97
+ example:
98
+ code: unauthorized_update
99
+ message: You are not authorized to perform this update. This attempt has been logged.
100
+ 422:
101
+ description: When the sent request details are incorrect, this "422 Unprocessable Entity" is returned
102
+ content:
103
+ 'application/json':
104
+ schema:
105
+ type: object
106
+ properties:
107
+ code:
108
+ type: string
109
+ description: The exact error code
110
+ enum:
111
+ - invalid_email
112
+ - email_conflict
113
+ - invalid_username
114
+ - username_conflict
115
+ - invalid_display_name
116
+ - invalid_picture
117
+ - invalid_settings
118
+ example: missing_details
119
+ message:
120
+ type: string
121
+ description: Description of the error
122
+ example: Account with email address exists already
123
+ example:
124
+ code: username_conflict
125
+ message: Account with username exists already
126
+ 500:
127
+ description: An unenexpected error occurred on the server
128
+ content:
129
+ 'application/json':
130
+ schema:
131
+ $ref: '#/components/schemas/UnexpectedError'
@@ -0,0 +1,52 @@
1
+ /auth/{dbname}/verify_email:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Verifies an email address with a code sent through their email address
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: verification object
16
+ content:
17
+ 'application/json':
18
+ schema:
19
+ type: object
20
+ properties:
21
+ code:
22
+ type: string
23
+ description: Verification code that was sent to the user's email address
24
+ required:
25
+ - code
26
+ example:
27
+ code: ewrg235235g23gwrvsdb34g524rvqewwrv425gervqew...
28
+ responses:
29
+ 200:
30
+ description: If the email address is successfully verified, returns the string `"OK"`
31
+ content:
32
+ 'text/plain':
33
+ schema:
34
+ type: 'string'
35
+ value: OK
36
+ example: OK
37
+ description: The string `"OK"`
38
+ 401:
39
+ description: Returns a `"401 Bad Request"` if the code sent with the request is invalid
40
+ content:
41
+ 'application/json':
42
+ schema:
43
+ $ref: '#/components/schemas/Error'
44
+ example:
45
+ code: invalid_code
46
+ message: Invalid token
47
+ 500:
48
+ description: An unexpected error occurred
49
+ content:
50
+ 'application/json':
51
+ schema:
52
+ $ref: '#/components/schemas/UnexpectedError'
@@ -0,0 +1,93 @@
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
+ components: {
23
+ securitySchemes: {
24
+ bearerAuth: {
25
+ type: 'http',
26
+ scheme: 'bearer',
27
+ bearerFormat: 'token' // switch to JWT in the future?
28
+ }
29
+ },
30
+ schemas: {
31
+ User: {
32
+ type: 'object',
33
+ properties: {
34
+ uid: { type: 'string', example: 'jpx0k53u0002ecr7s354c51l' },
35
+ username: { type: 'string', example: 'someuser' },
36
+ email: { type: 'string', example: 'email@domain.com' },
37
+ displayName: { type: 'string', example: 'Some User' },
38
+ picture: {
39
+ type: 'object',
40
+ properties: {
41
+ width: { type: 'number', example: 500 },
42
+ height: { type: 'number', example: 500 },
43
+ url: { type: 'string', example: 'https://profile.pic/user.jpg' }
44
+ }
45
+ },
46
+ emailVerified: { type: 'boolean', example: true },
47
+ created: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
48
+ prevSignin: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
49
+ prevSigninIp: { type: 'string', example: '127.0.0.1' },
50
+ lastSignin: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
51
+ lastSigninIp: { type: 'string', example: '127.0.0.1' },
52
+ changePassword: { type: 'boolean', example: false },
53
+ changePasswordRequested: { type: 'boolean', example: false },
54
+ changePasswordBefore: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
55
+ settings: { type: 'object' }
56
+ }
57
+ },
58
+ Error: {
59
+ type: 'object',
60
+ properties: {
61
+ code: { type: 'string', description: 'error code', example: 'invalid_request' },
62
+ message: { type: 'string', description: 'The error message', example: 'Invalid request for this endpoint' }
63
+ }
64
+ },
65
+ UnexpectedError: {
66
+ type: 'object',
67
+ properties: {
68
+ code: { type: 'string', value: 'unexpected', description: 'The string `"unexpected"`' },
69
+ message: { type: 'string', description: 'The server error message' }
70
+ }
71
+ },
72
+ UnknownError: {
73
+ type: 'object',
74
+ properties: {
75
+ code: { type: 'string', value: 'unknown', description: 'The string `"unknown"`' },
76
+ message: { type: 'string', description: 'The server error message' }
77
+ }
78
+ }
79
+ }
80
+ },
81
+ security: [
82
+ // Enable bearer auth globally
83
+ { bearerAuth: [] }
84
+ ],
85
+ },
86
+ apis: [path.resolve(__dirname, '../ts/routes/*.yaml')]
87
+ };
88
+
89
+ const swaggerDocs = swaggerJsdoc(options);
90
+ app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
91
+ };
92
+
93
+ export default addRoute;