ADR 0056: CLI Password Reset — Slim Spring Context, Trust Model, and Session Principal Indexing
Status: proposed Date: 2026-09-05
Context
v1 has no email-based password reset (deferred in spec 001); the only recovery path for a locked-out user was a manual DB UPDATE with no audit trail. The old super-admin reset service method (resetPasswordAsSuperAdmin) had zero callers and no session invalidation. Constraints: (1) the API jar is the only artifact deployed in the container — a separate CLI binary would double build/deploy surface; (2) resets must be auditable and must invalidate the target's live sessions; (3) shell history/CI logs must never see the password; (4) CLI startup must not start Tomcat, schedulers, ApplicationRunners, or the SecurityConfiguration.
Decision
- CLI mode lives inside the API jar: MemoriesApiApplication.main detects --reset-password before booting the web app and runs the flow in a slim Spring context (WebApplicationType.NONE) built from CliResetConfiguration — only DataSourceAutoConfiguration, JdbcTemplateAutoConfiguration, DataSourceTransactionManagerAutoConfiguration, FlywayAutoConfiguration, JacksonAutoConfiguration, CoreBeans (Clock, PasswordEncoder), plus LocalAuthService and AuditEventService. A TypeExcludeFilter-based component scan drops every other class under dev.memories.api so no servlet, scheduler, runner, or security chain is instantiated. 2. Password arrives via stdin (--password-stdin) or MEMORIES_RESET_PASSWORD env fallback; argument-path is rejected; nothing is echoed. Exit codes: 0 ok / 1 internal / 2 unknown email / 3 disabled user / 4 policy / 5 usage-IO. 3. resetPasswordByEmail normalizes the email like authenticate(), distinguishes unknown-email (exit 2) from disabled-user (exit 3), reuses hashPassword policy (>=12 chars), and in one transaction writes an audit_events row (event_type=password_reset, actor_user_id=NULL, subject_type=user_account, details {actor:cli,target_email}) and deletes spring_session rows by principal_name (FK cascade cleans attributes). 4. New SessionPrincipalIndexConfiguration registers a SingleIndexResolver on the JdbcIndexedSessionRepository mapping the memories.userId session attribute to the principal_name column so new sessions are indexed and invalidatable. 5. Trust model: the CLI is an operator tool gated by physical container access (same as docker exec psql); UI super-admin gating from the retired method is not reproduced — every reset is attributed via the audit row. 6. Legacy sessions with principal_name NULL are not invalidated (documented limitation, tracked with ISSUE-015).
Consequences
Positive: single artifact, auditable resets, live-session invalidation for all post-deploy sessions, password never on argv, no web/scheduler/runner side effects during recovery, slim context boots in ~1s and works while the web API is up. Negative: legacy NULL-principal sessions survive a reset (residual risk until backfill); env-var fallback exposes password in process environ (stdin preferred); slim context duplicates autoconfiguration imports — adding a new autoconfigured dependency to the reset flow requires editing CliResetConfiguration; the TypeExcludeFilter must be kept in sync when the reset flow needs new beans.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference