fix: agent REST router mounted before 404; promote opens pre-filled modal; Directory refresh; Vault OpenBao (v1.28.0) (#169)

- api_agent: REST router mounted synchronously in app.js (was post-listen, behind
  the 404 catch-all -> /api/agent/* 404'd); WS init stays on onListen
- directory.ejs: promote opens a pre-filled resource modal (Save confirms);
  addEdge/removeEdge call loadResources() (was undefined loadData -> stale table);
  addGroup/removeGroup refresh the Access column
- vault.ejs: 'Powered by OpenBao' header badge

.dockerignore

@@ -19,6 +19,9 @@
 !API.md
 !directory_spec.md
 !docs/**/*.md
+# The screenshots the README (served at /docs/overview) links. `COPY docs /docs`
+# in Dockerfile.openldap needs these present in the build context.
+!docs/images/**
 
 # Tests (excluded from production builds; test-runner Dockerfile copies them explicitly)
 # nodejs/tests/

CHANGELOG.md

@@ -1,3 +1,65 @@
+# v1.28.0
+- fix: `/api/agent/nodes` no longer 404s — the previous "unconditional mount" was still inside the post-listen `onListen` hook, so the REST router landed *behind* app.js's terminal 404 catch-all and every `/api/agent/*` request 404'd. The router is now mounted synchronously in `app.js` before the 404 handler; only the agent WebSocket setup runs on `onListen`.
+- feat: promoting a discovered inventory resource now opens the resource form pre-filled with the discovered data (name, kind, IP, subtype, …) for review; the modal's Save confirms the promote (creates the LDAP groups + marks it managed) instead of silently promoting.
+- fix: Directory table no longer goes stale after add/remove edge — `addEdge`/`removeEdge` called an undefined `loadData()`, which threw and left the host/parent linkage stale until a manual refresh; they now call `loadResources()`. `addGroup`/`removeGroup` also refresh so the Access column stays accurate.
+- feat: Vault page states it's powered by OpenBao (header badge linking to openbao.org).
+
+# v1.27.0
+- fix: Directory group names now match `docs/GROUPS.md` exactly — per-resource groups are `{site}_{kind}_{name}_{level}` (`site_local_host_theta-env_access`, `site_local_app_sso-manager_access`), with the kind always present and the resource name slug stripped of its kind prefix. Services map to the `app` kind. The access-request + resolver tests were updated to the documented convention.
+- fix: a site resource now carries only `god_admin` + the site-wide groups (`{site}_super_admin`, `{site}_everyone`); the kind-scoped aggregates are still created for nesting but are no longer surfaced on the site's modal.
+- fix: groups no longer appear 3× under a resource — the Directory self-heal (which runs on every load) was creating duplicate `ResourceGroup` links; linking is now idempotent (check-then-create).
+- fix: `/api/agent/nodes` no longer 404s — the agent REST router is mounted unconditionally instead of being gated on the WebSocket server being up.
+- fix: `POST /api/shared-secrets/` rejected valid slugs — the slug regex now allows underscores (was hyphens-only).
+- fix: `GET /api/shared-secrets/` crashed with `s.path is not a function` — the list spread dropped the instance's `path()` method; now uses the static `SharedSecret.pathFor`.
+- fix: promoting a discovered inventory resource crashed with `Resource.update is not a function` — `update` is an instance method; the promote handler now loads an instance and calls `update()` on it.
+- feat: Vault → Apps tab now lists minted app tokens (the "Minted apps" list) — each is a scoped OpenBao credential for an external service; sso renews them and the list shows renewal state, so a minted credential no longer vanishes after its once-only token display. New `GET /api/vault/apps`.
+- feat: Vault page documents itself — a `/docs/vault` help icon in the header, and the doc now covers the Apps + Shared tabs.
+- feat: discovery plugin cards show last-run time + status (ok/error) and a Logs button that opens the captured run log.
+
+# v1.26.1
+- fix: the legacy `app_super_admin` group is gone — `SUPER_ADMIN_GROUP` (nested into every resource's `_admin` group by auto-provisioning) is now `god_admin`, and `docker-entrypoint.sh` no longer seeds or nests `app_super_admin` (god_admin is nested into the `app_sso_*` groups directly). `isSuperAdmin` still recognizes a pre-existing `app_super_admin` as a migration alias, so an old deployment isn't stripped of rights until it's rebuilt.
+
+# v1.26.0
+- feat: complete the group model (docs/GROUPS.md) — `god_admin` is now seeded into LDAP and nested into `app_super_admin`; every site auto-provisions `{site}_super_admin`, `{site}_hosts_*`/`{site}_apps_*` aggregates and `{site}_everyone`; per-resource `_admin`/`_access` groups (named `{site}_{slug}_{level}`, the kind carried in the resource slug) are nested into the site aggregates so the inheritance lattice exists in LDAP, not just in the resolver. Site/aggregate groups are self-healed idempotently on every Directory load, so a directory seeded by an older release picks them up without a rebuild.
+- feat: the naming convention is now enforced server-side — `POST /api/directory-admin/groups` rejects a group CN that isn't a valid group for the target resource (its own `_admin`/`_access`/capability, a site aggregate, a site-level group, or `god_admin`), so the free-text field can no longer mint `*_accessmember`-style names
+- feat: `god_admin` is managed from the Directory — the site resource modal surfaces `god_admin` + the site-level groups as associated groups, so its members (and the site's) are editable right there
+- fix: Directory agent status dots no longer paint every host red when the `/api/agent/nodes` endpoint is unreachable (older app or transient outage) — they now show a neutral grey "agent service unreachable" instead of a false alarm
+- fix: Profile + API Tokens cards are both full-width on the profile page (the API card was a narrower centered block)
+- fix: in-app `/docs/<slug>` pages returned 500 — `Dockerfile.openldap` never copied the `docs/` tree into the image (only the root README/CHANGELOG/API/directory_spec), so every page but those few hit a missing-file error; the whole `docs/` dir now ships, and doc images are served at `/docs/images`
+- test: group resolver tests now cover the prefixed site-slug convention (`site_local_...` is kept verbatim, not re-slugified to `site-local`)
+
+# v1.25.0
+- feat: hierarchical group & permission model (docs/GROUPS.md) — god_admin, {site}_super_admin, {site}_hosts_*/{site}_apps_* aggregates, and per-resource {site}_host_<slug>_admin/access/<capability>; inheritance resolver (admin implies access, capabilities explicit), meta everyone/{site}_everyone groups
+- feat: remove the standalone Groups page — group management is tied to adopted Directory resources (help link to the model in the Directory toolbar)
+- feat: console admin recognizes god_admin and site-scoped super/app-admin groups (legacy app_sso_admin/app_super_admin kept as migration aliases)
+
+# v1.24.0
+- feat: Agents merged into the Directory — removed the standalone Agents page. Host rows show a green/yellow/red theta-agent status dot (healthy / high-load / not connected) and the resource modal gained a Metrics tab with live telemetry + discovery
+- feat: Discovery Plugins New-plugin modal — slug is now derived from the name (field removed), the cron field is a dropdown (hourly/daily/weekly + custom), and per-plugin settings are collected from the configSchema (e.g. Proxmox url/tokenId/tokenSecret) instead of an empty config
+- feat: Directory resource slug is now read-only and derived from the name
+- feat: Vault page restyled to match the rest of the site (bounded container, card + nav-tabs header, h4)
+- feat: navbar — the username is no longer underlined; only the active nav link is bold + underlined
+
+# v1.23.0
+- fix: /api/vault proxy never injected X-Vault-Token — the true root cause of the recurring vault 403 "permission denied". The proxy declared its hook with http-proxy-middleware v3 syntax (`on: { proxyReq }`), which the installed HPM v2 silently ignores, so every request reached OpenBao unauthenticated (and the client's sso auth headers were never stripped). Rewritten as v2 `onProxyReq`.
+- fix: vault proxy header injection ordered before `fixRequestBody` — the body write flushes headers, so setting X-Vault-Token after it silently failed on every POST/PUT (writes would still 403 even with the hook fixed)
+- fix: initORM add-only schema heal — `sequelize.sync()` never ALTERs existing tables, so columns added by newer releases (e.g. `PluginInstance.lastLog`, which crashed the scheduler on every boot of an upgraded deployment) are now detected via describeTable and added with addColumn (additive only, per-column fail-soft)
+- feat: external-app vault tokens are long-lived and auto-renewed — minted via the new `sso-app` token role (periodic 768h, falls back to sso-broker's 24h role until theta-suite setup.sh is re-run); sso stores each token's accessor (new VaultAppToken model — an accessor can renew/revoke but not authenticate) and renews all of them at boot + every 6h via auth/token/renew-accessor, so a downstream app's credential stays valid as long as sso runs with zero renewal code in the app
+- feat: re-minting an app token revokes the app's previous token via its stored accessor — exactly one live credential per app, no zombies
+- test: wire-level tests for the vault proxy (real HTTP round-trip asserting token injection, auth-header stripping, path rewrite, and POST body integrity) + app-token accessor lifecycle tests
+
+# v1.22.0
+- feat: Agents page — live list of connected theta-agent hosts with telemetry (CPU/RAM/disk/ZFS/GPU) + online status, updating via socket.io
+- security: auth + admin-gate the /api/agent REST routes (previously unauthenticated)
+
+# v1.21.0
+- fix: always reconcile OpenBao policy content before serving a (possibly cached) token, so stale stored policies can no longer cause a recurring vault 403 "permission denied"
+- feat: shared secrets — users can publish secrets to secret/shared/<owner>/<slug> and grant read access to other users and downstream apps (OpenBao ACL policy edits, applied live)
+- feat: shared-secrets API + Shared tab in the vault UI
+
+# v1.20.0
+- fix: OpenBao 403 on vault secrets list (directory list grants + policy self-heal)
+
 ## v1.19.0
 - Added WebSocket endpoint for theta-agent C2
 

DEPLOYMENT.md

@@ -0,0 +1,512 @@
+# Deployment Guide — SSO Manager
+
+Two supported deployment methods:
+
+1. **Docker** — a single all-in-one image bundling the app + OpenLDAP + Redis (`docker compose up`).
+2. **Bare metal** — `install.sh` on Debian/Ubuntu (installs Node.js, OpenLDAP, Redis, the app, and a systemd unit).
+
+## How configuration works
+
+The app loads configuration via [`@simpleworkjs/conf`](https://www.npmjs.com/package/@simpleworkjs/conf), which deep-merges, in order:
+
+1. `conf/base.js` (committed, generic defaults)
+2. `conf/<NODE_ENV>.js` (optional)
+3. `conf/secrets.js` (gitignored — secrets + per-deployment values)
+4. **`app_*` environment variables** — the highest-precedence layer
+
+Any env var whose name starts with `app_` overrides the merged config. The rest
+of the name is split on **double-underscore** (`__`) into a nested path. Values
+are `JSON.parse`-coerced when possible (numbers, booleans, null, JSON) and kept
+as raw strings otherwise. Examples:
+
+| Env var | Sets | Type |
+|---------|------|------|
+| `app_ldap__url=ldap://host:389` | `conf.ldap.url` | string |
+| `app_ldap__bindPassword=secret` | `conf.ldap.bindPassword` | string |
+| `app_ldap__uidGidMin=1500` | `conf.ldap.uidGidMin` | number (new-user id floor) |
+| `app_oauth__jwtSecret=...` | `conf.oauth.jwtSecret` | string |
+| `app_smtp__secure=false` | `conf.smtp.secure` | boolean |
+| `app_oauth__token_lifetime__access_token=3600` | `conf.oauth.token_lifetime.access_token` | number |
+| `app_name=My SSO` | `conf.name` | string |
+
+> **Requires `@simpleworkjs/conf` >= 1.1.0.** The Docker image will not honor
+> `app_*` env vars on 1.0.0. Before building the image, refresh the app's
+> dependency lock from the `nodejs/` directory:
+> ```bash
+> cd nodejs && npm install @simpleworkjs/conf@^1.1.0
+> ```
+
+---
+
+## Method 1: Docker (all-in-one)
+
+The image (`Dockerfile.openldap`) bundles OpenLDAP, Redis, and the app in one container.
+The app connects to the bundled slapd over `localhost:389` automatically; you only
+need to set a few secrets.
+
+### Setup
+
+The bundled `docker-compose.yml` reads config from a bind-mounted
+`./config/sso-secrets.js` (not from a `.env` file). Copy the example, fill in
+your secrets, then build + start:
+
+```bash
+mkdir -p config && chmod 700 config
+cp secrets.js.example config/sso-secrets.js
+$EDITOR config/sso-secrets.js     # set ldap.bindPassword, oauth.jwtSecret, ...
+docker compose up -d --build
+```
+
+`docker-entrypoint.sh` symlinks `/config/sso-secrets.js` → `/app/conf/secrets.js`
+so `@simpleworkjs/conf` reads it, and pulls the server-side LDAP vars (base DN,
+admin password, org, domain, cert CN, JWT secret) out of the same file. No
+`app_*` env is passed — `app_*` env would override `secrets.js` (env beats the
+file in `@simpleworkjs/conf`), so the file is kept authoritative.
+
+> **Your domain is entered once, as the LDAP base DN.** Set `stack.ldapBaseDn`
+> (e.g. `dc=718it,dc=biz`) and keep the LDAP DNs consistent with it — they all
+> derive from that one value: `ldap.bindDN` = `cn=admin,<dn>`,
+> `ldap.userBase` = `ou=people,<dn>`, `ldap.groupBase` = `ou=groups,<dn>`,
+> and `stack.ldapDomain` = the dotted form (`718it.biz`). `oauth.issuer` is the
+> public SSO URL (`https://<ssoHost>`). Drifting these apart (e.g. leaving
+> `ldap.bindDN` at `dc=example,dc=com` while `stack.ldapBaseDn` is your real
+> domain) makes the SSO bind against a non-existent root DN and every login
+> fails with `Invalid Credentials`.
+>
+> Running the unified `theta-env` stack? You don't hand-edit these DNs at all
+> — its `setup.sh` generates `./config/sso-secrets.js` (+ `./config/proxy-secrets.js`)
+> from a single `setup.env` (where the domain is asked once, as the base DN) with
+> random secrets, and snapshots state before rebuilds — so the DNs can't drift.
+> See the theta-env README.
+
+**Quick test (defaults):** with no `./config/sso-secrets.js` the entrypoint
+falls back to env-mode with safe defaults (`dc=example,dc=com`, admin password
+`admin`, an auto-generated JWT secret) — fine for kicking the tires, not for
+production.
+
+**Advanced — env vars instead of the file:** the entrypoint also supports
+config via `LDAP_*` / `app_*` env vars (env-mode, used when
+`/config/sso-secrets.js` is absent). Since the bundled compose no longer passes
+those env vars, you'd add them to its `environment:` block yourself, e.g.
+`LDAP_ADMIN_PASS`, `JWT_SECRET`, `app_oauth__issuer`. This is mainly for
+bare-metal / advanced standalone use; most deployments should use the file.
+
+### What the entrypoint does
+
+`docker-entrypoint.sh` (run as the container entrypoint):
+
+1. If `/config/sso-secrets.js` is mounted, symlinks it to `/app/conf/secrets.js`
+   and reads the server-side LDAP vars from it (secrets.js mode). Otherwise it
+   derives them from `LDAP_*` env vars with safe defaults (env mode).
+2. Generates a self-signed TLS cert (unless one is already present at
+   `LDAP_CERT_DIR`), generates a `slapd.conf` for the bundled OpenLDAP (`mdb`
+   database, `pw-sha2`/`ppolicy`/`memberof`/`refint` modules + overlays, TLS,
+   indexes, access controls), and starts `slapd -f /etc/openldap/slapd.conf`
+   listening on `ldap:///` (389) and `ldaps:///` (636).
+3. Seeds the directory (base DN, `ou=people`/`ou=groups`/`ou=policies`, a default
+   `pwdPolicy`, and the required SSO groups `app_sso_admin`, `app_sso_invite`,
+   `app_sso_oauth_admin`, `app_sso_service_account`) — idempotently, so
+   container restarts are safe.
+4. Starts a bundled Redis (the app uses `model-redis` for models/sessions and
+   stores OAuth clients there), AOF+RDB persisted to `/data`, unless
+   `app_redis__host` is set (then it's expected to be external).
+5. In env mode, exports `app_*` env vars so the app binds to the local slapd. In
+   secrets.js mode it exports none (the app reads the file directly).
+6. `exec`s `node bin/www`.
+
+### Access
+
+- SSO Manager UI: `http://localhost:3001` (HTTP inside the container — put a TLS-terminating proxy in front for browser access)
+- Health check: `http://localhost:3001/health` → `{"status":"ok"}`
+- OIDC discovery: `http://localhost:3001/.well-known/openid-configuration`
+- LDAP (internal, app↔slapd): `ldap://localhost:389` (not mapped to the host)
+- LDAPS (direct binds: Linux hosts, LDAP-native apps): `ldaps://<host>:636` (TLS)
+
+### API tokens (personal access tokens)
+
+Any logged-in user can mint a long-lived bearer token to call the management
+API from scripts/CI/other services, without a browser session. Tokens are
+self-service and authenticate **as their creator** — a token carries the
+creator's LDAP group permissions, so the same `permission.byGroup` checks apply
+(group membership is re-resolved from LDAP live on each request).
+
+Create one in the UI under **API Tokens** (the token string is shown **once**),
+then use it as a bearer token:
+
+```bash
+curl -H "Authorization: Bearer sso_<id>_<secret>" https://sso.example.com/api/user
+```
+
+Format: `sso_<id>_<secret>` — the `id` is the lookup key, the `secret` is
+bcrypt-hashed and never stored in plaintext. Rotate or revoke a token from the
+same UI page; revocation takes effect immediately. Optional expiry (in days) at
+creation. API tokens persist in the bundled Redis, so they survive rebuilds
+(Redis is persisted via AOF — see *Backups and restore*).
+
+The token has the same access as a browser session for that user — an
+`app_sso_admin`'s token can manage users/groups; a non-admin's token is limited
+to what they could do in the UI.
+
+### Logs
+
+The all-in-one image runs the Node app and slapd (OpenLDAP) in one container,
+both writing to the container's stdout/stderr, so `docker compose logs` is the
+primary view (slapd runs with `-d 0`, so LDAP output is there too).
+
+```bash
+docker compose logs -f sso-manager                       # app + slapd (stdout/stderr)
+docker compose logs --tail=200 --since=10m sso-manager   # recent context
+docker compose exec sso-manager ldapsearch -x -H ldap://localhost:389 \
+  -D "cn=admin,$LDAP_BASE_DN" -W -b "$LDAP_BASE_DN"       # LDAP health check
+```
+
+### Available environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LDAP_BASE_DN` | `dc=example,dc=com` | slapd suffix + app user/group base |
+| `LDAP_DOMAIN` | derived from `LDAP_BASE_DN` | DNS domain; default for `LDAP_CERT_CN` and OAuth issuer |
+| `LDAP_ADMIN_PASS` | `admin` | slapd root password + app bind password |
+| `ORG_NAME` | `SSO Manager` | org name in UI/email/group descriptions |
+| `JWT_SECRET` | auto-generated | OAuth JWT signing secret (persist it!) |
+| `OAUTH_ISSUER` | `https://sso.<LDAP_DOMAIN>` | OIDC issuer in the discovery doc (browser-facing URL) |
+| `LDAP_CERT_CN` | `LDAP_DOMAIN` | CN/SAN on the LDAPS cert (hostname clients verify against) |
+| `LDAP_CERT_DIR` | `/etc/openldap/certs` | where the entrypoint looks for `ldap.crt`+`ldap.key` (mount your own here) |
+| `SMTP_HOST`/`SMTP_PORT`/`SMTP_USER`/`SMTP_PASS`/`SMTP_FROM` | localhost / 587 / empty | outbound email |
+| `PORT` | `3001` | host port mapped to the UI |
+| `LDAPS_PORT` | `636` | host port mapped to LDAPS |
+| `LDAP_PORT` | `389` | uncomment the host mapping in compose to expose plain LDAP (not recommended) |
+| `LDAP_SERVER_ID` | empty | Unique integer ID (e.g. 1, 2) required to enable Multi-Master replication |
+| `LDAP_REPLICATION_HOSTS` | empty | Space-separated list of other sites' LDAP URLs for replication (e.g. `ldaps://site2:636`) |
+
+Any `app_*` var may also be set directly to override any config value (see the
+table at the top).
+
+### LDAP TLS (LDAPS / StartTLS)
+
+The bundled slapd generates a **self-signed cert** on first start (CN = `LDAP_CERT_CN`,
+valid 10 years, SAN includes the CN + `localhost` + `127.0.0.1`) and listens on
+`ldaps:///` (636) plus offers StartTLS on `ldap:///` (389). The cert is stored on the
+`ldap-certs` volume so it persists across container recreation — clients don't need
+to re-trust on every rebuild.
+
+The `/integrations` page derives its LDAPS URL from the OAuth issuer by default.
+To advertise a separate, internal-only hostname (e.g. `ldap.internal.example.com`
+or `sso-manager` for Docker-internal clients), set `conf.ldap.ldapsHost` in your
+secrets file or pass `app_ldap__ldapsHost=...`. See `docs/ldap.md` for
+recommended network layouts and how to match the cert SAN to the hostname.
+
+- **Trusting the self-signed cert** (clients): copy `/etc/openldap/certs/ldap.crt`
+  out of the container and add it to the client's trusted CA store, or set
+  `TLS_REQCERT never` for quick-and-dirty LAN use. Fetch it with:
+  ```bash
+  docker compose cp sso-manager:/etc/openldap/certs/ldap.crt ./ldap.crt
+  ```
+- **Use your own cert** (CA-signed / internal CA): replace the `ldap-certs` named
+  volume with a bind mount containing your own `ldap.crt` + `ldap.key`:
+  ```yaml
+  volumes:
+    - ./certs:/etc/openldap/certs   # must contain ldap.crt + ldap.key
+  ```
+  The entrypoint leaves existing certs untouched (idempotent).
+
+> Port 389 (plain LDAP) is **not** mapped to the host by default, to avoid cleartext
+> password binds over the LAN. Direct-LDAP clients should use LDAPS (636) or
+> StartTLS. Uncomment the `389` mapping in `docker-compose.yml` only if you need
+> plain LAN binds and accept the risk.
+
+### Fronting with a reverse proxy (theta42/proxy)
+
+The SSO Manager runs HTTP inside the container; terminate TLS at a front proxy.
+The [`theta42/proxy`](https://github.com/theta42/proxy) is an OIDC-protected reverse
+proxy and a natural fit — it's both an **OIDC client** of the SSO Manager *and* a
+**direct LDAP client** for user lookups. To run both together:
+
+1. **Put them on one Docker network** so the proxy can reach the SSO Manager
+   internally at `http://sso-manager:3001` for token/userinfo (server-to-server),
+   without exposing the SSO Manager's HTTP port to the internet:
+   ```yaml
+   # in the proxy's compose, or a shared external network:
+   networks:
+     - sso-net
+   ```
+2. **Set the SSO's `OAUTH_ISSUER`** to the *browser-facing* HTTPS URL the proxy
+   serves the SSO at (e.g. `https://sso.yourdomain.com`). The proxy's
+   `oidc.issuer`/endpoints must match — it can get them from the SSO's
+   `/.well-known/openid-configuration`. Server-to-server calls from the proxy go to
+   the internal `http://sso-manager:3001` URL; only the issuer/redirect URLs must
+   be public.
+3. **Register the proxy as an OAuth/OIDC client** in the SSO Manager UI, with a
+   `redirectUri` matching the proxy's callback (e.g.
+   `https://proxy.yourdomain.com/api/auth/oidc/callback`), and put the client
+   secret in the proxy's `secrets.js`.
+4. **LDAP for the proxy**: point the proxy's `ldap.url` at
+   `ldaps://sso-manager:636` (TLS, same Docker network) rather than a LAN IP, and
+   create a dedicated LDAP service account under `ou=people` (e.g.
+   `cn=ldapclient,ou=people,…`) via the SSO Manager UI — don't reuse the admin DN.
+
+### Backups and restore
+
+**What lives where**
+
+| State | Location | Persisted? |
+|-------|----------|------------|
+| LDAP directory (users, groups, policies) | `ldap-data` volume (`/var/lib/ldap`) | yes (volume) |
+| LDAP TLS cert | `ldap-certs` volume (`/etc/openldap/certs`) | yes (volume) |
+| Redis (OAuth clients, tokens, sessions) | `sso-data` volume (`/data`) | yes (AOF + RDB) |
+| Secrets (LDAP admin pass, JWT secret, SMTP) | `./config/sso-secrets.js` (bind mount) | your responsibility — back up off-host |
+
+**Automatic snapshots** — when run as part of the unified `theta-env` stack,
+`setup.sh` snapshots LDAP + Redis + `./config/` to `./backups/<timestamp>/`
+before every rebuild and keeps the last `BACKUP_KEEP` (default 5). Standalone
+deployments should run `ops/backup.sh` the same way (on a cron/systemd timer,
+or by hand before an upgrade):
+
+```bash
+./ops/backup.sh              # keeps the last 5 by default
+./ops/backup.sh 10           # or override retention
+BACKUP_KEEP=10 ./ops/backup.sh
+```
+
+It snapshots LDAP (`slapcat`, auto-detecting your base DN from
+`./config/sso-secrets.js`), Redis (`BGSAVE`, falling back to a synchronous
+`SAVE` if that doesn't complete quickly), and `./config/` to
+`./backups/<timestamp>/`, pruning older backups beyond the retention count —
+the same approach `theta-env`'s `setup.sh` uses, just scoped to this one
+container. Equivalent manual steps, if you'd rather not use the script:
+
+```bash
+# LDAP — full directory export (works while slapd is running)
+docker compose exec sso-manager slapcat -f /etc/openldap/slapd.conf \
+  -b "dc=yourdomain,dc=com" > ldap-backup-$(date +%F).ldif
+
+# Redis — hot snapshot: trigger a save, then copy the RDB out
+docker compose exec sso-manager redis-cli BGSAVE
+docker compose cp sso-manager:/data/dump.rdb sso-redis-$(date +%F).rdb
+
+# Secrets — copy the config dir (holds LDAP_ADMIN_PASS, JWT secret, etc.)
+cp -a ./config config-backup-$(date +%F) && chmod 700 config-backup-$(date +%F)
+```
+Store the backup **off the host** — it contains secrets and the whole user
+directory.
+
+**Restore — full (disaster recovery)**
+
+The SSO image uses a static `slapd.conf` (slapd starts with `-f`, not `-F`
+cn=config), so LDAP restore uses `slapadd -f /etc/openldap/slapd.conf`:
+
+```bash
+# 1. Secrets
+cp -a config-backup-<date> ./config && chmod 700 ./config
+./setup.sh                       # fresh empty volumes (or: docker compose up -d)
+docker compose stop sso-manager
+
+# 2. LDAP — wipe the mdb files, then load the LDIF into the stopped directory
+docker compose run --rm --no-deps --entrypoint sh sso-manager -c \
+  'rm -f /var/lib/ldap/* && slapadd -f /etc/openldap/slapd.conf -l /dev/stdin' \
+  < ldap-backup-<date>.ldif
+docker compose start sso-manager
+
+# 3. Redis — see the AOF note below
+docker compose stop sso-manager
+docker compose run --rm --no-deps --entrypoint sh sso-manager -c \
+  'rm -f /data/appendonly.aof /data/appendonly.aof.*'   # REQUIRED — see note
+docker compose cp sso-redis-<date>.rdb sso-manager:/data/dump.rdb
+docker compose start sso-manager
+```
+
+**Restore — Redis only** = step 3 above. **Restore — LDAP only** = step 2 above.
+
+> **AOF vs RDB (important):** with `--appendonly yes`, Redis loads
+> `appendonly.aof` on startup and **ignores** `dump.rdb` if the AOF exists. To
+> restore from an RDB snapshot you **must delete the AOF first** (step 3 does
+> this); Redis then loads the RDB and writes a fresh AOF. Verify after restoring:
+> `docker compose exec sso-manager redis-cli DBSIZE` and
+> `docker compose exec sso-manager ldapsearch -x -b "dc=yourdomain,dc=com"`.
+
+**Upgrades**
+
+```bash
+./setup.sh          # backs up, then rebuilds — volumes keep LDAP + Redis state
+# (standalone) docker compose pull && docker compose up -d
+```
+LDAP data and Redis state survive the rebuild because they live on named
+volumes, not in the image. Verify health (`docker compose ps`, log in, check an
+OAuth client). Note: re-running bootstrap resets the bootstrap-admin and
+service-account passwords to the values in `./config/sso-secrets.js`; non-theta
+OAuth clients live in SSO Redis and are preserved by the volume.
+
+> **Note — the bundled slapd is built from source.** The all-in-one image
+> compiles OpenLDAP from a pinned upstream commit to get the `nestgroup`
+> overlay (nested groups; see `docs/directory.md`), because no 2.6.x release
+> ships it. One consequence: master uses **LMDB 1.0.0**, whose on-disk format is
+> mutually unreadable with the 0.9.x in OpenLDAP 2.6.x
+> (`MDB_INVALID: File is not an LMDB file`). Moving a directory between a 2.6.x
+> image and this one is a `slapcat` → `slapadd` reload, not a restart — the same
+> shape as "Restore — LDAP only" above. Verify after a rebuild:
+> `docker compose logs sso-manager | grep nestgroup` should report the overlay
+> as available.
+
+---
+
+## Method 2: Bare metal (Debian/Ubuntu)
+
+`install.sh` is an idempotent installer: it installs Node.js 22.x and Redis,
+force-syncs the repo to `/opt/theta42/sso-manager`, and symlinks the systemd
+config from the repo. Re-run it to update — it prints the version you're
+updating from and to (or "Already up to date" if there's nothing new).
+
+On the **first run only** it also installs and configures OpenLDAP (modules +
+overlays + custom schema + directory tree + required groups — see
+`ops/ldap-setup.sh`) and seeds `/etc/sso-manager/secrets.js` with a generated
+LDAP admin password and JWT secret (SMTP is left as a placeholder). Once that
+file exists it's never touched again, and LDAP is never re-bootstrapped —
+edit the file and restart the service to change anything.
+
+### Prerequisites
+
+- Debian 11+ / Ubuntu 20.04+
+- Root (`sudo`)
+- Internet access
+
+### Install
+
+```bash
+wget -O - https://raw.githubusercontent.com/theta42/sso-manager-node/master/install.sh | sudo bash
+```
+
+or, if you already have the repo checked out:
+
+```bash
+sudo ./install.sh
+```
+
+| Env var | Description |
+|---------|-------------|
+| `LDAP_BASE_DN` | Base DN (default `dc=example,dc=com`) — first run only |
+| `LDAP_ADMIN_PASS` | LDAP admin password (default auto-generated) — first run only |
+| `JWT_SECRET` | JWT secret (default auto-generated) — first run only |
+| `ORG_NAME` | Org name (default `SSO Manager`) — first run only |
+| `PORT` | HTTP port (default `3001`) — first run only |
+| `SKIP_LDAP` | `true` to skip OpenLDAP bootstrap entirely (point at an existing server yourself) |
+| `REPO_URL`, `REPO_DIR`, `BRANCH`, `SECRETS_FILE` | Override the defaults |
+
+### Post-install
+
+```bash
+sudo systemctl status sso-manager
+journalctl -fu sso-manager
+curl http://localhost:3001/health    # -> {"status":"ok"}
+```
+
+### What `install.sh` does
+
+1. Installs Node.js 22.x (NodeSource) and Redis.
+2. Clones/updates the repo at `/opt/theta42/sso-manager`.
+3. **First run only:** installs OpenLDAP (`slapd`) with `pw-sha2`, `ppolicy`,
+   `memberof`, `refint` modules + overlays; the custom `theta42Person` schema
+   (`dateOfBirth`); indexes; `ou=people`/`ou=groups`/`ou=policies`; a default
+   `pwdPolicy`; and the SSO groups — then seeds `/etc/sso-manager/secrets.js`.
+4. Symlinks `ops/systemd/sso-manager.service` into `/etc/systemd/system` and
+   runs `npm ci --omit=dev`.
+5. Enables and (re)starts the service.
+
+> For an existing LDAP server, run with `SKIP_LDAP=true` and write
+> `/etc/sso-manager/secrets.js` yourself (see `secrets.js.example`) before
+> starting the service. To (re)configure overlays on an already-installed
+> slapd, use `ops/ldap-setup.sh` directly (idempotent, auto-detects the user
+> database).
+
+---
+
+## LDAP requirements (for any external LDAP server)
+
+The app needs these on the LDAP server:
+
+- **Modules:** `pw-sha2` (the app stores user passwords as `{SSHA512}`), `ppolicy`,
+  `memberof`, `refint`.
+- **Custom schema:** the `theta42Person` auxiliary objectClass with `dateOfBirth`
+  (OID `1.3.6.1.4.1.99999.x`) — see `ops/ldap-setup.sh` for the LDIF.
+- **Directory tree:** `ou=people`, `ou=groups`, `ou=policies` under the base DN, a
+  default `pwdPolicy` at `cn=ppolicy,ou=policies,<base>`.
+- **Required groups:** `app_sso_admin` (full admin), `app_sso_invite` (invitation
+  management), `app_sso_oauth_admin` (OAuth client management),
+  `app_sso_service_account` (not a permission — marks a `posixAccount` as a
+  non-person service account; see docs/ldap.md).
+
+`ops/ldap-setup.sh -p <admin-password>` configures all of the above idempotently
+against a running slapd (auto-detects the database holding your base DN, and
+verifies `pwdAccountLockedTime` is live — the attribute the app's
+active/inactive toggle depends on).
+
+---
+
+## Migrating an existing instance to the generic defaults
+
+The committed `nodejs/conf/base.js` now ships **generic** defaults
+(`dc=example,dc=com`, `localhost`, `SSO Manager`). Previously it carried
+Theta42-specific values (LDAP bind DN/bases, SMTP host/user/sender, OAuth issuer).
+If you run an existing instance off this repo:
+
+- Move those per-deployment, non-secret values (bind DN, user/group bases, SMTP
+  host/user/sender, OAuth issuer, org name) from `base.js` into your gitignored
+  `conf/secrets.js`, **or** set them as `app_*` env vars. Secret values (LDAP bind
+  password, SMTP password, JWT secret) already belong in `secrets.js`.
+- After the change, verify the merged config: `node -e "console.log(require('@simpleworkjs/conf'))"` from the `nodejs/` directory.
+
+---
+
+## Troubleshooting
+
+### `503 OpenLDAP ppolicy overlay is not configured`
+The ppolicy overlay isn't attached to the database holding your users, so the
+active/inactive toggle can't set `pwdAccountLockedTime`. Run:
+```bash
+sudo ./ops/ldap-setup.sh -p 'admin-password' -b dc=yourdomain,dc=com
+```
+
+### App starts but LDAP operations 401 / "Invalid Credentials"
+Check the merged LDAP config the app actually sees:
+```bash
+cd nodejs && node -e "console.log(require('@simpleworkjs/conf').ldap)"
+```
+Confirm `url`/`bindDN`/`bindPassword`/`userBase` match your directory. Remember
+`app_*` env vars override `secrets.js` which overrides `base.js`.
+
+### `app_*` env vars seem to do nothing
+You're on `@simpleworkjs/conf` 1.0.0. Bump to 1.1.0+:
+```bash
+cd nodejs && npm install @simpleworkjs/conf@^1.1.0
+```
+
+### LDAP connection refused
+```bash
+docker compose exec sso-manager sh -c 'ldapsearch -x -H ldap://localhost:389 -b "" -s base'
+systemctl status slapd   # bare metal
+netstat -tlnp | grep 389
+```
+
+---
+
+## Security notes
+
+1. **Never commit `secrets.js`** — it's in `.gitignore`.
+2. **Use LDAPS / StartTLS** for any LDAP connection that crosses the network. The
+   bundled slapd listens on `ldaps:///` (636, TLS) and `ldap:///` (389, plain +
+   StartTLS); port 389 is not mapped to the host by default so LAN clients can't
+   bind in cleartext. Direct-LDAP consumers (Linux hosts, LDAP-native apps,
+   `theta42/proxy`) should use `ldaps://…:636` or StartTLS.
+3. **Persist `JWT_SECRET`** — if the Docker image auto-generates one and you don't
+   set `JWT_SECRET`, issued tokens invalidate on container recreation.
+4. **Don't expose the UI's HTTP port to the internet** — terminate TLS at a front
+   proxy and keep `3001` on the Docker network / localhost only.
+5. **Don't port-forward LDAPS (636) to the internet either.** It's mapped to the
+   host by default for LAN/VPN clients that bind LDAP directly (other hosts
+   running `ldap-client`, apps with their own LDAP auth settings) — not for
+   exposure through your router/firewall. LDAP simple-bind is a brute-force
+   target with no rate limiting in front of it the way the HTTP login endpoints
+   have. If a remote host needs to bind LDAP, put it behind a VPN (Tailscale,
+   WireGuard, …) instead of forwarding 636 publicly.
+6. The all-in-one image runs slapd as the `ldap` user but the app process as root
+   (matches the bare-metal systemd unit). Harden the app to a non-root user for
+   production if needed.

Dockerfile.openldap

@@ -184,6 +184,11 @@ COPY README.md /README.md
 COPY CHANGELOG.md /CHANGELOG.md
 COPY API.md /API.md
 COPY directory_spec.md /directory_spec.md
+# The docs/*.md tree (plus the images the docs link) is read at runtime too, so
+# the whole docs/ dir must land at /docs. Without this every in-app /docs/<slug>
+# page other than the root-level README/CHANGELOG/API/directory_spec 500s on the
+# fs.readFileSync in routes/docs.js (files missing from the image).
+COPY docs /docs
 
 # Baked commit hash from the gitinfo stage (see build_info.js).
 COPY --from=gitinfo /commit.txt ./.build_commit

docker-entrypoint.sh

@@ -355,7 +355,11 @@ EOF
     # Required SSO groups. The app gates admin/invite/oauth-admin on these;
     # app_sso_service_account is a marker (not a permission gate) for
     # non-person accounts -- see the Users page.
-    for group in app_super_admin app_sso_admin app_sso_invite app_sso_oauth_admin app_sso_service_account; do
+    #
+    # god_admin is the global super group (docs/GROUPS.md §2), the top of the
+    # group-inheritance lattice. It is seeded here so it exists from first boot;
+    # the theta-suite bootstrap puts the first admin person into it.
+    for group in god_admin app_sso_admin app_sso_invite app_sso_oauth_admin app_sso_service_account; do
         ldapadd -x -D "$LDAP_BIND_DN" -w "$LDAP_ADMIN_PASS" -H ldap://localhost:389 << EOF || true
 dn: cn=${group},ou=groups,${LDAP_BASE_DN}
 objectClass: groupOfNames
@@ -366,11 +370,11 @@ member: ${LDAP_BIND_DN}
 EOF
     done
 
-    # Nest app_super_admin into the SSO admin groups, so cross-app super admins
-    # hold those rights by membership rather than by a special case in app code.
-    # This is what makes the privilege visible to every consumer -- SSSD, sudo,
-    # anything binding LDAP directly -- instead of only to callers that happen
-    # to route through utils/permission.js.
+    # Nest god_admin into the SSO admin groups, so god admins hold those rights
+    # by membership rather than by a special case in app code. This is what makes
+    # the privilege visible to every consumer -- SSSD, sudo, anything binding
+    # LDAP directly -- instead of only to callers that happen to route through
+    # utils/permission.js.
     #
     # app_sso_service_account is deliberately excluded: it is a marker for
     # non-person accounts, not a permission, and nesting admins into it would
@@ -381,10 +385,10 @@ EOF
 dn: cn=${group},ou=groups,${LDAP_BASE_DN}
 changetype: modify
 add: member
-member: cn=app_super_admin,ou=groups,${LDAP_BASE_DN}
+member: cn=god_admin,ou=groups,${LDAP_BASE_DN}
 EOF
         done
-        info "Nested app_super_admin into the SSO admin groups"
+        info "Nested god_admin into the SSO admin groups"
     fi
 
     info "LDAP directory initialized"

docs/_config.yml

@@ -0,0 +1,55 @@
+title: SSO Manager
+description: A self-hosted OpenID Connect provider with a bundled OpenLDAP directory and a web management UI, for home labs and small businesses that want their own identity provider.
+url: "https://theta42.github.io"
+baseurl: "/sso-manager-node"
+logo: /assets/img/theta42.svg
+lang: en_US
+
+plugins:
+  - jekyll-seo-tag
+  - jekyll-sitemap
+
+github:
+  repository_url: https://github.com/theta42/sso-manager-node
+  zip_url: https://github.com/theta42/sso-manager-node/archive/refs/heads/master.zip
+  tar_url: https://github.com/theta42/sso-manager-node/archive/refs/heads/master.tar.gz
+  repository_name: theta42/sso-manager-node
+
+nav:
+  - title: Home
+    page: /
+    icon: fa-house
+  - title: Deployment
+    page: /deployment.html
+    icon: fa-server
+  - title: Configuration
+    page: /configuration.html
+    icon: fa-gears
+  - title: OAuth
+    page: /oauth.html
+    icon: fa-key
+  - title: LDAP
+    page: /ldap.html
+    icon: fa-address-book
+  - title: Directory
+    page: /directory.html
+    icon: fa-server
+  - title: Plugins
+    page: /plugins.html
+    icon: fa-plug
+  # API.md lives at the repo root, not under docs/, so Jekyll never renders an
+  # api.html for it — link the source directly, same as the Changelog.
+  - title: API
+    url: https://github.com/theta42/sso-manager-node/blob/master/API.md
+    icon: fa-code
+  - title: Changelog
+    url: https://github.com/theta42/sso-manager-node/blob/master/CHANGELOG.md
+    icon: fa-list
+
+defaults:
+  - scope:
+      path: ""
+      type: "pages"
+    values:
+      layout: default
+      image: /assets/img/theta42.svg

docs/_layouts/default.html

@@ -0,0 +1,82 @@
+<!doctype html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+	<link rel="icon" type="image/svg+xml" href="{{ '/assets/img/theta42.svg' | relative_url }}">
+
+	{% seo title=false %}
+	<title>{% if page.title %}{{ page.title }} &middot; {% endif %}{{ site.title }}</title>
+
+	<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css">
+	<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css">
+	<link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
+</head>
+<body class="d-flex flex-column min-vh-100">
+
+	<nav class="navbar navbar-expand-md navbar-dark bg-dark fixed-top">
+		<div class="container-fluid px-3">
+			<a class="navbar-brand d-flex align-items-center" href="{{ '/' | relative_url }}">
+				<img src="{{ '/assets/img/theta42.svg' | relative_url }}" height="28" class="me-2" alt="">
+				{{ site.title }}
+			</a>
+			<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navMain" aria-controls="navMain" aria-expanded="false" aria-label="Toggle navigation">
+				<span class="navbar-toggler-icon"></span>
+			</button>
+			<div class="collapse navbar-collapse justify-content-end" id="navMain">
+				<ul class="navbar-nav">
+					{% for item in site.nav %}
+					<li class="nav-item">
+						{% if item.page %}
+						<a class="nav-link{% if page.url == item.page %} active{% endif %}" href="{{ item.page | relative_url }}">
+							{% if item.icon %}<i class="fa-solid {{ item.icon }}"></i>{% endif %} {{ item.title }}
+						</a>
+						{% else %}
+						<a class="nav-link" href="{{ item.url }}" target="_blank" rel="noopener">
+							{% if item.icon %}<i class="fa-solid {{ item.icon }}"></i>{% endif %} {{ item.title }}
+						</a>
+						{% endif %}
+					</li>
+					{% endfor %}
+				</ul>
+			</div>
+		</div>
+	</nav>
+
+	<main class="flex-grow-1" style="margin-top: 4.5rem;">
+		<div class="container-fluid py-4 py-md-5">
+			<div class="row justify-content-center">
+				<div class="col-12 col-lg-10 col-xl-8">
+					<div class="card shadow-lg">
+						<div class="card-body p-4 p-md-5 site-content">
+							{{ content }}
+						</div>
+					</div>
+				</div>
+			</div>
+		</div>
+	</main>
+
+	<footer class="py-3 bg-dark text-light mt-auto">
+		<div class="container-fluid d-flex flex-wrap justify-content-between align-items-center small gap-2 px-3">
+			<span class="d-flex align-items-center gap-2">
+				<a href="https://theta42.com" target="_blank" rel="noopener">
+					<img width="40" src="{{ '/assets/img/theta42.svg' | relative_url }}" alt="theta42">
+				</a>
+				&copy; {{ 'now' | date: '%Y' }} theta42 &middot;
+				<a href="{{ site.github.repository_url }}/blob/master/LICENSE" target="_blank" rel="noopener" class="text-light">MIT License</a>
+			</span>
+			<span class="d-flex align-items-center gap-3">
+				<a href="{{ site.github.repository_url }}" target="_blank" rel="noopener" class="text-light text-decoration-none">
+					<i class="fa-brands fa-github"></i> GitHub
+				</a>
+				<a href="{{ site.github.repository_url }}/blob/master/CHANGELOG.md" target="_blank" rel="noopener" class="text-light text-decoration-none">
+					<i class="fa-solid fa-list"></i> Changelog
+				</a>
+			</span>
+		</div>
+	</footer>
+
+	<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
+</body>
+</html>

docs/agents.md

@@ -0,0 +1,136 @@
+---
+layout: default
+title: Theta Agent & Endpoint Management
+nav_order: 5
+---
+
+# Theta Agent & Endpoint Management
+
+The **Theta Agent** (`theta-agent`) is a unified, 2-way Command & Control (C2) endpoint management daemon written in Go for Linux hosts across your home lab, infrastructure, or data center. It connects outbound via a long-lived WebSocket connection to the central **SSO Manager** (`wss://<sso-host>/api/agent/ws`), enabling real-time host telemetry, automated host discovery, and local-first administrative management.
+
+---
+
+## Core Functionality
+
+### 1. Host Discovery & Inventory
+Upon establishing a WebSocket connection, the agent immediately pushes a comprehensive discovery payload:
+- **Hostname & Network Interfaces**: Hostname and all non-loopback IPv4 addresses and MACs.
+- **Operating System & Kernel**: Linux distribution, platform, and kernel version.
+- **Hardware Specs**: CPU model, total RAM (GB), and total root disk capacity (GB).
+- **Physical Location**: Location identifier string (e.g. `dc-01-rack-12`) configured in `agent.yml`.
+
+If the agent detects a network IP change, it automatically re-pushes an updated discovery payload to the SSO Manager.
+
+### 2. Real-Time Telemetry Streaming
+Every 30 seconds, the agent streams real-time performance metrics:
+- **CPU Load**: System-wide CPU utilization percentage.
+- **Memory Utilization**: RAM usage percentage and available memory.
+- **Disk Utilization**: Root filesystem usage percentage.
+- **ZFS Storage Health**: Health status of ZFS pools (e.g., `ONLINE`).
+- **NVIDIA GPU Load**: GPU compute utilization percentage (via `nvidia-smi`).
+
+---
+
+## Viewing in the SSO Manager
+
+Agent status and telemetry live on the **Directory** page — there is no separate
+Agents page. For each **host** resource that has a connected theta-agent, the
+Directory shows a status dot in the row:
+
+| Color | Meaning |
+| :--- | :--- |
+| **Green** | Connected, healthy (CPU/RAM/disk within limits). |
+| **Yellow** | Connected but under high load (CPU > 80% or RAM > 80% or disk > 90%). |
+| **Red** | Not connected (no agent, or the agent is offline). |
+
+Opening a host's resource modal reveals a **Metrics** tab with the agent's live
+telemetry (CPU/RAM/disk/ZFS/GPU) and discovery info (OS, kernel, IPs, location).
+The agent is joined to its host by hostname (`agent.discovery.hostname` ↔ the
+resource name), so name the Directory host the same as the machine's hostname.
+
+---
+
+## Local-First Security & Capability Matrix
+
+To protect hosts against unauthorized control, `theta-agent` enforces a **strict, local-first capability matrix** defined in `/etc/theta42/agent.yml`. Central SSO Manager requests are checked against local configuration before execution; permissions cannot be overridden remotely.
+
+| Capability | Config Key | Risk Level | Description & Impact |
+| :--- | :--- | :--- | :--- |
+| **Telemetry** | `telemetry` | Safe | Streams read-only system metrics (CPU, RAM, Disk, ZFS, GPU). |
+| **Configure LDAP** | `configure_ldap` | Moderate | Writes updated SSSD configuration to `/etc/sssd/sssd.conf` & restarts `sssd`. |
+| **Service Control** | `service_control` | High | Restarts systemd services listed in an explicit allowlist (e.g., `["nginx", "docker", "sssd"]`). |
+| **Reboot** | `reboot` | High | Triggers an immediate system reboot (`systemctl reboot`). |
+| **Arbitrary Bash** | `arbitrary_bash` | Critical | Executes raw bash scripts sent from the SSO Manager as `root` (used for automated GitOps). |
+
+---
+
+## High-Risk Command Verification (Protocol v1.1.0)
+
+High-risk management commands (`reboot`, `service_restart`, `configure_ldap`, `arbitrary_bash`, `update_binary`) are cryptographically verified using **Ed25519 signatures**:
+1. The SSO Manager canonicalizes the command payload (sorted keys, no whitespace).
+2. The payload is signed with the SSO Manager's Ed25519 private key.
+3. The Base64 signature is appended to the message payload.
+4. The agent verifies the signature against the configured `public_key` in `/etc/theta42/agent.yml` before executing the action.
+
+---
+
+## Installation & Deployment
+
+### Quick One-Liner Install
+Run the following command as `root` on the target Linux host:
+
+```bash
+curl -fsSL https://<SSO_HOST>/resources/theta-agent/install.sh | sh -s -- --url "https://<SSO_HOST>" --token "<HOST_TOKEN>"
+```
+
+### Custom Config Wizard
+You can generate a Base64-encoded custom configuration using the **Install Agent** button on the **Directory Management** page in the SSO Manager UI:
+
+```bash
+curl -fsSL https://<SSO_HOST>/resources/theta-agent/install.sh | sh -s -- "<BASE64_ENCODED_CONFIG>"
+```
+
+---
+
+## Configuration File Example (`/etc/theta42/agent.yml`)
+
+```yaml
+# /etc/theta42/agent.yml
+server_url: "wss://sso.example.com"
+auth_token: "your-unique-host-token"
+location: "dc-01-rack-12"
+public_key: "MCowBQYDK2VwAyEA..."
+
+capabilities:
+  telemetry: true
+  configure_ldap: true
+  reboot: false
+  service_control: ["nginx", "docker", "sssd"]
+  arbitrary_bash: false
+```
+
+---
+
+## Troubleshooting: agent can't connect (`dial tcp ... i/o timeout`)
+
+If the agent host logs `Dial error: dial tcp <ip>:443: i/o timeout` while
+connecting to `wss://<sso-host>/api/agent/ws`, the WebSocket path is usually
+fine — this is a **network/NAT** problem, not an agent or SSO bug. A host behind
+the same NAT that owns the SSO often cannot reach its own **public IP** (no
+hairpin/loopback NAT on many home routers), so the TCP dial times out even
+though the same address works from outside.
+
+Fix options:
+1. Point `agent.yml` `server_url` at an address the host can reach directly —
+   e.g. the SSO host's LAN IP (`http://<lan-ip>` or `http://<lan-ip>:3001` for a
+   no-TLS direct path).
+2. Enable **NAT reflection / hairpin NAT** on the router so LAN hosts can reach
+   their own public IP:443.
+3. Add a local route/firewall rule on the agent host for its public IP.
+
+> Note: on a deployment where the theta42 proxy fronts `sso.suite.example`, make
+> sure the proxy has a **persistent Host record** for the real SSO domain — not
+> just the `localtest.me` placeholder — so routing survives a proxy restart
+> (an in-memory lookup cache can mask a missing Redis record for up to ~1h).
+
+

docs/assets/css/style.css

@@ -0,0 +1,116 @@
+/* theta42 docs site — shares the in-app dark navbar/footer + card look
+   (Bootstrap 5 + Font Awesome, same as the running apps) rather than a
+   generic Jekyll theme. */
+
+body {
+	background-color: #f4f5f6;
+}
+
+.navbar-brand img {
+	filter: drop-shadow(0 0 2px rgba(0, 0, 0, .4));
+}
+
+.navbar-nav .nav-link.active {
+	color: #fff;
+	font-weight: 600;
+}
+
+/* Markdown content typography, scoped to the card body so it doesn't leak
+   into the nav/footer. */
+.site-content h1:first-child {
+	margin-top: 0;
+}
+
+.site-content h1,
+.site-content h2,
+.site-content h3 {
+	font-weight: 700;
+}
+
+.site-content h2 {
+	margin-top: 2.5rem;
+	padding-bottom: .4rem;
+	border-bottom: 1px solid #e9ecef;
+}
+
+.site-content h3 {
+	margin-top: 1.75rem;
+}
+
+.site-content a {
+	color: #a3671f;
+	text-decoration-color: rgba(163, 103, 31, .35);
+}
+
+.site-content a:hover {
+	color: #8a5a16;
+}
+
+.site-content pre {
+	background-color: #212529;
+	color: #f8f9fa;
+	padding: 1rem 1.25rem;
+	border-radius: .375rem;
+	overflow-x: auto;
+}
+
+.site-content code {
+	color: #a3671f;
+	background-color: #f4f0e8;
+	padding: .15em .4em;
+	border-radius: .25rem;
+	font-size: .875em;
+}
+
+.site-content pre code {
+	color: inherit;
+	background: none;
+	padding: 0;
+}
+
+.site-content table {
+	display: block;
+	overflow-x: auto;
+	width: 100%;
+	border-collapse: collapse;
+	margin: 1.25rem 0;
+}
+
+.site-content table th,
+.site-content table td {
+	border: 1px solid #dee2e6;
+	padding: .5rem .75rem;
+	text-align: left;
+}
+
+.site-content table th {
+	background-color: #f8f9fa;
+}
+
+.site-content blockquote {
+	border-left: 4px solid #C59341;
+	padding: .5rem 1rem;
+	margin: 1.25rem 0;
+	background-color: #f8f6f1;
+	color: #495057;
+}
+
+.site-content img {
+	max-width: 100%;
+	height: auto;
+}
+
+/* Screenshot grids in the markdown use width="49%" inline attrs for a
+   two-up desktop layout -- stack them on narrow screens instead of
+   squeezing to illegibility. */
+@media (max-width: 576px) {
+	.site-content img[width] {
+		width: 100% !important;
+		margin-bottom: .75rem;
+	}
+}
+
+.site-content hr {
+	margin: 2rem 0;
+	border-top: 1px solid #e9ecef;
+}

docs/assets/img/theta42.svg

@@ -0,0 +1,51 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400" width="100%" height="100%">
+  <defs>
+    <linearGradient id="gold-grad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#C59341" />
+      <stop offset="20%" stop-color="#E4B869" />
+      <stop offset="40%" stop-color="#FBF0B9" />
+      <stop offset="60%" stop-color="#DFB260" />
+      <stop offset="80%" stop-color="#BC8837" />
+      <stop offset="100%" stop-color="#A36F28" />
+    </linearGradient>
+
+    <linearGradient id="text-grad" x1="0%" y1="100%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#FFFFFF" />
+      <stop offset="40%" stop-color="#F5E3B5" />
+      <stop offset="70%" stop-color="#D4A343" />
+      <stop offset="100%" stop-color="#8A5A16" />
+    </linearGradient>
+
+    <filter id="drop-shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="8" stdDeviation="6" flood-color="#000000" flood-opacity="0.4"/>
+    </filter>
+  </defs>
+
+  <g filter="url(#drop-shadow)">
+    <g fill="url(#gold-grad)">
+      <path d="M 200,40 
+               C 290,40 350,110 350,200 
+               C 350,290 290,360 200,360 
+               C 110,360 50,290 50,200 
+               C 50,110 110,40 200,40 Z 
+               M 200,75 
+               C 130,75 88,130 88,200 
+               C 88,270 130,325 200,325 
+               C 270,325 312,270 312,200 
+               C 312,130 270,75 200,75 Z" 
+            fill-rule="evenodd" />
+      
+      <path d="M 88,190 L 140,190 C 140,190 142,210 140,210 L 88,210 Z" />
+      
+      <path d="M 260,190 L 312,190 C 312,190 310,210 260,210 Z" />
+    </g>
+
+    <text x="200" y="222" 
+          font-family="system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" 
+          font-size="78" 
+          font-weight="900" 
+          fill="url(#text-grad)" 
+          text-anchor="middle"
+          letter-spacing="-2">42</text>
+  </g>
+</svg>

docs/concepts-accounts.md

@@ -0,0 +1,125 @@
+---
+layout: default
+title: Accounts, Groups & Managers
+description: A plain-language guide to users, service accounts, personal groups, and managers in SSO Manager.
+---
+
+# Accounts, Groups & Managers
+
+This page explains the concepts behind the Users and Groups pages in plain
+language. If you want the technical schema/attribute-level detail instead,
+see the [LDAP reference](ldap.html).
+
+## What's an account?
+
+Every person (or app) that can sign in through this SSO Manager has an
+**account** — a username, a display name, maybe an email address, and a
+password (or, for service accounts, no password at all — see below).
+Accounts live in the directory this app manages, and any other app you've
+connected (Gitea, Home Assistant, your Wi-Fi, whatever) checks against these
+same accounts instead of keeping its own separate list of users and
+passwords.
+
+## Two kinds of account: people and service accounts
+
+Most accounts belong to an actual person — check **Users → People** to see
+them. But sometimes you need an account for something that *isn't* a
+person: a media server, a backup script, a bind account another app uses to
+look people up. These are **service accounts**, listed separately under
+**Users → Service Accounts**, and they're different from a person's account
+in two ways that matter:
+
+- **No email required.** A service account doesn't need a mailbox, so the
+  form doesn't ask for one.
+- **A password is optional.** If you leave it blank, nobody can log in as
+  that account — which is exactly what you want for something that only
+  ever gets used programmatically (a script authenticating with an API
+  token, or another app binding with a fixed, separately-configured
+  password you set yourself). Only give it a password if the account
+  genuinely needs to log in or bind somewhere as itself.
+
+Aside from those two differences, a service account is a completely normal
+account under the hood — it can belong to groups, have a manager, and so
+on, just like anyone else's.
+
+## Groups: who can do what
+
+A **group** is just a named list of accounts, used to control access. This
+app has a handful of built-in groups that grant admin powers (e.g. only
+people in the `app_sso_admin` group can see the Users/Groups/Directory/Overview
+pages at all), but you can also make your own groups for any app you
+connect — say, a group listing everyone who should be allowed into your
+photo server. Once a group exists, add or remove members from the
+**Groups** page, and point the other app's "who's allowed in" setting at
+that group's name.
+
+### Groups inside groups
+
+A group can contain another group, not just people — the *Nested* tab on any
+group card. Everyone in the inner group counts as a member of the outer one,
+however many levels deep it goes.
+
+This is mostly a way to stop repeating yourself. Make one `developers` group,
+nest it into the handful of things developers should reach, and adding a new
+developer to that one group grants all of them at once — instead of adding them
+to each individually and slowly drifting out of sync. The app already does this
+for itself: super admins are nested into every resource's admin group, and each
+admin group into its access group, so "can administer it" always implies "can
+use it".
+
+Two things it won't let you do: put a group inside itself (directly or round a
+longer loop), and empty a group completely — every group must keep at least one
+member.
+
+A note if you also manage the directory by hand: a group's member list shows
+what is *directly* listed on it. Someone who gets in through a nested group is
+a real member but won't appear there — the **Nested** tab shows what is nested,
+and the API's `effective` view lists everyone who actually gets in.
+
+## Every account's personal group
+
+Separately from the groups above, every single account — person or
+service account — automatically gets its own small, personal group when
+it's created, named after the account itself. Most of the time you'll
+never think about this; it exists so that, on a Linux system connected to
+this directory, each account "owns" its own files by default the same way
+a normal Unix user account would.
+
+Occasionally you'll want to share that ownership with someone else — for
+example, letting a second account also have write access to files a
+service account owns. That's what the **"Members of `<uid>`'s group"**
+section on a profile page is for: add another account there, and the
+underlying Linux permissions treat them as if they belong to that same
+personal group too.
+
+## What's a "manager"?
+
+Every account has one or more **managers** — the people allowed to edit
+that account's profile (phone number, SSH key, home directory, and so on)
+without needing full admin rights. By default, whoever created an account
+(the admin who added it, or whoever sent the invite) becomes its first
+manager, but you can add or remove managers later from the account's Edit
+form.
+
+This is useful for service accounts especially: if a service account
+belongs to a particular project or person, make them its manager so they
+can maintain it — rotate its SSH key, adjust its description — without
+needing to be a full SSO administrator.
+
+## Inviting someone vs. adding them yourself
+
+From the Users page you can either fill in someone's details yourself
+("Add new user"), or send them an **invite** — an email (or a link you copy
+and send however you like) that lets them pick their own username and
+password. Either way, the resulting account is identical; invites are just
+a convenience so you don't have to know someone's preferred username or
+handle their password directly.
+
+## Want more detail?
+
+This page deliberately leaves out LDAP schema names, attribute types, and
+protocol-level detail. If you're connecting a third-party app directly to
+the LDAP directory, or you just want to know exactly what's stored where,
+see the [LDAP reference](ldap.html).
+
+[← Back to Home](index.html)

docs/concepts-api-tokens.md

@@ -0,0 +1,59 @@
+---
+layout: default
+title: API Tokens
+description: A plain-language guide to personal access tokens in SSO Manager.
+---
+
+# API Tokens
+
+This page explains what an API token is and when you'd want one. For the
+full list of API endpoints a token can call, see the
+[API reference](https://github.com/theta42/sso-manager-node/blob/master/API.md).
+
+## What's an API token, in plain terms?
+
+Normally, you interact with this app by logging in through a web browser.
+An **API token** (also called a personal access token, or PAT) is an
+alternative way in — a long, random string that a script, a scheduled job,
+or another program can use instead of a username and password, to act on
+your behalf without a human typing a login in each time.
+
+If you've ever set up a script to talk to GitHub, GitLab, or a similar
+service using a "token" instead of your real password, this is the same
+idea.
+
+## When would you actually need one?
+
+Most people never need to create one of these — you'll only want a token
+if you're automating something, for example:
+
+- A script that syncs users or groups from somewhere else into this SSO
+  Manager on a schedule.
+- A backup or monitoring job that checks this app's health via its API.
+- A CI/CD pipeline that needs to register or update an OAuth client
+  automatically.
+
+If you're not doing any of that, you don't need an API token — just log in
+normally through the web UI.
+
+## How it works
+
+Create a token from your Profile page, give it a name so you remember what
+it's for later, and optionally an expiry. You'll be shown the token's
+value **exactly once** — copy it somewhere safe immediately, because it
+can't be viewed again afterward (only revoked or rotated). Whatever script
+or tool you're using it with sends it along with each request, the same
+way a browser sends your login session.
+
+A token acts **as you**, with **your** permissions — if you're not an
+admin, a token you create can't do admin-only things either. If you ever
+suspect a token has leaked (ended up somewhere it shouldn't have, like a
+public script or log file), revoke it immediately from your Profile page;
+it stops working right away.
+
+## Want more detail?
+
+This page doesn't attempt to list every API endpoint or show request/
+response examples — for that, see the full [API reference](https://github.com/theta42/sso-manager-node/blob/master/API.md).
+
+[← Back to Home](index.html)

docs/concepts-oauth-apps.md

@@ -0,0 +1,79 @@
+---
+layout: default
+title: Connecting Apps (Single Sign-On)
+description: A plain-language guide to OAuth/OIDC clients and single sign-on in SSO Manager.
+---
+
+# Connecting Apps (Single Sign-On)
+
+This page explains, in plain language, what happens when you "connect" an
+app to your SSO Manager so people can log into it with their existing
+account. For the technical endpoint/token detail, see the
+[OAuth reference](oauth.html).
+
+## What does "single sign-on" actually mean?
+
+Instead of every app you run having its own separate list of usernames and
+passwords, they all check with this SSO Manager instead. You log in once,
+here, and any connected app trusts that login — no separate password to
+remember or manage for each one. If you ever need to lock someone out
+everywhere at once, you do it in one place (deactivate their account here)
+instead of hunting down every app individually.
+
+The technology behind this is called **OAuth 2.0** and **OpenID Connect
+(OIDC)** — you'll see both names used, often together, referring to the
+same thing. You don't need to understand the protocol to use this page;
+what matters practically is the handful of concepts below.
+
+## What's a "client"?
+
+Every app you connect is registered here as a **client** — a single entry
+in the Directory representing that one app. Registering a client
+gives you a **Client ID** and **Client Secret**: think of these like a
+username and password, but for the *app itself* rather than for a person.
+You paste them into the other app's own "Single Sign-On" or "OIDC" setup
+screen, along with the discovery URL shown at the top of this page, and
+that app is now able to ask this SSO Manager to authenticate people on its
+behalf.
+
+**Treat the Client Secret like a password** — anyone who has it can
+impersonate that app when talking to your SSO Manager. If you ever suspect
+it's leaked, rotate it from the client's card.
+
+## What are "scopes"?
+
+**Scopes** control what information a connected app is allowed to ask for
+about the person logging in — their username, email, group memberships,
+and so on. Most apps tell you exactly which scopes they need in their own
+setup instructions; when in doubt, the default set (`openid`, `profile`,
+`email`, `groups`) covers what nearly every app expects.
+
+## "Restrict to Groups"
+
+By default, *any* account with an SSO Manager login can sign into a
+connected app. If that's not what you want — say, a home automation
+dashboard that only certain family members should reach — set **Restrict
+to Groups** on that client to one of your [groups](concepts-accounts.html).
+Only members of that group will be allowed to log into that particular
+app; everyone else gets turned away at the login step, even though their
+SSO Manager account still works everywhere else.
+
+## Redirect URIs
+
+A **Redirect URI** is the exact web address the connected app wants people
+sent back to once they've logged in here — it's a security measure so an
+attacker can't trick the login flow into redirecting somewhere else. The
+app's own setup instructions will tell you this value; copy it in exactly
+as given. If the app is reachable via more than one hostname (for example,
+because it sits behind [theta42/proxy](https://theta42.github.io/proxy/)),
+this field supports wildcard patterns — see the inline help under the
+field itself for the exact syntax.
+
+## Want more detail?
+
+This page intentionally skips the protocol-level detail (exact endpoint
+URLs, token formats, claim names). If you're troubleshooting a connection
+or building something against the API directly, see the
+[OAuth reference](oauth.html).
+
+[← Back to Home](index.html)

docs/configuration.md

@@ -0,0 +1,104 @@
+---
+layout: default
+title: Configuration
+description: SSO Manager's config layers — conf/base.js defaults, secrets.js overrides, and app_* environment variables.
+---
+
+# Configuration
+
+[← Back to Home](index.html)
+
+The app loads configuration via
+[`@simpleworkjs/conf`](https://www.npmjs.com/package/@simpleworkjs/conf), which
+deep-merges, in order (later wins):
+
+1. `conf/base.js` — committed, generic defaults (`dc=example,dc=com`,
+   `localhost`, `SSO Manager`).
+2. `conf/<NODE_ENV>.js` — optional, environment-specific.
+3. `conf/secrets.js` — gitignored; secrets + per-deployment values.
+4. **`app_*` environment variables** — the highest-precedence layer.
+
+Any env var whose name starts with `app_` overrides the merged config. The rest
+of the name splits on **double-underscore** (`__`) into a nested path. Values are
+`JSON.parse`-coerced when possible (numbers, booleans, null, JSON) and kept as
+raw strings otherwise.
+
+## Examples
+
+| Env var | Sets | Type |
+|---------|------|------|
+| `app_ldap__url=ldap://host:389` | `conf.ldap.url` | string |
+| `app_ldap__bindPassword=secret` | `conf.ldap.bindPassword` | string |
+| `app_ldap__userBase=ou=people,dc=…` | `conf.ldap.userBase` | string |
+| `app_ldap__uidGidMin=1500` | `conf.ldap.uidGidMin` | number (new-user id floor) |
+| `app_ldap__uidGidReservedFloor=9000` | `conf.ldap.uidGidReservedFloor` | number (ids at/above this are ignored when allocating) |
+| `app_ldap__ldapsHost=ldap.internal.example.com` | `conf.ldap.ldapsHost` | string (hostname shown on `/integrations` for LDAPS binds; empty = derive from `oauth.issuer`) |
+| `app_ldap__ldapsPort=636` | `conf.ldap.ldapsPort` | number (port shown on `/integrations`) |
+| `app_oauth__jwtSecret=...` | `conf.oauth.jwtSecret` | string |
+| `app_oauth__issuer=https://sso.example.com` | `conf.oauth.issuer` | string |
+| `app_oauth__token_lifetime__access_token=3600` | `conf.oauth.token_lifetime.access_token` | number |
+| `app_smtp__secure=false` | `conf.smtp.secure` | boolean |
+| `app_smtp__host=smtp.example.com` | `conf.smtp.host` | string |
+| `app_name=My SSO` | `conf.name` | string |
+| `app_redis__host=redis.local` | `conf.redis.host` | string (external Redis) |
+
+## The `app_*` env layer requires conf >= 1.1.0
+
+The `app_*` environment-variable override layer was added in
+`@simpleworkjs/conf` **1.1.0**. On 1.0.0 the app ignores all `app_*` vars and only
+reads `base.js` / `<NODE_ENV>.js` / `secrets.js`. The Docker image will not honor
+`app_*` env on 1.0.0. Refresh the lock from the `nodejs/` directory:
+
+```bash
+cd nodejs && npm install @simpleworkjs/conf@^1.1.0
+```
+
+## Inspecting the merged config
+
+From the `nodejs/` directory:
+
+```bash
+node -e "console.log(require('@simpleworkjs/conf').ldap)"
+node -e "console.log(require('@simpleworkjs/conf').oauth)"
+node -e "console.log(require('@simpleworkjs/conf'))"   # everything
+```
+
+Or, inside the running container:
+
+```bash
+docker compose exec sso-manager node -e "console.log(require('@simpleworkjs/conf').ldap)"
+```
+
+`app_*` env vars override `secrets.js`, which overrides `base.js` — if a value
+isn't what you expect, check those layers in that order.
+
+## Migrating an existing instance to the generic defaults
+
+The committed `nodejs/conf/base.js` ships **generic** defaults
+(`dc=example,dc=com`, `localhost`, `SSO Manager`). Previously it carried
+Theta42-specific values (LDAP bind DN/bases, SMTP host/user/sender, OAuth
+issuer). If you run an existing instance off this repo:
+
+- Move per-deployment, non-secret values (bind DN, user/group bases, SMTP
+  host/user/sender, OAuth issuer, org name) from `base.js` into your gitignored
+  `conf/secrets.js`, **or** set them as `app_*` env vars.
+- Secret values (LDAP bind password, SMTP password, JWT secret) already belong
+  in `secrets.js`.
+
+## Troubleshooting `app_*` env vars
+
+### `app_*` vars seem to do nothing
+
+You're on `@simpleworkjs/conf` 1.0.0. Bump to 1.1.0+ (above).
+
+### LDAP operations 401 / "Invalid Credentials"
+
+Check the merged LDAP config the app actually sees:
+
+```bash
+cd nodejs && node -e "console.log(require('@simpleworkjs/conf').ldap)"
+```
+
+Confirm `url` / `bindDN` / `bindPassword` / `userBase` match your directory.
+
+[← Back to Home](index.html)

docs/deployment.md

@@ -0,0 +1,22 @@
+---
+layout: default
+title: Deployment
+description: Deploying SSO Manager — the all-in-one Docker image, bare-metal install, config layers, and backups.
+---
+
+# Deployment Guide
+
+[← Back to Home](index.html)
+
+The full deployment guide — Docker (all-in-one image), bare-metal install,
+the `app_*` env reference, backups, and the security notes (including why
+LDAPS shouldn't be port-forwarded to the internet) — lives in one place to
+avoid two copies drifting out of sync:
+
+**[DEPLOYMENT.md on GitHub](https://github.com/theta42/sso-manager-node/blob/master/DEPLOYMENT.md)**
+
+See also [Configuration](configuration.html) for the config layer merge
+order, and [LDAP](ldap.html) for the directory layout and connecting a
+3rd-party app.
+
+[← Back to Home](index.html)

docs/directory.md

@@ -0,0 +1,139 @@
+---
+layout: default
+title: Directory Management
+description: Managing your Home-Lab infrastructure, services, and LDAP access relationships via the SSO Directory API.
+---
+
+# Directory Management
+
+The SSO Manager ships with a built-in **Directory & Inventory Management** feature. Instead of just managing bare LDAP groups for your homelab, the Directory allows you to map out your infrastructure graph and assign rich metadata to your services.
+
+## Architecture
+
+The Directory models your homelab infrastructure using a parent-child graph (e.g. `Site -> Host -> Service`).
+
+There are three primary **Kinds** of resources you can define:
+- **Site**: A physical location, datacenter, or root node (e.g., `us-east`). Sites do not require parents.
+- **Host**: A physical machine, Proxmox node, virtual machine, or LXC container. A Host **must** have a parent Site or another Host.
+- **Service (App)**: An application, web service. A Service **must** have a parent Host or another Service.
+- **OAuth Integration**: An OAuth 2.0 / OpenID Connect client application. An OAuth integration **must** have a parent Service.
+
+By defining this hierarchy, the SSO Manager builds a queryable graph of your infrastructure.
+
+## Automatic LDAP Group Creation
+
+When you create a new **Host** or **Service** in the Directory via the web UI (or API), the SSO Manager will automatically provision two LDAP groups in your directory to govern access to that resource:
+
+1. `<slug>_access` (Member level access)
+2. `<slug>_admin` (Owner level access)
+
+For example, if you create a Service named "Emby" with the slug `app_emby`, the system will create the LDAP groups `app_emby_access` and `app_emby_admin`. You can then assign users to these groups, and they will immediately see the service populate on their "My Services" dashboard.
+
+## Resource Metadata
+
+Resources carry a flexible `metadata` JSON object that can store essential context for your applications. The UI natively supports the following metadata fields:
+
+### Common Metadata
+- **Sub Type**: Free-form text to categorize the resource (e.g., `proxmox_node`, `linux`, `lxc`, `web`).
+- **IP Address**: The internal IP address of the resource.
+- **MAC Address**: The hardware address of the primary interface.
+- **Host / URI Address**: The FQDN or URL of the resource (e.g., `https://emby.home.arpa`).
+- **Production Environment**: A boolean toggle indicating if the resource is in production.
+
+### Host Metadata
+- **VMID**: The hypervisor VM or Container ID (e.g. `101`).
+- **OS**: The operating system name (e.g. `Ubuntu 22.04.3 LTS`).
+- **Kernel**: The kernel version string (e.g. `5.15.0-100-generic`).
+
+### Service Metadata
+- **Internal Port**: The local port the service binds to (e.g. `8080`).
+- **External Port**: The reverse-proxy or external port (defaults to Internal Port if left blank).
+- **Public (No Auth)**: Indicates if the service is exposed publicly without authentication.
+- **External Reachable**: Indicates if the service is accessible outside the VPN/local network.
+- **Git Repo**: The source code repository for the service (e.g. `https://github.com/...`).
+- **Install Path**: The filesystem path where the service is installed (e.g. `/opt/app`).
+- **Systemd Service**: The systemd unit name for the service (e.g. `app.service`).
+
+### Who sees which metadata
+
+Metadata keys are declared in `@simpleworkjs/directory-schema` with an `admin` flag, and every API response is passed through its projection. There are three tiers:
+
+- **Public** — returned to any authenticated caller, including machine (`ServiceToken`) callers: `ip`, `address`, `sshPort`, `fqdn`, `dnsNames`, `port`, `externalPort`, `portMappings`, `isExternalReachable`, `os`, `gitRepo`, `subType`, `icon`, `tagline`, `isPublic`, `isProduction`, `requestable`, `isCurrentSite`.
+- **Admin-only** — only for members of `app_sso_directory_admin` / `app_sso_admin`: `vmid`, `macAddress`, `installPath`, `systemdService`, and the OAuth config keys (`redirect_uris`, `scopes`, `allowed_groups`, `token_lifetime`).
+- **Never returned** — `client_secret_hash`, plus any key matching `/secret|password|privatekey/i`. Stripped on every path, admins included.
+
+Note that machine tokens are deliberately *not* admins, so anything a machine consumer needs (the firewall generator reads `port` / `externalPort` / `isExternalReachable`) has to be in the public tier. A metadata key that isn't declared at all is treated as admin-only and will silently vanish for normal users — if you add a field to the admin form, declare it in the schema package too.
+
+## Catalog & access requests
+
+The site root (`/`) is the end-user catalog — the only ungated page in the nav. It shows:
+
+- **My Access** — everything the signed-in user can reach (`GET /api/discovery/me`), each card carrying a **how to reach it** block: the URL for a service, or the SSH invocation for a host. When `directory.jumpHost` is set in the config, host cards render the jump-host form `ssh <uid>_-_<slug>@<jumpHost>`; otherwise they fall back to a direct `ssh <uid>@<ip>`.
+- **Discover More** — everything else in the directory, with a **Request access** button.
+- **My Requests** / **Awaiting My Approval** — pending requests, and the approve/deny queue for anyone who owns a requested resource.
+
+A request is a proposal to join an LDAP group. It targets the resource's `member`-level group (the `_access` one, never `_admin`), and approving it performs the LDAP group add — so LDAP stays the single access-control truth and the table is just the audit trail. Approvals are idempotent: approving for someone already in the group succeeds rather than erroring.
+
+Requests are decided by the resource's `owner`, or by any directory admin. Mark a resource `metadata.requestable = false` to keep it out of self-service.
+
+## Navigating the UI
+
+The Directory Management interface provides a **Tree View** toggle that visually nests your resources, making it easy to comprehend your network topography at a glance. You can also filter, search, and sort your entire infrastructure inventory. From the tree view, you can click the green `+` icon next to any resource to instantly add a child resource beneath it.
+
+<a href="images/directory.png" target="_blank"><img src="images/directory.png" alt="Directory & inventory list view" width="80%"></a>
+
+## Slug conventions
+
+Slugs are the stable identifiers automation keys off, so the tooling around the SSO Manager follows a shared convention:
+
+- **Sites**: `site_<name>` — e.g. `site_local`, `site_us-east`
+- **Hosts**: `host_<hostname>` — e.g. `host_pve1`, `host_web01`
+- **Services/apps**: a plain slug or `app_<name>` — e.g. `sso-manager`, `app_emby`
+
+The auto-created LDAP groups derive from the slug (`<slug>_access` / `<slug>_admin`), so keep slugs stable once access groups are in use.
+
+## Automatic registration
+
+You don't have to build the graph by hand — the theta42 tooling registers itself:
+
+### The stack itself (theta-env)
+
+[theta-env](https://github.com/theta42/theta-env)'s `./setup.sh` seeds the directory on every run with the stack it deploys:
+
+- a **site** (name from `CFG_SITE_NAME` in `setup.env`, default `local` → slug `site_local`) marked as the current site
+- the **host** the stack runs on (`host_<hostname>`), with IP, MAC address, OS, and kernel collected from the machine
+- the **services** it composes — SSO Manager, Proxy (management UI), OpenLDAP Directory (the LDAPS endpoint Linux hosts and LDAP-native apps bind to), and OpenResty Edge (the 80/443 data plane) — each with its address, internal port, and git repo
+- the proxy's auto-registered **OAuth client**, linked under its service
+
+The seed is idempotent and non-destructive: a resource whose slug already exists is considered operator-owned — the seed only fills in metadata fields you haven't set, and never overwrites your values.
+
+### Linux hosts (ldap-client)
+
+The `ldap-client` join script enrolls a Debian/Ubuntu machine for LDAP login (SSSD/PAM), LDAP-backed `sudo`, and SSH keys from the directory — and, when given an SSO API token, registers the machine as a `host_<hostname>` resource with its IP, MAC, OS, and kernel, parented to the site named by its configured location.
+
+## Consumers of the directory
+
+The inventory graph isn't just documentation — other components read it to make decisions:
+
+- **[Jump Host](https://theta42.github.io/jump-host/)** — an SSH jump host that resolves which downstream machines a user may reach from their LDAP groups × the directory's `host` resources (`GET /api/discovery/resources?group=<cn>`), then bridges them in. The `host_<hostname>` slugs and `host_<slug>_access` groups this directory creates are exactly what it keys off; a host's `metadata.ip` / `metadata.sshPort` tell it where to connect. So a machine registered here (by theta-env or ldap-client) becomes reachable through the jump host the moment a user is in its access group.
+
+Planned consumers (end-user catalog, firewall/DNS generation) and the model/API gaps they need are tracked in [`directory_spec.md`](https://github.com/theta42/sso-manager-node/blob/master/directory_spec.md) §9.
+
+## API
+
+All of the above uses the same admin API the UI does (group `app_sso_directory_admin` or `app_sso_admin`):
+
+- `GET/POST /api/directory-admin/resources`, `PUT/DELETE /api/directory-admin/resources/:id`
+- `GET/POST/DELETE /api/directory-admin/edges` — parent/child links (`hosts`, `oauth` relations)
+- `GET/POST/DELETE /api/directory-admin/groups` — resource ↔ LDAP group links
+- `GET /api/directory-admin/access-summary` — per-resource group + member counts (the Access column)
+- `GET /api/directory-admin/user-access/:uid` — the reverse lookup: every resource a given user can reach, and via which group
+- Read-only graph views (any authenticated user): `GET /api/discovery/resources`, `/api/discovery/resources/:slug`, `/api/discovery/graph`, `/api/discovery/me`
+
+Access requests are open to any authenticated user; deciding is gated per-resource inside the router (resource owner or directory admin):
+
+- `POST /api/access-requests` — `{slug | resourceId, groupCn?, note?}`
+- `GET /api/access-requests/mine` — the caller's own history
+- `GET /api/access-requests` — pending requests the caller may decide
+- `POST /api/access-requests/:id/approve` · `POST /api/access-requests/:id/deny`
+- `DELETE /api/access-requests/:id` — the requester withdraws their own pending request

docs/groups.md

@@ -0,0 +1,312 @@
+---
+layout: default
+title: Group & Permission Model
+nav_order: 3
+---
+
+# Theta42 Group & Permission Model
+
+This is the canonical reference for how **groups and permissions work** across the
+theta42 suite (SSO Manager, Proxy, Jump-Host) and how **downstream apps and Linux
+hosts** should read and use them. It is written to be implementable by both humans
+and LLM agents.
+
+Everything below assumes LDAP is the single source of truth for identity and group
+membership. Group membership is managed in the **SSO Manager Directory**, generated
+from adopted resources — there is **no standalone "Groups" page**.
+
+---
+
+## 1. Principles
+
+1. **Groups are a projection of the resource graph.** Every adopted host and app
+   in the Directory gets its own groups, auto-created from its identity. Group
+   membership is managed on the resource's modal.
+2. **Two orthogonal resource namespaces: `host` and `app`.** A host administers
+   hosts; an app administers apps. They do not inherit from each other.
+3. **Three levels per resource: `admin`, `access`, and opaque `capability`.**
+   `admin` implies `access`. Capabilities are explicit and never implied by
+   `admin`.
+4. **Multi-site by prefix.** Each site's groups are fully independent, scoped by
+   the site slug.
+5. **Hosts map, LDAP stays clean.** Directory groups are `groupOfNames` (RBAC)
+   with **no `gidNumber`**. A Linux host uses SSSD to import only the groups it
+   needs and generate their GIDs on the fly (see §8) — no mass import, no GID
+   bloat. Only the meta groups are never imported by hosts.
+6. **The directory is the only place groups are created.** `god_admin` is the sole
+   group that does not belong to a resource or site.
+
+---
+
+## 2. Group schema
+
+`S` = site slug (see §7 for normalization). `<host>`/`<app>` = the resource slug.
+`<capability>` = an opaque, app-defined capability token (see §4).
+
+| Group | Scope | Meaning |
+| :--- | :--- | :--- |
+| `god_admin` | global | **Everything, everywhere** (all sites, hosts, apps, consoles, all capabilities). The only non-site group. |
+| `S_super_admin` | site | Everything on site `S` (all hosts, apps, consoles, all capabilities at `S`). |
+| `S_hosts_admin` | site | Admin on **all hosts** at `S`. |
+| `S_hosts_access` | site | Access to **all hosts** at `S`. |
+| `S_hosts_<capability>` | site | Capability `<capability>` on **all hosts** at `S`. |
+| `S_host_<host>_admin` | host | Admin on host `<host>`. |
+| `S_host_<host>_access` | host | Access to host `<host>`. |
+| `S_host_<host>_<capability>` | host | Capability `<capability>` on host `<host>`. |
+| `S_apps_admin` | site | Admin on **all apps** at `S`. |
+| `S_apps_access` | site | Access to **all apps** at `S`. |
+| `S_apps_<capability>` | site | Capability `<capability>` on **all apps** at `S`. |
+| `S_app_<app>_admin` | app | Admin on app `<app>`. |
+| `S_app_<app>_access` | app | Access to app `<app>`. |
+| `S_app_<app>_<capability>` | app | Capability `<capability>` on app `<app>`. |
+
+### Meta groups (implicit membership — not POSIX, no gidNumber)
+
+| Group | Scope | Meaning |
+| :--- | :--- | :--- |
+| `everyone` | global | **All authenticated users**, any site. |
+| `S_everyone` | site | **All authenticated users** at site `S`. |
+
+These are resolved by the directory (any authenticated user passes), never
+enumerated as LDAP members, and cannot be used as Unix groups.
+
+---
+
+## 3. Naming, normalization & reserved rules
+
+- The **structural delimiter is `_`**. It appears only between the fixed segments
+  of a group name.
+- **Site, host, and app slugs never contain `_`.** Normalize to lowercase;
+  spaces and `_` → `-`; strip other non-`[a-z0-9-]`. A host named `Web 01` and a
+  site `Main Office` produce slugs `web-01` and `main-office`.
+- **Aggregate groups use the plural kind** (`hosts`, `apps`); per-resource groups
+  use the singular (`host`, `app`). This makes `S_hosts_admin` unambiguous even
+  if a host were named `admin` (that host would be `S_host_admin_admin`).
+- **The last segment is the level.** If it is `admin` or `access` it is a known
+  level; any other value is an **opaque capability** owned by a downstream app.
+- **Total length budget:** keep a group cn under ~120 chars; reject group
+  creation that would exceed it.
+- Groups are **`groupOfNames`** (RFC 2307bis) with **no `gidNumber`**. GIDs are
+  generated on the host by SSSD for only the groups that host imports (see §8).
+
+---
+
+## 4. Levels and opaque capabilities
+
+- **`admin`** — manage (create/update/delete/config) the resource.
+- **`access`** — use/read the resource.
+- **`<capability>`** — an arbitrary token the SSO does **not** interpret. The SSO
+  manages membership and exposes the group to the app; **the downstream app
+  defines and enforces what the capability means** (e.g. `emby_admin`,
+  `gitea_maintain`, `reboot`, `backup`).
+
+The directory recognizes `admin`, `access`, `super_admin`, and the meta groups.
+Everything else on a resource group is treated as an opaque capability group and
+passed through to consumers.
+
+---
+
+## 5. Permission resolution (inheritance)
+
+Define a user's **effective permission** on a resource by checking, from most
+specific to most general, whether they are a member of any applicable group. The
+rule: a higher group implies everything below it.
+
+### On host `H` at site `S`
+
+| Wanted | Granted if the user is a member of **any** of |
+| :--- | :--- |
+| **admin** on `H` | `god_admin` · `S_super_admin` · `S_hosts_admin` · `S_host_H_admin` |
+| **access** on `H` | (any admin rule above) · `S_hosts_access` · `S_host_H_access` |
+| **capability `C`** on `H` | `god_admin` · `S_super_admin` · `S_hosts_C` · `S_host_H_C` |
+
+### On app `A` at site `S`
+
+Identical, with `app`/`apps` substituted for `host`/`hosts`.
+
+### Management console (SSO / Proxy / Jump-Host)
+
+Each console is registered as an **app** on its site, so console admin is:
+
+`god_admin` · `S_super_admin` · `S_app_<console>_admin`
+
+### Pseudocode
+
+```
+def effective(resource, level_or_cap, site):
+    if user in "god_admin":                  return True
+    if user in f"{site}_super_admin":        return True
+    if level_or_cap in ("admin","access"):
+        agg = f"{site}_{resource.kind}s_{level_or_cap}"
+        if user in agg:                      return True
+    specific = f"{site}_{resource.kind}_{resource.slug}_{level_or_cap}"
+    if user in specific:                     return True
+    if level_or_cap == "access":             return effective(resource, "admin", site)
+    if level_or_cap == "admin":              return False          # access does not imply admin
+    return False
+```
+
+`everyone` / `S_everyone` are a special grantee: if a resource grants a group to
+`everyone` (or `S_everyone`), any authenticated user (at that site) passes.
+
+---
+
+## 6. Where groups live — the Directory, generated from adopted resources
+
+- There is **no standalone Groups page.** Group creation/management happens on an
+  **adopted resource** in the Directory.
+- When a host or app is **adopted** (promoted from Discovered Inventory to
+  managed), the directory auto-creates its `_admin` and `_access` groups (and
+  site aggregates if configured). Capability groups are created on demand.
+- Membership (add/remove users) and capability grants are managed on that
+  resource's modal.
+- Deleting a resource removes its per-resource groups.
+- The `S_super_admin`, `S_hosts_*`, `S_apps_*`, `S_everyone` site groups and the
+  global `god_admin`/`everyone` are managed at the site level (not on a single
+  host/app resource).
+
+---
+
+## 7. Multi-site isolation
+
+One LDAP tree can serve many sites ("Main Office", "Branch Office", "co-lo",
+"Mikes Homelab", …). Each site `S` has its own fully independent set of `S_*`
+groups behind its prefix. A `main-office_super_admin` or `main-office_hosts_admin`
+touches nothing in `branch-office_*` or `steves-homelab_*`. Only `god_admin` and
+`everyone` cross site boundaries.
+
+---
+
+## 8. Unix/POSIX groups — mapped on the host, not in LDAP
+
+Directory groups are **`groupOfNames`** (RFC 2307bis) and carry **no `gidNumber`**.
+There are hundreds of them and only a handful matter on any given host, so we do
+**not** bloat LDAP with GIDs. Instead, each Linux host uses SSSD to import only the
+groups it cares about and map them to GIDs **on the fly** (algorithmic ID mapping).
+This keeps the directory clean and the per-host surface tiny.
+
+### SSSD — generate GIDs on the fly, import only what you need
+
+```ini
+[domain/example]
+id_provider = ldap
+auth_provider = ldap
+ldap_uri = ldaps://ldap.example
+ldap_search_base = dc=example,dc=com
+
+# groupOfNames (RFC 2307bis) schema
+ldap_schema = rfc2307bis
+ldap_group_object_class = groupOfNames
+ldap_group_member = member
+
+# Map GIDs mathematically from the LDAP UUID — no gidNumber in LDAP
+ldap_id_mapping = true
+ldap_group_uuid = entryUUID
+
+# Import ONLY the groups this host needs (e.g. a naming convention or an OU)
+ldap_group_search_filter = (&(objectClass=groupOfNames)(cn=linux-*))
+```
+
+Key ideas:
+- `ldap_id_mapping = true` + `ldap_group_uuid = entryUUID` make SSSD derive a
+  stable GID for any group it imports, so **no `gidNumber` attribute is required**
+  in LDAP.
+- `ldap_group_search_filter` is the gatekeeper: SSSD imports only groups that
+  match, discarding the other hundreds. After changing the filter, clear the
+  cache (`sss_cache -E`; `rm -f /var/lib/sss/db/*`; restart sssd) and verify with
+  `getent group <cn>`.
+
+### What filter to use — the naming convention is the answer
+
+A host should import its **own** resource groups (plus any explicitly granted
+ones). Because the schema is predictable, `ldap-client` can generate the per-host
+`ldap_group_search_filter` from the enrolled host's identity, e.g. a host `web01`
+at site `main-office` imports:
+
+```
+(&(objectClass=groupOfNames)(|(cn=main-office_host_web01_access)
+                               (cn=main-office_host_web01_admin)
+                               (cn=main-office_host_web01_sudo)))
+```
+
+So the operator (or ldap-client) selects a small allowlist of the host's `_access`
+/ `_admin` / capability groups to feed sudoers, SSH `AllowGroups`, and filesystem
+ACLs. **Only those groups are imported** — no GID bloat, no mass import.
+
+### Aliasing an LDAP group into a local group (e.g. `input`)
+
+SSSD cannot merge an LDAP group into a local group whose GID varies per host.
+Two host-side mechanisms cover it:
+
+- **pam_exec** — a script in the login stack adds the user to the local group for
+  the session:
+  ```sh
+  #!/bin/bash
+  if id -Gn "$PAM_USER" | grep -q "host_input"; then usermod -a -G input "$PAM_USER"; fi
+  ```
+  `session optional pam_exec.so /usr/local/bin/add_to_input.sh` in
+  `/etc/pam.d/common-session`.
+
+- **nss-groupmerge** — merge an LDAP group into a local group at NSS time
+  (`/etc/groupmerge.conf`: `input: host_input`, then `group: files sssd groupmerge`
+  in `/etc/nsswitch.conf`), so any service querying `input` sees the LDAP group's
+  members regardless of the local GID.
+
+### Meta groups
+
+`god_admin`, `everyone`, and `S_everyone` are NOT imported by hosts — they have
+implicit membership and are resolved by the directory only.
+
+---
+
+## 9. Downstream-app consumption guide
+
+A downstream app (Emby, Gitea, a custom service, a shell script) reads group
+membership from LDAP and interprets it as follows:
+
+1. **Discover the user's groups** — bind with the user's credentials (or use a
+   service account + `memberOf`). Groups are `groupOfNames` (member DN), so query
+   by the user's DN, e.g. `(&(objectClass=groupOfNames)(member=<user_dn>))`, or use
+   the `memberOf` reverse attribute on the user's entry.
+2. **Match each group to a scope:**
+   - `god_admin` → the user is a global administrator.
+   - `{site}_super_admin` → site administrator for that site.
+   - `{site}_hosts_*` / `{site}_app_*` (aggregate) → applies to all hosts/apps at the site.
+   - `{site}_host_<host>_*` / `{site}_app_<app>_*` → applies to that one resource.
+   - `everyone` / `{site}_everyone` → the user is implicitly a member.
+3. **Interpret the last segment:**
+   - `admin` → full control of that resource.
+   - `access` → read/use.
+   - anything else → a capability **you** define; act on it or ignore it.
+4. A user with `{site}_host_web01_access` can reach `web01`; a user with
+   `{site}_host_web01_reboot` (if you define `reboot`) may reboot it; a user with
+   `{site}_app_emby_emby_admin` administers Emby.
+
+The app must **never** treat an unknown last segment as `admin` or `access`.
+
+---
+
+## 10. Migration from the legacy `app_*` groups
+
+The current global groups (`app_sso_admin`, `app_super_admin`,
+`app_sso_directory_admin`, `app_jump_admin`) are replaced by the new model:
+
+| Legacy | New |
+| :--- | :--- |
+| `app_super_admin` | `god_admin` |
+| `app_sso_admin` | `S_app_sso_admin` (+ `S_super_admin` for site admins) |
+| `app_sso_directory_admin` | `S_app_sso_admin` |
+| `app_jump_admin` | `S_app_jump_admin` |
+
+During the transition the legacy groups may be kept as short-lived aliases that
+resolve to the same effective permission; once everything is moved, remove them.
+
+---
+
+## 11. The management consoles are apps
+
+The SSO, Proxy, and Jump-Host each register themselves as an app on their site and
+receive their auto-generated groups (`S_app_sso_admin`, `S_app_proxy_admin`,
+`S_app_jump_admin`, plus `_access`). Their admin UIs gate on
+`god_admin` · `S_super_admin` · `S_app_<console>_admin`. This keeps everything
+self-consistent: the SSO is "just another app."

docs/index.md

@@ -0,0 +1,86 @@
+---
+layout: default
+title: Home
+description: A self-hosted OpenID Connect provider with a bundled OpenLDAP directory and a web management UI. One login for your modern apps, one LDAP directory for the rest, no phone-home.
+---
+
+# SSO Manager
+
+A self-hosted **OpenID Connect provider** with a bundled **OpenLDAP directory**
+and a web management UI — for home labs and small businesses that want their
+own identity provider instead of a hosted one.
+
+One place to manage your users and groups, one login (OIDC) your modern apps
+can use, and one LDAP directory your older or odder apps can bind to directly.
+Everything runs on your own hardware; no phone-home, no hosted control plane,
+no per-user pricing.
+
+Part of the theta42 self-hosted identity stack, alongside
+[Proxy](https://theta42.github.io/proxy/) (an OIDC + LDAP-aware reverse proxy)
+and [theta-env](https://theta42.github.io/theta-env/) (the two composed with
+one command).
+
+## Screenshots
+
+<a href="images/dashboard.png" target="_blank"><img src="images/dashboard.png" alt="Overview dashboard" width="49%"></a>
+<a href="images/users.png" target="_blank"><img src="images/users.png" alt="User list" width="49%"></a>
+<a href="images/groups.png" target="_blank"><img src="images/groups.png" alt="Groups" width="49%"></a>
+<a href="images/directory.png" target="_blank"><img src="images/directory.png" alt="Directory & inventory" width="49%"></a>
+<a href="images/oauth-clients.png" target="_blank"><img src="images/oauth-clients.png" alt="OAuth client (edit view)" width="49%"></a>
+
+*(click any screenshot to view full size)*
+
+## Why this over the alternatives
+
+Tools like Keycloak, Authentik, Authelia, or Zitadel are OIDC providers, but
+LDAP is either a paid feature, a federation target you have to run
+separately, or absent. If your stack already has apps that speak LDAP
+directly — or you just want one real directory as the source of truth — you
+end up running *two* identity systems and keeping them in sync.
+
+SSO Manager bundles the OpenLDAP directory with the OIDC provider, so OIDC
+apps and LDAP apps read from the same users and groups. The trade-off is
+scope: it's intentionally small and self-hosted, not an enterprise IAM suite.
+If you want a lightweight, self-contained identity provider with a real LDAP
+backend, that's the niche.
+
+## Features
+
+- **OpenID Connect / OAuth 2.0 provider** — your own access/refresh/ID
+  tokens; standard discovery document at `/.well-known/openid-configuration`.
+- **Bundled OpenLDAP directory** — users, groups, POSIX accounts, SSH public
+  keys, and sudo roles, with `memberOf` + referential-integrity overlays.
+- **Web management UI** — users, groups, and OAuth clients from a browser;
+  invite and password-reset flows over email; self-service profile + API
+  tokens.
+- **Direct LDAP binds** — anything that binds LDAP directly (Linux hosts
+  via PAM/SSSD, Gitea, Emby, …) uses LDAPS/StartTLS against the same
+  directory.
+- **All-in-one Docker image** — app + OpenLDAP + Redis in one container, or
+  run the pieces separately via `app_*` env config.
+- **Geo-Location Scaling** — built-in support for N-Way Multi-Master OpenLDAP [replication](replication.html) across physical sites.
+- **[Directory & Inventory](directory.html)** — map sites, hosts, and services as a graph with rich metadata (IP/MAC, OS/kernel, ports, git repos), auto-provisioned access groups, and automatic registration from theta-env and ldap-client. Drives directory-aware tools like the [SSH jump host](https://theta42.github.io/jump-host/).
+- **[Theta Agent & Endpoint C2](agents.html)** — 2-way Go daemon (`theta-agent`) for real-time telemetry (CPU, RAM, Disk, ZFS, GPU), automated host discovery, SSSD/LDAP configuration, and local capability-controlled management operations.
+
+## Get it
+
+```bash
+git clone https://github.com/theta42/sso-manager-node.git
+cd sso-manager-node
+cp secrets.js.example nodejs/conf/secrets.js   # edit it, or use app_* env
+docker compose up -d --build
+```
+
+That's the standalone quick start. For the full set of install options
+(Docker, bare-metal, or as part of the combined SSO + proxy stack), the
+`app_*` env reference, and the OAuth/LDAP internals, see the
+**[GitHub repository](https://github.com/theta42/sso-manager-node)**.
+
+## Related projects
+
+- **[Proxy](https://theta42.github.io/proxy/)** — an OIDC + LDAP-aware
+  reverse proxy, designed to sit in front of this SSO.
+- **[Jump Host](https://theta42.github.io/jump-host/)** — an SSH jump host that
+  uses this SSO's directory to decide who may reach which machine.
+- **[theta-env](https://theta42.github.io/theta-env/)** — runs this SSO
+  Manager and the proxy together with one command.

docs/ldap.md

@@ -0,0 +1,432 @@
+---
+layout: default
+title: LDAP
+description: SSO Manager's bundled OpenLDAP directory — schema, service accounts, TLS, and connecting third-party apps directly.
+---
+
+# LDAP Directory
+
+[← Back to Home](index.html)
+
+> Looking for a plainer explanation of accounts, groups, and managers
+> instead of schema/attribute detail? See
+> [Accounts, Groups & Managers](concepts-accounts.html).
+
+SSO Manager runs an OpenLDAP directory holding your users and groups. The app
+authenticates against it over `localhost:389` (inside the all-in-one container)
+and exposes **LDAPS** (`ldaps://…:636`, TLS) for anything that binds LDAP
+directly — Linux hosts (PAM/SSSD, sudo rules, SSH keys), Gitea, Emby, the
+theta42/proxy, etc.
+
+## Directory layout
+
+```
+dc=yourdomain,dc=com
+├── ou=people          users (inetOrgPerson + posixAccount + …)
+├── ou=groups          groups (groupOfNames)
+└── ou=policies        password policies (pwdPolicy)
+    └── cn=ppolicy     default policy
+```
+
+### Users
+
+User entries are `cn=<uid>,ou=people,<base>` and carry the objectClasses:
+
+- `inetOrgPerson` (cn, sn, mail, …) — identity / contact attrs.
+- `posixAccount` (uid, uidNumber, gidNumber, homeDirectory) — the SSO's
+  `userFilter` is `(objectClass=posixAccount)`, so a user is "a real account"
+  iff it has `posixAccount`.
+- `ldapPublicKey` — SSH public keys (`sshPublicKey`).
+- `sudoRole` — per-user sudo rules (`sudoCommand`, `sudoHost`, `sudoUser`).
+- `theta42Person` (custom auxiliary; `dateOfBirth`).
+
+Every user (person or service account) also carries a `manager` attribute
+(the standard COSINE `manager`, `SUP distinguishedName`) — one or more DNs of
+the people who created/administer that account. Set automatically to the
+creator's DN on signup (whoever an admin was logged in as, or whoever sent
+the invite), and reassignable later from the account's Edit form. Anyone
+listed as a `manager` can edit that account (same fields an admin can:
+mobile, description, SSH key, date of birth, home directory, login shell,
+and the manager list itself) without needing `app_sso_admin`.
+
+Passwords are stored as `{SSHA512}` (8-byte salt, sha512(pass+salt), base64),
+verified by the `pw-sha2` module. The app's `hashPasswordSSHA512` is the
+canonical hasher; if you provision users out-of-band, hash passwords the same
+way or use `slappasswd -h '{SSHA512}'`.
+
+### Groups
+
+Groups are `cn=<name>,ou=groups,<base>` (`groupOfNames`) with a `member`
+attribute listing member DNs. The `memberOf` overlay populates reverse
+membership (`memberOf` on the user); `refint` keeps it consistent on
+add/remove.
+
+Note that `groupOfNames` requires **at least one member**, which has two
+consequences worth knowing: whoever creates a group is automatically seeded
+into it, and removing the last member (user *or* nested group) is refused with
+a 409 rather than leaving an invalid entry behind.
+
+### Nested groups
+
+A `member` DN may be another group's, not just a user's — that is how nesting
+is stored, with no extra schema. Everyone in the nested group is a member of
+the outer one, at any depth. Manage it on the **Groups** page under each
+group's *Nested* tab, or via the API:
+
+```
+PUT    /api/group/:group/nested/:child    nest :child inside :group
+DELETE /api/group/:group/nested/:child    un-nest
+GET    /api/group/:group/effective        direct users, nested groups, and the
+                                          full transitive set of users
+```
+
+Cycles are refused (409) rather than truncated — a loop makes "who is in this
+group" unanswerable. Two standing relationships are wired automatically: the
+cross-app `app_super_admin` is nested into every resource's `<slug>_admin`
+group, and each `<slug>_admin` into its `<slug>_access` group, so administering
+something implies being able to use it.
+
+**Resolving nesting is a client-side job on stock OpenLDAP.** No 2.6.x release
+can evaluate nested groups; `memberOf` and a `(member=X)` filter both return
+direct membership only. The bundled slapd is therefore built from source with
+the `nestgroup` overlay (see *Modules + overlays* below), and the app is told so
+via `ldap.nestedGroupsServerSide`. Against any other server the app computes the
+closure itself — same answers, more queries. Either way, **never read `memberOf`
+directly to make an access decision**; use `utils/user_groups.js`'s `groupCns()`,
+which is correct in both modes.
+
+### Personal groups
+
+Every user (person or service account) also gets a **personal Unix group**
+at creation — `cn=<uid>,ou=groups,<base>`, `objectClass: posixGroup` (RFC
+2307), holding just `cn` and `gidNumber` (the user's primary GID). This is a
+different schema than the `groupOfNames` groups above — its membership
+attribute is `memberUid` (a bare username, not a DN), and unlike
+`groupOfNames` it's valid with zero members. It's excluded from the
+`/groups` page (which filters on `objectClass=groupOfNames`) and managed
+instead from the owning user's own profile page ("Members of `<uid>`'s
+group", admin-only) — add other accounts as supplementary members, e.g. to
+share write access to files owned by this group.
+
+The SSO seeds these groups automatically (entrypoint / `install.sh`):
+
+| Group | Grants |
+|-------|--------|
+| `app_super_admin` | cross-app super admin. Nested into the three below, so its members hold those rights transitively rather than by a special case in app code — and the privilege is visible to LDAP-native consumers (SSSD, sudo) too. |
+| `app_sso_admin` | full admin (users, groups, settings) |
+| `app_sso_oauth_admin` | OAuth client management |
+| `app_sso_invite` | invitation management |
+| `app_sso_service_account` | not a permission — marks a `posixAccount` as a non-person service account (see *Service accounts* below). Deliberately **not** nested into, since it changes how an account is displayed rather than what it may do. |
+
+## TLS (LDAPS / StartTLS)
+
+The bundled slapd generates a **self-signed cert** on first start (CN =
+`LDAP_CERT_CN`, valid 10y, SAN = CN + `localhost` + `127.0.0.1`) and listens on:
+
+- `ldaps:///` — **636**, TLS (the port to expose for direct-LDAP clients).
+- `ldap:///` — **389**, plain + StartTLS (not mapped to the host by default).
+
+The cert lives on the `ldap-certs` volume so it persists across container
+recreation.
+
+### Trusting the self-signed cert
+
+Copy it out and add it to the client's CA store:
+
+```bash
+docker compose cp sso-manager:/etc/openldap/certs/ldap.crt ./ldap.crt
+```
+
+…or, for quick LAN use, set `TLS_REQCERT never` on the client (the theta42/proxy
+sets `app_ldap__tlsOptions__rejectUnauthorized=false` for the same effect).
+
+### Using your own cert
+
+Replace the `ldap-certs` named volume with a bind mount containing your own
+`ldap.crt` + `ldap.key`:
+
+```yaml
+volumes:
+  - ./certs:/etc/openldap/certs   # must contain ldap.crt + ldap.key
+```
+
+The entrypoint leaves existing certs untouched (idempotent).
+
+## Choosing the LDAPS hostname
+
+The `/integrations` page advertises an **LDAPS URL** for direct LDAP binds. By
+default it derives that URL from the public OAuth issuer (e.g.
+`https://sso.example.com` → `ldaps://sso.example.com:636`). That is convenient,
+but it implies LDAP clients reach your directory through the same public
+hostname — which usually means port-forwarding 636 through your router.
+
+**Do not port-forward LDAPS (636) to the public internet.** LDAP simple binds
+have no rate limiting and are a brute-force target. Instead, use one of these
+internal-only patterns and set `conf.ldap.ldapsHost` (or
+`app_ldap__ldapsHost`) so the `/integrations` page shows the right URL.
+
+### 1. Same Docker / local network host (best for apps on this machine)
+
+If the LDAP client runs on the same Docker network as the SSO Manager (for
+example, the bundled `theta-env` stack), use the internal service name:
+
+```
+ldaps://sso-manager:636
+```
+
+In `conf/secrets.js`:
+
+```javascript
+ldap: {
+  ldapsHost: 'sso-manager',
+  ldapsPort: 636,
+}
+```
+
+The proxy in theta-env already uses this internally. The bundled slapd cert
+includes `sso-manager` in its SAN when `LDAP_CERT_CN` is left at its default,
+so hostname verification works without extra setup.
+
+### 2. LAN host behind your router (best for separate home-lan machines)
+
+Create an internal-only DNS record — e.g. `ldap.internal.example.com` →
+`192.168.1.10` — using your router, Pi-hole, or a local `hosts` file. Then get
+or generate a cert whose SAN/CN matches that internal name:
+
+- **Let's Encrypt wildcard** (`*.internal.example.com`) works if you own the
+  public domain and can complete DNS-01 challenge; the record itself can stay
+  private/routable only inside your LAN.
+- **Internal CA** is fine for a pure LAN: run a small CA, issue a cert for
+  `ldap.internal.example.com`, and distribute the CA cert to clients.
+- **Self-signed** with `LDAP_CERT_CN=ldap.internal.example.com` also works; copy
+  the generated `ldap.crt` to each client and trust it.
+
+In `conf/secrets.js`:
+
+```javascript
+ldap: {
+  ldapsHost: 'ldap.internal.example.com',
+  ldapsPort: 636,
+}
+```
+
+The URL on `/integrations` becomes `ldaps://ldap.internal.example.com:636`.
+
+### 3. Public hostname (acceptable only behind a VPN/firewall)
+
+If a remote host must bind LDAP, put it behind a VPN (Tailscale, WireGuard,
+etc.) or a tightly locked-down firewall rule. In that case the public hostname
+may be appropriate, but the LDAPS port should still not be reachable from the
+open internet.
+
+### Why not just use the LDAP server's IP address?
+
+TLS clients verify the server name against the certificate. Connecting to
+`ldaps://192.168.1.10:636` with a cert issued for `*.internal.example.com`
+will fail hostname verification unless you disable cert checks — which removes
+most of the security benefit of LDAPS. Always use a hostname that matches the
+cert.
+
+## Service accounts
+
+A service account is a normal `posixAccount` for something that isn't a
+person: a media manager, a torrent client, a service like Emby, or a
+read-only bind account an app uses to look users up — anything that needs a
+real `uidNumber`/`gidNumber` to own files, or that other accounts join via a
+group for write access (e.g. a `stuff_manager` group granting write rights
+to a media library). There's only one kind — every account, person or
+service, is a real `posixAccount` with a UID.
+
+Create one from the **Users → Service Accounts** tab's "Add new user" form
+with **This is a service account** checked — it skips the birthday/
+Terms-of-Service fields a real person's account needs and asks for just an
+account name. It's flagged (via membership in the `app_sso_service_account`
+group) so it's listed separately from real people and excluded from "all
+users" notification broadcasts.
+
+Email and password are both optional for a service account:
+
+- No `mail` is set unless you give it one (it never needs a mailbox).
+- Leaving the password blank is fine — no `userPassword` attribute is set at
+  all, and an entry with no `userPassword` simply can't bind with any
+  password (standard LDAP simple-bind behavior). Only set a password if the
+  account actually needs to authenticate as itself (e.g. a bind-only account
+  an app uses to look users up).
+
+theta-env's bootstrap creates its own `cn=ldapclient` bind account directly
+against LDAP (independent of this app), and the proxy binds as it — that
+account won't show up in the Service Accounts tab since it isn't managed
+through this app, but it keeps working unchanged.
+
+Either way: don't reuse the admin DN, and give a service account only the
+group memberships and `manager`s it actually needs.
+
+Example bind test (a service account with a password set):
+
+```bash
+ldapsearch -x -H ldaps://sso.example.com:636 \
+  -D "cn=ldapclient,ou=people,dc=yourdomain,dc=com" -W \
+  -b "ou=people,dc=yourdomain,dc=com" '(objectClass=posixAccount)' cn mail
+```
+
+## Connecting a 3rd-party app or container
+
+Most self-hosted apps with an "LDAP authentication" settings page — Gitea,
+Nextcloud, Grafana, Emby, Jenkins, etc. — or containers configured via
+`LDAP_*` env vars, all ask for the same handful of values. These are the
+`conf.ldap` values from [Configuration](configuration.html), applied to
+*your* domain:
+
+| Field the app asks for | Value |
+|---|---|
+| Host / URL | `ldaps://<your-sso-host>:636` (preferred), or `ldap://<host>:389` + StartTLS |
+| Bind DN | a dedicated service account — e.g. `cn=ldapclient,ou=people,<base>` (see above) |
+| Bind password | that service account's password |
+| User search base | `ou=people,<base>` |
+| User search filter | `(objectClass=posixAccount)` |
+| Username attribute | `uid` |
+| Email attribute | `mail` |
+| Group search base | `ou=groups,<base>` |
+| Group membership attribute | `memberOf` (on the user entry — populated by the `memberof` overlay) |
+| TLS | required for 636 (LDAPS); if using the bundled self-signed cert, either trust it (see *TLS* above) or set the app's "don't verify cert" option for LAN-only use |
+
+### Worked example: Gitea
+
+Gitea's **Admin → Authentication Sources → Add Authentication Source** (type
+LDAP, "Bind DN/Password") maps directly:
+
+- Security Protocol: `LDAPS`
+- Host / Port: your SSO host / `636`
+- Bind DN: `cn=ldapclient,ou=people,dc=yourdomain,dc=com`
+- Bind Password: the service account's password
+- User Search Base: `ou=people,dc=yourdomain,dc=com`
+- User Filter: `(&(objectClass=posixAccount)(uid=%s))`
+- Username Attribute: `uid`
+- E-mail Attribute: `mail`
+
+Other apps with an LDAP settings UI follow the same shape — the field names
+above are the constants; only the base DN and hostname change per deployment.
+
+### Generic Docker container (`LDAP_*` env vars)
+
+For images that take a flat env-var LDAP config (there's no single standard,
+but most look like this):
+
+```yaml
+environment:
+  LDAP_URL: ldaps://sso.example.com:636
+  LDAP_BIND_DN: cn=ldapclient,ou=people,dc=yourdomain,dc=com
+  LDAP_BIND_PASSWORD: <service-account-password>
+  LDAP_USER_BASE: ou=people,dc=yourdomain,dc=com
+  LDAP_USER_FILTER: (objectClass=posixAccount)
+  LDAP_GROUP_BASE: ou=groups,dc=yourdomain,dc=com
+```
+
+Check the specific image's docs for its actual variable names — the values
+you plug in are still the ones from the table above.
+
+### Full Linux host auth (SSH, sudo, login) instead of a single app
+
+If you want a *host* (not just one app) to authenticate logins, SSH keys, and
+sudo against this LDAP directory — not just one application — that's a
+different integration (SSSD + PAM + NSS, not a single bind). See
+[theta42/ldap-client](https://github.com/theta42/ldap-client): a script that
+configures SSSD on Ubuntu/Debian hosts against this directory, including
+group-based access control and SSH public key retrieval from LDAP.
+
+## Modules + overlays (external LDAP servers)
+
+If you point the app at your own LDAP server instead of the bundled slapd, it
+needs:
+
+- **Modules:** `pw-sha2` (the app stores user passwords as `{SSHA512}`),
+  `ppolicy`, `memberof`, `refint`.
+- **Optional — `nestgroup`:** server-side nested-group evaluation. Not in any
+  released OpenLDAP (added to master as ITS#10161 in March 2024; 2.7 is still
+  unreleased), so the bundled image builds slapd from a pinned upstream commit.
+  Without it the app resolves nesting itself and everything still works — leave
+  `ldap.nestedGroupsServerSide` at `false`. With it, set that to `true` and
+  configure:
+
+  ```
+  overlay         nestgroup
+  nestgroup-base  ou=groups,<base>
+  nestgroup-flags member-filter memberof-filter memberof-values
+  ```
+
+  Flags are **space-separated**; the comma form the man page's `{a, b, c}`
+  notation suggests is rejected. `member-values` is deliberately omitted — it
+  expands the `member` attribute when reading a group, which destroys the
+  distinction between "listed here" and "reachable through a nested group", and
+  the raw values are then unrecoverable. Transitive answers come from the filter
+  flags and from `GET /api/group/:group/effective`.
+
+  One more consequence of building from master: it ships **LMDB 1.0.0**, whose
+  on-disk format is mutually unreadable with the 0.9.x in 2.6.x
+  (`MDB_INVALID: File is not an LMDB file`). Moving a directory between the two
+  is a `slapcat` → `slapadd` reload, not a restart.
+- **Custom schema:** the `theta42Person` auxiliary objectClass with
+  `dateOfBirth` — see `ops/ldap-setup.sh` for the LDIF.
+- **Directory tree:** `ou=people`, `ou=groups`, `ou=policies` under the base DN,
+  a default `pwdPolicy` at `cn=ppolicy,ou=policies,<base>`.
+- **Required groups:** `app_sso_admin`, `app_sso_invite`, `app_sso_oauth_admin`,
+  and `app_super_admin` (the cross-app super-admin group; the bundled entrypoint
+  also nests it into the first three).
+
+`ops/ldap-setup.sh -p <admin-password>` configures all of the above
+idempotently against a running slapd (auto-detects the database holding your
+base DN, and verifies `pwdAccountLockedTime` is live — the attribute the app's
+active/inactive toggle depends on).
+
+## Backups and restore
+
+`ops/backup.sh` automates this (LDAP + Redis + `./config/`, with retention)
+for standalone deployments — see the *Backups and restore* section of
+`DEPLOYMENT.md`. The manual LDAP-only steps below are what it does under the
+hood, useful if you want just the directory without Redis/config.
+
+**Backup** (while slapd is running):
+
+```bash
+docker compose exec sso-manager slapcat -f /etc/openldap/slapd.conf \
+  -b "dc=yourdomain,dc=com" > ldap-backup-$(date +%F).ldif
+```
+
+Store the `.ldif` off the host — it contains every user's password hash.
+
+**Restore** into a stopped directory. The SSO image uses a static `slapd.conf`
+(slapd starts with `-f`, not cn=config `-F`), so restore uses `slapadd -f`:
+
+```bash
+docker compose stop sso-manager
+docker compose run --rm --no-deps --entrypoint sh sso-manager -c \
+  'rm -f /var/lib/ldap/* && slapadd -f /etc/openldap/slapd.conf -l /dev/stdin' \
+  < ldap-backup-<date>.ldif
+docker compose start sso-manager
+```
+
+Verify: `docker compose exec sso-manager ldapsearch -x -b "dc=yourdomain,dc=com"`.
+
+Redis state (OAuth clients, tokens) and `./config/` secrets are backed up
+separately — see the *Backups and restore* section of `DEPLOYMENT.md` for the
+full (LDAP + Redis + secrets) runbook.
+
+## Troubleshooting
+
+### `503 OpenLDAP ppolicy overlay is not configured`
+
+The ppolicy overlay isn't attached to the database holding your users, so the
+active/inactive toggle can't set `pwdAccountLockedTime`:
+
+```bash
+sudo ./ops/ldap-setup.sh -p 'admin-password' -b dc=yourdomain,dc=com
+```
+
+### LDAP connection refused
+
+```bash
+docker compose exec sso-manager sh -c 'ldapsearch -x -H ldap://localhost:389 -b "" -s base'
+systemctl status slapd   # bare metal
+```
+
+[← Back to Home](index.html)

docs/oauth.md

@@ -0,0 +1,112 @@
+---
+layout: default
+title: OAuth / OIDC
+description: SSO Manager's OpenID Connect / OAuth 2.0 provider — discovery document, client registration, and token endpoints.
+---
+
+# OAuth 2.0 / OpenID Connect
+
+[← Back to Home](index.html)
+
+> Looking for a plainer explanation of clients/scopes/redirect URIs instead
+> of endpoint-level detail? See
+> [Connecting Apps (Single Sign-On)](concepts-oauth-apps.html).
+
+SSO Manager is an **OpenID Connect / OAuth 2.0 provider**: it issues its own
+access, refresh, and ID tokens that your apps can consume to authenticate
+users and authorize API calls. It also runs a full OpenLDAP directory, so it
+can be both your SSO and your user directory at once.
+
+## Discovery
+
+The provider publishes a standards-compliant discovery document:
+
+```
+GET https://<sso-host>/.well-known/openid-configuration
+```
+
+It advertises the `issuer`, `authorization_endpoint`, `token_endpoint`,
+`userinfo_endpoint`, `end_session_endpoint`, supported scopes, and token
+lifetimes. OIDC clients (e.g. the theta42/proxy) can read their endpoint URLs
+from here rather than configuring each one.
+
+The `issuer` advertised is `conf.oauth.issuer` — set it to the **browser-facing**
+HTTPS URL the SSO is served at (e.g. `https://sso.example.com`), either in
+`conf/secrets.js` or via `app_oauth__issuer` / `OAUTH_ISSUER`.
+
+## OAuth clients
+
+An OAuth client represents an app that authenticates against the SSO. Each has:
+
+- `client_id` (UUID) + `client_secret` (bcrypt-hashed; the **raw secret is
+  shown once** when the client is created or rotated — save it immediately).
+- `name`, `description`, `created_by` (the admin uid that created it).
+- `redirect_uris` — allowed callback URLs. Each entry matches exactly, or may
+  use `*` (one hostname label) / `**` (any number of labels) as a wildcard —
+  e.g. `https://*.example.com/__proxy_auth/callback` covers every host
+  theta42/proxy fronts under `example.com`, so you don't have to register
+  each proxied host's callback individually.
+- `scopes` — requested scopes (default `openid profile email groups`).
+- `allowed_groups` — restrict the client to members of specific SSO groups
+  (empty = any valid user).
+- `token_lifetime` — `access_token` / `refresh_token` lifetimes (seconds).
+
+### Managing clients
+
+Clients are managed directly from the **Directory** tab in the web UI. They are modeled as resources of `kind: oauth` and must belong to a parent Service.
+
+| Action | How to do it |
+|--------|--------------|
+| **Create** | Click the green **+** on a parent Service to add a child resource. Choose **OAuth Integration**. The raw `client_secret` is shown once upon creation. |
+| **Edit** | Click the edit pencil on the OAuth resource in the Directory list or tree. You can update redirect URIs, scopes, allowed groups, and token TTLs. |
+| **Delete** | Click the trash can on the OAuth resource in the Directory list. |
+| **Rotate Secret** | Open the edit modal for the OAuth resource and click **Rotate Client Secret**. The new raw secret is shown once. |
+
+> All client-management actions use the standard Directory API (`/api/directory-admin/resources`) and are gated by the `app_sso_directory_admin` group.
+
+<a href="images/oauth-clients.png" target="_blank"><img src="images/oauth-clients.png" alt="Editing an OAuth client resource" width="80%"></a>
+
+## Scopes
+
+| Scope | Claims / access |
+|-------|-----------------|
+| `openid` | OIDC ID token + discovery |
+| `profile` | `preferred_username`, display name, etc. |
+| `email` | the user's `mail` |
+| `groups` | the user's group memberships (the `groups` claim) |
+
+The `groups` claim is what relying parties (e.g. the proxy's
+`app_auth__adminGroups`) use to map group membership to roles.
+
+## Token lifetimes
+
+Defaults (overridable per-client via `token_lifetime`, or globally via
+`app_oauth__token_lifetime__access_token` /
+`app_oauth__token_lifetime__refresh_token`):
+
+- access token: 3600s (1 hour)
+- refresh token: 2592000s (30 days)
+
+## Admin gating
+
+SSO admin actions are gated by LDAP group membership (checked via the group's
+`member` list, not `memberOf` on the user):
+
+- `app_sso_admin` — full admin (users, groups, settings).
+- `app_sso_oauth_admin` — OAuth client management.
+- `app_sso_invite` — invitation management.
+
+The bootstrap in [theta-env](https://github.com/theta42/theta-env) creates your
+first admin and adds them to `app_sso_admin` + `app_sso_oauth_admin`
+automatically; for a standalone install, add the admin's DN to those groups
+manually (or via `ops/ldap-setup.sh`).
+
+## JWT signing
+
+Tokens are signed with `conf.oauth.jwtSecret` (`app_oauth__jwtSecret` /
+`JWT_SECRET`). **Persist this secret** — if it changes, every issued token
+stops validating. The all-in-one Docker image auto-generates one if none is set,
+but that generated value does not survive container recreation unless you
+persist it (set `JWT_SECRET` in your `.env`).
+
+[← Back to Home](index.html)

docs/plugins.md

@@ -0,0 +1,132 @@
+# Plugins
+
+The SSO Manager runs **plugins** as scheduled background tasks. A plugin
+**type** is an installed module; a plugin **instance** is a configured, loadable
+copy of a type. You can create, edit, load/unload, run, and delete instances
+from the **Plugins** page (or the `/api/plugins` API), and you can run several
+instances of the same type — e.g. two Proxmox endpoints, each with its own URL
+and token on its own schedule.
+
+Per-instance **secrets** are stored in [OpenBao](https://openbao.org/) at
+`secret/plugins/<instance-id>/conf`, not in `sso-secrets.js`. The admin UI only
+ever shows them masked (`********`); the plugin reads them at run time. This
+needs theta-suite ≥ v1.30.1 (which grants the `sso-broker` OpenBao policy
+`secret/plugins/*`); re-run `./setup.sh` after upgrading.
+
+## Plugin types
+
+A plugin type is a module under `nodejs/plugins/<category>/<type>.js`. The
+filename basename (without `.js`) is the `type`; the parent directory is the
+`category`. The built-ins ship under `plugins/discovery/`:
+
+- `proxmox` — Proxmox VE (URL + API token)
+- `unifi` — UniFi Network controller (URL + username/password)
+- `nmap` — nmap OS + port scan (a target range; no credentials)
+
+A module exports a **manifest**:
+
+```javascript
+module.exports = {
+  // Identity — `type`/`category` default to the file/dir name but can be set
+  // explicitly. `name`/`description` show up in the UI.
+  type: 'proxmox',
+  category: 'discovery',
+  name: 'Proxmox VE',
+  description: 'Discover VMs, containers, and nodes from a PVE endpoint.',
+
+  // Drives the admin UI form, API validation, and secret masking. Fields with
+  // `secret: true` are stored in OpenBao; the rest live in the DB row.
+  configSchema: [
+    { key: 'url',         label: 'API URL',       type: 'url',      required: true },
+    { key: 'tokenId',     label: 'Token ID',      type: 'text',     required: true },
+    { key: 'tokenSecret', label: 'Token Secret',  type: 'password', required: true, secret: true }
+  ],
+
+  // "Test" button: validate the config (don't do the work). Return
+  // { ok: true } or { ok: false, error: '...' }. Optional.
+  validate: async (config) => { … },
+
+  // The work. `run` is the generalized contract name; the discovery plugins
+  // also keep `discover` as an alias for back-compat. For `category:
+  // 'discovery'`, the scheduler passes the result to the discovery reconciler.
+  run: async (config) => { return { resources, edges }; },
+  discover: async (config) => { return { resources, edges }; }
+};
+```
+
+`run(config)` receives the merged non-secret config + secret values as one flat
+object (e.g. `{ url, tokenId, tokenSecret }`). For a discovery plugin it
+returns `{ resources, edges }`; the reconciler upserts them into the resource
+graph attributed to the instance's **slug** (the `discovery_sources` name).
+
+### Writing a custom plugin type
+
+Drop a `.js` file under `nodejs/plugins/discovery/` (or a new category directory)
+following the manifest above. New types are picked up at boot, so restart the
+SSO Manager after adding one. Runtime load/unload is per-**instance** only —
+adding a new type still needs a restart.
+
+## The Plugins page
+
+Under **Plugins** (nav, admin-only — `app_sso_admin` / `app_sso_directory_admin`
+/ `app_super_admin`):
+
+- **New Plugin** — pick a type, name it, choose a unique slug (the discovery
+  source name + the URL the resource graph attributes results to), set a cron
+  schedule, and fill in the config form (secret fields are password inputs).
+  Creating it schedules it and kicks one immediate run.
+- **Edit** — name, cron, and non-secret config.
+- **Edit Secrets** (key icon) — password fields, prefilled masked. Leave a
+  field blank to keep its current value.
+- **Test** (vial icon) — runs the plugin's `validate`.
+- **Run now** (play icon) — enqueues one immediate run regardless of state.
+- **Load / Unload** — enable/disable the schedule without deleting the instance.
+- **Delete** — removes the schedule, the OpenBao secret namespace, and the row.
+
+## API
+
+All endpoints are mounted at `/api/plugins`, require an authenticated admin
+(`app_sso_admin` / `app_sso_directory_admin` / `app_super_admin`), and return
+secret values masked.
+
+| Method + path | Purpose |
+|---|---|
+| `GET /api/plugins/types` | list installed plugin types + their `configSchema` |
+| `GET /api/plugins` | list instances (with masked secrets + last-run state) |
+| `GET /api/plugins/:id` | one instance |
+| `POST /api/plugins` | create — body `{ pluginType, name, slug, cron, config }` where `config` is a flat object of all field values; secret fields are split into OpenBao |
+| `PUT /api/plugins/:id` | update name/cron/enabled + non-secret config |
+| `PUT /api/plugins/:id/secrets` | update secret fields (blank = keep) |
+| `POST /api/plugins/:id/test` | run `validate` → `{ ok }` or `{ ok:false, error }` |
+| `POST /api/plugins/:id/load` | enable + schedule + run now |
+| `POST /api/plugins/:id/unload` | unschedule + disable |
+| `POST /api/plugins/:id/run` | enqueue one immediate run |
+| `DELETE /api/plugins/:id` | unschedule + remove OpenBao secrets + delete row |
+| `GET /api/plugins/:id/runs` | `{ lastRunAt, lastStatus, lastError }` |
+
+## Scheduler internals
+
+The scheduler ([BullMQ](https://docs.bullmq.io/) over Redis) gives each instance
+a stable JobScheduler id (`plugin:<instanceId>`); load/unload upsert/remove
+that one schedule without disturbing the others. A daily `garbage_collect` job
+prunes discovery resources not seen in > 7 days.
+
+### Legacy migration
+
+Before this system, plugins were configured statically in `sso-secrets.js`:
+
+```javascript
+module.exports = {
+  discovery: {
+    plugins: {
+      proxmox: { enabled: true, cron: '0 * * * *', url: '…', tokenId: '…', tokenSecret: '…' }
+    }
+  }
+};
+```
+
+On the first boot of SSO Manager ≥ v1.17.0, if the `PluginInstance` table is
+empty **and** `conf.discovery.plugins` has entries, one instance per configured
+type is seeded automatically (secret fields copied into OpenBao). After that the
+table is non-empty and the static config is ignored — manage plugins from the
+UI/API instead. The migration is idempotent (guarded by the empty-table check).

docs/replication.md

@@ -0,0 +1,55 @@
+---
+layout: default
+title: Geo-Location Scaling (Replication)
+---
+
+# Geo-Location Scaling (Replication)
+
+SSO Manager is built to be a self-contained identity provider, but if you have multiple physical sites, you may want a local copy of the directory at each site to ensure low latency and high availability.
+
+## Why and when to use this?
+- **High Availability (HA)**: If your primary site goes completely offline, your other sites can still authenticate users locally without depending on a WAN link.
+- **Low Latency**: Applications at a remote site can bind directly to their local LDAP server (`localhost` or LAN IP) instead of traversing the internet to query the primary site, making logins blazing fast.
+- **Independent Failure Domains**: By replicating only the LDAP directory (the source of truth) and keeping session state (Redis) independent, you prevent complex "split-brain" scenarios in the web UI. A failure at Site A won't bring down Site B.
+
+By default, the `sso-manager` Docker container runs a single, independent OpenLDAP instance. However, you can enable **N-Way Multi-Master Replication** via environment variables.
+
+## How it works
+
+In an N-Way Multi-Master setup, every site runs a fully active OpenLDAP server (`slapd`).
+- **Reads and Writes anywhere**: A user can change their password or update their profile at Site A, Site B, or Site C.
+- **Conflict Resolution**: OpenLDAP's `syncrepl` engine uses Context Sequence Numbers (CSN) to track changes. If Site A goes offline and a user changes their password at Site B, Site A will automatically pull the newest changes the moment it rejoins the cluster.
+- **Independent Redis**: Session data, API Tokens, and OAuth Clients are stored in Redis. By design, Redis is NOT replicated in this geographic setup. This ensures that a failure at Site A never causes Site B's Redis to become read-only, which would break the web UI at Site B. OAuth clients must be configured per-site.
+
+## Configuration
+
+To enable replication, you must pass two environment variables to the `sso-manager` container:
+
+1. `LDAP_SERVER_ID`: A unique integer for this node (e.g., `1`, `2`, `3`). This MUST be unique across the cluster.
+2. `LDAP_REPLICATION_HOSTS`: A space-separated list of the LDAP URLs of all **other** nodes in the cluster.
+
+### Example using `theta-env` / Docker Compose
+
+**Site 1 (`setup.env` or `docker-compose.yml`)**
+```env
+LDAP_SERVER_ID=1
+LDAP_REPLICATION_HOSTS="ldaps://sso.site2.com:636 ldaps://sso.site3.com:636"
+```
+
+**Site 2 (`setup.env` or `docker-compose.yml`)**
+```env
+LDAP_SERVER_ID=2
+LDAP_REPLICATION_HOSTS="ldaps://sso.site1.com:636 ldaps://sso.site3.com:636"
+```
+
+**Site 3 (`setup.env` or `docker-compose.yml`)**
+```env
+LDAP_SERVER_ID=3
+LDAP_REPLICATION_HOSTS="ldaps://sso.site1.com:636 ldaps://sso.site2.com:636"
+```
+
+Once configured, the container's entrypoint will automatically load the `syncprov` module, enable `mirrormode`, and generate the necessary `syncrepl` blocks in `/etc/openldap/slapd.conf`.
+
+## User Locations
+
+When creating or editing a user, you can specify their **Location (Site)**. This maps directly to the standard LDAP `l` (localityName) attribute, allowing you to track which physical site a user belongs to natively within the directory.

docs/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://theta42.github.io/sso-manager-node/sitemap.xml

docs/vault.md

@@ -0,0 +1,56 @@
+# Vault Secrets Management
+
+The Vault Secrets feature integrates with OpenBao to provide a secure key-value store for your environment. It allows you to store sensitive information like passwords, API keys, and credentials, ensuring they are encrypted and access-controlled.
+
+## Usage
+
+You can access the Vault UI from the application's top navigation bar. 
+
+### Creating Secrets
+
+1. Click on the **New Secret** button.
+2. Enter a **Secret Path**. This acts as the name/identifier of your secret (e.g., `db-credentials`).
+3. Enter the **Secret Data** in JSON format. For example:
+   ```json
+   {
+     "username": "admin",
+     "password": "supersecretpassword123"
+   }
+   ```
+4. Click **Save Secret**.
+
+### Reading and Editing Secrets
+
+* To view a secret, click on its name in the **Secrets List**.
+* To update an existing secret, select it and click the **Edit** button. You can then modify the JSON data and save your changes.
+
+### OpenBao Integration
+
+The secrets are stored in an OpenBao backend configured in development mode. The default KV (Key-Value) version 2 engine is mounted at `secret/`. The built-in UI uses the `/api/vault/secret/` API endpoints to interact with OpenBao.
+
+## Apps tab (admin)
+
+The **Apps** tab mints a scoped OpenBao token for an **external application** so it can read its own configuration out of OpenBao — a downstream-app credential, not a per-user secret.
+
+1. Enter an app **name** (e.g. `my-service`) and click **Mint token**.
+2. A token is shown **once** — copy it into the external app now; it cannot be recovered later. The app uses it as the `X-Vault-Token` header against `secret/apps/<name>/*` (see the connection convention shown on the page).
+3. The **Minted apps** list shows every token you've created (metadata only — the token itself is never stored). sso keeps each token alive by renewing it periodically, so a downstream app's credential stays valid as long as sso runs. If an app shows a **renewal error**, re-mint it here — that revokes the old token and issues a fresh one.
+
+The token is scoped to `secret/apps/<name>/*` only (policy `app-<name>`), so a compromised token can't touch any other secret.
+
+## Shared tab
+
+The **Shared** tab lets you share a secret with another user (or app) without copying the value around.
+
+1. **New** — give the secret a name (slug) and its JSON data. The owner has full read/write on `secret/shared/<uid>/<slug>`.
+2. Open a secret and use **Grants** to share it with a user or app; the grantee's OpenBao policy is edited immediately so the share takes effect with no token re-mint. Revoking a grant removes access at the ACL.
+3. The data itself is read through the normal Vault proxy using each user's own session, so OpenBao enforces read access per-request.
+
+## API Access
+
+If you need to programmatically access the secrets, you can interact directly with the OpenBao API using the root token (in dev mode):
+
+```bash
+# Example: Read a secret via the API
+curl -H "X-Vault-Token: root" -H "Authorization: Bearer <your-sso-token>" http://<your-sso-host>/api/vault/secret/data/<your-secret-path>
+```

nodejs/app.js

@@ -44,9 +44,10 @@ app.onListen.push(function(){
     });
   });
   
-  // Initialize Theta Agent WebSockets
-  require('./routes/api_agent')(app);
-}); 
+  // Initialize Theta Agent WebSockets. The REST router is already mounted
+  // synchronously above (see the /api/agent mount); this hook only wires the WS.
+  require('./routes/api_agent').initAgentWebSockets(app);
+});
 
 // Gzip text responses (HTML/JS/CSS/JSON). The admin UI loads ~13 separate,
 // uncompressed vendor JS/CSS files on every full page navigation (a
@@ -72,7 +73,8 @@ app.locals.ui = require('./utils/ui');
 // Have express server static content( images, CSS, browser JS) from the public
 // local folder. maxAge is short since this is the app's own JS/CSS, which
 // changes on every deploy and isn't cache-busted/fingerprinted.
-app.use('/static', express.static(path.join(__dirname, 'public'), {maxAge: '1h'}))
+app.use('/static', express.static(path.join(__dirname, 'public'), {maxAge: '1h'}));
+app.use('/resources', express.static(path.join(__dirname, 'public/resources'), {maxAge: '1h'}));
 
 // Routes for front end content.
 app.use('/', require('./routes/index'));
@@ -104,6 +106,12 @@ app.use('/api/conf', middleware.auth, require('./routes/api_conf'));
 // Self-service API tokens (PATs) — owner-scoped, no admin group required.
 app.use('/api/api-token', middleware.auth, require('./routes/api_token'));
 
+// theta-agent REST API. Mounted SYNCHRONOUSLY (before the 404 catch-all below),
+// not from an onListen hook — a router registered post-listen would sit behind
+// the terminal 404 handler and make every /api/agent/* request 404. The agent
+// WebSocket handler (routes/api_agent.initAgentWebSockets) still runs on onListen.
+app.use('/api/agent', require('./routes/api_agent'));
+
 // OAuth 2.0 / OpenID Connect
 app.use('/oauth', oauthRouter);
 app.use('/api/oauth', middleware.auth, oauthApiRouter);
@@ -125,6 +133,8 @@ app.use('/api/plugins', middleware.auth, require('./routes/api_plugins'));
 const vaultBroker = require('./utils/vault_broker');
 app.use('/api/vault/apps', middleware.auth, vaultBroker.mintAppRouter);
 app.use('/api/vault', middleware.auth, vaultBroker.scopeGuard, vaultBroker.vaultProxy());
+// Shared secrets (metadata + grants; data reads go through /api/vault proxy).
+app.use('/api/shared-secrets', middleware.auth, require('./routes/api_shared_secrets'));
 
 // Catch 404 and forward to error handler. If none of the above routes are
 // used, this is what will be called.

nodejs/bin/www

@@ -60,6 +60,13 @@ models.initORM().then(() => {
   initScheduler(conf.discovery).catch(err => {
     console.error('Failed to initialize scheduler:', err);
   });
+
+  // Keep external-app vault tokens alive: renew every stored accessor now and
+  // on an interval (see vault_broker.startAppTokenRenewal). Only meaningful
+  // when OpenBao is configured; without VAULT_TOKEN the loop's calls fail soft.
+  if (process.env.VAULT_TOKEN) {
+    require('../utils/vault_broker').startAppTokenRenewal();
+  }
 }).catch(err => {
   console.error('Failed to initialize ORM:', err);
   process.exit(1);

nodejs/conf/base.js

@@ -57,14 +57,6 @@ module.exports = {
 		password: '__in secrets file__',
 		did:      '__in secrets file__',
 	},
-	smtp: {
-		host: 'localhost',
-		port: 587,
-		secure: false,
-		user: 'noreply@example.com',
-		pass: '__in secrets file__',
-		from: 'SSO Manager <noreply@example.com>',
-	},
 	directory: {
 		// Public SSH jump host fronting the lab, if there is one (the jump-host
 		// component). When set, a host card in the catalog shows the real

nodejs/models/index.js

@@ -17,6 +17,9 @@ const { Resource, ResourceEdge, ResourceGroup } = require('./resource');
 const { AccessRequest } = require('./access_request');
 const { Webhook } = require('./webhook');
 const { PluginInstance } = require('./plugin_instance');
+const { SharedSecret } = require('./shared_secret');
+const { SharedSecretGrant } = require('./shared_secret_grant');
+const { VaultAppToken } = require('./vault_app_token');
 async function initORM() {
   const ormConf = conf.orm || {
     dialect: 'sqlite',
@@ -31,15 +34,48 @@ async function initORM() {
       conf: { orm: ormConf },
       models: [
         Resource, ResourceEdge, ResourceGroup, AccessRequest, Webhook, PluginInstance,
+        SharedSecret, SharedSecretGrant, VaultAppToken,
         Token, AuthToken, InviteToken, ImpersonationToken, PasswordResetToken, OtpToken, ServiceToken
       ]
     });
     console.log('[initORM] ORM initialized successfully');
     console.log('[initORM] Resource.orm =', !!Resource.orm, 'Token.orm =', !!Token.orm);
+    await healSchema();
   } catch (err) {
     console.error('[initORM] ORM initialization failed:', err.message);
     throw err;
   }
 }
 
+// Add-only schema heal. @simpleworkjs/orm runs sequelize.sync() WITHOUT alter,
+// which creates missing tables but never touches existing ones — so a column
+// added in a newer release (e.g. PluginInstance.lastLog) simply never appears
+// in an upgraded deployment's database and every query on the model fails
+// ("no such column"). This walks each Sequelize model and ADDs any attribute
+// missing from its table. Strictly additive (never drops or retypes), works on
+// any dialect via the query interface, and fail-soft per column so one bad
+// attribute can't take the boot down.
+async function healSchema() {
+  const adapter = Resource.orm && Resource.orm.adapters && Resource.orm.adapters.sequelize;
+  if (!adapter || !adapter.sequelize) return;
+  const sequelize = adapter.sequelize;
+  const qi = sequelize.getQueryInterface();
+  for (const SM of Object.values(sequelize.models)) {
+    const table = SM.getTableName();
+    let existing;
+    try { existing = await qi.describeTable(table); }
+    catch (e) { continue; } // no table yet — sync() handles creation
+    for (const [name, attr] of Object.entries(SM.getAttributes())) {
+      const col = attr.field || name;
+      if (existing[col]) continue;
+      try {
+        await qi.addColumn(table, col, attr);
+        console.log(`[initORM] schema heal: added missing column ${table}.${col}`);
+      } catch (e) {
+        console.error(`[initORM] schema heal: could not add ${table}.${col}:`, e.message);
+      }
+    }
+  }
+}
+
 module.exports.initORM = initORM;

nodejs/models/shared_secret.js

@@ -0,0 +1,56 @@
+'use strict';
+
+// SharedSecret — a secret the owner has published to the shared namespace so it
+// can be shared with other users and/or downstream apps.
+//
+// The secret DATA lives in OpenBao at `secret/shared/<ownerUid>/<slug>` (KV-v2),
+// never in the DB. This row is metadata only (owner + slug + description) and is
+// the source of truth for the UI (which shares exist). ACCESS CONTROL is enforced
+// entirely by OpenBao ACL policies: the owner's `user-<uid>` policy grants full
+// R/W on `secret/shared/<ownerUid>/*`, and each grantee's policy content is
+// edited to add `read` on the exact shared path (see vault_broker.js — policy
+// content is parsed live at token use, so a grant takes effect immediately with
+// no token re-mint). `secretId` on SharedSecretGrant links grantees to this row.
+//
+// `slug` is unique and immutable in practice — it is embedded in the shared path
+// and in grantee policy rules, so changing it would require rewriting policies.
+// Like PluginInstance, there is no ORM auto-timestamp hook: route handlers stamp
+// created_by/on + updated_by/on on every write. `id` (uuid) is generated by the
+// ORM on create.
+
+const { Model } = require('@simpleworkjs/orm');
+
+class SharedSecret extends Model {
+  static fields = {
+    id: { type: 'uuid', primaryKey: true },
+    // Human slug embedded in the OpenBao path: secret/shared/<ownerUid>/<slug>.
+    // Unique so two owners can't collide on the same shared path.
+    slug: { type: 'string', isRequired: true, unique: true, min: 1, max: 64 },
+    // The publishing user's uid — also the shared path's namespace segment.
+    ownerUid: { type: 'string', isRequired: true, min: 1, max: 64 },
+    // Optional human description shown in the Shared tab.
+    description: { type: 'text' },
+    // Audit stamps (set by the route handler, not by an ORM hook).
+    created_by: { type: 'string' },
+    created_on: { type: 'integer' },
+    updated_by: { type: 'string' },
+    updated_on: { type: 'integer' },
+  };
+
+  // Full OpenBao KV-v2 path for this shared secret (logical path, no data/metadata).
+  static pathFor(ownerUid, slug) {
+    return `shared/${ownerUid}/${slug}`;
+  }
+
+  path() {
+    return SharedSecret.pathFor(this.ownerUid, this.slug);
+  }
+
+  // Look up by slug (unique). Returns the row or null.
+  static async getBySlug(slug) {
+    const rows = await this.list({ where: { slug } });
+    return rows[0] || null;
+  }
+}
+
+module.exports = { SharedSecret };

nodejs/models/shared_secret_grant.js

@@ -0,0 +1,53 @@
+'use strict';
+
+// SharedSecretGrant — who can read a shared secret. Each row says "grantee
+// <granteeId> (a user uid or an app name) has <capability> on the shared secret
+// <secretId>".
+//
+// This table is the metadata/UX record of a grant. The actual ENFORCEMENT lives
+// in OpenBao ACL policy content: when a grant is created, vault_broker.js
+// recomputes the grantee's policy HCL (`user-<uid>` or `app-<name>`) to include
+// `read` on the exact shared path and rewrites it. Because OpenBao parses policy
+// content live at token use, the grant applies to the grantee's existing token
+// immediately (no re-mint). Revoking removes the rule and rewrites the policy.
+//
+// granteeType distinguishes the two principal kinds:
+//   'user' — a user uid → grantee's `user-<uid>` policy is edited
+//   'app'  — an app name → grantee's `app-<name>` policy is edited (downstream apps)
+// capability is currently always 'read' (grantees are read-only); the column is
+// a string so later capabilities could be added without a migration.
+//
+// No ORM auto-timestamp hook: route handlers stamp created_by/on + updated_by/on.
+// Uniqueness on (secretId, granteeType, granteeId) prevents duplicate grants.
+
+const { Model } = require('@simpleworkjs/orm');
+
+const GRANTEE_TYPES = ['user', 'app'];
+const CAPABILITIES = ['read'];
+
+class SharedSecretGrant extends Model {
+  static fields = {
+    id: { type: 'uuid', primaryKey: true },
+    // FK to SharedSecret.id.
+    secretId: { type: 'string', isRequired: true, min: 1 },
+    // 'user' (a uid) or 'app' (an app name) — which policy to edit.
+    granteeType: { type: 'string', isRequired: true, min: 1 },
+    // The grantee's uid (for 'user') or app name (for 'app').
+    granteeId: { type: 'string', isRequired: true, min: 1, max: 64 },
+    // Access level — 'read' today.
+    capability: { type: 'string', isRequired: true, default: 'read' },
+    // Audit stamps (set by the route handler, not by an ORM hook).
+    created_by: { type: 'string' },
+    created_on: { type: 'integer' },
+    updated_by: { type: 'string' },
+    updated_on: { type: 'integer' },
+  };
+
+  // All grants for a given grantee (user uid or app name). Used to rebuild the
+  // grantee's policy content so every granted shared path is present/absent.
+  static async listForGrantee(granteeType, granteeId) {
+    return this.list({ where: { granteeType, granteeId } });
+  }
+}
+
+module.exports = { SharedSecretGrant, GRANTEE_TYPES, CAPABILITIES };

nodejs/models/vault_app_token.js

@@ -0,0 +1,43 @@
+'use strict';
+
+// VaultAppToken — the ACCESSOR of an OpenBao token minted for an external app
+// from the vault UI (Apps tab), so sso can keep the token alive.
+//
+// The token itself is shown ONCE at mint and never stored (a stolen accessor
+// cannot authenticate — it can only look up, renew, or revoke its token, and
+// only the sso broker's policy grants those endpoints). App tokens are minted
+// through the sso-app role as PERIODIC tokens: they live forever, but only if
+// something renews them inside every period window. That something is sso's
+// renewal loop (vault_broker.startAppTokenRenewal), which walks these rows and
+// POSTs auth/token/renew-accessor on a timer — so a downstream app's credential
+// stays valid as long as sso itself is running, with no renewal code needed in
+// the downstream app.
+//
+// One row per app name: re-minting an app's token revokes the previous token
+// via its accessor (no zombie credentials) and replaces the row.
+
+const { Model } = require('@simpleworkjs/orm');
+
+class VaultAppToken extends Model {
+  static fields = {
+    id: { type: 'uuid', primaryKey: true },
+    // The external app's name — also its policy (app-<name>) and KV namespace
+    // (secret/apps/<name>/). Unique: one live token per app.
+    name: { type: 'string', isRequired: true, unique: true, min: 1, max: 64 },
+    // The minted token's accessor (renew/revoke handle, cannot authenticate).
+    accessor: { type: 'string', isRequired: true, max: 128 },
+    // Renewal bookkeeping, updated by the renewal loop.
+    lastRenewedAt: { type: 'integer' },
+    lastError: { type: 'text' },
+    // Audit stamps (set by the route handler, not by an ORM hook).
+    created_by: { type: 'string' },
+    created_on: { type: 'integer' },
+  };
+
+  static async getByName(name) {
+    const rows = await this.list({ where: { name } });
+    return rows[0] || null;
+  }
+}
+
+module.exports = { VaultAppToken };

nodejs/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "t42-sso-manager",
-  "version": "1.19.6",
+  "version": "1.28.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "t42-sso-manager",
-      "version": "1.19.6",
+      "version": "1.28.0",
       "license": "MIT",
       "dependencies": {
         "@fortawesome/fontawesome-free": "^7.3.0",
@@ -2344,9 +2344,9 @@
       }
     },
     "node_modules/brace-expansion": {
-      "version": "2.1.2",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.2.tgz",
-      "integrity": "sha512-w5JZcKgdhDOgOwm8H+KgbosopHMuGcl6qbulwjtz3SM7I7P3yW1eAjzMPLrIE+NQ9vjgANKHWeMHnrT0OXW1oA==",
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.4.tgz",
+      "integrity": "sha512-hGfVzPxthbf3+2yjg/RBs60cB0FhqBS/zvdV/4wn4/BmN0bNMMHPc4V/BbFieqf1TKAGGAHnY4eSjajCl0f2Xg==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^1.0.0"
@@ -4294,9 +4294,9 @@
       "license": "MIT"
     },
     "node_modules/ip-address": {
-      "version": "10.2.0",
-      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
-      "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
+      "version": "10.4.0",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.4.0.tgz",
+      "integrity": "sha512-oSK96Grm3aP6OrS263xVxbNDGVL7rzBtYdpGqlDG8iQdoenDoTs/nkki+DflYbAEE8Xl6o5YxhxlrKvI3nqKXQ==",
       "license": "MIT",
       "engines": {
         "node": ">= 12"
@@ -5966,16 +5966,16 @@
       }
     },
     "node_modules/nodemon/node_modules/brace-expansion": {
-      "version": "5.0.7",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.7.tgz",
-      "integrity": "sha512-7oFy703dxfY3/NLxC1fh2SUCQ0H9rmAY+5EpDVfXjUTTs+HEwR2nYaqLv+GWcTsumwxPfiz6CzCNkwXwBUwqCA==",
+      "version": "5.0.9",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz",
+      "integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^4.0.2"
       },
       "engines": {
-        "node": "18 || 20 || >=22"
+        "node": "20 || >=22"
       }
     },
     "node_modules/nodemon/node_modules/debug": {
@@ -7726,9 +7726,9 @@
       }
     },
     "node_modules/test-exclude/node_modules/brace-expansion": {
-      "version": "1.1.16",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.16.tgz",
-      "integrity": "sha512-IDw48K2/2kRkg9LdJxurvq3lV3aBgq0REY89duEqFRthjlPdXHKMj7EnQOXVckxzgisinf3nHfrcE2FufFLXMw==",
+      "version": "1.1.18",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
+      "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -7918,9 +7918,9 @@
       "license": "MIT"
     },
     "node_modules/undici": {
-      "version": "6.27.0",
-      "resolved": "https://registry.npmjs.org/undici/-/undici-6.27.0.tgz",
-      "integrity": "sha512-YmfV3YnEDzXRC5lZ2jWtWWHKGUm1zIt8AhesR1tens+HTNv+YZlN/dp6G727LOvMJ8xjP9Be7Y2Sdr96LDm+pg==",
+      "version": "6.28.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-6.28.0.tgz",
+      "integrity": "sha512-LIY910g9TI13YS95lrMFrs8Rm/u/irgHeTWoKCoteeJ04CUJ92eEfj0rVn+7VKMPBpUPiUoBKfhNyLI23EE/KA==",
       "license": "MIT",
       "optional": true,
       "engines": {

nodejs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "t42-sso-manager",
-  "version": "1.19.6",
+  "version": "1.28.0",
   "description": "A very simple LDAP management and SSO system",
   "author": [
     {

nodejs/plugins/discovery/nmap.js

@@ -32,10 +32,13 @@ module.exports = {
 
     return new Promise((resolve, reject) => {
       // OsAndPortScan requires root (for -O). NmapScan does a basic port scan (TCP connect if non-root).
-      const scan = new nmap.NmapScan(targetRange);
-      scan.command.push('-Pn');
-      scan.command.push('-F'); // fast scan, 100 top ports
-      scan.command.push('--min-rate', '100'); // speed up the scan
+      // Pass custom arguments in constructor so node-nmap includes them before spawning nmap process.
+      // -Pn: treat all hosts as online (skip ping/ARP host discovery which fails inside Docker containers NAT/bridge)
+      // -sT: TCP connect scan (unprivileged scan compatible with container environments)
+      // -F: fast scan (100 top ports)
+      // --min-rate 100: speed up scan rate
+      const customFlags = ['-Pn', '-sT', '-F', '--min-rate', '100'];
+      const scan = new nmap.NmapScan(targetRange, customFlags);
       
       if (config.log) config.log(`Starting nmap scan: ${scan.command.join(' ')}`);
 

nodejs/public/css/styles.css

@@ -3,6 +3,12 @@ nav.navbar{
 	padding-right: 1em;
 }
 
+/* Only the active top-nav link is bold + underlined; the username is plain. */
+.top-nav a.active{
+	font-weight: bold;
+	text-decoration: underline;
+}
+
 body {
 	display: flex;
 	flex-direction: column;

nodejs/public/lib/js/app-base.js

@@ -615,9 +615,10 @@ app.util = (function(app){
 // Reveal every .group-required-<cn> element the current user's groups entitle
 // them to. Elements carrying .group-required start hidden (styles.css), so a
 // user who is in no groups — or who isn't logged in — simply never sees them.
+// The synthetic 'login' group is special: it's true for any authenticated user.
 app.auth.applyGroupVisibility = function(user){
 	var groups = app.auth.groupCNs(user);
-	if(!groups.length) return;
+	var isLoggedIn = !!user;
 
 	var style = document.getElementById('group-required-rules');
 	if(!style){
@@ -636,6 +637,19 @@ app.auth.applyGroupVisibility = function(user){
 			// A group whose CN isn't a usable CSS identifier just gates nothing.
 		}
 	}
+
+	// The 'login' group is synthetic — it means "any authenticated user".
+	// Reveal .group-required-login for any logged-in user.
+	if(isLoggedIn){
+		try{
+			style.sheet.insertRule(
+				`.group-required-login { display: revert !important; }`,
+				style.sheet.cssRules.length
+			);
+		}catch(error){
+			// Ignore CSS escape errors.
+		}
+	}
 };
 
 $( document ).ready(async function(){

nodejs/public/resources/theta-agent/install.sh

@@ -0,0 +1,130 @@
+#!/bin/bash
+set -e
+
+# --- Configuration ---
+# In a real environment, these would be derived from the script's download URL
+# or passed as additional arguments. For now, we use the most recent release.
+BINARY_URL="${BINARY_URL:-}"
+CONFIG_DIR="/etc/theta42"
+CONFIG_FILE="$CONFIG_DIR/agent.yml"
+BIN_PATH="/usr/local/bin/theta-agent"
+SERVICE_FILE="/etc/systemd/system/theta-agent.service"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+log() { echo -e "${GREEN}[+]${NC} $1"; }
+error() { echo -e "${RED}[!]${NC} $1"; exit 1; }
+
+# 1. Root check
+if [ "$EUID" -ne 0 ]; then
+  error "This script must be run as root."
+fi
+
+# 2. Argument Parsing
+URL=""
+TOKEN=""
+B64_CONFIG=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --url)
+      URL="$2"
+      shift 2
+      ;;
+    --token)
+      TOKEN="$2"
+      shift 2
+      ;;
+    *)
+      B64_CONFIG="$1"
+      shift
+      ;;
+  esac
+done
+
+# Validation
+if [ -z "$B64_CONFIG" ] && [ -z "$URL" ] || [ -z "$B64_CONFIG" ] && [ -z "$TOKEN" ]; then
+  error "Missing required configuration. Either provide a base64 encoded config, or both --url and --token."
+  echo "Usage examples:"
+  echo "  sh install.sh \"BASE64_CONFIG\""
+  echo "  sh install.sh --url \"https://sso.local\" --token \"secret-token\""
+  exit 1
+fi
+
+# 3. Resolve binary URL dynamically if not specified
+if [ -z "$BINARY_URL" ]; then
+  if [ -n "$URL" ]; then
+    BINARY_URL="${URL%/}/resources/theta-agent/theta-agent-linux-amd64"
+  elif [ -n "$B64_CONFIG" ]; then
+    EXTRACTED_URL=$(echo "$B64_CONFIG" | base64 -d 2>/dev/null | grep -E '^\s*server_url:' | awk -F'"' '{print $2}' | tr -d ' ' || true)
+    if [ -n "$EXTRACTED_URL" ]; then
+      HTTP_URL=$(echo "$EXTRACTED_URL" | sed -e 's/^wss:\/\//https:\/\//' -e 's/^ws:\/\//http:\/\//')
+      BINARY_URL="${HTTP_URL%/}/resources/theta-agent/theta-agent-linux-amd64"
+    fi
+  fi
+fi
+if [ -z "$BINARY_URL" ]; then
+  BINARY_URL="https://sso.example.com/resources/theta-agent/theta-agent-linux-amd64"
+fi
+
+log "Downloading binary from $BINARY_URL..."
+curl -fsSL "$BINARY_URL" -o "$BIN_PATH" || error "Failed to download binary."
+chmod +x "$BIN_PATH"
+
+# 4. Setup configuration
+log "Preparing configuration directory $CONFIG_DIR..."
+mkdir -p "$CONFIG_DIR"
+chmod 755 "$CONFIG_DIR"
+
+if [ -n "$B64_CONFIG" ]; then
+  log "Decoding and writing configuration from base64..."
+  echo "$B64_CONFIG" | base64 -d > "$CONFIG_FILE" || error "Failed to decode base64 configuration."
+else
+  log "Generating minimal configuration from arguments..."
+  # Create a minimal yaml with the provided URL and Token
+  cat <<EOF > "$CONFIG_FILE"
+server_url: "$URL"
+auth_token: "$TOKEN"
+location: "unknown"
+capabilities:
+  telemetry: true
+  configure_ldap: false
+  reboot: false
+  service_control: []
+  arbitrary_bash: false
+EOF
+fi
+chmod 600 "$CONFIG_FILE"
+
+# 5. Setup systemd service
+log "Creating systemd service unit..."
+cat <<EOF > "$SERVICE_FILE"
+[Unit]
+Description=Theta Agent Unified Endpoint Management
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=$BIN_PATH
+Restart=always
+RestartSec=5
+StandardOutput=syslog
+StandardError=syslog
+SyslogIdentifier=theta-agent
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# 6. Start the agent
+log "Enabling and starting Theta Agent..."
+systemctl daemon-reload
+systemctl enable theta-agent
+systemctl start theta-agent
+
+log "Theta Agent installation complete!"
+log "Verify status with: systemctl status theta-agent"
+log "Check logs with: journalctl -u theta-agent -f"

nodejs/routes/api_agent.js

@@ -1,53 +1,128 @@
 'use strict';
 
-module.exports = function initAgentWebSockets(app) {
-    if (!app.wss) {
-        console.warn("WebSocket server for agents is not initialized.");
-        return;
+const express = require('express');
+const middleware = require('../middleware/auth');
+const permission = require('../utils/permission');
+const agentManager = require('../utils/agent_manager');
+
+const ADMIN_GROUPS = ['app_sso_admin', 'app_super_admin', 'app_sso_directory_admin'];
+
+// ── REST API (mounted synchronously in app.js, BEFORE the 404 catch-all) ──
+// This is a plain Express Router exported directly so app.js can
+// `app.use('/api/agent', require('./routes/api_agent'))` at require time. It
+// must NOT be mounted from the onListen hook (which runs after the 404
+// catch-all is already on the stack): a router registered behind that terminal
+// handler would make every /api/agent/* request 404, no matter the WS server
+// state. The WebSocket handler is separate (initAgentWebSockets below) and is
+// the only part that needs the post-listen onListen hook.
+const router = express.Router();
+
+// The agent WebSocket (/api/agent/ws) is handled by the raw `wss` upgrade server
+// in bin/www with its own ?token= auth — unaffected by the express middleware
+// here. These REST routes are admin-facing, so they're auth + admin gated.
+router.use(middleware.auth);
+router.use(async (req, res, next) => {
+  try {
+    await permission.byGroup(req.user, ADMIN_GROUPS);
+    next();
+  } catch (err) {
+    if (err && (err.status === 401 || err.name === 'Insufficient Permission')) {
+      return res.status(403).json({ status: 'error', message: 'admin only' });
+    }
+    next(err);
+  }
+});
+
+router.get('/nodes', (req, res) => {
+  res.json({
+    status: 'ok',
+    agents: agentManager.getConnectedAgents(),
+    publicKey: agentManager.publicKeyPem
+  });
+});
+
+router.post('/nodes/:token/command', (req, res) => {
+  const { token } = req.params;
+  const { command, payload, isHighRisk } = req.body;
+
+  if (!command) {
+    return res.status(400).json({ status: 'error', message: 'Command type is required' });
+  }
+
+  try {
+    const HIGH_RISK_COMMANDS = ['reboot', 'service_restart', 'configure_ldap', 'arbitrary_bash', 'update_binary'];
+    const requiresSigning = isHighRisk || HIGH_RISK_COMMANDS.includes(command);
+
+    const msg = agentManager.sendCommand(token, command, payload || {}, requiresSigning);
+    res.json({ status: 'ok', sentMessage: msg });
+  } catch (err) {
+    res.status(400).json({ status: 'error', message: err.message });
+  }
+});
+
+module.exports = router;
+module.exports.initAgentWebSockets = function initAgentWebSockets(app) {
+  // WebSocket handler only needs the WS server; runs from the onListen hook.
+  if (!app.wss) return;
+  app.wss.on('connection', (ws, req) => {
+    const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+    const token = url.searchParams.get('token') || req.headers['authorization'];
+
+    if (!token) {
+      ws.close(4001, 'Unauthorized: Missing token');
+      return;
     }
 
-    app.wss.on('connection', (ws, req) => {
-        // Parse the token from query param or header (e.g. ?token=XYZ)
-        // For the beta, we will just accept it if a token is present.
-        const url = new URL(req.url, `http://${req.headers.host}`);
-        const token = url.searchParams.get('token') || req.headers['authorization'];
+    const remoteAddr = req.socket.remoteAddress;
+    console.log(`[Theta Agent] Agent connected from ${remoteAddr} with token ${token.substring(0, 8)}...`);
 
-        if (!token) {
-            ws.close(4001, 'Unauthorized: Missing token');
-            return;
+    agentManager.registerAgent(token, ws, remoteAddr);
+
+    ws.on('message', (message) => {
+      try {
+        const data = JSON.parse(message);
+        if (!data || typeof data.type !== 'string') return;
+
+        const payload = data.payload || {};
+
+        switch (data.type) {
+          case 'discovery':
+            agentManager.handleDiscovery(token, payload);
+            if (app.io) app.io.emit('agent.discovery', { token, payload });
+            break;
+          case 'telemetry':
+            agentManager.handleTelemetry(token, payload);
+            if (app.io) app.io.emit('agent.telemetry', { token, payload });
+            break;
+          case 'heartbeat':
+            agentManager.handleHeartbeat(token, payload, ws);
+            break;
+          case 'response':
+            agentManager.handleResponse(token, payload);
+            if (app.io) app.io.emit('agent.response', { token, payload });
+            break;
+          default:
+            console.log(`[Theta Agent] Received message type '${data.type}' from ${token}`);
         }
-
-        console.log(`[Theta Agent] Agent connected from ${req.socket.remoteAddress}`);
-
-        ws.on('message', (message) => {
-            try {
-                const data = JSON.parse(message);
-                
-                // Example handling incoming telemetry
-                if (data.type === 'telemetry') {
-                    // Send to discovery service or log
-                    // console.log(`[Theta Agent] Received telemetry from ${data.host}`);
-                    
-                    // We can publish it to the event bus for the UI
-                    if(app.contoller && app.contoller.ps) {
-                        app.contoller.ps.publish('agent.telemetry', data);
-                    }
-                }
-            } catch (err) {
-                console.error("[Theta Agent] Error parsing message:", err);
-            }
-        });
-
-        ws.on('close', () => {
-            console.log(`[Theta Agent] Agent disconnected`);
-        });
-
-        // Example: Send a welcome config payload to the agent
-        ws.send(JSON.stringify({
-            type: 'config',
-            payload: {
-                message: 'Welcome to SSO Manager C2'
-            }
-        }));
+      } catch (err) {
+        console.error("[Theta Agent] Error parsing message:", err);
+      }
     });
+
+    ws.on('close', () => {
+      console.log(`[Theta Agent] Agent disconnected (${token})`);
+      agentManager.unregisterAgent(token, ws);
+    });
+
+    // Send initial welcome/config payload
+    try {
+      ws.send(JSON.stringify({
+        type: 'config',
+        payload: {
+          message: 'Connected to SSO Manager C2',
+          protocol_version: '1.1.0'
+        }
+      }));
+    } catch (e) {}
+  });
 };

nodejs/routes/api_conf.js

@@ -128,4 +128,67 @@ router.post('/proxy', async (req, res, next) => {
   }
 });
 
+// Send a test email to verify SMTP configuration
+router.post('/test-email', async (req, res, next) => {
+  try {
+    const { to, subject, body } = req.body || {};
+    if (!to) {
+      return res.status(400).json({ error: 'Recipient email address is required' });
+    }
+
+    // Use the email model to send the test message
+    const Email = require('../models/email');
+    const testSubject = subject || 'SSO Manager Test Email';
+    const testBody = body || `<p>This is a test email from SSO Manager.</p><p>If you received this, your SMTP configuration is working correctly.</p><p>Sent at: ${new Date().toISOString()}</p>`;
+
+    await Email.send(to, testSubject, testBody);
+    res.json({ success: true, message: `Test email sent to ${to}` });
+  } catch(err) {
+    next(err);
+  }
+});
+
+// Send a test SMS to verify VoIP.ms configuration
+router.post('/test-sms', async (req, res, next) => {
+  try {
+    const { to, message } = req.body || {};
+    if (!to) {
+      return res.status(400).json({ error: 'Recipient phone number is required' });
+    }
+
+    const voipmsConf = conf.voipms || {};
+    if (!voipmsConf.username || !voipmsConf.password || !voipmsConf.did) {
+      return res.status(400).json({ error: 'VoIP.ms credentials not configured. Please configure username, DID, and password in the SMS tab.' });
+    }
+
+    const testMessage = message || `SSO Manager Test SMS: This is a test message from ${conf.name}. If you received this, your VoIP.ms configuration is working correctly.`;
+
+    // VoIP.ms SMS API endpoint
+    const voipmsApiUrl = 'https://api.voip.ms/v1.0';
+    const authHeader = Buffer.from(`${voipmsConf.username}:${voipmsConf.password}`).toString('base64');
+
+    const response = await fetch(`${voipmsApiUrl}/sms/send`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Basic ${authHeader}`,
+        'Content-Type': 'application/x-www-form-urlencoded'
+      },
+      body: new URLSearchParams({
+        did: voipmsConf.did,
+        to: to,
+        message: testMessage
+      })
+    });
+
+    const result = await response.json();
+    if (result.status === 'success') {
+      res.json({ success: true, message: `Test SMS sent to ${to}` });
+    } else {
+      res.status(400).json({ error: `VoIP.ms API error: ${result.message || 'Unknown error'}` });
+    }
+  } catch(err) {
+    next(err);
+  }
+});
+
 module.exports = router;

nodejs/routes/api_directory_admin.js

@@ -8,10 +8,11 @@ const { cnFromDn } = require('../utils/user_groups');
 const { projectResources } = require('@simpleworkjs/directory-schema');
 
 const SUPER_ADMIN_GROUP = permission.SUPER_ADMIN_GROUP;
+const groups = require('../utils/groups');
 
 // Make `childCn` a member of `parentCn`, i.e. everyone in the child is
 // transitively in the parent. Idempotent and non-fatal: "already a member" is
-// the goal state, and a missing group (e.g. app_super_admin absent on a
+// the goal state, and a missing group (e.g. god_admin absent on a
 // directory seeded by an older entrypoint) is a reason to skip, not to fail the
 // caller's real work.
 async function nestGroup(childCn, parentCn) {
@@ -29,6 +30,160 @@ async function nestGroup(childCn, parentCn) {
   }
 }
 
+// ── Group-model provisioning (docs/GROUPS.md) ───────────────────────────────
+// The directory is the single place groups are created, as a projection of the
+// resource graph. These helpers materialize the group-inheritance lattice for
+// a resource so it exists in LDAP as well as in the resolver (utils/groups.js).
+// All of them are idempotent, so calling them again for a resource a newer
+// release is backfilling is a no-op.
+
+// Map a directory resource kind onto a group-model kind (GROUPS.md §2).
+// host -> host; service -> app (services/consoles are the group model's "apps");
+// site gets site-level groups (handled separately); oauth/container get no
+// per-resource groups (oauth clients hang off their owning service).
+function groupKind(resource) {
+  if (resource.kind === 'host') return 'host';
+  if (resource.kind === 'service') return 'app';
+  return null;
+}
+
+// Create a groupOfNames if it doesn't already exist. Idempotent; `ownerDn`
+// seeds the mandatory first member. Returns true when created.
+async function ensureGroup(name, ownerDn, description) {
+  try {
+    await Group.add({ name, owner: ownerDn, description });
+    return true;
+  } catch (err) {
+    if (err.name !== 'EntryAlreadyExistsError' && err.code !== 68) {
+      console.error(`ensureGroup: failed to create ${name}:`, err);
+    }
+    return false;
+  }
+}
+
+// Link a group to a resource only if that link doesn't already exist. The
+// ResourceGroup table has no unique constraint on (resourceId, groupCn), so a
+// naive create on every Directory self-heal (which runs ensureSiteGroups /
+// provisionResourceGroups on each load) was accumulating duplicate links -- the
+// "groups appear 3x under a resource" bug. Always check first.
+async function ensureResourceGroup(resourceId, groupCn, accessLevel) {
+  const existing = await ResourceGroup.list({ where: { resourceId, groupCn } });
+  if (existing.length) return existing[0];
+  return ResourceGroup.create({ resourceId, groupCn, accessLevel });
+}
+
+// Provision the site-level groups + the aggregates the per-resource groups nest
+// into. Idempotent -- called on every directory list so a site seeded by an
+// older release gets its groups without a rebuild:
+//
+//   god_admin -> {site}_super_admin
+//   {site}_super_admin -> {site}_hosts_admin, {site}_apps_admin
+//   {site}_hosts_admin -> {site}_hosts_access ; {site}_apps_admin -> {site}_apps_access
+//
+// `{site}_everyone` is created for completeness; it has implicit membership and
+// is granted to a resource as a grantee, never enumerated.
+async function ensureSiteGroups(siteSlug, ownerDn, siteName, siteResourceId) {
+  if (!siteSlug) return;
+
+  // Link a site group to the site resource (so it shows + is member-manageable
+  // on the site's modal). Idempotent. Admin groups link as owner; access/meta
+  // groups as member.
+  const link = async (cn, isAdmin) => {
+    if (!siteResourceId) return;
+    await ensureResourceGroup(siteResourceId, cn, isAdmin ? 'owner' : 'member');
+  };
+
+  const sAdmin = groups.siteSuperAdminCns(siteSlug);
+  await ensureGroup(sAdmin, ownerDn, `Site admin for ${siteName || siteSlug}`);
+  await link(sAdmin, true);
+  // The kind-scoped aggregates are CREATED here (per-resource groups nest into
+  // them), but are NOT linked to the site resource: a site carries only the god
+  // and site-wide groups (S_super_admin, S_everyone), per the user's model. The
+  // aggregates have no modal home; site-wide access is granted via S_super_admin
+  // and per-resource access via the host/app groups.
+  for (const kind of ['host', 'app']) {
+    await ensureGroup(groups.aggregateGroupCns(siteSlug, kind, 'admin'), ownerDn, `Admin on all ${kind}s at ${siteSlug}`);
+    await ensureGroup(groups.aggregateGroupCns(siteSlug, kind, 'access'), ownerDn, `Access to all ${kind}s at ${siteSlug}`);
+  }
+  await ensureGroup(groups.siteEveryoneCns(siteSlug), ownerDn, `All users at ${siteSlug}`);
+  await link(groups.siteEveryoneCns(siteSlug), false);
+  // god_admin is the global group; surface it on the site modal so its members
+  // can be managed from the Directory (it has no home on a single resource).
+  await link(groups.GOD_ADMIN, true);
+
+  // Wire the lattice as nesting so LDAP-level consumers (SSSD, sudo, anything
+  // binding directly) resolve it transitively, not just utils/permission.js.
+  // nestGroup(child, parent) makes child a member of parent -- membership flows
+  // child -> parent ("up"), so a group's members inherit what its parents hold.
+  await nestGroup(groups.GOD_ADMIN, sAdmin); // god admins are site admins everywhere
+  for (const kind of ['host', 'app']) {
+    const aggAdmin = groups.aggregateGroupCns(siteSlug, kind, 'admin');
+    const aggAccess = groups.aggregateGroupCns(siteSlug, kind, 'access');
+    await nestGroup(sAdmin, aggAdmin);        // site admins administer all hosts/apps
+    await nestGroup(aggAdmin, aggAccess);     // site admin implies site access
+  }
+}
+
+// Provision the per-resource groups for a host/app and nest them into the site
+// aggregates (so a site/aggregate admin reaches this resource by membership).
+// Group names follow docs/GROUPS.md §2: `{site}_{kind}_{nameSlug}_{level}` where
+// nameSlug is the resource name with the kind prefix stripped (`host_theta-env` ->
+// `theta-env`). `kind` (host/app) both goes in the name and selects the aggregate:
+//
+//   {site}_{kind}_{slug}_admin  -> {site}_{kind}_{slug}_access
+//   {site}_{kind}_{slug}_admin  -> {site}_{kind}s_admin    (aggregate)
+//   {site}_{kind}_{slug}_access -> {site}_{kind}s_access   (aggregate)
+//   god_admin                   -> {site}_{kind}_{slug}_admin  (global super admin)
+async function provisionResourceGroups(resource, kind, siteSlug, ownerDn) {
+  const nameSlug = groups.resourceNameSlug(resource.slug);
+  const accessCn = groups.resourceGroupCns(siteSlug, kind, nameSlug, 'access');
+  const adminCn = groups.resourceGroupCns(siteSlug, kind, nameSlug, 'admin');
+
+  await ensureGroup(accessCn, ownerDn, `Access group for ${resource.name}`);
+  await ensureGroup(adminCn, ownerDn, `Admin group for ${resource.name}`);
+
+  // Link both groups to the resource so the Directory can show/revoke them.
+  await ensureResourceGroup(resource.id, accessCn, 'member');
+  await ensureResourceGroup(resource.id, adminCn, 'owner');
+
+  await nestGroup(adminCn, accessCn); // administering implies using
+  await nestGroup(adminCn, groups.aggregateGroupCns(siteSlug, kind, 'admin'));  // aggregate admin reaches this resource
+  await nestGroup(accessCn, groups.aggregateGroupCns(siteSlug, kind, 'access')); // aggregate access reaches this resource
+  await nestGroup(SUPER_ADMIN_GROUP, adminCn); // global super admin
+}
+
+// The group CNs it is valid to associate with a given resource (docs/GROUPS.md
+// §2/§3). This is what "force the correct naming convention" means: a group
+// linked to a resource must be one that parses for consumers -- the resource's
+// own specific groups, its site's aggregates, site-level groups, or the global
+// god_admin. Returns a Set of the fixed valid CNs plus a RegExp for opaque
+// capability groups following the same shapes.
+function validGroupCnsForResource(resource, siteSlug) {
+  const valid = new Set();
+  // A site resource only carries god_admin (added by the route) + the site-wide
+  // groups (S_super_admin, S_everyone). The kind-scoped host/app aggregates and
+  // specific groups belong to host/app resources, not to the site.
+  if (resource.kind === 'site') {
+    valid.add(groups.siteSuperAdminCns(siteSlug));
+    valid.add(groups.siteEveryoneCns(siteSlug));
+    return { valid, capRe: new RegExp(`^${siteSlug}_super_admin$|^${siteSlug}_everyone$`) };
+  }
+  const kind = groupKind(resource); // 'host'|'app'|null
+  if (kind) {
+    const nameSlug = groups.resourceNameSlug(resource.slug);
+    valid.add(groups.resourceGroupCns(siteSlug, kind, nameSlug, 'admin'));
+    valid.add(groups.resourceGroupCns(siteSlug, kind, nameSlug, 'access'));
+    valid.add(groups.aggregateGroupCns(siteSlug, kind, 'admin'));
+    valid.add(groups.aggregateGroupCns(siteSlug, kind, 'access'));
+    valid.add(groups.siteSuperAdminCns(siteSlug));
+    valid.add(groups.siteEveryoneCns(siteSlug));
+    return { valid, capRe: new RegExp(`^${siteSlug}_${kind}_${nameSlug}_[a-z0-9-]+$|^${siteSlug}_${kind}s_[a-z0-9-]+$`) };
+  }
+  // oauth/container etc. — only the global god_admin makes sense to pin here.
+  valid.add(groups.siteSuperAdminCns(siteSlug));
+  return { valid, capRe: null };
+}
+
 // Require the admin group
 router.use(async (req, res, next) => {
   try {
@@ -50,6 +205,36 @@ router.get('/resources', async (req, res, next) => {
     });
     // Even admins never receive secret metadata (e.g. client_secret_hash) over
     // the wire; projectResources strips it unconditionally.
+
+    // Self-heal the group model (docs/GROUPS.md): ensure every site has its
+    // site-level groups (S_super_admin, S_hosts_*, S_apps_*, S_everyone) + the
+    // aggregates, and every host/app resource has its per-resource groups nested
+    // into them. Idempotent, so this is a cheap no-op once present -- it's what
+    // backfills a directory seeded by an older release without a rebuild.
+    // Never fails the list.
+    const sites = resources.filter(r => r.kind === 'site');
+    await Promise.all(sites.map(site =>
+      ensureSiteGroups(site.slug, req.user.dn, site.name, site.id)
+        .catch(err => console.error(`ensureSiteGroups(${site.slug}) failed:`, err.message))
+    ));
+    const siteByResource = new Map();
+    for (const site of sites) siteByResource.set(site.id, site.slug);
+    const siteOf = async (r) => {
+      const direct = siteByResource.get(r.id);
+      if (direct) return direct;
+      // findAncestorSiteSlug returns the site's full slug (`site_local`) -- the
+      // group-model builders take it verbatim, so do NOT strip the `site_` prefix.
+      return await Resource.findAncestorSiteSlug(r.id).catch(() => null);
+    };
+    await Promise.all(resources.map(async (r) => {
+      const gKind = groupKind(r);
+      if (!gKind) return;
+      const siteSlug = await siteOf(r);
+      if (!siteSlug) return;
+      await provisionResourceGroups(r, gKind, siteSlug, req.user.dn)
+        .catch(err => console.error(`provisionResourceGroups(${r.slug}) failed:`, err.message));
+    }));
+
     res.json({ results: projectResources(resources, { fullMetadata: true }) });
   } catch (err) { next(err); }
 });
@@ -95,46 +280,25 @@ router.post('/resources', async (req, res, next) => {
       await ResourceEdge.create({ parentId: req.body.hostId, childId: r.id, relation: r.kind === 'oauth' ? 'oauth' : 'hosts' });
     }
 
-    if (r.kind === 'host' || r.kind === 'service') {
-      const siteSlug = await Resource.findAncestorSiteSlug(r.id);
-      const groupCn = suffix => (siteSlug ? `${siteSlug}_${r.slug}_${suffix}` : `${r.slug}_${suffix}`);
-
-      const createGroup = async (suffix, accessLevel) => {
-        const cn = groupCn(suffix);
-        try {
-          await Group.add({
-            name: cn,
-            owner: req.user.dn,
-            description: `${suffix === 'admin' ? 'Admin' : 'Access'} group for ${r.name}`
-          });
-        } catch (err) {
-          if (err.name !== 'EntryAlreadyExistsError' && err.code !== 68) {
-            console.error(`Failed to create LDAP group ${cn}:`, err);
-          }
-        }
-        try {
-          await ResourceGroup.create({ resourceId: r.id, groupCn: cn, accessLevel });
-        } catch(err) { /* ignore duplicate links */ }
-      };
-      await createGroup('access', 'member');
-      await createGroup('admin', 'owner');
-
-      // Wire up the two standing relationships every resource has, as nesting
-      // rather than as membership that has to be maintained per resource:
-      //
-      //   app_super_admin -> <slug>_admin   cross-app super admins administer
-      //                                     every resource, automatically
-      //   <slug>_admin    -> <slug>_access  administering something implies
-      //                                     being able to use it
-      //
-      // Before nesting, both of these could only be expressed by adding every
-      // super admin to every new group by hand -- which nobody does, so the
-      // groups drifted. A failure here must not fail resource creation: the
-      // resource and its groups already exist and the nesting is repairable.
-      await nestGroup(groupCn('admin'), groupCn('access'));
-      await nestGroup(SUPER_ADMIN_GROUP, groupCn('admin'));
+    // ── Group provisioning (docs/GROUPS.md) ───────────────────────────────
+    // Materialize the group-model for the new resource. Site resources get the
+    // site-level groups; host/app resources get their per-resource groups nested
+    // into the site aggregates. Idempotent -- safe for a resource created by an
+    // older release. A provisioning failure must not fail resource creation: the
+    // resource already exists and the groups are repairable (re-run ensures them).
+    //
+    // `siteSlug` is the site resource's slug verbatim (`site_local`) -- the
+    // group-model builders treat it as opaque (docs/GROUPS.md §3) and re-apply
+    // the kind prefix themselves.
+    const gKind = groupKind(r);
+    const ancestorSite = await Resource.findAncestorSiteSlug(r.id);
+    if (r.kind === 'site') {
+      await ensureSiteGroups(r.slug, req.user.dn, r.name, r.id);
+    } else if (gKind && ancestorSite) {
+      await ensureSiteGroups(ancestorSite, req.user.dn, r.name); // backfill site tier if missing
+      await provisionResourceGroups(r, gKind, ancestorSite, req.user.dn);
     }
-    
+
     res.json({ results: r });
   } catch (err) {
     if (err.name === 'SequelizeUniqueConstraintError') {
@@ -265,7 +429,29 @@ router.get('/groups', async (req, res, next) => {
 
 router.post('/groups', async (req, res, next) => {
   try {
-    const g = await ResourceGroup.create(req.body);
+    const { resourceId, groupCn } = req.body;
+    if (!resourceId || !groupCn) return res.status(400).json({ error: 'resourceId and groupCn are required' });
+
+    // Enforce the group-model naming convention (docs/GROUPS.md §3). The CN must
+    // be a valid group for this resource; reject free-form names so the groups
+    // consumers read are always parseable. god_admin is always allowed (it is
+    // the global group and is managed from a site's modal).
+    const resource = await Resource.get(resourceId);
+    // Full site slug verbatim (`site_local`) -- the builders take it as-is. A
+    // site resource's own slug is its site; a host/app uses its ancestor site.
+    const siteSlug = resource && resource.kind === 'site'
+      ? resource.slug
+      : await Resource.findAncestorSiteSlug(resourceId);
+    if (resource && siteSlug && groupCn !== groups.GOD_ADMIN) {
+      const { valid, capRe } = validGroupCnsForResource(resource, siteSlug);
+      if (!valid.has(groupCn) && !(capRe && capRe.test(groupCn))) {
+        const err = new Error(`"${groupCn}" is not a valid group for this ${resource.kind}. Use the resource's own groups, a site aggregate, a site-level group, or god_admin (e.g. ${[...valid].join(', ')}).`);
+        err.status = 400;
+        throw err;
+      }
+    }
+
+    const g = await ensureResourceGroup(req.body.resourceId, groupCn, req.body.accessLevel);
     res.json({ results: g });
   } catch (err) { next(err); }
 });
@@ -313,7 +499,7 @@ router.get('/access-summary', async (req, res, next) => {
       //
       // Counts come from the transitive closure, not from `member`. Reading the
       // attribute would report only who is listed on the group, missing anyone
-      // who reaches it through a nested group -- and since app_super_admin is
+      // who reaches it through a nested group -- and since god_admin is
       // nested into every resource's _admin group, that is not an edge case.
       let members = [];
       if (group) {

nodejs/routes/api_shared_secrets.js

@@ -0,0 +1,213 @@
+'use strict';
+
+// Shared-secrets API.
+//
+// A shared secret is metadata in the DB (SharedSecret + SharedSecretGrant) with
+// its DATA in OpenBao at secret/shared/<ownerUid>/<slug> (KV-v2). The owner has
+// full R/W/list on their own secret/shared/<ownerUid>/* subtree; each grantee's
+// OpenBao policy content is edited to add read on the exact shared path (see
+// vault_broker.js grantSharedSecret/revokeSharedSecret). Enforcement is entirely
+// the OpenBao ACL — the broker's policy reconciliation makes a grant effective
+// immediately, with no token re-mint.
+//
+// Reads of the secret DATA are intentionally NOT proxied here: the UI fetches
+// them through the existing /api/vault proxy using the requester's own session
+// token, so OpenBao ACL enforces read access per-request. This router handles
+// metadata CRUD + grant management; KV writes (create/update/delete) are made
+// server-side using the acting user's scoped token.
+
+const express = require('express');
+const baoConf = require('@simpleworkjs/bao-conf');
+const permission = require('../utils/permission');
+const { SharedSecret } = require('../models/shared_secret');
+const { SharedSecretGrant } = require('../models/shared_secret_grant');
+const vaultBroker = require('../utils/vault_broker');
+
+const ADMIN_GROUPS = ['app_sso_admin', 'app_super_admin', 'app_sso_directory_admin'];
+// Allow hyphens AND underscores (matching the plugin-instance slug convention);
+// only reject values that can't be a sane secret path segment (spaces, slashes,
+// leading non-alnum, too long).
+const SLUG_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+const router = express.Router();
+
+// Machine/service tokens cannot manage shared secrets (mirrors scopeGuard on the
+// /api/vault proxy — personal, per-user secret management only).
+router.use((req, res, next) => {
+	if (req.user && req.user.isMachine) {
+		return res.status(403).json({ error: 'machine tokens cannot manage shared secrets' });
+	}
+	next();
+});
+
+async function isAdmin(user) {
+	try { await permission.byGroup(user, ADMIN_GROUPS); return true; }
+	catch (e) { return false; }
+}
+
+// Scoped OpenBao token for an actor, used for server-side KV writes. Owner uses
+// their own token (R/W on secret/shared/<ownerUid>/*); an admin uses the
+// sso-admin token (R/W on secret/*).
+async function actorToken(user, ownerUid) {
+	if (user.uid === ownerUid) return vaultBroker.getOrCreateUserToken(ownerUid);
+	if (await isAdmin(user)) return vaultBroker.getOrCreateAdminToken(user.uid);
+	return null;
+}
+
+// Does this user manage the given shared secret? Owner or admin.
+async function canManage(user, secret) {
+	if (user.uid === secret.ownerUid) return true;
+	return isAdmin(user);
+}
+
+async function loadSecret(req, res) {
+	const secret = await SharedSecret.get(req.params.id);
+	if (!secret) { res.status(404).json({ error: 'not found' }); return null; }
+	return secret;
+}
+
+// ── List: mine + shared-with-me ─────────────────────────────────────────────
+router.get('/', async (req, res, next) => {
+	try {
+		const uid = req.user.uid;
+		const mine = await SharedSecret.list({ where: { ownerUid: uid } });
+		const grants = await SharedSecretGrant.listForGrantee('user', uid);
+		const granteeSecretIds = [...new Set(grants.map(g => g.secretId))];
+		const granted = granteeSecretIds.length
+			? await SharedSecret.list({ where: { id: { in: granteeSecretIds } } }) : [];
+		const byId = new Map(mine.map(s => [s.id, { role: 'owner', ...s }]));
+		for (const g of granted) {
+			if (byId.has(g.id)) continue; // already owner
+			byId.set(g.id, { role: 'grantee', ...g });
+		}
+		// The `{ role, ...s }` spread above copies only own properties, so the
+		// instance method `path()` is dropped -- call the static builder instead.
+		res.json({ items: [...byId.values()].map(s => ({ id: s.id, slug: s.slug, ownerUid: s.ownerUid, description: s.description, path: SharedSecret.pathFor(s.ownerUid, s.slug), role: s.role })) });
+	} catch (e) { next(e); }
+});
+
+// ── Create ──────────────────────────────────────────────────────────────────
+router.post('/', async (req, res, next) => {
+	try {
+		const uid = req.user.uid;
+		const slug = String(req.body.slug || '').trim().toLowerCase();
+		if (!SLUG_RE.test(slug)) return res.status(400).json({ error: 'slug must be lowercase letters/digits/hyphens/underscores, 1-64 chars' });
+		const description = String(req.body.description || '').trim();
+		const data = (req.body.data && typeof req.body.data === 'object') ? req.body.data : {};
+
+		if (await SharedSecret.getBySlug(slug)) {
+			return res.status(409).json({ error: `a shared secret named '${slug}' already exists` });
+		}
+		const token = await actorToken(req.user, uid);
+		if (!token) return res.status(403).json({ error: 'not allowed' });
+		const path = SharedSecret.pathFor(uid, slug);
+		await baoConf.set(path, data, { token });
+
+		const secret = await SharedSecret.create({
+			slug, ownerUid: uid, description,
+			created_by: uid, created_on: Date.now(), updated_by: uid, updated_on: Date.now(),
+		});
+		res.status(201).json({ id: secret.id, slug, ownerUid: uid, description, path, role: 'owner' });
+	} catch (e) { next(e); }
+});
+
+// ── Detail (metadata; data is read via /api/vault proxy) ────────────────────
+router.get('/:id', async (req, res, next) => {
+	try {
+		const secret = await loadSecret(req, res);
+		if (!secret) return;
+		const uid = req.user.uid;
+		const admin = await isAdmin(req.user);
+		const grantee = (await SharedSecretGrant.listForGrantee('user', uid)).some(g => g.secretId === secret.id);
+		if (!admin && uid !== secret.ownerUid && !grantee) return res.status(403).json({ error: 'not shared with you' });
+		const grants = await SharedSecretGrant.list({ where: { secretId: secret.id } });
+		res.json({ id: secret.id, slug: secret.slug, ownerUid: secret.ownerUid, description: secret.description, path: secret.path(), role: uid === secret.ownerUid ? 'owner' : (admin ? 'admin' : 'grantee'), grants: grants.map(g => ({ id: g.id, granteeType: g.granteeType, granteeId: g.granteeId, capability: g.capability })) });
+	} catch (e) { next(e); }
+});
+
+// ── Update data / description ───────────────────────────────────────────────
+router.put('/:id', async (req, res, next) => {
+	try {
+		const secret = await loadSecret(req, res);
+		if (!secret) return;
+		if (!(await canManage(req.user, secret))) return res.status(403).json({ error: 'only the owner (or admin) can edit a shared secret' });
+		const token = await actorToken(req.user, secret.ownerUid);
+		const update = {};
+		if (req.body && typeof req.body.data === 'object') {
+			await baoConf.set(secret.path(), req.body.data, { token });
+		}
+		if (req.body && req.body.description !== undefined) {
+			update.description = String(req.body.description).trim();
+		}
+		if (Object.keys(update).length) {
+			update.updated_by = req.user.uid;
+			update.updated_on = Date.now();
+			await secret.update(update);
+		}
+		res.json({ id: secret.id, slug: secret.slug, ownerUid: secret.ownerUid, description: secret.description, path: secret.path() });
+	} catch (e) { next(e); }
+});
+
+// ── Delete (KV + DB row + all grants) ───────────────────────────────────────
+router.delete('/:id', async (req, res, next) => {
+	try {
+		const secret = await loadSecret(req, res);
+		if (!secret) return;
+		if (!(await canManage(req.user, secret))) return res.status(403).json({ error: 'only the owner (or admin) can delete a shared secret' });
+		const token = await actorToken(req.user, secret.ownerUid);
+		// Revoke all grants first so grantees' policies drop the path.
+		const grants = await SharedSecretGrant.list({ where: { secretId: secret.id } });
+		for (const g of grants) await vaultBroker.revokeSharedSecret(g.id, req.user.uid);
+		// Delete the KV data (metadata delete removes all versions), then the row.
+		try { await baoConf.request('DELETE', `secret/metadata/${secret.path()}`, undefined, { token }); } catch (e) { /* best-effort */ }
+		await secret.delete();
+		res.status(204).end();
+	} catch (e) { next(e); }
+});
+
+// ── Grants: list ────────────────────────────────────────────────────────────
+router.get('/:id/grants', async (req, res, next) => {
+	try {
+		const secret = await loadSecret(req, res);
+		if (!secret) return;
+		if (!(await canManage(req.user, secret))) return res.status(403).json({ error: 'only the owner (or admin) can manage grants' });
+		const grants = await SharedSecretGrant.list({ where: { secretId: secret.id } });
+		res.json({ grants: grants.map(g => ({ id: g.id, granteeType: g.granteeType, granteeId: g.granteeId, capability: g.capability })) });
+	} catch (e) { next(e); }
+});
+
+// ── Grants: create ──────────────────────────────────────────────────────────
+router.post('/:id/grants', async (req, res, next) => {
+	try {
+		const secret = await loadSecret(req, res);
+		if (!secret) return;
+		if (!(await canManage(req.user, secret))) return res.status(403).json({ error: 'only the owner (or admin) can manage grants' });
+		const granteeType = String(req.body.granteeType || '').trim();
+		const granteeId = String(req.body.granteeId || '').trim();
+		if (!['user', 'app'].includes(granteeType)) return res.status(400).json({ error: 'granteeType must be user or app' });
+		if (!granteeId) return res.status(400).json({ error: 'granteeId is required' });
+		if (granteeId === secret.ownerUid && granteeType === 'user') {
+			return res.status(400).json({ error: 'the owner already has access' });
+		}
+		// Idempotent: skip if the grant already exists.
+		const existing = (await SharedSecretGrant.list({ where: { secretId: secret.id, granteeType, granteeId } }))[0];
+		if (existing) return res.json({ id: existing.id, granteeType, granteeId, capability: existing.capability });
+		const grant = await vaultBroker.grantSharedSecret(secret.id, granteeType, granteeId, req.user.uid);
+		res.status(201).json({ id: grant.id, granteeType, granteeId, capability: grant.capability });
+	} catch (e) { next(e); }
+});
+
+// ── Grants: revoke ──────────────────────────────────────────────────────────
+router.delete('/:id/grants/:grantId', async (req, res, next) => {
+	try {
+		const secret = await loadSecret(req, res);
+		if (!secret) return;
+		if (!(await canManage(req.user, secret))) return res.status(403).json({ error: 'only the owner (or admin) can manage grants' });
+		const grant = await SharedSecretGrant.get(req.params.grantId);
+		if (!grant || grant.secretId !== secret.id) return res.status(404).json({ error: 'grant not found' });
+		await vaultBroker.revokeSharedSecret(grant.id, req.user.uid);
+		res.status(204).end();
+	} catch (e) { next(e); }
+});
+
+module.exports = router;

nodejs/routes/discovery.js

@@ -186,8 +186,11 @@ router.post('/promote/:slug', async (req, res, next) => {
 		
 		const meta = resource.metadata || {};
 		meta.managed = true;
-		await resource.update({ metadata: meta });
-		
+		// `Resource.update` is not a static — `update` is an instance method
+		// (@simpleworkjs/orm). Load a fresh instance and call it on that.
+		const inst = await Resource.get(resource.id);
+		await inst.update({ metadata: meta });
+
 		res.json(envelope({ success: true, groups: [accessGroup, adminGroup] }));
 	} catch (err) { next(err); }
 });

nodejs/routes/docs.js

@@ -37,6 +37,7 @@ const DOCS = {
 	agents:          {title: 'Plugins',                file: path.join(__dirname, '../../docs/plugins.md')},
 	plugins:         {title: 'Plugins',                file: path.join(__dirname, '../../docs/plugins.md')},
 	vault:           {title: 'Vault Secrets',           file: path.join(__dirname, '../../docs/vault.md')},
+	groups:          {title: 'Groups & Permissions',   file: path.join(__dirname, '../../docs/groups.md')},
 
 	overview:        {title: 'Overview',        file: path.join(__dirname, '../../README.md')},
 	changelog:       {title: 'Changelog',       file: path.join(__dirname, '../../CHANGELOG.md')},
@@ -54,7 +55,7 @@ const docList = Object.entries(DOCS).map(([slug, d]) => ({slug, title: d.title})
 // only resolves correctly on GitHub. Serve that same folder here and rewrite
 // the rendered markup to point at it absolutely, so the images work when
 // read from /docs/overview too.
-router.use('/images', require('express').static(path.join(__dirname, '../../docs/images')));
+router.use('/docs/images', require('express').static(path.join(__dirname, '../../docs/images')));
 function fixImagePaths(html) {
 	return html.replace(/(["(])docs\/images\//g, '$1/docs/images/');
 }

nodejs/routes/index.js

@@ -84,14 +84,7 @@ router.get('/discovery', function(req, res, next) {
 });
 
 router.get('/plugins', function(req, res, next) {
-  // Plugin instances page — loadable/unloadable, configurable plugin copies
-  // with per-instance secrets in OpenBao. Renders the shell for anyone; the
-  // client gates with app.auth.forceLogin(['app_sso_admin',
-  // 'app_sso_directory_admin','admin']) and the /api/plugins endpoints enforce
-  // the same server-side. Same header-vs-navigation auth model as /conf and
-  // /vault (auth-token is a client-set header, not a cookie).
-  const registry = require('../services/plugin_registry');
-  res.render('plugins', {...values, pluginTypes: registry.types });
+  res.redirect('/directory');
 });
 
 router.get('/vault', function(req, res) {
@@ -195,10 +188,6 @@ router.get('/users/:uid', function(req, res, next) {
   res.render('profile', {...values});
 });
 
-router.get('/groups', function(req, res, next) {
-  res.render('groups', {...values});
-});
-
 router.get('/token', function(req, res, next) {
   res.render('token', {...values});
 });

nodejs/routes/user.js

@@ -90,7 +90,13 @@ router.get('/me', async function(req, res, next){
 		// same answer in both modes.
 		const groups = await groupCns(user);
 		user.groups = groups;
-		user.isAdmin = groups.includes('app_sso_admin') || groups.includes(permission.SUPER_ADMIN_GROUP);
+		// Console admin under the group model (docs/GROUPS.md §11): god_admin,
+		// a site super admin, the SSO-as-app admin ({site}_app_sso_admin), or the
+		// legacy app_sso_admin/app_super_admin during migration.
+		user.isAdmin = groups.some((g) =>
+			g === 'app_sso_admin' || g === 'app_super_admin' ||
+			g === 'god_admin' || g === permission.SUPER_ADMIN_GROUP ||
+			g.endsWith('_super_admin') || g.endsWith('_app_sso_admin'));
 
 		return res.json(user);
 	}catch(error){

nodejs/services/discovery_reconciler.js

@@ -12,32 +12,39 @@ class DiscoveryReconciler {
       res._originalSlug = res.slug; // Keep track for edge mapping
       
       let existing = null;
-      
-      // Attempt matching by MAC if available (case-insensitive)
+      const normalizeMac = (m) => (m || '').toLowerCase().replace(/[^a-f0-9]/g, '');
+      const normalizeHost = (h) => (h || '').toLowerCase().split('.')[0].trim();
+
+      const allRes = await Resource.list();
+
+      // 1. Attempt matching by MAC (highest precision)
       if (res.metadata.interfaces && res.metadata.interfaces.length > 0) {
-        const macs = res.metadata.interfaces.map(i => i.mac ? i.mac.toLowerCase() : null).filter(m => !!m);
+        const macs = res.metadata.interfaces.map(i => normalizeMac(i.mac)).filter(m => m.length === 12);
         if (macs.length > 0) {
-          const allRes = await Resource.list();
           existing = allRes.find(r => 
-            r.metadata && r.metadata.interfaces && 
-            r.metadata.interfaces.some(i => i.mac && macs.includes(i.mac.toLowerCase()))
+            r.metadata && (
+              (r.metadata.macAddress && macs.includes(normalizeMac(r.metadata.macAddress))) ||
+              (r.metadata.interfaces && r.metadata.interfaces.some(i => macs.includes(normalizeMac(i.mac))))
+            )
           );
         }
       }
-      
-      // Fallback matching by IP if no MAC match (weaker)
+
+      // 2. Fallback matching by IP address
       let ipsToMatch = [];
       if (res.metadata.interfaces) {
         ipsToMatch = res.metadata.interfaces.map(i => i.ip).filter(i => !!i);
       }
+      if (res.metadata.ip) ipsToMatch.push(res.metadata.ip);
       if (res.metadata.address) {
         res.metadata.address.split(',').forEach(a => ipsToMatch.push(a.trim()));
       }
-      
+      ipsToMatch = [...new Set(ipsToMatch.filter(Boolean))];
+
       if (!existing && ipsToMatch.length > 0) {
-        const allRes = await Resource.list();
         existing = allRes.find(r => {
           if (!r.metadata) return false;
+          if (r.metadata.ip && ipsToMatch.includes(r.metadata.ip)) return true;
           if (r.metadata.address) {
             const addrs = r.metadata.address.split(',').map(a => a.trim());
             if (addrs.some(a => ipsToMatch.includes(a))) return true;
@@ -46,14 +53,17 @@ class DiscoveryReconciler {
           return false;
         });
       }
-      
-      // Fallback matching by Slug or Name
+
+      // 3. Fallback matching by Slug, Name, or Base Hostname
       if (!existing && (res.slug || res.name)) {
-        const allRes = await Resource.list();
-        existing = allRes.find(r => 
-          (res.slug && r.slug === res.slug) || 
-          (res.name && r.name && r.name.toLowerCase() === res.name.toLowerCase())
-        );
+        const inputName = normalizeHost(res.name || res.slug);
+        existing = allRes.find(r => {
+          if (res.slug && r.slug === res.slug) return true;
+          if (res.name && r.name && r.name.toLowerCase() === res.name.toLowerCase()) return true;
+          if (inputName && r.name && normalizeHost(r.name) === inputName) return true;
+          if (inputName && r.slug && normalizeHost(r.slug) === inputName) return true;
+          return false;
+        });
       }
 
       if (existing) {

nodejs/test-proxy.js

@@ -1,12 +0,0 @@
-const express = require('express');
-const { createProxyMiddleware } = require('http-proxy-middleware');
-const app = express();
-app.use('/', createProxyMiddleware({
-  target: 'http://localhost:8080',
-  on: {
-    proxyRes: (proxyRes, req, res) => {
-      delete proxyRes.headers['x-frame-options'];
-    }
-  }
-}));
-app.listen(3004);

nodejs/tests/access_request.test.js

@@ -44,9 +44,10 @@ beforeAll(async () => {
 	expect(host.status).toBe(200);
 	hostId = host.body.results.id;
 
-	// Creating a host auto-provisions <site>_<slug>_access / _admin.
-	accessGroupCn = `${siteSlug}_${hostSlug}_access`;
-	const adminGroupCn = `${siteSlug}_${hostSlug}_admin`;
+	// Creating a host auto-provisions <site>_host_<slug>_access / _admin
+	// (docs/GROUPS.md §2 — the kind is part of the name).
+	accessGroupCn = `${siteSlug}_host_${hostSlug}_access`;
+	const adminGroupCn = `${siteSlug}_host_${hostSlug}_admin`;
 
 	// The creator is seeded into both groups -- groupOfNames requires at least
 	// one member, so Group.add puts the owner's DN there -- and _admin is nested
@@ -213,8 +214,9 @@ describe('Access requests — withdrawal', () => {
 		expect(host.status).toBe(200);
 
 		// Same as the top-level setup: step out of the auto-created groups the
-		// creator is seeded into, or this is a request for access already held.
-		for (const cn of [`${siteSlug}_${slug}_admin`, `${siteSlug}_${slug}_access`]) {
+		// creator is seeded into (docs/GROUPS.md §2 — kind is part of the name),
+		// or this is a request for access already held.
+		for (const cn of [`${siteSlug}_host_${slug}_admin`, `${siteSlug}_host_${slug}_access`]) {
 			await request(app)
 				.delete(`/api/group/${encodeURIComponent(cn)}/test`)
 				.set('auth-token', token);

nodejs/tests/agent_manager.test.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const crypto = require('crypto');
+const agentManager = require('../utils/agent_manager');
+
+describe('AgentManager PROTOCOL.md v1.1.0 Compliance', () => {
+  let mockWs;
+  let sentMessages;
+
+  beforeEach(() => {
+    sentMessages = [];
+    mockWs = {
+      readyState: 1, // OPEN
+      send: jest.fn((msg) => sentMessages.push(JSON.parse(msg))),
+      close: jest.fn()
+    };
+  });
+
+  test('registers agent and tracks initial connection state', () => {
+    const record = agentManager.registerAgent('test-token-123', mockWs, '192.168.1.100');
+    expect(record.token).toBe('test-token-123');
+    expect(record.ipAddress).toBe('192.168.1.100');
+
+    const agents = agentManager.getConnectedAgents();
+    const found = agents.find(a => a.token === 'test-token-123');
+    expect(found).toBeDefined();
+    expect(found.isOnline).toBe(true);
+  });
+
+  test('processes discovery payload per PROTOCOL.md v1.1.0 Section 3.1', () => {
+    agentManager.registerAgent('test-token-123', mockWs, '192.168.1.100');
+
+    const discoveryPayload = {
+      hostname: 'node-01.local',
+      ip_addresses: ['192.168.1.100', '10.0.0.5'],
+      os: 'Ubuntu 24.04 LTS',
+      kernel: '6.8.0-31-generic',
+      cpu: 'AMD EPYC 7763',
+      ram_total_gb: 32.0,
+      disk_total_gb: 500.0,
+      location: 'dc-chicago-rack-4'
+    };
+
+    agentManager.handleDiscovery('test-token-123', discoveryPayload);
+
+    const agents = agentManager.getConnectedAgents();
+    const agent = agents.find(a => a.token === 'test-token-123');
+    expect(agent.hostname).toBe('node-01.local');
+    expect(agent.discovery.os).toBe('Ubuntu 24.04 LTS');
+    expect(agent.discovery.ip_addresses).toEqual(['192.168.1.100', '10.0.0.5']);
+  });
+
+  test('processes telemetry payload per PROTOCOL.md v1.1.0 Section 3.2', () => {
+    agentManager.registerAgent('test-token-123', mockWs, '192.168.1.100');
+
+    const telemetryPayload = {
+      cpu_usage_percent: 14.5,
+      ram_usage_percent: 42.1,
+      disk_usage_percent: 68.0,
+      zfs_health: 'ONLINE',
+      gpu_usage_percent: -1.0,
+      timestamp: new Date().toISOString()
+    };
+
+    agentManager.handleTelemetry('test-token-123', telemetryPayload);
+
+    const agents = agentManager.getConnectedAgents();
+    const agent = agents.find(a => a.token === 'test-token-123');
+    expect(agent.telemetry.cpu_usage_percent).toBe(14.5);
+    expect(agent.telemetry.zfs_health).toBe('ONLINE');
+  });
+
+  test('responds to heartbeat with heartbeat_ack per Section 3.3', () => {
+    agentManager.registerAgent('test-token-123', mockWs, '192.168.1.100');
+
+    agentManager.handleHeartbeat('test-token-123', { timestamp: new Date().toISOString() }, mockWs);
+
+    expect(mockWs.send).toHaveBeenCalled();
+    const lastMsg = sentMessages[sentMessages.length - 1];
+    expect(lastMsg.type).toBe('heartbeat_ack');
+    expect(lastMsg.payload.timestamp).toBeDefined();
+  });
+
+  test('canonicalizes payload and signs high-risk commands using Ed25519 per Section 5', () => {
+    agentManager.registerAgent('test-token-123', mockWs, '192.168.1.100');
+
+    const rawPayload = { script: 'uptime', location: 'datacenter' };
+    const msg = agentManager.sendCommand('test-token-123', 'arbitrary_bash', rawPayload, true);
+
+    expect(msg.type).toBe('arbitrary_bash');
+    expect(msg.payload.signature).toBeDefined();
+    expect(typeof msg.payload.signature).toBe('string');
+
+    // Verify signature with public key
+    const signatureBuffer = Buffer.from(msg.payload.signature, 'base64');
+    const canonicalStr = agentManager.canonicalize(rawPayload);
+    const isValid = crypto.verify(null, Buffer.from(canonicalStr, 'utf8'), agentManager.publicKeyPem, signatureBuffer);
+    expect(isValid).toBe(true);
+  });
+});

nodejs/tests/groups.test.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const {
+	slugify,
+	resourceGroupCns,
+	aggregateGroupCns,
+	siteSuperAdminCns,
+	siteEveryoneCns,
+	isKnownLevel,
+	levelGrants,
+	hasPermission,
+	GOD_ADMIN,
+} = require('../utils/groups');
+
+// Resource fixtures mirror the directory: hosts carry a `host_` prefix, services
+// are stored bare. The builders take the *name* slug (kind stripped) + a kind, so
+// a host `host_web-01` gives `main-office_host_web-01_*` and a service `emby`
+// gives `main-office_app_emby_*` -- matching docs/GROUPS.md §2.
+const HOST = { site: 'main-office', kind: 'host', slug: 'host_web-01' };
+const APP = { site: 'main-office', kind: 'app', slug: 'emby' };
+const SERVICE = { site: 'main-office', kind: 'service', slug: 'emby' };
+const OTHER_SITE_HOST = { site: 'branch-office', kind: 'host', slug: 'host_db' };
+
+describe('slugify', () => {
+	test('lowercases, spaces and underscores become hyphens, no leading/trailing dash', () => {
+		expect(slugify('Web 01')).toBe('web-01');
+		expect(slugify('Main Office')).toBe('main-office');
+		expect(slugify('my_host')).toBe('my-host');
+		expect(slugify('  Mixed CASE--name  ')).toBe('mixed-case-name');
+		expect(slugify('')).toBe('');
+	});
+});
+
+describe('group cn builders', () => {
+	test('per-resource names the kind + name slug (docs §2)', () => {
+		expect(resourceGroupCns('main-office', 'host', 'web-01', 'admin')).toBe('main-office_host_web-01_admin');
+		expect(resourceGroupCns('main-office', 'app', 'emby', 'access')).toBe('main-office_app_emby_access');
+	});
+	test('a prefixed site slug is kept verbatim; the resource name slug is kind-stripped', () => {
+		expect(resourceGroupCns('site_local', 'host', 'theta-env', 'access')).toBe('site_local_host_theta-env_access');
+		expect(resourceGroupCns('site_local', 'app', 'sso-manager', 'access')).toBe('site_local_app_sso-manager_access');
+	});
+	test('aggregate uses the plural kind', () => {
+		expect(aggregateGroupCns('main-office', 'host', 'admin')).toBe('main-office_hosts_admin');
+		expect(aggregateGroupCns('main-office', 'app', 'access')).toBe('main-office_apps_access');
+	});
+	test('site super admin + everyone', () => {
+		expect(siteSuperAdminCns('main-office')).toBe('main-office_super_admin');
+		expect(siteEveryoneCns('main-office')).toBe('main-office_everyone');
+	});
+	test('a directory site slug with a kind prefix is kept verbatim', () => {
+		expect(siteSuperAdminCns('site_local')).toBe('site_local_super_admin');
+		expect(siteEveryoneCns('site_local')).toBe('site_local_everyone');
+		expect(aggregateGroupCns('site_local', 'host', 'admin')).toBe('site_local_hosts_admin');
+	});
+	test('invalid kind throws', () => {
+		expect(() => resourceGroupCns('s', 'service', 'x', 'admin')).toThrow();
+		expect(() => aggregateGroupCns('s', 'service', 'admin')).toThrow();
+	});
+});
+
+describe('levels', () => {
+	test('admin/access known; capabilities opaque', () => {
+		expect(isKnownLevel('admin')).toBe(true);
+		expect(isKnownLevel('access')).toBe(true);
+		expect(isKnownLevel('reboot')).toBe(false);
+		expect(isKnownLevel('emby_admin')).toBe(false);
+	});
+	test('admin implies access; access does not imply admin', () => {
+		expect(levelGrants('admin', 'access')).toBe(true);
+		expect(levelGrants('access', 'admin')).toBe(false);
+	});
+});
+
+describe('hasPermission — inheritance', () => {
+	test('god_admin grants everything everywhere', () => {
+		expect(hasPermission([GOD_ADMIN], HOST, 'admin')).toBe(true);
+		expect(hasPermission([GOD_ADMIN], HOST, 'access')).toBe(true);
+		expect(hasPermission([GOD_ADMIN], HOST, 'reboot')).toBe(true);
+		expect(hasPermission([GOD_ADMIN], OTHER_SITE_HOST, 'admin')).toBe(true);
+	});
+
+	test('site super admin grants everything on its site, not other sites', () => {
+		expect(hasPermission(['main-office_super_admin'], HOST, 'admin')).toBe(true);
+		expect(hasPermission(['main-office_super_admin'], HOST, 'reboot')).toBe(true);
+		expect(hasPermission(['main-office_super_admin'], OTHER_SITE_HOST, 'admin')).toBe(false);
+	});
+
+	test('aggregate (all hosts) grants on any host at the site', () => {
+		expect(hasPermission(['main-office_hosts_admin'], HOST, 'admin')).toBe(true);
+		expect(hasPermission(['main-office_hosts_access'], HOST, 'access')).toBe(true);
+		expect(hasPermission(['main-office_hosts_admin'], HOST, 'access')).toBe(true);
+	});
+
+	test('specific host group grants only that host', () => {
+		const cn = resourceGroupCns('main-office', 'host', 'web-01', 'admin');
+		expect(hasPermission([cn], HOST, 'admin')).toBe(true);
+		expect(hasPermission([cn], OTHER_SITE_HOST, 'admin')).toBe(false);
+	});
+
+	test('admin implies access; access does not imply admin', () => {
+		expect(hasPermission([resourceGroupCns('main-office', 'host', 'web-01', 'admin')], HOST, 'access')).toBe(true);
+		expect(hasPermission([resourceGroupCns('main-office', 'host', 'web-01', 'access')], HOST, 'admin')).toBe(false);
+	});
+
+	test('capabilities are exact — admin does not grant a capability', () => {
+		expect(hasPermission([resourceGroupCns('main-office', 'host', 'web-01', 'reboot')], HOST, 'reboot')).toBe(true);
+		expect(hasPermission([resourceGroupCns('main-office', 'host', 'web-01', 'admin')], HOST, 'reboot')).toBe(false);
+		expect(hasPermission(['main-office_hosts_reboot'], HOST, 'reboot')).toBe(true);
+	});
+
+	test('hosts and apps are orthogonal namespaces', () => {
+		const hostAdmin = resourceGroupCns('main-office', 'host', 'web-01', 'admin');
+		expect(hasPermission([hostAdmin], APP, 'access')).toBe(false);
+		const appAdmin = resourceGroupCns('main-office', 'app', 'emby', 'admin');
+		expect(hasPermission([appAdmin], APP, 'access')).toBe(true);
+	});
+
+	test('a service maps to the app kind (docs §11)', () => {
+		// The directory `service` kind is the group model's `app`.
+		expect(hasPermission([resourceGroupCns('main-office', 'app', 'emby', 'admin')], SERVICE, 'admin')).toBe(true);
+		expect(hasPermission([resourceGroupCns('main-office', 'host', 'web-01', 'admin')], SERVICE, 'admin')).toBe(false);
+	});
+
+	test('cross-site isolation', () => {
+		const mainHostAdmin = resourceGroupCns('main-office', 'host', 'web-01', 'admin');
+		expect(hasPermission([mainHostAdmin], OTHER_SITE_HOST, 'access')).toBe(false);
+		expect(hasPermission(['branch-office_hosts_admin'], OTHER_SITE_HOST, 'admin')).toBe(true);
+	});
+});

nodejs/tests/nmap_plugin.test.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const nmapPlugin = require('../plugins/discovery/nmap');
+
+jest.mock('node-nmap', () => {
+  const EventEmitter = require('events');
+  class MockNmapScan extends EventEmitter {
+    constructor(targetRange, customFlags) {
+      super();
+      this.targetRange = targetRange;
+      this.customFlags = customFlags;
+      this.command = ['-oX', '-', ...(customFlags || []), targetRange];
+    }
+    startScan() {
+      setImmediate(() => {
+        this.emit('complete', [
+          { ip: '192.168.1.10', hostname: 'host-10', openPorts: [{ port: 80, protocol: 'tcp', service: 'http' }] }
+        ]);
+      });
+    }
+  }
+  return {
+    NmapScan: MockNmapScan,
+    nmapLocation: 'nmap'
+  };
+});
+
+describe('nmap discovery plugin', () => {
+  test('discover passes custom flags (-Pn, -sT, -F, --min-rate) to constructor', async () => {
+    const logs = [];
+    const result = await nmapPlugin.discover({
+      targetRange: '192.168.1.0/24',
+      log: (msg) => { logs.push(msg); }
+    });
+
+    const startLog = logs.find(l => l.startsWith('Starting nmap scan'));
+    expect(startLog).toBeDefined();
+    expect(startLog).toContain('-Pn');
+    expect(startLog).toContain('-sT');
+    expect(startLog).toContain('-F');
+    expect(startLog).toContain('--min-rate 100');
+    expect(result.resources).toHaveLength(2); // host + service
+    expect(result.resources[0].name).toBe('host-10');
+    expect(result.edges).toHaveLength(1);
+  });
+});

nodejs/tests/vault_broker.test.js

@@ -0,0 +1,204 @@
+'use strict';
+
+jest.mock('@simpleworkjs/bao-conf', () => ({
+  get: jest.fn(),
+  set: jest.fn(),
+  request: jest.fn(),
+}));
+
+jest.mock('redis', () => ({
+  createClient: () => ({
+    on: jest.fn(),
+    connect: jest.fn().mockResolvedValue(),
+    get: jest.fn().mockResolvedValue(null),
+    set: jest.fn().mockResolvedValue(),
+  })
+}));
+
+// In-memory stand-ins for the ORM-backed models so mintAppToken/renewAppTokens
+// can run without a database.
+jest.mock('../models/shared_secret', () => ({
+  SharedSecret: { list: jest.fn().mockResolvedValue([]) },
+}));
+jest.mock('../models/shared_secret_grant', () => ({
+  SharedSecretGrant: { listForGrantee: jest.fn().mockResolvedValue([]) },
+}));
+jest.mock('../models/vault_app_token', () => {
+  const rows = [];
+  const VaultAppToken = {
+    _rows: rows,
+    list: jest.fn(async () => rows),
+    getByName: jest.fn(async (name) => rows.find(r => r.name === name) || null),
+    create: jest.fn(async (data) => {
+      const row = {
+        ...data,
+        update: jest.fn(async function (patch) { Object.assign(this, patch); }),
+        delete: jest.fn(async function () { rows.splice(rows.indexOf(this), 1); }),
+      };
+      rows.push(row);
+      return row;
+    }),
+  };
+  return { VaultAppToken };
+});
+
+const baoConf = require('@simpleworkjs/bao-conf');
+const vaultBroker = require('../utils/vault_broker');
+const { VaultAppToken } = require('../models/vault_app_token');
+
+describe('vault_broker admin policy', () => {
+  beforeEach(() => {
+    baoConf.request.mockReset();
+  });
+
+  test('getOrCreateAdminToken ensures sso-admin policy with list capabilities on metadata', async () => {
+    baoConf.request.mockImplementation(async (method, path, body) => {
+      if (method === 'GET' && path === 'sys/policies/acl/sso-admin') {
+        return { status: 404, text: async () => '' };
+      }
+      if (method === 'PUT' && path === 'sys/policies/acl/sso-admin') {
+        expect(body.policy).toContain('path "secret/metadata" { capabilities = ["create", "read", "update", "delete", "list"] }');
+        expect(body.policy).toContain('path "secret/metadata/" { capabilities = ["create", "read", "update", "delete", "list"] }');
+        return { status: 204, ok: true };
+      }
+      if (method === 'POST' && path === 'auth/token/create/sso-broker') {
+        return {
+          ok: true,
+          json: async () => ({ auth: { client_token: 'test-admin-token', lease_duration: 3600 } })
+        };
+      }
+      return { status: 200, ok: true, json: async () => ({}) };
+    });
+
+    const token = await vaultBroker.getOrCreateAdminToken('adminuser');
+    expect(token).toBe('test-admin-token');
+    expect(baoConf.request).toHaveBeenCalledWith('PUT', 'sys/policies/acl/sso-admin', expect.objectContaining({
+      policy: expect.stringContaining('path "secret/metadata/"')
+    }));
+  });
+});
+
+describe('app token lifecycle (accessor storage + renewal)', () => {
+  beforeEach(() => {
+    baoConf.request.mockReset();
+    VaultAppToken._rows.length = 0;
+  });
+
+  function mockBao({ mintAccessor = 'acc-1', renewOk = true } = {}) {
+    baoConf.request.mockImplementation(async (method, path, body) => {
+      if (path.startsWith('sys/policies/acl/')) {
+        if (method === 'GET') return { status: 404, text: async () => '' };
+        return { status: 204, ok: true };
+      }
+      if (path === 'auth/token/create/sso-app') {
+        return { ok: true, json: async () => ({ auth: { client_token: 'app-tok', accessor: mintAccessor, lease_duration: 2764800 } }) };
+      }
+      if (path === 'auth/token/renew-accessor') {
+        return renewOk ? { ok: true, json: async () => ({}) } : { ok: false, status: 400, text: async () => 'invalid accessor' };
+      }
+      if (path === 'auth/token/revoke-accessor') {
+        return { ok: true, status: 204, text: async () => '' };
+      }
+      return { status: 200, ok: true, json: async () => ({}) };
+    });
+  }
+
+  test('mintAppToken stores the accessor; re-mint revokes the old accessor and replaces the row', async () => {
+    mockBao({ mintAccessor: 'acc-old' });
+    await vaultBroker.mintAppToken('demo', 'adminuser');
+    expect(VaultAppToken._rows).toHaveLength(1);
+    expect(VaultAppToken._rows[0]).toMatchObject({ name: 'demo', accessor: 'acc-old', created_by: 'adminuser' });
+
+    mockBao({ mintAccessor: 'acc-new' });
+    await vaultBroker.mintAppToken('demo', 'adminuser');
+    expect(baoConf.request).toHaveBeenCalledWith('POST', 'auth/token/revoke-accessor', { accessor: 'acc-old' });
+    expect(VaultAppToken._rows).toHaveLength(1);
+    expect(VaultAppToken._rows[0].accessor).toBe('acc-new');
+  });
+
+  test('renewAppTokens renews each accessor and stamps lastRenewedAt', async () => {
+    mockBao();
+    await vaultBroker.mintAppToken('demo', 'adminuser');
+    VaultAppToken._rows[0].lastRenewedAt = 0;
+    await vaultBroker.renewAppTokens();
+    expect(baoConf.request).toHaveBeenCalledWith('POST', 'auth/token/renew-accessor', { accessor: 'acc-1' });
+    expect(VaultAppToken._rows[0].lastRenewedAt).toBeGreaterThan(0);
+    expect(VaultAppToken._rows[0].lastError).toBeNull();
+  });
+
+  test('renewAppTokens records the failure on the row without throwing', async () => {
+    mockBao({ renewOk: false });
+    await vaultBroker.mintAppToken('demo', 'adminuser');
+    await vaultBroker.renewAppTokens();
+    expect(VaultAppToken._rows[0].lastError).toMatch(/renew failed \(400\)/);
+  });
+});
+
+// Real HTTP round-trip through vaultProxy() against an in-process fake OpenBao.
+// This exists because the proxy once shipped with a hook shape the installed
+// http-proxy-middleware version ignored (v3 `on: { proxyReq }` vs v2
+// `onProxyReq`), so NO X-Vault-Token was ever injected and every /api/vault
+// request 403'd. A unit test on options can't catch that — only a wire test can.
+describe('vaultProxy wire behavior', () => {
+  const http = require('http');
+  const express = require('express');
+
+  let target; // fake OpenBao
+  let seen;   // last request the fake OpenBao received
+  let app;    // sso app fragment: scopeGuard stub + vaultProxy
+  let server;
+
+  beforeAll((done) => {
+    target = http.createServer((req, res) => {
+      let body = '';
+      req.on('data', (c) => { body += c; });
+      req.on('end', () => {
+        seen = { method: req.method, url: req.url, headers: req.headers, body };
+        res.setHeader('content-type', 'application/json');
+        res.end('{"ok":true}');
+      });
+    });
+    target.listen(0, '127.0.0.1', () => {
+      process.env.VAULT_ADDR = `http://127.0.0.1:${target.address().port}`;
+      jest.resetModules();
+      const broker = require('../utils/vault_broker');
+      app = express();
+      app.use(express.json());
+      app.use('/api/vault', (req, res, next) => { req.vaultToken = 'scoped-token-123'; next(); }, broker.vaultProxy());
+      server = app.listen(0, '127.0.0.1', done);
+    });
+  });
+
+  afterAll((done) => {
+    server.close(() => target.close(done));
+  });
+
+  function call(path, opts = {}) {
+    const port = server.address().port;
+    return fetch(`http://127.0.0.1:${port}${path}`, opts);
+  }
+
+  test('GET list rewrites /api/vault -> /v1, injects X-Vault-Token, strips sso auth headers', async () => {
+    const res = await call('/api/vault/secret/metadata/users/alice?list=true', {
+      headers: { 'auth-token': 'sso-session-token', authorization: 'Bearer sso_x_y', 'content-type': 'application/json' },
+    });
+    expect(res.status).toBe(200);
+    expect(seen.url).toBe('/v1/secret/metadata/users/alice?list=true');
+    expect(seen.headers['x-vault-token']).toBe('scoped-token-123');
+    expect(seen.headers['auth-token']).toBeUndefined();
+    expect(seen.headers['authorization']).toBeUndefined();
+  });
+
+  test('POST body survives the express.json + fixRequestBody round-trip', async () => {
+    const res = await call('/api/vault/secret/data/users/alice/foo', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'auth-token': 'sso-session-token' },
+      body: JSON.stringify({ data: { hello: 'world' } }),
+    });
+    expect(res.status).toBe(200);
+    expect(seen.method).toBe('POST');
+    expect(seen.url).toBe('/v1/secret/data/users/alice/foo');
+    expect(seen.headers['x-vault-token']).toBe('scoped-token-123');
+    expect(JSON.parse(seen.body)).toEqual({ data: { hello: 'world' } });
+  });
+});

nodejs/utils/agent_manager.js

@@ -0,0 +1,180 @@
+'use strict';
+
+const crypto = require('crypto');
+
+class AgentManager {
+  constructor() {
+    this.agents = new Map(); // token -> agentRecord
+    this.privateKeyPem = null;
+    this.publicKeyPem = null;
+    this.initKeyPair();
+  }
+
+  initKeyPair() {
+    try {
+      const { privateKey, publicKey } = crypto.generateKeyPairSync('ed25519', {
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+        publicKeyEncoding: { type: 'spki', format: 'pem' }
+      });
+      this.privateKeyPem = privateKey;
+      this.publicKeyPem = publicKey;
+    } catch (err) {
+      console.error('[AgentManager] Failed to generate Ed25519 key pair:', err);
+    }
+  }
+
+  /**
+   * Canonicalize payload for signing per PROTOCOL.md v1.1.0 section 5:
+   * Sort keys alphabetically, remove whitespace, omit 'signature' key.
+   */
+  canonicalize(payload) {
+    const cleanObj = {};
+    const sortedKeys = Object.keys(payload).filter(k => k !== 'signature').sort();
+    for (const key of sortedKeys) {
+      cleanObj[key] = payload[key];
+    }
+    return JSON.stringify(cleanObj);
+  }
+
+  /**
+   * Sign payload using Ed25519 private key.
+   * Returns base64 encoded signature.
+   */
+  signPayload(payload) {
+    if (!this.privateKeyPem) {
+      throw new Error('Ed25519 private key is not initialized');
+    }
+    const canonicalBytes = Buffer.from(this.canonicalize(payload), 'utf8');
+    const signature = crypto.sign(null, canonicalBytes, this.privateKeyPem);
+    return signature.toString('base64');
+  }
+
+  registerAgent(token, ws, remoteAddress) {
+    const existing = this.agents.get(token);
+    if (existing && existing.ws && existing.ws !== ws) {
+      try { existing.ws.close(4002, 'Superseded by new connection'); } catch (e) {}
+    }
+
+    const agentRecord = {
+      token,
+      ws,
+      ipAddress: remoteAddress,
+      hostname: 'unknown',
+      connectedAt: new Date().toISOString(),
+      lastSeen: new Date().toISOString(),
+      discovery: {},
+      telemetry: {},
+      pendingResponses: new Map()
+    };
+
+    this.agents.set(token, agentRecord);
+    return agentRecord;
+  }
+
+  unregisterAgent(token, ws) {
+    const record = this.agents.get(token);
+    if (record && record.ws === ws) {
+      this.agents.delete(token);
+    }
+  }
+
+  handleDiscovery(token, payload) {
+    const agent = this.agents.get(token);
+    if (!agent) return;
+
+    agent.lastSeen = new Date().toISOString();
+    agent.hostname = payload.hostname || agent.hostname;
+    agent.discovery = {
+      hostname: payload.hostname || '',
+      ip_addresses: Array.isArray(payload.ip_addresses) ? payload.ip_addresses : [],
+      os: payload.os || '',
+      kernel: payload.kernel || '',
+      cpu: payload.cpu || '',
+      ram_total_gb: payload.ram_total_gb || 0,
+      disk_total_gb: payload.disk_total_gb || 0,
+      location: payload.location || 'default'
+    };
+  }
+
+  handleTelemetry(token, payload) {
+    const agent = this.agents.get(token);
+    if (!agent) return;
+
+    agent.lastSeen = new Date().toISOString();
+    agent.telemetry = {
+      cpu_usage_percent: payload.cpu_usage_percent || 0,
+      ram_usage_percent: payload.ram_usage_percent || 0,
+      disk_usage_percent: payload.disk_usage_percent || 0,
+      zfs_health: payload.zfs_health || 'N/A',
+      gpu_usage_percent: payload.gpu_usage_percent ?? -1,
+      timestamp: payload.timestamp || new Date().toISOString()
+    };
+  }
+
+  handleHeartbeat(token, payload, ws) {
+    const agent = this.agents.get(token);
+    if (agent) {
+      agent.lastSeen = new Date().toISOString();
+    }
+    try {
+      ws.send(JSON.stringify({
+        type: 'heartbeat_ack',
+        payload: { timestamp: new Date().toISOString() }
+      }));
+    } catch (e) {}
+  }
+
+  handleResponse(token, payload) {
+    const agent = this.agents.get(token);
+    if (agent) {
+      agent.lastSeen = new Date().toISOString();
+      agent.lastResponse = {
+        status: payload.status || 'ok',
+        message: payload.message || '',
+        output: payload.output || '',
+        timestamp: new Date().toISOString()
+      };
+    }
+  }
+
+  sendCommand(token, commandType, payload = {}, isHighRisk = false) {
+    const agent = this.agents.get(token);
+    if (!agent || !agent.ws || agent.ws.readyState !== 1) {
+      throw new Error(`Agent with token "${token}" is not connected`);
+    }
+
+    const finalPayload = { ...payload };
+    if (isHighRisk) {
+      finalPayload.signature = this.signPayload(finalPayload);
+    }
+
+    const message = {
+      type: commandType,
+      payload: finalPayload
+    };
+
+    agent.ws.send(JSON.stringify(message));
+    return message;
+  }
+
+  getConnectedAgents() {
+    const list = [];
+    const now = new Date();
+    for (const [token, agent] of this.agents.entries()) {
+      list.push({
+        token,
+        hostname: agent.hostname,
+        ipAddress: agent.ipAddress,
+        connectedAt: agent.connectedAt,
+        lastSeen: agent.lastSeen,
+        discovery: agent.discovery,
+        telemetry: agent.telemetry,
+        lastResponse: agent.lastResponse || null,
+        isOnline: (now - new Date(agent.lastSeen)) < 90000
+      });
+    }
+    return list;
+  }
+}
+
+module.exports = new AgentManager();

nodejs/utils/groups.js

@@ -0,0 +1,141 @@
+'use strict';
+
+// Theta42 group & permission model.
+//
+// Canonical spec: theta-suite/docs/GROUPS.md. Group names follow a fixed,
+// parseable structure. The structural delimiter is `_`; site/host/app slugs
+// never contain it. Aggregates use the plural kind (hosts/apps); per-resource
+// uses the singular (host/app).
+//
+//   god_admin                              global — everything, everywhere
+//   {site}_super_admin                     everything on the site
+//   {site}_hosts_<level>                   admin/access/capability on ALL hosts at the site
+//   {site}_hosts_<level>
+//   {site}_host_<slug>_<level>             admin/access/capability on ONE host
+//   {site}_apps_<level>                    ... on ALL apps at the site
+//   {site}_app_<slug>_<level>              ... on ONE app
+//   {site}_everyone / everyone             meta groups (implicit membership)
+//
+// `level` is 'admin', 'access', or an opaque `<capability>`. `admin` implies
+// `access`; capabilities are explicit and never implied by `admin`. Groups are
+// `groupOfNames` (RBAC) — no gidNumber; hosts map GIDs on the fly (SSSD).
+//
+// This module is pure logic (no LDAP/DB) so it is fully unit-testable. Callers
+// supply the user's group memberships (e.g. from Group.list(user.dn)).
+
+const GOD_ADMIN = 'god_admin';
+const KNOWN_LEVELS = ['admin', 'access'];
+const KINDS = ['host', 'app'];
+
+// Normalize a site/host/app slug: lowercase; runs of non-alnum -> '-'; never
+// contains '_' (the structural delimiter), so group names parse unambiguously.
+function slugify(name) {
+  return String(name || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// Validate a kind (host/app) — throw on anything else.
+function assertKind(kind) {
+  if (!KINDS.includes(kind)) throw new Error(`invalid resource kind: ${kind} (must be host or app)`);
+}
+
+// Strip the kind prefix a directory resource slug may carry (`host_theta-env` ->
+// `theta-env`), leaving the resource's name slug. Services are stored bare
+// (`sso-manager`), so this is a no-op for them.
+function resourceNameSlug(slug) {
+  return String(slug || '').replace(/^(site|host|app)_/, '');
+}
+
+// {site}_{kind}_{nameSlug}_{level} — the per-resource group for ONE resource.
+// Matches docs/GROUPS.md §2 (`S_host_<host>_<level>` / `S_app_<app>_<level>`):
+// `site` is the site resource's slug verbatim (`site_local`), `kind` is the
+// group-model kind (`host`/`app`), `nameSlug` is the resource's name (kind
+// stripped, e.g. `theta-env` from `host_theta-env`). So a host `host_theta-env`
+// yields `site_local_host_theta-env_access` and a service `sso-manager` yields
+// `site_local_app_sso-manager_access`.
+function resourceGroupCns(site, kind, nameSlug, level) {
+  assertKind(kind);
+  return `${site}_${kind}_${slugify(nameSlug)}_${level}`;
+}
+
+// {site}_hosts_<level> / {site}_apps_<level> (plural kind — the aggregate).
+function aggregateGroupCns(site, kind, level) {
+  assertKind(kind);
+  return `${site}_${kind}s_${level}`;
+}
+
+// {site}_super_admin
+function siteSuperAdminCns(site) {
+  return `${site}_super_admin`;
+}
+
+// {site}_everyone
+function siteEveryoneCns(site) {
+  return `${site}_everyone`;
+}
+
+// True if `level` is a known admin/access level (not an opaque capability).
+function isKnownLevel(level) {
+  return KNOWN_LEVELS.includes(level);
+}
+
+// True if holding `level` grants `wanted` (admin implies access).
+function levelGrants(level, wanted) {
+  if (level === wanted) return true;
+  return level === 'admin' && wanted === 'access';
+}
+
+// Resolve whether a user (given `memberOf` — the group cns they belong to) has
+// `level` on a resource. Applies the inheritance lattice:
+//   god_admin ⊇ {site}_super_admin ⊇ aggregate ⊇ specific; admin ⊇ access.
+//
+//   memberOf: array of group cns the user is a member of.
+//   resource: { site, kind: 'host'|'app', slug }.
+//   level:    'admin' | 'access' | an opaque capability token.
+//
+// Meta-group grants (`everyone` / `{site}_everyone`) are NOT handled here — they
+// are resource-level grants, resolved by the caller against the resource's own
+// granted groups (see permission.onResource). This keeps the function pure over
+// the user's membership only.
+function hasPermission(memberOf, resource, level) {
+  // `site` is used verbatim (`site_local`); `kind` maps the directory `service`
+  // kind onto the group model's `app` (docs/GROUPS.md §11 — consoles/services are
+  // apps); `nameSlug` is the resource name with any kind prefix stripped.
+  const site = resource && resource.site;
+  const rawKind = resource && resource.kind;
+  const kind = rawKind === 'service' ? 'app' : rawKind;
+  const nameSlug = resourceNameSlug(resource && resource.slug);
+  const set = new Set(memberOf || []);
+
+  if (set.has(GOD_ADMIN)) return true;
+  if (set.has(siteSuperAdminCns(site))) return true;
+
+  if (isKnownLevel(level)) {
+    // admin / access
+    if (set.has(aggregateGroupCns(site, kind, level))) return true;
+    if (set.has(resourceGroupCns(site, kind, nameSlug, level))) return true;
+    if (level === 'access' && hasPermission(memberOf, resource, 'admin')) return true;
+    return false;
+  }
+  // Opaque capability — exact aggregate or specific grant only.
+  if (set.has(aggregateGroupCns(site, kind, level))) return true;
+  if (set.has(resourceGroupCns(site, kind, nameSlug, level))) return true;
+  return false;
+}
+
+module.exports = {
+  GOD_ADMIN,
+  KNOWN_LEVELS,
+  KINDS,
+  slugify,
+  resourceNameSlug,
+  resourceGroupCns,
+  aggregateGroupCns,
+  siteSuperAdminCns,
+  siteEveryoneCns,
+  isKnownLevel,
+  levelGrants,
+  hasPermission,
+};

nodejs/utils/permission.js

@@ -1,10 +1,27 @@
 'use strict';
 
 const {Group} = require('../models/group_ldap');
+const groups = require('./groups');
 
-const SUPER_ADMIN_GROUP = 'app_super_admin';
+// The group nested into every resource's _admin group by api_directory_admin
+// (cross-resource super-admin administration). This is `god_admin` -- the global
+// super group of the new model (docs/GROUPS.md), seeded by docker-entrypoint.sh.
+// It used to be the legacy `app_super_admin`, which existed while god_admin
+// didn't; now that god_admin is created at boot, the provisioning nests it.
+// LEGACY_SUPER_ADMIN_ALIASES still recognizes a `app_super_admin` that predates
+// the migration, so an existing deployment isn't stripped of rights until it's
+// rebuilt.
+const SUPER_ADMIN_GROUP = 'god_admin';
+const LEGACY_SUPER_ADMIN_ALIASES = ['app_super_admin'];
 
-let byGroup = async function(user, groups, ownerOf){
+// True if the user (by resolved member cns) is a global god/super admin.
+// Recognizes BOTH the new schema's `god_admin` and the legacy `app_super_admin`.
+async function isSuperAdmin(memberOfCns) {
+	return memberOfCns.includes(groups.GOD_ADMIN) ||
+		memberOfCns.some((cn) => LEGACY_SUPER_ADMIN_ALIASES.includes(cn));
+}
+
+let byGroup = async function(user, checkGroups, ownerOf){
 	// Membership is resolved once, transitively: a user placed in an admin group
 	// through a nested group is as much a member as one listed on it directly.
 	// Checking `group.member.includes(user.dn)` per group -- as this used to --
@@ -17,9 +34,9 @@ let byGroup = async function(user, groups, ownerOf){
 		// they still catch direct membership if the resolver is unavailable.
 	}
 
-	if(memberOfCns.includes(SUPER_ADMIN_GROUP)) return true;
+	if(await isSuperAdmin(memberOfCns)) return true;
 
-	for(let group of groups){
+	for(let group of checkGroups){
 		if(memberOfCns.includes(group)) return true;
 	}
 
@@ -42,4 +59,46 @@ let byGroup = async function(user, groups, ownerOf){
 	throw error;
 }
 
-module.exports = {byGroup, SUPER_ADMIN_GROUP};
+// Resolve whether a user has `level` on a directory resource under the group
+// model (see utils/groups.js). Applies the inheritance lattice and the
+// `everyone`/`{site}_everyone` meta grants when the resource grants them.
+//
+//   user:    the auth user ({ dn, isMachine }).
+//   resource:{ site, kind: 'host'|'app', slug }.
+//   level:   'admin' | 'access' | an opaque capability token.
+//   grantedGroups: optional array of the resource's granted group cns (used only
+//     for meta `everyone` handling). Omit to skip meta grants.
+async function onResource(user, resource, level, grantedGroups) {
+	let memberOfCns = [];
+	try { memberOfCns = await Group.list(user.dn); } catch (e) { /* ignore */ }
+
+	if (await isSuperAdmin(memberOfCns)) return true;
+	if (groups.hasPermission(memberOfCns, resource, level)) return true;
+
+	// Meta grants: `everyone` / `{site}_everyone` confer access to any
+	// authenticated (non-machine) user when the resource grants them.
+	if (level === 'access' && !user.isMachine && Array.isArray(grantedGroups)) {
+		const siteEveryone = groups.siteEveryoneCns(resource.site);
+		if (grantedGroups.includes('everyone') || grantedGroups.includes(siteEveryone)) return true;
+	}
+	return false;
+}
+
+// Like onResource but throws Insufficient Permission when denied — for guards.
+async function requireResource(user, resource, level, grantedGroups) {
+	if (await onResource(user, resource, level, grantedGroups)) return;
+	const error = new Error('Insufficient Permission');
+	error.name = 'Insufficient Permission';
+	error.status = 401;
+	throw error;
+}
+
+module.exports = {
+	byGroup,
+	onResource,
+	requireResource,
+	isSuperAdmin,
+	SUPER_ADMIN_GROUP,
+	LEGACY_SUPER_ADMIN_ALIASES,
+	...groups, // group schema builders (slugify, resourceGroupCns, ...)
+};

nodejs/utils/ui.js

@@ -38,16 +38,13 @@ module.exports = {
 	// app-base.js, which reveals .group-required-<cn> for each group the user is
 	// in (plus the synthetic `admin` group when user/me reports isAdmin).
 	nav: [
-		// Ungated on purpose: the catalog is the one page that exists for
-		// ordinary users. Before this, every nav item was admin-only and a
-		// non-admin had no signposted destination at all.
-		{href: '/', icon: 'fa-solid fa-compass', label: 'Catalog', groups: []},
+		// Catalog requires login - it's the end-user view of their accessible resources.
+		{href: '/', icon: 'fa-solid fa-compass', label: 'Catalog', groups: ['login']},
 		{href: '/users', icon: 'fa-solid fa-users', label: 'Users', groups: ['app_sso_admin', 'admin']},
-		{href: '/groups', icon: 'fas fa-users-cog', label: 'Groups', groups: ['app_sso_admin']},
 		{href: '/conf', icon: 'fas fa-cogs', label: 'Configuration', groups: ['app_sso_admin']},
 		{href: '/directory', icon: 'fa-solid fa-server', label: 'Directory', groups: ['app_sso_admin', 'app_sso_directory_admin', 'admin']},
-		{href: '/plugins', icon: 'fa-solid fa-plug', label: 'Plugins', groups: ['app_sso_admin', 'app_sso_directory_admin', 'admin']},
-		{href: '/vault', icon: 'fa-solid fa-vault', label: 'Vault', groups: []},
+		// Vault requires login - per-user secrets at secret/users/<uid>/*.
+		{href: '/vault', icon: 'fa-solid fa-vault', label: 'Vault', groups: ['login']},
 		{href: '/overview', icon: 'fa-solid fa-gauge-high', label: 'Overview', groups: ['app_sso_admin', 'admin']},
 	],
 };

nodejs/utils/vault_broker.js

@@ -4,15 +4,25 @@
 // external apps, using the SSO_VAULT_TOKEN (policy `sso-broker`) and the
 // `sso-broker` token role created by theta-env/setup.sh.
 //
-//   secret/users/<uid>/*   per-user personal KV (user-<uid> policy)
-//   secret/apps/<name>/*   per-external-app namespace (app-<name> policy)
-//   secret/*               admin UI sessions (sso-admin policy)
+//   secret/users/<uid>/*          per-user personal KV (user-<uid> policy)
+//   secret/shared/<uid>/*         user-owned shared KV (user-<uid> policy)
+//   secret/apps/<name>/*          per-external-app namespace (app-<name> policy)
+//   secret/shared/<owner>/<slug>  granted read (added to grantee's policy)
+//   secret/*                      admin UI sessions (sso-admin policy)
 //
 // The sso-broker policy grants update on auth/token/create/sso-broker and on
 // sys/policies/acl/user-*, app-*, sso-admin — exactly what this module needs to
 // create the per-subject policies and mint their tokens. Per-user/admin tokens
 // are cached in Redis for the token's lifetime and re-minted on miss; per-app
 // tokens are returned ONCE (displayed in the UI, never stored retrievably).
+//
+// Policy reconciliation is the load-bearing part: OpenBao parses policy CONTENT
+// live at token use (only the SET of policy names on a token is fixed at mint),
+// so we ALWAYS reconcile a subject's policy content BEFORE returning any token
+// — cached or freshly minted. That way a stale cached token immediately gains
+// corrected/revoked capabilities, and a new shared-secret grant takes effect for
+// an existing grantee token with no re-mint. The Redis cache only short-circuits
+// token MINTING, never policy reconciliation.
 
 const baoConf = require('@simpleworkjs/bao-conf');
 const { createClient } = require('redis');
@@ -20,6 +30,9 @@ const express = require('express');
 const { createProxyMiddleware, fixRequestBody } = require('http-proxy-middleware');
 const conf = require('@simpleworkjs/conf');
 const permission = require('./permission');
+const { SharedSecret } = require('../models/shared_secret');
+const { SharedSecretGrant } = require('../models/shared_secret_grant');
+const { VaultAppToken } = require('../models/vault_app_token');
 
 const ROLE = 'sso-broker';
 const DEFAULT_TTL = 24 * 60 * 60; // matches the role's token_period (24h)
@@ -54,59 +67,104 @@ async function bao(method, path, body) {
 	return res;
 }
 
-// Ensure an ACL policy exists AND carries the latest HCL. Always (re)writes —
-// `bao policy write` is an idempotent overwrite — so policy edits (e.g. adding
-// a list grant on a directory path) propagate on the next vault-page visit
-// without an operator re-running setup.sh. Skipping on an existing policy
-// would strand the old, narrower HCL forever.
+// Ensure an ACL policy carries exactly `hcl`. Compare-and-skip: read the current
+// content and only PUT when it differs. `bao policy write` is an idempotent
+// overwrite, so this is safe to call on every token fetch — edits (e.g. adding a
+// grant) propagate immediately because OpenBao parses policy content at use.
 async function ensurePolicy(name, hcl) {
 	const existing = await baoConf.request('GET', `sys/policies/acl/${name}`);
 	if (existing.status !== 200 && existing.status !== 404) {
 		const t = await existing.text().catch(() => '');
 		throw new Error(`OpenBao policy read ${name} failed (${existing.status}) ${t}`);
 	}
+	if (existing.status === 200) {
+		const body = await existing.json().catch(() => null);
+		if (body && typeof body.policy === 'string' && body.policy === hcl) return; // unchanged
+	}
 	await bao('PUT', `sys/policies/acl/${name}`, { policy: hcl });
 }
 
-// Mint a token through the sso-broker role with the given policies. Returns
-// { token, ttl } (ttl = lease_duration seconds, falls back to DEFAULT_TTL).
-async function mintToken(policies) {
-	const res = await bao('POST', 'auth/token/create/sso-broker', { policies });
+// Mint a token through a token role with the given policies. Returns
+// { token, accessor, ttl } (ttl = lease_duration seconds, falls back to
+// DEFAULT_TTL). Roles: sso-broker (24h period — user/admin tokens, re-minted
+// from cache) and sso-app (768h period — long-lived external-app credentials,
+// kept alive via their stored accessor by the renewal loop below).
+async function mintToken(policies, role = ROLE) {
+	const res = await bao('POST', `auth/token/create/${role}`, { policies });
 	const json = await res.json();
 	const token = json && json.auth && json.auth.client_token;
 	if (!token) throw new Error(`OpenBao token mint returned no client_token: ${JSON.stringify(json)}`);
 	const ttl = (json.auth && json.auth.lease_duration) || DEFAULT_TTL;
-	return { token, ttl };
+	return { token, accessor: json.auth.accessor, ttl };
+}
+
+// ── Shared-secret policy rules ───────────────────────────────────────────────
+// Returns the HCL rules granting `read` on every shared secret the given
+// grantee (a user uid or an app name) has been granted. Enforcement is
+// OpenBao ACL policy CONTENT — live-evaluated at token use, so these rules take
+// effect for the grantee's existing token immediately (no re-mint).
+async function sharedPolicyRules(granteeType, granteeId) {
+	const grants = await SharedSecretGrant.listForGrantee(granteeType, granteeId);
+	if (!grants.length) return '';
+	const secretIds = [...new Set(grants.map(g => g.secretId))];
+	const secrets = secretIds.length
+		? await SharedSecret.list({ where: { id: { in: secretIds } } }) : [];
+	const byId = new Map(secrets.map(s => [s.id, s]));
+	const rules = [];
+	for (const g of grants) {
+		const sec = byId.get(g.secretId);
+		if (!sec) continue;
+		const p = sec.path(); // shared/<ownerUid>/<slug>
+		rules.push(`path "secret/data/${p}" { capabilities = ["read"] }`);
+		rules.push(`path "secret/metadata/${p}" { capabilities = ["read", "list"] }`);
+	}
+	return rules.join('\n');
 }
 
 // ── Per-user token ──────────────────────────────────────────────────────────
-function userPolicyHcl(uid) {
-	// uid is an LDAP uid (alphanumeric + a few separators); it is interpolated
-	// into a policy path, so reject anything but a safe charset.
-	// The bare `secret/metadata/users/<uid>` grant is required to LIST the
-	// contents of the namespace: `.../*` covers nested paths but NOT the
-	// directory itself, so without it the /vault secrets list 403s.
-	return `path "secret/data/users/${uid}/*" { capabilities = ["create", "read", "update", "delete", "list"] }
-path "secret/metadata/users/${uid}" { capabilities = ["list", "read", "delete"] }
-path "secret/metadata/users/${uid}/" { capabilities = ["list", "read", "delete"] }
-path "secret/metadata/users/${uid}/*" { capabilities = ["list", "read", "delete"] }`;
+async function userPolicyHcl(uid) {
+	const granted = await sharedPolicyRules('user', uid);
+	return `path "secret/data/users/${uid}" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/data/users/${uid}/*" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/metadata/users/${uid}" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/metadata/users/${uid}/" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/metadata/users/${uid}/*" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/data/shared/${uid}" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/data/shared/${uid}/*" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/metadata/shared/${uid}" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/metadata/shared/${uid}/" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/metadata/shared/${uid}/*" { capabilities = ["create", "read", "update", "delete", "list"] }
+${granted}`.trim();
 }
 
-// Mint (or return the cached) per-user token confined to secret/users/<uid>/*.
-// Re-minted when the cache entry expires (a little before the token's own TTL).
+// Mint (or return the cached) per-user token. The policy is ALWAYS reconciled
+// (compare-and-skip) before the cache is consulted, so a cached token can never
+// outlive a policy change; the cache only short-circuits re-minting. Re-minted
+// when the cache entry expires (a little before the token's own TTL).
 async function getOrCreateUserToken(uid) {
 	if (!/^[A-Za-z0-9._-]{1,64}$/.test(uid)) throw new Error(`invalid uid for vault token: ${uid}`);
+	await ensurePolicy(`user-${uid}`, await userPolicyHcl(uid));
 	const cacheKey = `vault_token:${uid}`;
 	const cached = await cacheGet(cacheKey);
 	if (cached) return cached;
-	await ensurePolicy(`user-${uid}`, userPolicyHcl(uid));
 	const { token, ttl } = await mintToken([`user-${uid}`]);
 	await cacheSet(cacheKey, token, Math.max(ttl - 60, 60));
 	return token;
 }
 
 // ── Admin token (read/write all of secret/) ─────────────────────────────────
+function adminPolicyHcl() {
+	return `path "secret/*" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/data/*" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/data" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/metadata" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/metadata/" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/metadata/*" { capabilities = ["create", "read", "update", "delete", "list"] }`;
+}
+
 async function getOrCreateAdminToken(uid) {
+	await ensurePolicy('sso-admin', adminPolicyHcl());
 	const cacheKey = `vault_token:admin:${uid || 'global'}`;
 	const cached = await cacheGet(cacheKey);
 	if (cached) return cached;
@@ -116,27 +174,144 @@ async function getOrCreateAdminToken(uid) {
 }
 
 // ── Per-app token (minted ONCE, returned to the caller, never cached) ───────
-function appPolicyHcl(name) {
-	// The bare `secret/metadata/apps/<name>` grant lets an app LIST its own
-	// namespace root (see userPolicyHcl for why `/*` alone isn't enough).
-	return `path "secret/data/apps/${name}/*" { capabilities = ["create", "read", "update", "delete", "list"] }
-path "secret/metadata/apps/${name}" { capabilities = ["list", "read", "delete"] }
-path "secret/metadata/apps/${name}/*" { capabilities = ["list", "read", "delete"] }`;
+async function appPolicyHcl(name) {
+	const granted = await sharedPolicyRules('app', name);
+	return `path "secret/data/apps/${name}" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/data/apps/${name}/*" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/metadata/apps/${name}" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/metadata/apps/${name}/" { capabilities = ["create", "read", "update", "delete", "list"] }
+path "secret/metadata/apps/${name}/*" { capabilities = ["create", "read", "update", "delete", "list"] }
+${granted}`.trim();
 }
 
 // Create the app-<name> policy + mint a token for it. Returns the token ONCE
 // (the admin UI shows it with a copy button); it is not stored retrievably, so
 // a later compromise of an admin session cannot recover previously-minted app
-// tokens. The caller must record it in the external app immediately.
-async function mintAppToken(name) {
+// tokens. The caller must record it in the external app immediately. Later
+// grants to the app edit app-<name> policy content (live-applied to this token).
+//
+// What IS stored is the token's ACCESSOR (VaultAppToken row): an accessor
+// cannot authenticate, but it lets the renewal loop below keep the (periodic)
+// token alive and lets a re-mint revoke the app's previous token so exactly
+// one credential per app is ever live.
+async function mintAppToken(name, actorUid) {
 	if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(name)) {
 		throw new Error('invalid app name (lowercase letters, digits, hyphens; max 63 chars)');
 	}
-	await ensurePolicy(`app-${name}`, appPolicyHcl(name));
-	const { token, ttl } = await mintToken([`app-${name}`]);
+	await ensurePolicy(`app-${name}`, await appPolicyHcl(name));
+	// App tokens are long-lived credentials: mint via the sso-app role (768h
+	// period) so a renewal inside every 32-day window keeps them alive forever.
+	// Fall back to the broker's own 24h role on deployments whose setup.sh
+	// predates the sso-app role (re-running setup.sh creates it).
+	let minted;
+	try {
+		minted = await mintToken([`app-${name}`], 'sso-app');
+	} catch (e) {
+		console.warn(`vault_broker: sso-app token role unavailable (${e.message}); falling back to sso-broker (24h period). Re-run theta-env setup.sh to create the sso-app role.`);
+		minted = await mintToken([`app-${name}`]);
+	}
+	const { token, accessor, ttl } = minted;
+	// Replace the app's accessor row; revoke the superseded token (best-effort —
+	// it may already be expired) so re-minting never leaves a zombie credential.
+	try {
+		const existing = await VaultAppToken.getByName(name);
+		if (existing) {
+			await baoConf.request('POST', 'auth/token/revoke-accessor', { accessor: existing.accessor });
+			await existing.delete();
+		}
+		if (accessor) {
+			await VaultAppToken.create({
+				name, accessor,
+				lastRenewedAt: Date.now(),
+				created_by: actorUid, created_on: Date.now(),
+			});
+		}
+	} catch (e) {
+		// Accessor bookkeeping must never block handing the token out; without a
+		// row the token simply isn't auto-renewed (it still lives one full period).
+		console.error(`vault_broker: could not store accessor for app-${name}:`, e.message);
+	}
 	return { token, ttl, policy: `app-${name}`, path: `secret/apps/${name}/` };
 }
 
+// ── App-token renewal loop ──────────────────────────────────────────────────
+// Walks the stored accessors and renews each token (auth/token/renew-accessor),
+// resetting its periodic clock. Runs at boot and then every RENEW_INTERVAL_MS —
+// far inside both possible periods (24h fallback and 768h), so a downstream
+// app's token stays valid for as long as sso is running. Failures are recorded
+// on the row (visible to admins in the DB / future UI) and never throw.
+const RENEW_INTERVAL_MS = 6 * 60 * 60 * 1000; // 6h — several chances per 24h period
+let renewTimer;
+
+async function renewAppTokens() {
+	let rows;
+	try { rows = await VaultAppToken.list(); }
+	catch (e) { console.error('vault_broker: app-token renewal: could not list accessors:', e.message); return; }
+	for (const row of rows) {
+		try {
+			const res = await baoConf.request('POST', 'auth/token/renew-accessor', { accessor: row.accessor });
+			if (res.ok) {
+				await row.update({ lastRenewedAt: Date.now(), lastError: null });
+			} else {
+				const text = await res.text().catch(() => '');
+				// 400 "invalid accessor" = token expired or was revoked out-of-band;
+				// keep the row + error so the admin can see the app needs a re-mint.
+				await row.update({ lastError: `renew failed (${res.status}) ${text}` });
+				console.warn(`vault_broker: renew of app token '${row.name}' failed (${res.status}) — re-mint it from the vault UI if the app is still in use.`);
+			}
+		} catch (e) {
+			try { await row.update({ lastError: e.message }); } catch (e2) { /* best-effort */ }
+			console.error(`vault_broker: renew of app token '${row.name}' errored:`, e.message);
+		}
+	}
+}
+
+// Start the loop (idempotent). unref() so an open handle never blocks exit.
+function startAppTokenRenewal() {
+	if (renewTimer) return renewTimer;
+	renewAppTokens().catch((e) => console.error('vault_broker: initial app-token renewal failed:', e.message));
+	renewTimer = setInterval(() => {
+		renewAppTokens().catch((e) => console.error('vault_broker: app-token renewal failed:', e.message));
+	}, RENEW_INTERVAL_MS);
+	if (renewTimer.unref) renewTimer.unref();
+	return renewTimer;
+}
+
+// ── Grant / revoke shared-secret access ─────────────────────────────────────
+// Creating a grant writes the DB row and then edits the grantee's policy content
+// to add read on the shared path; revoking removes both. Because OpenBao parses
+// policy content live, the change applies to the grantee's existing token
+// immediately — no token re-mint, no cache invalidation needed.
+async function grantSharedSecret(secretId, granteeType, granteeId, actorUid) {
+	const grant = await SharedSecretGrant.create({
+		secretId, granteeType, granteeId, capability: 'read',
+		created_by: actorUid, created_on: Date.now(),
+		updated_by: actorUid, updated_on: Date.now(),
+	});
+	await reconcileGrantee(granteeType, granteeId);
+	return grant;
+}
+
+async function revokeSharedSecret(grantId, actorUid) {
+	const grant = await SharedSecretGrant.get(grantId);
+	if (!grant) return null;
+	const { granteeType, granteeId } = grant;
+	await grant.delete();
+	await reconcileGrantee(granteeType, granteeId);
+	return grant;
+}
+
+// Recompute and rewrite a grantee's policy content after a grant/revoke.
+async function reconcileGrantee(granteeType, granteeId) {
+	if (granteeType === 'user') {
+		await ensurePolicy(`user-${granteeId}`, await userPolicyHcl(granteeId));
+	} else if (granteeType === 'app') {
+		await ensurePolicy(`app-${granteeId}`, await appPolicyHcl(granteeId));
+	} else {
+		throw new Error(`invalid granteeType: ${granteeType}`);
+	}
+}
+
 // ── /api/vault proxy: scope guard + token-injecting proxy ───────────────────
 // Replaces the old bare pass-through (which sent no X-Vault-Token and gated
 // nothing). The guard mints a server-side token for the user (per-user or
@@ -145,11 +320,12 @@ async function mintAppToken(name) {
 // client's sso auth headers so OpenBao never sees them.
 
 const VAULT_ADDR = process.env.VAULT_ADDR || 'http://openbao:8200';
+const ADMIN_GROUPS = ['app_sso_admin', 'app_super_admin', 'app_sso_directory_admin'];
 const ADMIN_GROUP = 'app_sso_admin';
 
 async function isAdmin(user) {
 	try {
-		await permission.byGroup(user, [ADMIN_GROUP]);
+		await permission.byGroup(user, ADMIN_GROUPS);
 		return true;
 	} catch (e) {
 		return false;
@@ -178,17 +354,13 @@ async function scopeGuard(req, res, next) {
 		return res.status(503).json({ error: 'vault broker unavailable', detail: e.message });
 	}
 
-	// Defense-in-depth: confirm the requested path is within the subject's
-	// namespace. Admins roam all of secret/; users are confined to
-	// secret/users/<uid>/. (The token's own policy enforces the same at the
-	// OpenBao layer; this catches a buggy/malicious client early with a clear
-	// 403 instead of an opaque OpenBao denial.)
 	const norm = normalizeVaultPath(req.path);
 	if (norm === null) {
 		return res.status(403).json({ error: 'vault paths must be under /secret/' });
 	}
-	const base = `/secret/users/${uid}`;
-	const allowed = admin || norm === base || norm.startsWith(base + '/');
+	const userBase = `/secret/users/${uid}`;
+	const sharedBase = `/secret/shared`;
+	const allowed = admin || norm === userBase || norm.startsWith(userBase + '/') || norm === sharedBase || norm.startsWith(sharedBase + '/');
 	if (!allowed) {
 		return res.status(403).json({ error: 'path outside your vault namespace' });
 	}
@@ -203,15 +375,20 @@ function vaultProxy() {
 		target: VAULT_ADDR,
 		changeOrigin: true,
 		pathRewrite: { '^/api/vault': '/v1' },
-		on: {
-			proxyReq(proxyReq, req, res, options) {
-				fixRequestBody(proxyReq, req, res, options);
-				// Inject ONLY the server-minted scoped token; strip the client's
-				// sso session/api auth so it never reaches OpenBao.
-				proxyReq.setHeader('X-Vault-Token', req.vaultToken);
-				proxyReq.removeHeader('auth-token');
-				proxyReq.removeHeader('authorization');
-			},
+		// http-proxy-middleware v2 API: hooks are top-level onProxyReq/onError,
+		// NOT the v3 `on: { proxyReq }` shape. v2 silently ignores an `on` key,
+		// which shipped this proxy with NO token injection — every /api/vault
+		// call reached OpenBao unauthenticated and 403'd.
+		onProxyReq(proxyReq, req, res, options) {
+			// Header ops MUST precede fixRequestBody: it write()s the parsed body
+			// onto proxyReq, which flushes headers — setHeader after that throws
+			// (swallowed upstream), silently dropping the token on every write.
+			// Inject ONLY the server-minted scoped token; strip the client's
+			// sso session/api auth so it never reaches OpenBao.
+			proxyReq.setHeader('X-Vault-Token', req.vaultToken);
+			proxyReq.removeHeader('auth-token');
+			proxyReq.removeHeader('authorization');
+			fixRequestBody(proxyReq, req, res, options);
 		},
 	});
 }
@@ -225,7 +402,7 @@ mintAppRouter.post('/', async (req, res, next) => {
 		await permission.byGroup(req.user, [ADMIN_GROUP]);
 		const name = (req.body && req.body.name || '').trim();
 		if (!name) return res.status(400).json({ error: 'name is required' });
-		const result = await mintAppToken(name);
+		const result = await mintAppToken(name, req.user && req.user.uid);
 		res.json(result);
 	} catch (e) {
 		if (e.status === 401) return res.status(403).json({ error: 'admin only' });
@@ -233,6 +410,27 @@ mintAppRouter.post('/', async (req, res, next) => {
 	}
 });
 
+// List the minted external-app tokens (metadata only — the token itself is shown
+// once at mint and never stored; the accessor is a renewal/revoke handle and is
+// never exposed). Lets the Apps tab show what has been minted instead of a
+// credential vanishing into the void.
+mintAppRouter.get('/', async (req, res, next) => {
+	try {
+		await permission.byGroup(req.user, [ADMIN_GROUP]);
+		const rows = await VaultAppToken.list();
+		res.json({ apps: rows.map((r) => ({
+			name: r.name,
+			createdBy: r.created_by,
+			createdOn: r.created_on,
+			lastRenewedAt: r.lastRenewedAt || null,
+			lastError: r.lastError || null,
+		})) });
+	} catch (e) {
+		if (e.status === 401) return res.status(403).json({ error: 'admin only' });
+		next(e);
+	}
+});
+
 module.exports = {
 	getOrCreateUserToken,
 	getOrCreateAdminToken,
@@ -241,4 +439,16 @@ module.exports = {
 	scopeGuard,
 	vaultProxy,
 	mintAppRouter,
-};
+	// app-token lifecycle
+	renewAppTokens,
+	startAppTokenRenewal,
+	VaultAppToken,
+	// sharing
+	SharedSecret,
+	SharedSecretGrant,
+	userPolicyHcl,
+	appPolicyHcl,
+	grantSharedSecret,
+	revokeSharedSecret,
+	reconcileGrantee,
+};

nodejs/views/conf.ejs

@@ -1,11 +1,16 @@
 <%- include('top') %>
+
 <script type="text/javascript">
 	app.auth.forceLogin(['admin', 'app_sso_admin']);
 
+	var messagingTypes = {};
+	var messagingPlugins = [];
+
 	$(document).ready(function() {
 		loadConf();
 		loadProxyConf();
 		loadTos();
+		loadMessagingPlugins();
 	});
 
 	async function loadConf() {
@@ -44,8 +49,8 @@
 
 	async function saveConf() {
 		const btn = $('#btn-save');
-		btn.prop('disabled', true).html('<i class="fas fa-spinner fa-spin"></i> Saving...');
-		
+		btn.prop('disabled', true).html('<i class="fas fa-spinner fa-spin me-1"></i> Saving...');
+
 		const payload = {
 			smtp: {
 				host: $('#smtp-host').val(),
@@ -72,14 +77,77 @@
 
 		try {
 			await app.api.post('conf', payload);
-			app.messages.toast('Configuration saved successfully! It will take effect immediately.', 'success');
+			app.messages.toast('Configuration saved successfully!', 'success');
 		} catch (error) {
 			app.messages.toast('Failed to save configuration: ' + error.message, 'danger');
 		} finally {
-			btn.prop('disabled', false).html('<i class="fas fa-save"></i> Save Configuration');
+			btn.prop('disabled', false).html('<i class="fas fa-save me-1"></i> Save Configuration');
 		}
 	}
-	
+
+	async function sendTestEmail() {
+		const to = $('#test-email-to').val().trim();
+		if (!to) {
+			app.messages.toast('Please enter a recipient email address', 'warning');
+			return;
+		}
+
+		const btn = $('#btn-test-email');
+		const originalHtml = btn.html();
+		btn.prop('disabled', true).html('<i class="fas fa-spinner fa-spin me-1"></i> Sending...');
+
+		try {
+			const payload = {
+				smtp: {
+					host: $('#smtp-host').val(),
+					port: parseInt($('#smtp-port').val(), 10) || 587,
+					user: $('#smtp-user').val(),
+					pass: $('#smtp-pass').val(),
+					from: $('#smtp-from').val(),
+					secure: $('#smtp-secure').is(':checked')
+				}
+			};
+			await app.api.post('conf', payload);
+			const result = await app.api.post('conf/test-email', { to });
+			app.messages.toast(result.message || 'Test email sent!', 'success');
+			$('#test-email-to').val('');
+		} catch (error) {
+			app.messages.toast('Failed to send test email: ' + (error.message || 'Unknown error'), 'danger');
+		} finally {
+			btn.prop('disabled', false).html(originalHtml);
+		}
+	}
+
+	async function sendTestSms() {
+		const to = $('#test-sms-to').val().trim();
+		if (!to) {
+			app.messages.toast('Please enter a recipient phone number', 'warning');
+			return;
+		}
+
+		const btn = $('#btn-test-sms');
+		const originalHtml = btn.html();
+		btn.prop('disabled', true).html('<i class="fas fa-spinner fa-spin me-1"></i> Sending...');
+
+		try {
+			const payload = {
+				voipms: {
+					username: $('#voipms-username').val(),
+					did: $('#voipms-did').val(),
+					password: $('#voipms-password').val()
+				}
+			};
+			await app.api.post('conf', payload);
+			const result = await app.api.post('conf/test-sms', { to });
+			app.messages.toast(result.message || 'Test SMS sent!', 'success');
+			$('#test-sms-to').val('');
+		} catch (error) {
+			app.messages.toast('Failed to send test SMS: ' + (error.message || 'Unknown error'), 'danger');
+		} finally {
+			btn.prop('disabled', false).html(originalHtml);
+		}
+	}
+
 	function togglePassword(id) {
 		const el = document.getElementById(id);
 		if (el.type === 'password') {
@@ -107,7 +175,7 @@
 
 	async function saveProxyConf() {
 		const btn = $('#btn-save-proxy');
-		btn.prop('disabled', true).html('<i class="fas fa-spinner fa-spin"></i> Saving...');
+		btn.prop('disabled', true).html('<i class="fas fa-spinner fa-spin me-1"></i> Saving...');
 		
 		const payload = {
 			oidc: {
@@ -126,22 +194,18 @@
 		} catch (error) {
 			app.messages.toast('Failed to save Proxy configuration: ' + error.message, 'danger');
 		} finally {
-			btn.prop('disabled', false).html('<i class="fas fa-save"></i> Save Proxy Secrets');
+			btn.prop('disabled', false).html('<i class="fas fa-save me-1"></i> Save Proxy Secrets');
 		}
 	}
 
-	// ── Terms of Service editor ──────────────────────────────────────────
-	// Moved here from the admin Overview dashboard — it's a configuration
-	// control, so it belongs on the System Configuration page. The API is
-	// routes/tos.js (GET to read, PUT to save; PUT is app_sso_admin-gated, which
-	// matches this page's gate). app.tos.get/update are the shared frontend
-	// helpers (@simpleworkjs/frontend).
 	async function loadTos() {
 		try {
 			const tos = await app.tos.get();
-			document.getElementById('tos-content').value = tos.content;
-			document.getElementById('tos-meta').textContent =
-				'Last updated ' + moment(tos.updated_on, 'x').fromNow() + ' by ' + tos.updated_by;
+			if (tos && tos.content) {
+				document.getElementById('tos-content').value = tos.content;
+				document.getElementById('tos-meta').textContent =
+					'Last updated ' + moment(tos.updated_on, 'x').fromNow() + ' by ' + tos.updated_by;
+			}
 		} catch(e) {
 			console.error('Failed to load ToS:', e);
 		}
@@ -173,203 +237,287 @@
 			loadTos();
 		});
 	}
+
+	// ── Messaging Plugins ──────────────────────────────────────────────
+	function loadMessagingPlugins() {
+		app.api.get('plugins/types', function(err, res) {
+			if (!err && res && res.results) {
+				(res.results || []).forEach(t => { messagingTypes[t.type] = t; });
+			}
+			app.api.get('plugins', function(err, res) {
+				if (err) return;
+				messagingPlugins = (res.results || []).filter(p => p.category === 'messaging');
+				renderMessagingPlugins();
+			});
+		});
+	}
+
+	function renderMessagingPlugins() {
+		const $list = $('#messaging-plugins-list').empty();
+		if (messagingPlugins.length === 0) {
+			$list.append('<div class="text-muted text-center py-4"><i class="fas fa-plug text-black-50 fs-2 mb-2"></i><br>No messaging plugins configured.</div>');
+			return;
+		}
+		messagingPlugins.forEach(p => {
+			const badgeClass = p.enabled ? 'bg-success' : 'bg-secondary';
+			const statusText = p.enabled ? 'Loaded' : 'Unloaded';
+			const card = `
+				<div class="card mb-3 border shadow-sm">
+					<div class="card-body d-flex align-items-center justify-content-between">
+						<div>
+							<h6 class="mb-1"><strong>${p.name}</strong> <span class="badge bg-secondary ms-2">${p.pluginType}</span></h6>
+							<div class="small text-muted font-monospace">${p.slug} | Schedule: ${p.cron}</div>
+						</div>
+						<div class="d-flex align-items-center gap-2">
+							<span class="badge ${badgeClass} me-2">${statusText}</span>
+							<button class="btn btn-sm btn-outline-primary" onclick="togglePlugin('${p.id}', ${!p.enabled})">${p.enabled ? 'Unload' : 'Load'}</button>
+							<button class="btn btn-sm btn-outline-danger" onclick="deletePlugin('${p.id}')"><i class="fas fa-trash"></i></button>
+						</div>
+					</div>
+				</div>
+			`;
+			$list.append(card);
+		});
+	}
+
+	async function togglePlugin(id, state) {
+		const endpoint = state ? 'load' : 'unload';
+		try {
+			await app.api.post(`plugins/${id}/${endpoint}`, {});
+			app.messages.toast(`Plugin ${state ? 'loaded' : 'unloaded'} successfully`, 'success');
+			loadMessagingPlugins();
+		} catch (e) {
+			app.messages.toast('Error toggling plugin: ' + e.message, 'danger');
+		}
+	}
+
+	async function deletePlugin(id) {
+		const ok = await app.messages.confirm('Are you sure you want to delete this plugin instance?');
+		if (!ok) return;
+		try {
+			await app.api.delete(`plugins/${id}`);
+			app.messages.toast('Plugin deleted', 'success');
+			loadMessagingPlugins();
+		} catch (e) {
+			app.messages.toast('Error deleting plugin: ' + e.message, 'danger');
+		}
+	}
 </script>
 
-<div class="container py-4">
-	<div class="row mb-4">
-		<div class="col d-flex justify-content-between align-items-center">
-			<div>
-				<h2><i class="fas fa-cogs"></i> System Configuration</h2>
-				<p class="text-muted mb-0">
-					Manage runtime configuration such as SMTP, SMS, OAuth, and Terms of Service
-					settings. These are stored securely in OpenBao and take effect immediately.
-					Secret fields (the SMTP password, OAuth JWT secret, and VoIP.ms API password)
-					are masked — leave them unchanged to keep the stored value.
-				</p>
-			</div>
-			<div>
-				<button class="btn btn-secondary me-2" onclick="loadConf()"><i class="fas fa-undo"></i> Reset</button>
-				<button id="btn-save" class="btn btn-primary" onclick="saveConf()"><i class="fas fa-save"></i> Save Configuration</button>
-			</div>
-		</div>
-	</div>
-
-	<ul class="nav nav-tabs mb-4" id="confTabs" role="tablist">
-		<li class="nav-item" role="presentation">
-			<button class="nav-link active" id="smtp-tab" data-bs-toggle="tab" data-bs-target="#smtp" type="button" role="tab">SMTP Settings</button>
-		</li>
-		<li class="nav-item" role="presentation">
-			<button class="nav-link" id="oauth-tab" data-bs-toggle="tab" data-bs-target="#oauth" type="button" role="tab">OAuth & JWT</button>
-		</li>
-		<li class="nav-item" role="presentation">
-			<button class="nav-link" id="sms-tab" data-bs-toggle="tab" data-bs-target="#sms" type="button" role="tab">SMS (VoIP.ms)</button>
-		</li>
-		<li class="nav-item" role="presentation">
-			<button class="nav-link" id="tos-tab" data-bs-toggle="tab" data-bs-target="#tos" type="button" role="tab">Terms of Service</button>
-		</li>
-		<li class="nav-item" role="presentation">
-			<button class="nav-link" id="proxy-tab" data-bs-toggle="tab" data-bs-target="#proxy" type="button" role="tab">Proxy Secrets</button>
-		</li>
-	</ul>
-
-	<div class="tab-content" id="confTabsContent">
-		<!-- SMTP Tab -->
-		<div class="tab-pane fade show active" id="smtp" role="tabpanel">
-			<div class="card shadow-sm border-0 mb-4">
-				<div class="card-header bg-white border-bottom-0 pt-4 pb-0">
-					<h5 class="mb-0"><i class="fas fa-envelope text-primary me-2"></i> SMTP Settings</h5>
+<div class="container mt-4">
+	<div class="row">
+		<div class="col-12">
+			<div class="card shadow">
+				<!-- Header with Sub-Nav Tabs matching directory.ejs -->
+				<div class="card-header d-flex flex-wrap justify-content-between align-items-center gap-2">
+					<ul class="nav nav-tabs card-header-tabs" id="confTabs" role="tablist">
+						<li class="nav-item" role="presentation">
+							<button class="nav-link active" id="oauth-tab" data-bs-toggle="tab" data-bs-target="#pane-oauth" type="button" role="tab">
+								<i class="fas fa-key text-success me-1"></i> OAuth & JWT
+							</button>
+						</li>
+						<li class="nav-item" role="presentation">
+							<button class="nav-link" id="smtp-tab" data-bs-toggle="tab" data-bs-target="#pane-smtp" type="button" role="tab">
+								<i class="fas fa-envelope text-primary me-1"></i> Email (SMTP)
+							</button>
+						</li>
+						<li class="nav-item" role="presentation">
+							<button class="nav-link" id="sms-tab" data-bs-toggle="tab" data-bs-target="#pane-sms" type="button" role="tab">
+								<i class="fas fa-comment-sms text-info me-1"></i> SMS & Messaging
+							</button>
+						</li>
+						<li class="nav-item" role="presentation">
+							<button class="nav-link" id="proxy-tab" data-bs-toggle="tab" data-bs-target="#pane-proxy" type="button" role="tab">
+								<i class="fas fa-shield-alt text-warning me-1"></i> Proxy Secrets
+							</button>
+						</li>
+						<li class="nav-item" role="presentation">
+							<button class="nav-link" id="tos-tab" data-bs-toggle="tab" data-bs-target="#pane-tos" type="button" role="tab">
+								<i class="fas fa-file-contract text-secondary me-1"></i> Terms of Service
+							</button>
+						</li>
+					</ul>
+					<div>
+						<button class="btn btn-sm btn-outline-secondary me-1" onclick="loadConf()"><i class="fas fa-rotate me-1"></i> Reset</button>
+						<button id="btn-save" class="btn btn-sm btn-primary" onclick="saveConf()"><i class="fas fa-save me-1"></i> Save Configuration</button>
+					</div>
 				</div>
-				<div class="card-body">
-					<div class="mb-3">
-						<label class="form-label">Host</label>
-						<input type="text" class="form-control" id="smtp-host">
-					</div>
-					<div class="mb-3">
-						<label class="form-label">Port</label>
-						<input type="number" class="form-control" id="smtp-port">
-					</div>
-					<div class="mb-3">
-						<label class="form-label">User</label>
-						<input type="text" class="form-control" id="smtp-user">
-					</div>
-					<div class="mb-3">
-						<label class="form-label">Password</label>
-						<div class="input-group">
-							<input type="password" class="form-control" id="smtp-pass" placeholder="********">
-							<button class="btn btn-outline-secondary" type="button" onclick="togglePassword('smtp-pass')"><i class="fas fa-eye"></i></button>
+
+				<div class="card-body p-4">
+					<div class="tab-content" id="confTabContent">
+						
+						<!-- OAuth & JWT Tab -->
+						<div class="tab-pane fade show active" id="pane-oauth" role="tabpanel">
+							<h5 class="fw-bold mb-3"><i class="fas fa-key text-success me-2"></i> OAuth 2.0 & JWT Settings</h5>
+							<p class="text-muted small">Configure OIDC issuer URLs, token lifetimes, and JWT signing keys. Stored in OpenBao.</p>
+							<div class="mb-3">
+								<label class="form-label fw-semibold">Issuer URL</label>
+								<input type="text" class="form-control" id="oauth-issuer" placeholder="https://sso.example.com">
+							</div>
+							<div class="mb-3">
+								<label class="form-label fw-semibold">JWT Secret</label>
+								<div class="input-group">
+									<input type="password" class="form-control" id="oauth-jwtsecret" placeholder="********">
+									<button class="btn btn-outline-secondary" type="button" onclick="togglePassword('oauth-jwtsecret')"><i class="fas fa-eye"></i></button>
+								</div>
+								<div class="form-text">Stored in OpenBao. Leave unchanged to preserve stored value.</div>
+							</div>
+							<div class="row">
+								<div class="col-md-6 mb-3">
+									<label class="form-label fw-semibold">Access Token Lifetime (seconds)</label>
+									<input type="number" class="form-control" id="oauth-token-access" placeholder="3600">
+								</div>
+								<div class="col-md-6 mb-3">
+									<label class="form-label fw-semibold">Refresh Token Lifetime (seconds)</label>
+									<input type="number" class="form-control" id="oauth-token-refresh" placeholder="2592000">
+								</div>
+							</div>
 						</div>
-						<div class="form-text">Leave unchanged to keep the current password stored in OpenBao. Clear and type a new value to replace it.</div>
-					</div>
-					<div class="mb-3">
-						<label class="form-label">From Address</label>
-						<input type="text" class="form-control" id="smtp-from">
-					</div>
-					<div class="form-check">
-						<input class="form-check-input" type="checkbox" id="smtp-secure">
-						<label class="form-check-label">Use Secure (TLS)</label>
-					</div>
-				</div>
-			</div>
-		</div>
 
-		<!-- OAuth Tab -->
-		<div class="tab-pane fade" id="oauth" role="tabpanel">
-			<div class="card shadow-sm border-0 mb-4">
-				<div class="card-header bg-white border-bottom-0 pt-4 pb-0">
-					<h5 class="mb-0"><i class="fas fa-key text-success me-2"></i> OAuth & JWT Settings</h5>
-				</div>
-				<div class="card-body">
-					<div class="mb-3">
-						<label class="form-label">Issuer URL</label>
-						<input type="text" class="form-control" id="oauth-issuer">
-					</div>
-					<div class="mb-3">
-						<label class="form-label">JWT Secret</label>
-						<div class="input-group">
-							<input type="password" class="form-control" id="oauth-jwtsecret" placeholder="********">
-							<button class="btn btn-outline-secondary" type="button" onclick="togglePassword('oauth-jwtsecret')"><i class="fas fa-eye"></i></button>
+						<!-- SMTP Tab -->
+						<div class="tab-pane fade" id="pane-smtp" role="tabpanel">
+							<h5 class="fw-bold mb-3"><i class="fas fa-envelope text-primary me-2"></i> SMTP Server Settings</h5>
+							<p class="text-muted small">System mail server credentials for password resets, notifications, and verification emails.</p>
+							<div class="row">
+								<div class="col-md-8 mb-3">
+									<label class="form-label fw-semibold">SMTP Host</label>
+									<input type="text" class="form-control" id="smtp-host" placeholder="smtp.example.com">
+								</div>
+								<div class="col-md-4 mb-3">
+									<label class="form-label fw-semibold">Port</label>
+									<input type="number" class="form-control" id="smtp-port" placeholder="587">
+								</div>
+							</div>
+							<div class="row">
+								<div class="col-md-6 mb-3">
+									<label class="form-label fw-semibold">User</label>
+									<input type="text" class="form-control" id="smtp-user">
+								</div>
+								<div class="col-md-6 mb-3">
+									<label class="form-label fw-semibold">Password</label>
+									<div class="input-group">
+										<input type="password" class="form-control" id="smtp-pass" placeholder="********">
+										<button class="btn btn-outline-secondary" type="button" onclick="togglePassword('smtp-pass')"><i class="fas fa-eye"></i></button>
+									</div>
+								</div>
+							</div>
+							<div class="mb-3">
+								<label class="form-label fw-semibold">From Address</label>
+								<input type="text" class="form-control" id="smtp-from" placeholder="noreply@example.com">
+							</div>
+							<div class="form-check mb-4">
+								<input class="form-check-input" type="checkbox" id="smtp-secure">
+								<label class="form-check-label fw-semibold" for="smtp-secure">Use Secure TLS Connection</label>
+							</div>
+
+							<div class="p-3 bg-light rounded border">
+								<h6 class="fw-bold mb-2"><i class="fas fa-paper-plane text-primary me-2"></i> Send Test Email</h6>
+								<div class="input-group">
+									<input type="email" class="form-control" id="test-email-to" placeholder="recipient@example.com">
+									<button id="btn-test-email" class="btn btn-outline-primary" type="button" onclick="sendTestEmail()">
+										<i class="fas fa-paper-plane me-1"></i> Send Test Email
+									</button>
+								</div>
+								<div class="form-text">Saves current SMTP config and sends a test message.</div>
+							</div>
 						</div>
-						<div class="form-text">Leave unchanged to keep the current secret stored in OpenBao. Clear and type a new value to replace it.</div>
-					</div>
-					<div class="mb-3">
-						<label class="form-label">Access Token Lifetime (seconds)</label>
-						<input type="number" class="form-control" id="oauth-token-access">
-					</div>
-					<div class="mb-3">
-						<label class="form-label">Refresh Token Lifetime (seconds)</label>
-						<input type="number" class="form-control" id="oauth-token-refresh">
-					</div>
-				</div>
-			</div>
-		</div>
 
-		<!-- SMS Tab -->
-		<div class="tab-pane fade" id="sms" role="tabpanel">
-			<div class="card shadow-sm border-0 mb-4">
-				<div class="card-header bg-white border-bottom-0 pt-4 pb-0">
-					<h5 class="mb-0"><i class="fas fa-comment text-info me-2"></i> SMS (VoIP.ms)</h5>
-				</div>
-				<div class="card-body">
-					<p class="form-text">Used to deliver SMS 2FA login codes. The API password is stored in OpenBao and masked below.</p>
-					<div class="mb-3">
-						<label class="form-label">API Username</label>
-						<input type="text" class="form-control" id="voipms-username">
-					</div>
-					<div class="mb-3">
-						<label class="form-label">DID (sender number)</label>
-						<input type="text" class="form-control" id="voipms-did" placeholder="15551234567">
-					</div>
-					<div class="mb-3">
-						<label class="form-label">API Password</label>
-						<div class="input-group">
-							<input type="password" class="form-control" id="voipms-password" placeholder="********">
-							<button class="btn btn-outline-secondary" type="button" onclick="togglePassword('voipms-password')"><i class="fas fa-eye"></i></button>
+						<!-- SMS & Messaging Tab -->
+						<div class="tab-pane fade" id="pane-sms" role="tabpanel">
+							<h5 class="fw-bold mb-3"><i class="fas fa-comment-sms text-info me-2"></i> VoIP.ms SMS Integration</h5>
+							<p class="text-muted small">Configure VoIP.ms API credentials for delivering SMS 2FA codes.</p>
+							<div class="row">
+								<div class="col-md-6 mb-3">
+									<label class="form-label fw-semibold">API Username</label>
+									<input type="text" class="form-control" id="voipms-username">
+								</div>
+								<div class="col-md-6 mb-3">
+									<label class="form-label fw-semibold">DID Sender Number</label>
+									<input type="text" class="form-control" id="voipms-did" placeholder="15551234567">
+								</div>
+							</div>
+							<div class="mb-3">
+								<label class="form-label fw-semibold">API Password</label>
+								<div class="input-group">
+									<input type="password" class="form-control" id="voipms-password" placeholder="********">
+									<button class="btn btn-outline-secondary" type="button" onclick="togglePassword('voipms-password')"><i class="fas fa-eye"></i></button>
+								</div>
+							</div>
+
+							<div class="p-3 bg-light rounded border mb-4">
+								<h6 class="fw-bold mb-2"><i class="fas fa-paper-plane text-info me-2"></i> Send Test SMS</h6>
+								<div class="input-group">
+									<input type="tel" class="form-control" id="test-sms-to" placeholder="+15551234567">
+									<button id="btn-test-sms" class="btn btn-outline-info" type="button" onclick="sendTestSms()">
+										<i class="fas fa-paper-plane me-1"></i> Send Test SMS
+									</button>
+								</div>
+							</div>
+
+							<hr class="my-4">
+
+							<div class="d-flex justify-content-between align-items-center mb-3">
+								<h5 class="mb-0 fw-bold"><i class="fas fa-plug text-primary me-2"></i> Messaging Plugins & Webhooks</h5>
+								<button class="btn btn-sm btn-outline-primary" onclick="loadMessagingPlugins()"><i class="fas fa-rotate"></i> Refresh</button>
+							</div>
+							<div id="messaging-plugins-list"></div>
 						</div>
-						<div class="form-text">Leave unchanged to keep the current password stored in OpenBao. Clear and type a new value to replace it.</div>
-					</div>
-				</div>
-			</div>
-		</div>
 
-		<!-- Proxy Secrets Tab -->
-		<div class="tab-pane fade" id="proxy" role="tabpanel">
-			<div class="card shadow-sm border-0 mb-4">
-				<div class="card-header bg-white border-bottom-0 pt-4 pb-0">
-					<h5 class="mb-0"><i class="fas fa-shield-alt text-warning me-2"></i> Proxy Secrets (OpenBao)</h5>
-				</div>
-				<div class="card-body">
-					<p class="form-text">These secrets are stored directly in OpenBao (`secret/proxy/conf`) and read by the Proxy at boot.</p>
-					
-					<h6 class="mt-3 mb-2">OAuth / OIDC Integration</h6>
-					<div class="mb-3">
-						<label class="form-label">Issuer URL</label>
-						<input type="text" class="form-control" id="proxy-issuer" placeholder="https://sso.example.com">
-					</div>
-					<div class="mb-3">
-						<label class="form-label">Client ID</label>
-						<input type="text" class="form-control" id="proxy-client-id">
-					</div>
-					<div class="mb-3">
-						<label class="form-label">Client Secret</label>
-						<div class="input-group">
-							<input type="password" class="form-control" id="proxy-client-secret" placeholder="********">
-							<button class="btn btn-outline-secondary" type="button" onclick="togglePassword('proxy-client-secret')"><i class="fas fa-eye"></i></button>
+						<!-- Proxy Secrets Tab -->
+						<div class="tab-pane fade" id="pane-proxy" role="tabpanel">
+							<h5 class="fw-bold mb-3"><i class="fas fa-shield-alt text-warning me-2"></i> OpenBao Proxy Integration</h5>
+							<p class="text-muted small">Secrets stored directly in OpenBao (<code>secret/proxy/conf</code>) and consumed by Proxy at boot.</p>
+							
+							<h6 class="fw-bold text-dark mt-3 mb-2">OAuth / OIDC Client</h6>
+							<div class="mb-3">
+								<label class="form-label fw-semibold">Issuer URL</label>
+								<input type="text" class="form-control" id="proxy-issuer" placeholder="https://sso.example.com">
+							</div>
+							<div class="row">
+								<div class="col-md-6 mb-3">
+									<label class="form-label fw-semibold">Client ID</label>
+									<input type="text" class="form-control" id="proxy-client-id">
+								</div>
+								<div class="col-md-6 mb-3">
+									<label class="form-label fw-semibold">Client Secret</label>
+									<div class="input-group">
+										<input type="password" class="form-control" id="proxy-client-secret" placeholder="********">
+										<button class="btn btn-outline-secondary" type="button" onclick="togglePassword('proxy-client-secret')"><i class="fas fa-eye"></i></button>
+									</div>
+								</div>
+							</div>
+
+							<h6 class="fw-bold text-dark mt-4 mb-2">LDAP Bind Account</h6>
+							<div class="mb-3">
+								<label class="form-label fw-semibold">Proxy Bind Password</label>
+								<div class="input-group">
+									<input type="password" class="form-control" id="proxy-ldap-bindpass" placeholder="********">
+									<button class="btn btn-outline-secondary" type="button" onclick="togglePassword('proxy-ldap-bindpass')"><i class="fas fa-eye"></i></button>
+								</div>
+							</div>
+
+							<button id="btn-save-proxy" class="btn btn-warning mt-2 text-dark fw-semibold" onclick="saveProxyConf()"><i class="fas fa-save me-1"></i> Save Proxy Secrets</button>
 						</div>
-					</div>
 
-					<h6 class="mt-4 mb-2">LDAP Integration</h6>
-					<div class="mb-3">
-						<label class="form-label">Bind Password</label>
-						<div class="input-group">
-							<input type="password" class="form-control" id="proxy-ldap-bindpass" placeholder="********">
-							<button class="btn btn-outline-secondary" type="button" onclick="togglePassword('proxy-ldap-bindpass')"><i class="fas fa-eye"></i></button>
+						<!-- Terms of Service Tab -->
+						<div class="tab-pane fade" id="pane-tos" role="tabpanel">
+							<div class="d-flex justify-content-between align-items-center mb-3">
+								<h5 class="fw-bold mb-0"><i class="fas fa-file-contract me-2"></i> Terms of Service Editor</h5>
+								<span class="small text-muted" id="tos-meta"></span>
+							</div>
+							<div class="mb-3">
+								<label class="form-label fw-semibold">Terms Content (Markdown)</label>
+								<textarea class="form-control font-monospace" id="tos-content" rows="10" placeholder="Enter Terms of Service markdown content..."></textarea>
+							</div>
+							<div class="form-check mb-4">
+								<input class="form-check-input" type="checkbox" id="tos-reset-acceptance">
+								<label class="form-check-label fw-semibold" for="tos-reset-acceptance">Require all users to re-accept these terms upon next login</label>
+							</div>
+							<button class="btn btn-primary" onclick="saveTos()"><i class="fas fa-floppy-disk me-1"></i> Save Terms of Service</button>
+							<div id="tos-result" style="display:none" class="mt-3"></div>
 						</div>
-						<div class="form-text">Password for the Proxy's LDAP service account.</div>
-					</div>
 
-					<button id="btn-save-proxy" class="btn btn-warning mt-2" onclick="saveProxyConf()"><i class="fas fa-save"></i> Save Proxy Secrets</button>
-				</div>
-			</div>
-		</div>
-
-		<!-- ToS Tab -->
-		<div class="tab-pane fade" id="tos" role="tabpanel">
-			<div class="card shadow-sm border-0 mb-4">
-				<div class="card-header bg-white border-bottom-0 pt-4 pb-0 d-flex justify-content-between align-items-center">
-					<h5 class="mb-0"><i class="fas fa-file-contract me-2"></i> Terms of Service</h5>
-					<small class="text-muted" id="tos-meta"></small>
-				</div>
-				<div class="card-body">
-					<div class="mb-3">
-						<label class="form-label">Content <small class="text-muted">(Markdown)</small></label>
-						<textarea class="form-control" id="tos-content" rows="8"></textarea>
 					</div>
-					<div class="form-check mb-3">
-						<input class="form-check-input" type="checkbox" id="tos-reset-acceptance">
-						<label class="form-check-label" for="tos-reset-acceptance">Require all users to re-accept these terms</label>
-					</div>
-					<button class="btn btn-primary" onclick="saveTos()"><i class="fas fa-floppy-disk"></i> Save Terms</button>
-					<div id="tos-result" style="display:none" class="mt-2"></div>
 				</div>
 			</div>
 		</div>

nodejs/views/directory.ejs

@@ -13,7 +13,12 @@
             </li>
             <li class="nav-item" role="presentation">
               <button class="nav-link" id="discovery-tab" data-bs-toggle="tab" data-bs-target="#discovery-tab-pane" type="button" role="tab" aria-controls="discovery-tab-pane" aria-selected="false">
-                <i class="fa-solid fa-network-wired"></i> Discovery
+                <i class="fa-solid fa-network-wired"></i> Discovered Inventory
+              </button>
+            </li>
+            <li class="nav-item" role="presentation">
+              <button class="nav-link" id="plugins-tab" data-bs-toggle="tab" data-bs-target="#plugins-tab-pane" type="button" role="tab" aria-controls="plugins-tab-pane" aria-selected="false">
+                <i class="fa-solid fa-plug"></i> Discovery Plugins
               </button>
             </li>
           </ul>
@@ -25,6 +30,7 @@
 				<div class="card-header d-flex flex-wrap justify-content-between align-items-center gap-2">
 				    <div>
     					<i class="fa-solid fa-server"></i> Directory Management
+    					<a href="/docs/groups" class="text-reset ms-1" title="Group & permission model"><i class="fa-solid fa-circle-question"></i></a>
     				</div>
 					<div class="d-flex flex-wrap gap-2 align-items-center">
                         <input type="text" id="search-filter" class="form-control form-control-sm shadow-sm" placeholder="Search..." onkeyup="renderTable()" style="width: 200px;">
@@ -40,6 +46,9 @@
                             <datalist id="access-uid-list"></datalist>
                             <button class="btn btn-outline-secondary" onclick="openUserAccessModal()">Check</button>
                         </div>
+                        <button class="btn btn-sm btn-outline-primary ms-1 shadow-sm" onclick="openAgentInstallModal()">
+                            <i class="fa-solid fa-shield-halved me-1"></i> Install Agent
+                        </button>
 					    <button class="btn btn-sm btn-primary ms-1 shadow-sm" onclick="openAddModal()">
 					        <i class="fas fa-plus"></i> Add Resource
 					    </button>
@@ -64,6 +73,7 @@
               <tr id="resource-row-{{id}}">
                 <td class="ps-3">
                   {{{indentHtml}}}
+                  {{#isHost}}<span class="d-inline-block rounded-circle me-1" style="width:10px;height:10px;background:{{agentColor}};" title="{{agentStatusTitle}}"></span>{{/isHost}}
                   <span class="badge bg-secondary">{{kind}}{{#metadata.subType}} ({{metadata.subType}}){{/metadata.subType}}</span>
                   {{#metadata.isProduction}}<span class="badge bg-danger">Prod</span>{{/metadata.isProduction}}
                   {{^metadata.isProduction}}<span class="badge bg-info">Dev</span>{{/metadata.isProduction}}
@@ -184,6 +194,23 @@
           </div>
         </div>
       </div>
+
+      <!-- Discovery Plugins Tab Pane -->
+      <div class="tab-pane fade" id="plugins-tab-pane" role="tabpanel" aria-labelledby="plugins-tab">
+        <div class="p-4 bg-white border-top">
+          <div class="d-flex justify-content-between align-items-center mb-3">
+            <div>
+              <h5 class="fw-bold mb-1"><i class="fa-solid fa-plug text-primary me-2"></i> Discovery Plugins</h5>
+              <p class="text-muted small mb-0">Manage background discovery agents (Nmap, Docker, Proxmox, UniFi). Per-instance secrets are stored in OpenBao.</p>
+            </div>
+            <div>
+              <button class="btn btn-sm btn-outline-primary me-2" onclick="loadDiscoveryPlugins()"><i class="fas fa-rotate me-1"></i> Refresh</button>
+              <button class="btn btn-sm btn-primary shadow-sm" onclick="openNewDiscoveryPluginModal()"><i class="fas fa-plus me-1"></i> New Plugin</button>
+            </div>
+          </div>
+          <div id="discovery-plugins-list" class="mt-3"></div>
+        </div>
+      </div>
           </div>
         </div>
       </div>
@@ -210,7 +237,8 @@
       </div>
       <div class="col-6">
         <label class="form-label">Slug</label>
-        <input type="text" id="res-slug" class="form-control shadow-sm font-monospace">
+        <input type="text" id="res-slug" class="form-control shadow-sm font-monospace" readonly>
+        <div class="form-text">Derived from the name; read-only.</div>
       </div>
     </div>
 
@@ -451,6 +479,7 @@
         {id: 'details', label: 'Details', bodyHtml: detailsTabHtml},
         {id: 'groups', label: 'Associated LDAP Groups', bodyHtml: groupsTabHtml},
         {id: 'children', label: 'Children', bodyHtml: childrenTabHtml},
+        {id: 'metrics', label: 'Metrics', bodyHtml: metricsTabHtml(resourcesById[id] && resourcesById[id].agent)},
       ],
       footer: {
         metaHtml: id ? app.modal.formatAudit(resourcesById[id], {formatDate: function(ms){ return moment(ms).format('YYYY-MM-DD HH:mm'); }}) : '',
@@ -486,6 +515,9 @@
   var rawResources = [];
   // resourceId -> { groups: [{cn, accessLevel, exists, memberCount}], memberCount }
   var accessSummary = {};
+  // When set, the resource modal's Save promotes this discovered slug (review
+  // the pre-filled form, then confirm) instead of a normal resource save.
+  var promoteSlug = null;
 
   $(document).ready(async function() {
     await loadResources();
@@ -496,24 +528,43 @@
     }
   });
   
+  // Connected theta-agent join: hostname->agent and token->agent (case-insensitive
+  // hostname). Populated by loadResources/refreshAgents; host rows + the Metrics
+  // tab read from these. Agent data comes from /api/agent/nodes (admin-gated).
+  var agentsByHost = {};
+  var agentsByToken = {};
+  // True when the agent/nodes endpoint itself was unreachable (network, or an
+  // older app without the agent route). When set we cannot tell "this host has
+  // no agent" apart from "the agent service is down", so we must NOT paint every
+  // host red as if it lacked an agent.
+  var agentsUnavailable = false;
+
   async function loadResources() {
     try {
-      const [resResources, resGroups, resEdges, resAccess] = await Promise.all([
+      const [resResources, resGroups, resEdges, resAccess, resAgents] = await Promise.all([
         app.api.get('directory-admin/resources'),
         app.api.get('directory-admin/groups'),
         app.api.get('directory-admin/edges'),
         // Access counts are a nicety, not load-bearing: if the LDAP join fails
         // the table still renders, just without the Access column populated.
-        app.api.get('directory-admin/access-summary').catch(function(){ return {results: {}}; })
+        app.api.get('directory-admin/access-summary').catch(function(){ return {results: {}}; }),
+        // Agents are a nicety too: never block the directory on them. Track
+        // whether the endpoint itself is reachable so host rows can tell "no
+        // agent on this host" from "agent service is down" (see attachAgentStatus).
+        app.api.get('agent/nodes')
+          .then(function(res){ agentsUnavailable = false; return res; })
+          .catch(function(){ agentsUnavailable = true; return {agents: []}; })
       ]);
 
       accessSummary = (resAccess && resAccess.results) || {};
       resourcesById = {};
-      
+
       for (const r of resResources.results) {
         r.metadata = r.metadata || {};
         resourcesById[r.id] = r;
       }
+
+      indexAgents((resAgents && resAgents.agents) || []);
       
       allGroups = resGroups.results;
       allEdges = resEdges.results;
@@ -547,6 +598,88 @@
     }
   }
 
+  // Build the hostname->agent and token->agent lookup maps from /api/agent/nodes.
+  function indexAgents(agents) {
+    agentsByHost = {};
+    agentsByToken = {};
+    for (const a of agents || []) {
+      const hn = (a.hostname || (a.discovery && a.discovery.hostname) || '').toLowerCase();
+      if (hn) agentsByHost[hn] = a;
+      if (a.token) agentsByToken[a.token] = a;
+    }
+  }
+
+  function esc(s) { return s == null ? '' : app.util.escapeHtml(String(s)); }
+  function timeAgo(iso) { if (!iso) return ''; var m = moment(iso); return m.isValid() ? m.fromNow() : ''; }
+
+  // Green (online, healthy) / Yellow (online, high load) / Red (not connected
+  // or offline). Attaches n.isHost + a colored dot + tooltip for host rows, and
+  // stores the agent on resourcesById so the Metrics tab can find it.
+  function attachAgentStatus(n) {
+    n.isHost = true;
+    const name = (n.name || '').toLowerCase();
+    const slug = (n.slug || '').replace(/^host_/, '').toLowerCase();
+    const a = agentsByHost[name] || (slug && agentsByHost[slug]);
+    n.agent = a || null;
+    if (resourcesById[n.id]) resourcesById[n.id].agent = a || null;
+    if (!a) {
+      // Endpoint unreachable: we genuinely don't know -- neutral grey, not a
+      // false red alarm across every host.
+      if (agentsUnavailable) { n.agentColor = '#adb5bd'; n.agentStatusTitle = 'Agent service unreachable'; return; }
+      n.agentColor = '#dc3545'; n.agentStatusTitle = 'No theta-agent connected'; return;
+    }
+    if (!a.isOnline) { n.agentColor = '#dc3545'; n.agentStatusTitle = 'Agent offline (' + (a.hostname || 'unknown') + ')'; return; }
+    const t = a.telemetry || {};
+    const high = (t.cpu_usage_percent > 80) || (t.ram_usage_percent > 80) || (t.disk_usage_percent > 90);
+    n.agentColor = high ? '#ffc107' : '#198754';
+    n.agentStatusTitle = high ? 'Connected — high load' : 'Connected — healthy';
+  }
+
+  // Metrics tab body for the resource modal (snapshot of the joined agent).
+  function metricsTabHtml(agent) {
+    if (!agent) {
+      return '<div class="p-3 text-center text-muted"><i class="fa-solid fa-microchip fa-3x mb-3"></i><h6>No theta-agent connected</h6><p class="small">Install the agent on this host to see live metrics.</p></div>';
+    }
+    const d = agent.discovery || {};
+    const t = agent.telemetry || {};
+    const bar = (val) => `<div class="progress" style="height:8px"><div class="progress-bar" style="width:${Math.max(0, Math.min(100, val || 0))}%"></div></div>`;
+    const online = agent.isOnline ? '<span class="badge bg-success">Online</span>' : '<span class="badge bg-secondary">Offline</span>';
+    const gpu = (t.gpu_usage_percent != null && t.gpu_usage_percent >= 0) ? t.gpu_usage_percent + '%' : 'N/A';
+    return `<div class="p-3">
+      <div class="mb-3 d-flex justify-content-between align-items-center">
+        <h5 class="mb-0">${esc(agent.hostname || 'unknown')} ${online}</h5>
+        <small class="text-muted">Last seen ${timeAgo(agent.lastSeen)}</small>
+      </div>
+      <div class="row g-3">
+        <div class="col-6">CPU <strong>${t.cpu_usage_percent ?? 0}%</strong>${bar(t.cpu_usage_percent)}</div>
+        <div class="col-6">RAM <strong>${t.ram_usage_percent ?? 0}%</strong>${bar(t.ram_usage_percent)}</div>
+        <div class="col-6">Disk <strong>${t.disk_usage_percent ?? 0}%</strong>${bar(t.disk_usage_percent)}</div>
+        <div class="col-6">GPU <strong>${gpu}</strong></div>
+        <div class="col-6">ZFS <strong>${esc(t.zfs_health || 'N/A')}</strong></div>
+      </div>
+      <hr><h6>Discovery</h6>
+      <div class="row small text-muted">
+        <div class="col-6">OS: ${esc(d.os || '')}</div>
+        <div class="col-6">Kernel: ${esc(d.kernel || '')}</div>
+        <div class="col-6">IPs: ${esc((d.ip_addresses || []).join(', '))}</div>
+        <div class="col-6">Location: ${esc(d.location || '')}</div>
+      </div>
+    </div>`;
+  }
+
+  // Re-fetch agents (every 30s + on socket events) so status dots stay live.
+  async function refreshAgents() {
+    try {
+      const res = await app.api.get('agent/nodes');
+      indexAgents((res && res.agents) || []);
+      agentsUnavailable = false;
+      renderTable();
+    } catch (e) {
+      agentsUnavailable = true;
+      renderTable(); // re-render so dots flip to neutral, not stale green
+    }
+  }
+
   // "Who can reach this?" at a glance. A resource with no linked group is not a
   // locked-down resource -- it is an unreachable one, and a group whose LDAP
   // entry has been deleted grants nothing, so both get called out rather than
@@ -654,6 +787,7 @@
          }
          n.indentHtml = indentHtml;
          n.accessHtml = accessCellHtml(n.id);
+         if (n.kind === 'host') attachAgentStatus(n);
          finalRenderList.push(n);
          if (n.children.length > 0) {
            flatten(n.children, depth + 1);
@@ -1048,6 +1182,29 @@
   }
   
   async function saveResource() {
+    // Promote path: the modal was opened from a discovered inventory row, so
+    // Save confirms promotion (creates LDAP groups + marks managed) rather than
+    // a normal resource create/update.
+    if (promoteSlug) {
+      const slug = promoteSlug;
+      promoteSlug = null;
+      try {
+        const res = await new Promise((resolve, reject) => {
+          app.api.post('discovery/promote/' + slug, {}, function(err, r) {
+            if (err) reject(err); else resolve(r);
+          });
+        });
+        await loadResources();
+        loadDiscoveryResources();
+        app.modal.close();
+        app.messages.toast('Promoted ' + slug + (res && res.groups ? ' — created groups: ' + res.groups.join(', ') : ''), 'success');
+      } catch (err) {
+        promoteSlug = slug;
+        app.messages.action('Failed to promote: ' + (err.message || err), app.modal.body(), 'danger');
+      }
+      return;
+    }
+
     const id = $('#res-id').val();
     const data = {
       name: $('#res-name').val(),
@@ -1146,6 +1303,7 @@
       allGroups.push(res.results);
       refreshGroupsUI(resourceId);
       $('#new-group-cn').val('');
+      await loadResources(); // keep the Access column in sync
     } catch (err) {
       console.error(err);
       app.messages.action('Failed to add group', app.modal.body(), 'danger');
@@ -1157,6 +1315,7 @@
       await app.api.delete('directory-admin/groups/' + id);
       allGroups = allGroups.filter(g => g.id !== id);
       refreshGroupsUI($('#res-id').val());
+      await loadResources(); // keep the Access column in sync
     } catch (err) {
       console.error(err);
       app.messages.action('Failed to remove group', app.modal.body(), 'danger');
@@ -1185,6 +1344,7 @@
       allEdges.push(res.results);
       refreshEdgesUI(resourceId);
       $('#new-edge-target').val('');
+      await loadResources();
     } catch (err) {
       console.error(err);
       app.messages.action('Failed to add edge', app.modal.body(), 'danger');
@@ -1196,6 +1356,7 @@
       await app.api.delete('directory-admin/edges/' + id);
       allEdges = allEdges.filter(e => e.id !== id);
       refreshEdgesUI($('#res-id').val());
+      await loadResources();
     } catch (err) {
       console.error(err);
       app.messages.action('Failed to remove edge', app.modal.body(), 'danger');
@@ -1235,9 +1396,10 @@
   function renderDiscoveryTable() {
     const search = $('#discovery-search-filter').val().toLowerCase();
     const filtered = allDiscoveryResources.filter(r => {
-      if(search && !r.name.toLowerCase().includes(search) && !r.slug.toLowerCase().includes(search)) return false;
-      const isManaged = !!(r.metadata && r.metadata.managed);
-      if(isManaged) return false;
+      if (search && !r.name.toLowerCase().includes(search) && !r.slug.toLowerCase().includes(search)) return false;
+      // Directory contains managed items; Discovered Inventory only shows unmanaged/pending items awaiting promotion
+      const isExplicitManaged = r.metadata && (r.metadata.managed === true || r.metadata.managed === 'true');
+      if (isExplicitManaged || r.kind === 'site' || r.kind === 'service') return false;
       return true;
     });
 
@@ -1255,29 +1417,518 @@
     }
   }
 
+  // Promoting a discovered resource opens the resource form pre-filled with the
+  // discovered data so it can be reviewed before the resource is marked managed
+  // (and its LDAP groups created). The modal's Save (saveResource) sees
+  // promoteSlug set and calls the promote endpoint instead of a normal save.
   function promoteResource(slug) {
-    app.api.post('discovery/promote/' + slug, {}, function(err, res) {
-      if(err) {
-        app.messages.toast("Error promoting resource: " + (err.message || err), 'danger');
-        return;
-      }
-      const resource = allDiscoveryResources.find(r => r.slug === slug);
-      if(resource) {
-        resource.metadata = resource.metadata || {};
-        resource.metadata.managed = true;
-      }
-      $('.actionMessage').html('<div class="alert alert-success alert-dismissible"><button type="button" class="btn-close" data-bs-dismiss="alert"></button>Successfully promoted! Created groups: ' + res.groups.join(', ') + '</div>').show();
-      renderDiscoveryTable();
-      loadResources(); // Also update directory tab
+    const r = allDiscoveryResources.find(x => x.slug === slug);
+    if (!r) { app.messages.toast('Discovered resource not found', 'danger'); return; }
+    promoteSlug = slug;
+    openResourceModal('Promote Resource', null); // add-mode: groups/children tabs hidden
+    const m = r.metadata || {};
+    $('#res-name').val(r.name || '');
+    $('#res-slug').val(r.slug || '');
+    $('#res-kind').val(r.kind || 'host');
+    $('#res-description').val(r.description || '');
+    $('#res-ip').val(m.ip || '');
+    $('#res-address').val(m.address || '');
+    $('#res-subtype').val(m.subType || '');
+    $('#res-mac').val(m.macAddress || '');
+    $('#res-port').val(m.port || '');
+    $('#res-external-port').val(m.externalPort || '');
+    $('#res-icon').val(m.icon || '');
+    $('#res-tagline').val(m.tagline || '');
+    updateIconPreview();
+    toggleFormFields();
+    loadLdapGroups();
+  }
+
+  // --- THETA AGENT INSTALL MODAL & WIZARD ---
+  function generateRandomHexToken(byteLen) {
+    const arr = new Uint8Array(byteLen || 16);
+    (window.crypto || window.msCrypto).getRandomValues(arr);
+    return Array.from(arr, b => b.toString(16).padStart(2, '0')).join('');
+  }
+
+  function regenerateAgentToken(inputId) {
+    const newToken = generateRandomHexToken(16);
+    $('#' + inputId).val(newToken);
+    if (inputId === 'agent-quick-token') $('#agent-custom-token').val(newToken);
+    else $('#agent-quick-token').val(newToken);
+    updateAgentCommands();
+  }
+
+  function updateAgentCommands() {
+    const quickUrl = ($('#agent-quick-url').val() || window.location.origin).replace(/\/+$/, '');
+    const quickToken = $('#agent-quick-token').val() || '';
+    const quickCmd = `curl -fsSL ${quickUrl}/resources/theta-agent/install.sh | sh -s -- --url "${quickUrl}" --token "${quickToken}"`;
+    $('#agent-quick-command').text(quickCmd);
+
+    const customUrl = ($('#agent-custom-url').val() || window.location.origin).replace(/\/+$/, '');
+    const customToken = $('#agent-custom-token').val() || '';
+    const customLocation = $('#agent-custom-location').val() || 'default';
+
+    const telemetry = $('#cap-telemetry').is(':checked');
+    const configureLdap = $('#cap-configure-ldap').is(':checked');
+    const reboot = $('#cap-reboot').is(':checked');
+    const arbitraryBash = $('#cap-arbitrary-bash').is(':checked');
+
+    const servicesRaw = $('#cap-services').val() || '';
+    const servicesList = servicesRaw.split(',').map(s => s.trim()).filter(Boolean);
+    const servicesYaml = servicesList.length > 0
+      ? '[' + servicesList.map(s => `"${s}"`).join(', ') + ']'
+      : '[]';
+
+    const yamlStr = [
+      `server_url: "${customUrl}"`,
+      `auth_token: "${customToken}"`,
+      `location: "${customLocation}"`,
+      `capabilities:`,
+      `  telemetry: ${telemetry}`,
+      `  configure_ldap: ${configureLdap}`,
+      `  reboot: ${reboot}`,
+      `  service_control: ${servicesYaml}`,
+      `  arbitrary_bash: ${arbitraryBash}`
+    ].join('\n');
+
+    $('#agent-yaml-preview').text(yamlStr);
+
+    try {
+      const b64Config = btoa(yamlStr);
+      const customCmd = `curl -fsSL ${customUrl}/resources/theta-agent/install.sh | sh -s -- "${b64Config}"`;
+      $('#agent-custom-command').text(customCmd);
+    } catch (e) {
+      $('#agent-custom-command').text('Error encoding config to Base64');
+    }
+  }
+
+  function copyAgentCommand(elementId, btnId) {
+    const text = $('#' + elementId).text();
+    if (!text) return;
+    navigator.clipboard.writeText(text).then(() => {
+      const $btn = $('#' + btnId);
+      const origHtml = $btn.html();
+      $btn.html('<i class="fa-solid fa-check me-1"></i> Copied!').removeClass('btn-success').addClass('btn-outline-success');
+      setTimeout(() => {
+        $btn.html(origHtml).removeClass('btn-outline-success').addClass('btn-success');
+      }, 2000);
+    }).catch(err => {
+      app.messages.toast('Failed to copy: ' + err, 'danger');
     });
   }
 
-  // Plugin scheduling moved to the dedicated /plugins page (the Agents &
-  // Scheduler tab here was its old home). Discovery inventory + the discovery
-  // results table remain on this page.
+  function openAgentInstallModal() {
+    const currentOrigin = window.location.origin;
+    const initialToken = generateRandomHexToken(16);
+
+    const bodyHtml = `
+      <div class="mb-3 p-3 bg-light rounded border">
+        <div class="d-flex align-items-center">
+          <i class="fa-solid fa-shield-halved fa-2x text-primary me-3"></i>
+          <div>
+            <h6 class="mb-0 fw-bold">Theta Agent Endpoint Management Daemon</h6>
+            <small class="text-muted">A 2-way Command & Control (C2) daemon that streams real-time telemetry and enables secure, capability-controlled management operations on Linux hosts.</small>
+          </div>
+        </div>
+      </div>
+
+      <ul class="nav nav-pills mb-3" id="agent-install-tabs" role="tablist">
+        <li class="nav-item" role="presentation">
+          <button class="nav-link active" id="tab-quick-btn" data-bs-toggle="pill" data-bs-target="#tab-quick-pane" type="button" role="tab">
+            <i class="fa-solid fa-bolt me-1"></i> Quick Install
+          </button>
+        </li>
+        <li class="nav-item" role="presentation">
+          <button class="nav-link" id="tab-custom-btn" data-bs-toggle="pill" data-bs-target="#tab-custom-pane" type="button" role="tab">
+            <i class="fa-solid fa-sliders me-1"></i> Custom Config Wizard
+          </button>
+        </li>
+      </ul>
+
+      <div class="tab-content" id="agent-install-tab-content">
+        <!-- ── Tab 1: Quick Install ──────────────────────────────────────── -->
+        <div class="tab-pane fade show active" id="tab-quick-pane" role="tabpanel">
+          <div class="row g-2 mb-3">
+            <div class="col-md-6">
+              <label class="form-label small fw-bold mb-1">SSO Server URL</label>
+              <input type="text" id="agent-quick-url" class="form-control form-control-sm" value="${currentOrigin}" oninput="updateAgentCommands()">
+            </div>
+            <div class="col-md-6">
+              <label class="form-label small fw-bold mb-1">Host Token</label>
+              <div class="input-group input-group-sm">
+                <input type="text" id="agent-quick-token" class="form-control font-monospace" value="${initialToken}" oninput="updateAgentCommands()">
+                <button class="btn btn-outline-secondary" type="button" onclick="regenerateAgentToken('agent-quick-token')" title="Regenerate Token">
+                  <i class="fa-solid fa-rotate"></i>
+                </button>
+              </div>
+            </div>
+          </div>
+
+          <label class="form-label small fw-bold mb-1">Run this command on the target host (as root):</label>
+          <div class="position-relative mb-2">
+            <pre class="bg-dark text-light p-3 rounded font-monospace small mb-0 text-wrap text-break" id="agent-quick-command" style="user-select: all;"></pre>
+          </div>
+          <div class="d-flex justify-content-end">
+            <button class="btn btn-sm btn-success" id="btn-copy-quick" onclick="copyAgentCommand('agent-quick-command', 'btn-copy-quick')">
+              <i class="fa-solid fa-copy me-1"></i> Copy Quick Install Command
+            </button>
+          </div>
+        </div>
+
+        <!-- ── Tab 2: Custom Config Wizard ────────────────────────────────── -->
+        <div class="tab-pane fade" id="tab-custom-pane" role="tabpanel">
+          <div class="row g-2 mb-3">
+            <div class="col-md-5">
+              <label class="form-label small fw-bold mb-1">SSO Server URL</label>
+              <input type="text" id="agent-custom-url" class="form-control form-control-sm" value="${currentOrigin}" oninput="updateAgentCommands()">
+            </div>
+            <div class="col-md-4">
+              <label class="form-label small fw-bold mb-1">Host Token</label>
+              <div class="input-group input-group-sm">
+                <input type="text" id="agent-custom-token" class="form-control font-monospace" value="${initialToken}" oninput="updateAgentCommands()">
+                <button class="btn btn-outline-secondary" type="button" onclick="regenerateAgentToken('agent-custom-token')" title="Regenerate Token">
+                  <i class="fa-solid fa-rotate"></i>
+                </button>
+              </div>
+            </div>
+            <div class="col-md-3">
+              <label class="form-label small fw-bold mb-1">Location Identifier</label>
+              <input type="text" id="agent-custom-location" class="form-control form-control-sm" placeholder="e.g. dc-01-rack-12" value="default" oninput="updateAgentCommands()">
+            </div>
+          </div>
+
+          <div class="card bg-light border mb-3">
+            <div class="card-header py-2 bg-light fw-bold small"><i class="fa-solid fa-key me-1"></i> Capability Matrix (Local-First Security Controls)</div>
+            <div class="card-body py-2">
+              <div class="row g-2">
+                <div class="col-md-6">
+                  <div class="form-check form-switch">
+                    <input class="form-check-input" type="checkbox" id="cap-telemetry" checked onchange="updateAgentCommands()">
+                    <label class="form-check-label small" for="cap-telemetry"><strong>Telemetry</strong> <span class="text-muted">(CPU, RAM, Disk, ZFS stats)</span></label>
+                  </div>
+                </div>
+                <div class="col-md-6">
+                  <div class="form-check form-switch">
+                    <input class="form-check-input" type="checkbox" id="cap-configure-ldap" checked onchange="updateAgentCommands()">
+                    <label class="form-check-label small" for="cap-configure-ldap"><strong>Configure LDAP</strong> <span class="text-muted">(SSSD config & SSH keys)</span></label>
+                  </div>
+                </div>
+                <div class="col-md-6">
+                  <div class="form-check form-switch">
+                    <input class="form-check-input" type="checkbox" id="cap-reboot" onchange="updateAgentCommands()">
+                    <label class="form-check-label small" for="cap-reboot"><strong>Reboot</strong> <span class="text-muted">(remote system reboot)</span></label>
+                  </div>
+                </div>
+                <div class="col-md-6">
+                  <div class="form-check form-switch">
+                    <input class="form-check-input" type="checkbox" id="cap-arbitrary-bash" onchange="updateAgentCommands()">
+                    <label class="form-check-label small text-danger" for="cap-arbitrary-bash"><strong>Arbitrary Bash</strong> <span class="text-muted">(remote root execution)</span></label>
+                  </div>
+                </div>
+                <div class="col-12 mt-2">
+                  <label class="form-label small fw-bold mb-1">Service Control Allowlist <span class="text-muted font-normal">(comma-separated services, e.g. nginx, gitea, sssd)</span></label>
+                  <input type="text" id="cap-services" class="form-control form-control-sm" placeholder="nginx, docker, sssd" oninput="updateAgentCommands()">
+                </div>
+              </div>
+            </div>
+          </div>
+
+          <ul class="nav nav-tabs nav-tabs-sm mb-2" id="preview-sub-tabs" role="tablist">
+            <li class="nav-item">
+              <button class="nav-link active py-1 px-3 small" id="subtab-cmd-btn" data-bs-toggle="tab" data-bs-target="#subtab-cmd-pane" type="button">Base64 Install Command</button>
+            </li>
+            <li class="nav-item">
+              <button class="nav-link py-1 px-3 small" id="subtab-yaml-btn" data-bs-toggle="tab" data-bs-target="#subtab-yaml-pane" type="button">Generated agent.yml</button>
+            </li>
+          </ul>
+
+          <div class="tab-content mb-2">
+            <div class="tab-pane fade show active" id="subtab-cmd-pane" role="tabpanel">
+              <pre class="bg-dark text-light p-3 rounded font-monospace small mb-0 text-wrap text-break" id="agent-custom-command" style="user-select: all;"></pre>
+            </div>
+            <div class="tab-pane fade" id="subtab-yaml-pane" role="tabpanel">
+              <pre class="bg-light text-dark p-3 rounded border font-monospace small mb-0" id="agent-yaml-preview"></pre>
+            </div>
+          </div>
+
+          <div class="d-flex justify-content-end">
+            <button class="btn btn-sm btn-success" id="btn-copy-custom" onclick="copyAgentCommand('agent-custom-command', 'btn-copy-custom')">
+              <i class="fa-solid fa-copy me-1"></i> Copy Base64 Command
+            </button>
+          </div>
+        </div>
+      </div>
+    `;
+
+    app.modal.open({
+      title: 'Install Theta Agent',
+      bodyHtml: bodyHtml,
+      size: 'lg'
+    });
+
+    updateAgentCommands();
+  }
+
+  var discoveryPlugins = [];
+
+  function loadDiscoveryPlugins() {
+    app.api.get('plugins', function(err, res) {
+      if (err) return;
+      discoveryPlugins = (res.results || []).filter(p => p.category === 'discovery');
+      renderDiscoveryPlugins();
+    });
+  }
+
+  function renderDiscoveryPlugins() {
+    const $list = $('#discovery-plugins-list').empty();
+    if (discoveryPlugins.length === 0) {
+      $list.append('<div class="text-muted text-center py-4"><i class="fa-solid fa-plug fs-2 mb-2 text-black-50"></i><br>No discovery plugins configured.</div>');
+      return;
+    }
+    discoveryPlugins.forEach(p => {
+      const badgeClass = p.enabled ? 'bg-success' : 'bg-secondary';
+      const statusText = p.enabled ? 'Loaded' : 'Unloaded';
+      // Last-run state is surfaced by the plugins API (lastRunAt/lastStatus/
+      // lastError/lastLog) but was dropped here; show it so a plugin that errors
+      // is visible without digging into logs.
+      const runOk = p.lastStatus === 'ok';
+      const runErr = p.lastStatus === 'error';
+      const runState = p.lastRunAt
+        ? `<span class="badge ${runOk ? 'bg-success' : runErr ? 'bg-danger' : 'bg-secondary'}" ${runErr && p.lastError ? 'title="' + esc(p.lastError) + '"' : ''}>${runOk ? 'ok' : runErr ? 'error' : esc(p.lastStatus) || 'ran'}</span> <span class="text-muted">${fmtRunTs(p.lastRunAt)}</span>`
+        : '<span class="text-muted">Never run</span>';
+      const logsBtn = (p.lastLog || p.lastError)
+        ? `<button class="btn btn-sm btn-outline-secondary" title="View run log" onclick="showPluginLog('${p.id}')"><i class="fa-solid fa-scroll"></i> Logs</button>`
+        : '';
+      const card = `
+        <div class="card mb-3 border shadow-sm">
+          <div class="card-body d-flex align-items-center justify-content-between">
+            <div>
+              <h6 class="mb-1"><strong>${p.name}</strong> <span class="badge bg-secondary ms-2">${p.pluginType}</span></h6>
+              <div class="small text-muted font-monospace">${p.slug} | Schedule: ${p.cron}</div>
+              <div class="small">Last run: ${runState}</div>
+            </div>
+            <div class="d-flex align-items-center gap-2">
+              <span class="badge ${badgeClass} me-2">${statusText}</span>
+              ${logsBtn}
+              <button class="btn btn-sm btn-outline-primary" onclick="toggleDiscoveryPlugin('${p.id}', ${!p.enabled})">${p.enabled ? 'Unload' : 'Load'}</button>
+              <button class="btn btn-sm btn-success" title="Run now" onclick="runDiscoveryPluginNow('${p.id}')"><i class="fa-solid fa-play"></i> Run</button>
+              <button class="btn btn-sm btn-outline-danger" onclick="deleteDiscoveryPlugin('${p.id}')"><i class="fas fa-trash"></i></button>
+            </div>
+          </div>
+        </div>
+      `;
+      $list.append(card);
+    });
+  }
+
+  // "Never run" when a discovery plugin has no run yet; otherwise relative time.
+  function fmtRunTs(ts) {
+    if (!ts) return 'Never run';
+    const m = moment(ts);
+    return m.isValid() ? m.fromNow() : 'Never run';
+  }
+
+  // Modal showing the discovery plugin's last run log + error (from the plugins
+  // API's lastLog/lastError fields). Logs can be long, so render in a scrollable
+  // <pre> rather than a toast.
+  function showPluginLog(id) {
+    const p = discoveryPlugins.find(x => x.id === id);
+    if (!p) return;
+    const body = p.lastError
+      ? `<div class="alert alert-danger mb-2">${esc(p.lastError)}</div>`
+      : '';
+    const log = p.lastLog || '(no log captured for this run)';
+    app.modal.open({
+      title: 'Run log — ' + (p.name || p.slug),
+      size: 'lg',
+      bodyHtml: body + '<pre class="p-2 mb-0 bg-light border" style="max-height:55vh;overflow:auto;white-space:pre-wrap;font-size:.85rem;">' + esc(log) + '</pre>',
+    });
+  }
+
+  async function toggleDiscoveryPlugin(id, state) {
+    const endpoint = state ? 'load' : 'unload';
+    try {
+      await app.api.post(`plugins/${id}/${endpoint}`, {});
+      app.messages.toast(`Discovery plugin ${state ? 'loaded' : 'unloaded'}`, 'success');
+      loadDiscoveryPlugins();
+    } catch (e) {
+      app.messages.toast('Error toggling plugin: ' + e.message, 'danger');
+    }
+  }
+
+  async function runDiscoveryPluginNow(id) {
+    try {
+      await app.api.post(`plugins/${id}/run`, {});
+      app.messages.toast('Enqueued discovery plugin run', 'success');
+      loadDiscoveryPlugins();
+    } catch (e) {
+      app.messages.toast('Error running plugin: ' + e.message, 'danger');
+    }
+  }
+
+  var discoveryPluginTypes = [];
+
+  // ── Discovery plugin config helpers (ported from plugins.ejs) ─────────────
+  // Stored value is always a 5-field cron string; the dropdown picks a preset
+  // and "Custom…" reveals the raw input. Config fields are driven by each
+  // plugin type's configSchema so per-plugin settings (e.g. Proxmox url /
+  // tokenId / tokenSecret) are collected at create time.
+  var DP_CRON_PRESETS = [
+    { key: 'hourly', label: 'Hourly',           cron: '0 * * * *' },
+    { key: 'daily',  label: 'Daily (midnight)',  cron: '0 0 * * *' },
+    { key: 'weekly', label: 'Weekly (Sun)',      cron: '0 0 * * 0' },
+    { key: 'custom', label: 'Custom…',           cron: null },
+  ];
+  function dpCronKeyFor(cron) {
+    var m = DP_CRON_PRESETS.filter(function(p){ return p.cron === cron; })[0];
+    return m ? m.key : 'custom';
+  }
+  function dpCronSelectHtml(prefix, current) {
+    current = current || '0 * * * *';
+    var key = dpCronKeyFor(current);
+    var opts = DP_CRON_PRESETS.map(function(p){
+      return '<option value="' + p.key + '"' + (p.key === key ? ' selected' : '') + '>' + p.label + '</option>';
+    }).join('');
+    var rawStyle = key === 'custom' ? '' : ' style="display:none"';
+    return '<select class="form-select" id="' + prefix + 'cron-select" onchange="dpOnCronChange(\'' + prefix + '\')">' + opts + '</select>' +
+      '<input type="text" class="form-control font-monospace mt-2" id="' + prefix + 'cron" value="' + current + '"' + rawStyle + '>';
+  }
+  function dpOnCronChange(prefix) {
+    var sel = document.getElementById(prefix + 'cron-select');
+    var raw = document.getElementById(prefix + 'cron');
+    if (!sel || !raw) return;
+    if (sel.value === 'custom') { raw.style.display = ''; }
+    else {
+      raw.style.display = 'none';
+      var preset = DP_CRON_PRESETS.filter(function(p){ return p.key === sel.value; })[0];
+      if (preset) raw.value = preset.cron;
+    }
+  }
+  function dpCronFromForm(prefix) {
+    var sel = document.getElementById(prefix + 'cron-select');
+    if (sel && sel.value !== 'custom') {
+      var preset = DP_CRON_PRESETS.filter(function(p){ return p.key === sel.value; })[0];
+      if (preset) return preset.cron;
+    }
+    var raw = document.getElementById(prefix + 'cron');
+    return (raw && raw.value.trim()) || '0 * * * *';
+  }
+  function dpConfigFormHtml(type, prefix) {
+    var t = discoveryPluginTypes.filter(function(x){ return x.type === type; })[0];
+    var schema = t && t.configSchema;
+    if (!schema || !schema.length) return '<p class="text-muted">No configuration fields for this plugin.</p>';
+    var html = '';
+    schema.forEach(function(f) {
+      var inputType = f.type === 'password' ? 'password' : (f.type === 'url' ? 'url' : 'text');
+      var req = f.required ? ' required' : '';
+      var ph = f.placeholder ? (' placeholder="' + f.placeholder + '"') : '';
+      var label = f.label + (f.secret ? ' <span class="text-warning" title="stored in OpenBao"><i class="fa-solid fa-key"></i></span>' : '') + (f.required ? ' <span class="text-danger">*</span>' : '');
+      html += '<div class="mb-3"><label class="form-label">' + label + '</label>' +
+        '<input type="' + inputType + '" class="form-control" id="' + prefix + f.key + '"' + req + ph + '></div>';
+    });
+    return html;
+  }
+  function dpCollectConfig(type, prefix) {
+    var t = discoveryPluginTypes.filter(function(x){ return x.type === type; })[0];
+    var schema = t && t.configSchema;
+    var out = {};
+    if (!schema) return out;
+    schema.forEach(function(f) { var el = document.getElementById(prefix + f.key); if (el) out[f.key] = el.value; });
+    return out;
+  }
+  function dpRenderFields() {
+    var type = document.getElementById('new-plugin-type').value;
+    document.getElementById('new-plugin-config-fields').innerHTML = dpConfigFormHtml(type, 'np-');
+  }
+
+  function openNewDiscoveryPluginModal() {
+    app.api.get('plugins/types', function(err, res) {
+      if (err) { app.messages.toast('Error loading plugin types: ' + err.message, 'danger'); return; }
+      discoveryPluginTypes = (res.results || []).filter(t => t.category === 'discovery');
+      if (discoveryPluginTypes.length === 0) {
+        app.messages.toast('No discovery plugin types available', 'warning');
+        return;
+      }
+
+      const options = discoveryPluginTypes.map(t => `<option value="${t.type}">${t.name} (${t.type})</option>`).join('');
+      const bodyHtml = `
+        <div class="mb-3">
+          <label class="form-label fw-bold">Plugin Type</label>
+          <select id="new-plugin-type" class="form-select shadow-sm" onchange="dpRenderFields()">${options}</select>
+        </div>
+        <div class="mb-3">
+          <label class="form-label fw-bold">Instance Name</label>
+          <input type="text" id="new-plugin-name" class="form-control shadow-sm" placeholder="e.g. Local Subnet Scanner">
+          <div class="form-text">A slug is derived automatically from the name.</div>
+        </div>
+        <div class="mb-3">
+          <label class="form-label fw-bold">Schedule</label>
+          ${dpCronSelectHtml('np-', '0 * * * *')}
+        </div>
+        <div class="form-check mb-3">
+          <input class="form-check-input" type="checkbox" id="new-plugin-enabled" checked>
+          <label class="form-check-label fw-semibold" for="new-plugin-enabled">Enable (load on create)</label>
+        </div>
+        <hr><h6 class="fw-bold">Configuration</h6><div id="new-plugin-config-fields">${dpConfigFormHtml(discoveryPluginTypes[0].type, 'np-')}</div>
+        <div class="d-flex justify-content-end gap-2">
+          <button class="btn btn-secondary" onclick="app.modal.close()">Cancel</button>
+          <button class="btn btn-primary" onclick="saveNewDiscoveryPlugin()">Create Plugin</button>
+        </div>
+      `;
+
+      app.modal.open({
+        title: 'Configure New Discovery Plugin',
+        bodyHtml: bodyHtml,
+        size: 'lg'
+      });
+    });
+  }
+
+  async function saveNewDiscoveryPlugin() {
+    const type = $('#new-plugin-type').val();
+    const name = $('#new-plugin-name').val().trim();
+    const cron = dpCronFromForm('np-');
+    const enabled = $('#new-plugin-enabled').is(':checked');
+    const config = dpCollectConfig(type, 'np-');
+
+    if (!type) return app.messages.action('Select a plugin type.', app.modal.body(), 'danger');
+    if (!name) return app.messages.action('Name is required', app.modal.body(), 'danger');
+
+    try {
+      await app.api.post('plugins', {
+        pluginType: type,
+        name,
+        cron,
+        enabled,
+        config
+      });
+      app.messages.toast('Discovery plugin created successfully!', 'success');
+      app.modal.close();
+      loadDiscoveryPlugins();
+    } catch (e) {
+      app.messages.action('Error creating plugin: ' + e.message, app.modal.body(), 'danger');
+    }
+  }
 
   $(document).ready(function(){
     loadDiscoveryResources();
+    loadDiscoveryPlugins();
+    // Keep the host status dots live: refresh the agent join periodically and on
+    // socket.io agent.* broadcasts (dedicated socket — the app default is P2PSub).
+    refreshAgents();
+    setInterval(refreshAgents, 30000);
+    try {
+      const dirAgentSocket = io({ auth: { token: app.auth.getToken() } });
+      dirAgentSocket.on('agent.telemetry', function(msg){
+        const a = msg && agentsByToken[msg.token];
+        if (a) { a.telemetry = msg.payload; a.isOnline = true; renderTable(); }
+      });
+      dirAgentSocket.on('agent.discovery', function(msg){
+        const a = msg && agentsByToken[msg.token];
+        if (a) { a.discovery = msg.payload; if (msg.payload && msg.payload.hostname) a.hostname = msg.payload.hostname; a.isOnline = true; renderTable(); }
+      });
+    } catch (e) { /* socket is optional; periodic refresh still runs */ }
   });
 </script>
 

nodejs/views/groups.ejs

@@ -1,406 +0,0 @@
-<%- include('top') %>
-
-<script type="text/javascript">
-	var userlist;
-	var allGroups = [];
-
-	// A member DN under the groups base is a nested group, not a person. Both
-	// live in the same `member` attribute, so they have to be told apart here --
-	// otherwise a nested group renders as a user whose name happens to be the
-	// group's, and its remove button calls the user endpoint and 404s.
-	function isGroupDn(dn){
-		return /,ou=groups,/i.test(String(dn));
-	}
-
-	function processGroup(value){
-		if (!Array.isArray(value.member)) value.member = value.member ? [value.member] : [];
-		if (!Array.isArray(value.owner))  value.owner  = value.owner  ? [value.owner]  : [];
-
-		// Split before anything else consumes `member`.
-		value.nested = value.member.filter(isGroupDn).map(function(dn){
-			return {
-				dn: dn,
-				cn: dn.match(/cn=[^,]+/)[0].replace('cn=', ''),
-				groupCN: value.cn
-			};
-		});
-		value.member = value.member.filter(function(dn){ return !isGroupDn(dn); });
-		value.nestedCount = value.nested.length;
-		value.hasNested = value.nestedCount > 0;
-
-		// Candidates to nest: every other group not already nested here. Self is
-		// excluded; deeper loops are refused server-side by Group.wouldCycle,
-		// which is the only place that can see the whole graph.
-		var nestedDns = value.nested.map(function(g){ return g.dn.toLowerCase(); });
-		value.toNest = allGroups.filter(function(g){
-			return g.cn !== value.cn && nestedDns.indexOf(String(g.dn).toLowerCase()) === -1;
-		}).map(function(g){ return {cn: g.cn, groupCN: value.cn}; });
-
-		value.toAdd = userlist.filter(function(user){
-			return !value.member.includes(user.dn);
-		});
-		value.toAddOwner = userlist.filter(function(user){
-			return !value.owner.includes(user.dn);
-		});
-		value.member = value.member.map(function(user){
-			return {
-				dn: user,
-				uid: user.match(/cn=[a-zA-Z0-9\_\-\@\.]+/)[0].replace('cn=', '')
-			};
-		});
-		value.owner = value.owner.map(function(user){
-			return {
-				dn: user,
-				uid: user.match(/cn=[a-zA-Z0-9\_\-\@\.]+/)[0].replace('cn=', '')
-			};
-		});
-		value.memberCount = value.member.length;
-		value.createTimestamp = moment(value.createTimestamp, "YYYYMMDDHHmmssZ").fromNow();
-		value.modifyTimestamp = moment(value.modifyTimestamp, "YYYYMMDDHHmmssZ").fromNow();
-		value.groupCN = value.cn;
-		return value;
-	}
-
-	// app_sso_service_account is a marker group: membership hides an account
-	// from the Users page's People tab entirely (see users.ejs), which is
-	// exactly right for a non-person account but has silently made a real
-	// person's account look "gone" before (nothing else about it changes).
-	// Everywhere else in this dropdown just fires the PUT directly; only
-	// this one group gets a confirmation first.
-	function addMemberClick(event, groupCN, uid, el){
-		event.preventDefault();
-		const $el = $(el);
-		(async function(){
-			if (groupCN === 'app_sso_service_account') {
-				const ok = await app.messages.confirm(
-					`Mark "${uid}" as a service account? This hides them from the Users page's People tab (Service Accounts tab only) — only do this for a non-person account.`,
-					$el.closest('.card'), 'warning'
-				);
-				if (!ok) return;
-			}
-			try {
-				const data = await app.api.put(`group/${groupCN}/${uid}`, {});
-				await addedUser(data.message, groupCN, uid, $el);
-			} catch(e) {
-				app.messages.action(e.message || 'Failed to add member', $el.closest('.card'), 'danger');
-			}
-		})();
-		return false;
-	}
-
-	async function addedUser(message, group, user, $form){
-		let data = await app.group.get(group);
-		$.scope.groupCard.update('cn', group, processGroup(data.results));
-		app.messages.action(message, $("#group-card-"+group), 'success');
-		$('a[href="#'+$form.closest('.tab-pane').attr('id')+'"]').tab('show');
-		setTimeout(function(){ app.util.revealItem($("#group-card-" + group)); }, 400);
-	}
-
-	function applySort() {
-		const sort = $('#groupSort').val();
-		const scope = $.scope.groupCard;
-		if (sort === 'name-asc')     { scope.__jqOrderBy = 'cn';          scope.__jqOrderReverse = false; }
-		if (sort === 'name-desc')    { scope.__jqOrderBy = 'cn';          scope.__jqOrderReverse = true;  }
-		if (sort === 'members-desc') { scope.__jqOrderBy = 'memberCount'; scope.__jqOrderReverse = true;  }
-		if (sort === 'members-asc')  { scope.__jqOrderBy = 'memberCount'; scope.__jqOrderReverse = false; }
-	}
-
-	function matchesSearch(g) {
-		const q = $('#groupSearch').val().toLowerCase().trim();
-		return !q || g.cn.toLowerCase().includes(q) || (g.description || '').toLowerCase().includes(q);
-	}
-
-	function applyFilters() {
-		applySort();
-		const groups = allGroups.filter(matchesSearch);
-		$.scope.groupCard.empty();
-		$.scope.groupCard.push(...groups);
-		$('#groupCount').text(groups.length + ' of ' + allGroups.length + ' group' + (allGroups.length !== 1 ? 's' : ''));
-	}
-
-	async function tableAJAX(revealCn) {
-		let data = await app.group.list();
-		// processGroup builds each card's "nest a group" list from allGroups, so
-		// it has to see the full set before the map runs -- assigning only the
-		// mapped result would leave every dropdown empty on first load (and one
-		// render stale thereafter). The raw entries carry the cn/dn it needs.
-		allGroups = data.results;
-		allGroups = data.results.map(processGroup);
-		applyFilters();
-		if (revealCn) setTimeout(function(){ app.util.revealItem($('#group-card-' + revealCn)); }, 100);
-	}
-
-	function addNestedClick(event, groupCN, childCN, el){
-		event.preventDefault();
-		const $card = $('#group-card-' + groupCN);
-		(async function(){
-			try {
-				const data = await app.api.put(`group/${groupCN}/nested/${childCN}`, {});
-				const groupData = await app.group.get(groupCN);
-				$.scope.groupCard.update('cn', groupCN, processGroup(groupData.results));
-				app.messages.action(data.message, $card, 'success');
-			} catch(e) {
-				// 409 here is the cycle guard or an already-nested group -- both
-				// carry a specific server message worth showing verbatim.
-				app.messages.action((e && e.message) || 'Failed to nest group', $card, 'danger');
-			}
-		})();
-	}
-
-	async function removeNested(groupCN, childCN, btn) {
-		const $item = $(btn).closest('li');
-		$item.addClass('list-group-item-warning');
-		const confirmed = await app.messages.confirm(
-			`Remove "${childCN}" from "${groupCN}"? Its members lose access granted through this group.`,
-			$item, 'warning');
-		if (!confirmed) { $item.removeClass('list-group-item-warning'); return; }
-		try {
-			const data = await app.api.delete(`group/${groupCN}/nested/${childCN}`);
-			const groupData = await app.group.get(groupCN);
-			$.scope.groupCard.update('cn', groupCN, processGroup(groupData.results));
-			app.messages.action(data.message, $('#group-card-' + groupCN), 'success');
-		} catch(e) {
-			$item.removeClass('list-group-item-warning');
-			app.messages.action(e.message || 'Failed to un-nest group', $('#group-card-' + groupCN), 'danger');
-		}
-	}
-
-	async function removeMember(groupCN, uid, btn) {
-		const $item = $(btn).closest('li');
-		$item.addClass('list-group-item-warning');
-		const confirmed = await app.messages.confirm(`Remove "${uid}" from "${groupCN}"?`, $item, 'warning');
-		if (!confirmed) { $item.removeClass('list-group-item-warning'); return; }
-		try {
-			const data = await app.api.delete(`group/${groupCN}/${uid}`);
-			const groupData = await app.group.get(groupCN);
-			$.scope.groupCard.update('cn', groupCN, processGroup(groupData.results));
-			app.messages.action(data.message, $('#group-card-' + groupCN), 'success');
-		} catch(e) {
-			$item.removeClass('list-group-item-warning');
-			app.messages.action(e.message || 'Failed to remove member', $('#group-card-' + groupCN), 'danger');
-		}
-	}
-
-	async function removeOwner(groupCN, uid, btn) {
-		const $item = $(btn).closest('li');
-		$item.addClass('list-group-item-warning');
-		const confirmed = await app.messages.confirm(`Remove "${uid}" as owner of "${groupCN}"?`, $item, 'warning');
-		if (!confirmed) { $item.removeClass('list-group-item-warning'); return; }
-		try {
-			const data = await app.api.delete(`group/owner/${groupCN}/${uid}`);
-			const groupData = await app.group.get(groupCN);
-			$.scope.groupCard.update('cn', groupCN, processGroup(groupData.results));
-			app.messages.action(data.message, $('#group-card-' + groupCN), 'success');
-		} catch(e) {
-			$item.removeClass('list-group-item-warning');
-			app.messages.action(e.message || 'Failed to remove owner', $('#group-card-' + groupCN), 'danger');
-		}
-	}
-
-	async function deleteGroup(cn, btn) {
-		const $card = $(btn).closest('.card');
-		const confirmed = await app.messages.confirm(`Delete group "${cn}"?`, $card, 'danger');
-		if (!confirmed) return;
-		try {
-			await app.api.delete(`group/${cn}`);
-			$.scope.groupCard.remove('cn', cn);
-		} catch(e) {
-			app.messages.action(e.message || 'Failed to delete group', $card, 'danger');
-		}
-	}
-
-	app.auth.forceLogin(['app_sso_admin', 'admin']);
-
-	$(document).ready(async function(){
-		userlist = (await app.user.list()).results;
-		tableAJAX();
-	});
-</script>
-<div class="container mt-4">
-	
-	<div class="d-flex flex-wrap gap-2 align-items-center sticky-top bg-body py-2" style="top: var(--sw-content-offset, 0);">
-		<div class="input-group" style="flex: 1 1 200px;">
-			<span class="input-group-text"><i class="fa-solid fa-magnifying-glass"></i></span>
-			<input type="text" id="groupSearch" class="form-control" placeholder="Search groups…" oninput="applyFilters()">
-		</div>
-		<select id="groupSort" class="form-select" style="width:auto; min-width:175px" onchange="applyFilters()">
-			<option value="name-asc">Name A → Z</option>
-			<option value="name-desc">Name Z → A</option>
-			<option value="members-desc">Most members</option>
-			<option value="members-asc">Fewest members</option>
-		</select>
-		<span id="groupCount" class="text-muted text-nowrap small"></span>
-	</div>
-	<div class="row row-cols-1 row-cols-md-3 g-4 mt-0">
-		<div class="col">
-			<div class="card shadow">
-				<div class="card-header">
-					<i class="fa-solid fa-object-group"></i>
-					Add new group
-					<a href="/docs/accounts" class="text-reset float-end" title="Help"><i class="fa-solid fa-circle-question"></i></a>
-				</div>
-				<div class="card-header actionMessage" style="display:none"></div>
-				<div class="card-body">
-					<form action="group/" method="post" onsubmit="formAJAX(this)" evalAJAX="tableAJAX(data.results.cn)">
-						<div class="mb-3">
-							<label class="form-label">Name</label>
-							<input type="text" class="form-control shadow" name="name" placeholder="app_gitea_admin" validate=":3" />
-						</div>
-
-						<div class="mb-3">
-							<label class="form-label">Description</label>
-							<textarea class="form-control shadow" name="description" placeholder="Admin group for gitea app" validate=":3"></textarea>
-						</div>
-
-						<button type="submit" class="btn btn-outline-dark">Add</button>
-					</form>
-				</div>
-			</div>
-		</div>
-		<div class="col" jq-repeat="groupCard" jq-index-key="cn" jr-order-by="cn" id="group-card-{{cn}}">
-			<div class="card shadow col">
-				<div class="card-header">
-					<h5>
-						<i class="fa-solid fa-arrows-down-to-people"></i>
-						Group: {{ cn }}
-						<a href="/docs/accounts" class="text-reset float-end" title="Help"><i class="fa-solid fa-circle-question"></i></a>
-					</h5>
-					<ul class="nav nav-tabs card-header-tabs" id="myTab" role="tablist">
-						<li class="nav-item">
-							<a class="nav-link active" id="group-members-tab-{{cn}}" data-bs-toggle="tab" data-bs-target="#group-memmbers-{{cn}}" href="#group-memmbers-{{cn}}" role="tab" aria-controls="member" aria-selected="true">
-								<i class="fa-solid fa-users"></i>
-								Members
-							</a>
-						</li>
-						<li class="nav-item">
-							<a class="nav-link" id="group-nested-tab-{{cn}}" data-bs-toggle="tab" data-bs-target="#group-nested-{{cn}}" href="#group-nested-{{cn}}" role="tab" aria-controls="nested" aria-selected="false">
-								<i class="fa-solid fa-layer-group"></i>
-								Nested{{#hasNested}} <span class="badge bg-secondary">{{nestedCount}}</span>{{/hasNested}}
-							</a>
-						</li>
-						<li class="nav-item">
-							<a class="nav-link" id="group-admins-tab-{{cn}}" data-bs-toggle="tab" data-bs-target="#group-admins-{{cn}}" href="#group-admins-{{cn}}" role="tab" aria-controls="admin" aria-selected="false">
-								<i class="fa-solid fa-user-tie"></i>
-								Owners
-							</a>
-						</li>
-						<li class="nav-item float-end">
-							
-						</li>
-					</ul>
-
-				</div>
-				<div class="card-header actionMessage" style="display:none"></div>
-				<div class="card-body">
-					<p>
-						{{ description }}
-					</p>
-					<div class="tab-content" id="myTabContent">			  
-						<div class="tab-pane fade show active" id="group-memmbers-{{cn}}" role="tabpanel" aria-labelledby="member-tab">
-							<p>	
-								<ul class="list-group">
-								{{ #member }}
-									<li id="group-card-{{cn}}-{{uid}}" class="list-group-item shadow">
-										<i class="fa-solid fa-user"></i> {{ uid }}
-										<button type="button" onclick="removeMember('{{groupCN}}', '{{uid}}', this)" class="btn btn-sm btn-danger float-end">
-											<i class="fa-solid fa-user-slash"></i>
-										</button>
-									</li>
-								{{ /member }}
-								</ul>
-							</p>
-							<div class="dropdown">
-								<button class="btn btn-secondary dropdown-toggle" type="button" id="group_add_member" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
-									<i class="fa-solid fa-user-plus"></i>
-								</button>
-								<div class="dropdown-menu shadow-lg" aria-labelledby="group_add_member">
-								{{ #toAdd }}{{#.}}
-									<a class="dropdown-item" href="#" onclick="return addMemberClick(event, '{{groupCN}}', '{{uid}}', this);">
-										<i class="fa-solid fa-user"></i> {{uid}}
-									</a>
-								{{/.}}{{ /toAdd }}
-								
-								</div>
-							</div>
-						</div>
-
-						<div class="tab-pane fade" id="group-nested-{{cn}}" role="tabpanel" aria-labelledby="nested-tab">
-							<p class="text-muted small mb-2">
-								Everyone in a nested group is a member of this one, at any depth.
-							</p>
-							<ul class="list-group">
-							{{ #nested }}
-								<li id="group-card-{{groupCN}}-nested-{{cn}}" class="list-group-item shadow">
-									<i class="fa-solid fa-layer-group"></i> {{ cn }}
-									<button type="button" onclick="removeNested('{{groupCN}}', '{{cn}}', this)" class="btn btn-sm btn-danger float-end">
-										<i class="fa-solid fa-link-slash"></i>
-									</button>
-								</li>
-							{{ /nested }}
-							{{ ^hasNested }}
-								<li class="list-group-item text-muted fst-italic">No groups nested here.</li>
-							{{ /hasNested }}
-							</ul>
-							<div class="dropdown mt-2">
-								<button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
-									<i class="fa-solid fa-diagram-project"></i> Nest a group
-								</button>
-								<div class="dropdown-menu" style="max-height: 300px; overflow-y: auto;">
-								{{ #toNest }}
-									<a class="dropdown-item" href="#" onclick="addNestedClick(event, '{{groupCN}}', '{{cn}}', this)">{{ cn }}</a>
-								{{ /toNest }}
-								</div>
-							</div>
-						</div>
-
-						<div class="tab-pane fade" id="group-admins-{{cn}}" role="tabpanel" aria-labelledby="admin-tab">
-							<p>
-								<ul class="list-group">
-								{{ #owner }}
-									<li class="list-group-item shadow">
-										<i class="fa-solid fa-user"></i> {{ uid }}
-										<button type="button" onclick="removeOwner('{{groupCN}}', '{{uid}}', this)" class="btn btn-sm btn-danger float-end">
-											<i class="fa-solid fa-user-slash"></i>
-										</button>
-									</li>
-								{{ /owner }}
-								</ul>
-							</p>
-
-							<div class="dropdown float-start">
-								<button class="btn btn-secondary dropdown-toggle" type="button" id="group_add_admin" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
-									<i class="fa-solid fa-user-plus"></i>
-								</button>
-								<div class="dropdown-menu shadow-lg" aria-labelledby="group_add_admin">
-								{{ #toAddOwner }}{{#.}}
-									<a class="dropdown-item" action="group/owner/{{groupCN}}/{{uid}}" method="put" onclick="formAJAX(this)" evalAJAX="addedUser(data.message, '{{groupCN}}', '{{uid}}', $form)">
-										<i class="fa-solid fa-user"></i> {{uid}}
-									</a>
-								{{/.}}{{ /toAddOwner }}
-								
-								</div>
-							</div>
-
-						</div>
-					</div>
-				</div>
-				<div class="card-footer">
-					<div class="float-end">
-						<button type="button" onclick="" class="btn btn-warning btn-lg shadow">
-							<i class="fa-solid fa-edit"></i>
-						</button>
-						<button type="button" onclick="deleteGroup('{{cn}}', this)" class="btn btn-danger btn-lg">
-							<i class="fa-solid fa-trash"></i>
-						</button>
-					</div>
-					<div>
-						Created: {{createTimestamp}}<br />
-						Last Modified: {{modifyTimestamp}}
-					</div>
-				</div>
-			</div>
-		</div>
-	</div>
-
-</div>
-<%- include('bottom') %>

nodejs/views/profile.ejs

@@ -657,8 +657,8 @@
 </script>
 
 <div id="own-api-tokens-section" style="display:none">
-<div class="row mt-3 justify-content-center">
-	<div class="col-md-8">
+<div class="row mt-3">
+	<div class="col-12">
 		<div class="card shadow-lg">
 			<div class="card-header d-flex justify-content-between align-items-center">
 				<span><i class="fa-solid fa-key me-1"></i> API Tokens</span>

nodejs/views/top.ejs

@@ -49,7 +49,7 @@
 				</ul>
 				<div class="form-inline mt-2 mt-md-0">
 					<% if(ui.profileUrl){ %>
-					<a id="cl-username" class="navbar-text text-light me-3" href="<%- ui.profileUrl %>" style="display: none;">
+					<a id="cl-username" class="navbar-text text-light me-3 text-decoration-none" href="<%- ui.profileUrl %>" style="display: none;">
 						<i class="fa-solid fa-user me-1"></i><span id="cl-username-text"></span>
 					</a>
 					<% } else { %>

nodejs/views/vault.ejs

@@ -1,26 +1,33 @@
 <%- include('top') %>
 
-<div class="container-fluid py-4">
-  <div class="d-flex justify-content-between align-items-center mb-3">
-    <h2 id="vault-title"><i class="fas fa-lock"></i> My Secrets <small class="text-muted">(personal namespace)</small></h2>
-    <ul class="nav nav-pills" id="vault-tabs">
-      <li class="nav-item"><button class="nav-link active" data-bs-toggle="pill" data-bs-target="#tab-secrets" type="button">Secrets</button></li>
-      <li class="nav-item" id="vault-apps-tab" style="display:none"><button class="nav-link" data-bs-toggle="pill" data-bs-target="#tab-apps" type="button">Apps</button></li>
-    </ul>
-  </div>
-
-  <div class="tab-content">
+<div class="container mt-4">
+  <div class="row">
+    <div class="col-12">
+      <div class="card shadow">
+        <div class="card-header d-flex justify-content-between align-items-center flex-wrap gap-2">
+          <ul class="nav nav-tabs card-header-tabs" id="vault-tabs" role="tablist">
+            <li class="nav-item"><button class="nav-link active" data-bs-toggle="tab" data-bs-target="#tab-secrets" type="button"><i class="fa-solid fa-lock"></i> Secrets</button></li>
+            <li class="nav-item" id="vault-apps-tab" style="display:none"><button class="nav-link" data-bs-toggle="tab" data-bs-target="#tab-apps" type="button"><i class="fa-solid fa-key"></i> Apps</button></li>
+            <li class="nav-item"><button class="nav-link" data-bs-toggle="tab" data-bs-target="#tab-shared" type="button"><i class="fa-solid fa-share-nodes"></i> Shared</button></li>
+          </ul>
+          <span class="small text-muted"><i class="fa-solid fa-database me-1"></i>Powered by <a href="https://openbao.org" target="_blank" rel="noopener">OpenBao</a></span>
+        </div>
+        <div class="card-body p-0">
+          <div class="tab-content">
     <!-- ── Secrets tab ─────────────────────────────────────────────────── -->
     <div class="tab-pane fade show active" id="tab-secrets">
-      <div class="d-flex justify-content-end mb-3">
-        <button class="btn btn-primary" onclick="showCreateModal()">
-          <i class="fas fa-plus"></i> New Secret
-        </button>
+      <div class="card-header d-flex flex-wrap justify-content-between align-items-center gap-2">
+        <h5 class="mb-0" id="vault-title"><i class="fas fa-lock"></i> My Secrets <small class="text-muted">(personal namespace)</small></h5>
+        <div class="d-flex align-items-center gap-2">
+          <a href="/docs/vault" class="text-reset" title="Vault help &amp; documentation"><i class="fa-solid fa-circle-question"></i></a>
+          <button class="btn btn-primary btn-sm" onclick="showCreateModal()"><i class="fas fa-plus"></i> New Secret</button>
+        </div>
       </div>
-      <div class="row">
+      <div class="p-3">
+        <div class="row">
         <div class="col-md-4">
           <div class="card shadow-sm">
-            <div class="card-header bg-light"><h5 class="card-title mb-0">Secrets List</h5></div>
+            <div class="card-header"><h5 class="card-title mb-0">Secrets List</h5></div>
             <div class="list-group list-group-flush" id="secrets-list">
               <div class="list-group-item text-center text-muted">Loading...</div>
             </div>
@@ -28,7 +35,7 @@
         </div>
         <div class="col-md-8">
           <div class="card shadow-sm" id="secret-details-card" style="display: none;">
-            <div class="card-header bg-light d-flex justify-content-between align-items-center">
+            <div class="card-header d-flex justify-content-between align-items-center">
               <h5 class="card-title mb-0" id="secret-title">Secret Details</h5>
               <div>
                 <button class="btn btn-sm btn-outline-primary me-2" onclick="editCurrentSecret()"><i class="fas fa-edit"></i> Edit</button>
@@ -44,17 +51,20 @@
             <h4>Select a secret to view its details</h4>
           </div>
         </div>
+        </div>
       </div>
     </div>
 
     <!-- ── Apps tab (admin only; revealed client-side for admins) ─────── -->
     <div class="tab-pane fade" id="tab-apps">
-      <div class="row">
+      <div class="p-3">
+        <div class="row">
         <div class="col-md-5">
           <div class="card shadow-sm">
-            <div class="card-header bg-light"><h5 class="card-title mb-0">Mint an app token</h5></div>
+            <div class="card-header"><h5 class="card-title mb-0">Mint an app token</h5></div>
             <div class="card-body">
               <p class="text-muted small">Mints a scoped OpenBao token confined to <code>secret/apps/&lt;name&gt;/*</code> for an external app. The token is shown <strong>once</strong> — record it in the app immediately; it cannot be recovered later.</p>
+              <p class="text-muted small">The token is periodic: it stays valid as long as the app renews it within its period (<code>POST /v1/auth/token/renew-self</code>). If it lapses, mint a new one here — the app's policy and stored secrets are kept.</p>
               <div class="mb-3">
                 <label class="form-label">App name (lowercase letters, digits, hyphens)</label>
                 <input type="text" class="form-control" id="app-name-input" placeholder="e.g. my-service">
@@ -66,7 +76,7 @@
         </div>
         <div class="col-md-7">
           <div class="card shadow-sm d-none" id="app-result-card">
-            <div class="card-header bg-light d-flex justify-content-between align-items-center">
+            <div class="card-header d-flex justify-content-between align-items-center">
               <h5 class="card-title mb-0">App token</h5>
               <button class="btn btn-sm btn-outline-primary" onclick="copyText(document.getElementById('app-token').textContent)"><i class="fas fa-copy"></i> Copy</button>
             </div>
@@ -81,8 +91,124 @@ curl "$VAULT_ADDR/v1/secret/data/apps/<span id="app-name-display"></span>/conf"
             </div>
           </div>
         </div>
+        </div>
+        <div class="row mt-3">
+          <div class="col-12">
+            <div class="card shadow-sm">
+              <div class="card-header d-flex justify-content-between align-items-center">
+                <h5 class="card-title mb-0"><i class="fa-solid fa-key me-1"></i> Minted apps</h5>
+                <button class="btn btn-sm btn-outline-primary" onclick="loadApps()"><i class="fas fa-rotate"></i> Refresh</button>
+              </div>
+              <div class="card-body">
+                <p class="text-muted small mb-2">Each entry is a scoped OpenBao credential an external service uses to read <code>secret/apps/&lt;name&gt;/*</code>. The token itself is shown <strong>once</strong> at mint — this list is metadata sso keeps so it can renew the token and so you can see what's been minted. If an app shows a renewal error, re-mint it here.</p>
+                <div id="apps-list"><div class="text-muted small">Loading…</div></div>
+              </div>
+            </div>
+          </div>
+        </div>
       </div>
     </div>
+
+    <!-- ── Shared tab ─────────────────────────────────────────────────── -->
+    <div class="tab-pane fade" id="tab-shared">
+      <div class="p-3">
+        <div class="row">
+        <div class="col-md-6">
+          <div class="card shadow-sm">
+            <div class="card-header d-flex justify-content-between align-items-center">
+              <h5 class="card-title mb-0">My shared secrets</h5>
+              <button class="btn btn-sm btn-primary" onclick="showCreateSharedModal()"><i class="fas fa-plus"></i> New</button>
+            </div>
+            <div class="list-group list-group-flush" id="shared-mine-list">
+              <div class="list-group-item text-center text-muted">Loading...</div>
+            </div>
+          </div>
+        </div>
+        <div class="col-md-6">
+          <div class="card shadow-sm">
+            <div class="card-header"><h5 class="card-title mb-0">Shared with me</h5></div>
+            <div class="list-group list-group-flush" id="shared-granted-list">
+              <div class="list-group-item text-center text-muted">Loading...</div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- Create Shared Secret Modal -->
+<div class="modal fade" id="sharedCreateModal" tabindex="-1">
+  <div class="modal-dialog">
+    <div class="modal-content">
+      <div class="modal-header">
+        <h5 class="modal-title">New Shared Secret</h5>
+        <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
+      </div>
+      <div class="modal-body">
+        <div class="mb-3">
+          <label class="form-label">Name (slug)</label>
+          <input type="text" class="form-control" id="shared-slug-input" placeholder="e.g. db-creds">
+        </div>
+        <div class="mb-3">
+          <label class="form-label">Description</label>
+          <input type="text" class="form-control" id="shared-desc-input" placeholder="optional">
+        </div>
+        <div class="mb-3">
+          <label class="form-label">Secret Data (JSON)</label>
+          <textarea class="form-control" id="shared-data-input" rows="6" style="font-family: monospace;">{
+  "key": "value"
+}</textarea>
+        </div>
+        <div class="alert alert-danger d-none" id="shared-create-error"></div>
+      </div>
+      <div class="modal-footer">
+        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button>
+        <button type="button" class="btn btn-primary" onclick="saveSharedSecret()">Create</button>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- Manage Grants Modal -->
+<div class="modal fade" id="sharedGrantsModal" tabindex="-1">
+  <div class="modal-dialog modal-lg">
+    <div class="modal-content">
+      <div class="modal-header">
+        <h5 class="modal-title">Share</h5>
+        <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
+      </div>
+      <div class="modal-body">
+        <div class="row g-2 mb-3">
+          <div class="col-4"><select class="form-select" id="grant-type-input"><option value="user">User</option><option value="app">App</option></select></div>
+          <div class="col-5"><input class="form-control" id="grant-id-input" placeholder="uid or app name"></div>
+          <div class="col-3"><button class="btn btn-primary w-100" onclick="addGrant()">Grant</button></div>
+        </div>
+        <div class="alert alert-danger d-none" id="grants-error"></div>
+        <div class="list-group" id="grants-list"><div class="list-group-item text-muted">No grants yet.</div></div>
+      </div>
+      <div class="modal-footer">
+        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- View Shared Secret Modal -->
+<div class="modal fade" id="sharedViewModal" tabindex="-1">
+  <div class="modal-dialog modal-lg">
+    <div class="modal-content">
+      <div class="modal-header">
+        <h5 class="modal-title" id="shared-view-title">Secret</h5>
+        <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
+      </div>
+      <div class="modal-body"><pre id="shared-view-content" class="bg-dark text-light p-3 rounded" style="min-height: 200px;"></pre></div>
+    </div>
   </div>
 </div>
 
@@ -134,7 +260,12 @@ curl "$VAULT_ADDR/v1/secret/data/apps/<span id="app-name-display"></span>/conf"
   // key relative to the subject's namespace (so 'foo' for a user means
   // secret/data/users/<uid>/foo).
   function vpath(kind, key) {
-    return `secret/${kind}/${VAULT_BASE}${key}`;
+    let cleanKey = key || '';
+    if (cleanKey.startsWith('/')) cleanKey = cleanKey.slice(1);
+    if (VAULT_BASE) {
+      return `secret/${kind}/${VAULT_BASE}${cleanKey}`;
+    }
+    return `secret/${kind}/${cleanKey}`;
   }
 
   function apiCall(method, path, body = null) {
@@ -156,7 +287,8 @@ curl "$VAULT_ADDR/v1/secret/data/apps/<span id="app-name-display"></span>/conf"
 
   async function loadSecrets() {
     try {
-      const res = await apiCall('GET', vpath('metadata', '?list=true'));
+      const listPath = vpath('metadata', '').replace(/\/$/, '') + '?list=true';
+      const res = await apiCall('GET', listPath);
       const listEl = document.getElementById('secrets-list');
       listEl.innerHTML = '';
       if (!res || !res.data || !res.data.keys || res.data.keys.length === 0) {
@@ -291,16 +423,194 @@ curl "$VAULT_ADDR/v1/secret/data/apps/<span id="app-name-display"></span>/conf"
       document.getElementById('app-token').textContent = result.token;
       document.getElementById('app-name-display').textContent = name;
       document.getElementById('app-result-card').classList.remove('d-none');
+      loadApps();
     } catch (err) {
       errorEl.textContent = err.message;
       errorEl.classList.remove('d-none');
     }
   }
 
+  // List the minted external-app tokens (metadata only). Makes the Apps tab show
+  // what's been minted instead of a credential that vanishes after the once-only
+  // token display.
+  async function loadApps() {
+    const $list = document.getElementById('apps-list');
+    if (!$list) return;
+    $list.textContent = 'Loading…';
+    try {
+      const res = await fetch('/api/vault/apps', {
+        headers: { 'auth-token': app.auth.getToken() }
+      });
+      if (!res.ok) { $list.innerHTML = '<div class="text-danger small">Failed to load apps.</div>'; return; }
+      const { apps = [] } = await res.json();
+      if (!apps.length) { $list.innerHTML = '<div class="text-muted small">No apps minted yet.</div>'; return; }
+      $list.innerHTML = '<div class="list-group shadow-sm">' + apps.map(a => {
+        const ok = !a.lastError;
+        const renewed = a.lastRenewedAt ? ' · renewed ' + moment(a.lastRenewedAt).fromNow() : ' · never renewed';
+        return `<div class="list-group-item d-flex justify-content-between align-items-center">
+          <div>
+            <strong class="font-monospace">${app.util.escapeHtml(a.name)}</strong>
+            ${ok ? '<span class="badge bg-success ms-1">renewing</span>' : '<span class="badge bg-danger ms-1" title="' + app.util.escapeHtml(a.lastError) + '">renewal error</span>'}
+            <div class="small text-muted">minted ${moment(a.createdOn).format('YYYY-MM-DD HH:mm')}${renewed}</div>
+          </div>
+          <span class="font-monospace small text-muted">secret/apps/${app.util.escapeHtml(a.name)}/</span>
+        </div>`;
+      }).join('') + '</div>';
+    } catch (err) {
+      $list.innerHTML = '<div class="text-danger small">Failed to load apps: ' + app.util.escapeHtml(err.message) + '</div>';
+    }
+  }
+
   function copyText(text) {
     navigator.clipboard.writeText(text).then(() => app.messages.toast('Copied', 'success'));
   }
 
+  // ── Shared secrets tab ──────────────────────────────────────────────
+  let currentShared = null;
+  const sharedCreateModal = new bootstrap.Modal(document.getElementById('sharedCreateModal'));
+  const sharedGrantsModal = new bootstrap.Modal(document.getElementById('sharedGrantsModal'));
+  const sharedViewModal = new bootstrap.Modal(document.getElementById('sharedViewModal'));
+
+  function sharedApi(path, method = 'GET', body = null) {
+    const opts = { method, headers: { 'Content-Type': 'application/json', 'auth-token': app.auth.getToken() } };
+    if (body) opts.body = JSON.stringify(body);
+    return fetch('/api/shared-secrets' + path, opts).then(async res => {
+      if (res.status === 404) return null;
+      if (!res.ok) { const t = await res.text(); throw new Error(`${res.status} ${t}`); }
+      if (res.status === 204) return null;
+      return res.json();
+    });
+  }
+
+  async function loadShared() {
+    try {
+      const res = await sharedApi('/');
+      const items = (res && res.items) || [];
+      renderSharedMine(items.filter(i => i.role === 'owner'));
+      renderSharedGranted(items.filter(i => i.role === 'grantee'));
+    } catch (err) {
+      document.getElementById('shared-mine-list').innerHTML =
+        `<div class="list-group-item text-danger">Error: ${err.message}</div>`;
+    }
+  }
+
+  function renderSharedMine(items) {
+    const el = document.getElementById('shared-mine-list');
+    if (!items.length) { el.innerHTML = '<div class="list-group-item text-center text-muted">No shared secrets yet</div>'; return; }
+    el.innerHTML = '';
+    items.forEach(s => {
+      const row = document.createElement('div');
+      row.className = 'list-group-item d-flex justify-content-between align-items-center';
+      row.innerHTML = `<div><i class="fas fa-share-alt text-secondary me-2"></i><strong>${s.slug}</strong><div class="small text-muted">${s.path}</div></div>
+        <div class="btn-group">
+          <button class="btn btn-sm btn-outline-primary" onclick="openGrants('${s.id}')"><i class="fas fa-users"></i> Share</button>
+          <button class="btn btn-sm btn-outline-danger" onclick="deleteShared('${s.id}')"><i class="fas fa-trash"></i></button>
+        </div>`;
+      el.appendChild(row);
+    });
+  }
+
+  function renderSharedGranted(items) {
+    const el = document.getElementById('shared-granted-list');
+    if (!items.length) { el.innerHTML = '<div class="list-group-item text-center text-muted">Nothing shared with you yet</div>'; return; }
+    el.innerHTML = '';
+    items.forEach(s => {
+      const row = document.createElement('a');
+      row.href = '#';
+      row.className = 'list-group-item list-group-item-action d-flex align-items-center';
+      row.innerHTML = `<i class="fas fa-key text-secondary me-3"></i><span>${s.slug}</span><small class="text-muted ms-auto">by ${s.ownerUid}</small>`;
+      row.onclick = (e) => { e.preventDefault(); viewShared(s); };
+      el.appendChild(row);
+    });
+  }
+
+  function showCreateSharedModal() {
+    currentShared = null;
+    document.getElementById('shared-slug-input').value = '';
+    document.getElementById('shared-desc-input').value = '';
+    document.getElementById('shared-data-input').value = '{\n  "key": "value"\n}';
+    document.getElementById('shared-create-error').classList.add('d-none');
+    sharedCreateModal.show();
+  }
+
+  async function saveSharedSecret() {
+    const err = document.getElementById('shared-create-error');
+    err.classList.add('d-none');
+    let data;
+    try { data = JSON.parse(document.getElementById('shared-data-input').value); }
+    catch (e) { err.textContent = 'Invalid JSON: ' + e.message; err.classList.remove('d-none'); return; }
+    try {
+      await sharedApi('/', 'POST', {
+        slug: document.getElementById('shared-slug-input').value.trim(),
+        description: document.getElementById('shared-desc-input').value.trim(),
+        data
+      });
+      sharedCreateModal.hide();
+      await loadShared();
+    } catch (e) { err.textContent = e.message; err.classList.remove('d-none'); }
+  }
+
+  async function viewShared(s) {
+    document.getElementById('shared-view-title').textContent = s.slug + ' (by ' + s.ownerUid + ')';
+    document.getElementById('shared-view-content').textContent = 'Loading...';
+    sharedViewModal.show();
+    try {
+      const res = await apiCall('GET', 'secret/data/' + s.path);
+      document.getElementById('shared-view-content').textContent =
+        (res && res.data && res.data.data) ? JSON.stringify(res.data.data, null, 2) : 'No data found.';
+    } catch (e) {
+      document.getElementById('shared-view-content').textContent = 'Error: ' + e.message;
+    }
+  }
+
+  async function openGrants(id) {
+    currentShared = id;
+    document.getElementById('grants-error').classList.add('d-none');
+    document.getElementById('grant-id-input').value = '';
+    sharedGrantsModal.show();
+    try {
+      const res = await sharedApi('/' + id + '/grants');
+      const grants = (res && res.grants) || [];
+      const el = document.getElementById('grants-list');
+      el.innerHTML = '';
+      if (!grants.length) el.innerHTML = '<div class="list-group-item text-muted">No grants yet.</div>';
+      grants.forEach(g => {
+        const row = document.createElement('div');
+        row.className = 'list-group-item d-flex justify-content-between align-items-center';
+        row.innerHTML = `<span><span class="badge bg-secondary me-2">${g.granteeType}</span>${g.granteeId}</span>
+          <button class="btn btn-sm btn-outline-danger" onclick="revokeGrant('${g.id}')"><i class="fas fa-times"></i></button>`;
+        el.appendChild(row);
+      });
+    } catch (e) {
+      document.getElementById('grants-list').innerHTML = `<div class="list-group-item text-danger">${e.message}</div>`;
+    }
+  }
+
+  async function addGrant() {
+    const err = document.getElementById('grants-error');
+    err.classList.add('d-none');
+    try {
+      await sharedApi('/' + currentShared + '/grants', 'POST', {
+        granteeType: document.getElementById('grant-type-input').value,
+        granteeId: document.getElementById('grant-id-input').value.trim()
+      });
+      document.getElementById('grant-id-input').value = '';
+      openGrants(currentShared);
+    } catch (e) { err.textContent = e.message; err.classList.remove('d-none'); }
+  }
+
+  async function revokeGrant(grantId) {
+    try { await sharedApi('/' + currentShared + '/grants/' + grantId, 'DELETE'); openGrants(currentShared); }
+    catch (e) { app.messages.toast('Error revoking: ' + e.message, 'danger'); }
+  }
+
+  async function deleteShared(id) {
+    const confirmed = await app.messages.confirm('Delete this shared secret? Grantees will immediately lose access.', $('#shared-mine-list'), 'warning');
+    if (!confirmed) return;
+    try { await sharedApi('/' + id, 'DELETE'); await loadShared(); }
+    catch (e) { app.messages.toast('Error deleting: ' + e.message, 'danger'); }
+  }
+
   (async function init() {
     const user = await app.auth.forceLogin();
     if (!user) return; // not logged in — forceLogin redirected to /login
@@ -312,8 +622,10 @@ curl "$VAULT_ADDR/v1/secret/data/apps/<span id="app-name-display"></span>/conf"
         '<i class="fas fa-lock"></i> Vault Secrets <small class="text-muted">(admin — all of secret/)</small>';
       document.getElementById('secret-path-label').textContent = 'Secret path (under secret/)';
       document.getElementById('secret-path-input').placeholder = 'e.g. apps/my-service/conf';
+      loadApps();
     }
     loadSecrets();
+    loadShared();
   })();
 </script>