# 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

```ts
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:

```ts
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.