soul-cli 0.8.2 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/.env.sample +11 -2
  2. package/.github/dependabot.yml +9 -0
  3. package/.github/pull_request_template.md +8 -0
  4. package/.github/workflows/ci.yml +33 -0
  5. package/.github/workflows/pr-title.yml +27 -0
  6. package/.github/workflows/release.yml +44 -0
  7. package/.husky/pre-commit +0 -3
  8. package/.release-please-manifest.json +3 -0
  9. package/AGENTS.md +31 -0
  10. package/CHANGELOG.md +35 -0
  11. package/CLAUDE.md +1 -0
  12. package/README.md +16 -8
  13. package/ROADMAP.md +154 -0
  14. package/SECURITY.md +19 -0
  15. package/docs/extensions-examples.md +96 -16
  16. package/docs/ws-examples.md +4 -0
  17. package/eslint.config.js +29 -0
  18. package/package.json +44 -24
  19. package/release-please-config.json +10 -0
  20. package/scripts/dev.sh +64 -0
  21. package/src/cli.test.js +128 -0
  22. package/src/config/index.js +10 -2
  23. package/src/config/index.test.js +120 -0
  24. package/src/controllers/auth/common.js +1 -16
  25. package/src/controllers/auth/common.test.js +23 -0
  26. package/src/controllers/auth/tables.js +1 -1
  27. package/src/controllers/auth/token.js +30 -7
  28. package/src/controllers/auth/user.js +20 -20
  29. package/src/controllers/auth/user.test.js +232 -0
  30. package/src/controllers/auth.test.js +445 -0
  31. package/src/controllers/rows.js +159 -112
  32. package/src/controllers/rows.test.js +88 -1
  33. package/src/controllers/tables.js +63 -17
  34. package/src/controllers/tables.test.js +185 -0
  35. package/src/db/index.test.js +21 -0
  36. package/src/extensions.js +105 -36
  37. package/src/extensions.test.js +340 -0
  38. package/src/index.js +37 -20
  39. package/src/index.test.js +118 -0
  40. package/src/middlewares/api.js +1 -1
  41. package/src/middlewares/api.test.js +29 -0
  42. package/src/middlewares/auth.js +11 -48
  43. package/src/middlewares/auth.test.js +105 -0
  44. package/src/middlewares/validation.test.js +60 -0
  45. package/src/schemas/index.js +3 -1
  46. package/src/schemas/rows.js +15 -5
  47. package/src/schemas/tables.js +28 -4
  48. package/src/server.js +85 -4
  49. package/src/services/authService.js +33 -3
  50. package/src/services/authService.test.js +115 -0
  51. package/src/services/rowService.js +25 -18
  52. package/src/services/rowService.test.js +153 -0
  53. package/src/services/tableService.js +15 -17
  54. package/src/services/tableService.test.js +190 -0
  55. package/src/swagger/swagger.json +4 -7
  56. package/src/tests/index.js +1 -1
  57. package/src/utils/index.js +25 -2
  58. package/src/utils/index.test.js +135 -0
  59. package/src/utils/logger.js +15 -0
  60. package/src/utils/sql.js +112 -0
  61. package/src/utils/sql.test.js +115 -0
  62. package/src/websocket.js +47 -8
  63. package/src/websocket.test.js +121 -0
  64. package/.eslintignore +0 -2
  65. package/.eslintrc.js +0 -24
  66. package/.github/workflows/npm-publish.yml +0 -23
  67. package/src/middlewares/logger.js +0 -13
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,8 @@
1
+ ## What and why
2
+
3
+ <!-- Short description of the change. -->
4
+
5
+ > **PR title must follow [Conventional Commits](https://www.conventionalcommits.org):** `feat: ...` (minor), `fix: ...` / `perf: ...` (patch), `feat!: ...` (breaking), or `docs:` / `chore:` / `ci:` / `test:` / `refactor:` (no release). The title becomes the commit on `main` and decides the next version.
6
+
7
+ - [ ] Tests added or updated
8
+ - [ ] Docs / `.env.sample` updated if behavior or config changed
@@ -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
@@ -0,0 +1,27 @@
1
+ # release-please reads the squash-merge commit, which is the PR title.
2
+ name: PR title
3
+
4
+ on:
5
+ pull_request_target:
6
+ types: [opened, edited, synchronize, reopened]
7
+
8
+ permissions:
9
+ pull-requests: read
10
+
11
+ jobs:
12
+ conventional-title:
13
+ runs-on: ubuntu-latest
14
+ steps:
15
+ - uses: amannn/action-semantic-pull-request@v5
16
+ env:
17
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
18
+ with:
19
+ types: |
20
+ feat
21
+ fix
22
+ perf
23
+ docs
24
+ chore
25
+ ci
26
+ test
27
+ refactor
@@ -0,0 +1,44 @@
1
+ # Publishes to npm via Trusted Publishing (OIDC), no npm token involved.
2
+ # The Trusted Publisher on npmjs.com must point at workflow file `release.yml`.
3
+ # Publishing lives here because releases created with GITHUB_TOKEN don't
4
+ # trigger other workflows.
5
+
6
+ name: Release
7
+
8
+ on:
9
+ push:
10
+ branches: [main]
11
+
12
+ permissions:
13
+ contents: write
14
+ pull-requests: write
15
+ id-token: write
16
+
17
+ jobs:
18
+ release-please:
19
+ runs-on: ubuntu-latest
20
+ outputs:
21
+ release_created: ${{ steps.release.outputs.release_created }}
22
+ tag_name: ${{ steps.release.outputs.tag_name }}
23
+ steps:
24
+ - id: release
25
+ uses: googleapis/release-please-action@v4
26
+
27
+ publish-npm:
28
+ needs: release-please
29
+ if: needs.release-please.outputs.release_created == 'true'
30
+ runs-on: ubuntu-latest
31
+ steps:
32
+ - uses: actions/checkout@v4
33
+ with:
34
+ ref: ${{ needs.release-please.outputs.tag_name }}
35
+ - uses: actions/setup-node@v4
36
+ with:
37
+ node-version: 24
38
+ registry-url: https://registry.npmjs.org/
39
+
40
+ # Trusted Publishing needs npm CLI >=11.5.1
41
+ - run: npm install -g npm@latest
42
+ - run: npm ci
43
+ - run: npm test
44
+ - run: npm publish
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
@@ -0,0 +1,3 @@
1
+ {
2
+ ".": "0.10.0"
3
+ }
package/AGENTS.md ADDED
@@ -0,0 +1,31 @@
1
+ # Soul
2
+
3
+ SQLite REST and realtime (WebSocket) server. Published to npm as `soul-cli` (CLI: `soul`). Node 22/24/26, CommonJS, Express 5, better-sqlite3.
4
+
5
+ ## Commands
6
+
7
+ - `npm run dev` — regenerate swagger, run with nodemon
8
+ - `npm test` — jest (needs no setup; env vars are set in the script)
9
+ - `npm run test:coverage` — enforces thresholds in `package.json` (`jest.coverageThreshold`)
10
+ - `npm run lint` / `npm run format` — eslint / prettier
11
+ - `npm run swagger-autogen` — regenerates `src/swagger/swagger.json`; commit it when routes change
12
+ - `scripts/dev.sh` — local instance with a ready superuser
13
+
14
+ A husky pre-commit hook runs the full test suite and lint-staged.
15
+
16
+ ## Layout (`src/`)
17
+
18
+ Request flow: `routes/` → `middlewares/` (+ `schemas/` Joi validation) → `controllers/` → `services/` → `db/`.
19
+
20
+ - `controllers/auth/` — users, roles, tokens
21
+ - `extensions.js` — user-provided extensions (`docs/extensions-examples.md`)
22
+ - `websocket.js` — realtime; `cli.js` / `commands.js` — CLI
23
+ - `config/` — env-driven config; new env vars go in `.env.sample` and `README.md`
24
+ - Tests live next to the code as `*.test.js`; shared helpers in `src/tests/`
25
+
26
+ ## Conventions
27
+
28
+ - Single quotes, 2-space indent, prettier-formatted. Few comments.
29
+ - Add or update tests with every change; keep coverage above the thresholds.
30
+ - Commits and PR titles use conventional prefixes: `feat:`, `fix:`, `perf:`, `docs:`, `chore:`, `ci:`, `test:`, `refactor:`. Breaking changes use `feat!:` or a `BREAKING CHANGE:` footer. These drive the version bump; `pr-title.yml` checks PR titles (squash-merge commit message).
31
+ - Don't edit `version` in `package.json` by hand. release-please opens a release PR from merged commits; merging it tags, creates the GitHub Release and publishes to npm (`.github/workflows/release.yml`). Force a version with a `Release-As: x.y.z` commit footer.
package/CHANGELOG.md ADDED
@@ -0,0 +1,35 @@
1
+ # Changelog
2
+
3
+ ## [0.10.0](https://github.com/thevahidal/soul/compare/soul-cli-v0.9.4...soul-cli-v0.10.0) (2026-11-16)
4
+
5
+
6
+ ### Features
7
+
8
+ * add global error handling, graceful shutdown, WebSocket auth, CORS/helmet ([e8c6c7b](https://github.com/thevahidal/soul/commit/e8c6c7b2bfe5f671974c785107cb652e62843d14))
9
+ * **core/cli:** Added `-S` flag ([654c1f5](https://github.com/thevahidal/soul/commit/654c1f598ed288e2d58c2284697d962f57c615ba))
10
+ * **core:** Integrated soul-studio ([60f240f](https://github.com/thevahidal/soul/commit/60f240f6a695ccf9e322a892f1d2ee6606eaee40))
11
+ * expose foreign key info on GET /api/tables/:name ([b3eff42](https://github.com/thevahidal/soul/commit/b3eff42c471c36f6927ceaceade17e2d1ff8a4f0))
12
+ * harden extensions with multi-file loading, opt-in auth, generic methods ([e832b94](https://github.com/thevahidal/soul/commit/e832b9460292710f8cfed6e0bec35b77fa846d6d))
13
+ * make auth cookie SameSite/Secure configurable ([1a9ac43](https://github.com/thevahidal/soul/commit/1a9ac432aae6ce63a70b246664ebc568c18943b4))
14
+ * **npm-publish:** Added proper ci, build, publish procedure ([82cf9d4](https://github.com/thevahidal/soul/commit/82cf9d42230dfa0ee78d17f3ef4cb3f78922d021))
15
+ * **npm-publish:** Added proper ci, build, publish procedure ([553b7be](https://github.com/thevahidal/soul/commit/553b7be19915afd3e95d95452a527cb9c8225ffd))
16
+
17
+
18
+ ### Bug Fixes
19
+
20
+ * **ci:** drop Node 20 from engines/CI matrix, unsupported by better-sqlite3 13 ([35b63ed](https://github.com/thevahidal/soul/commit/35b63ed49a3d649eece7cda8cc1ae6c267445f39))
21
+ * **core:** Fixed Soul Studio startup misconfiguration ([2b39777](https://github.com/thevahidal/soul/commit/2b3977759b78fb2c3a3a86991273f843931bfa7e))
22
+ * correct _users_roles unique constraint to (user_id, role_id) ([021c058](https://github.com/thevahidal/soul/commit/021c058ee825db17d9e9c844b936dbd0fad4f3a7))
23
+ * correct _users_roles unique constraint to (user_id, role_id) ([c06b403](https://github.com/thevahidal/soul/commit/c06b4039e600176e96400ce21ef0d2a6f12a3ea4))
24
+ * don't reject requests over an unrelated cookie the browser sends ([a99a329](https://github.com/thevahidal/soul/commit/a99a3296d8acd15edc8760a01d644fe3627241b7))
25
+ * give every JWT a unique jti to prevent cross-session revocation ([27f920e](https://github.com/thevahidal/soul/commit/27f920ea3a0c076bea1d1fa79fce68c5c52ba70c))
26
+ * keep yargs on 17 (v18 is ESM-only, breaks Jest on Node 22) ([a908687](https://github.com/thevahidal/soul/commit/a90868725282e2f2906a8a1102e0212baac7ad71))
27
+ * mount Studio at root and filter by path, not app.use('/studio', ...) ([acb66d9](https://github.com/thevahidal/soul/commit/acb66d911b355847c9bb59e4b52605f1da748135))
28
+ * mount Studio at root and filter by path, not app.use('/studio', ...) ([8f1b2fa](https://github.com/thevahidal/soul/commit/8f1b2fac7d80e1584fb375770c3072dd12c7972c))
29
+ * **npm-publish:** Removed `needs` key ([51a64cf](https://github.com/thevahidal/soul/commit/51a64cf103ccf0b89d175573ecf89923ad9d43cc))
30
+ * **npm-publish:** Removed `needs` key ([cdef494](https://github.com/thevahidal/soul/commit/cdef4943ba4dcb5ba0b10f99b6ca7ada3efe023c))
31
+ * **security:** address CodeQL findings on workflow permissions and PRAGMA/DROP ([97ae630](https://github.com/thevahidal/soul/commit/97ae6305be0ddd866a0ab3f7e6abdf6569464409))
32
+ * **security:** close SQL injection surface, validate identifiers against schema ([efeb8d1](https://github.com/thevahidal/soul/commit/efeb8d1152a0f0d8bfbf4c0dfd705aa4aae56fa7))
33
+ * **security:** eliminate PRAGMA identifier interpolation via table-valued functions ([aca2756](https://github.com/thevahidal/soul/commit/aca27566094d677a622edf5f41c8fe129cd4c8d3))
34
+ * unblock npm install, fix startup race, and rate-limit config bug ([e3b4f16](https://github.com/thevahidal/soul/commit/e3b4f16ac84fe697606085c9726b42a7c102df16))
35
+ * updatesuperuser crashes when setting --is_superuser via SQLite bind ([f5c3038](https://github.com/thevahidal/soul/commit/f5c30389d3e701314998229a2dee19e1232d855b))
package/CLAUDE.md ADDED
@@ -0,0 +1 @@
1
+ @AGENTS.md
package/README.md CHANGED
@@ -12,16 +12,16 @@
12
12
 
13
13
  ### Docker
14
14
 
15
- > This is the preferred method as the dependency [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) is making of lot of assumptions about the system it will be installed and running on which in most cases will lead to errors when installing soul.
15
+ > This is a convenient way to run Soul without worrying about your local Node.js version. Soul requires Node.js `22.x`, `24.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.
16
16
 
17
17
  Using the following Dockerfile:
18
18
 
19
19
  <details>
20
20
  <summary>Dockerfile</summary>
21
-
22
- ```nginx
23
- # node:19-alpine amd64
24
- FROM node@sha256:d0ba7111bc031323ce2706f8e424afc868db289ba40ff55b05561cf59c123be1 AS node
21
+
22
+ ```nginx
23
+ # node:22-alpine amd64
24
+ FROM node@sha256:76789712cd1ae89a1225eac9077010d68987a423588042dac30446f502f1858c AS node
25
25
 
26
26
  WORKDIR /app
27
27
 
@@ -29,12 +29,18 @@ ENV NODE_ENV="production"
29
29
 
30
30
  COPY package-lock.json package.json ./
31
31
 
32
- RUN apk update && apk add python3=3.11.10-r1 build-base=0.5-r3 && npm ci
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
33
37
 
34
38
  COPY . .
35
39
 
36
40
  CMD [ "npm", "start" ]
37
- ```
41
+
42
+ ```
43
+
38
44
  </details>
39
45
 
40
46
  You can proceed [to building the application](https://docs.docker.com/get-started/workshop/02_our_app/#build-the-apps-image).
@@ -42,7 +48,7 @@ You can proceed [to building the application](https://docs.docker.com/get-starte
42
48
  ### npm
43
49
 
44
50
  ```bash
45
- npm install -g soul-cli
51
+ npm install -g soul-cli
46
52
  ```
47
53
 
48
54
  ### 1. Running Soul
@@ -74,6 +80,8 @@ Options:
74
80
 
75
81
  ```
76
82
 
83
+ 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.
84
+
77
85
  Then to test Soul is working run the following command
78
86
 
79
87
  ```bash
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).
package/SECURITY.md ADDED
@@ -0,0 +1,19 @@
1
+ # Security Policy
2
+
3
+ ## Supported Versions
4
+
5
+ Only the latest release receives security fixes.
6
+
7
+ | Version | Supported |
8
+ | -------- | ------------------ |
9
+ | 0.9.x | :white_check_mark: |
10
+ | < 0.9 | :x: |
11
+
12
+ ## Reporting a Vulnerability
13
+
14
+ Please do not open a public issue. Report it privately through GitHub:
15
+ https://github.com/thevahidal/soul/security/advisories/new
16
+
17
+ You can expect an initial response within a few days. If the report is accepted,
18
+ we will work on a fix and publish it in a new release with credit to the reporter
19
+ (if wanted). If it is declined, we will explain why.
@@ -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`.
@@ -41,3 +41,7 @@ soul -d ./Chinook_Sqlite.sqlite -p 8000
41
41
  ## Namespaces
42
42
 
43
43
  1. [/ws/tables](ws/rows-examples.md) Examples for Rows websockets
44
+
45
+ ## Authentication
46
+
47
+ When Soul is running with `-a` (auth mode), WebSocket connections require the same `accessToken` cookie used by the REST API, and are subject to the same per-table read permission checks. Connect with the cookie set (e.g. `wscat --header "Cookie: accessToken=<token>"` or a browser session that already has it) -- connections without a valid, authorized token are closed with an error message.