schemas/routes/reset-password

Purpose

Schemas for POST /auth/reset-password. The body accepts the single-use token previously emailed to the user plus the new password; the response is { success: true }. Better-Auth's downstream handler validates the token, hashes the new password, and clears the verification row.

Features

ResetPasswordBodySchema — { token: string (min 1), password: string (min 8) }.
ResetPasswordResponseSchema — { success: literal(true) }.
Inferred companions ResetPasswordBody and ResetPasswordResponse.

Usage: Basic

import { ResetPasswordBodySchema } from "@suaveplan/api-plugin-auth/schemas/routes";

const body = ResetPasswordBodySchema.parse(await c.req.json());

Usage: Advanced

Combine the schema with the standard error response so the OpenAPI document advertises the 400 (invalid token) and 422 (password too weak) cases consumers need to handle:

import { POST, successResponse } from "@suaveplan/api-openapi";
import {
    ResetPasswordBodySchema,
    ResetPasswordResponseSchema,
} from "@suaveplan/api-plugin-auth/schemas/routes";

const resetRoute = POST("/auth/reset-password")
    .tags("auth")
    .summary("Apply a password reset using a single-use token")
    .body(ResetPasswordBodySchema)
    .response(successResponse(ResetPasswordResponseSchema))
    .build();

API Reference

`ResetPasswordBodySchema`

Required: token: string (min 1), password: string (min 8). Inferred type ResetPasswordBody.

`ResetPasswordResponseSchema`

{ success: true }. Inferred type ResetPasswordResponse.

Implementation Notes

The 8-character minimum on password matches Better-Auth's default password policy. Stricter policies are configured downstream; the schema is a floor, not a ceiling.
The token is opaque from the schema's perspective — its structure (HMAC, JWT, or random base64) is a Better-Auth implementation detail and the schema only ensures the field is non-empty.
The response is a literal true so the typed return narrows correctly on the client side.
Better-Auth's downstream handler enforces single-use semantics — the schema does not need to track whether the token was previously redeemed. Replaying a consumed token surfaces a 400 from Better-Auth, which the host's error-handler middleware translates into the standard error envelope.
Hashing the new password happens inside Better-Auth using its configured hashing strategy (bcrypt, argon2, scrypt). The schema only checks length; the policy layer (zxcvbn, breached-password checks) is configured upstream and runs before this route is invoked.

2.6 KiB Raw Blame History