Story: Automate connections.db master-password unlock via CLI/env
Table of Contents
This page documents a story in Sprint 24. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
ores.qt's connection-bookmark store (connections.db, managed by
ores.connections) is protected by a master password that gates
decryption of stored server-login credentials. Today the only way to
supply it is MasterPasswordDialog (MainWindow::initializeConnectionManager(),
projects/ores.qt/application/src/MainWindow.cpp:948-1049) –
Unlock mode when encrypted passwords already exist and the current
in-memory masterPassword_ doesn't verify, Create mode on first run.
Every dev/test workflow that spins up one or more ores.qt instances
(compass client start, the --open-scenario QA workflow, multi-
client eventing scenarios) currently blocks on this dialog every
single launch, with no way to script around it.
Let the master password be supplied via a CLI arg and/or an
.env-sourced environment variable (mirroring the pattern the sibling
server-login auto-unlock capture
uses for the separate LoginDialog flow), so
initializeConnectionManager() can attempt verification with the
supplied value before falling back to the interactive dialog. As with
that sibling capture: if an auto-unlock attempt is made (the env
var/CLI arg is present) and fails – wrong password, no encrypted
passwords yet configured with that value, etc. – surface a clear,
loud message rather than silently falling through to the dialog or
proceeding unlocked. The manual dialog path must remain available for
whenever no env/CLI value is supplied.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 24 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-07-29 |
Acceptance
[X]A CLI arg and an equivalent.env-sourced environment variable can both supply the connections.db master password atores.qtstartup.[X]When supplied,initializeConnectionManager()attempts unlock with it before falling back toMasterPasswordDialog– no dialog shown if it succeeds.[X]A failed auto-unlock attempt (wrong password) shows a clear message box stating unlock was attempted automatically from the environment/CLI and failed, rather than silently falling back to the dialog or proceeding unlocked.[X]The manualMasterPasswordDialog(Unlock=/=Create=/=Change) path is unaffected when no env/CLI value is supplied.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Supply connections.db master password via CLI arg or .env | DONE | 2026-07-29 | 2026-07-29 | Add a CLI arg and .env-sourced environment variable for the connections.db master password; wire initializeConnectionManager() to attempt verification with it before falling back to MasterPasswordDialog, and show a clear failure message on a bad supplied value. |
Decisions
CLI/env password threaded through MainWindow's constructor, not a setter
Decided in the implementation task. Followed the
existing openScenarioPath precedent: passed as a new constructor
parameter rather than a post-construction setter, since
initializeConnectionManager() can run before any caller-supplied
setter would fire.
Failed auto-unlock falls through to the existing interactive dialog
Rather than aborting startup on a bad supplied password,
initializeConnectionManager() shows a distinct "Auto-Unlock Failed"
message box and then falls through into the same Unlock dialog
flow already used when no password was supplied at all – one code
path handles both cases past that point, and the manual fallback the
story's acceptance criteria require comes for free.
Out of scope
- Auto-unlocking the separate server-login dialog (
LoginDialog) – that's the sibling capture Auto-unlock login from an env/CLI password, a distinct credential/flow from the local connections.db master password this story covers. Create=/=Changemaster-password flows via CLI/env – this story only covers unlocking an already-configured master password non-interactively; first-time creation and password changes stay interactive.