feat(go-api): port forgot-password flow to Go (#15282) (#15290)

## Summary Implements **chunk 1** of #15282 — the four `/api/v1/auth/password/...` endpoints from the login-page Go port. **Chunk 2 (OAuth/OIDC) is deferred** to its own subtask, matching the issue author's own confidence-low recommendation ("multi-provider, stateful redirect flow with external dependencies; recommend its own subtask"). New endpoints, all registered under `apiNoAuth` (forgot-password users are unauthenticated by definition): | Method | Path | Status | |--------|------|--------| | `POST` | `/api/v1/auth/password/forgot/captcha` | new | | `POST` | `/api/v1/auth/password/forgot/otp` | new | | `POST` | `/api/v1/auth/password/forgot/otp/verify` | new | | `POST` | `/api/v1/auth/password/reset` | new | ## Wire compatibility with the Python backend The two backends share state through Redis, so the Go port had to use identical keys, encodings, and constants. Either backend can now validate a code the other minted. - **Redis keys**: `captcha:<email>`, `otp:<email>`, `otp_attempts:<email>`, `otp_last_sent:<email>`, `otp_lock:<email>`, `otp:verified:<email>` — same as `api/utils/web_utils.py`. - **Stored OTP value**: `"<hex_hash>:<hex_salt>"` — same as Python. - **Hash**: HMAC-SHA256 with a `crypto/rand` 16-byte salt — same as `hash_code()`. - **Constants**: `OTP_LENGTH=4`, `OTP_TTL=5min`, `ATTEMPT_LIMIT=5`, `ATTEMPT_LOCK_SECONDS=30min`, `RESEND_COOLDOWN_SECONDS=60s` — all match `api/utils/web_utils.py`. - **Email body**: matches `RESET_CODE_EMAIL_TMPL` byte-for-byte. ## Files ### New | File | Purpose | |---|---| | `internal/utility/otp.go` | OTP/captcha constants, Redis key builders (`CaptchaRedisKey`, `OTPRedisKeys`, `OTPVerifiedRedisKey`), `HashOTPCode`, `GenerateOTPCode` / `GenerateCaptchaCode` / `GenerateOTPSalt` via `crypto/rand`, and `EncodeOTPStorageValue` / `DecodeOTPStorageValue` matching Python's storage shape. | | `internal/utility/smtp.go` | Minimal stdlib `net/smtp` sender. `SendResetCodeEmail(to, otp, ttlMin)` builds an RFC 5322 plain-text message and dispatches via implicit TLS / STARTTLS / plain — same selectors as Python `aiosmtplib`. Returns `SMTPNotConfiguredError` if the config block is empty. | ### Modified | File | Change | |---|---| | `internal/server/config.go` | New `SMTPConfig` struct + `Config.SMTP` field. Field names mirror the `smtp:` keys in `common/settings.py` (`mail_server`, `mail_port`, `mail_use_ssl`, `mail_use_tls`, `mail_username`, `mail_password`, `mail_from_name`, `mail_from_address`, `mail_frontend_url`) so a single `conf/service_conf.yaml` powers both backends. | | `internal/service/user.go` | Four methods — `ForgotIssueCaptcha`, `ForgotSendOTP`, `ForgotVerifyOTP`, `ForgotResetPassword`. Reuses the existing `decryptPassword`, `HashPassword`, `userDAO.Update`, and `utility.GenerateToken` so the reset+auto-login path is identical to `LoginByEmail`. | | `internal/handler/user.go` | Four handlers in the same `c.JSON` shape as `LoginByEmail`. The reset handler rotates the access token and emits an `Authorization` header for auto-login (matches Python `construct_response(auth=user.get_id())`). | | `internal/router/router.go` | Routes registered under `apiNoAuth`, with an explanatory comment on why they sit outside the auth middleware. | ## Known divergence — captcha rendering The Python endpoint returns a rendered `image/JPEG` from the `python-captcha` library. The Go side has **no image-captcha dependency vendored** in `go.mod`, and hand-rolling a raster generator was out of scope for this PR. This commit returns JSON `{captcha: "<text>"}` instead. Implications: - **Backend gate is identical** — the OTP step still verifies the user-submitted captcha string against the Redis value, so the security model is unchanged. - **Frontend impact**: the password-reset page rendering needs a small tweak (text display instead of `<img>`) until a Go captcha library is wired in. - The handler comments call this out explicitly so the next PR knows what to swap. Possible follow-ups (any one closes the gap): 1. Add `github.com/mojocn/base64Captcha` or `github.com/dchest/captcha` to `go.mod` and replace the JSON response with an `image/JPEG`. 2. Hand-roll a 5x7 bitmap font + `image/png` writer using only the stdlib. 3. Render a server-side SVG (cheap, but trivially OCR-able — only useful as a UI shim). ## Test plan - [ ] **Captcha**: `POST /api/v1/auth/password/forgot/captcha?email=<existing>` returns `{code: 0, data: {captcha: "ABCD"}}`. Redis shows `captcha:<email>` with that value and ~60s TTL. Unknown email returns `code: CodeDataError`. - [ ] **OTP send**: `POST /api/v1/auth/password/forgot/otp` with the right captcha mints an OTP, stores `<hash>:<salt>` under `otp:<email>` for 5 min, sends an email, returns success. With a wrong captcha returns `CodeAuthenticationError`. Hitting it again within 60s returns "you still have to wait …" with `CodeNotEffective`. - [ ] **OTP verify**: correct OTP → `code: 0`, OTP keys cleared, `otp:verified:<email>` = `"1"`. Wrong OTP → `code: CodeAuthenticationError`, attempt counter bumped; after 5 wrong tries `otp_lock:<email>` is set and further attempts hit `CodeNotEffective`. - [ ] **Reset**: with the verified flag set, supply a new password (RSA-encrypted+base64, same as `LoginByEmail`). Returns `code: 0`, `Authorization` header set, verified flag deleted. Without the verified flag returns `CodeAuthenticationError`. - [ ] **Wire-compat smoke**: mint an OTP from the Python backend, verify it via the Go endpoint, and vice versa. Should both succeed. - [ ] **SMTP misconfigured**: drop `smtp.mail_server` from `conf/service_conf.yaml`. The OTP-send endpoint should now return "failed to send email" without panicking; check the log for the `SMTPNotConfiguredError` warning. - [ ] **End-to-end FE**: hit the password-reset flow from `web/src/pages/login-next/`. Confirm the text-captcha shim works after the FE tweak. - [ ] `go build ./...` and `go vet ./...` — I could not run these in the sandbox; please confirm a clean build before merging. - [ ] `uv run pytest` to confirm no Python regressions (shared Redis schema). ### Type of change - [x] New Feature (non-breaking change which adds functionality)
2026-06-29 15:31:05 +08:00 · 2026-06-10 06:27:56 -07:00
parent dfcf226ba3
commit bf59eb77cc
8 changed files with 1143 additions and 0 deletions
--- a/internal/common/smtp_config.go
+++ b/internal/common/smtp_config.go
@@ -0,0 +1,37 @@
+//
+//  Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+//
+
+package common
+
+// SMTPConfig is the SMTP block from conf/service_conf.yaml, used by the
+// forgot-password OTP flow and any other transactional email path.
+//
+// It lives in internal/common rather than internal/server so that
+// internal/utility (which renders/sends the email) can reference the
+// type without importing internal/server. internal/server already
+// imports internal/utility (via variable.go), so the reverse import
+// would close an import cycle.
+type SMTPConfig struct {
+	MailServer      string `mapstructure:"mail_server"`
+	MailPort        int    `mapstructure:"mail_port"`
+	MailUseSSL      bool   `mapstructure:"mail_use_ssl"`
+	MailUseTLS      bool   `mapstructure:"mail_use_tls"`
+	MailUsername    string `mapstructure:"mail_username"`
+	MailPassword    string `mapstructure:"mail_password"`
+	MailFromName    string `mapstructure:"mail_from_name"`
+	MailFromAddress string `mapstructure:"mail_from_address"`
+	MailFrontendURL string `mapstructure:"mail_frontend_url"`
+}
--- a/internal/handler/user.go
+++ b/internal/handler/user.go
@@ -628,3 +628,223 @@ func joinStrings(values []string) string {
 	}
 	return result
 }
+// ---- Forgot-password flow (fixes #15282) -----------------------------
+//
+// Mirrors api/apps/restful_apis/user_api.py /auth/password/... endpoints.
+//
+// Contract divergence from Python: the Python endpoint returns a
+// rendered image (Content-Type: image/JPEG) from the python-captcha
+// library and stores the captcha under captcha:<email>. This Go port
+// returns a server-issued captcha_id plus a PNG captcha image (as a
+// data URL the FE drops straight into <img src>), and stores
+// captcha:<captcha_id>. The plaintext text only ever appears as
+// raster pixels — the OTP step reuses the captcha_id to look the
+// expected text up server-side.
+//
+// The PNG is rendered using stdlib `image/png` + a hand-rolled 5x7
+// bitmap font in internal/utility/captcha_png.go, because no Go
+// captcha library is vendored in go.mod (no network during build).
+// PR #15290 review (Hz-186) explicitly asked for a raster after the
+// earlier SVG implementation: the SVG embedded the answer in <text>
+// nodes, so a scripted client could base64-decode the response and
+// grep the captcha directly. PNG closes that attack — the response
+// bytes never reference the original text.
+
+type forgotCaptchaRequest struct {
+	Email string `form:"email" json:"email"`
+}
+
+// ForgotCaptcha POST /api/v1/auth/password/forgot/captcha
+// @Summary Issue forgot-password captcha
+// @Description Generates a captcha for the email and stores it in Redis
+// for 60 seconds keyed by a server-issued captcha_id. Returns the id
+// and a PNG image (data URL) the FE renders inside <img src>. The
+// plaintext code never appears in the response — only as raster
+// pixels — so a scripted client can't regex it out (fixes the
+// SVG-text leak from the previous iteration, per PR #15290 review).
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param email query string false "user email (also accepted in JSON body)"
+// @Success 200 {object} map[string]interface{}
+// @Router /api/v1/auth/password/forgot/captcha [post]
+func (h *UserHandler) ForgotCaptcha(c *gin.Context) {
+	var req forgotCaptchaRequest
+	// Python reads from request.args (query string), accept both for parity.
+	if v := c.Query("email"); v != "" {
+		req.Email = v
+	} else {
+		_ = c.ShouldBindJSON(&req)
+	}
+
+	captchaID, captchaImage, errCode, err := h.userService.ForgotIssueCaptcha(req.Email)
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    errCode,
+			"message": err.Error(),
+			"data":    false,
+		})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"code":    common.CodeSuccess,
+		"message": "captcha issued",
+		"data": gin.H{
+			"captcha_id":    captchaID,
+			"captcha_image": captchaImage,
+		},
+	})
+}
+
+type forgotSendOTPRequest struct {
+	Email     string `json:"email"`
+	CaptchaID string `json:"captcha_id"`
+	Captcha   string `json:"captcha"`
+}
+
+// ForgotSendOTP POST /api/v1/auth/password/forgot/otp
+// @Summary Send forgot-password OTP
+// @Description Validates the captcha (looked up by captcha_id), then
+// mints a one-time code, stores a salted hash in Redis (5 min TTL,
+// attempt cap, resend cooldown), and emails the OTP to the user.
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param request body forgotSendOTPRequest true "email + captcha_id + captcha"
+// @Success 200 {object} map[string]interface{}
+// @Router /api/v1/auth/password/forgot/otp [post]
+func (h *UserHandler) ForgotSendOTP(c *gin.Context) {
+	var req forgotSendOTPRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    common.CodeArgumentError,
+			"message": err.Error(),
+			"data":    false,
+		})
+		return
+	}
+	errCode, err := h.userService.ForgotSendOTP(req.Email, req.CaptchaID, req.Captcha)
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    errCode,
+			"message": err.Error(),
+			"data":    false,
+		})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"code":    common.CodeSuccess,
+		"message": "verification passed, email sent",
+		"data":    true,
+	})
+}
+
+type forgotVerifyOTPRequest struct {
+	Email string `json:"email"`
+	OTP   string `json:"otp"`
+}
+
+// ForgotVerifyOTP POST /api/v1/auth/password/forgot/otp/verify
+// @Summary Verify forgot-password OTP
+// @Description Consumes the OTP if it matches, sets a short-lived
+// verified flag the reset endpoint will gate on. Wrong-OTP attempts
+// are counted and a 30-minute lockout kicks in at the limit.
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param request body forgotVerifyOTPRequest true "email + otp"
+// @Success 200 {object} map[string]interface{}
+// @Router /api/v1/auth/password/forgot/otp/verify [post]
+func (h *UserHandler) ForgotVerifyOTP(c *gin.Context) {
+	var req forgotVerifyOTPRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    common.CodeArgumentError,
+			"message": err.Error(),
+			"data":    false,
+		})
+		return
+	}
+	errCode, err := h.userService.ForgotVerifyOTP(req.Email, req.OTP)
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    errCode,
+			"message": err.Error(),
+			"data":    false,
+		})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"code":    common.CodeSuccess,
+		"message": "otp verified",
+		"data":    true,
+	})
+}
+
+// ForgotResetPassword POST /api/v1/auth/password/reset
+// @Summary Reset password after OTP verification
+// @Description Requires a successful prior verify call (verified flag
+// set in Redis). Updates the password hash and rotates the access
+// token so the response can auto-login the user.
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param request body service.ForgotResetPasswordRequest true "email + new password"
+// @Success 200 {object} map[string]interface{}
+// @Router /api/v1/auth/password/reset [post]
+func (h *UserHandler) ForgotResetPassword(c *gin.Context) {
+	var req service.ForgotResetPasswordRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    common.CodeArgumentError,
+			"message": err.Error(),
+			"data":    false,
+		})
+		return
+	}
+
+	user, code, err := h.userService.ForgotResetPassword(&req)
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    code,
+			"message": err.Error(),
+			"data":    false,
+		})
+		return
+	}
+
+	secretKey, err := server.GetSecretKey(cache.Get())
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    common.CodeServerError,
+			"message": fmt.Sprintf("Failed to get secret key: %s", err.Error()),
+			"data":    false,
+		})
+		return
+	}
+	authToken, err := utility.DumpAccessToken(*user.AccessToken, secretKey)
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    common.CodeServerError,
+			"message": "Failed to generate auth token",
+			"data":    false,
+		})
+		return
+	}
+	c.Header("Authorization", authToken)
+	c.Header("Access-Control-Expose-Headers", "Authorization")
+
+	// GetUserProfile includes the password hash and the live access_token,
+	// which must never appear in the reset response body (the token is
+	// already in the Authorization header). Mirror the Python contract
+	// `user.to_safe_dict(for_self=True)` by stripping those fields before
+	// writing. PR #15290 review.
+	profile := h.userService.GetUserProfile(user)
+	delete(profile, "password")
+	delete(profile, "access_token")
+	c.JSON(http.StatusOK, gin.H{
+		"code":    common.CodeSuccess,
+		"message": "Password reset successful. Logged in.",
+		"data":    profile,
+	})
+}
--- a/internal/router/router.go
+++ b/internal/router/router.go
@@ -156,6 +156,14 @@ func (r *Router) Setup(engine *gin.Engine) {
 		// Google redirects here after Gmail / Google Drive web OAuth completes.
 		apiNoAuth.GET("/connectors/gmail/oauth/web/callback", r.connectorHandler.GmailWebOAuthCallback)
 		apiNoAuth.GET("/connectors/google-drive/oauth/web/callback", r.connectorHandler.GoogleDriveWebOAuthCallback)
+		// Forgot-password flow (fixes #15282).
+		// Routes are intentionally registered before any auth middleware:
+		// a user who has forgotten their password is, by definition,
+		// unauthenticated.
+		apiNoAuth.POST("/auth/password/forgot/captcha", r.userHandler.ForgotCaptcha)
+		apiNoAuth.POST("/auth/password/forgot/otp", r.userHandler.ForgotSendOTP)
+		apiNoAuth.POST("/auth/password/forgot/otp/verify", r.userHandler.ForgotVerifyOTP)
+		apiNoAuth.POST("/auth/password/reset", r.userHandler.ForgotResetPassword)
 	}

 	// Protected routes
--- a/internal/server/config.go
+++ b/internal/server/config.go
@@ -26,6 +26,8 @@ import (
 	"strings"
 	"time"

+	"ragflow/internal/common"
+
 	"github.com/spf13/viper"
 	"go.uber.org/zap"
 )
@@ -44,6 +46,7 @@ type Config struct {
 	StorageEngine    StorageConfig          `mapstructure:"storage_engine"`
 	RegisterEnabled  int                    `mapstructure:"register_enabled"`
 	OAuth            map[string]OAuthConfig `mapstructure:"oauth"`
+	SMTP             common.SMTPConfig      `mapstructure:"smtp"`
 	Admin            AdminConfig            `mapstructure:"admin"`
 	UserDefaultLLM   UserDefaultLLMConfig   `mapstructure:"user_default_llm"`
 	DefaultSuperUser DefaultSuperUser       `mapstructure:"default_super_user"`
--- a/internal/service/user.go
+++ b/internal/service/user.go
@@ -1193,3 +1193,260 @@ func (s *UserService) GetUserByAPIToken(authorization string) (*entity.User, com
 	return user, common.CodeSuccess, nil

 }
+
+// ---- Forgot-password flow (mirrors api/apps/restful_apis/user_api.py
+// `/auth/password/...` endpoints, fixes #15282) -------------------------
+
+// ForgotIssueCaptcha mints a captcha for the given email and stores the
+// expected text in Redis under utility.CaptchaIDRedisKey, keyed by a
+// fresh server-side captcha_id, with a 60s TTL. Returns the captcha_id
+// and a renderable SVG image (data URL) the FE drops into <img src> so
+// the human can read the challenge and type the answer. The plaintext
+// code itself is never sent to the client outside the rendered image.
+//
+// Refuses unknown emails to avoid leaking the user list — matches Python.
+func (s *UserService) ForgotIssueCaptcha(email string) (captchaID, imageDataURL string, code common.ErrorCode, err error) {
+	if email == "" {
+		return "", "", common.CodeArgumentError, fmt.Errorf("email is required")
+	}
+	if _, err := s.userDAO.GetByEmail(email); err != nil {
+		return "", "", common.CodeDataError, fmt.Errorf("invalid email")
+	}
+
+	text, err := utility.GenerateCaptchaCode()
+	if err != nil {
+		return "", "", common.CodeServerError, err
+	}
+	captchaID = utility.GenerateToken()
+	if ok := cache.Get().Set(utility.CaptchaIDRedisKey(captchaID), text, 60*time.Second); !ok {
+		return "", "", common.CodeServerError, fmt.Errorf("failed to store captcha")
+	}
+	imageDataURL = utility.RenderCaptchaPNGDataURL(text)
+	return captchaID, imageDataURL, common.CodeSuccess, nil
+}
+
+// ForgotSendOTP verifies the captcha (looked up by the server-issued
+// captcha_id), then issues an OTP and emails it. Hash-and-salt is
+// stored in Redis under the keys returned by utility.OTPRedisKeys.
+// Resend cooldown and per-email lockout behaviour otherwise match the
+// Python implementation byte-for-byte.
+func (s *UserService) ForgotSendOTP(email, captchaID, captcha string) (common.ErrorCode, error) {
+	if email == "" || captchaID == "" || captcha == "" {
+		return common.CodeArgumentError, fmt.Errorf("email, captcha_id and captcha required")
+	}
+	if _, err := s.userDAO.GetByEmail(email); err != nil {
+		return common.CodeDataError, fmt.Errorf("invalid email")
+	}
+
+	rc := cache.Get()
+	captchaKey := utility.CaptchaIDRedisKey(captchaID)
+	stored, _ := rc.Get(captchaKey)
+	if stored == "" {
+		return common.CodeNotEffective, fmt.Errorf("invalid or expired captcha")
+	}
+	if !strings.EqualFold(strings.TrimSpace(stored), strings.TrimSpace(captcha)) {
+		return common.CodeAuthenticationError, fmt.Errorf("invalid or expired captcha")
+	}
+	// One-shot: consume the captcha so a leaked captcha_id cannot be
+	// reused for a stream of OTP requests.
+	rc.Delete(captchaKey)
+
+	codeKey, attemptsKey, lastSentKey, lockKey := utility.OTPRedisKeys(email)
+
+	// Lockout — a previous verify burst already locked this email; do not
+	// let a request for a new OTP wipe the lock (deliberate divergence
+	// from the Python implementation, which deletes the lock here and so
+	// allows a locked attacker to clear their own lockout by re-requesting).
+	if locked, _ := rc.Get(lockKey); locked != "" {
+		return common.CodeNotEffective, fmt.Errorf("too many attempts, try later")
+	}
+
+	// Resend cooldown — refuse if we already sent within the window.
+	if lastSent, _ := rc.Get(lastSentKey); lastSent != "" {
+		ts, parseErr := strconv.ParseInt(lastSent, 10, 64)
+		if parseErr == nil {
+			elapsed := time.Since(time.Unix(ts, 0))
+			remaining := utility.OTPResendCooldown - elapsed
+			if remaining > 0 {
+				return common.CodeNotEffective, fmt.Errorf("you still have to wait %d seconds", int(remaining.Seconds()))
+			}
+		}
+	}
+
+	otp, err := utility.GenerateOTPCode()
+	if err != nil {
+		return common.CodeServerError, err
+	}
+	salt, err := utility.GenerateOTPSalt()
+	if err != nil {
+		return common.CodeServerError, err
+	}
+	codeHash := utility.HashOTPCode(otp, salt)
+	now := strconv.FormatInt(time.Now().Unix(), 10)
+
+	// Snapshot the previous OTP-flow state so we can restore it if email
+	// delivery fails — otherwise the user is throttled by lastSentKey
+	// even though they never received the code.
+	prevCode, _ := rc.Get(codeKey)
+	prevAttempts, _ := rc.Get(attemptsKey)
+	prevLastSent, _ := rc.Get(lastSentKey)
+
+	if !rc.Set(codeKey, utility.EncodeOTPStorageValue(codeHash, salt), utility.OTPTTL) {
+		return common.CodeServerError, fmt.Errorf("failed to store otp")
+	}
+	rc.Set(attemptsKey, "0", utility.OTPTTL)
+	rc.Set(lastSentKey, now, utility.OTPTTL)
+	// Note: lockKey is intentionally not cleared here. If the user has
+	// been locked out by a previous verify burst, requesting a new OTP
+	// does not lift the lock — we already refused above.
+
+	ttlMin := int(utility.OTPTTL.Minutes())
+	cfg := server.GetConfig()
+	if err := utility.SendResetCodeEmail(cfg.SMTP, email, otp, ttlMin); err != nil {
+		// Roll back: restore prior code/attempts/last-sent or remove the
+		// keys we just wrote so the next attempt isn't blocked by the
+		// resend cooldown a failed send just installed.
+		if prevCode != "" {
+			rc.Set(codeKey, prevCode, utility.OTPTTL)
+		} else {
+			rc.Delete(codeKey)
+		}
+		if prevAttempts != "" {
+			rc.Set(attemptsKey, prevAttempts, utility.OTPTTL)
+		} else {
+			rc.Delete(attemptsKey)
+		}
+		if prevLastSent != "" {
+			rc.Set(lastSentKey, prevLastSent, utility.OTPTTL)
+		} else {
+			rc.Delete(lastSentKey)
+		}
+		return common.CodeServerError, fmt.Errorf("failed to send email")
+	}
+	return common.CodeSuccess, nil
+}
+
+// ForgotVerifyOTP checks an OTP submitted by the user. On success it
+// consumes the OTP/attempt counters and writes a short-lived "verified"
+// flag the reset endpoint will gate on.
+func (s *UserService) ForgotVerifyOTP(email, otp string) (common.ErrorCode, error) {
+	if email == "" || otp == "" {
+		return common.CodeArgumentError, fmt.Errorf("email and otp are required")
+	}
+	if _, err := s.userDAO.GetByEmail(email); err != nil {
+		return common.CodeDataError, fmt.Errorf("invalid email")
+	}
+
+	rc := cache.Get()
+	codeKey, attemptsKey, lastSentKey, lockKey := utility.OTPRedisKeys(email)
+
+	if locked, _ := rc.Get(lockKey); locked != "" {
+		return common.CodeNotEffective, fmt.Errorf("too many attempts, try later")
+	}
+
+	stored, _ := rc.Get(codeKey)
+	if stored == "" {
+		return common.CodeNotEffective, fmt.Errorf("expired otp")
+	}
+	storedHash, salt, err := utility.DecodeOTPStorageValue(stored)
+	if err != nil {
+		return common.CodeServerError, fmt.Errorf("otp storage corrupted")
+	}
+
+	if utility.HashOTPCode(strings.ToUpper(strings.TrimSpace(otp)), salt) != storedHash {
+		// bump attempts; lock on >= limit
+		attempts := 0
+		if cur, _ := rc.Get(attemptsKey); cur != "" {
+			if n, perr := strconv.Atoi(cur); perr == nil {
+				attempts = n
+			}
+		}
+		attempts++
+		rc.Set(attemptsKey, strconv.Itoa(attempts), utility.OTPTTL)
+		if attempts >= utility.OTPAttemptLimit {
+			rc.Set(lockKey, strconv.FormatInt(time.Now().Unix(), 10), utility.OTPAttemptLockDuration)
+		}
+		return common.CodeAuthenticationError, fmt.Errorf("expired otp")
+	}
+
+	// Success: clear OTP state, mark email verified.
+	rc.Delete(codeKey)
+	rc.Delete(attemptsKey)
+	rc.Delete(lastSentKey)
+	rc.Delete(lockKey)
+	if !rc.Set(utility.OTPVerifiedRedisKey(email), "1", utility.OTPTTL) {
+		return common.CodeServerError, fmt.Errorf("failed to set verification state")
+	}
+	return common.CodeSuccess, nil
+}
+
+// ForgotResetPasswordRequest carries the JSON body of /auth/password/reset.
+//
+// No `binding` tags on purpose: gin's validator fires inside
+// c.ShouldBindJSON and produces a verbose
+// `Key: 'ForgotResetPasswordRequest.Email' Error:Field validation ...`
+// message that diverges from the Python contract for this endpoint,
+// which returns the friendlier `"email and passwords are required"`
+// (api/apps/restful_apis/user_api.py:forget_reset_password). Letting
+// the binding succeed with zero values means the existing service
+// check below produces the matching message, and an entirely missing
+// JSON body now gets exactly Python's response.
+type ForgotResetPasswordRequest struct {
+	Email              string `json:"email"`
+	NewPassword        string `json:"new_password"`
+	ConfirmNewPassword string `json:"confirm_new_password"`
+}
+
+// ForgotResetPassword finalises the reset: only proceeds if the verified
+// flag is set, validates the two ciphertexts match after RSA decryption,
+// updates the password hash, and clears the verified flag. Returns the
+// user so the handler can auto-login (matching Python's
+// `construct_response(auth=user.get_id())`).
+func (s *UserService) ForgotResetPassword(req *ForgotResetPasswordRequest) (*entity.User, common.ErrorCode, error) {
+	if req.Email == "" || req.NewPassword == "" || req.ConfirmNewPassword == "" {
+		return nil, common.CodeArgumentError, fmt.Errorf("email and passwords are required")
+	}
+
+	rc := cache.Get()
+	verifiedKey := utility.OTPVerifiedRedisKey(req.Email)
+	if v, _ := rc.Get(verifiedKey); v != "1" {
+		return nil, common.CodeAuthenticationError, fmt.Errorf("email not verified")
+	}
+
+	plain, err := s.decryptPassword(req.NewPassword)
+	if err != nil {
+		return nil, common.CodeServerError, fmt.Errorf("fail to decrypt password")
+	}
+	confirm, err := s.decryptPassword(req.ConfirmNewPassword)
+	if err != nil {
+		return nil, common.CodeServerError, fmt.Errorf("fail to decrypt password")
+	}
+	if plain != confirm {
+		return nil, common.CodeArgumentError, fmt.Errorf("passwords do not match")
+	}
+
+	user, err := s.userDAO.GetByEmail(req.Email)
+	if err != nil {
+		return nil, common.CodeDataError, fmt.Errorf("invalid email")
+	}
+
+	hashed, err := s.HashPassword(plain)
+	if err != nil {
+		return nil, common.CodeServerError, fmt.Errorf("failed to hash new password: %w", err)
+	}
+	user.Password = &hashed
+
+	// Auto-login: rotate the access token like LoginByEmail does so the
+	// handler can immediately mint an Authorization header.
+	token := utility.GenerateToken()
+	user.AccessToken = &token
+	now := time.Now().Truncate(time.Second)
+	user.LastLoginTime = &now
+
+	if err := s.userDAO.Update(user); err != nil {
+		return nil, common.CodeServerError, fmt.Errorf("failed to reset password: %w", err)
+	}
+
+	rc.Delete(verifiedKey)
+	return user, common.CodeSuccess, nil
+}
--- a/internal/utility/captcha_png.go
+++ b/internal/utility/captcha_png.go
@@ -0,0 +1,259 @@
+//
+//  Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+//
+
+// Stdlib-only PNG captcha renderer.
+//
+// PR #15290 review (Hz-186): the previous SVG renderer embedded the
+// captcha text in <text> nodes, so a scripted client could base64-
+// decode the response and read the answer with a regex — defeating
+// the captcha entirely. The reviewer asked for either a raster
+// captcha or something that doesn't put the answer in machine-
+// readable response content. We have no image-captcha library
+// vendored in go.mod and no network access during build, so this
+// renders a real PNG using only stdlib `image`, `image/color`,
+// `image/draw`, and `image/png`, with a hand-rolled 5x7 bitmap font
+// for [A-Z0-9].
+//
+// The output bytes contain only the raster — the captcha text is
+// nowhere in the response stream — so the previous regex-the-answer
+// attack is closed. An OCR-capable attacker can still solve it, but
+// that's the standard limit of any non-trivial captcha; the bar set
+// by the reviewer was specifically "not machine-readable in the
+// response content."
+package utility
+
+import (
+	"bytes"
+	"encoding/base64"
+	"image"
+	"image/color"
+	"image/draw"
+	"image/png"
+	"math/rand"
+	"strings"
+	"time"
+)
+
+// captchaPNGScale is the per-glyph pixel multiplier. The font is 5x7,
+// so a scale of 4 produces 20x28 glyphs, which are ~16x16 px after
+// padding — comfortably readable for humans at typical browser zoom.
+const (
+	captchaPNGScale     = 4
+	captchaGlyphW       = 5
+	captchaGlyphH       = 7
+	captchaCharSpacing  = 4 // px between glyphs (after scaling)
+	captchaSidePadding  = 8
+	captchaTopPadding   = 6
+	captchaNoiseDots    = 60
+	captchaNoiseLines   = 4
+)
+
+// font5x7 maps a single character to its 7-row bitmap. Each row is a
+// 5-character string where '#' is a foreground pixel and any other
+// character is background. Covers the captcha alphabet ([A-Z0-9])
+// plus '?' as a fallback glyph for anything unexpected.
+//
+// These are hand-drawn — apologies for the eye-strain.
+var font5x7 = map[byte][7]string{
+	'A': {".###.", "#...#", "#...#", "#####", "#...#", "#...#", "#...#"},
+	'B': {"####.", "#...#", "#...#", "####.", "#...#", "#...#", "####."},
+	'C': {".####", "#....", "#....", "#....", "#....", "#....", ".####"},
+	'D': {"####.", "#...#", "#...#", "#...#", "#...#", "#...#", "####."},
+	'E': {"#####", "#....", "#....", "####.", "#....", "#....", "#####"},
+	'F': {"#####", "#....", "#....", "####.", "#....", "#....", "#...."},
+	'G': {".####", "#....", "#....", "#..##", "#...#", "#...#", ".####"},
+	'H': {"#...#", "#...#", "#...#", "#####", "#...#", "#...#", "#...#"},
+	'I': {"#####", "..#..", "..#..", "..#..", "..#..", "..#..", "#####"},
+	'J': {"#####", "...#.", "...#.", "...#.", "...#.", "#..#.", ".##.."},
+	'K': {"#...#", "#..#.", "#.#..", "##...", "#.#..", "#..#.", "#...#"},
+	'L': {"#....", "#....", "#....", "#....", "#....", "#....", "#####"},
+	'M': {"#...#", "##.##", "#.#.#", "#...#", "#...#", "#...#", "#...#"},
+	'N': {"#...#", "##..#", "#.#.#", "#.#.#", "#..##", "#...#", "#...#"},
+	'O': {".###.", "#...#", "#...#", "#...#", "#...#", "#...#", ".###."},
+	'P': {"####.", "#...#", "#...#", "####.", "#....", "#....", "#...."},
+	'Q': {".###.", "#...#", "#...#", "#...#", "#.#.#", "#..#.", ".##.#"},
+	'R': {"####.", "#...#", "#...#", "####.", "#.#..", "#..#.", "#...#"},
+	'S': {".####", "#....", "#....", ".###.", "....#", "....#", "####."},
+	'T': {"#####", "..#..", "..#..", "..#..", "..#..", "..#..", "..#.."},
+	'U': {"#...#", "#...#", "#...#", "#...#", "#...#", "#...#", ".###."},
+	'V': {"#...#", "#...#", "#...#", "#...#", "#...#", ".#.#.", "..#.."},
+	'W': {"#...#", "#...#", "#...#", "#...#", "#.#.#", "##.##", "#...#"},
+	'X': {"#...#", "#...#", ".#.#.", "..#..", ".#.#.", "#...#", "#...#"},
+	'Y': {"#...#", "#...#", ".#.#.", "..#..", "..#..", "..#..", "..#.."},
+	'Z': {"#####", "....#", "...#.", "..#..", ".#...", "#....", "#####"},
+	'0': {".###.", "#...#", "#..##", "#.#.#", "##..#", "#...#", ".###."},
+	'1': {"..#..", ".##..", "..#..", "..#..", "..#..", "..#..", ".###."},
+	'2': {".###.", "#...#", "....#", "...#.", "..#..", ".#...", "#####"},
+	'3': {"####.", "....#", "....#", ".###.", "....#", "....#", "####."},
+	'4': {"...#.", "..##.", ".#.#.", "#..#.", "#####", "...#.", "...#."},
+	'5': {"#####", "#....", "####.", "....#", "....#", "....#", "####."},
+	'6': {".###.", "#....", "#....", "####.", "#...#", "#...#", ".###."},
+	'7': {"#####", "....#", "....#", "...#.", "..#..", ".#...", "#...."},
+	'8': {".###.", "#...#", "#...#", ".###.", "#...#", "#...#", ".###."},
+	'9': {".###.", "#...#", "#...#", ".####", "....#", "....#", ".###."},
+	'?': {".###.", "#...#", "....#", "...#.", "..#..", ".....", "..#.."},
+}
+
+// RenderCaptchaPNG renders the captcha text as a PNG and returns the
+// raw bytes. The image has per-character jitter, random distractor
+// lines, and dot noise applied — enough to defeat the trivial-regex
+// attack from the previous SVG implementation. OCR-capable attackers
+// remain a possibility (standard captcha limit).
+//
+// The output never references the original text — the answer is
+// painted as raster pixels only.
+func RenderCaptchaPNG(text string) []byte {
+	if text == "" {
+		text = " "
+	}
+	upper := strings.ToUpper(text)
+	rng := rand.New(rand.NewSource(time.Now().UnixNano()))
+
+	glyphW := captchaGlyphW * captchaPNGScale
+	glyphH := captchaGlyphH * captchaPNGScale
+	width := captchaSidePadding*2 + len(upper)*glyphW + (len(upper)-1)*captchaCharSpacing
+	if width < 40 {
+		width = 40
+	}
+	height := captchaTopPadding*2 + glyphH + 8 // a bit of headroom for jitter
+
+	img := image.NewRGBA(image.Rect(0, 0, width, height))
+	// Background — light, slightly cool grey.
+	bg := color.RGBA{R: 0xf5, G: 0xf5, B: 0xf7, A: 0xff}
+	draw.Draw(img, img.Bounds(), &image.Uniform{bg}, image.Point{}, draw.Src)
+
+	// Distractor lines drawn under the glyphs.
+	for i := 0; i < captchaNoiseLines; i++ {
+		drawLine(
+			img,
+			rng.Intn(width), rng.Intn(height),
+			rng.Intn(width), rng.Intn(height),
+			pickStrokeRGBA(rng),
+		)
+	}
+
+	// Glyphs, each with x/y jitter and a per-glyph foreground colour.
+	x := captchaSidePadding
+	for i := 0; i < len(upper); i++ {
+		ch := upper[i]
+		bitmap, ok := font5x7[ch]
+		if !ok {
+			bitmap = font5x7['?']
+		}
+		dx := rng.Intn(5) - 2
+		dy := rng.Intn(7) - 3
+		fg := pickFillRGBA(rng)
+		drawGlyph(img, x+dx, captchaTopPadding+dy, bitmap, fg)
+		x += glyphW + captchaCharSpacing
+		_ = i // explicit to silence any future lint pass
+	}
+
+	// Foreground dot noise on top.
+	for i := 0; i < captchaNoiseDots; i++ {
+		img.Set(rng.Intn(width), rng.Intn(height), pickStrokeRGBA(rng))
+	}
+
+	var buf bytes.Buffer
+	_ = png.Encode(&buf, img)
+	return buf.Bytes()
+}
+
+// RenderCaptchaPNGDataURL base64-wraps the PNG so the handler can
+// return a single JSON string the FE drops into <img src="...">.
+func RenderCaptchaPNGDataURL(text string) string {
+	pngBytes := RenderCaptchaPNG(text)
+	return "data:image/png;base64," + base64.StdEncoding.EncodeToString(pngBytes)
+}
+
+// drawGlyph blits a 5x7 bitmap at (x, y) using captchaPNGScale x
+// captchaPNGScale pixel blocks. Each '#' in the bitmap becomes a
+// scale*scale block of `fg`.
+func drawGlyph(img *image.RGBA, x, y int, bitmap [7]string, fg color.RGBA) {
+	for row := 0; row < captchaGlyphH; row++ {
+		line := bitmap[row]
+		for col := 0; col < captchaGlyphW && col < len(line); col++ {
+			if line[col] != '#' {
+				continue
+			}
+			for dy := 0; dy < captchaPNGScale; dy++ {
+				for dx := 0; dx < captchaPNGScale; dx++ {
+					img.Set(x+col*captchaPNGScale+dx, y+row*captchaPNGScale+dy, fg)
+				}
+			}
+		}
+	}
+}
+
+// drawLine paints a 1px line using Bresenham's algorithm. Out-of-bounds
+// pixels are clipped by image.RGBA.Set silently, so no bounds check
+// is needed here.
+func drawLine(img *image.RGBA, x0, y0, x1, y1 int, c color.RGBA) {
+	dx := abs(x1 - x0)
+	dy := -abs(y1 - y0)
+	sx := 1
+	if x0 >= x1 {
+		sx = -1
+	}
+	sy := 1
+	if y0 >= y1 {
+		sy = -1
+	}
+	err := dx + dy
+	for {
+		img.Set(x0, y0, c)
+		if x0 == x1 && y0 == y1 {
+			return
+		}
+		e2 := 2 * err
+		if e2 >= dy {
+			err += dy
+			x0 += sx
+		}
+		if e2 <= dx {
+			err += dx
+			y0 += sy
+		}
+	}
+}
+
+func abs(n int) int {
+	if n < 0 {
+		return -n
+	}
+	return n
+}
+
+func pickFillRGBA(rng *rand.Rand) color.RGBA {
+	palette := []color.RGBA{
+		{R: 0x1f, G: 0x29, B: 0x37, A: 0xff},
+		{R: 0x1d, G: 0x4e, B: 0xd8, A: 0xff},
+		{R: 0x7c, G: 0x2d, B: 0x12, A: 0xff},
+		{R: 0x06, G: 0x5f, B: 0x46, A: 0xff},
+		{R: 0x7e, G: 0x22, B: 0xce, A: 0xff},
+	}
+	return palette[rng.Intn(len(palette))]
+}
+
+func pickStrokeRGBA(rng *rand.Rand) color.RGBA {
+	palette := []color.RGBA{
+		{R: 0x9c, G: 0xa3, B: 0xaf, A: 0xff},
+		{R: 0x6b, G: 0x72, B: 0x80, A: 0xff},
+		{R: 0xa1, G: 0x62, B: 0x07, A: 0xff},
+		{R: 0x0e, G: 0x74, B: 0x90, A: 0xff},
+		{R: 0xbe, G: 0x18, B: 0x5d, A: 0xff},
+	}
+	return palette[rng.Intn(len(palette))]
+}
--- a/internal/utility/otp.go
+++ b/internal/utility/otp.go
@@ -0,0 +1,157 @@
+//
+//  Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+//
+
+// OTP / captcha helpers for the forgot-password flow.
+// Constants and key shapes mirror api/utils/web_utils.py so the Python
+// and Go backends share the same Redis namespace and contract.
+package utility
+
+import (
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"math/big"
+	"strings"
+	"time"
+)
+
+// Forgot-password constants — match api/utils/web_utils.py.
+const (
+	OTPLength               = 4
+	OTPTTL                  = 5 * time.Minute
+	OTPAttemptLimit         = 5
+	OTPAttemptLockDuration  = 30 * time.Minute
+	OTPResendCooldown       = 60 * time.Second
+)
+
+// otpUpperAlphabet is the OTP alphabet (uppercase letters, same as
+// Python ``string.ascii_uppercase``).
+const otpUpperAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+
+// captchaAlphabet is the captcha alphabet (uppercase letters + digits,
+// same as Python ``string.ascii_uppercase + string.digits``).
+const captchaAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+// normalizeEmail lowercases and trims an email address for keying. Mirrors
+// the leading ``email = (email or "").strip().lower()`` in Python's
+// otp_keys helper.
+func normalizeEmail(email string) string {
+	return strings.ToLower(strings.TrimSpace(email))
+}
+
+// CaptchaIDRedisKey returns the Redis key that holds the active captcha
+// for a server-issued captcha_id. The handler returns the id to the
+// client and never the code itself, so an attacker cannot read the
+// expected answer from the response. Diverges from Python's
+// email-keyed ``captcha_key`` on purpose — captchas are 60s-lived
+// and never cross between Go and Python in practice, so there is no
+// shared-state requirement.
+func CaptchaIDRedisKey(captchaID string) string {
+	return "captcha:" + captchaID
+}
+
+// OTPRedisKeys returns the four Redis keys used by the forgot-password
+// flow, in the same order as Python's ``otp_keys`` helper:
+//
+//	code, attempts, last_sent, lock
+func OTPRedisKeys(email string) (codeKey, attemptsKey, lastSentKey, lockKey string) {
+	email = normalizeEmail(email)
+	return "otp:" + email,
+		"otp_attempts:" + email,
+		"otp_last_sent:" + email,
+		"otp_lock:" + email
+}
+
+// OTPVerifiedRedisKey returns the Redis key that records a successful OTP
+// verification, used as the gate for the password-reset step (matches
+// Python ``_verified_key``).
+func OTPVerifiedRedisKey(email string) string {
+	return "otp:verified:" + normalizeEmail(email)
+}
+
+// HashOTPCode computes the HMAC-SHA256 of an OTP using the given salt and
+// returns its hex digest, matching Python's ``hash_code`` helper.
+func HashOTPCode(code string, salt []byte) string {
+	mac := hmac.New(sha256.New, salt)
+	mac.Write([]byte(code))
+	return hex.EncodeToString(mac.Sum(nil))
+}
+
+// GenerateOTPSalt returns a cryptographically random 16-byte salt for
+// hashing an OTP — same width as Python ``os.urandom(16)``.
+func GenerateOTPSalt() ([]byte, error) {
+	salt := make([]byte, 16)
+	if _, err := rand.Read(salt); err != nil {
+		return nil, fmt.Errorf("failed to generate otp salt: %w", err)
+	}
+	return salt, nil
+}
+
+// GenerateOTPCode generates an OTP of length ``OTPLength`` drawn uniformly
+// from ``otpUpperAlphabet`` using crypto/rand (matches Python
+// ``secrets.choice``).
+func GenerateOTPCode() (string, error) {
+	return randomStringFromAlphabet(otpUpperAlphabet, OTPLength)
+}
+
+// GenerateCaptchaCode generates a captcha of length ``OTPLength`` drawn
+// uniformly from ``captchaAlphabet`` using crypto/rand. The shared length
+// is intentional — Python uses ``OTP_LENGTH`` for both.
+func GenerateCaptchaCode() (string, error) {
+	return randomStringFromAlphabet(captchaAlphabet, OTPLength)
+}
+
+// EncodeOTPStorageValue serializes the (hash, salt) pair the way Python
+// stores it in Redis: ``"<hex_hash>:<hex_salt>"``. Returning the salt's
+// hex form (not raw bytes) keeps the value safe to store as a Redis
+// string and matches the Python encoding so either backend can verify a
+// code minted by the other.
+func EncodeOTPStorageValue(codeHash string, salt []byte) string {
+	return codeHash + ":" + hex.EncodeToString(salt)
+}
+
+// DecodeOTPStorageValue reverses ``EncodeOTPStorageValue``. Returns the
+// stored hash, decoded salt bytes, and a non-nil error if the value is
+// malformed.
+func DecodeOTPStorageValue(stored string) (codeHash string, salt []byte, err error) {
+	parts := strings.SplitN(stored, ":", 2)
+	if len(parts) != 2 {
+		return "", nil, fmt.Errorf("otp storage value missing salt separator")
+	}
+	salt, err = hex.DecodeString(parts[1])
+	if err != nil {
+		return "", nil, fmt.Errorf("otp storage salt is not valid hex: %w", err)
+	}
+	return parts[0], salt, nil
+}
+
+func randomStringFromAlphabet(alphabet string, length int) (string, error) {
+	if length <= 0 {
+		return "", fmt.Errorf("random string length must be positive")
+	}
+	out := make([]byte, length)
+	max := big.NewInt(int64(len(alphabet)))
+	for i := 0; i < length; i++ {
+		n, err := rand.Int(rand.Reader, max)
+		if err != nil {
+			return "", fmt.Errorf("failed to read random byte: %w", err)
+		}
+		out[i] = alphabet[n.Int64()]
+	}
+	return string(out), nil
+}
--- a/internal/utility/smtp.go
+++ b/internal/utility/smtp.go
@@ -0,0 +1,202 @@
+//
+//  Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+//
+
+// Minimal SMTP sender for transactional email (forgot-password OTP, etc).
+// Mirrors api/utils/web_utils.py:send_email_html on the Python side and
+// uses the same conf/service_conf.yaml `smtp` block so a single config
+// powers both backends.
+//
+// The config is passed in as a parameter rather than read via
+// server.GetConfig() — internal/server already imports internal/utility
+// (via variable.go), so importing server from here would close an
+// import cycle. The SMTPConfig type lives in internal/common for the
+// same reason.
+package utility
+
+import (
+	"crypto/tls"
+	"fmt"
+	"net"
+	"net/smtp"
+	"strings"
+
+	"ragflow/internal/common"
+
+	"go.uber.org/zap"
+)
+
+// SMTPNotConfiguredError is returned when an SMTP send is attempted but the
+// active config has no mail server. Lets the caller distinguish a config
+// problem from a transient delivery failure.
+type SMTPNotConfiguredError struct{}
+
+func (SMTPNotConfiguredError) Error() string {
+	return "smtp is not configured"
+}
+
+// SMTPInsecureAuthError is returned when authentication is requested over
+// an unencrypted SMTP connection (neither MailUseSSL nor MailUseTLS set).
+// Sending credentials in the clear is refused on principle.
+type SMTPInsecureAuthError struct{}
+
+func (SMTPInsecureAuthError) Error() string {
+	return "smtp authentication refused over plaintext connection (set mail_use_ssl or mail_use_tls)"
+}
+
+// SendResetCodeEmail delivers the password-reset OTP email. It is the Go
+// analogue of:
+//
+//	await send_email_html(
+//	    subject="Your Password Reset Code",
+//	    to_email=email,
+//	    template_key="reset_code",
+//	    code=otp,
+//	    ttl_min=ttl_min,
+//	)
+//
+// — same subject, same plaintext body shape (see RESET_CODE_EMAIL_TMPL in
+// api/utils/email_templates.py).
+func SendResetCodeEmail(cfg common.SMTPConfig, toEmail, otp string, ttlMinutes int) error {
+	if cfg.MailServer == "" || cfg.MailPort == 0 {
+		return SMTPNotConfiguredError{}
+	}
+
+	subject := "Your Password Reset Code"
+	body := fmt.Sprintf(
+		"Hello,\nYour password reset code is: %s\nThis code will expire in %d minutes.\n",
+		otp, ttlMinutes,
+	)
+
+	fromAddr := cfg.MailFromAddress
+	if fromAddr == "" {
+		fromAddr = cfg.MailUsername
+	}
+	fromName := cfg.MailFromName
+	if fromName == "" {
+		fromName = "RAGFlow"
+	}
+	fromHeader := fmt.Sprintf("%s <%s>", fromName, fromAddr)
+
+	msg := buildPlainEmail(fromHeader, toEmail, subject, body)
+	if err := sendMail(cfg, fromAddr, toEmail, msg); err != nil {
+		common.Warn("smtp send failed",
+			zap.String("to", toEmail),
+			zap.String("server", cfg.MailServer),
+			zap.Int("port", cfg.MailPort),
+			zap.Error(err),
+		)
+		return err
+	}
+	return nil
+}
+
+// buildPlainEmail composes an RFC 5322 plain-text message. CRLF line
+// endings are required by the SMTP DATA spec.
+func buildPlainEmail(from, to, subject, body string) []byte {
+	headers := []string{
+		"From: " + from,
+		"To: " + to,
+		"Subject: " + subject,
+		"MIME-Version: 1.0",
+		"Content-Type: text/plain; charset=utf-8",
+		"Content-Transfer-Encoding: 8bit",
+	}
+	return []byte(strings.Join(headers, "\r\n") + "\r\n\r\n" + body)
+}
+
+// sendMail dispatches the message over implicit TLS, STARTTLS, or plain
+// — matching how the Python aiosmtplib client is configured by the
+// `mail_use_ssl` / `mail_use_tls` flags.
+//
+// Authentication is only attempted over an encrypted session. If the
+// caller asks for auth (MailUsername set) on a plaintext connection,
+// SMTPInsecureAuthError is returned before any credential is written.
+func sendMail(cfg common.SMTPConfig, from, to string, msg []byte) error {
+	if cfg.MailUsername != "" && !cfg.MailUseSSL && !cfg.MailUseTLS {
+		return SMTPInsecureAuthError{}
+	}
+
+	addr := net.JoinHostPort(cfg.MailServer, fmt.Sprintf("%d", cfg.MailPort))
+	auth := smtp.PlainAuth("", cfg.MailUsername, cfg.MailPassword, cfg.MailServer)
+
+	if cfg.MailUseSSL {
+		// Implicit TLS (typical port 465). Dial TLS first, then SMTP.
+		tlsCfg := &tls.Config{
+			ServerName: cfg.MailServer,
+			MinVersion: tls.VersionTLS12,
+		}
+		conn, err := tls.Dial("tcp", addr, tlsCfg)
+		if err != nil {
+			return fmt.Errorf("smtp tls dial: %w", err)
+		}
+		client, err := smtp.NewClient(conn, cfg.MailServer)
+		if err != nil {
+			conn.Close()
+			return fmt.Errorf("smtp client init: %w", err)
+		}
+		defer client.Quit()
+		if cfg.MailUsername != "" {
+			if err := client.Auth(auth); err != nil {
+				return fmt.Errorf("smtp auth: %w", err)
+			}
+		}
+		return deliverMail(client, from, to, msg)
+	}
+
+	// STARTTLS (typical port 587) or plain (auth refused above).
+	client, err := smtp.Dial(addr)
+	if err != nil {
+		return fmt.Errorf("smtp dial: %w", err)
+	}
+	defer client.Quit()
+	if cfg.MailUseTLS {
+		tlsCfg := &tls.Config{
+			ServerName: cfg.MailServer,
+			MinVersion: tls.VersionTLS12,
+		}
+		if err := client.StartTLS(tlsCfg); err != nil {
+			return fmt.Errorf("smtp starttls: %w", err)
+		}
+		if cfg.MailUsername != "" {
+			if err := client.Auth(auth); err != nil {
+				return fmt.Errorf("smtp auth: %w", err)
+			}
+		}
+	}
+	// Plaintext: no auth performed (refused at the top of the function).
+	return deliverMail(client, from, to, msg)
+}
+
+func deliverMail(client *smtp.Client, from, to string, msg []byte) error {
+	if err := client.Mail(from); err != nil {
+		return fmt.Errorf("smtp mail-from: %w", err)
+	}
+	if err := client.Rcpt(to); err != nil {
+		return fmt.Errorf("smtp rcpt-to: %w", err)
+	}
+	w, err := client.Data()
+	if err != nil {
+		return fmt.Errorf("smtp data: %w", err)
+	}
+	if _, err := w.Write(msg); err != nil {
+		w.Close()
+		return fmt.Errorf("smtp write: %w", err)
+	}
+	if err := w.Close(); err != nil {
+		return fmt.Errorf("smtp close: %w", err)
+	}
+	return nil
+}