@lenne.tech/nuxt-extensions 1.15.1 → 1.17.0

package/CLAUDE.md

@@ -25,8 +25,8 @@ src/
 
 | Composable | Purpose |
 |-----------|---------|
-| `useLtAuth()` | Authentication state, login, logout, session management |
-| `useLtAuthClient()` | Raw Better Auth client access |
+| `useLtAuth()` | Authentication state, login, logout, session management, password change + reset |
+| `useLtAuthClient()` | Raw Better Auth client access (`twoFactor.*`, `admin.*`, `passkey`) |
 | `useSystemSetup()` | First-admin setup flow |
 | `useLtTusUpload()` | TUS resumable file uploads |
 | `useLtFile()` | File utilities (size formatting, URLs) |
@@ -179,6 +179,90 @@ export default defineNuxtRouteMiddleware((to) => {
 });
 ```
 
+## Password Handling: Reset, Change, and Client-Side Hashing
+
+**Every password leaves the browser SHA256-hashed.** `auth-client.ts` wraps each Better-Auth
+method that carries a credential and substitutes that one field with its digest;
+`@lenne.tech/nest-server` hashes the received value again on its side. The two ends agree only
+because both do this — which is why a hand-rolled call is not a style choice but a way to lock
+a user out of their own account.
+
+### Use the composable. Never hand-roll the flow.
+
+`useLtAuth()` exposes the whole set — `changePassword`, `requestPasswordReset`, `resetPassword`
+(since 1.16.0) — alongside `signIn` / `signUp`. Reach for `useLtAuthClient()` only for surfaces
+the composable does not carry (`twoFactor.*`, `admin.*`, `passkey`); that client hashes too.
+
+What went wrong when a project did otherwise: `useLtAuth()` offered `changePassword` but neither
+reset method, so a reset page was built directly against `$fetch`, the client-side hashing was
+forgotten, and the backend stored `scrypt(plaintext)` while sign-in verified
+`scrypt(sha256(plaintext))`. The password the user had just chosen did not work, and nothing in
+either log said why. The gap in this composable is what created that workaround.
+
+```typescript
+const { requestPasswordReset, resetPassword } = useLtAuth();
+
+// Step 1 — send the mail. `redirectTo` MUST be absolute (see below).
+await requestPasswordReset({
+  email,
+  redirectTo: new URL('/auth/reset-password', config.public.siteUrl).toString(),
+});
+
+// Step 2 — on the reset page, with the token from the query string.
+await resetPassword({ newPassword, token });
+```
+
+### `redirectTo` must be absolute, and must never come from user input
+
+Better Auth resolves it against the **API** origin (`new URL(callbackURL, ctx.baseURL)`). A
+relative value therefore lands on the API host, where the route does not exist: 403
+`INVALID_REDIRECT_URL`, no mail sent, nothing visible in the browser. It fails silently.
+
+**It also carries a live single-use reset token.** An attacker-chosen value is account takeover,
+not a phishing redirect — so never build it from `route.query`, a referrer, or a form field.
+The only thing holding it back is the server's `trustedOrigins` allowlist; a project that
+widens that (or sets a wildcard) removes the last barrier. In lt starter projects `appUrl()`
+(from the starter's `app/utils/app-origin.ts`, not from this package) builds one and throws
+rather than returning something relative; elsewhere use `new URL(path, siteUrl).toString()`.
+
+### Password length is enforced by YOUR form — the server cannot do it
+
+better-auth checks `minPasswordLength` against the value it **receives**
+(`api/routes/password.mjs`). Because this library hashes first, that value is always a 64-character
+hex string, so the check passes trivially on every path. nest-server 11.38.0 adds a raw-value
+length check for plaintext clients, and it deliberately skips anything matching `^[a-f0-9]{64}$`
+— i.e. skips us.
+
+This is a consequence of client-side hashing, not a bug in either backend, and there is nothing to
+"fix" server-side. **A minimum length must live in your form schema** (the starters use
+`v.minLength(8)` on register, setup and reset). If someone later removes that rule reasoning that
+"the server validates it", nothing will catch it.
+
+### `admin.*` is passed through UNHASHED — an armed trap, not a live one
+
+`admin.createUser` (`password`) and `admin.setUserPassword` (`newPassword`) are the only
+credential-carrying methods this library does **not** hash.
+
+Today that is harmless: `@lenne.tech/nest-server` does not register better-auth's `admin()`
+plugin and has no option to enable it, so those routes 404. But `auth.enableAdmin` defaults to
+`true`, meaning the admin *client* plugin is registered in every consuming project — the trap is
+armed and waiting for a server that answers.
+
+**Enabling `admin()` server-side is therefore a lock-step change across both repos in one
+release:** the two routes join nest-server's password-normalisation table, and these two methods
+get `ltSha256` wrappers here. Doing only the server half creates accounts whose password nobody
+can ever log in with, with no error anywhere. Hashing here pre-emptively is equally wrong — it
+would build a client expectation the server does not answer.
+
+### If you add a wrapper that hashes something
+
+Add it to both guards. `test/auth-client-hashing.test.ts` asserts the actual request payload;
+`test/auth-client-param-forwarding.test.ts` keeps the source-level half. A hashing wrapper
+replaces ONE field and forwards the rest — `{ ...params, password: hashed }`. Never
+`{ password: hashed }` (drops `revokeOtherSessions`, `redirectTo`, `method`, `issuer` — all
+shipped defects), and never `{ password: hashed, ...params }`, which looks almost identical and
+puts the **plaintext** back on the wire.
+
 ## Form Label Repair
 
 **The defect:** Nuxt UI's `FormField` derives the label's `for` and the control's `id` from one
@@ -257,7 +341,10 @@ fields at `app:beforeMount` and restores them at `app:mounted`, dispatching a sy
 ## Development Rules
 
 1. **ALWAYS read source code** in `dist/runtime/` to understand available composables and components
-2. **Use `useLtAuth()`** for authentication — never implement auth manually
+2. **Use `useLtAuth()`** for authentication — never implement auth manually. This includes the
+   password-reset flow: passwords are SHA256-hashed client-side, and a hand-rolled call that skips
+   that step desynchronises the two credential stores and locks the user out (see "Password
+   Handling" below).
 3. **Check existing composables** before creating new ones — this module may already provide what you need
 4. **Peer dependencies** (`better-auth`, `@better-auth/passkey`, `tus-js-client`) must be installed in the consuming project.
    `better-auth` and `@better-auth/passkey` are pinned to **`>=1.7.1 <1.8.0`** — deliberately not a caret.

package/README.md

@@ -363,6 +363,9 @@ const {
   authenticateWithPasskey,
   registerPasskey,
   twoFactor,
+  changePassword,
+  requestPasswordReset,
+  resetPassword,
 } = useLtAuth();
 
 // Login with email/password
@@ -426,6 +429,50 @@ const { hasRole, hasAnyRole } = useLtAuth();
 </template>
 ```
 
+### Password Change and Reset
+
+All three methods hash the password with SHA256 before it leaves the browser, because
+`@lenne.tech/nest-server` verifies that shape. **Use them rather than calling the endpoints
+yourself** — a hand-rolled reset that skips the hashing stores a credential the login can never
+match, and the user is locked out of the account they just set a password for. That is not
+hypothetical; it is why these two methods were added in 1.16.0.
+
+```vue
+<script setup lang="ts">
+const { changePassword, requestPasswordReset, resetPassword } = useLtAuth();
+const config = useRuntimeConfig();
+
+// Signed-in user changes their own password.
+// `revokeOtherSessions` ends every OTHER session — set it after a suspected compromise.
+await changePassword({ currentPassword, newPassword, revokeOtherSessions: true });
+
+// Step 1: send the reset mail.
+await requestPasswordReset({
+  email,
+  redirectTo: new URL('/auth/reset-password', config.public.siteUrl).toString(),
+});
+
+// Step 2: on the reset page, with the token from the query string.
+await resetPassword({ newPassword, token: route.query.token as string });
+</script>
+```
+
+**`redirectTo` must be an absolute URL.** Better Auth resolves it against the **API** origin, so
+a relative value lands on the API host where the route does not exist — a 403
+`INVALID_REDIRECT_URL`, no mail sent, and nothing visible in the browser. In an lt starter
+project the auto-imported `appUrl()` helper builds one and throws rather than returning something
+relative; that helper lives in the starter (`app/utils/app-origin.ts`), not in this package, so
+outside a starter use `new URL(path, siteUrl).toString()` as above.
+
+**Never build `redirectTo` from user input** (`route.query`, a referrer, a form field). The link
+carries a live single-use reset token, so an attacker-chosen destination is account takeover
+rather than a phishing redirect. The server's `trustedOrigins` allowlist is what stops it.
+
+**Enforce a minimum password length in your own form.** better-auth checks `minPasswordLength`
+against the value it receives, and because this library hashes first, that value is always a
+64-character hex string — the check passes on every path. The form is the only place the rule can
+live.
+
 ### Custom Better Auth Plugins
 
 You can extend the auth client with additional [Better Auth plugins](https://www.better-auth.com/docs/plugins):
@@ -655,8 +702,8 @@ The package works **with or without** `@nuxtjs/i18n`:
 
 | Composable | Description |
 |------------|-------------|
-| `useLtAuth()` | Better-Auth integration with session, passkey, 2FA |
-| `useLtAuthClient()` | Direct access to the Better-Auth client singleton |
+| `useLtAuth()` | Better-Auth integration with session, passkey, 2FA, password change + reset |
+| `useLtAuthClient()` | Direct access to the Better-Auth client singleton (`twoFactor.*`, `admin.*`, `passkey`) |
 | `useLtErrorTranslation()` | Translate backend error codes to user-friendly messages |
 | `useLtTusUpload()` | TUS protocol file uploads with pause/resume |
 | `useLtFile()` | File utilities (size formatting, URLs) |

package/dist/module.d.mts

@@ -3,7 +3,7 @@ import { LtExtensionsModuleOptions } from '../dist/runtime/types/index.js';
 export * from '../dist/runtime/types/index.js';
 
 declare const name = "@lenne.tech/nuxt-extensions";
-declare const version = "1.15.1";
+declare const version = "1.17.0";
 declare const configKey = "ltExtensions";
 declare const DEFAULT_LT_AUTH_STATE_COOKIE = "lt-auth-state";
 declare const DEFAULT_LT_JWT_TOKEN_COOKIE = "lt-jwt-token";

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "configKey": "ltExtensions",
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.15.1",
+  "version": "1.17.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -2,7 +2,7 @@ import { defineNuxtModule, createResolver, tryResolveModule, addImports, addComp
 import { pathToFileURL } from 'node:url';
 
 const name = "@lenne.tech/nuxt-extensions";
-const version = "1.15.1";
+const version = "1.17.0";
 const configKey = "ltExtensions";
 const DEFAULT_LT_AUTH_STATE_COOKIE = "lt-auth-state";
 const DEFAULT_LT_JWT_TOKEN_COOKIE = "lt-jwt-token";

package/dist/runtime/composables/auth/use-lt-auth.js

@@ -201,7 +201,6 @@ export function useLtAuth() {
   }
   const signIn = {
     ...authClient.signIn,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     email: async (params, options) => {
       isLoading.value = true;
       try {
@@ -227,7 +226,6 @@ export function useLtAuth() {
   };
   const signUp = {
     ...authClient.signUp,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     email: async (params, options) => {
       isLoading.value = true;
       try {
@@ -382,7 +380,6 @@ export function useLtAuth() {
           timeout: options.timeout,
           attestation: options.attestation,
           authenticatorSelection: options.authenticatorSelection,
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
           excludeCredentials: (options.excludeCredentials || []).map((cred) => ({
             ...cred,
             id: ltBase64UrlToUint8Array(cred.id).buffer
@@ -479,6 +476,21 @@ export function useLtAuth() {
     changePassword: authClient.changePassword,
     clearUser,
     registerPasskey,
+    // The reset pair, exposed so no project has to reach for `useLtAuthClient()` or hand-roll
+    // the flow — the one that did forgot the client-side hashing and desynchronised the two
+    // credential stores. The full contract, including why `redirectTo` must be absolute and
+    // must never come from user input, lives on `UseLtAuthReturn` in `runtime/types/auth.ts`:
+    // that is the surface consumers read, and one copy cannot drift from itself.
+    //
+    // `params` is forwarded WHOLE and stays fully type-checked. Only `options` is cast, and
+    // only because `UseLtAuthReturn` declares it `unknown` while Better-Auth wants its own
+    // `ClientFetchOption`. Casting the METHOD instead — which is what this used to do — would
+    // throw away the checking on `params` as collateral, on the one argument that carries a
+    // credential. The `Parameters<>` here reads the client's option type INSIDE the
+    // implementation; it never reaches the published declarations, so it does not recreate
+    // the better-auth coupling that 1.15.1 had to revert.
+    requestPasswordReset: (params, options) => authClient.requestPasswordReset(params, options),
+    resetPassword: (params, options) => authClient.resetPassword(params, options),
     setUser,
     signIn,
     signOut,

package/dist/runtime/composables/use-lt-error-translation.js

@@ -59,6 +59,10 @@ export function useLtErrorTranslation() {
       return errorOrMessage;
     }
     if (errorOrMessage instanceof Error) {
+      const body = errorOrMessage.data;
+      if (typeof body?.message === "string" && body.message) {
+        return body.message;
+      }
       return errorOrMessage.message;
     }
     if (typeof errorOrMessage === "object" && errorOrMessage !== null) {