soul-cli 0.6.1 → 0.7.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.
Files changed (66) hide show
  1. package/.all-contributorsrc +73 -0
  2. package/.editorconfig +26 -0
  3. package/.env.sample +9 -0
  4. package/.eslintignore +2 -0
  5. package/.eslintrc.js +24 -0
  6. package/.github/ISSUE_TEMPLATE/bug_report.md +38 -0
  7. package/.github/ISSUE_TEMPLATE/feature_request.md +20 -0
  8. package/.github/workflows/npm-publish.yml +23 -0
  9. package/.husky/pre-commit +5 -0
  10. package/CONTRIBUTING.md +92 -0
  11. package/LICENSE +21 -0
  12. package/README.md +188 -1
  13. package/docs/api/root-examples.md +41 -0
  14. package/docs/api/rows-examples.md +225 -0
  15. package/docs/api/tables-examples.md +217 -0
  16. package/docs/api-examples.md +62 -0
  17. package/docs/auth-db-diagram.png +0 -0
  18. package/docs/auth.md +135 -0
  19. package/docs/extensions-examples.md +167 -0
  20. package/docs/logo.png +0 -0
  21. package/docs/soul-studio.png +0 -0
  22. package/docs/ws/rows-examples.md +122 -0
  23. package/docs/ws-examples.md +42 -0
  24. package/package.json +17 -2
  25. package/src/cli.js +59 -1
  26. package/src/commands.js +22 -0
  27. package/src/config/index.js +48 -3
  28. package/src/constants/api.js +26 -0
  29. package/src/constants/auth.js +5 -0
  30. package/src/constants/index.js +13 -0
  31. package/src/constants/messages.js +41 -0
  32. package/src/constants/roles.js +3 -0
  33. package/src/constants/tables.js +47 -0
  34. package/src/controllers/auth/common.js +16 -0
  35. package/src/controllers/auth/index.js +5 -0
  36. package/src/controllers/auth/tables.js +96 -0
  37. package/src/controllers/auth/token.js +243 -0
  38. package/src/controllers/auth/user.js +394 -0
  39. package/src/controllers/auth.test.js +372 -0
  40. package/src/controllers/rows.js +48 -55
  41. package/src/controllers/rows.test.js +146 -40
  42. package/src/controllers/tables.test.js +58 -28
  43. package/src/db/schema.js +118 -0
  44. package/src/index.js +33 -4
  45. package/src/middlewares/api.js +79 -0
  46. package/src/middlewares/auth.js +85 -0
  47. package/src/middlewares/broadcast.js +1 -1
  48. package/src/middlewares/validation.js +3 -2
  49. package/src/routes/auth.js +29 -0
  50. package/src/routes/rows.js +17 -5
  51. package/src/routes/tables.js +26 -4
  52. package/src/schemas/auth.js +67 -0
  53. package/src/schemas/index.js +6 -1
  54. package/src/schemas/rows.js +20 -0
  55. package/src/schemas/tables.js +18 -2
  56. package/src/server.js +3 -2
  57. package/src/services/authService.js +78 -0
  58. package/src/services/index.js +2 -1
  59. package/src/services/rowService.js +36 -7
  60. package/src/services/tableService.js +127 -1
  61. package/src/swagger/index.js +67 -0
  62. package/src/swagger/swagger.json +292 -60
  63. package/src/tests/index.js +4 -5
  64. package/src/tests/testData.js +23 -10
  65. package/src/utils/index.js +78 -0
  66. /package/{src/services/.gitkeep → docs/extensions/api-examples.js} +0 -0
@@ -0,0 +1,225 @@
1
+ ## Rows
2
+
3
+ ### 1. List Rows of a Table
4
+
5
+ To list all (or some of) rows we simply call `/tables/<table-name>/rows/` endpoint with `GET` method.
6
+
7
+ ```bash
8
+ curl 'localhost:8000/api/tables/Album/rows/'
9
+ ```
10
+
11
+ Response
12
+
13
+ ```json
14
+ {
15
+ "data": [
16
+ {
17
+ "AlbumId": 1,
18
+ "Title": "For Those About To Rock We Salute You",
19
+ "ArtistId": 1
20
+ },
21
+ { "AlbumId": 2, "Title": "Balls to the Wall", "ArtistId": 2 }
22
+ // ...
23
+ ],
24
+ "total": 347,
25
+ "next": "/tables/Album?page=2",
26
+ "previous": null
27
+ }
28
+ ```
29
+
30
+ #### Query Params
31
+
32
+ - `_page` e.g. `?_page=2`, to get the second page of results.
33
+ - `_limit` e.g. `?_limit=20`, to get 20 results per page.
34
+ - `_search` e.g. `?_search=rock`, to search across all fields.
35
+ - `_ordering` e.g. `?_ordering=-Title`, to order rows by title descending, or without `-` to sort ascending, e.g. `?_ordering=Title`
36
+ - `_schema` e.g. `?_schema=Title,ArtistId`, to get only the Title and ArtistId columns.
37
+ - `_extend` e.g. `?_extend=ArtistId`, to get the Artist object related to the Album.
38
+ - `_filters` e.g. `?_filters=ArtistId:[1,2,3],Title:Rock`, to get only the rows where the ArtistId can be 1,2 or 3 and the Title is Rock.
39
+ NOTE: If you want to use comparison operators in the filter, you can use these operators after the field: `__eq, __neq, __lt, __gt, __lte, __gte, __null, __notnull` . For example, you can use `/invoices/rows?_filters=InvoiceId__neq:1,Total__gte:5,BillingPostalCode__notnull`
40
+
41
+ Example with query params
42
+
43
+ ```bash
44
+ curl 'localhost:8000/api/tables/Album/rows?_page=1&_limit=20&_search=rock&_ordering=-Title&_schema=Title,ArtistId&_extend=ArtistId&_filters=ArtistId:90'
45
+ ```
46
+
47
+ Response
48
+
49
+ ```json
50
+ {
51
+ "data": [
52
+ {
53
+ "Title": "Rock In Rio [CD2]",
54
+ "ArtistId": 90,
55
+ "ArtistId_data": { "ArtistId": 90, "Name": "Iron Maiden" }
56
+ },
57
+ {
58
+ "Title": "Rock In Rio [CD1]",
59
+ "ArtistId": 90,
60
+ "ArtistId_data": { "ArtistId": 90, "Name": "Iron Maiden" }
61
+ }
62
+ ],
63
+ "total": 2,
64
+ "next": null,
65
+ "previous": null
66
+ }
67
+ ```
68
+
69
+ ### 2. Insert a New Row
70
+
71
+ To insert a new row to a `table` call `/tables/<table-name>/rows/` endpoint with `POST` method.
72
+
73
+ ```bash
74
+ curl --request POST \
75
+ --url http://localhost:8000/api/tables/Employee/rows \
76
+ --header 'Content-Type: application/json' \
77
+ --data '{
78
+ "fields": {
79
+ "FirstName": "Damien",
80
+ "LastName": "Rice"
81
+ }
82
+ }'
83
+ ```
84
+
85
+ Response
86
+
87
+ ```json
88
+ {
89
+ "message": "Row inserted",
90
+ "data": {
91
+ "changes": 1,
92
+ "lastInsertRowid": 9
93
+ }
94
+ }
95
+ ```
96
+
97
+ #### Body Params
98
+
99
+ - `fields` e.g.
100
+
101
+ ```json
102
+ "fields": {
103
+ // fields values for the new row
104
+ }
105
+ ```
106
+
107
+ ### 3. Get Row(s) by ID
108
+
109
+ To get a row call `/tables/<table-name>/rows/<lookup-values>/` endpoint with `GET` method.
110
+
111
+ ```bash
112
+ curl http://localhost:8000/api/tables/Album/rows/1/
113
+ ```
114
+
115
+ Response
116
+
117
+ ```json
118
+ {
119
+ "data": {
120
+ "AlbumId": 1,
121
+ "Title": "For Those About To Rock We Salute You",
122
+ "ArtistId": 1
123
+ }
124
+ }
125
+ ```
126
+
127
+ #### Path Params
128
+
129
+ - `lookup-values` e.g. `1`, to get the row with the AlbumId 1. or comma-separated values e.g. `1,2`, to get the rows with the AlbumId 1 and 2. (Bulk Retrieve)
130
+
131
+ #### Query Params
132
+
133
+ - `_lookup_field` e.g. `?_lookup_field=ArtistId`, to get the row by the ArtistId field. If not provided, the default lookup field is the primary key of the table.
134
+ - `_schema` e.g. `?_schema=Title,ArtistId`, to get only the Title and ArtistId columns.
135
+ - `_extend` e.g. `?_extend=ArtistId`, to get the Artist object related to the Album.
136
+
137
+ Example with query params
138
+
139
+ ```bash
140
+ curl 'http://localhost:8000/api/tables/Album/rows/Facelift?_lookup_field=Title&_extend=ArtistId&_schema=Title'
141
+ ```
142
+
143
+ Response
144
+
145
+ ```json
146
+ {
147
+ "data": {
148
+ "Title": "Facelift",
149
+ "ArtistId_data": {
150
+ "ArtistId": 5,
151
+ "Name": "Alice In Chains"
152
+ }
153
+ }
154
+ }
155
+ ```
156
+
157
+ ### 4. Update Row(s) by ID
158
+
159
+ To update a row call `/tables/<table-name>/rows/<lookup-values>/` endpoint with `PUT` method.
160
+
161
+ ```bash
162
+ curl --request PUT \
163
+ --url http://localhost:8000/api/tables/Album/rows/7 \
164
+ --header 'Content-Type: application/json' \
165
+ --data '{
166
+ "fields": {
167
+ "Title": "FaceElevate"
168
+ }
169
+ }'
170
+ ```
171
+
172
+ Response
173
+
174
+ ```json
175
+ {
176
+ "message": "Row updated"
177
+ }
178
+ ```
179
+
180
+ #### Path Params
181
+
182
+ - `lookup-values` e.g. `1`, to update the row with the AlbumId 1. or comma-separated values e.g. `1,2`, to update the rows with the AlbumId 1 and 2. (Bulk Update)
183
+
184
+ #### Query Params
185
+
186
+ - `_lookup_field` e.g. `?_lookup_field=ArtistId`, to update the row by the ArtistId field. If not provided, the default lookup field is the primary key of the table.
187
+
188
+ #### Body Params
189
+
190
+ - `fields` e.g.
191
+
192
+ ```json
193
+ "fields": {
194
+ // fields values to update
195
+ }
196
+ ```
197
+
198
+ ### 5. Delete Row(s) by ID
199
+
200
+ To delete a row call `/tables/<table-name>/rows/<lookup-values>/` endpoint with `DELETE` method.
201
+
202
+ ```bash
203
+ curl --request DELETE \
204
+ --url http://localhost:8000/api/tables/PlaylistTrack/rows/1
205
+ ```
206
+
207
+ Response
208
+
209
+ ```json
210
+ {
211
+ "message": "Row deleted",
212
+ "data": {
213
+ "changes": 3290,
214
+ "lastInsertRowid": 0
215
+ }
216
+ }
217
+ ```
218
+
219
+ #### Path Params
220
+
221
+ - `lookup-values` e.g. `1`, to delete the row with the AlbumId 1. or comma-separated values e.g. `1,2`, to delete the rows with the AlbumId 1 and 2. (Bulk Delete)
222
+
223
+ #### Query Params
224
+
225
+ - `_lookup_field` e.g. `?_lookup_field=ArtistId`, to delete the row by the ArtistId field. If not provided, the default lookup field is the primary key of the table.
@@ -0,0 +1,217 @@
1
+ ## Tables
2
+
3
+ ### 1. List Tables
4
+
5
+ To list all tables we simply call `/tables` endpoint with `GET` method.
6
+
7
+ ```bash
8
+ curl 'localhost:8000/api/tables'
9
+ ```
10
+
11
+ Response
12
+
13
+ ```json
14
+ {
15
+ "data": [
16
+ { "name": "Album" },
17
+ { "name": "Artist" }
18
+ // ...
19
+ ]
20
+ }
21
+ ```
22
+
23
+ #### Query Params
24
+
25
+ - `_search` e.g. `?_search=art`, to search between tables.
26
+ - `_ordering` e.g. `?_ordering=-name`, to order tables by name descending, or without `-` to sort ascending, e.g. `?_ordering=name`
27
+
28
+ Example with query params
29
+
30
+ ```bash
31
+ curl 'localhost:8000/api/tables?_search=pl&_ordering=-name'
32
+ ```
33
+
34
+ Response
35
+
36
+ ```json
37
+ {
38
+ "data": [
39
+ { "name": "Playlist" },
40
+ { "name": "PlaylistTrack" },
41
+ { "name": "Employee" }
42
+ // ...
43
+ ]
44
+ }
45
+ ```
46
+
47
+ ### 2. Create Tables
48
+
49
+ To create a new table use the following `POST` endpoint.
50
+
51
+ ```bash
52
+ curl --request POST \
53
+ --url http://localhost:8000/api/tables \
54
+ --header 'Content-Type: application/json' \
55
+ --data '{
56
+ "name": "pets",
57
+ "autoAddCreatedAt": true,
58
+ "autoAddUpdatedAt": false,
59
+ "schema": [
60
+ {
61
+ "name": "name",
62
+ "type": "Text",
63
+ "index": true
64
+ },
65
+ {
66
+ "name": "birth_date",
67
+ "type": "Date",
68
+ "notNull": true
69
+ },
70
+ {
71
+ "name": "owner_id",
72
+ "type": "Integer",
73
+ "foreignKey": {
74
+ "table": "artists",
75
+ "column": "ArtistId",
76
+ "onDelete": "CASCADE",
77
+ "onUpdate": "CASCADE"
78
+ }
79
+ }
80
+ ]
81
+ }'
82
+
83
+ ```
84
+
85
+ Response
86
+
87
+ ```json
88
+ {
89
+ "message": "Table created",
90
+ "data": {
91
+ "name": "pets",
92
+ "schema": [
93
+ {
94
+ "cid": 0,
95
+ "name": "createdAt",
96
+ "type": "DATETIME",
97
+ "notnull": 0,
98
+ "dflt_value": "CURRENT_TIMESTAMP",
99
+ "pk": 0
100
+ },
101
+ {
102
+ "cid": 1,
103
+ "name": "id",
104
+ "type": "INTEGER",
105
+ "notnull": 0,
106
+ "dflt_value": null,
107
+ "pk": 1
108
+ },
109
+ {
110
+ "cid": 2,
111
+ "name": "name",
112
+ "type": "TEXT",
113
+ "notnull": 0,
114
+ "dflt_value": null,
115
+ "pk": 0
116
+ },
117
+ {
118
+ "cid": 3,
119
+ "name": "birth_date",
120
+ "type": "Date",
121
+ "notnull": 1,
122
+ "dflt_value": null,
123
+ "pk": 0
124
+ },
125
+ {
126
+ "cid": 4,
127
+ "name": "owner_id",
128
+ "type": "INTEGER",
129
+ "notnull": 0,
130
+ "dflt_value": null,
131
+ "pk": 0
132
+ }
133
+ ]
134
+ }
135
+ }
136
+ ```
137
+
138
+ #### Body Params
139
+
140
+ - `name` e.g. `name: pets`, to be used as the table name
141
+ - `autoAddCreatedAt` e.g. `autoAddCreatedAt: false` to automatically add a created at field, default `true`
142
+ - `autoAddUpdatedAt` e.g. `autoAddCreatedAt: false` to automatically add a updated at field, default `true`
143
+ - `schema` e.g.
144
+
145
+ ```json
146
+ "schema": [
147
+ {
148
+ "name": "name", // field name (required)
149
+ "type": "TEXT", // field type (required) (one of `TEXT | NUMERIC | INTEGER | REAL | BLOB | BOOLEAN | DATE | DATETIME)
150
+ "index": true, // should this field be indexed?
151
+ "default": "John", // field default value
152
+ "notNull": false, // should this field be non-nullable?
153
+ "unique": false, // should this field be unique?
154
+ "primaryKey": true // should this field be the primaryKey? if false Soul will add an auto-increment primary key field
155
+ },
156
+ {
157
+ "name": "user_id",
158
+ "foreignKey": {
159
+ "table": "users", // foreign key table
160
+ "column": "id", // foreign key related field
161
+ "onDelete": "CASCADE", // on delete constraint (on of CASCADE | SET NULL | SET DEFAULT | RESTRICT)
162
+ "onUpdate": "CASCADE" // on update constraint (on of CASCADE | SET NULL | SET DEFAULT | RESTRICT)
163
+ }
164
+ },
165
+ // ...
166
+ ]
167
+ ```
168
+
169
+ ### 3. Get a Table's Schema
170
+
171
+ To get a table's schema call `/tables/<table-name>` endpoint with `GET` method.
172
+
173
+ ```bash
174
+ curl 'localhost:8000/api/tables/genres'
175
+ ```
176
+
177
+ Response
178
+
179
+ ```json
180
+ {
181
+ "data": [
182
+ {
183
+ "cid": 0,
184
+ "name": "GenreId",
185
+ "type": "INTEGER",
186
+ "notnull": 1,
187
+ "dflt_value": null,
188
+ "pk": 1
189
+ },
190
+ {
191
+ "cid": 1,
192
+ "name": "Name",
193
+ "type": "NVARCHAR(120)",
194
+ "notnull": 0,
195
+ "dflt_value": null,
196
+ "pk": 0
197
+ }
198
+ ]
199
+ }
200
+ ```
201
+
202
+ ### 4. Delete / Drop a Table
203
+
204
+ > CAUTION: Be careful when using this endpoint, it will delete the table and all its data.
205
+
206
+ To delete a table call `/tables/<table-name>` with a `DELETE` endpoint.
207
+
208
+ ```bash
209
+ curl --request DELETE \
210
+ --url http://localhost:8000/api/tables/pets
211
+ ```
212
+
213
+ Response
214
+
215
+ ```json
216
+ { "message": "Table deleted" }
217
+ ```
@@ -0,0 +1,62 @@
1
+ # API Examples
2
+
3
+ Soul is consist of 3 main namespaces: `/tables`, `/rows` and `/`. In this document we'll try to go over all of them so you can get familiar with how Soul works.
4
+
5
+ ## Setup Environment
6
+
7
+ To follow the below examples we need to download a sample database and also install Soul CLI.
8
+
9
+ ### Download Sample Database
10
+
11
+ ```bash
12
+ wget https://raw.githubusercontent.com/lerocha/chinook-database/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite # Download sample sqlite database
13
+ ```
14
+ ### Using Soul CLI
15
+ ```bash
16
+ npm install -g soul-cli
17
+ soul -d ./Chinook_Sqlite.sqlite -p 8000
18
+ ```
19
+
20
+ <details>
21
+ <summary>Or Using Local Development</summary>
22
+
23
+ ```bash
24
+ git clone https://github.com/thevahidal/soul # Clone project
25
+ npm install # Install dependencies
26
+ npm link # might need `sudo`
27
+ soul -d ./Chinook_Sqlite.sqlite -p 8000
28
+ ```
29
+ </details>
30
+
31
+
32
+ ## Namespaces
33
+
34
+ 1. [/api/tables](/docs/api/tables-examples.md) Examples for Tables endpoints
35
+ 2. [/api/rows](/docs/api/rows-examples.md) Examples for Rows endpoints
36
+ 3. [/api/](/docs/api/root-examples.md) Examples for Root endpoints
37
+
38
+
39
+ ## Handling Errors
40
+
41
+ If an error occurs while processing a request, it will be indicated via the presence of an `error` key and a `message` in the JSON response. For example:
42
+
43
+ ```bash
44
+ curl --request POST \
45
+ --url http://localhost:8000/api/tables \
46
+ --header 'Content-Type: application/json' \
47
+ --data '{
48
+ "name": "Artist", # note that we already have an `artists` table
49
+ "schema": [
50
+ # ...
51
+ ]
52
+ }'
53
+ ```
54
+
55
+ ```json
56
+ {
57
+ "message": "table artists already exists",
58
+ "error": {
59
+ "code": "SQLITE_ERROR"
60
+ }
61
+ }
62
+ ```
Binary file
package/docs/auth.md ADDED
@@ -0,0 +1,135 @@
1
+ ## User Authentication in Soul
2
+
3
+ Soul incorporates a robust user authentication system that handles user accounts, groups, permissions, and cookie-based user sessions. This section provides an overview of how the default implementation works.
4
+
5
+ Authentication is switched off by default in Soul, but is enabled when either of the `-a` or `--auth` flags are provided at the command line.
6
+
7
+ ### Overview
8
+
9
+ The Soul authentication system handles both authentication and authorization. Briefly, authentication verifies a user is who they claim to be, and authorization determines what an authenticated user is allowed to do. Here, the term "authentication" is used to refer to both tasks.
10
+
11
+ The auth system consists of:
12
+
13
+ - Users
14
+ - Roles and Permissions: A generic way of applying labels and permissions to more than one user.
15
+ - A password hashing system
16
+ - APIs for logging in users or restricting content
17
+ - JWT based access tokens
18
+
19
+ The authentication system in Soul aims to be very generic and doesn't provide some features commonly found in web authentication systems, such as:
20
+
21
+ - Password strength checking
22
+ - Throttling of login attempts
23
+ - Authentication against third-parties (OAuth, for example)
24
+ - Object-level permissions
25
+
26
+ ![auth-db-diagram](./auth-db-diagram.png)
27
+
28
+ <center style="font-size: 12px; color: gray">Figure 1: Soul Authentication Database Diagram</center>
29
+
30
+ #### Users
31
+
32
+ The `_users` table serves as the central component of the authentication system. Each row in the `_users` table represents an individual who interacts with your Soul instance. This table is crucial for enabling various functionalities, such as access restriction, and user registration.
33
+
34
+ **_Superusers_**, distinguished by the `is_superuser` attribute set to true, are a special type of user in Soul. They can bypass any permissions and restrictions, effectively granting them "God-mode" within the system, including being able to access the `/api/tables` and `/api` end-points. Authorization limitations do not apply to superusers.
35
+
36
+ The attributes of the `_users` table are:
37
+
38
+ - id int
39
+ - username varchar
40
+ - \_hashed_password varchar
41
+ - \_salt varchar
42
+ - is_superuser boolean
43
+ - created_at datetime
44
+ - updated_at datetime
45
+
46
+ Note that when Soul boots up, it looks for a table called `_users` (Otherwise Soul creates `_users` table) which holds the Users mentioned above.
47
+
48
+ ##### Modifying Superusers
49
+
50
+ Due to the sensitive nature of the superuser status, it is not possible to change the `is_superuser` attribute of a user through the API.
51
+
52
+ Instead, you can update superusers using the command line.
53
+
54
+ ```
55
+ $ node src/server.js updateuser --id=1 --password=newstrongstring // To update password of a superuser with id 1
56
+ $ node src/server.js updateuser --id=1 --is_superuser=true // To promote a user with id 1 to superuser
57
+ ```
58
+
59
+ #### Roles
60
+
61
+ Roles are a generic way of categorizing users so you can assign permissions to those users. A user can belong to any number of roles.
62
+
63
+ If we have an `editor` role, and a `_roles_permissions` entry for the `posts` table that allows `update`, then any user with that role will be able to update `posts`.
64
+
65
+ The attributes of the `_roles` table are:
66
+
67
+ - id int
68
+ - name varchar
69
+ - created_at datetime
70
+ - updated_at datetime
71
+
72
+ ##### Roles Permissions
73
+
74
+ Using a table called `_roles_permissions` we can assign permissions to roles.
75
+
76
+ The attributes of this table are:
77
+
78
+ - id int
79
+ - role_id int
80
+ - table_name varchar
81
+ - create boolean
82
+ - read boolean
83
+ - update boolean
84
+ - delete boolean
85
+
86
+ There is unique constraint on the combination of `role_id` and `table_name` attributes,
87
+ to prevent duplication of permissions for the same role and table.
88
+
89
+ ###### Default Role
90
+
91
+ Once a new table is created, Soul will automatically create a new `_roles_permissions` row for the `default` role and the new table, with the following permissions:
92
+
93
+ - create: false
94
+ - read: true
95
+ - update: false
96
+ - delete: false
97
+
98
+ Which basically means that any user can read the table data, but can't create, update or delete data.
99
+
100
+ Soul uses the `default` role to assign permissions to new users.
101
+
102
+ The same happens when Soul boots up, but for all existing tables, making sure that all tables have the `default` role assigned to them.
103
+
104
+ ##### Users Roles
105
+
106
+ To assign roles to users we have a join table called `_users_roles` with the following attributes:
107
+
108
+ - id int
109
+ - user_id int
110
+ - role_id int
111
+
112
+ #### Authentication
113
+
114
+ Soul uses cookies and middleware to hook the authentication system into request objects.
115
+
116
+ These provide a `req.user` attribute on every request, which represents the current user. If the current user has not logged in, it is set to null.
117
+
118
+ #### Obtain Access Token
119
+
120
+ To be able to use private APIs, users need to obtain an access token, which is a JWT token consisting of this payload:
121
+
122
+ - username
123
+ - is_superuser
124
+ - roles
125
+
126
+ For security reasons, Access tokens have a very short lifetime, and once expired, they can be refreshed using another API called Refresh Access token. Refresh tokens have a much longer lifetime, and both access and refresh tokens are provided to the user upon logging in.
127
+
128
+ #### Register New Users
129
+
130
+ To register new users, you need to create a new user using the `/api/tables/_users/rows/` endpoint, and then assign roles to that user using the `/api/tables/_users_roles/rows/` endpoint.
131
+ Note that you need to be logged in using a user with a role that has creating users permission.
132
+
133
+ Additionally, it's important to note that the `/api/tables/_users/rows/` endpoint functions slightly differently compared to other `/api/tables/<table_name>/rows/` endpoints. When creating or updating user data through this endpoint, we need to provide the raw passwords, which are then automatically hashed before being stored in the `_hashed_password` field. This extra step enhances the security of the stored passwords.
134
+
135
+ 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.