chore: bump package.json version to 1.20.0

Merge pull request #151 from theta42/feature/v1.20.0-theta-agent-c2
feat: Protocol v1.1.0 theta-agent C2 integration & install wizard
2026-08-03 02:35:04 -04:00 · 2026-08-03 02:21:50 -04:00 · 2026-08-03 02:18:09 -04:00 · 2026-08-02 22:49:52 -04:00 · 2026-08-02 21:30:47 -04:00
44 changed files with 3347 additions and 80 deletions
@@ -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.
@@ -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
@@ -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>
@@ -0,0 +1,88 @@
 ---
 layout: default
 title: Discovery Agents
 nav_order: 5
 ---
 # Discovery Agents
 The SSO Manager supports a robust agent architecture for auto-discovering devices, hosts, and services across your home lab or data center. Agents run on a scheduled cron and feed their data into a central **Reconciliation Engine** that smartly merges information based on MAC addresses and IPs.
 ## Writing a Custom Agent
 Agents are simple JavaScript files placed in `nodejs/agents/discovery/`.
 A agent must export a single `discover` async function that returns a standardized graph of `resources` and `edges`.
 ### Agent Skeleton
 ```javascript
 // nodejs/agents/discovery/my_custom_agent.js
 module.exports = {
  discover: async (config) => {
    const { url, apiKey } = config; // Provided by your configuration
    const resources = [];
    const edges = [];
    // 1. Fetch your data from an API
    // const data = await fetch(...);
    // 2. Map data to Resources
    resources.push({
      kind: 'network_device', // 'host', 'service', 'network_device', 'unmanaged_device'
      name: 'My Switch',
      slug: 'my-switch-01',
      metadata: {
        make: 'Vendor',
        model: 'Model X',
        interfaces: [
          { mac: '00:1A:2B:3C:4D:5E', ip: '10.0.0.5' }
        ]
      }
    });
    // 3. Map relations to Edges (optional)
    edges.push({
      parentSlug: 'my-switch-01',
      childSlug: 'some-connected-client-slug',
      relation: 'connected_to' // 'hosts', 'exposes', 'connected_to'
    });
    return { resources, edges };
  }
 };
 ```
 ## Configuration
 Agents are automatically loaded and executed by the internal BullMQ job scheduler. You configure them in your `config/sso-secrets.js`:
 ```javascript
 module.exports = {
  // ... existing config ...
  discovery: {
    agents: {
      my_custom_agent: {
        enabled: true,
        cron: '*/30 * * * *', // Run every 30 minutes
        url: 'https://api.example.com',
        apiKey: 'secret-key'
      },
      nmap: {
        enabled: true,
        cron: '0 * * * *',
        targetRange: '192.168.1.0/24'
      }
    }
  }
 };
 ```
 ## The Reconciliation Engine
 When your agent returns its graph, the Reconciliation Engine takes over:
 1. **Matching:** It tries to find an existing device in the database matching any MAC address provided in the `interfaces` array. If no MAC matches, it falls back to IP address, and then to `slug`.
 2. **Merging:** If it finds a match, it gracefully merges the metadata (so your agent can add CPU info to a host that NMAP previously found).
 3. **Source Tracking:** It records your agent's filename in the `discovery_sources` array on the resource, and updates the `last_seen` timestamp.
 4. **LDAP Spam Prevention:** Brand new devices are marked as `managed: false`. They will not pollute your LDAP directory until an admin explicitly promotes them.
@@ -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;
 }
@@ -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>
@@ -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)
@@ -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)
@@ -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)
@@ -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)
@@ -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)
@@ -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
@@ -0,0 +1,85 @@
 ---
 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/).
 ## 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.
@@ -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)
@@ -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)
@@ -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).
@@ -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.
@@ -0,0 +1,4 @@
 User-agent: *
 Allow: /
 Sitemap: https://theta42.github.io/sso-manager-node/sitemap.xml
@@ -0,0 +1,38 @@
 # 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.
 ## 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>
 ```
@@ -72,7 +72,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'));
@@ -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
@@ -1,12 +1,12 @@
 {
  "name": "t42-sso-manager",
-  "version": "1.19.6",
+  "version": "1.20.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "t42-sso-manager",
-      "version": "1.19.6",
+      "version": "1.20.0",
      "license": "MIT",
      "dependencies": {
        "@fortawesome/fontawesome-free": "^7.3.0",
@@ -1,6 +1,6 @@
 {
  "name": "t42-sso-manager",
-  "version": "1.19.6",
+  "version": "1.20.0",
  "description": "A very simple LDAP management and SSO system",
  "author": [
    {
@@ -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);
+      // Pass custom arguments in constructor so node-nmap includes them before spawning nmap process.
-      scan.command.push('-Pn');
+      // -Pn: treat all hosts as online (skip ping/ARP host discovery which fails inside Docker containers NAT/bridge)
-      scan.command.push('-F'); // fast scan, 100 top ports
+      // -sT: TCP connect scan (unprivileged scan compatible with container environments)
-      scan.command.push('--min-rate', '100'); // speed up the scan
+      // -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(' ')}`);
@@ -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(){
@@ -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"
@@ -1,53 +1,105 @@
 'use strict';
 const express = require('express');
 const agentManager = require('../utils/agent_manager');
 module.exports = function initAgentWebSockets(app) {
-    if (!app.wss) {
+  if (!app.wss) {
-        console.warn("WebSocket server for agents is not initialized.");
+    console.warn("WebSocket server for agents is not initialized.");
-        return;
+    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) => {
+    const remoteAddr = req.socket.remoteAddress;
-        // Parse the token from query param or header (e.g. ?token=XYZ)
+    console.log(`[Theta Agent] Agent connected from ${remoteAddr} with token ${token.substring(0, 8)}...`);
        // 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'];
-        if (!token) {
+    agentManager.registerAgent(token, ws, remoteAddr);
-            ws.close(4001, 'Unauthorized: Missing token');
+
-            return;
+    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}`);
        }
-
+      } catch (err) {
-        console.log(`[Theta Agent] Agent connected from ${req.socket.remoteAddress}`);
+        console.error("[Theta Agent] Error parsing message:", err);
-
+      }
        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'
            }
        }));
    });
    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) {}
  });
  // REST API routes for Agent Management (mounted under /api/agent)
  const router = express.Router();
  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 });
    }
  });
  app.use('/api/agent', router);
 };
@@ -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;
@@ -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);
@@ -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);
  });
 });
@@ -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);
  });
 });
@@ -0,0 +1,51 @@
 '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(),
  })
 }));
 const baoConf = require('@simpleworkjs/bao-conf');
 const vaultBroker = require('../utils/vault_broker');
 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 = ["list", "read", "delete"] }');
        expect(body.policy).toContain('path "secret/metadata/" { capabilities = ["list", "read", "delete"] }');
        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/"')
    }));
  });
 });
@@ -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();
@@ -38,16 +38,15 @@ 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
+		// Catalog requires login - it's the end-user view of their accessible resources.
-		// ordinary users. Before this, every nav item was admin-only and a
+		{href: '/', icon: 'fa-solid fa-compass', label: 'Catalog', groups: ['login']},
 		// non-admin had no signposted destination at all.
 		{href: '/', icon: 'fa-solid fa-compass', label: 'Catalog', groups: []},
 		{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']},
 	],
 };
@@ -106,10 +106,21 @@ async function getOrCreateUserToken(uid) {
 }
 // ── Admin token (read/write all of secret/) ─────────────────────────────────
 function adminPolicyHcl() {
 	// The bare `secret/metadata` / `secret/metadata/` grants let an admin LIST
 	// the KV mount root (the top-level dirs); `secret/metadata/*` covers nested
 	// paths but NOT the root itself, so without it the /vault secrets list 403s.
 	return `path "secret/data/*" { capabilities = ["create", "read", "update", "delete", "list"] }
 path "secret/metadata" { capabilities = ["list", "read", "delete"] }
 path "secret/metadata/" { capabilities = ["list", "read", "delete"] }
 path "secret/metadata/*" { capabilities = ["list", "read", "delete"] }`;
 }
 async function getOrCreateAdminToken(uid) {
 	const cacheKey = `vault_token:admin:${uid || 'global'}`;
 	const cached = await cacheGet(cacheKey);
 	if (cached) return cached;
 	await ensurePolicy('sso-admin', adminPolicyHcl());
 	const { token, ttl } = await mintToken(['sso-admin']);
 	await cacheSet(cacheKey, token, Math.max(ttl - 60, 60));
 	return token;
@@ -45,7 +45,7 @@
 	async function saveConf() {
 		const btn = $('#btn-save');
 		btn.prop('disabled', true).html('<i class="fas fa-spinner fa-spin"></i> Saving...');
-		
+
 		const payload = {
 			smtp: {
 				host: $('#smtp-host').val(),
@@ -79,7 +79,82 @@
 			btn.prop('disabled', false).html('<i class="fas fa-save"></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 $inputGroup = $('#test-email-to').closest('.input-group');
 		const btn = $inputGroup.find('button');
 		const originalHtml = btn.html();
 		btn.prop('disabled', true).html('<i class="fas fa-spinner fa-spin"></i> Sending...');
 		try {
 			// First save the SMTP config, then send test email
 			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')
 				}
 			};
 			// Save config first
 			await app.api.post('conf', payload);
 			// Then send test email
 			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 $inputGroup = $('#test-sms-to').closest('.input-group');
 		const btn = $inputGroup.find('button');
 		const originalHtml = btn.html();
 		btn.prop('disabled', true).html('<i class="fas fa-spinner fa-spin"></i> Sending...');
 		try {
 			// First save the VoIP.ms config, then send test SMS
 			const payload = {
 				voipms: {
 					username: $('#voipms-username').val(),
 					did: $('#voipms-did').val(),
 					password: $('#voipms-password').val()
 				}
 			};
 			// Save config first
 			await app.api.post('conf', payload);
 			// Then send test SMS
 			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') {
@@ -239,6 +314,28 @@
 							<button class="btn btn-outline-secondary" type="button" onclick="togglePassword('smtp-pass')"><i class="fas fa-eye"></i></button>
 						</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>
 					<hr class="my-4">
 					<div class="mb-3">
 						<label class="form-label">Send Test SMS</label>
 						<div class="input-group">
 							<input type="tel" class="form-control" id="test-sms-to" placeholder="+15551234567">
 							<button class="btn btn-outline-primary" type="button" onclick="sendTestSms()">
 								<i class="fas fa-paper-plane"></i> Send Test SMS
 							</button>
 						</div>
 						<div class="form-text">Send a test SMS to verify your VoIP.ms configuration is working.</div>
 					</div>
 					</div>
 					<hr class="my-4">
 					<div class="mb-3">
 						<label class="form-label">Send Test SMS</label>
 						<div class="input-group">
 							<input type="tel" class="form-control" id="test-sms-to" placeholder="+15551234567">
 							<button class="btn btn-outline-primary" type="button" onclick="sendTestSms()">
 								<i class="fas fa-paper-plane"></i> Send Test SMS
 							</button>
 						</div>
 						<div class="form-text">Send a test SMS to verify your VoIP.ms configuration is working.</div>
 					</div>
 					<div class="mb-3">
 						<label class="form-label">From Address</label>
@@ -248,6 +345,17 @@
 						<input class="form-check-input" type="checkbox" id="smtp-secure">
 						<label class="form-check-label">Use Secure (TLS)</label>
 					</div>
 						<hr class="my-4">
 						<div class="mb-3">
 							<label class="form-label">Send Test Email</label>
 							<div class="input-group">
 								<input type="email" class="form-control" id="test-email-to" placeholder="recipient@example.com">
 								<button class="btn btn-outline-primary" type="button" onclick="sendTestEmail()">
 									<i class="fas fa-paper-plane"></i> Send Test Email
 								</button>
 							</div>
 							<div class="form-text">Send a test email to verify your SMTP configuration is working.</div>
 						</div>
 				</div>
 			</div>
 		</div>
@@ -306,6 +414,16 @@
 							<button class="btn btn-outline-secondary" type="button" onclick="togglePassword('voipms-password')"><i class="fas fa-eye"></i></button>
 						</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>
 					<hr class="my-4">
 					<div class="mb-3">
 						<label class="form-label">Send Test SMS</label>
 						<div class="input-group">
 							<input type="tel" class="form-control" id="test-sms-to" placeholder="+15551234567">
 							<button class="btn btn-outline-primary" type="button" onclick="sendTestSms()">
 								<i class="fas fa-paper-plane"></i> Send Test SMS
 							</button>
 						</div>
 						<div class="form-text">Send a test SMS to verify your VoIP.ms configuration is working.</div>
 					</div>
 				</div>
 			</div>
@@ -40,6 +40,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>
@@ -1272,6 +1275,232 @@
    });
  }
  // --- 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');
    });
  }
  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: '<i class="fa-solid fa-shield-halved text-primary me-2"></i> Install Theta Agent',
      bodyHtml: bodyHtml,
      size: 'lg'
    });
    updateAgentCommands();
  }
  // 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.
Author	SHA1	Message	Date
wmantly	3ecc153563	chore: bump package.json version to 1.20.0 Pull Request Tests / Run Tests (20.x) (push) Failing after 1m25s Details Pull Request Tests / Run Tests (22.x) (push) Failing after 27s Details Pull Request Tests / Run Tests (18.x) (push) Failing after 13m44s Details Pull Request Tests / Test Summary (push) Failing after 4s Details	2026-08-03 02:35:04 -04:00
wmantly	7a364bfb8e	Merge pull request #151 from theta42/feature/v1.20.0-theta-agent-c2 feat: Protocol v1.1.0 theta-agent C2 integration & install wizard	2026-08-03 02:21:50 -04:00
wmantly	b7aac2d2ba	feat: Protocol v1.1.0 theta-agent C2 integration, agent install wizard, OpenBao 403 fix, nmap discovery fix, and restored documentation	2026-08-03 02:18:09 -04:00
wmantly	4945dec9c2	Merge pull request #150 from theta42/release/v1.19.6 Release v1.19.6	2026-08-02 22:49:52 -04:00
wmantly	59d68c0269	chore: release v1.19.6 - UI nav auth, SMTP UI-only, test messages, directory.md Pull Request Tests / Run Tests (18.x) (push) Failing after 1m6s Details Pull Request Tests / Run Tests (20.x) (push) Failing after 29s Details Pull Request Tests / Run Tests (22.x) (push) Failing after 29s Details Pull Request Tests / Test Summary (push) Failing after 4s Details ### Fixed - Navbar shows Catalog/Vault for unauthenticated users — Changed nav gating from `groups: []` (always visible) to `groups: ['login']` and added synthetic 'login' group handling in app-base.js. - 500 ENOENT: no such file or directory, open '/docs/directory.md' — Created the missing documentation file. ### Changed - SMTP configuration UI-only — Removed SMTP from static config files (conf/base.js, sso-secrets.js, setup.env.example). SMTP is now only configurable via the runtime UI at /conf. ### Added - Test email/SMS capability — Added POST /api/conf/test-email and POST /api/conf/test-sms endpoints with UI buttons in the Configuration page. Saves config first, then sends test message to verify settings. ### theta-env setup.sh - Non-interactive theta-agent configuration — Added CFG_THETA_AGENT_ENABLE, CFG_THETA_AGENT_LDAP_AUTH, and CFG_THETA_AGENT_FULL_CONTROL variables to setup.env (all default to 1/enabled). Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-02 21:30:47 -04:00