soul-cli 0.7.7 → 0.8.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/.env.sample +1 -1
- package/README.md +33 -11
- package/docs/api/auth-examples.md +164 -0
- package/docs/api/root-examples.md +0 -40
- package/docs/api/rows-auth-examples.md +137 -0
- package/docs/api-examples.md +6 -4
- package/docs/auth.md +6 -0
- package/package.json +2 -2
- package/src/cli.js +6 -0
- package/src/config/index.js +1 -1
- package/src/constants/messages.js +2 -1
- package/src/controllers/auth.test.js +1 -1
- package/src/controllers/index.js +9 -70
- package/src/controllers/index.test.js +4 -23
- package/src/index.js +1 -3
- package/src/routes/index.js +1 -7
- package/src/swagger/index.js +2 -1
- package/src/swagger/swagger.json +7 -30
package/.env.sample
CHANGED
package/README.md
CHANGED
|
@@ -7,7 +7,6 @@
|
|
|
7
7
|
|
|
8
8
|
[](https://justforfunnoreally.dev)
|
|
9
9
|
[](#contributors)
|
|
10
|
-
[](https://trackgit.com)
|
|
11
10
|
|
|
12
11
|
## Installation
|
|
13
12
|
|
|
@@ -34,6 +33,7 @@ Options:
|
|
|
34
33
|
-p, --port Port to listen on [number]
|
|
35
34
|
-r, --rate-limit-enabled Enable rate limiting [boolean]
|
|
36
35
|
-c, --cors CORS whitelist origins [string]
|
|
36
|
+
--env, --envpath Path to load .env file [string]
|
|
37
37
|
-a, --auth Enable authentication and authorization [boolean]
|
|
38
38
|
|
|
39
39
|
--iuu, --initialuserusername Initial user username [string]
|
|
@@ -42,8 +42,8 @@ Options:
|
|
|
42
42
|
--ts, --tokensecret Token Secret [string]
|
|
43
43
|
--atet, --accesstokenexpirationtime Access Token Expiration Time (Default: 5H) [string]
|
|
44
44
|
--rtet, --refreshtokenexpirationtime Refresh Token Expiration Time (Default: 1D) [string]
|
|
45
|
-
-S, --studio
|
|
46
|
-
--help
|
|
45
|
+
-S, --studio Start Soul Studio in parallel
|
|
46
|
+
--help Show help
|
|
47
47
|
|
|
48
48
|
```
|
|
49
49
|
|
|
@@ -67,16 +67,16 @@ Run the Soul command with the necessary parameters:
|
|
|
67
67
|
|
|
68
68
|
```
|
|
69
69
|
|
|
70
|
-
Note: When configuring your JWT Secret, it is recommended to use a long string value for enhanced security. It is advisable to use a secret that is at least 10 characters in length.
|
|
70
|
+
> Note: When configuring your JWT Secret, it is recommended to use a long string value for enhanced security. It is advisable to use a secret that is at least 10 characters in length.
|
|
71
71
|
|
|
72
72
|
In this example:
|
|
73
73
|
|
|
74
|
-
The `-a` flag instructs Soul to run in auth mode.
|
|
75
|
-
The `--ts` flag allows you to pass a JWT secret value for the `access and refresh tokens` generation and verification. Replace <your_jwt_secret_value> with your desired secret value.
|
|
76
|
-
The `--atet` flag sets the JWT expiration time for the access token. In this case, it is set to four hours (4H), meaning the token will expire after 4 hours.
|
|
77
|
-
The `--rtet` flag sets the JWT expiration time for the refresh token. In this case, it is set to three days (3D), meaning the token will expire after 3 days.
|
|
78
|
-
The `--iuu` flag is used to pass a username for the initial user
|
|
79
|
-
The `--iup` flag is used to pass a password for the initial user
|
|
74
|
+
- The `-a` flag instructs Soul to run in auth mode.
|
|
75
|
+
- The `--ts` flag allows you to pass a JWT secret value for the `access and refresh tokens` generation and verification. Replace <your_jwt_secret_value> with your desired secret value.
|
|
76
|
+
- The `--atet` flag sets the JWT expiration time for the access token. In this case, it is set to four hours (4H), meaning the token will expire after 4 hours.
|
|
77
|
+
- The `--rtet` flag sets the JWT expiration time for the refresh token. In this case, it is set to three days (3D), meaning the token will expire after 3 days.
|
|
78
|
+
- The `--iuu` flag is used to pass a username for the initial user
|
|
79
|
+
- The `--iup` flag is used to pass a password for the initial user
|
|
80
80
|
|
|
81
81
|
Here are some example values for the `atet` and `rtet` flags
|
|
82
82
|
|
|
@@ -98,6 +98,20 @@ soul -d foobar.db updatesuperuser --id=1 --is_superuser=true // Upgrade the user
|
|
|
98
98
|
soul -d foobar.db updatesuperuser --id=1 --is_superuser=false // Revoke the superuser role from the superuser with ID 1
|
|
99
99
|
```
|
|
100
100
|
|
|
101
|
+
### Passing Custom Path for .env File
|
|
102
|
+
|
|
103
|
+
There might be cases where you want to pass a custom path for your `.env` file. For this, you can use the `--env` flag when running the `soul` command, providing the absolute file path of your `.env` file.
|
|
104
|
+
|
|
105
|
+
```shell
|
|
106
|
+
soul -d foobar.db --env=/absolute/path/of/your/.env/file
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
NOTE:
|
|
110
|
+
|
|
111
|
+
- You should pass an absolute file path of the .env file.
|
|
112
|
+
- Relative paths are not allowed.
|
|
113
|
+
- Don't forget to include the .env file in the specified path.
|
|
114
|
+
|
|
101
115
|
## Documentation
|
|
102
116
|
|
|
103
117
|
API documentation is available while the project is running at [http://localhost:8000/api/docs](http://localhost:8000/api/docs)
|
|
@@ -126,6 +140,8 @@ A collection of projects that revolve around the Soul ecosystem.
|
|
|
126
140
|
|
|
127
141
|
- [RCO-Soul](https://github.com/DeepBlueCLtd/RCO-Soul) The purpose of this project is to demonstrate how to run a React admin client using Soul as a REST API service.
|
|
128
142
|
|
|
143
|
+
- [dber](https://github.com/findyourmagic/dber) Database design tool based on entity relation diagram
|
|
144
|
+
|
|
129
145
|
## Development
|
|
130
146
|
|
|
131
147
|
```bash
|
|
@@ -140,12 +156,18 @@ npm run dev # Start the dev server
|
|
|
140
156
|
|
|
141
157
|
## Testing
|
|
142
158
|
|
|
143
|
-
Set the `AUTH` variable to
|
|
159
|
+
1. Set the `AUTH` variable to true in your `.env` file.
|
|
160
|
+
2. Provide a username for the `INITIAL_USER_USERNAME` environment variable. The username should be a valid, meaningful username.
|
|
161
|
+
3. Provide a strong password for the `INITIAL_USER_PASSWORD` environment variable. The password should be at least 8 characters long and contain a combination of lowercase letters, uppercase letters, numbers, and special characters, for example: "Str0ng$Pw!".
|
|
162
|
+
4. Provider a secret for the `TOKEN_SECRET` environment variable.
|
|
163
|
+
5. Use the following command to run the tests:
|
|
144
164
|
|
|
145
165
|
```
|
|
146
166
|
npm run test
|
|
147
167
|
```
|
|
148
168
|
|
|
169
|
+
Make sure to replace the placeholders with the appropriate values for your environment.
|
|
170
|
+
|
|
149
171
|
## Community
|
|
150
172
|
|
|
151
173
|
[Join](https://bit.ly/soul-discord) the discussion in our Discord server and help making Soul together.
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
## Authentication / Authorization
|
|
2
|
+
|
|
3
|
+
These endpoints are for Soul in the Auth mode. For that you need to enable auth mode by setting the `AUTH=true` environment variable or using the `-a` argument when starting a Soul server.
|
|
4
|
+
|
|
5
|
+
### 1. Obtain an access token
|
|
6
|
+
|
|
7
|
+
To obtain an access token call `/auth/token/obtain/` endpoint with `POST` method.
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
curl -v --request POST \
|
|
11
|
+
--url http://localhost:8000/api/auth/token/obtain \
|
|
12
|
+
--header 'Content-Type: application/json' \
|
|
13
|
+
--data '{
|
|
14
|
+
"fields": {
|
|
15
|
+
"username": "damien",
|
|
16
|
+
"password": "strongpass"
|
|
17
|
+
}
|
|
18
|
+
}'
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Response
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
...
|
|
25
|
+
< Set-Cookie: accessToken=<jwt-access-token>; Path=/; HttpOnly
|
|
26
|
+
< Set-Cookie: refreshToken=<jwt-refresh-token>; Path=/; HttpOnly
|
|
27
|
+
...
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
> You can see that when login is successful, Soul sets two cookies one for the access token and the other for the refresh token.
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"message": "Success",
|
|
35
|
+
"data": {
|
|
36
|
+
"userId": 1
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
#### Body Params
|
|
42
|
+
|
|
43
|
+
- `fields` containing `username` and `password` e.g.
|
|
44
|
+
|
|
45
|
+
```json
|
|
46
|
+
"fields": {
|
|
47
|
+
"username": "damien",
|
|
48
|
+
"password": "strongpass"
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
> Here's how the jwt access token payload looks like:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"subject": "accessToken",
|
|
57
|
+
"username": "damien",
|
|
58
|
+
"userId": 1,
|
|
59
|
+
"isSuperuser": "false",
|
|
60
|
+
"roleIds": [1],
|
|
61
|
+
"iat": 1717427688,
|
|
62
|
+
"exp": 1717463688
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### 2. Refresh token
|
|
67
|
+
|
|
68
|
+
To refresh and obtain a new access token call `/auth/token/refresh/` endpoint with `GET` method.
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
curl -v http://localhost:8000/api/auth/token/refresh \
|
|
72
|
+
--cookie 'refreshToken=<jwt-refresh-token>'
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Response
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
...
|
|
79
|
+
< Set-Cookie: accessToken=<jwt-access-token>; Path=/; HttpOnly
|
|
80
|
+
< Set-Cookie: refreshToken=<jwt-refresh-token>; Path=/; HttpOnly
|
|
81
|
+
...
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
> There you get a new token pair
|
|
85
|
+
|
|
86
|
+
```json
|
|
87
|
+
{
|
|
88
|
+
"message": "Success",
|
|
89
|
+
"data": {
|
|
90
|
+
"userId": 1
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
#### Cookies
|
|
96
|
+
|
|
97
|
+
- `refreshToken` the refresh token that you acquired before
|
|
98
|
+
|
|
99
|
+
### 3. Change password
|
|
100
|
+
|
|
101
|
+
To change your account password call `/auth/change-password/` endpoint with `PUT` method.
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
curl --request PUT \
|
|
105
|
+
--url http://localhost:8000/api/auth/change-password \
|
|
106
|
+
--header 'Content-Type: application/json' \
|
|
107
|
+
--data '{
|
|
108
|
+
"fields": {
|
|
109
|
+
"currentPassword": "strongpass",
|
|
110
|
+
"newPassword": "anotherstrongpass"
|
|
111
|
+
}
|
|
112
|
+
}' \
|
|
113
|
+
--cookie 'accessToken=<jwt-access-token>'
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Response
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{
|
|
120
|
+
"message": "Password updated successfully",
|
|
121
|
+
"data": {
|
|
122
|
+
"id": 1,
|
|
123
|
+
"username": "damien"
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
#### Body Params
|
|
129
|
+
|
|
130
|
+
- `fields` containing `currentPassword` and `newPassword` e.g.
|
|
131
|
+
|
|
132
|
+
```json
|
|
133
|
+
"fields": {
|
|
134
|
+
"currentPassword": "strongpass",
|
|
135
|
+
"newPassword": "anotherstrongpass"
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
#### Cookies
|
|
140
|
+
|
|
141
|
+
- `accessToken` the access token that you acquired before
|
|
142
|
+
|
|
143
|
+
### 4. Logout
|
|
144
|
+
|
|
145
|
+
In order to logout from your account e.g. remove access and refresh cookies and also revoke your refresh token (access token lifetime is very short and doesn't need to be revoked) call `/auth/logout/` endpoint with `GET` method.
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
curl http://localhost:8000/api/auth/logout \
|
|
149
|
+
--cookie 'accessToken=<jwt-access-token>' \
|
|
150
|
+
--cookie 'refreshToken=<jwt-refresh-token>'
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Response
|
|
154
|
+
|
|
155
|
+
```json
|
|
156
|
+
{
|
|
157
|
+
"message": "Logout successful"
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
#### Cookies
|
|
162
|
+
|
|
163
|
+
- `accessToken` the access token that you acquired before
|
|
164
|
+
- `refreshToken` the refresh token that you acquired before
|
|
@@ -1,41 +1 @@
|
|
|
1
1
|
## Root
|
|
2
|
-
|
|
3
|
-
### 1. Transaction
|
|
4
|
-
|
|
5
|
-
To start a transaction call `/transaction` endpoint with `POST` method.
|
|
6
|
-
|
|
7
|
-
```bash
|
|
8
|
-
curl --request POST \
|
|
9
|
-
--url http://localhost:8000/api/transaction \
|
|
10
|
-
--header 'Content-Type: application/json' \
|
|
11
|
-
--data '{
|
|
12
|
-
"transaction": [
|
|
13
|
-
{
|
|
14
|
-
"statement": "INSERT INTO Artist (ArtistId, Name) VALUES (:id, :name)",
|
|
15
|
-
"values": { "id": 100000, "name": "Glen Hansard" }
|
|
16
|
-
},
|
|
17
|
-
{
|
|
18
|
-
"query": "SELECT * FROM Artist ORDER BY ArtistId DESC LIMIT 1"
|
|
19
|
-
}
|
|
20
|
-
]
|
|
21
|
-
}'
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
Response
|
|
25
|
-
|
|
26
|
-
```json
|
|
27
|
-
{
|
|
28
|
-
"data": [
|
|
29
|
-
{
|
|
30
|
-
"changes": 1,
|
|
31
|
-
"lastInsertRowid": 100000
|
|
32
|
-
},
|
|
33
|
-
[
|
|
34
|
-
{
|
|
35
|
-
"ArtistId": 100000,
|
|
36
|
-
"Name": "Glen Hansard"
|
|
37
|
-
}
|
|
38
|
-
]
|
|
39
|
-
]
|
|
40
|
-
}
|
|
41
|
-
```
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
## Rows in Auth mode
|
|
2
|
+
|
|
3
|
+
### 1. List Rows of a Table in Auth mode
|
|
4
|
+
|
|
5
|
+
To list rows in auth mode we call `/tables/<table-name>/rows/` endpoint with `GET` method and pass the jwt access token via Cookies.
|
|
6
|
+
|
|
7
|
+
> Note that your account needs to have access to read this table.
|
|
8
|
+
> Access (Authorization) in Soul is handled via "\_roles" table aka Roles.
|
|
9
|
+
> If you want to learn about granting permissions proceed to the next example.
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
curl 'localhost:8000/api/tables/Album/rows/' \
|
|
13
|
+
--cookie 'accessToken=<jwt-access-token>'
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Response
|
|
17
|
+
|
|
18
|
+
```json
|
|
19
|
+
{
|
|
20
|
+
"data": [
|
|
21
|
+
{
|
|
22
|
+
"AlbumId": 1,
|
|
23
|
+
"Title": "For Those About To Rock We Salute You",
|
|
24
|
+
"ArtistId": 1
|
|
25
|
+
},
|
|
26
|
+
{ "AlbumId": 2, "Title": "Balls to the Wall", "ArtistId": 2 }
|
|
27
|
+
// ...
|
|
28
|
+
],
|
|
29
|
+
"total": 347,
|
|
30
|
+
"next": "/tables/Album?page=2",
|
|
31
|
+
"previous": null
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
#### Cookies
|
|
36
|
+
|
|
37
|
+
- `accessToken` the access token that you acquired before
|
|
38
|
+
|
|
39
|
+
### 2. Granting access to users
|
|
40
|
+
|
|
41
|
+
Only super users (e.g. `is_superuser=true`) or those with roles that have access to '\_roles' table can grant access to other users.
|
|
42
|
+
|
|
43
|
+
> Head over to [README, _Updating Super Users_ section](/README.md#3-updating-super-users) to learn how to promote someone to a super user.
|
|
44
|
+
|
|
45
|
+
#### 2.1. Create a new Role
|
|
46
|
+
|
|
47
|
+
To create a new Role call `/tables/_roles/rows/` endpoint with `POST` method.
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
curl --request POST \
|
|
51
|
+
--url http://localhost:8000/api/tables/_roles/rows/ \
|
|
52
|
+
--header 'Content-Type: application/json' \
|
|
53
|
+
--header 'Cookie: accessToken=<jwt-access-token>' \
|
|
54
|
+
--data '{
|
|
55
|
+
"fields": {
|
|
56
|
+
"name": "editor"
|
|
57
|
+
}
|
|
58
|
+
}'
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Response
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"message": "Row inserted",
|
|
66
|
+
"data": {
|
|
67
|
+
"changes": 1,
|
|
68
|
+
"lastInsertRowid": 2
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Now that we have our `editor` Role, we can give it some permissions. Here we want to give it permission to `read` `Album` table.
|
|
74
|
+
|
|
75
|
+
#### 2.2. Create permissions for a Role
|
|
76
|
+
|
|
77
|
+
To create permissions for a Role call `/tables/_roles_permissions/rows/` endpoint with `POST` method.
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
curl --request POST \
|
|
81
|
+
--url http://localhost:8000/api/tables/_roles_permissions/rows/ \
|
|
82
|
+
--header 'Content-Type: application/json' \
|
|
83
|
+
--header 'Cookie: accessToken=<jwt-access-token>' \
|
|
84
|
+
--data '{
|
|
85
|
+
"fields": {
|
|
86
|
+
"role_id": 2,
|
|
87
|
+
"table_name": "Album",
|
|
88
|
+
"create": 0,
|
|
89
|
+
"read": 1,
|
|
90
|
+
"update": 0,
|
|
91
|
+
"delete": 0
|
|
92
|
+
}
|
|
93
|
+
}'
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Response
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"message": "Row inserted",
|
|
101
|
+
"data": {
|
|
102
|
+
"changes": 1,
|
|
103
|
+
"lastInsertRowid": 6
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
#### 2.3. Assign Role to a User
|
|
109
|
+
|
|
110
|
+
To assign roles to a user call `/tables/_users_roles/rows/` endpoint with `POST` method.
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
curl --request POST \
|
|
114
|
+
--url http://localhost:8000/api/tables/_users_roles/rows/ \
|
|
115
|
+
--header 'Content-Type: application/json' \
|
|
116
|
+
--header 'Cookie: accessToken=<jwt-access-token>' \
|
|
117
|
+
--data '{
|
|
118
|
+
"fields": {
|
|
119
|
+
"user_id": 1,
|
|
120
|
+
"role_id": 2
|
|
121
|
+
}
|
|
122
|
+
}'
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Response
|
|
126
|
+
|
|
127
|
+
```json
|
|
128
|
+
{
|
|
129
|
+
"message": "Row inserted",
|
|
130
|
+
"data": {
|
|
131
|
+
"changes": 1,
|
|
132
|
+
"lastInsertRowid": 2
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Now that we assigned `editor` role to a user, he / she can read the `Album` table.
|
package/docs/api-examples.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# API Examples
|
|
2
2
|
|
|
3
|
-
Soul
|
|
3
|
+
Soul consists of 4 main namespaces: Tables (`/tables/`), Rows (`/tables/{table-name}/rows/`), Auth (`/auth/`), and Root (`/`). In this document, we'll try to go over all of them so you can get familiar with how Soul works.
|
|
4
4
|
|
|
5
5
|
## Setup Environment
|
|
6
6
|
|
|
@@ -33,9 +33,11 @@ soul -d ./Chinook_Sqlite.sqlite -p 8000
|
|
|
33
33
|
|
|
34
34
|
## Namespaces
|
|
35
35
|
|
|
36
|
-
1. [/api/tables](api/tables-examples.md) Examples for Tables endpoints
|
|
37
|
-
2. [/api/rows](api/rows-examples.md) Examples for Rows endpoints
|
|
38
|
-
3. [/api/](api/
|
|
36
|
+
1. [/api/tables/](api/tables-examples.md) Examples for Tables endpoints
|
|
37
|
+
2. [/api/{table-name}/rows/](api/rows-examples.md) Examples for Rows endpoints
|
|
38
|
+
3. [/api/auth/](api/auth-examples.md) Examples for Authentication / Authorization endpoints
|
|
39
|
+
1. [/api/{table-name}/rows/](api/rows-auth-examples.md) Examples for Rows endpoints in Auth mode
|
|
40
|
+
4. [/api/](api/root-examples.md) Examples for Root endpoints
|
|
39
41
|
|
|
40
42
|
## Handling Errors
|
|
41
43
|
|
package/docs/auth.md
CHANGED
|
@@ -135,3 +135,9 @@ Additionally, it's important to note that the `/api/tables/_users/rows/` endpoin
|
|
|
135
135
|
When creating a user, the required fields are `username` and `password`. However, you also have the flexibility to include additional optional fields. To do this, you will need to modify the schema of the `_users` table in your database using a suitable database editor GUI tool. Simply add the desired field(s) to the database schema for the `_users` table. Once the schema is updated, you can pass the optional field(s) from your client application during user creation.
|
|
136
136
|
|
|
137
137
|
Furthermore, when retrieving user data, the endpoint automatically filters out sensitive information such as the `_hashed_password` and `_salt` fields. This precautionary measure is in place to address security concerns and ensure that only necessary and non-sensitive information is included in the returned results.
|
|
138
|
+
|
|
139
|
+
#### Revoked Refresh Tokens
|
|
140
|
+
|
|
141
|
+
When you send a request to log in to Soul using the `/token/obtain` endpoint, you will receive `Access` and `Refresh` tokens. These tokens can be stored in a secure client environment. You can then send a request to the `/token/refresh` endpoint to refresh your access token when it expires.
|
|
142
|
+
|
|
143
|
+
When you log out of Soul, the `Access` and `Refresh` tokens are removed. However, there might be instances where you log out before the refresh token expires, allowing these tokens to be reused by other users. To handle this issue, Soul saves removed refresh tokens temporarily in a table named `revoked_access_tokens`. Each time you attempt to refresh your access token, Soul checks if the `Refresh` token you are using is valid. If you try to reuse a revoked refresh token, Soul will throw an error.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "soul-cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.1",
|
|
4
4
|
"description": "A SQLite REST and Realtime server",
|
|
5
5
|
"main": "src/server.js",
|
|
6
6
|
"bin": {
|
|
@@ -51,7 +51,7 @@
|
|
|
51
51
|
"eslint-config-prettier": "^9.0.0",
|
|
52
52
|
"husky": "^8.0.3",
|
|
53
53
|
"jest": "^29.4.3",
|
|
54
|
-
"nodemon": "^
|
|
54
|
+
"nodemon": "^3.1.3",
|
|
55
55
|
"prettier": "3.1.0",
|
|
56
56
|
"supertest": "^6.3.3",
|
|
57
57
|
"swagger-autogen": "^2.23.1"
|
package/src/cli.js
CHANGED
|
@@ -46,6 +46,12 @@ if (process.env.NO_CLI !== 'true') {
|
|
|
46
46
|
type: 'string',
|
|
47
47
|
demandOption: false,
|
|
48
48
|
})
|
|
49
|
+
.options('env', {
|
|
50
|
+
alias: 'envpath',
|
|
51
|
+
describe: 'Environment variable file path to load',
|
|
52
|
+
type: 'string',
|
|
53
|
+
demandOption: false,
|
|
54
|
+
})
|
|
49
55
|
.options('a', {
|
|
50
56
|
alias: 'auth',
|
|
51
57
|
describe: 'Enable authentication and authorization',
|
package/src/config/index.js
CHANGED
|
@@ -10,7 +10,8 @@ module.exports = {
|
|
|
10
10
|
|
|
11
11
|
errorMessage: {
|
|
12
12
|
USERNAME_TAKEN_ERROR: 'This username is taken',
|
|
13
|
-
WEAK_PASSWORD_ERROR:
|
|
13
|
+
WEAK_PASSWORD_ERROR:
|
|
14
|
+
'This password is weak, it should be at least 8 characters long and contain a combination of lowercase letters, uppercase letters, numbers, and special characters',
|
|
14
15
|
DEFAULT_ROLE_NOT_CREATED_ERROR:
|
|
15
16
|
'Please restart soul so a default role can be created',
|
|
16
17
|
INVALID_USERNAME_PASSWORD_ERROR: 'Invalid username or password',
|
|
@@ -78,7 +78,7 @@ describe('Auth Endpoints', () => {
|
|
|
78
78
|
|
|
79
79
|
expect(res.status).toEqual(400);
|
|
80
80
|
expect(res.body.message).toBe(
|
|
81
|
-
'This password is weak,
|
|
81
|
+
'This password is weak, it should be at least 8 characters long and contain a combination of lowercase letters, uppercase letters, numbers, and special characters',
|
|
82
82
|
);
|
|
83
83
|
|
|
84
84
|
expect(res.body).not.toHaveProperty('password');
|
package/src/controllers/index.js
CHANGED
|
@@ -1,12 +1,11 @@
|
|
|
1
|
-
const db = require('../db/index');
|
|
2
1
|
const version = require('../../package.json').version;
|
|
3
2
|
|
|
4
3
|
// Root endpoint
|
|
5
4
|
const root = async (req, res) => {
|
|
6
|
-
/*
|
|
5
|
+
/*
|
|
7
6
|
#swagger.tags = ['Root']
|
|
8
|
-
#swagger.summary = 'Timestamp'
|
|
9
|
-
#swagger.description = 'Endpoint to return server timestamp'
|
|
7
|
+
#swagger.summary = 'Timestamp'
|
|
8
|
+
#swagger.description = 'Endpoint to return server timestamp'
|
|
10
9
|
*/
|
|
11
10
|
|
|
12
11
|
res.json({
|
|
@@ -18,77 +17,17 @@ const root = async (req, res) => {
|
|
|
18
17
|
});
|
|
19
18
|
};
|
|
20
19
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
// e.g. body:
|
|
24
|
-
// "transaction": [
|
|
25
|
-
// {
|
|
26
|
-
// "statement": "INSERT INTO users (id, firstName, lastName) VALUES (:id, :firstName, :lastName)",
|
|
27
|
-
// "values": { "id": 1, "firstName": "John", "lastName": "Doe" }
|
|
28
|
-
// },
|
|
29
|
-
// {
|
|
30
|
-
// "query": "SELECT * FROM users"
|
|
31
|
-
// }
|
|
32
|
-
// }
|
|
33
|
-
//
|
|
34
|
-
// response:
|
|
35
|
-
// "data": [
|
|
36
|
-
// {
|
|
37
|
-
// "changes": 1,
|
|
38
|
-
// "lastInsertRowid": 1
|
|
39
|
-
// },
|
|
40
|
-
// [
|
|
41
|
-
// {
|
|
42
|
-
// "id": 1,
|
|
43
|
-
// "createdAt": "2022-10-10 10:55:29",
|
|
44
|
-
// "updatedAt": "2022-10-10 10:55:29",
|
|
45
|
-
// "firstName": "John",
|
|
46
|
-
// "lastName": "Doe"
|
|
47
|
-
// }
|
|
48
|
-
// ]
|
|
49
|
-
// ]
|
|
50
|
-
//
|
|
51
|
-
|
|
52
|
-
const transaction = async (req, res) => {
|
|
53
|
-
/*
|
|
20
|
+
const health = async (req, res) => {
|
|
21
|
+
/*
|
|
54
22
|
#swagger.tags = ['Root']
|
|
55
|
-
#swagger.summary = '
|
|
56
|
-
#swagger.description = 'Endpoint to
|
|
57
|
-
#swagger.parameters['body'] = {
|
|
58
|
-
in: 'body',
|
|
59
|
-
required: true,
|
|
60
|
-
schema: { $ref: "#/definitions/TransactionRequestBody" }
|
|
61
|
-
}
|
|
23
|
+
#swagger.summary = 'Health Check'
|
|
24
|
+
#swagger.description = 'Endpoint to return server health status'
|
|
62
25
|
*/
|
|
63
|
-
const { transaction } = req.body;
|
|
64
|
-
const results = [];
|
|
65
|
-
try {
|
|
66
|
-
db.transaction(() => {
|
|
67
|
-
transaction.forEach((query) => {
|
|
68
|
-
if (query.statement) {
|
|
69
|
-
const { statement, values } = query;
|
|
70
|
-
const data = db.prepare(statement).run(values);
|
|
71
|
-
results.push(data);
|
|
72
|
-
} else if (query.query) {
|
|
73
|
-
const { query: queryString } = query;
|
|
74
|
-
const data = db.prepare(queryString).all();
|
|
75
|
-
results.push(data);
|
|
76
|
-
}
|
|
77
|
-
});
|
|
78
|
-
})();
|
|
79
26
|
|
|
80
|
-
|
|
81
|
-
data: results,
|
|
82
|
-
});
|
|
83
|
-
} catch (error) {
|
|
84
|
-
res.status(400).json({
|
|
85
|
-
message: error.message,
|
|
86
|
-
error: error,
|
|
87
|
-
});
|
|
88
|
-
}
|
|
27
|
+
res.send('OK');
|
|
89
28
|
};
|
|
90
29
|
|
|
91
30
|
module.exports = {
|
|
92
31
|
root,
|
|
93
|
-
|
|
32
|
+
health,
|
|
94
33
|
};
|
|
@@ -15,29 +15,10 @@ describe('Root Endpoints', () => {
|
|
|
15
15
|
});
|
|
16
16
|
});
|
|
17
17
|
|
|
18
|
-
describe('
|
|
19
|
-
it('
|
|
20
|
-
const res = await requestWithSupertest.
|
|
21
|
-
transaction: [
|
|
22
|
-
{
|
|
23
|
-
statement: `CREATE TABLE students (id INTEGER PRIMARY KEY, firstName TEXT, lastName TEXT)`,
|
|
24
|
-
values: {},
|
|
25
|
-
},
|
|
26
|
-
{
|
|
27
|
-
statement: `INSERT INTO students (id, firstName, lastName) VALUES (:id, :firstName, :lastName)`,
|
|
28
|
-
values: { id: 1, firstName: 'John', lastName: 'Doe' },
|
|
29
|
-
},
|
|
30
|
-
{
|
|
31
|
-
query: `SELECT * FROM students`,
|
|
32
|
-
},
|
|
33
|
-
],
|
|
34
|
-
});
|
|
35
|
-
|
|
18
|
+
describe('Health Endpoints', () => {
|
|
19
|
+
it('GET /health should return server version and timestamp', async () => {
|
|
20
|
+
const res = await requestWithSupertest.get('/api/health');
|
|
36
21
|
expect(res.status).toEqual(200);
|
|
37
|
-
expect(res.type).toEqual(expect.stringContaining('
|
|
38
|
-
expect(res.body).toHaveProperty('data');
|
|
39
|
-
expect(res.body.data).toEqual(expect.any(Array));
|
|
40
|
-
expect(res.body.data[0]).toHaveProperty('changes');
|
|
41
|
-
expect(res.body.data[0]).toHaveProperty('lastInsertRowid');
|
|
22
|
+
expect(res.type).toEqual(expect.stringContaining('text'));
|
|
42
23
|
});
|
|
43
24
|
});
|
package/src/index.js
CHANGED
|
@@ -28,10 +28,8 @@ const {
|
|
|
28
28
|
|
|
29
29
|
const { runCLICommands } = require('./commands');
|
|
30
30
|
const { authConstants } = require('./constants');
|
|
31
|
+
|
|
31
32
|
const app = express();
|
|
32
|
-
app.get('/health', (req, res) => {
|
|
33
|
-
res.send('OK');
|
|
34
|
-
});
|
|
35
33
|
|
|
36
34
|
app.use(bodyParser.json());
|
|
37
35
|
app.use(cookieParser());
|
package/src/routes/index.js
CHANGED
|
@@ -1,16 +1,10 @@
|
|
|
1
1
|
const express = require('express');
|
|
2
2
|
|
|
3
3
|
const controllers = require('../controllers/index');
|
|
4
|
-
const { validator } = require('../middlewares/validation');
|
|
5
|
-
const schema = require('../schemas/index');
|
|
6
4
|
|
|
7
5
|
const router = express.Router();
|
|
8
6
|
|
|
9
7
|
router.get('/', controllers.root);
|
|
10
|
-
router.
|
|
11
|
-
'/transaction',
|
|
12
|
-
validator(schema.transaction),
|
|
13
|
-
controllers.transaction
|
|
14
|
-
);
|
|
8
|
+
router.get('/health', controllers.health);
|
|
15
9
|
|
|
16
10
|
module.exports = router;
|
package/src/swagger/index.js
CHANGED
|
@@ -152,7 +152,8 @@ const doc = {
|
|
|
152
152
|
},
|
|
153
153
|
|
|
154
154
|
WeakPasswordErrorResponse: {
|
|
155
|
-
message:
|
|
155
|
+
message:
|
|
156
|
+
'This password is weak, it should be at least 8 characters long and contain a combination of lowercase letters, uppercase letters, numbers, and special characters',
|
|
156
157
|
},
|
|
157
158
|
|
|
158
159
|
UsernameTakenErrorResponse: {
|
package/src/swagger/swagger.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"swagger": "2.0",
|
|
3
3
|
"info": {
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.8.0",
|
|
5
5
|
"title": "Soul API",
|
|
6
6
|
"description": "API Documentation for <b>Soul</b>, a SQLite REST and realtime server. "
|
|
7
7
|
},
|
|
@@ -30,17 +30,6 @@
|
|
|
30
30
|
"consumes": ["application/json"],
|
|
31
31
|
"produces": ["application/json"],
|
|
32
32
|
"paths": {
|
|
33
|
-
"/health": {
|
|
34
|
-
"get": {
|
|
35
|
-
"description": "",
|
|
36
|
-
"parameters": [],
|
|
37
|
-
"responses": {
|
|
38
|
-
"200": {
|
|
39
|
-
"description": "OK"
|
|
40
|
-
}
|
|
41
|
-
}
|
|
42
|
-
}
|
|
43
|
-
},
|
|
44
33
|
"/api/": {
|
|
45
34
|
"get": {
|
|
46
35
|
"tags": ["Root"],
|
|
@@ -54,27 +43,15 @@
|
|
|
54
43
|
}
|
|
55
44
|
}
|
|
56
45
|
},
|
|
57
|
-
"/api/
|
|
58
|
-
"
|
|
46
|
+
"/api/health": {
|
|
47
|
+
"get": {
|
|
59
48
|
"tags": ["Root"],
|
|
60
|
-
"summary": "
|
|
61
|
-
"description": "Endpoint to
|
|
62
|
-
"parameters": [
|
|
63
|
-
{
|
|
64
|
-
"name": "body",
|
|
65
|
-
"in": "body",
|
|
66
|
-
"required": true,
|
|
67
|
-
"schema": {
|
|
68
|
-
"$ref": "#/definitions/TransactionRequestBody"
|
|
69
|
-
}
|
|
70
|
-
}
|
|
71
|
-
],
|
|
49
|
+
"summary": "Health Check",
|
|
50
|
+
"description": "Endpoint to return server health status",
|
|
51
|
+
"parameters": [],
|
|
72
52
|
"responses": {
|
|
73
53
|
"200": {
|
|
74
54
|
"description": "OK"
|
|
75
|
-
},
|
|
76
|
-
"400": {
|
|
77
|
-
"description": "Bad Request"
|
|
78
55
|
}
|
|
79
56
|
}
|
|
80
57
|
}
|
|
@@ -890,7 +867,7 @@
|
|
|
890
867
|
"properties": {
|
|
891
868
|
"message": {
|
|
892
869
|
"type": "string",
|
|
893
|
-
"example": "This password is weak,
|
|
870
|
+
"example": "This password is weak, it should be at least 8 characters long and contain a combination of lowercase letters, uppercase letters, numbers, and special characters"
|
|
894
871
|
}
|
|
895
872
|
}
|
|
896
873
|
},
|