Initial Commit

packages/api-stack/api/api-plugin-auth/src/schemas/routes/reset-password.md

@@ -0,0 +1,77 @@
+# 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.