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.
- package/.env.sample +11 -2
- package/.github/dependabot.yml +9 -0
- package/.github/pull_request_template.md +8 -0
- package/.github/workflows/ci.yml +33 -0
- package/.github/workflows/pr-title.yml +27 -0
- package/.github/workflows/release.yml +44 -0
- package/.husky/pre-commit +0 -3
- package/.release-please-manifest.json +3 -0
- package/AGENTS.md +31 -0
- package/CHANGELOG.md +35 -0
- package/CLAUDE.md +1 -0
- package/README.md +16 -8
- package/ROADMAP.md +154 -0
- package/SECURITY.md +19 -0
- package/docs/extensions-examples.md +96 -16
- package/docs/ws-examples.md +4 -0
- package/eslint.config.js +29 -0
- package/package.json +44 -24
- package/release-please-config.json +10 -0
- package/scripts/dev.sh +64 -0
- package/src/cli.test.js +128 -0
- package/src/config/index.js +10 -2
- package/src/config/index.test.js +120 -0
- package/src/controllers/auth/common.js +1 -16
- package/src/controllers/auth/common.test.js +23 -0
- package/src/controllers/auth/tables.js +1 -1
- package/src/controllers/auth/token.js +30 -7
- package/src/controllers/auth/user.js +20 -20
- package/src/controllers/auth/user.test.js +232 -0
- package/src/controllers/auth.test.js +445 -0
- package/src/controllers/rows.js +159 -112
- package/src/controllers/rows.test.js +88 -1
- package/src/controllers/tables.js +63 -17
- package/src/controllers/tables.test.js +185 -0
- package/src/db/index.test.js +21 -0
- package/src/extensions.js +105 -36
- package/src/extensions.test.js +340 -0
- package/src/index.js +37 -20
- package/src/index.test.js +118 -0
- package/src/middlewares/api.js +1 -1
- package/src/middlewares/api.test.js +29 -0
- package/src/middlewares/auth.js +11 -48
- package/src/middlewares/auth.test.js +105 -0
- package/src/middlewares/validation.test.js +60 -0
- package/src/schemas/index.js +3 -1
- package/src/schemas/rows.js +15 -5
- package/src/schemas/tables.js +28 -4
- package/src/server.js +85 -4
- package/src/services/authService.js +33 -3
- package/src/services/authService.test.js +115 -0
- package/src/services/rowService.js +25 -18
- package/src/services/rowService.test.js +153 -0
- package/src/services/tableService.js +15 -17
- package/src/services/tableService.test.js +190 -0
- package/src/swagger/swagger.json +4 -7
- package/src/tests/index.js +1 -1
- package/src/utils/index.js +25 -2
- package/src/utils/index.test.js +135 -0
- package/src/utils/logger.js +15 -0
- package/src/utils/sql.js +112 -0
- package/src/utils/sql.test.js +115 -0
- package/src/websocket.js +47 -8
- package/src/websocket.test.js +121 -0
- package/.eslintignore +0 -2
- package/.eslintrc.js +0 -24
- package/.github/workflows/npm-publish.yml +0 -23
- 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
|
-
|
|
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
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
|
|
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
|
-
|
|
23
|
-
# node:
|
|
24
|
-
FROM node@sha256:
|
|
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
|
-
|
|
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
|
-
|
|
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`.
|
|
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:
|
|
45
|
-
path:
|
|
63
|
+
method: "GET",
|
|
64
|
+
path: "/api/hello-soul",
|
|
46
65
|
handler: (req, res, db) => {
|
|
47
66
|
res.status(200).json({
|
|
48
|
-
|
|
67
|
+
message: "Hello Soul!",
|
|
49
68
|
});
|
|
50
69
|
},
|
|
51
70
|
};
|
|
52
71
|
|
|
53
72
|
const timestamp = {
|
|
54
|
-
method:
|
|
55
|
-
path:
|
|
73
|
+
method: "GET",
|
|
74
|
+
path: "/api/timestamp",
|
|
56
75
|
handler: (req, res, db) => {
|
|
57
76
|
res.status(200).json({
|
|
58
|
-
|
|
77
|
+
timestamp: Date.now(),
|
|
59
78
|
});
|
|
60
79
|
},
|
|
61
80
|
};
|
|
62
81
|
|
|
63
82
|
const greetings = {
|
|
64
|
-
method:
|
|
65
|
-
path:
|
|
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
|
-
|
|
89
|
+
message: `${greeting} ${name}!`,
|
|
71
90
|
});
|
|
72
91
|
},
|
|
73
|
-
}
|
|
92
|
+
};
|
|
74
93
|
|
|
75
94
|
const searchTables = {
|
|
76
|
-
method:
|
|
77
|
-
path:
|
|
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`.
|
package/docs/ws-examples.md
CHANGED
|
@@ -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.
|