planche 0.5.3 → 0.7.0

package/README.md

@@ -116,6 +116,52 @@ database connections open and forwards queries with the matching driver
   `~/.ssh/known_hosts` are honoured too). A changed key refuses the
   connection until the stale entry is removed.
 
+## Gateway mode
+
+Run one agent on a shared host so a team can use Planche with just a
+browser, without anyone holding database credentials:
+
+The web app it serves lives in its own package, so a plain `npx planche`
+stays a small download; install both on the gateway host:
+
+```bash
+npm i -g planche planche-app
+planche --gateway gateway.json --addr 0.0.0.0 --allow-remote \
+  --token "$(openssl rand -base64 24)" --public-url https://sql.example.com
+```
+
+(or `npx --package planche --package planche-app planche --gateway …`, or
+point at your own build with `--app-dir <dir>`)
+
+`gateway.json` lists named profiles; the credentials never leave this file:
+
+```json
+{
+  "name": "Acme staging",
+  "profiles": [
+    { "name": "Shop (read-only)", "driver": "mysql", "host": "db", "port": 3306,
+      "user": "reporting", "password": "…", "database": "shop" },
+    { "name": "Shop (writable)", "readOnly": false, "driver": "postgres",
+      "host": "pg", "port": 5432, "user": "app", "password": "…", "database": "shop" }
+  ]
+}
+```
+
+- Browsers only ever send `{ "profile": "Shop (read-only)" }`; `/connect`
+  bodies with credentials are refused in gateway mode.
+- Profiles are **read-only by default**: the agent refuses anything but a
+  single `SELECT` / `WITH … SELECT` / `SHOW` / `DESCRIBE` / `EXPLAIN` per
+  request (statement filter), and additionally puts the session in read-only
+  mode where the engine supports it (MySQL, PostgreSQL, SQLite). Set
+  `"readOnly": false` on a profile to allow writes.
+- The agent serves the web app itself at `/` (`--serve-app`, on by default in
+  gateway mode; needs `planche-app` or `--app-dir`) so the app talks to its
+  own origin — the strict CSP stays
+  intact and no `--origin` is needed. Put a TLS reverse proxy in front and
+  pass its URL as `--public-url`; the printed pairing link is single-use, so
+  share the token (`--print-token`) with teammates and let them paste it in
+  the connect dialog's *Configure* box.
+
 ## Security
 
 - Every request except `GET /health` and `POST /pair` requires the bearer
@@ -130,6 +176,7 @@ database connections open and forwards queries with the matching driver
   machine can reach it. It speaks plain HTTP, so binding to another address
   requires `--allow-remote` plus an explicit token, and should only be done
   behind a TLS reverse proxy or an SSH port forward.
+- In gateway mode credentials live only in the gateway config file on the server; browsers pick profiles by name. Read-only profiles are enforced by the agent (statement filter + engine session read-only), not by the UI.
 - The agent never stores credentials. They are passed per connection by the
   app (including SSH passwords and private key contents) and live in memory
   only while the connection is open. The only thing written to disk is the