Merge pull request #77 from theta42/release/v1.3.1

Release v1.3.1: bump proxy to v1.2.1, sso-manager-node to v1.1.18

.env.example

@@ -14,7 +14,8 @@
 LDAP_BASE_DN=dc=example,dc=com
 # DNS domain (dc=foo,dc=bar -> foo.bar). Leave blank to derive from LDAP_BASE_DN.
 LDAP_DOMAIN=
-LDAP_ADMIN_PASS=change-me-ldap-admin-password
+# LDAP admin password. MUST be changed. Leave blank and setup.sh will generate one.
+LDAP_ADMIN_PASS=CHANGE-ME
 ORG_NAME="My Org"
 
 # ── Public hostnames (REQUIRED) ───────────────────────────────────────────────
@@ -30,13 +31,15 @@ PROXY_HOST=proxy.example.com
 # app_sso_oauth_admin, and logs in as them to register the proxy OAuth client.
 # Re-running setup.sh resets this password to BOOTSTRAP_ADMIN_PASS.
 BOOTSTRAP_ADMIN_UID=admin
-BOOTSTRAP_ADMIN_PASS=change-me-admin-password
+# First admin password. MUST be changed. Leave blank and setup.sh will generate one.
+BOOTSTRAP_ADMIN_PASS=CHANGE-ME
 BOOTSTRAP_ADMIN_EMAIL=admin@example.com
 
 # ── Proxy LDAP service account (created by the bootstrap) ────────────────────
 # The proxy binds to LDAP as cn=ldapclient,ou=people,<base> with this password.
 # Re-running setup.sh resets it to LDAP_SERVICE_PASS.
-LDAP_SERVICE_PASS=change-me-ldap-service-password
+# LDAP service-account password. MUST be changed. Leave blank and setup.sh will generate one.
+LDAP_SERVICE_PASS=CHANGE-ME
 
 # ── OAuth JWT secret (REQUIRED — persist it) ────────────────────────────────
 # Signs the SSO's access/refresh tokens. Generate with: openssl rand -hex 32
@@ -73,4 +76,10 @@ MGMT_BIND=0.0.0.0
 # Defaults to LDAP_DOMAIN. Set to the hostname the proxy connects via
 # (sso-manager inside the docker net uses the service name, which is in the
 # cert's SAN, so the default is usually fine).
-LDAP_CERT_CN=
+LDAP_CERT_CN=
+
+# ── Optional: LDAPS hostname shown on the SSO /integrations page ────────────────
+# Leave blank to derive from the public SSO host (SSO_HOST). Set an internal-only
+# name like 'ldap.internal.example.com' or 'sso-manager' so direct-LDAP clients
+# don't need a public 636 port forward. See docs/ldap.md for network layouts.
+LDAPS_HOST=

CHANGELOG.md

@@ -10,6 +10,229 @@ for what changed inside the apps it composes.
 
 ## [Unreleased]
 
+## [1.3.1] - 2026-07-21
+
+### Bumped
+- proxy -> [v1.2.1](https://github.com/theta42/proxy/releases/tag/v1.2.1)
+- sso-manager-node -> [v1.1.18](https://github.com/theta42/sso-manager-node/releases/tag/v1.1.18)
+
+proxy:
+
+### Fixed
+- The bootstrap anti-lockout admin account was always created as `proxyadmin2` regardless of `conf.auth.adminUsers`, while `migrations/permission_bootstrap.js` grants the global-admin permission to `conf.auth.adminUsers[0]`. If an operator customized `adminUsers` away from the default, the bootstrapped account and the permissioned account were two different (non-matching) usernames, so the anti-lockout account ended up with no admin access. `models/user_redis.js` now derives the bootstrap username from `conf.auth.adminUsers[0]` (falling back to `proxyadmin2`), matching `permission_bootstrap.js`.
+- Corrected a `secrets.js.example` comment that claimed the bootstrap admin's password "defaults to the username itself" — it actually generates a random password printed to the container log on first boot.
+
+### Changed
+- Refreshed all README screenshots (hosts, per-host SSO auth, per-host basic auth) against the current UI, and added a new load-balancing screenshot for the multi-target feature.
+
+sso-manager-node:
+
+### Added
+- N-Way Multi-Master LDAP replication: `LDAP_SERVER_ID` + `LDAP_REPLICATION_HOSTS` configure `syncrepl` peers in the bundled OpenLDAP, and a new `/sites` page (nav: **Sites**) shows each configured peer's LDAP URL and live reachability.
+- A `location` property on users, editable from the profile and user-edit forms.
+
+### Fixed
+- `/sites` (added above) 500'd on every load: `views/sites.ejs` included nonexistent partials `header`/`footer` instead of this app's actual `top`/`bottom`. Fixed to match every other view.
+
+### Changed
+- Refreshed all README screenshots (dashboard, users, groups, OAuth apps) against the current UI, and added a new Sites & Replication screenshot.
+
+### theta-env own changes
+- Refreshed `docs/images/sso-dashboard.png` and `docs/images/proxy-hosts.png` to match the submodules' updated screenshots.
+
+## [1.1.20] - 2026-07-20
+
+### Bumped
+- proxy -> [v1.1.17](https://github.com/theta42/proxy/releases/tag/v1.1.17)
+
+proxy:
+
+### Fixed
+- An existing single-label subdomain host (e.g. `sso.nl.wgnode.com`) could not be attached to a wildcard cert added later (e.g. `*.nl.wgnode.com`): `Host.lookUpWildcardParent()` only checked the wildcard-as-child position (the wildcard's own base domain) and missed the far more common wildcard-as-sibling case, so the edit form's "Parent Wildcard" option stayed permanently greyed out. It now checks both positions, and a regression test covers the sibling case.
+
+## [1.1.19] - 2026-07-18
+
+### Bumped
+- sso-manager-node -> [v1.1.17](https://github.com/theta42/sso-manager-node/releases/tag/v1.1.17)
+
+sso-manager-node:
+
+### Added
+- `conf.ldap.ldapsHost` and `conf.ldap.ldapsPort` config options for advertising a separate, internal-only LDAPS hostname on the `/integrations` page. Falls back to the public OAuth issuer host when unset.
+- Contextual help panel on `/integrations` → LDAP explaining why LDAPS needs a hostname, why port 636 should not be forwarded publicly, and the recommended internal-DNS / Docker-internal alternatives.
+- Tests for the `/integrations` route's LDAPS URL derivation and `ldapsHost` override.
+
+### Changed
+- `nodejs/package.json` / `package-lock.json` version bumped to `1.1.17`.
+- `routes/index.js` now derives the displayed LDAPS URL from `conf.ldap.ldapsHost`/`ldapsPort` with fallback to the OAuth issuer host.
+- `docs/configuration.md`, `docs/ldap.md`, `DEPLOYMENT.md`, and `secrets.js.example` document the new `ldapsHost`/`ldapsPort` options and recommended network layouts.
+
+### theta-env own changes
+- `setup.env.example` adds optional `CFG_LDAPS_HOST` for the internal LDAPS hostname.
+- `setup.sh` passes `CFG_LDAPS_HOST` into the generated `./config/sso-secrets.js` as `ldap.ldapsHost`.
+- `config.example/sso-secrets.js.example` documents `ldap.ldapsHost` / `ldap.ldapsPort`.
+- `.env.example` adds `LDAPS_HOST` for legacy `.env` migrations.
+- `docker-compose.yml` comments warn against forwarding 636 to the public internet.
+- `README.md` explains the `CFG_LDAPS_HOST` recommendation in the port-forwarding section.
+
+## [1.1.18] - 2026-07-18
+
+### Bumped
+- proxy -> [v1.1.16](https://github.com/theta42/proxy/releases/tag/v1.1.16)
+- sso-manager-node -> [v1.1.16](https://github.com/theta42/sso-manager-node/releases/tag/v1.1.16)
+
+proxy:
+
+### Changed
+- Public-release packaging: removed `"private": true` from `nodejs/package.json`, corrected the repository URL to `https://github.com/theta42/proxy.git`, and fixed the MIT `LICENSE` copyright line.
+- Genericized committed config defaults in `conf/base.js` and `conf/development.js` (`example.com` / `localhost` instead of theta42 infrastructure).
+- The bootstrap `proxyadmin2` account now gets a random, one-time password when `auth.localAdminPass` is unset, instead of the well-known default.
+
+### Security
+- Sanitized rendered docs HTML with `xss` in `routes/docs.js`.
+- The Unix socket JSON-RPC socket is now created with mode `660` instead of world-writable `777`.
+
+### Fixed
+- The global error handler no longer leaks `err.keys`, stack traces, or internal details in JSON responses.
+- `DEPLOYMENT.md` and `docs/docker.md` now correctly describe the `CONF_SECRETS` env-var mechanism.
+
+sso-manager-node:
+
+### Security
+- Hardened LDAP filter and DN construction against injection in `models/group_ldap.js` and `models/user_ldap.js`.
+- Replaced `Math.random()`-based token/UUID/OTP generation with `crypto.randomUUID()` / `crypto.randomInt()` in `models/token.js`, `models/oauth_code.js`, and `models/oauth_client.js`.
+- Refused startup when `oauth.jwtSecret` is missing or placeholder.
+- Sanitized rendered docs/Terms-of-Service HTML with `xss` to block malicious markdown output.
+- Removed full-object `console.log` of new-user data and reduced login error logging to `name`/`message` only.
+
+### Changed
+- Public-release packaging: removed `"private": true` from `nodejs/package.json` and bumped version to `1.1.16`.
+
+### Fixed
+- `models/email.js`: fixed from-address template rendering bug.
+
+### theta-env own changes
+- `CHANGELOG.md` now embeds the full app-level release notes for each submodule bump, not just links.
+- `.env.example` no longer ships realistic-looking default passwords; values are clearly placeholders.
+- `config.example/*.js.example` comments now describe the actual `CONF_SECRETS` env-var loading mechanism.
+- `setup.sh` summary no longer prints generated passwords to stdout; it points to `./config/*.js`.
+- `bootstrap/bootstrap.js` fails hard instead of falling back to weak default passwords when config is missing.
+
+## [1.1.17] - 2026-07-18
+
+### Bumped
+- proxy -> [v1.1.15](https://github.com/theta42/proxy/releases/tag/v1.1.15)
+- sso-manager-node -> [v1.1.15](https://github.com/theta42/sso-manager-node/releases/tag/v1.1.15)
+
+Both apps' bare-metal `install.sh` now installs to `/opt/theta42/<app>` and seeds `/etc/<app>/secrets.js` on first run, matching a `wget -O - .../install.sh | sudo bash` one-line install for both (previously proxy-only); re-running it prints the version it's updating from/to. sso-manager-node's installer was rewritten from a flag-driven, copy-based script into the same idempotent git-clone pattern proxy already used, and now bootstraps OpenLDAP itself on first run instead of requiring the repo to already be checked out locally. None of this affects the Docker/unified-stack deployment this repo orchestrates — bare-metal-only.
+
+## [1.1.16] - 2026-07-18
+
+### Bumped
+- proxy -> [v1.1.14](https://github.com/theta42/proxy/releases/tag/v1.1.14)
+- sso-manager-node -> [v1.1.14](https://github.com/theta42/sso-manager-node/releases/tag/v1.1.14)
+
+Both: bumped `@simpleworkjs/conf` to 1.2.0 and `jq-repeat` to 2.2.0.
+
+### Changed
+- `./config/sso-secrets.js` and `./config/proxy-secrets.js` are now loaded via each app's `CONF_SECRETS` env var (set by the entrypoint) instead of being symlinked into `/app/conf/secrets.js` — neither container needs write access to its own `conf/` directory anymore. No change to the config file format or bind mounts; existing `./config/` directories keep working as-is.
+
+## [1.1.15] - 2026-07-17
+
+### Bumped
+- proxy -> [v1.1.13](https://github.com/theta42/proxy/releases/tag/v1.1.13)
+- sso-manager-node -> [v1.1.13](https://github.com/theta42/sso-manager-node/releases/tag/v1.1.13)
+
+proxy:
+
+### Fixed
+- The host edit form's "Parent Wildcard" option stayed greyed out even when a valid wildcard actually existed for that host, so an already-created host could never be switched onto one from the edit modal (only brand-new hosts, via the field's `keyup` handler, ever saw it become available). The underlying `/host/lookup/:item` check also had the same self-match issue as the recently-fixed backend bug: it resolved an already-existing host to its own record instead of a sibling wildcard. Added a dedicated `/host/wildcard-parent/:item` endpoint that checks both directions, and the edit form now actually runs the check when it opens.
+- Fixed an nginx startup warning: `the "listen ... http2" directive is deprecated, use the "http2" directive instead`. Migrated to the standalone `http2 on;` directive (nginx 1.25.1+).
+
+### Added
+- Four new plain-language docs aimed at less technical readers, replacing the system-design-level Architecture/Installation docs as the target of most card help links: **Hosts & HTTPS**, **DNS Providers**, **Users, Groups & Permissions**, and **API Tokens**. Each links onward to the deeper technical reference for readers who want it; the technical docs link back the other way too. The personal-access-token card (previously missed entirely) now has a help link.
+
+### Fixed
+- The in-app docs viewer rendered every `docs/*.md` page with a garbled heading and a stray horizontal rule at the top — Jekyll front matter (meant only for the GitHub Pages build) was never stripped before being handed to the markdown renderer. Also fixed: cross-doc links never resolved in-app, since this viewer serves docs at `/docs/<slug>` with no `.html` suffix — they're now rewritten to the correct in-app URL (by registered slug, falling back to the doc's real filename), the same way image paths already were.
+
+sso-manager-node:
+
+### Added
+- Three new plain-language docs aimed at less technical readers, replacing the schema-level LDAP/OAuth/API docs as the target of most card help links: **Accounts, Groups & Managers**, **Connecting Apps (SSO)**, and **API Tokens**. Each links onward to the deeper technical reference for readers who want it; the technical docs link back the other way too. The personal-access-token card (previously missed) now links to its own doc.
+
+### Fixed
+- The in-app docs viewer rendered every `docs/*.md` page with a garbled heading and a stray horizontal rule at the top — Jekyll front matter (meant only for the GitHub Pages build) was never stripped before being handed to the markdown renderer. Also fixed: cross-doc links (`ldap.html`, `index.html`, etc.) never resolved in-app, since this viewer serves docs at `/docs/<slug>` with no `.html` suffix — they're now rewritten to the correct in-app URL, the same way image paths already were.
+- The new concept docs' cross-links (`concepts-accounts.html` etc.) are the correct, working URL on the Jekyll/GitHub Pages build (where the page's URL is its filename stem) but didn't resolve in the in-app docs viewer, which serves docs at a separate short slug (`/docs/accounts`). The in-app renderer now also resolves a doc's real filename as a fallback, so one link written in a doc works on both targets.
+
+## [1.1.14] - 2026-07-17
+
+### Bumped
+- proxy -> [v1.1.11](https://github.com/theta42/proxy/releases/tag/v1.1.11)
+- sso-manager-node -> [v1.1.11](https://github.com/theta42/sso-manager-node/releases/tag/v1.1.11)
+
+Both: moved the help (❓) link out of the global header and onto each relevant card individually, so it deep-links straight to the doc that actually covers that card instead of one generic per-page guess.
+
+## [1.1.13] - 2026-07-17
+
+### Bumped
+- proxy -> [v1.1.10](https://github.com/theta42/proxy/releases/tag/v1.1.10)
+- sso-manager-node -> [v1.1.10](https://github.com/theta42/sso-manager-node/releases/tag/v1.1.10)
+
+Both: added a help icon (❓) in the top-right header that deep-links to the doc most relevant to the current page, and made the in-app docs viewer (`/docs`) searchable (a simple line-substring search over the local doc set, no new dependency, still works with no internet access).
+
+## [1.1.12] - 2026-07-17
+
+### Bumped
+- proxy -> [v1.1.9](https://github.com/theta42/proxy/releases/tag/v1.1.9)
+
+proxy:
+
+### Added
+- The host list now shows who created each host, and when.
+- Plain (non-wildcard) hosts can now be renamed after creation — the hostname field is no longer permanently locked. Wildcard hosts, wildcard children, and auto-created subdomain cache entries stay locked, since other records reference them by name.
+- More inline help text on the host create/edit form (Target SSL, wildcard matching behavior).
+
+### Fixed
+- The host create/edit modal's tabs could overflow awkwardly on narrow (mobile) screens — they now scroll horizontally instead.
+- Fixed a bug in the vendored `model-redis` library's record-rename path: renaming a record's primary key while another `always`-type field (e.g. `updated_on`) is defined earlier in the schema left a stray, incomplete hash behind under the old key, making that name permanently unavailable for reuse. Worked around in `Host.prototype.update()`.
+
+## [1.1.11] - 2026-07-17
+
+### Bumped
+- proxy -> [v1.1.8](https://github.com/theta42/proxy/releases/tag/v1.1.8)
+
+proxy:
+
+### Fixed
+- **Couldn't attach an existing host to a parent wildcard.** The host edit form's "Parent Wildcard" option submitted correctly, but `Host.prototype.update()` had no `challengeType` handling at all (only `Host.create()` did) — selecting it and saving silently did nothing. Added the same wildcard-parent lookup to `update()`.
+- **Couldn't register a wildcard's own base domain as a host.** A wildcard cert's `altNames` already cover both the base domain and `*.base domain`, but the lookup tree stores the wildcard one level below its base domain, and a lookup for the bare base domain landed on that empty parent node and found nothing — even though the already-issued cert covers it. `buildLookUpObj()` now also stamps the parent node so this resolves correctly, without re-issuing or duplicating the cert.
+
+## [1.1.10] - 2026-07-17
+
+### Bumped
+- sso-manager-node -> [v1.1.9](https://github.com/theta42/sso-manager-node/releases/tag/v1.1.9)
+
+sso-manager-node:
+
+### Added
+- Every account's personal Unix group (its primary GID holder) can now have supplementary members managed from the account's profile page ("Members of `<uid>`'s group", admin-only) — e.g. to share write access to files owned by that group. Uses the standard `memberUid` attribute (RFC 2307 `posixGroup`).
+
+## [1.1.9] - 2026-07-17
+
+### Bumped
+- sso-manager-node -> [v1.1.8](https://github.com/theta42/sso-manager-node/releases/tag/v1.1.8)
+
+sso-manager-node:
+
+### Added
+- Group membership is now editable directly from a user's profile page ("My groups" -- add via a group-name picker, remove with a button per row), instead of only from each group's own card on the Groups page. Admin-only, using the existing per-group member add/remove endpoints.
+
+### Fixed
+- The Edit Profile form's Mobile Phone field had a stray `validate=":9"` making it effectively required (submission was blocked with "Please fix the form errors" if left blank) -- it was always meant to be optional, matching the "Add user" form. Removed.
+- A service account's profile always showed `Name: Service Account` -- every service account has the same literal filler given/last name (a schema-satisfying placeholder, not meant to be shown), making them indistinguishable by name. The Name line is now hidden for service accounts.
+- The Users page's Service Accounts tab, and a freshly-created service account's own profile, could appear empty/not-a-service-account for up to 5 minutes right after creation. Creating a user caches it via `User.get()` *before* the route handler marks it as a service account (group membership), so the cached copy had `isServiceAccount` stuck wrong until the cache TTL expired. Now cleared and re-fetched immediately after marking.
+- A user belonging to exactly one LDAP group had their `memberOf` attribute returned as a bare string instead of a one-element array (ldapts's normal behavior for single-valued attributes) -- client-side permission checks (`for(let group of user.memberOf)`) would then iterate the DN character-by-character instead of once, causing pages gated on that group (e.g. Groups) to incorrectly show "You do not have permission to be here." Normalized `memberOf` to always be an array, same fix already applied to `manager`.
+
 ## [1.1.8] - 2026-07-17
 
 ### Bumped
@@ -99,7 +322,16 @@ First tagged release. Establishes the `vX.Y.Z` tag convention going forward.
 - proxy -> [v1.1.0](https://github.com/theta42/proxy/releases/tag/v1.1.0)
 - sso-manager-node -> [v1.1.0](https://github.com/theta42/sso-manager-node/releases/tag/v1.1.0)
 
-[Unreleased]: https://github.com/theta42/theta-env/compare/v1.1.8...HEAD
+[Unreleased]: https://github.com/theta42/theta-env/compare/v1.1.20...HEAD
+[1.1.17]: https://github.com/theta42/theta-env/compare/v1.1.16...v1.1.17
+[1.1.16]: https://github.com/theta42/theta-env/compare/v1.1.15...v1.1.16
+[1.1.15]: https://github.com/theta42/theta-env/compare/v1.1.14...v1.1.15
+[1.1.14]: https://github.com/theta42/theta-env/compare/v1.1.13...v1.1.14
+[1.1.13]: https://github.com/theta42/theta-env/compare/v1.1.12...v1.1.13
+[1.1.12]: https://github.com/theta42/theta-env/compare/v1.1.11...v1.1.12
+[1.1.11]: https://github.com/theta42/theta-env/compare/v1.1.10...v1.1.11
+[1.1.10]: https://github.com/theta42/theta-env/compare/v1.1.9...v1.1.10
+[1.1.9]: https://github.com/theta42/theta-env/compare/v1.1.8...v1.1.9
 [1.1.8]: https://github.com/theta42/theta-env/compare/v1.1.7...v1.1.8
 [1.1.7]: https://github.com/theta42/theta-env/compare/v1.1.6...v1.1.7
 [1.1.6]: https://github.com/theta42/theta-env/compare/v1.1.5...v1.1.6

README.md

@@ -60,6 +60,10 @@ It is **both** an OIDC client of the SSO (for login) **and** a direct LDAP
 client (for user lookups). Legacy apps can still bind to LDAPS on the SSO
 directly.
 
+- **Self-service API tokens** in both apps' UIs, for scripting/CI without a browser session.
+- **Multi-Site Support (Geo-Location Scaling)** — built-in support for N-Way Multi-Master LDAP replication across physical locations.
+- **Multi-target load balancing** — built-in proxy support for round-robin load balancing across multiple application servers.
+
 ---
 
 ## Before you begin
@@ -120,6 +124,10 @@ Optional extra ports (only if you need them):
 - **636** (LDAPS) — only if a legacy app on another machine binds to LDAP
   directly over the network. The proxy itself reaches LDAP over the internal
   Docker network, so you do **not** need to expose 636 for the stack to work.
+  **Do not forward 636 to the public internet.** If you need LAN clients to bind
+  LDAP, set `CFG_LDAPS_HOST=ldap.internal.example.com` (or `sso-manager` for
+  same-host Docker clients) in `setup.env` and use an internal DNS record / cert
+  SAN. The default shows the public SSO hostname, which implies a public route.
 
 ### 4. Docker + Docker Compose
 
@@ -172,7 +180,8 @@ operator-owned and `setup.env` is ignored.
 ### Configuration — `./config/` (no `.env` files)
 
 All config and secrets live in a bind-mounted `./config/` directory (gitignored),
-read by each app's `@simpleworkjs/conf` from a symlinked `secrets.js`:
+read by each app's `@simpleworkjs/conf` via the `CONF_SECRETS` env var, which
+the entrypoint points at the mounted file:
 
 - **`./config/sso-secrets.js`** — SSO config: `ldap` (base, admin password,
   user/group bases), `oauth` (issuer, `jwtSecret`), `smtp`, `name`, plus

bootstrap/bootstrap.js

@@ -44,8 +44,15 @@ const fs = require('fs');
 const sso   = require('/config/sso-secrets.js');
 const proxy = require('/config/proxy-secrets.js');
 
-const BASE_DN        = (sso.stack && sso.stack.ldapBaseDn) || 'dc=example,dc=com';
-const ADMIN_PASS     = (sso.ldap && sso.ldap.bindPassword) || 'admin';
+function requireConf(value, name) {
+	if (value === undefined || value === null || value === '' || value === 'CHANGE-ME') {
+		throw new Error(`${name} is not configured in /config/sso-secrets.js`);
+	}
+	return value;
+}
+
+const BASE_DN        = requireConf((sso.stack && sso.stack.ldapBaseDn), 'stack.ldapBaseDn');
+const ADMIN_PASS     = requireConf((sso.ldap && sso.ldap.bindPassword), 'ldap.bindPassword');
 const BIND_DN        = `cn=admin,${BASE_DN}`;
 const LDAP_URL       = 'ldap://localhost:389';
 
@@ -53,9 +60,9 @@ const ADMIN_UID      = (sso.bootstrap && sso.bootstrap.adminUid) || 'admin';
 // The first admin *user's* password (cn=<uid>,ou=people,<base>). Distinct from
 // ADMIN_PASS above, which is the LDAP *root* (cn=admin,<base>) bind password —
 // two different accounts, two different secrets.
-const ADMIN_USER_PASS = (sso.bootstrap && sso.bootstrap.adminPass) || 'admin';
+const ADMIN_USER_PASS = requireConf((sso.bootstrap && sso.bootstrap.adminPass), 'bootstrap.adminPass');
 const ADMIN_EMAIL    = (sso.bootstrap && sso.bootstrap.adminEmail) || '';
-const SVC_PASS       = sso.serviceAccountPass || 'service';
+const SVC_PASS       = requireConf(sso.serviceAccountPass, 'serviceAccountPass');
 
 const SSO_HOST   = (sso.stack && sso.stack.ssoHost)   || 'sso.example.com';
 const PROXY_HOST = (sso.stack && sso.stack.proxyHost) || 'proxy.example.com';

config.example/proxy-secrets.js.example

@@ -5,8 +5,8 @@
 // bootstrap writes the OAuth client clientId/clientSecret back into it; this
 // file documents the shape for manual editing / reference.
 //
-// The proxy app reads this via @simpleworkjs/conf (docker-entrypoint.sh
-// symlinks it to /app/conf/secrets.js). Never commit ./config/.
+// The proxy app reads this via @simpleworkjs/conf (docker-entrypoint.sh sets
+// CONF_SECRETS to point at it). Never commit ./config/.
 
 module.exports = {
 	oidc: {

config.example/sso-secrets.js.example

@@ -4,8 +4,8 @@
 // `./setup.sh` generates ./config/sso-secrets.js for you on first run; this file
 // documents the shape for manual editing / reference.
 //
-// The SSO app reads this via @simpleworkjs/conf (docker-entrypoint.sh symlinks
-// it to /app/conf/secrets.js). The app ignores the extra stack/bootstrap/
+// The SSO app reads this via @simpleworkjs/conf (docker-entrypoint.sh sets
+// CONF_SECRETS to point at it). The app ignores the extra stack/bootstrap/
 // serviceAccountPass keys (read by the orchestrator). Back this up off-host —
 // it holds all SSO secrets. Never commit ./config/.
 
@@ -17,6 +17,9 @@ module.exports = {
 		bindPassword: 'CHANGE-ME',             // slapd root + app bind password
 		userBase: 'ou=people,dc=example,dc=com',
 		groupBase: 'ou=groups,dc=example,dc=com',
+		// ldapsHost: 'ldap.internal.example.com', // optional: internal-only hostname
+		// shown on /integrations for direct LDAPS binds. Empty -> derive from issuer.
+		// ldapsPort: 636,
 	},
 	smtp: {                                   // optional; leave host '' to skip
 		host: '', port: 587, secure: false,

docker-compose.yml

@@ -13,11 +13,12 @@
 # Config + secrets live in bind-mounted ./config/ (gitignored):
 #   ./config/sso-secrets.js   — SSO app + orchestrator config
 #   ./config/proxy-secrets.js — proxy OIDC/LDAP/auth config
-# Each app's entrypoint symlinks its file into /app/conf/secrets.js so
-# @simpleworkjs/conf reads it. No app_* env is passed (app_* env would override
-# secrets.js). The sso-manager mounts ./config read-write so the bootstrap can
-# write the generated OAuth client creds back into proxy-secrets.js; the proxy
-# mounts it read-only.
+# Each app's entrypoint points CONF_SECRETS at its file so @simpleworkjs/conf
+# (>= 1.2.0) reads it directly -- no app_* env is passed (app_* env would
+# override secrets.js), and no write access to /app/conf is needed. The
+# sso-manager mounts ./config read-write so the bootstrap can write the
+# generated OAuth client creds back into proxy-secrets.js; the proxy mounts
+# it read-only.
 #
 # Compose only interpolates the port defaults below — there is no .env file.
 # First-run wiring (LDAP service account, first admin, OAuth client) is
@@ -45,6 +46,8 @@ services:
       - "${SSO_BIND:-0.0.0.0}:${SSO_PORT:-3001}:3001"
       # LDAPS for EXTERNAL direct-LDAP clients (legacy apps). The proxy itself
       # reaches LDAPS over theta-net (sso-manager:636) without this host mapping.
+      # Prefer an internal-only hostname (set CFG_LDAPS_HOST in setup.env / ldapsHost
+      # in sso-secrets.js) and do NOT forward 636 to the public internet.
       - "${LDAPS_PORT:-636}:636"
       # Plain LDAP (389) is NOT mapped — direct-LDAP clients should use LDAPS.
     environment:
@@ -53,10 +56,12 @@ services:
       # reads that are not part of its conf tree.
       - NODE_ENV=production
       - NODE_PORT=3001
+      - LDAP_SERVER_ID=${LDAP_SERVER_ID:-}
+      - LDAP_REPLICATION_HOSTS=${LDAP_REPLICATION_HOSTS:-}
     volumes:
       # Operator-edited SSO secrets (sso-secrets.js). Read-WRITE so the bootstrap
       # can write the generated OAuth client creds into proxy-secrets.js. The
-      # entrypoint symlinks /config/sso-secrets.js -> /app/conf/secrets.js.
+      # entrypoint points CONF_SECRETS at /config/sso-secrets.js.
       - ./config:/config
       # Persist the LDAP database across container recreation.
       - ldap-data:/var/lib/ldap
@@ -108,7 +113,7 @@ services:
     volumes:
       # Operator-edited proxy secrets (proxy-secrets.js). READ-ONLY — the proxy
       # only reads it; the sso-manager bootstrap writes the OAuth creds. The
-      # entrypoint symlinks /config/proxy-secrets.js -> /app/conf/secrets.js.
+      # entrypoint points CONF_SECRETS at /config/proxy-secrets.js.
       - ./config:/config:ro
       # Persist Redis (AOF + RDB) so Host records, permissions, DNS creds, local
       # users, AND the auto-ssl Let's Encrypt certs survive container recreation.

docs/architecture.md

@@ -102,9 +102,9 @@ inputs from the bind-mounted `./config/sso-secrets.js` + `./config/proxy-secrets
    read-only). If `proxy-secrets.js` already holds a `clientId`+`clientSecret`
    matching an existing client, they are kept; if the client exists but the file
    has no usable secret, the secret is rotated and written back.
-6. **Build + start the proxy**, wait for `/health`. The proxy entrypoint symlinks
-   `./config/proxy-secrets.js` to `/app/conf/secrets.js`, so `@simpleworkjs/conf`
-   (≥1.1.0) reads the OAuth creds + LDAP bind creds from the file.
+6. **Build + start the proxy**, wait for `/health`. The proxy entrypoint points
+   `CONF_SECRETS` at `./config/proxy-secrets.js`, so `@simpleworkjs/conf`
+   (≥1.2.0) reads the OAuth creds + LDAP bind creds from the file.
 7. **Register `<SSO_HOST>` and `<PROXY_HOST>` as Host records in the proxy** —
    `setup.sh` runs a short script inside the proxy container that calls its
    Host model directly (`Host.create({host, ip, targetPort, ...})`), rather
@@ -123,19 +123,20 @@ inputs from the bind-mounted `./config/sso-secrets.js` + `./config/proxy-secrets
 ### How config reaches the apps (no `.env`)
 
 All config and secrets live in `./config/` (gitignored, bind-mounted). Each
-entrypoint symlinks its file to `/app/conf/secrets.js` early, before the app
-starts:
+entrypoint points the `CONF_SECRETS` env var (`@simpleworkjs/conf` >= 1.2.0)
+at its file early, before the app starts:
 
 ```
-./config/sso-secrets.js    ->  sso-manager:/app/conf/secrets.js   (./config RW)
-./config/proxy-secrets.js  ->  proxy:/app/conf/secrets.js         (./config RO)
+CONF_SECRETS=/config/sso-secrets.js    (sso-manager, ./config RW)
+CONF_SECRETS=/config/proxy-secrets.js  (proxy, ./config RO)
 ```
 
-`@simpleworkjs/conf` loads `conf/base.js → <env>.js → conf/secrets.js → app_*
-env`, where **env beats `secrets.js`**. So compose passes **no `app_*` env vars**
-(only `NODE_ENV`, `NODE_PORT`) — that makes `secrets.js` authoritative. The SSO
-entrypoint reads the few values it needs at startup (LDAP base DN, admin
-password, JWT secret, cert CN) from `secrets.js` via an in-container `node` call.
+`@simpleworkjs/conf` loads `conf/base.js → <env>.js → secrets file → app_*
+env`, where **env beats the secrets file**. So compose passes **no `app_*` env
+vars** (only `NODE_ENV`, `NODE_PORT`) — that makes the secrets file
+authoritative. The SSO entrypoint reads the few values it needs at startup
+(LDAP base DN, admin password, JWT secret, cert CN) from `sso-secrets.js` via
+an in-container `node` call.
 
 ### Why not `require` the SSO's internal models?
 

docs/index.md

@@ -44,6 +44,8 @@ snapshots state before every rebuild.
 - **LDAPS** for legacy apps that bind directly.
 - **Self-service API tokens** in both apps' UIs, for scripting/CI without a
   browser session.
+- **Multi-Site Support (Geo-Location Scaling)** — built-in support for N-Way Multi-Master LDAP replication across physical locations.
+- **Multi-target load balancing** — built-in proxy support for round-robin load balancing across multiple application servers.
 
 ## Get it
 

docs/standalone.md

@@ -25,18 +25,18 @@ mkdir -p config && cp secrets.js.example config/sso-secrets.js   # edit it
 docker compose up -d --build
 ```
 
-The entrypoint symlinks `config/sso-secrets.js` to `nodejs/conf/secrets.js` so
+The entrypoint points the `CONF_SECRETS` env var at `config/sso-secrets.js` so
 `@simpleworkjs/conf` reads it. Set `ldap.bindPassword`, `oauth.jwtSecret`, and
 the `stack`/`bootstrap` keys (the app ignores the ones it doesn't use). Pass
-**no `app_*` env** — env beats `secrets.js`, so `app_*` would silently override
-your file.
+**no `app_*` env** — env beats the secrets file, so `app_*` would silently
+override your file.
 
 - Web UI: `http://localhost:3001`
 - Health: `http://localhost:3001/health`
 - OIDC discovery: `http://localhost:3001/.well-known/openid-configuration`
 - LDAPS: `ldaps://<host>:636`
 
-Requires `@simpleworkjs/conf` >= 1.1.0. Full reference:
+Requires `@simpleworkjs/conf` >= 1.2.0. Full reference:
 [SSO Manager deployment docs](https://theta42.github.io/sso-manager-node/deployment.html).
 
 ### Bare metal
@@ -62,11 +62,11 @@ mkdir -p config && cp secrets.js.example config/proxy-secrets.js   # edit it
 docker compose up -d --build
 ```
 
-The entrypoint symlinks `config/proxy-secrets.js` to `nodejs/conf/secrets.js` so
-`@simpleworkjs/conf` reads it. Fill in `oidc` (your SSO's endpoints +
+The entrypoint points the `CONF_SECRETS` env var at `config/proxy-secrets.js`
+so `@simpleworkjs/conf` reads it. Fill in `oidc` (your SSO's endpoints +
 `clientId`/`clientSecret`/`redirectUri`), `ldap` (bind creds + search base), and
-`auth` (admin groups/users). Pass **no `app_*` env** — env beats `secrets.js`,
-so `app_*` would silently override your file.
+`auth` (admin groups/users). Pass **no `app_*` env** — env beats the secrets
+file, so `app_*` would silently override your file.
 
 - Proxy (public, auto-SSL): `https://<host>/`
 - Mgmt UI / API: `http://127.0.0.1:3000/`

pr_url.txt

@@ -0,0 +1 @@
+https://github.com/theta42/theta-env/pull/75

setup.env.example

@@ -36,6 +36,12 @@ CFG_DOMAIN=example.com
 #CFG_ADMIN_UID=admin            # initial SSO admin username
 #CFG_ADMIN_EMAIL=admin@proxy.example.com   # defaults to admin@<proxyHost>
 #CFG_LDAP_CERT_CN=              # LDAP TLS cert CN; empty -> defaults to the domain
+#
+# Hostname advertised on the SSO /integrations page for direct LDAPS binds.
+# Leave blank to derive it from the public SSO host (same as oauth.issuer).
+# Recommended: set an internal-only name like 'ldap.internal.example.com' or
+# 'sso-manager' so clients don't need a public 636 port forward. See docs.
+#CFG_LDAPS_HOST=
 
 # Optional SMTP (outbound email from the SSO app). Leave blank to disable:
 #CFG_SMTP_HOST=smtp.example.com
@@ -52,4 +58,16 @@ CFG_DOMAIN=example.com
 # password is the exception — see ./config/proxy-secrets.js's auth.localAdminPass
 # comment for how to actually change it after the account exists). Do NOT set
 # CFG_LDAP_ADMIN_PASS / CFG_JWT_SECRET / CFG_ADMIN_PASS / CFG_SVC_PASS /
-# CFG_PROXY_ADMIN_PASS here.
+# CFG_PROXY_ADMIN_PASS here.
+
+# ── Geo-Location Scaling (N-Way Multi-Master LDAP) ───────────────────────────
+# If deploying this stack across multiple physical sites to provide local HA
+# for directory services, you can enable N-Way Multi-Master OpenLDAP replication.
+# This requires assigning a unique ID to each site and listing the LDAPS URLs
+# of all OTHER sites in the cluster.
+#
+# Each site MUST have a unique LDAP_SERVER_ID (e.g. 1, 2, 3).
+# LDAP_REPLICATION_HOSTS is a space-separated list of the other sites' LDAP URLs.
+# Example for Site 1:
+#LDAP_SERVER_ID=1
+#LDAP_REPLICATION_HOSTS="ldaps://sso.site2.com:636 ldaps://sso.site3.com:636"

setup.sh

@@ -135,10 +135,12 @@ if [[ "${SKIP_SELF_UPDATE:-0}" != "1" && "${THETA_ENV_REEXECED:-0}" != "1" ]] \
 	&& git rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1
 then
 	BEFORE_REV="$(git rev-parse HEAD)"
+	BEFORE_VER="$(git describe --tags "$BEFORE_REV" 2>/dev/null || echo "${BEFORE_REV:0:12}")"
 	if git pull --ff-only -q; then
 		AFTER_REV="$(git rev-parse HEAD)"
 		if [[ "$BEFORE_REV" != "$AFTER_REV" ]]; then
-			info "Updated theta-env (${BEFORE_REV:0:12} -> ${AFTER_REV:0:12}) — restarting setup.sh with the new version..."
+			AFTER_VER="$(git describe --tags "$AFTER_REV" 2>/dev/null || echo "${AFTER_REV:0:12}")"
+			info "Updated theta-env (${BEFORE_VER} -> ${AFTER_VER}) — restarting setup.sh with the new version..."
 			THETA_ENV_REEXECED=1 exec "$0" "$@"
 		fi
 	else
@@ -165,26 +167,32 @@ if [[ "${SKIP_SUBMODULE_UPDATE:-0}" != "1" ]]; then
 	for sm in sso-manager-node proxy; do
 		[[ -d "$sm" ]] || continue
 		before_rev="$(git -C "$sm" rev-parse HEAD 2>/dev/null || true)"
+		# Prefer the exact tag the submodule is currently pinned to; fall back
+		# to a short commit hash if it's on an untagged commit (shouldn't
+		# normally happen -- this repo only ever pins tagged releases).
+		before_tag="$(git -C "$sm" describe --tags --exact-match "$before_rev" 2>/dev/null || echo "${before_rev:0:12}")"
 
 		if ! git -C "$sm" fetch --tags -q 2>&1; then
-			warn "  ${sm}: could not fetch tags (offline?) — staying on the current pin."
+			warn "  ${sm}: could not fetch tags (offline?) — staying on ${before_tag}."
 			continue
 		fi
 
 		latest_tag="$(git -C "$sm" tag --list 'v*' --sort=-v:refname | head -n1)"
 		if [[ -z "$latest_tag" ]]; then
-			warn "  ${sm}: no vX.Y.Z release tags found — staying on the current pin."
+			warn "  ${sm}: no vX.Y.Z release tags found — staying on ${before_tag}."
 			continue
 		fi
 
 		if ! git -C "$sm" checkout -q "$latest_tag" 2>&1; then
-			warn "  ${sm}: could not check out ${latest_tag} — staying on the current pin."
+			warn "  ${sm}: could not check out ${latest_tag} — staying on ${before_tag}."
 			continue
 		fi
 
 		after_rev="$(git -C "$sm" rev-parse HEAD 2>/dev/null || true)"
 		if [[ "$before_rev" != "$after_rev" ]]; then
-			info "  ${sm}: updated to ${latest_tag} (${before_rev:0:12} -> ${after_rev:0:12})"
+			info "  ${sm}: updated ${before_tag} -> ${latest_tag}"
+		else
+			info "  ${sm}: already up to date (${latest_tag})"
 		fi
 	done
 else
@@ -220,7 +228,7 @@ write_sso_secrets() {
 	cat > "$CONFIG_DIR/sso-secrets.js" <<SSOEOF
 'use strict';
 // Generated by setup.sh. Edit freely; re-run ./setup.sh to apply.
-// The SSO app reads this via @simpleworkjs/conf (symlinked to conf/secrets.js).
+// The SSO app reads this via @simpleworkjs/conf (CONF_SECRETS env var).
 // The app ignores the extra stack/bootstrap/serviceAccountPass keys (read by
 // the orchestrator). Back this file up off-host — it holds all SSO secrets.
 
@@ -232,6 +240,8 @@ module.exports = {
 		bindPassword: $(js_str "$CFG_LDAP_ADMIN_PASS"),
 		userBase: $(js_str "ou=people,${dn}"),
 		groupBase: $(js_str "ou=groups,${dn}"),
+		ldapsHost: $(js_str "${CFG_LDAPS_HOST:-}"),
+		ldapsPort: 636,
 	},
 	smtp: {
 		host: $(js_str "${CFG_SMTP_HOST:-}"),
@@ -271,8 +281,8 @@ write_proxy_secrets() {
 	local dn="$CFG_BASE_DN"
 	cat > "$CONFIG_DIR/proxy-secrets.js" <<PROXYEOF
 'use strict';
-// Generated by setup.sh. The proxy reads this via @simpleworkjs/conf (symlinked
-// to conf/secrets.js). clientId/clientSecret are filled in by the bootstrap
+// Generated by setup.sh. The proxy reads this via @simpleworkjs/conf (CONF_SECRETS
+// env var). clientId/clientSecret are filled in by the bootstrap
 // (run by ./setup.sh) — leave them as-is. ldap.bindPassword MUST equal
 // serviceAccountPass in sso-secrets.js (the proxy binds as that account).
 
@@ -347,6 +357,7 @@ ensure_config() {
 	CFG_ADMIN_UID="${CFG_ADMIN_UID:-}"
 	CFG_ADMIN_EMAIL="${CFG_ADMIN_EMAIL:-}"
 	CFG_LDAP_CERT_CN="${CFG_LDAP_CERT_CN:-}"
+	CFG_LDAPS_HOST="${CFG_LDAPS_HOST:-}"
 	CFG_CLIENT_ID="${CFG_CLIENT_ID:-}"
 	CFG_CLIENT_SECRET="${CFG_CLIENT_SECRET:-}"
 	CFG_LDAP_ADMIN_PASS="${CFG_LDAP_ADMIN_PASS:-}"
@@ -375,6 +386,8 @@ ensure_config() {
 		CFG_ADMIN_PASS="${BOOTSTRAP_ADMIN_PASS:-$CFG_ADMIN_PASS}"
 		CFG_SVC_PASS="${LDAP_SERVICE_PASS:-$CFG_SVC_PASS}"
 		CFG_LDAP_CERT_CN="${LDAP_CERT_CN:-$CFG_LDAP_CERT_CN}"
+		# .env has no legacy LDAPS_HOST key; this stays as set in setup.env/env.
+		CFG_LDAPS_HOST="${CFG_LDAPS_HOST:-}"
 		CFG_SMTP_HOST="${SMTP_HOST:-${CFG_SMTP_HOST:-}}"
 		CFG_SMTP_PORT="${SMTP_PORT:-${CFG_SMTP_PORT:-}}"
 		CFG_SMTP_USER="${SMTP_USER:-${CFG_SMTP_USER:-}}"
@@ -408,6 +421,7 @@ ensure_config() {
 	CFG_ADMIN_UID="${CFG_ADMIN_UID:-admin}"
 	CFG_ADMIN_EMAIL="${CFG_ADMIN_EMAIL:-admin@$CFG_PROXY_HOST}"
 	CFG_LDAP_CERT_CN="${CFG_LDAP_CERT_CN:-}"
+	CFG_LDAPS_HOST="${CFG_LDAPS_HOST:-}"
 	CFG_CLIENT_ID="${CFG_CLIENT_ID:-}"
 	CFG_CLIENT_SECRET="${CFG_CLIENT_SECRET:-}"
 	# Random secrets (generated fresh unless sourced/migrated above). These do
@@ -602,8 +616,6 @@ read_config_kv() {
 			LDAP_BASE_DN: (c.stack && c.stack.ldapBaseDn) || "",
 			ORG_NAME: c.name || "",
 			ADMIN_UID: (c.bootstrap && c.bootstrap.adminUid) || "",
-			ADMIN_PASS: (c.bootstrap && c.bootstrap.adminPass) || "",
-			PROXY_LOCAL_ADMIN_PASS: (p.auth && p.auth.localAdminPass) || "",
 		};
 		for (const k in o) console.log(k + "=" + (o[k] == null ? "" : o[k]));
 	' 2>/dev/null
@@ -613,8 +625,6 @@ cfgval() { echo "$CFG_OUT" | grep -m1 "^$1=" | cut -d= -f2-; }
 SSO_HOST="$(cfgval SSO_HOST)"
 PROXY_HOST="$(cfgval PROXY_HOST)"
 ADMIN_UID="$(cfgval ADMIN_UID)"
-ADMIN_PASS="$(cfgval ADMIN_PASS)"
-PROXY_LOCAL_ADMIN_PASS="$(cfgval PROXY_LOCAL_ADMIN_PASS)"
 
 info "Stack config:"
 info "  SSO host:      https://${SSO_HOST}"
@@ -709,13 +719,13 @@ echo "                      first-run fallback: http://127.0.0.1:${SSO_PORT:-300
 echo "  Proxy mgmt UI:      https://${PROXY_HOST}"
 echo "                      first-run fallback: http://127.0.0.1:${MGMT_PORT:-3000}"
 echo
-echo "  First admin login:"
+echo "  First admin login credentials are in ./config/sso-secrets.js:"
 echo "    user: ${ADMIN_UID}"
-echo "    pass: ${ADMIN_PASS}"
+echo "    pass: bootstrap.adminPass"
 echo
 echo "  Proxy local admin (anti-lockout fallback if the SSO is unreachable):"
 echo "    user: proxyadmin2"
-echo "    pass: ${PROXY_LOCAL_ADMIN_PASS}"
+echo "    pass: auth.localAdminPass in ./config/proxy-secrets.js"
 echo "    (only shown when the account is first created; edit ./config/proxy-secrets.js"
 echo "    or use the proxy UI to change it afterward)"
 echo