Password reset

User flow

1. Login page → “Forgot password?”
2. Enter email. Submit.
3. z4j always responds “check your email” regardless of whether the email exists (prevents enumeration).
4. If the email exists, a one-shot reset link is sent. Token expires in 60 minutes.
5. User clicks → new-password form → new password enforced by password policy.
6. On save, all existing sessions for that user are invalidated.

Requires SMTP

Password reset requires SMTP. Without it, users cannot self-serve; admins must reset via CLI (see below).

Rate limits

• Max 3 reset requests per email per hour.
• Max 10 reset requests per IP per hour.

Admin-reset (CLI)

For lost admin accounts or SMTP outages:

z4j-brain password-reset --email owner@example.com

The CLI prints a one-shot reset URL (bypasses SMTP). Use it to set a new password.

Requires direct brain-container access.

Last-resort recovery

If you’ve lost all admins and CLI access:

1. Connect to Postgres directly.
2. Generate an argon2id hash with an external tool (e.g., argon2 --encoded).
3. UPDATE users SET password_hash = '$argon2id$...' WHERE email = 'owner@example.com'.
4. Log in with the new password.

This is a break-glass procedure - log the event externally and treat it as a compromise drill.

Audit

• Reset requested → audit entry with just the email + IP (not the token).
• Reset completed → audit entry with user_id.