61 lines
3.2 KiB
Markdown
61 lines
3.2 KiB
Markdown
# Design: NATS `external-apps` user
|
|
|
|
## Goal
|
|
|
|
Add a third NATS user, `external-apps`, so third-party / external applications can connect to `wss://nats.tes.gd` with their own credential instead of borrowing the `admin` or `volcanic-agents` account.
|
|
|
|
## Scope decisions
|
|
|
|
- **Permissions:** unrestricted. Same shape as the existing `admin` and `volcanic-agents` users — no `permissions` block, so full publish/subscribe on any subject, JetStream management included. Scoped permissions are explicitly out of scope for this change; if we later need to lock down external callers, that's a follow-up.
|
|
- **Credential style:** password (not opaque bearer token). Env var is `NATS_EXTERNAL_APPS_PASSWORD`, following the `NATS_PASSWORD` convention used by `admin` rather than the `..._TOKEN` convention used by `volcanic-agents`.
|
|
- **Wire protocol / transport:** unchanged. The user connects the same way as the others (WebSockets at `wss://nats.tes.gd`, standard user+password auth on the wire).
|
|
|
|
## Change surface
|
|
|
|
1. **`docker-compose.yml`** — inside `configs.nats-conf.content`, append one entry to `authorization.users`:
|
|
```
|
|
{ user: "external-apps", password: "${NATS_EXTERNAL_APPS_PASSWORD}" }
|
|
```
|
|
Substitution happens at Docker Compose parse time, so NATS sees a static config on disk.
|
|
|
|
2. **Coolify env var** — add `NATS_EXTERNAL_APPS_PASSWORD` on the `nats` application (project `Volcanic MFEs`, app UUID from local `deploy.json`). Value: a fresh random secret (e.g. `openssl rand -hex 32`).
|
|
|
|
3. **`credentials.local.json`** — add a third entry under `users`:
|
|
```json
|
|
"external-apps": { "user": "external-apps", "password": "…", "note": "…" }
|
|
```
|
|
Mirrors the Coolify env value. File is gitignored.
|
|
|
|
4. **`CLAUDE.md`** — update the two spots that enumerate users so the doc stays in sync:
|
|
- The "Connection details (for agents managing this NATS)" intro list.
|
|
- The "Auth" bullet under "What's inside the server".
|
|
Mention that `external-apps` is the intended account for third-party callers, unrestricted for now.
|
|
|
|
5. **Deploy** — commit the compose + doc changes on `main`, then fire-and-forget `POST /api/v1/deploy?uuid=<app-uuid>` on Coolify. Do not poll.
|
|
|
|
## Ordering constraint
|
|
|
|
Set the Coolify env var **before** pushing the compose change. Otherwise the compose parser substitutes an empty string, the config lands as `password: ""`, and until the next deploy anyone who connects with empty credentials for user `external-apps` is authenticated. Order:
|
|
|
|
1. PATCH the env var into Coolify.
|
|
2. Commit + push the compose + doc changes.
|
|
3. Trigger the deploy.
|
|
|
|
## Verification
|
|
|
|
After the deploy triggers, connect from a workstation with the `nats` CLI as the new user and confirm auth works:
|
|
|
|
```
|
|
nats --server=wss://nats.tes.gd \
|
|
--user=external-apps --password="$NATS_EXTERNAL_APPS_PASSWORD" \
|
|
server info
|
|
```
|
|
|
|
A `Server ID` response = success. An auth error = the env var didn't land or the substitution failed; check `docker logs` on the Coolify host per the existing "Gotchas" section of `CLAUDE.md`.
|
|
|
|
## Out of scope
|
|
|
|
- Scoped/restricted permissions for external callers (deliberate — noted above).
|
|
- Rotating the existing `admin` or `volcanic-agents` credentials.
|
|
- Adding a UI or self-service flow for provisioning further users.
|