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
@@ -62,6 +62,15 @@
62
62
  "contributions": [
63
63
  "code"
64
64
  ]
65
+ },
66
+ {
67
+ "login": "thoughtsunificator",
68
+ "name": "Romain Lebesle",
69
+ "avatar_url": "https://avatars.githubusercontent.com/u/85041649?v=4",
70
+ "profile": "http://thoughtsunificator.me",
71
+ "contributions": [
72
+ "code"
73
+ ]
65
74
  }
66
75
  ],
67
76
  "contributorsPerLine": 7,
@@ -0,0 +1,8 @@
1
+ meta {
2
+ name: auth
3
+ seq: 2
4
+ }
5
+
6
+ auth {
7
+ mode: inherit
8
+ }
@@ -0,0 +1,25 @@
1
+ meta {
2
+ name: obtain-access-token
3
+ type: http
4
+ seq: 1
5
+ }
6
+
7
+ post {
8
+ url: {{base_url}}/api/auth/token/obtain
9
+ body: json
10
+ auth: inherit
11
+ }
12
+
13
+ body:json {
14
+ {
15
+ "fields": {
16
+ "username": "john",
17
+ "password": "johns_passowrd"
18
+ }
19
+ }
20
+ }
21
+
22
+ settings {
23
+ encodeUrl: true
24
+ timeout: 0
25
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "version": "1",
3
+ "name": "soul",
4
+ "type": "collection",
5
+ "ignore": ["node_modules", ".git"]
6
+ }
@@ -0,0 +1,3 @@
1
+ vars {
2
+ base_url: http://localhost:8000
3
+ }
@@ -0,0 +1,8 @@
1
+ meta {
2
+ name: rows
3
+ seq: 1
4
+ }
5
+
6
+ auth {
7
+ mode: inherit
8
+ }
@@ -0,0 +1,25 @@
1
+ meta {
2
+ name: list-rows-with-ordering
3
+ type: http
4
+ seq: 1
5
+ }
6
+
7
+ get {
8
+ url: {{base_url}}/api/tables/:tableName/rows/?_ordering=-CustomerId.LastName&_extend=CustomerId
9
+ body: none
10
+ auth: inherit
11
+ }
12
+
13
+ params:query {
14
+ _ordering: -CustomerId.LastName
15
+ _extend: CustomerId
16
+ }
17
+
18
+ params:path {
19
+ tableName: Invoice
20
+ }
21
+
22
+ settings {
23
+ encodeUrl: true
24
+ timeout: 0
25
+ }
@@ -0,0 +1,8 @@
1
+ meta {
2
+ name: tables
3
+ seq: 3
4
+ }
5
+
6
+ auth {
7
+ mode: inherit
8
+ }
@@ -0,0 +1,16 @@
1
+ meta {
2
+ name: list-tables
3
+ type: http
4
+ seq: 1
5
+ }
6
+
7
+ get {
8
+ url: {{base_url}}/api/tables
9
+ body: none
10
+ auth: inherit
11
+ }
12
+
13
+ settings {
14
+ encodeUrl: true
15
+ timeout: 0
16
+ }
package/.env.sample CHANGED
@@ -5,9 +5,18 @@ NODE_ENV=development
5
5
  CORS_ORIGIN_WHITELIST=http://localhost:3000,http://127.0.0.1:3000
6
6
  AUTH=false
7
7
 
8
+ # Auth cookie attributes. Defaults (lax/false) are correct for same-origin
9
+ # setups (e.g. `soul -S`). For a frontend hosted on a different origin
10
+ # talking to this API with credentials, set CORS_ORIGIN_WHITELIST to that
11
+ # exact origin (never *), COOKIE_SAMESITE=none, and COOKIE_SECURE=true
12
+ # (browsers treat localhost as trustworthy even over plain http, so this
13
+ # still works for local cross-origin dev).
14
+ COOKIE_SAMESITE=lax
15
+ COOKIE_SECURE=false
16
+
8
17
  RATE_LIMIT_ENABLED=false
9
- RATE_LIMIT_WINDOW=1000
10
- RATE_LIMIT_MAX=10
18
+ RATE_LIMIT_WINDOW_MS=1000
19
+ RATE_LIMIT_MAX_REQUESTS=10
11
20
 
12
21
  DB=foobar.db
13
22
 
@@ -0,0 +1,9 @@
1
+ # Please see the documentation for all configuration options:
2
+ # https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
3
+
4
+ version: 2
5
+ updates:
6
+ - package-ecosystem: "npm" # See documentation for possible values
7
+ directory: "/" # Location of package manifests
8
+ schedule:
9
+ interval: "weekly"
@@ -0,0 +1,33 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ test:
13
+ strategy:
14
+ fail-fast: false
15
+ matrix:
16
+ os: [ubuntu-latest, macos-latest]
17
+ node-version: [22.x, 24.x, 26.x]
18
+
19
+ runs-on: ${{ matrix.os }}
20
+
21
+ steps:
22
+ - uses: actions/checkout@v4
23
+
24
+ - uses: actions/setup-node@v4
25
+ with:
26
+ node-version: ${{ matrix.node-version }}
27
+ cache: npm
28
+
29
+ - run: npm ci
30
+
31
+ - run: npm run lint
32
+
33
+ - run: npm run test:coverage
@@ -1,4 +1,9 @@
1
- # This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
1
+ # Publishes to npm via Trusted Publishing (OIDC) -- no long-lived npm
2
+ # token/secret involved. Requires a matching Trusted Publisher configured
3
+ # on the package's npmjs.com settings: GitHub Actions, owner/repo
4
+ # thevahidal/soul, workflow filename `npm-publish.yml`, action `npm publish`
5
+ # allowed. See https://docs.npmjs.com/trusted-publishers.
6
+ #
2
7
  # For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
3
8
 
4
9
  name: Node.js Package
@@ -7,17 +12,25 @@ on:
7
12
  release:
8
13
  types: [created]
9
14
 
15
+ permissions:
16
+ contents: read
17
+ id-token: write
18
+
10
19
  jobs:
11
20
  publish-npm:
12
21
  runs-on: ubuntu-latest
13
22
  steps:
14
- - uses: actions/checkout@v3
15
- - uses: actions/setup-node@v3
23
+ - uses: actions/checkout@v4
24
+ - uses: actions/setup-node@v4
16
25
  with:
17
- node-version: 16
26
+ node-version: 22
18
27
  registry-url: https://registry.npmjs.org/
19
28
 
29
+ # Trusted Publishing needs npm CLI >=11.5.1; the version bundled with
30
+ # setup-node's Node 22 isn't guaranteed to be that recent.
31
+ - name: Check tag matches package.json version
32
+ run: test "v$(node -p 'require("./package.json").version')" = "${{ github.event.release.tag_name }}"
33
+ - run: npm install -g npm@latest
20
34
  - run: npm ci
35
+ - run: npm test
21
36
  - run: npm publish
22
- env:
23
- NODE_AUTH_TOKEN: ${{secrets.npm_token}}
package/.husky/pre-commit CHANGED
@@ -1,5 +1,2 @@
1
- #!/usr/bin/env sh
2
- . "$(dirname -- "$0")/_/husky.sh"
3
-
4
1
  npm test
5
2
  npx lint-staged
package/README.md CHANGED
@@ -8,15 +8,47 @@
8
8
  [![justforfunnoreally.dev badge](https://img.shields.io/badge/justforfunnoreally-dev-9ff)](https://justforfunnoreally.dev)
9
9
  [![All Contributors](https://img.shields.io/github/all-contributors/thevahidal/soul?color=ee8449&style=flat-square)](#contributors)
10
10
 
11
- ## Installation
11
+ ## Usage
12
12
 
13
- Install Soul CLI with npm
13
+ ### Docker
14
14
 
15
- ```bash
16
- npm install -g soul-cli
17
- ```
15
+ > This is a convenient way to run Soul without worrying about your local Node.js version. Soul requires Node.js `22.x`, `23.x`, `24.x`, `25.x`, or `26.x` (see `engines` in `package.json`) since its [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) dependency requires Node 22 or newer.
18
16
 
19
- ## Usage
17
+ Using the following Dockerfile:
18
+
19
+ <details>
20
+ <summary>Dockerfile</summary>
21
+
22
+ ```nginx
23
+ # node:22-alpine amd64
24
+ FROM node@sha256:76789712cd1ae89a1225eac9077010d68987a423588042dac30446f502f1858c AS node
25
+
26
+ WORKDIR /app
27
+
28
+ ENV NODE_ENV="production"
29
+
30
+ COPY package-lock.json package.json ./
31
+
32
+ # python3/build-base are a fallback in case no prebuilt native binary matches
33
+
34
+ # this platform (e.g. non-amd64/arm64 or a libc variant without a prebuild)
35
+
36
+ RUN apk update && apk add python3 build-base && npm ci
37
+
38
+ COPY . .
39
+
40
+ CMD [ "npm", "start" ]
41
+
42
+ ````
43
+ </details>
44
+
45
+ You can proceed [to building the application](https://docs.docker.com/get-started/workshop/02_our_app/#build-the-apps-image).
46
+
47
+ ### npm
48
+
49
+ ```bash
50
+ npm install -g soul-cli
51
+ ````
20
52
 
21
53
  ### 1. Running Soul
22
54
 
@@ -47,6 +79,8 @@ Options:
47
79
 
48
80
  ```
49
81
 
82
+ NOTE: If `--cors` is left at its default (or explicitly set to `*`), cookie-based credentials (used for auth) are disabled on cross-origin requests, since browsers reject the combination of a wildcard origin with credentials. Pass an explicit comma-separated origin list via `--cors` to allow authenticated cross-origin requests.
83
+
50
84
  Then to test Soul is working run the following command
51
85
 
52
86
  ```bash
@@ -148,7 +182,7 @@ A collection of projects that revolve around the Soul ecosystem.
148
182
  git clone https://github.com/thevahidal/soul # Clone project
149
183
 
150
184
  cp .env.sample .env # Duplicate sample environment variables
151
- nano .env # Update the environment variables
185
+ vim .env # Update the environment variables
152
186
 
153
187
  npm install # Install dependencies
154
188
  npm run dev # Start the dev server
@@ -168,6 +202,10 @@ npm run dev # Start the dev server
168
202
 
169
203
  Make sure to replace the placeholders with the appropriate values for your environment.
170
204
 
205
+ ## Hosting Static Content Using Soul
206
+
207
+ You can host static content using Soul by utilizing its extensions feature. This allows you to expose your static application through Soul, enabling users to access your content without hosting multiple applications. please check [this](./docs/self-hosting.md) document
208
+
171
209
  ## Community
172
210
 
173
211
  [Join](https://bit.ly/soul-discord) the discussion in our Discord server and help making Soul together.
@@ -198,6 +236,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
198
236
  <td align="center" valign="top" width="14.28%"><a href="https://godot.id"><img src="https://avatars.githubusercontent.com/u/40712686?v=4?s=100" width="100px;" alt="Hanz"/><br /><sub><b>Hanz</b></sub></a><br /><a href="https://github.com/thevahidal/soul/commits?author=HanzCEO" title="Code">💻</a></td>
199
237
  <td align="center" valign="top" width="14.28%"><a href="https://github.com/KoenDG"><img src="https://avatars.githubusercontent.com/u/1440619?v=4?s=100" width="100px;" alt="Koen De Groote"/><br /><sub><b>Koen De Groote</b></sub></a><br /><a href="https://github.com/thevahidal/soul/commits?author=KoenDG" title="Code">💻</a></td>
200
238
  <td align="center" valign="top" width="14.28%"><a href="https://github.com/TahaKhanAbdalli"><img src="https://avatars.githubusercontent.com/u/50602678?v=4?s=100" width="100px;" alt="Muhammad Taha Khan"/><br /><sub><b>Muhammad Taha Khan</b></sub></a><br /><a href="https://github.com/thevahidal/soul/commits?author=TahaKhanAbdalli" title="Code">💻</a></td>
239
+ <td align="center" valign="top" width="14.28%"><a href="http://thoughtsunificator.me"><img src="https://avatars.githubusercontent.com/u/85041649?v=4?s=100" width="100px;" alt="Romain Lebesle"/><br /><sub><b>Romain Lebesle</b></sub></a><br /><a href="https://github.com/thevahidal/soul/commits?author=thoughtsunificator" title="Code">💻</a></td>
201
240
  </tr>
202
241
  </tbody>
203
242
  </table>
package/ROADMAP.md ADDED
@@ -0,0 +1,154 @@
1
+ # Soul Roadmap
2
+
3
+ This document captures where Soul is today and the direction agreed on for
4
+ what comes next. Written to hand off to a fresh session — it should be
5
+ enough context to start executing without re-deriving the "why."
6
+
7
+ ## Where Soul is today
8
+
9
+ Soul started as a lighter, JS-based take on PocketBase: point it at a
10
+ SQLite file and get an instant REST + realtime API, with auth/authorization
11
+ and an extensions mechanism. It picked up some attention via Hacker News
12
+ and Reddit early on.
13
+
14
+ As of `main` (merged PR #240, tagged `v0.9.0`), Soul just went through a
15
+ full production-hardening pass:
16
+
17
+ - Fixed `npm install` failing outright on modern Node (better-sqlite3/bcrypt
18
+ had no prebuilds for Node 20+; both bumped, `engines` now `22.x–26.x`).
19
+ - Closed a real, exploitable SQL injection surface across the rows/tables
20
+ endpoints (identifiers are now allowlist-validated against the live
21
+ schema; values are always parameter-bound; regression tests prove
22
+ injection payloads are neutralized).
23
+ - Added WebSocket auth (previously anyone could subscribe to realtime
24
+ changes on any table regardless of the REST permission model), graceful
25
+ shutdown, a global error handler that doesn't leak stack traces, CORS/
26
+ helmet hardening.
27
+ - Found and fixed several real latent bugs along the way: revoked-refresh-
28
+ token cleanup silently never worked (comparing an INTEGER timestamp
29
+ against a TEXT `CURRENT_TIMESTAMP` never matched), `authService` ignored
30
+ its own dependency-injection parameter, extension `POST`/`PUT`/`DELETE`
31
+ handlers never received `db` (only `GET` did, contradicting the docs),
32
+ a broken rate-limit config key mismatch.
33
+ - CI now runs lint + tests across a Node 22/24/26 × ubuntu/macos matrix,
34
+ plus CodeQL.
35
+ - Test coverage went from ~83% to ~94% (branches ~70% → ~88%), with a
36
+ coverage-threshold gate enforced in CI so it can't regress silently.
37
+
38
+ **Net effect: the core (rows/tables REST API, auth, realtime, permissions)
39
+ is now solid and reasonably well-defended.** That's the foundation the
40
+ rest of this roadmap builds on — it wasn't true before this pass.
41
+
42
+ Soul Studio (a Prisma-Studio-like data browser, separate repo) exists but
43
+ is pre-alpha — the main README still says "not useful to work with yet."
44
+
45
+ ## Strategic direction
46
+
47
+ Considered and **rejected**: pivoting Soul + Soul Studio into a broad
48
+ business-app suite (CRM/inventory/accounting/etc. on a shared framework).
49
+ Reasoning: that market's moat is years of vertical business-app logic, not
50
+ infrastructure, and it means competing head-on with incumbents that are
51
+ 15+ years in with large module ecosystems and paid-support businesses.
52
+ It would mean abandoning Soul's current, real niche to restart as a much
53
+ larger, much slower-to-differentiate project — and Soul Studio is nowhere
54
+ near ready to be the UI layer for that anyway.
55
+
56
+ **Decided direction instead: lean into Soul as the safe, instant backend
57
+ for AI-agent-built apps.** This niche got more relevant, not less, as
58
+ agents write more backend code — the bug list above (SQL injection, a
59
+ missing auth check, a silently-broken rate limiter) is exactly the class
60
+ of mistake an LLM writing bespoke CRUD+auth code from scratch tends to
61
+ ship. A tool that turns "here's a SQLite file" into a safe, permissioned,
62
+ realtime API removes that entire failure surface.
63
+
64
+ ## Roadmap
65
+
66
+ Ordered by priority / leverage. Each item should be scoped and planned
67
+ properly (via `/plan` or similar) when picked up — this is direction, not
68
+ a detailed spec.
69
+
70
+ ### 1. MCP server (start here)
71
+
72
+ Smallest scope, highest signal for where Soul's actual users increasingly
73
+ are. Expose the already-hardened service layer as MCP tools so agents
74
+ (Claude Code, Cursor, etc.) can attach to a Soul-backed DB directly instead
75
+ of hand-rolling HTTP calls.
76
+
77
+ Tools to expose (mirroring existing REST semantics):
78
+
79
+ - `list_tables`, `get_schema`
80
+ - `query_rows` (reuse the existing `_filters`/`_search`/`_ordering`/
81
+ `_schema`/`_extend` semantics from `rows.js`)
82
+ - `insert_row`, `update_row`, `delete_row`
83
+ - `create_table` (JSON schema in, same shape as the existing REST
84
+ `POST /tables`)
85
+
86
+ Should sit directly on `src/services/rowService.js` /
87
+ `src/services/tableService.js` / `src/utils/sql.js` — no new validation
88
+ logic needed, just a transport layer. Open question to resolve when
89
+ starting: ship as a separate package, or a mode on the existing CLI
90
+ (e.g. `soul --mcp`)?
91
+
92
+ ### 2. Make the safety properties part of the pitch
93
+
94
+ Write up the specific bug classes found and fixed in the hardening pass
95
+ (injection via unvalidated identifiers, the WS auth gap, the rate-limit
96
+ bug) as the actual argument for "safe to let an agent drive this." The
97
+ regression tests added during that work are the receipts.
98
+
99
+ Consider: an ongoing adversarial/fuzz test suite (random or LLM-generated
100
+ filter/ordering/table-name payloads) as both a visible regression guard
101
+ and something to point to.
102
+
103
+ ### 3. LLM-native schema workflows
104
+
105
+ Soul's `createTable` API already takes a JSON schema description rather
106
+ than raw DDL — lean into that explicitly ("describe your schema, don't
107
+ write SQL"). Add incremental schema evolution (an alter-table / add-column
108
+ endpoint) so an agent can iterate on a schema across a conversation
109
+ instead of only create-once. Consider migration history/versioning if
110
+ this sees real use.
111
+
112
+ ### 4. Soul Studio v1 — scoped, not full-featured
113
+
114
+ Target workflow: agent writes to the DB via Soul, human opens Studio to
115
+ inspect and correct it. Not a general-purpose admin framework.
116
+
117
+ Needs: table/row browser, inline edit, respecting the same permission
118
+ model as the API. Explicitly **not** in scope for v1: dashboards, complex
119
+ relation UIs, anything Retool-shaped — get the core loop solid first.
120
+
121
+ ### 5. Scoped agent credentials
122
+
123
+ Package the existing per-table CRUD permission/role system (see
124
+ `authService.hasTablePermission`) as a named feature: give an agent a key
125
+ that can only read/write specific tables. Likely needs a lighter API-key
126
+ auth mode alongside the current username/password + JWT flow, scoped at
127
+ key-creation time to specific tables/verbs. Addresses a real, currently
128
+ annoying problem in agentic products (over-broad tool access).
129
+
130
+ ### 6. Cheap wins
131
+
132
+ - Ship an `llms.txt`.
133
+ - Explicitly point agents at the already-generated OpenAPI/Swagger spec
134
+ (`npm run swagger-autogen`) — "give this file to your coding agent and
135
+ it knows how to drive the API." Most of the work already exists.
136
+
137
+ ## Explicitly out of scope (for now)
138
+
139
+ - ERP-style business-app suite.
140
+ - General-purpose no-code app builder.
141
+ - Multi-database support (Postgres/MySQL) — SQLite-native is a feature of
142
+ this niche, not a limitation to fix.
143
+
144
+ ## Starting a new session
145
+
146
+ - Codebase state: `main` is current as of `v0.9.0` / PR #240 merge.
147
+ - Test commands: `npm test` (fast, no coverage) / `npm run test:coverage`
148
+ (enforces the coverage threshold — this is what CI runs).
149
+ - CI: Node 22/24/26 × ubuntu/macos, plus CodeQL, on push/PR.
150
+ - Key files for MCP work specifically: `src/services/rowService.js`,
151
+ `src/services/tableService.js`, `src/utils/sql.js` (identifier
152
+ validation — reuse this, don't reinvent it), `src/controllers/rows.js` /
153
+ `src/controllers/tables.js` (existing REST-layer patterns to mirror for
154
+ parameter semantics).
Binary file
@@ -6,7 +6,6 @@ Soul extensions are a way to extend the functionality of Soul. Extensions are wr
6
6
 
7
7
  - API Extensions: Add new endpoints to Soul
8
8
 
9
-
10
9
  ## Setup Environment
11
10
 
12
11
  To follow the below examples we need to download a sample database and also install Soul CLI.
@@ -18,6 +17,7 @@ wget https://raw.githubusercontent.com/lerocha/chinook-database/master/ChinookDa
18
17
  ```
19
18
 
20
19
  ### Using Soul CLI
20
+
21
21
  ```bash
22
22
  npm install -g soul-cli
23
23
  soul -d ./Chinook_Sqlite.sqlite -p 8000 -e "/absolute/path/to/_extensions/"
@@ -32,49 +32,68 @@ npm install # Install dependencies
32
32
  npm link # might need `sudo`
33
33
  soul -d ./Chinook_Sqlite.sqlite -p 8000 -e "/absolute/path/to/_extensions/"
34
34
  ```
35
- </details>
36
35
 
36
+ </details>
37
37
 
38
38
  ## Creating an API extension
39
39
 
40
- To create an extension, create a new folder named `_extensions`. Then create a file named `api.js` inside it. This file will contain the extension code.
40
+ To create an extension, create a new folder named `_extensions`. Inside it, add
41
+ one or more `.js` files containing your route definitions -- Soul loads
42
+ **every** `.js` file in the extensions directory (not just a single `api.js`),
43
+ and merges all their exported routes together. This lets you split routes
44
+ across files however makes sense for your project (e.g. `users.js`,
45
+ `reports.js`), instead of cramming everything into one file.
46
+
47
+ Each route definition supports:
48
+
49
+ - `method` -- any HTTP method Express supports (`GET`, `POST`, `PUT`,
50
+ `DELETE`, `PATCH`, ...).
51
+ - `path` -- the Express route path.
52
+ - `handler(req, res, db)` -- your route handler. `db` is always the same
53
+ `better-sqlite3` database instance Soul itself uses, so you can run your
54
+ own queries against it.
55
+ - `auth` (optional) -- require authentication/authorization for this route,
56
+ reusing the same checks Soul's core REST API uses. See
57
+ [Protecting extension routes with `auth`](#protecting-extension-routes-with-auth)
58
+ below.
41
59
 
42
60
  ```js
61
+ // _extensions/api.js
43
62
  const hello = {
44
- method: 'GET',
45
- path: '/api/hello-soul',
63
+ method: "GET",
64
+ path: "/api/hello-soul",
46
65
  handler: (req, res, db) => {
47
66
  res.status(200).json({
48
- message: 'Hello Soul!'
67
+ message: "Hello Soul!",
49
68
  });
50
69
  },
51
70
  };
52
71
 
53
72
  const timestamp = {
54
- method: 'GET',
55
- path: '/api/timestamp',
73
+ method: "GET",
74
+ path: "/api/timestamp",
56
75
  handler: (req, res, db) => {
57
76
  res.status(200).json({
58
- timestamp: Date.now(),
77
+ timestamp: Date.now(),
59
78
  });
60
79
  },
61
80
  };
62
81
 
63
82
  const greetings = {
64
- method: 'POST',
65
- path: '/api/greetings/:name',
83
+ method: "POST",
84
+ path: "/api/greetings/:name",
66
85
  handler: (req, res, db) => {
67
86
  const { name } = req.params;
68
87
  const { greeting } = req.body;
69
88
  res.status(200).json({
70
- message: `${greeting} ${name}!`,
89
+ message: `${greeting} ${name}!`,
71
90
  });
72
91
  },
73
- }
92
+ };
74
93
 
75
94
  const searchTables = {
76
- method: 'GET',
77
- path: '/api/search-tables',
95
+ method: "GET",
96
+ path: "/api/search-tables",
78
97
  handler: (req, res, db) => {
79
98
  const { q } = req.query;
80
99
  const sql = `
@@ -103,7 +122,6 @@ module.exports = {
103
122
  greetings,
104
123
  searchTables,
105
124
  };
106
-
107
125
  ```
108
126
 
109
127
  Alright, now we can test if the extension is working:
@@ -165,3 +183,65 @@ It should return:
165
183
  ]
166
184
  }
167
185
  ```
186
+
187
+ ## Protecting extension routes with `auth`
188
+
189
+ By default, extension routes are public, regardless of Soul's `AUTH` setting.
190
+ To require authentication (and optionally authorization), add an `auth`
191
+ field to the route definition. It accepts:
192
+
193
+ - `true` -- the request must have a valid access token. Any authenticated
194
+ user is allowed in; the handler doesn't run for anyone else.
195
+ - `{ superuserOnly: true }` -- the request must have a valid access token
196
+ **and** belong to a superuser.
197
+ - `{ table: 'tableName' }` -- the request must have a valid access token
198
+ **and** have permission on `tableName` for the request's HTTP method,
199
+ using the same role-based permission checks Soul's core `/api/:name`
200
+ routes use (so a route guarded with `{ table: 'orders' }` follows
201
+ whatever read/write permissions the caller's role already has on the
202
+ `orders` table).
203
+
204
+ If `auth` is omitted, the route is public and `AUTH` has no effect on it.
205
+ If Soul's `AUTH` setting is off, all `auth`-guarded routes behave as if
206
+ `auth` were omitted (no token is required), matching how the core REST API
207
+ behaves when auth is disabled.
208
+
209
+ ```js
210
+ // _extensions/admin.js
211
+ const purgeSessions = {
212
+ method: "POST",
213
+ path: "/api/admin/purge-sessions",
214
+ auth: { superuserOnly: true },
215
+ handler: (req, res, db) => {
216
+ db.prepare("DELETE FROM _sessions").run();
217
+ res.status(200).json({ message: "Sessions purged" });
218
+ },
219
+ };
220
+
221
+ const myOrders = {
222
+ method: "GET",
223
+ path: "/api/my-orders",
224
+ auth: { table: "orders" },
225
+ handler: (req, res, db) => {
226
+ // req.user is the decoded access token payload
227
+ const orders = db
228
+ .prepare("SELECT * FROM orders WHERE userId = ?")
229
+ .all(req.user.id);
230
+ res.status(200).json({ orders });
231
+ },
232
+ };
233
+
234
+ module.exports = {
235
+ purgeSessions,
236
+ myOrders,
237
+ };
238
+ ```
239
+
240
+ Calling `purge-sessions` without a token returns a `401`:
241
+
242
+ ```bash
243
+ curl -i -X POST http://localhost:8000/api/admin/purge-sessions
244
+ ```
245
+
246
+ Calling it with a valid, non-superuser token returns a `403`; with a
247
+ superuser's token, it runs the handler and returns `200`.