feat(api): CLI password reset with audit + session invalidation #704

Merged
chris merged 3 commits from feature/cli-password-reset-admin into main 2026-09-05 21:07:24 +02:00
Owner

What/Why

Operator-facing CLI password reset for the self-hosted recovery path. Spec 001 deferred email self-service reset; previously the only recovery was a manual, unaudited DB UPDATE. The old resetPasswordAsSuperAdmin service method had zero callers and no session invalidation; replaced by an audited CLI flow.

Design (per SE-approved plan)

  • Slim context: MemoriesApiApplication.main detects --reset-password before web boot and runs the flow in a slim Spring context (WebApplicationType.NONE) — only DataSource/JdbcTemplate/TransactionManager/Flyway/Jackson autoconfig + CoreBeans + LocalAuthService + AuditEventService. No Tomcat, no schedulers, no ApplicationRunners, no SecurityConfiguration. Component scan limited by TypeExcludeFilter to the two service classes.
  • Service: LocalAuthService.resetPasswordByEmail(email, newPassword) — normalizes email exactly like authenticate(), distinct unknown-email vs disabled-user errors, reuses existing hashPassword policy (>=12 chars), then in one @Transactional: password update + audit_events row (event_type=password_reset, actor_user_id=NULL, subject_type=user_account, details {actor:cli, target_email}) + DELETE FROM spring_session WHERE principal_name = :userId (FK cascade cleans attributes). resetPasswordAsSuperAdmin deleted.
  • Indexing: new SessionPrincipalIndexConfiguration registers a SingleIndexResolver on the JdbcIndexedSessionRepository mapping the memories.userId session attribute -> principal_name, so new sessions are indexed and invalidatable (V048 added the column, V049 widened it).
  • Password entry: stdin (--password-stdin) or MEMORIES_RESET_PASSWORD env fallback (warned in docs); argv path rejected (shell-history leak); nothing echoed.
  • Exit codes: 0 ok / 1 internal / 2 unknown email / 3 disabled user / 4 policy / 5 usage-IO.

Refs: specs/001-v1-baseline (ux-capability-matrix + open-questions updated), docs/adr/0056, docs/dev/cli-password-reset.md.

Test coverage

  • Testcontainers (postgis) persistence tests: happy path incl. old-pw/new-pw authenticate round trip, audit row shape assertions (event_type, NULL actor_user_id, subject_id, details->>'actor'='cli'), unknown-email exit semantics + no audit row, disabled-user exit 3 + no update/audit, short-password exit 4 semantics + no update, indexed session deletion + attribute FK cascade, legacy NULL-principal session survival, resetPasswordAsSuperAdmin removal guard.
  • Slim-context test: boots against real Postgres with only the intended beans (asserts no SecurityFilterChain, no ScheduledAnnotationBeanPostProcessor, no ApplicationRunner/CommandLineRunner, no servlet container), Flyway runs, end-to-end reset usable; CLI arg parsing + exit-code constants.
  • Contract tests: main() routes --reset-password before web boot; SecurityConfiguration diff pinned — same 6 permitAll matchers, no reset endpoint, /api/** still authenticated; no --password argv path; slim-context import list pinned.
  • Index-resolver unit tests: attr -> principal index mapping, empty for sessions without attr, customizer wiring.
  • ./gradlew :apps:api:test (full) and :apps:api:build green locally. SecurityConfiguration file itself untouched (verified via git diff).

Limitations

  • Legacy sessions with principal_name NULL (pre-deploy logins) are NOT invalidated by a reset; documented in docs + ADR-0056, related to ISSUE-015 (SE will add resolved entry at merge).
  • Env-var fallback exposes password in process environ; docs steer to stdin.

Notes

  • Pre-existing Playwright/web test failures unrelated to this change.
  • No merge — awaiting Test Engineer verdict + SE sign-off.
## What/Why Operator-facing CLI password reset for the self-hosted recovery path. Spec 001 deferred email self-service reset; previously the only recovery was a manual, unaudited DB UPDATE. The old `resetPasswordAsSuperAdmin` service method had zero callers and no session invalidation; replaced by an audited CLI flow. ## Design (per SE-approved plan) - **Slim context**: `MemoriesApiApplication.main` detects `--reset-password` before web boot and runs the flow in a slim Spring context (`WebApplicationType.NONE`) — only DataSource/JdbcTemplate/TransactionManager/Flyway/Jackson autoconfig + CoreBeans + LocalAuthService + AuditEventService. No Tomcat, no schedulers, no ApplicationRunners, no SecurityConfiguration. Component scan limited by TypeExcludeFilter to the two service classes. - **Service**: `LocalAuthService.resetPasswordByEmail(email, newPassword)` — normalizes email exactly like authenticate(), distinct unknown-email vs disabled-user errors, reuses existing hashPassword policy (>=12 chars), then in one @Transactional: password update + audit_events row (event_type=password_reset, actor_user_id=NULL, subject_type=user_account, details {actor:cli, target_email}) + `DELETE FROM spring_session WHERE principal_name = :userId` (FK cascade cleans attributes). `resetPasswordAsSuperAdmin` deleted. - **Indexing**: new `SessionPrincipalIndexConfiguration` registers a SingleIndexResolver on the JdbcIndexedSessionRepository mapping the `memories.userId` session attribute -> principal_name, so new sessions are indexed and invalidatable (V048 added the column, V049 widened it). - **Password entry**: stdin (`--password-stdin`) or `MEMORIES_RESET_PASSWORD` env fallback (warned in docs); argv path rejected (shell-history leak); nothing echoed. - **Exit codes**: 0 ok / 1 internal / 2 unknown email / 3 disabled user / 4 policy / 5 usage-IO. Refs: specs/001-v1-baseline (ux-capability-matrix + open-questions updated), docs/adr/0056, docs/dev/cli-password-reset.md. ## Test coverage - Testcontainers (postgis) persistence tests: happy path incl. old-pw/new-pw authenticate round trip, audit row shape assertions (event_type, NULL actor_user_id, subject_id, details->>'actor'='cli'), unknown-email exit semantics + no audit row, disabled-user exit 3 + no update/audit, short-password exit 4 semantics + no update, indexed session deletion + attribute FK cascade, legacy NULL-principal session survival, resetPasswordAsSuperAdmin removal guard. - Slim-context test: boots against real Postgres with only the intended beans (asserts no SecurityFilterChain, no ScheduledAnnotationBeanPostProcessor, no ApplicationRunner/CommandLineRunner, no servlet container), Flyway runs, end-to-end reset usable; CLI arg parsing + exit-code constants. - Contract tests: main() routes --reset-password before web boot; SecurityConfiguration diff pinned — same 6 permitAll matchers, no reset endpoint, /api/** still authenticated; no --password argv path; slim-context import list pinned. - Index-resolver unit tests: attr -> principal index mapping, empty for sessions without attr, customizer wiring. - `./gradlew :apps:api:test` (full) and `:apps:api:build` green locally. SecurityConfiguration file itself untouched (verified via git diff). ## Limitations - Legacy sessions with principal_name NULL (pre-deploy logins) are NOT invalidated by a reset; documented in docs + ADR-0056, related to ISSUE-015 (SE will add resolved entry at merge). - Env-var fallback exposes password in process environ; docs steer to stdin. ## Notes - Pre-existing Playwright/web test failures unrelated to this change. - No merge — awaiting Test Engineer verdict + SE sign-off.
- LocalAuthService.resetPasswordByEmail: normalize email like authenticate(),
  distinct unknown-email vs disabled-user errors, hash+update+audit+session
  invalidation in one @Transactional
- audit_events row: event_type=password_reset, actor_user_id=NULL,
  subject_type=user_account, details {actor:cli,target_email}
- DELETE FROM spring_session WHERE principal_name=:userId (FK cascade)
- remove dead resetPasswordAsSuperAdmin (zero callers)
- SessionPrincipalIndexConfiguration: IndexResolver maps memories.userId
  session attr -> principal_name so new sessions are indexed/invalidatable
- MemoriesApiApplication.main routes --reset-password to slim Spring context
  (WebApplicationType.NONE, no web/schedulers/runners/security)
- PasswordResetCli: stdin or MEMORIES_RESET_PASSWORD password (never argv),
  exit codes 0/1/2/3/4/5
- bump version to 1.21.26
- PasswordResetCliIntegrationTest (Testcontainers postgis): happy path with
  old-pw/new-pw authenticate round trip, audit row shape (event_type,
  NULL actor_user_id, subject, details->>'actor'='cli'), unknown-email and
  disabled-user exit semantics with no audit write, short-password policy
  rejection without update, indexed session deletion + FK cascade of
  attribute rows, legacy NULL-principal session survival,
  resetPasswordAsSuperAdmin removal guard
- PasswordResetCliSlimContextTest: slim context boots with only the
  intended beans (no SecurityFilterChain, no schedulers/runners, no servlet
  container), Flyway runs, end-to-end reset works; CLI arg parsing and
  exit-code constants
- CliPasswordResetContractTest: main() routes --reset-password before web
  boot; SecurityConfiguration gains no new permitAll (6 baseline matchers
  pinned); no --password argv path; slim-context import list pinned
- SessionPrincipalIndexConfigurationTest: resolver maps memories.userId ->
  principal_name index, empty for sessions without the attr, customizer
  wiring executes
- OperatorStatusServiceTest: adapt LocalAuthService constructor (new
  AuditEventService dependency)
docs: CLI password reset usage, ADR-0056, spec 001 scope updates
All checks were successful
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
ae1c76571a
- docs/dev/cli-password-reset.md: docker exec usage with --password-stdin,
  env fallback warning, exit codes, limitations (legacy NULL-principal
  sessions not invalidated, ISSUE-015 relation, env-var exposure note)
- ADR-0056: slim-context decision, operator trust model, principal_name
  indexing, legacy-session residual risk
- spec 001 ux-capability-matrix + open-questions: reflect delivered scope
  (CLI any-user-by-email, audited, session invalidation; deviation note from
  super-admin-only wording; email self-service reset still deferred)
chris merged commit ad2b400707 into main 2026-09-05 21:07:24 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!704
No description provided.