mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-22 13:48:21 +00:00
* feat(auth): add admin password reset CLI command and reset password web UI * fix(auth): invalidate previous reset tokens and use AsyncLocalStorage for link capture
61 lines
2.3 KiB
Plaintext
61 lines
2.3 KiB
Plaintext
---
|
|
title: Password Reset
|
|
description: How administrators generate secure password reset links for team members.
|
|
---
|
|
|
|
Because Shumai does not require an external email delivery service (SMTP) to be configured for standard self-hosted deployments, password resets are initiated securely by an administrator using the Shumai CLI.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
When a user forgets their password, an administrator can generate a one-time password reset link directly from the command line.
|
|
|
|
- **Link Expiration**: The generated password reset link is valid for **1 hour** (`3600 seconds`).
|
|
- **One-Time Use**: Once used, the token is permanently invalidated.
|
|
- **Session Revocation**: When a user resets their password, all existing active sessions for that account are automatically revoked across all devices.
|
|
- **Latest Link Validity**: Generating a new reset link for a user immediately supersedes any previously generated pending links.
|
|
|
|
---
|
|
|
|
## Generating a Password Reset Link
|
|
|
|
### Running on Local Host / Server
|
|
|
|
Run the `reset-password` subcommand from your Shumai installation directory:
|
|
|
|
```bash
|
|
shumai reset-password <user-email>
|
|
```
|
|
|
|
_(Alternatively, `bun apps/web/src/index.ts reset-password <user-email>`)_
|
|
|
|
**Example Output:**
|
|
|
|
```text
|
|
http://localhost:3000/reset-password?token=bb3xg4uO3cwN0FQv4cgUK6Hh
|
|
```
|
|
|
|
### Running inside Docker
|
|
|
|
If Shumai is running inside a Docker container, execute the command using `docker exec`:
|
|
|
|
```bash
|
|
docker exec -it <container-name-or-id> shumai reset-password <user-email>
|
|
```
|
|
|
|
> [!TIP]
|
|
> Both `shumai` and the common alias `shuami` (e.g. `shuami reset-password <user-email>`) are supported.
|
|
|
|
> [!NOTE]
|
|
> For remote servers or production deployments, ensure `BETTER_AUTH_URL` is set in your environment (e.g., `BETTER_AUTH_URL=https://shumai.example.com`) so the CLI generates the reset link with your public domain instead of `localhost`.
|
|
|
|
---
|
|
|
|
## Member Reset Experience
|
|
|
|
1. The administrator sends the generated URL to the team member via their preferred secure communication channel.
|
|
2. The user opens the link in their browser.
|
|
3. The user inputs their **New Password** and **Confirm Password** (minimum 3 characters).
|
|
4. Upon clicking **Reset Password**, the password is securely updated, all previous active sessions are invalidated, and the user is redirected to `/login` to sign in.
|