soul-cli 0.8.1 → 0.9.3

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 (71) hide show
  1. package/.all-contributorsrc +9 -0
  2. package/.bruno/auth/folder.bru +8 -0
  3. package/.bruno/auth/obtain-access-token.bru +25 -0
  4. package/.bruno/bruno.json +6 -0
  5. package/.bruno/environments/local.bru +3 -0
  6. package/.bruno/rows/folder.bru +8 -0
  7. package/.bruno/rows/list-rows-with-ordering.bru +25 -0
  8. package/.bruno/tables/folder.bru +8 -0
  9. package/.bruno/tables/list-tables.bru +16 -0
  10. package/.env.sample +11 -2
  11. package/.github/dependabot.yml +9 -0
  12. package/.github/workflows/ci.yml +33 -0
  13. package/.github/workflows/npm-publish.yml +19 -6
  14. package/.husky/pre-commit +0 -3
  15. package/README.md +46 -7
  16. package/ROADMAP.md +154 -0
  17. package/assets/images/soul-RA-app.png +0 -0
  18. package/assets/images/soul-standalone.png +0 -0
  19. package/docs/extensions-examples.md +96 -16
  20. package/docs/self-hosting.md +54 -0
  21. package/docs/ws-examples.md +4 -0
  22. package/eslint.config.js +29 -0
  23. package/package.json +40 -20
  24. package/scripts/dev.sh +64 -0
  25. package/src/cli.test.js +128 -0
  26. package/src/config/index.js +10 -2
  27. package/src/config/index.test.js +120 -0
  28. package/src/controllers/auth/common.js +1 -16
  29. package/src/controllers/auth/common.test.js +23 -0
  30. package/src/controllers/auth/tables.js +1 -1
  31. package/src/controllers/auth/token.js +30 -7
  32. package/src/controllers/auth/user.js +20 -20
  33. package/src/controllers/auth/user.test.js +232 -0
  34. package/src/controllers/auth.test.js +445 -0
  35. package/src/controllers/rows.js +183 -120
  36. package/src/controllers/rows.test.js +119 -2
  37. package/src/controllers/tables.js +63 -17
  38. package/src/controllers/tables.test.js +185 -0
  39. package/src/db/index.test.js +21 -0
  40. package/src/extensions.js +105 -36
  41. package/src/extensions.test.js +340 -0
  42. package/src/index.js +29 -20
  43. package/src/index.test.js +118 -0
  44. package/src/middlewares/api.js +1 -1
  45. package/src/middlewares/api.test.js +29 -0
  46. package/src/middlewares/auth.js +11 -48
  47. package/src/middlewares/auth.test.js +105 -0
  48. package/src/middlewares/validation.test.js +60 -0
  49. package/src/schemas/index.js +3 -1
  50. package/src/schemas/rows.js +16 -6
  51. package/src/schemas/tables.js +28 -4
  52. package/src/server.js +83 -1
  53. package/src/services/authService.js +33 -3
  54. package/src/services/authService.test.js +115 -0
  55. package/src/services/rowService.js +39 -14
  56. package/src/services/rowService.test.js +153 -0
  57. package/src/services/tableService.js +15 -17
  58. package/src/services/tableService.test.js +190 -0
  59. package/src/swagger/swagger.json +4 -7
  60. package/src/tests/globalSetup.js +8 -1
  61. package/src/tests/index.js +23 -0
  62. package/src/utils/index.js +25 -2
  63. package/src/utils/index.test.js +135 -0
  64. package/src/utils/logger.js +15 -0
  65. package/src/utils/sql.js +112 -0
  66. package/src/utils/sql.test.js +115 -0
  67. package/src/websocket.js +46 -8
  68. package/src/websocket.test.js +121 -0
  69. package/.eslintignore +0 -2
  70. package/.eslintrc.js +0 -24
  71. package/src/middlewares/logger.js +0 -13
@@ -1,4 +1,13 @@
1
1
  const db = require('../db/index');
2
+ const { dbConstants } = require('../constants');
3
+ const {
4
+ assertValidTableName,
5
+ getValidatedTableName,
6
+ quoteIdentifier,
7
+ quoteLiteral,
8
+ } = require('../utils/sql');
9
+
10
+ const { reservedTableNames } = dbConstants;
2
11
 
3
12
  const createTable = async (req, res) => {
4
13
  /*
@@ -37,7 +46,7 @@ const createTable = async (req, res) => {
37
46
  }) => {
38
47
  let column = `${name} ${type}`;
39
48
  if (defaultValue) {
40
- column += ` DEFAULT ${defaultValue}`;
49
+ column += ` DEFAULT ${quoteLiteral(defaultValue)}`;
41
50
  }
42
51
  if (notNull) {
43
52
  column += ' NOT NULL';
@@ -62,7 +71,7 @@ const createTable = async (req, res) => {
62
71
  }
63
72
 
64
73
  return column;
65
- }
74
+ },
66
75
  )
67
76
  .join(', ');
68
77
 
@@ -107,7 +116,9 @@ const createTable = async (req, res) => {
107
116
  db.prepare(indicesString).run();
108
117
  }
109
118
 
110
- const generatedSchema = db.prepare(`PRAGMA table_info(${tableName})`).all();
119
+ const generatedSchema = db
120
+ .prepare('SELECT * FROM pragma_table_info(?)')
121
+ .all(tableName);
111
122
 
112
123
  /*
113
124
  #swagger.responses[201] = {
@@ -163,26 +174,36 @@ const listTables = async (req, res) => {
163
174
  const { _search, _ordering } = req.query;
164
175
 
165
176
  let query = `SELECT name FROM sqlite_master WHERE type IN ('table', 'view')`;
177
+ const queryValues = [];
166
178
 
167
179
  // if search is provided, search the tables
168
180
  // e.g. ?_search=users
169
181
  if (_search) {
170
- query += ` AND name LIKE $searchQuery`;
182
+ query += ` AND name LIKE ?`;
183
+ queryValues.push(`%${_search}%`);
171
184
  }
172
185
 
173
186
  // if ordering is provided, order the tables
174
187
  // e.g. ?_ordering=name (ascending) or ?_ordering=-name (descending)
188
+ // `name` is the only column this query returns, so it's the only valid
189
+ // ordering target -- there's no live schema to validate an arbitrary
190
+ // column against here the way row/column ordering does.
175
191
  if (_ordering) {
176
- query += ` ORDER BY $ordering`;
192
+ const isDesc = _ordering.startsWith('-');
193
+ const cleanOrder = _ordering.replace('-', '');
194
+
195
+ if (cleanOrder !== 'name') {
196
+ return res.status(400).json({
197
+ message: `Invalid ordering field '${cleanOrder}'. Only 'name' can be used to order tables.`,
198
+ error: 'invalid_ordering_field',
199
+ });
200
+ }
201
+
202
+ query += ` ORDER BY name ${isDesc ? 'DESC' : 'ASC'}`;
177
203
  }
178
204
 
179
205
  try {
180
- const tables = db.prepare(query).all({
181
- searchQuery: `%${_search}%`,
182
- ordering: `${_ordering?.replace('-', '')} ${
183
- _ordering?.startsWith('-') ? 'DESC' : 'ASC'
184
- }`,
185
- });
206
+ const tables = db.prepare(query).all(...queryValues);
186
207
 
187
208
  res.json({
188
209
  data: tables,
@@ -210,15 +231,27 @@ const getTableSchema = async (req, res) => {
210
231
 
211
232
  */
212
233
  const { name: tableName } = req.params;
213
- const query = `PRAGMA table_info(${tableName})`;
214
234
  try {
215
- const schema = db.prepare(query).all();
235
+ assertValidTableName(db, tableName);
236
+
237
+ const schema = db
238
+ .prepare('SELECT * FROM pragma_table_info(?)')
239
+ .all(tableName);
240
+
241
+ // Additive alongside `data` -- lets clients (e.g. Soul Studio) render
242
+ // foreign-key-aware widgets without probing `_extend` on the rows
243
+ // endpoint, which throws on a non-FK column instead of reporting what
244
+ // the FK columns actually are.
245
+ const foreignKeys = db
246
+ .prepare('SELECT * FROM pragma_foreign_key_list(?)')
247
+ .all(tableName);
216
248
 
217
249
  res.json({
218
250
  data: schema,
251
+ foreignKeys,
219
252
  });
220
253
  } catch (error) {
221
- res.status(400).json({
254
+ res.status(error.status || 400).json({
222
255
  message: error.message,
223
256
  error: error,
224
257
  });
@@ -240,16 +273,29 @@ const deleteTable = async (req, res) => {
240
273
 
241
274
  */
242
275
  const { name: tableName } = req.params;
243
- const query = `DROP TABLE ${tableName}`;
244
276
  try {
245
- const data = db.prepare(query).run();
277
+ if (reservedTableNames.includes(tableName)) {
278
+ return res.status(409).json({
279
+ message: `Table '${tableName}' is reserved and cannot be deleted`,
280
+ error: 'reserved_table_name',
281
+ });
282
+ }
283
+
284
+ const validatedTableName = getValidatedTableName(db, tableName);
285
+
286
+ // DROP TABLE cannot take a bound parameter for its identifier in any
287
+ // SQL dialect. Use the canonical name returned from sqlite_master
288
+ // (parameterized lookup) and quote it as an identifier before use.
289
+ const data = db
290
+ .prepare(`DROP TABLE ${quoteIdentifier(validatedTableName)}`)
291
+ .run();
246
292
 
247
293
  res.json({
248
294
  message: 'Table deleted',
249
295
  data,
250
296
  });
251
297
  } catch (error) {
252
- res.status(400).json({
298
+ res.status(error.status || 400).json({
253
299
  message: error.message,
254
300
  error: error,
255
301
  });
@@ -25,6 +25,42 @@ describe('Tables Endpoints', () => {
25
25
  expect(res.body.data[0]).toHaveProperty('name');
26
26
  });
27
27
 
28
+ it('GET /tables succeeds even with an unrelated cookie present alongside accessToken', async () => {
29
+ // regression: Joi rejects unknown object keys by default. The browser
30
+ // sends every cookie for the domain, including ones unrelated to Soul
31
+ // (e.g. `localhost` cookies from other local apps aren't scoped by
32
+ // port) -- without `.unknown(true)` on the cookies schema, a request
33
+ // riding alongside a stray cookie like this would 400 with
34
+ // `"cookies.csrftoken" is not allowed`, even though the actual auth
35
+ // cookie is perfectly valid.
36
+ const accessToken = await generateToken(
37
+ { username: 'John', isSuperuser: true },
38
+ config.tokenSecret,
39
+ '1H',
40
+ );
41
+
42
+ const res = await requestWithSupertest
43
+ .get('/api/tables')
44
+ .set('Cookie', [`accessToken=${accessToken}`, 'csrftoken=some-value']);
45
+
46
+ expect(res.status).toEqual(200);
47
+ });
48
+
49
+ it('POST /tables should reject creating a table with a reserved name', async () => {
50
+ const accessToken = await generateToken(
51
+ { username: 'John', isSuperuser: true },
52
+ config.tokenSecret,
53
+ '1H',
54
+ );
55
+
56
+ const res = await requestWithSupertest
57
+ .post('/api/tables')
58
+ .set('Cookie', [`accessToken=${accessToken}`])
59
+ .send({ name: '_users', schema: [{ name: 'x', type: 'TEXT' }] });
60
+
61
+ expect(res.status).toEqual(409);
62
+ });
63
+
28
64
  it('POST /tables should create a new table and return generated schema', async () => {
29
65
  const accessToken = await generateToken(
30
66
  { username: 'John', isSuperuser: true },
@@ -89,4 +125,153 @@ describe('Tables Endpoints', () => {
89
125
  expect(res.body).toHaveProperty('data');
90
126
  expect(res.body.data).toEqual(expect.any(Array));
91
127
  });
128
+
129
+ it('GET /tables/:name includes foreignKeys for a table with a foreign key column', async () => {
130
+ const accessToken = await generateToken(
131
+ { username: 'John', isSuperuser: true },
132
+ config.tokenSecret,
133
+ '1H',
134
+ );
135
+
136
+ // "pets" is created earlier in this file with an `owner` column
137
+ // referencing users(id).
138
+ const res = await requestWithSupertest
139
+ .get('/api/tables/pets')
140
+ .set('Cookie', [`accessToken=${accessToken}`]);
141
+
142
+ expect(res.status).toEqual(200);
143
+ expect(res.body).toHaveProperty('foreignKeys');
144
+ expect(res.body.foreignKeys).toEqual(expect.any(Array));
145
+
146
+ const ownerForeignKey = res.body.foreignKeys.find(
147
+ (fk) => fk.from === 'owner',
148
+ );
149
+ expect(ownerForeignKey).toMatchObject({
150
+ table: 'users',
151
+ to: 'id',
152
+ });
153
+ });
154
+
155
+ it('GET /tables/:name returns an empty foreignKeys array for a table with no foreign keys', async () => {
156
+ const accessToken = await generateToken(
157
+ { username: 'John', isSuperuser: true },
158
+ config.tokenSecret,
159
+ '1H',
160
+ );
161
+
162
+ const res = await requestWithSupertest
163
+ .get('/api/tables/users')
164
+ .set('Cookie', [`accessToken=${accessToken}`]);
165
+
166
+ expect(res.status).toEqual(200);
167
+ expect(res.body.foreignKeys).toEqual([]);
168
+ });
169
+
170
+ describe('SQL injection regression', () => {
171
+ it('safely escapes a malicious column default value instead of executing it', async () => {
172
+ const accessToken = await generateToken(
173
+ { username: 'John', isSuperuser: true },
174
+ config.tokenSecret,
175
+ '1H',
176
+ );
177
+
178
+ const res = await requestWithSupertest
179
+ .post('/api/tables')
180
+ .set('Cookie', [`accessToken=${accessToken}`])
181
+ .send({
182
+ name: 'evil_defaults',
183
+ schema: [
184
+ {
185
+ name: 'myfield',
186
+ type: 'TEXT',
187
+ default: "x'); DROP TABLE users; --",
188
+ },
189
+ ],
190
+ });
191
+
192
+ expect(res.status).toEqual(201);
193
+
194
+ const usersStillExist = await requestWithSupertest
195
+ .get('/api/tables/users')
196
+ .set('Cookie', [`accessToken=${accessToken}`]);
197
+ expect(usersStillExist.status).toEqual(200);
198
+ });
199
+
200
+ it('rejects a table name containing SQL metacharacters with a 400 before it reaches the query', async () => {
201
+ const accessToken = await generateToken(
202
+ { username: 'John', isSuperuser: true },
203
+ config.tokenSecret,
204
+ '1H',
205
+ );
206
+
207
+ const res = await requestWithSupertest
208
+ .get(`/api/tables/${encodeURIComponent('nope; DROP TABLE users;--')}`)
209
+ .set('Cookie', [`accessToken=${accessToken}`]);
210
+
211
+ expect(res.status).toEqual(400);
212
+ });
213
+
214
+ it('returns a 404 (not a 500) for a syntactically valid but nonexistent table name on GET /tables/:name', async () => {
215
+ const accessToken = await generateToken(
216
+ { username: 'John', isSuperuser: true },
217
+ config.tokenSecret,
218
+ '1H',
219
+ );
220
+
221
+ const res = await requestWithSupertest
222
+ .get('/api/tables/totally-nonexistent-table')
223
+ .set('Cookie', [`accessToken=${accessToken}`]);
224
+
225
+ expect(res.status).toEqual(404);
226
+ });
227
+
228
+ it('rejects deleting a reserved system table', async () => {
229
+ const accessToken = await generateToken(
230
+ { username: 'John', isSuperuser: true },
231
+ config.tokenSecret,
232
+ '1H',
233
+ );
234
+
235
+ const res = await requestWithSupertest
236
+ .delete('/api/tables/_users')
237
+ .set('Cookie', [`accessToken=${accessToken}`]);
238
+
239
+ expect(res.status).toEqual(409);
240
+
241
+ const usersStillExist = await requestWithSupertest
242
+ .get('/api/tables/_users')
243
+ .set('Cookie', [`accessToken=${accessToken}`]);
244
+ expect(usersStillExist.status).toEqual(200);
245
+ });
246
+
247
+ it('rejects a crafted table name on DELETE with a 400 before it reaches the query', async () => {
248
+ const accessToken = await generateToken(
249
+ { username: 'John', isSuperuser: true },
250
+ config.tokenSecret,
251
+ '1H',
252
+ );
253
+
254
+ const res = await requestWithSupertest
255
+ .delete(
256
+ `/api/tables/${encodeURIComponent('nope; DROP TABLE users;--')}`,
257
+ )
258
+ .set('Cookie', [`accessToken=${accessToken}`]);
259
+
260
+ expect(res.status).toEqual(400);
261
+ });
262
+
263
+ it('returns a 404 (not a 500) when deleting a syntactically valid but nonexistent table name', async () => {
264
+ const accessToken = await generateToken(
265
+ { username: 'John', isSuperuser: true },
266
+ config.tokenSecret,
267
+ '1H',
268
+ );
269
+
270
+ const res = await requestWithSupertest
271
+ .delete('/api/tables/totally-nonexistent-table')
272
+ .set('Cookie', [`accessToken=${accessToken}`]);
273
+
274
+ expect(res.status).toEqual(404);
275
+ });
276
+ });
92
277
  });
@@ -0,0 +1,21 @@
1
+ // This module's export is the raw better-sqlite3 connection (a singleton
2
+ // built from `config.db.filename`), not the `Database` wrapper class -- so
3
+ // these tests exercise the module's actual public contract rather than
4
+ // reaching into its internals.
5
+ const db = require('./index');
6
+
7
+ describe('db', () => {
8
+ it('exports a usable better-sqlite3 connection', () => {
9
+ expect(typeof db.prepare).toBe('function');
10
+ expect(typeof db.exec).toBe('function');
11
+ expect(typeof db.close).toBe('function');
12
+
13
+ const result = db.prepare('SELECT 1 + 1 AS total').get();
14
+ expect(result.total).toBe(2);
15
+ });
16
+
17
+ it('closes without throwing', () => {
18
+ expect(() => db.close()).not.toThrow();
19
+ expect(db.open).toBe(false);
20
+ });
21
+ });
package/src/extensions.js CHANGED
@@ -1,45 +1,114 @@
1
1
  const fs = require('fs');
2
+ const path = require('path');
2
3
 
3
- const { extensions: extensionsConfig } = require('./config');
4
+ const config = require('./config');
5
+ const { decodeToken, toBoolean } = require('./utils');
6
+ const logger = require('./utils/logger');
7
+ const { responseMessages } = require('./constants');
8
+ const { authService } = require('./services');
4
9
 
5
- const { path: extensionsPath } = extensionsConfig;
10
+ const { path: extensionsPath } = config.extensions;
11
+ const { errorMessage } = responseMessages;
6
12
 
7
- const setupExtensions = async (app, db) => {
8
- if (extensionsPath) {
9
- const extensions = fs.readdirSync(extensionsPath);
10
- extensions.forEach((extension) => {
11
- if (extension === 'api.js') {
12
- const apiExtensions = require(`${extensionsPath}/${extension}`);
13
-
14
- console.log('API extensions loaded');
15
-
16
- Object.keys(apiExtensions).forEach((key) => {
17
- const api = apiExtensions[key];
18
- switch (api.method) {
19
- case 'GET':
20
- app.get(api.path, (req, res) => api.handler(req, res, db));
21
- break;
22
- case 'POST':
23
- app.post(api.path, api.handler);
24
- break;
25
- case 'PUT':
26
- app.put(api.path, api.handler);
27
- break;
28
- case 'DELETE':
29
- app.delete(api.path, api.handler);
30
- break;
31
-
32
- default:
33
- break;
34
- }
35
- console.log(' >', api.path);
36
- });
37
- console.log('\n');
38
- }
13
+ // Wraps an extension handler with an auth check, reusing the same
14
+ // decodeToken/hasTablePermission primitives the core hasAccess middleware
15
+ // uses -- not hasAccess itself, since that assumes a `:name` route param
16
+ // for the table, which extension routes don't have.
17
+ //
18
+ // `auth` accepts:
19
+ // true -- must be authenticated, no further check
20
+ // { superuserOnly } -- must be authenticated and a superuser
21
+ // { table } -- must be authenticated and have permission on
22
+ // `table` for the request's HTTP method (via
23
+ // authService.hasTablePermission, which already
24
+ // grants superusers everything)
25
+ const withAuth = (auth, handler, db) => async (req, res) => {
26
+ if (!config.auth) {
27
+ return handler(req, res, db);
28
+ }
29
+
30
+ let payload;
31
+ try {
32
+ payload = await decodeToken(req.cookies?.accessToken, config.tokenSecret);
33
+ req.user = payload;
34
+ } catch {
35
+ return res
36
+ .status(401)
37
+ .send({ message: errorMessage.INVALID_ACCESS_TOKEN_ERROR });
38
+ }
39
+
40
+ if (auth === true) {
41
+ return handler(req, res, db);
42
+ }
43
+
44
+ if (auth.superuserOnly && !toBoolean(payload.isSuperuser)) {
45
+ return res.status(403).send({ message: errorMessage.NOT_AUTHORIZED_ERROR });
46
+ }
47
+
48
+ if (auth.table) {
49
+ const hasPermission = authService.hasTablePermission({
50
+ payload,
51
+ tableName: auth.table,
52
+ verb: req.method,
39
53
  });
40
- } else {
41
- console.log('No extensions directory provided');
54
+
55
+ if (!hasPermission) {
56
+ return res
57
+ .status(403)
58
+ .send({ message: errorMessage.NOT_AUTHORIZED_ERROR });
59
+ }
60
+ }
61
+
62
+ return handler(req, res, db);
63
+ };
64
+
65
+ const loadExtensionRoutes = (dirPath) => {
66
+ const files = fs.readdirSync(dirPath).filter((file) => file.endsWith('.js'));
67
+
68
+ return files.reduce((routes, file) => {
69
+ const exported = require(path.join(dirPath, file));
70
+ return { ...routes, ...exported };
71
+ }, {});
72
+ };
73
+
74
+ const setupExtensions = async (app, db) => {
75
+ if (!extensionsPath) {
76
+ logger.info('No extensions directory provided');
77
+ return;
42
78
  }
79
+
80
+ const routes = loadExtensionRoutes(extensionsPath);
81
+ const routeCount = Object.keys(routes).length;
82
+
83
+ if (routeCount === 0) {
84
+ logger.info(`No extension routes found in ${extensionsPath}`);
85
+ return;
86
+ }
87
+
88
+ logger.info(
89
+ `Loading ${routeCount} extension route(s) from ${extensionsPath}`,
90
+ );
91
+
92
+ Object.entries(routes).forEach(([key, route]) => {
93
+ const method = String(route.method || '').toLowerCase();
94
+ const registerRoute = app[method];
95
+
96
+ if (typeof registerRoute !== 'function') {
97
+ logger.warn(
98
+ `Skipping extension route '${key}': unsupported method '${route.method}'`,
99
+ );
100
+ return;
101
+ }
102
+
103
+ const handler = route.auth
104
+ ? withAuth(route.auth, route.handler, db)
105
+ : (req, res) => route.handler(req, res, db);
106
+
107
+ registerRoute.call(app, route.path, handler);
108
+ logger.info(
109
+ ` > ${route.method} ${route.path}${route.auth ? ' (auth required)' : ''}`,
110
+ );
111
+ });
43
112
  };
44
113
 
45
114
  module.exports = {