1 Dev Cli Password Reset
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

CLI Password Reset

Operator-facing recovery tool: reset any user's password directly against the database when email self-service reset is unavailable (email delivery is out of scope for v1 — see specs/001-v1-baseline/open-questions.md, "Auth And Session UX").

ADR: docs/adr/0056-cli-password-reset-slim-context.json

Usage

echo -n "$PW" | docker compose exec -T memories-api java -jar /app/memories-api.jar --reset-password [email protected] --password-stdin

Generate a strong password first (12 characters minimum, enforced by the same policy as login):

PW=$(openssl rand -base64 18)

Environment-variable fallback (prefer stdin; env vars leak into /proc/<pid>/environ and CI logs more easily than stdin pipes):

MEMORIES_RESET_PASSWORD="$PW" docker compose exec memories-api java -jar /app/memories-api.jar --reset-password [email protected]

The CLI runs inside the existing API container. It starts a slim Spring context (same image as the web API) with web/schedulers/security disabled — safe to run while the web API is up; only run one reset at a time.

Behavior

  1. Normalizes the email exactly like login (lowercase, trim).
  2. Looks the user up in user_accounts:
    • unknown email → exit code 2, no changes
    • disabled user → exit code 3, no changes
  3. Validates password policy (≥ 12 chars) → exit code 4 on violation, no changes.
  4. In one transaction:
    • updates user_accounts.password_hash
    • writes an audit_events row (event_type='password_reset', actor_user_id=NULL, subject_type='user_account', subject_id=<user>, details={"actor":"cli","target_email":<normalized email>})
    • deletes all indexed sessions of the user (DELETE FROM spring_session WHERE principal_name = :userId; attribute rows go through the FK cascade)

The password is read from stdin or the environment variable — never from a command-line argument (shell-history leak). Neither the password nor its hash is printed anywhere.

Exit codes

Code Meaning
0 Password reset
1 Internal error (CLI/context startup failure)
2 Unknown email
3 Disabled user
4 Password policy violation (< 12 chars)
5 Usage error or stdin/IO failure

Limitations

  • Legacy sessions are not invalidated. Sessions created before the principal-name indexing shipped have principal_name IS NULL and survive a password reset. New sessions (post-deploy logins) are invalidated. See ISSUE-015 (SessionAuthenticationFilter trusts the session attribute without DB revalidation) — an attacker holding a legacy session cookie retains access up to the session TTL even after a reset. Remediation path: backfill principal_name from spring_session_attributes, or hard-logout on disable.
  • Any operator with container/DB access can reset any user. The CLI is a server-side operator tool, not a UI capability: super-admin gating from the old (never-wired) resetPasswordAsSuperAdmin service method is replaced by physical container access as the trust boundary. Audit rows make every reset attributable.
  • No email self-service reset — still deferred (see spec 001 open questions).
  • The CLI accepts exactly --reset-password <email> plus --password-stdin; any other argument is a usage error (exit 5). The web server never starts in CLI mode.