How OpenChronology was built

#121 · Read configuration whole, and reset the administrator's password from it

2026-10-13T01:23:21Z CE

• timeline-app
• pull request
• security

Closes #118. ## Cause (found on timeline.clark.arpa) That server runs the Ubuntu 24.04 package. Its `ADMIN_INITIAL_PASSWORD` is 27 characters and contains `#`. The two programs that read `/etc/openchronology/openchronology.env` disagreed about `#`: | Reader | Used by | `abc#def` | | --- | --- | --- | | systemd `EnvironmentFile` | the running server | `abc#def` | | Node `--env-file` | `openchronology-migrate`, which **creates the administrator** | `abc` | So the administrator was created with an 18-character password, everything before the `#`. Logging in with the configured password returned 401. I checked this on the server without printing the password: the full value is rejected, and the part before `#` signs in. ## Fix - **One parser** (`server/env-file.mjs`) reads the file the way systemd and Docker Compose do: - `#` or `;` starts a comment only at the beginning of a line; - quotes are optional (`\"` escapes in double quotes); - `export KEY=value` and backslash continuation lines are accepted; - it never overrides what the environment already sets. - **Every reader uses it:** - `openchronology-migrate` and `och-import-logs` pass the file as `OCH_CONFIG` instead of `--env-file`; - the package launcher replaces `process.loadEnvFile`; - `npm start` and `npm run dev` use it for `.env` (they had the same bug). - The templates now say any characters, `#` included, are fine. ## `openchronology-reset-admin-password` It sets the administrator's password back to `ADMIN_INITIAL_PASSWORD` from the configuration. Write a new one there first to choose a different password. - **Ways to run it:** - **Packages:** `sudo openchronology-reset-admin-password` (`.deb` and `.rpm`). - **Docker Compose:** `docker compose run --rm migrate node server/reset-admin-password.mjs`. - **Source:** `npm run reset-admin-password` (reads `.env`). - **Which account:** `ADMIN_USERNAME`, or the administrator the installation created first if that's empty. - **What it does:** - checks the password the same way creation does (15–1024 characters, not a placeholder); - sets it, signs out the account's sessions, and ends pending desktop sign-ins and reset links; - records `password-reset` in the admin audit; - keeps API keys and the authenticator, and says so (and notes when the account is disabled, not an admin, or has two-factor authentication on). - Documented in `docs/administration.md` ("Resetting the administrator's password"), README.Debian, README.RPM and the configuration templates. ## Tests - **Unit tests** (`test/env-file.test.mjs`) cover `#` inside values, comments, quotes and escapes, `export`, continuations, CRLF, and not overriding the environment. - **`test/admin-reset-postgres.mjs`** (added to CI) runs the tool the way the package does, with only `OCH_CONFIG`, and a password containing two `#`. It checks: - the whole password is set; - two sessions are signed out; - the reset is recorded in the audit; - unknown accounts and short passwords are refused. - **Package tests** (`server-deb`, `server-rpm`): with an admin password containing `#`, migration creates the admin with the whole password. With the hash cleared, `openchronology-reset-admin-password` restores it. Passes locally on Ubuntu 24.04. ## The running installation Until this is released and installed, sign in with the part of the password before the `#`. After upgrading, `sudo openchronology-reset-admin-password` sets it to the full value from the configuration. Alternatively, quote the value now (`ADMIN_INITIAL_PASSWORD="…"`), which both readers handle, and run the reset after upgrading.

Open #121 · Read configuration whole, and reset the administrator's password from it in the timeline