@lenne.tech/nuxt-extensions 1.14.0 → 1.15.1

package/CLAUDE.md

@@ -259,5 +259,14 @@ fields at `app:beforeMount` and restores them at `app:mounted`, dispatching a sy
 1. **ALWAYS read source code** in `dist/runtime/` to understand available composables and components
 2. **Use `useLtAuth()`** for authentication — never implement auth manually
 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
+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.
+   **They move in lock-step with `@lenne.tech/nest-server`.** better-auth is one protocol with two ends;
+   this module is the client end, nest-server the server end, and both declare the *same* narrow range.
+   Raising it means raising it in **both** framework repos and pinning the new version in **both** starters,
+   in one release. Never half of it, not even "just to unblock the frontend" — a split resolves as api on one
+   minor and app on another, 2FA activation fails at runtime, and *both* repos' `check` stays green because
+   each is internally consistent and only the assembled workspace has both halves.
+   `test/peer-dependency-ranges.test.ts` guards the declared range against the version actually tested;
+   `test/better-auth-contract.test.ts` pins the consumed better-auth surface.
 5. **AI types collision pitfall:** `LtAiPromptInput` is the CRUD input for the user-facing `LtAiPrompt` entity (used by `useLtAiPrompts().create/update`). The execution payload for `useLtAi.prompt()` / `.promptStream()` is `LtAiPromptRunInput`. Do not conflate them.

package/README.md

@@ -23,16 +23,48 @@ Reusable Nuxt 4 composables, components, and Better-Auth integration for lenne.t
 > npx @lenne.tech/cli fullstack init my-project
 > ```
 
+## Requirements
+
+| Dependency | Required version | Notes |
+|---|---|---|
+| Node | `>= 22` | |
+| Nuxt | `^4.0.0` | |
+| `better-auth` | `>=1.7.1 <1.8.0` | **required peer** — pin it, see below |
+| `@better-auth/passkey` | `>=1.7.1 <1.8.0` | optional peer, passkey/WebAuthn only |
+| `tus-js-client` | `>=4.0.0` | optional peer, resumable uploads only |
+| `@lenne.tech/nest-server` | `>= 11.37.0` | **only if you use the backend** — see the lock-step rule |
+
+**Why `better-auth` is pinned to one minor line, and why you must not widen it:**
+better-auth is one protocol with two ends. This module is the client end and
+`@lenne.tech/nest-server` is the server end, and they must resolve the **same**
+better-auth minor. better-auth breaks in *minor* releases — 1.7 removed subpath
+exports and changed the 2FA response shape — so a caret (`^1.7.1`) would re-open the
+hole at 1.8. If the api and the app drift apart, 2FA activation fails at runtime with a
+generic client error while **both** projects' checks stay green: each is internally
+consistent, and only the assembled workspace has both halves.
+
+Raising better-auth therefore means raising it in `@lenne.tech/nest-server` **and**
+`@lenne.tech/nuxt-extensions` in one step.
+
 ## Installation
 
 ```bash
-npm install @lenne.tech/nuxt-extensions better-auth
+npm install @lenne.tech/nuxt-extensions better-auth@1.7.1
 # Optional: For passkey support
-npm install @better-auth/passkey
+npm install @better-auth/passkey@1.7.1
 # Optional: For TUS file uploads
 npm install tus-js-client
 ```
 
+In a fullstack monorepo, pin it workspace-wide so the api and the app cannot drift:
+
+```yaml
+# pnpm-workspace.yaml
+overrides:
+  better-auth: 1.7.1
+  '@better-auth/passkey': 1.7.1
+```
+
 ## Features
 
 - **Better-Auth Integration** - Login, 2FA, Passkey/WebAuthn support

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.14.0";
+declare const version = "1.15.1";
 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.14.0",
+  "version": "1.15.1",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,7 +1,8 @@
 import { defineNuxtModule, createResolver, tryResolveModule, addImports, addComponent, addPlugin, addRouteMiddleware } from '@nuxt/kit';
+import { pathToFileURL } from 'node:url';
 
 const name = "@lenne.tech/nuxt-extensions";
-const version = "1.14.0";
+const version = "1.15.1";
 const configKey = "ltExtensions";
 const DEFAULT_LT_AUTH_STATE_COOKIE = "lt-auth-state";
 const DEFAULT_LT_JWT_TOKEN_COOKIE = "lt-jwt-token";
@@ -74,7 +75,7 @@ const module$1 = defineNuxtModule({
       preHydrationInput: { ...defaultOptions.preHydrationInput, ...options.preHydrationInput },
       tus: { ...defaultOptions.tus, ...options.tus }
     };
-    const passkeyAvailable = !!await tryResolveModule("@better-auth/passkey/client", new URL(import.meta.url));
+    const passkeyAvailable = !!await tryResolveModule("@better-auth/passkey/client", [new URL(import.meta.url), pathToFileURL(`${nuxt.options.rootDir}/`)]);
     if (!passkeyAvailable) {
       const passkeyStub = resolve("./runtime/lib/passkey-stub");
       nuxt.options.alias["@better-auth/passkey/client"] = passkeyStub;
@@ -233,11 +234,14 @@ const module$1 = defineNuxtModule({
     }
     nuxt.options.build.transpile.push(resolve("./runtime"));
     nuxt.options.build.transpile.push("tus-js-client");
-    console.log(`[${name}] Module loaded with config:`, {
-      auth: resolvedOptions.auth?.enabled ? "enabled" : "disabled",
-      i18nAutoMerge: resolvedOptions.i18n?.autoMerge,
-      tusEndpoint: resolvedOptions.tus?.defaultEndpoint
-    });
+    console.log(`[${name}] v${version}`);
+    if (nuxt.options.dev) {
+      console.log(`[${name}] Module loaded with config:`, {
+        auth: resolvedOptions.auth?.enabled ? "enabled" : "disabled",
+        i18nAutoMerge: resolvedOptions.i18n?.autoMerge,
+        tusEndpoint: resolvedOptions.tus?.defaultEndpoint
+      });
+    }
   }
 });
 

package/dist/runtime/lib/passkey-stub.d.ts

@@ -11,6 +11,16 @@
  * so the factory below is normally never called. It stays a no-op (rather than
  * throwing) to keep the direct `createLtAuthClient()` entry point working, whose
  * own `enablePasskey` default is `true`.
+ *
+ * WHY this file exports more than `passkeyClient`:
+ * the alias is installed into `nuxt.options.alias` and `nuxt.options.nitro.alias`,
+ * which rewrites the specifier for the WHOLE consumer app — not just for our
+ * `auth-client.ts`. A consumer (or another dependency) importing any other name
+ * from `@better-auth/passkey/client` would then hit
+ * `"PASSKEY_ERROR_CODES" is not exported by …/passkey-stub` — the same class of
+ * unresolved-export build failure this stub exists to prevent, merely relocated.
+ * So the stub mirrors the real package's full export surface.
+ * `test/optional-peers.test.ts` pins that surface against the real package.
  */
 /**
  * No-op replacement for the real `passkeyClient()` Better-Auth client plugin.
@@ -21,3 +31,86 @@
 export declare function passkeyClient(): {
     id: "lt-passkey-unavailable";
 };
+/**
+ * Mirror of the real package's error-code table.
+ *
+ * Frozen and value-complete so a consumer that reads a code for a message or an
+ * equality check still gets a defined value instead of a `TypeError` on
+ * `undefined`. The codes are the contract; the messages are best-effort copies.
+ */
+export declare const PASSKEY_ERROR_CODES: Readonly<{
+    AUTH_CANCELLED: {
+        code: string;
+        message: string;
+    };
+    AUTHENTICATION_FAILED: {
+        code: string;
+        message: string;
+    };
+    CHALLENGE_NOT_FOUND: {
+        code: string;
+        message: string;
+    };
+    FAILED_TO_UPDATE_PASSKEY: {
+        code: string;
+        message: string;
+    };
+    FAILED_TO_VERIFY_REGISTRATION: {
+        code: string;
+        message: string;
+    };
+    PASSKEY_NOT_FOUND: {
+        code: string;
+        message: string;
+    };
+    PREVIOUSLY_REGISTERED: {
+        code: string;
+        message: string;
+    };
+    REGISTRATION_CANCELLED: {
+        code: string;
+        message: string;
+    };
+    RESOLVE_USER_REQUIRED: {
+        code: string;
+        message: string;
+    };
+    RESOLVED_USER_INVALID: {
+        code: string;
+        message: string;
+    };
+    SESSION_REQUIRED: {
+        code: string;
+        message: string;
+    };
+    UNABLE_TO_CREATE_SESSION: {
+        code: string;
+        message: string;
+    };
+    UNKNOWN_ERROR: {
+        code: string;
+        message: string;
+    };
+    USER_NOT_FOUND: {
+        code: string;
+        message: string;
+    };
+    YOU_ARE_NOT_ALLOWED_TO_REGISTER_THIS_PASSKEY: {
+        code: string;
+        message: string;
+    };
+}>;
+/**
+ * No-op replacement for the real `getPasskeyActions()`.
+ *
+ * Every action rejects rather than resolving falsely: a passkey ceremony that
+ * silently "succeeds" without the package would leave the caller believing a
+ * credential exists. The rejection names the missing dependency.
+ */
+export declare function getPasskeyActions(..._args: unknown[]): {
+    addPasskey: () => Promise<never>;
+    deletePasskey: () => Promise<never>;
+    listUserPasskeys: () => Promise<never>;
+    signInPasskey: () => Promise<never>;
+    updatePasskey: () => Promise<never>;
+};

package/dist/runtime/lib/passkey-stub.js

@@ -1,10 +1,50 @@
 let warned = false;
-export function passkeyClient() {
-  if (!warned) {
-    warned = true;
-    console.warn(
-      '[@lenne.tech/nuxt-extensions] Passkey support is unavailable: the optional peer dependency "@better-auth/passkey" is not installed. Install it to use passkeys, or pass `enablePasskey: false` to createLtAuthClient() to silence this warning.'
-    );
+function warnOnce(entryPoint) {
+  if (warned) {
+    return;
   }
+  warned = true;
+  console.warn(
+    `[@lenne.tech/nuxt-extensions] Passkey support is unavailable: the optional peer dependency "@better-auth/passkey" is not installed. Install it to use passkeys, or pass \`enablePasskey: false\` to createLtAuthClient() to silence this warning. (reached via ${entryPoint})`
+  );
+}
+export function passkeyClient() {
+  warnOnce("passkeyClient()");
   return { id: "lt-passkey-unavailable" };
 }
+export const PASSKEY_ERROR_CODES = Object.freeze({
+  AUTH_CANCELLED: { code: "AUTH_CANCELLED", message: "Auth cancelled" },
+  AUTHENTICATION_FAILED: { code: "AUTHENTICATION_FAILED", message: "Authentication failed" },
+  CHALLENGE_NOT_FOUND: { code: "CHALLENGE_NOT_FOUND", message: "Challenge not found" },
+  FAILED_TO_UPDATE_PASSKEY: { code: "FAILED_TO_UPDATE_PASSKEY", message: "Failed to update passkey" },
+  FAILED_TO_VERIFY_REGISTRATION: { code: "FAILED_TO_VERIFY_REGISTRATION", message: "Failed to verify registration" },
+  PASSKEY_NOT_FOUND: { code: "PASSKEY_NOT_FOUND", message: "Passkey not found" },
+  PREVIOUSLY_REGISTERED: { code: "PREVIOUSLY_REGISTERED", message: "Previously registered" },
+  REGISTRATION_CANCELLED: { code: "REGISTRATION_CANCELLED", message: "Registration cancelled" },
+  RESOLVE_USER_REQUIRED: {
+    code: "RESOLVE_USER_REQUIRED",
+    message: "Passkey registration requires either an authenticated session or a resolveUser callback when requireSession is false"
+  },
+  RESOLVED_USER_INVALID: { code: "RESOLVED_USER_INVALID", message: "Resolved user is invalid" },
+  SESSION_REQUIRED: { code: "SESSION_REQUIRED", message: "Passkey registration requires an authenticated session" },
+  UNABLE_TO_CREATE_SESSION: { code: "UNABLE_TO_CREATE_SESSION", message: "Unable to create session" },
+  UNKNOWN_ERROR: { code: "UNKNOWN_ERROR", message: "Unknown error" },
+  USER_NOT_FOUND: { code: "USER_NOT_FOUND", message: "User not found" },
+  YOU_ARE_NOT_ALLOWED_TO_REGISTER_THIS_PASSKEY: {
+    code: "YOU_ARE_NOT_ALLOWED_TO_REGISTER_THIS_PASSKEY",
+    message: "You are not allowed to register this passkey"
+  }
+});
+export function getPasskeyActions(..._args) {
+  warnOnce("getPasskeyActions()");
+  const unavailable = async () => {
+    throw new Error('[@lenne.tech/nuxt-extensions] Passkey action unavailable: the optional peer dependency "@better-auth/passkey" is not installed.');
+  };
+  return {
+    addPasskey: unavailable,
+    deletePasskey: unavailable,
+    listUserPasskeys: unavailable,
+    signInPasskey: unavailable,
+    updatePasskey: unavailable
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.14.0",
+  "version": "1.15.1",
   "description": "Reusable Nuxt 4 composables, components, and Better-Auth integration for lenne.tech projects",
   "repository": {
     "type": "git",
@@ -78,9 +78,9 @@
     "@nuxt/kit": "^4.0.0"
   },
   "peerDependencies": {
-    "@better-auth/passkey": ">=1.0.0",
+    "@better-auth/passkey": ">=1.7.1 <1.8.0",
     "@playwright/test": ">=1.0.0",
-    "better-auth": ">=1.0.0",
+    "better-auth": ">=1.7.1 <1.8.0",
     "nuxt": "^4.0.0",
     "tus-js-client": ">=4.0.0"
   },