@lenne.tech/nuxt-extensions 1.24.0 → 1.25.0

package/CLAUDE.md

@@ -27,7 +27,7 @@ src/
 |-----------|---------|
 | `useLtAuth()` | Authentication state, login, logout, session management, password change + reset |
 | `useLtAuthClient()` | Raw Better Auth client access (`twoFactor.*`, `admin.*`, `passkey`) |
-| `useSystemSetup()` | First-admin setup flow |
+| `useSystemSetup()` | First-admin setup flow: status, HTTP-setup release + setup token (nest-server >= 12.4.0) |
 | `useLtTusUpload()` | TUS resumable file uploads |
 | `useLtFile()` | File utilities (size formatting, URLs) |
 | `useLtShare()` | Web Share API with clipboard fallback |
@@ -311,7 +311,8 @@ This is a consequence of client-side hashing, not a bug in either backend, and t
 ### `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.
+passwords this library does **not** hash. (The setup token of `useSystemSetup().initSetup()` is
+unhashed too, by design — see "First Admin Setup" below.)
 
 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
@@ -333,6 +334,28 @@ replaces ONE field and forwards the rest — `{ ...params, password: hashed }`.
 shipped defects), and never `{ password: hashed, ...params }`, which looks almost identical and
 puts the **plaintext** back on the wire.
 
+## First Admin Setup: the HTTP init is closed on deployed stages
+
+Since nest-server 12.4.0 the anonymous `POST /system-setup/init` is open only in `local`, `ci` and
+`e2e`. A deployed API refuses it with 403 (`LTNS_0053`) unless `systemSetup.httpInit` releases it,
+optionally behind a setup token (`LTNS_0054` when wrong). `GET /system-setup/status` reports
+`httpInitEnabled` and `httpInitTokenRequired`; `useSystemSetup()` exposes both.
+
+- **The middleware does not redirect when `httpInitEnabled === false`.** That is deliberate, not a
+  bug: a redirect would hold every visitor on a page whose only action fails, and the login would be
+  unreachable. The setup page itself must show the notice ("first admin comes from the
+  configuration") instead of the form.
+- **The token is a header (`X-System-Setup-Token`), unhashed, never a body field.** Unlike the
+  passwords, it is not hashed: the server compares it as given. Do not add it to the SHA256
+  wrappers.
+- **A missing field means an API before 12.4.0**, which accepts the HTTP setup: `httpInitEnabled`
+  reads `true`. The server's 403 is the boundary, the flag is UX. Only a 200 without the field
+  counts as old; a failed status read leaves both values unchanged (`null` initially).
+- **After a 403 from `initSetup()` the composable re-reads the status** before rethrowing, so the
+  page switches to the notice or the token field when the API was restarted with another
+  configuration. Pass the error itself to `translateError(error)`: the `#LTNS_` code is in the
+  body, `error.message` holds only the transport line.
+
 ## Form Label Repair
 
 **The defect:** Nuxt UI's `FormField` derives the label's `for` and the control's `id` from one
@@ -433,6 +456,10 @@ fields at `app:beforeMount` and restores them at `app:mounted`, dispatching a sy
   relative `extends` points at nothing, and `oxlint --type-aware` then stops every vendored project's
   `check` with `Invalid tsconfig`. Nitro code is typechecked through the root `tsconfig.server.json`.
   No gate here runs in vendor mode, so `test/vendored-core.test.ts` holds this.
+- **nuxt-base-starter lints `app/core/**` with a subset of the plugins in `.oxlintrc.json`, never
+  more**, and `lint` here runs with `--deny-warnings`. A plugin only the starter applies reports its
+  warnings in every generated project after the release; the 1.24.0 smoke test found three. A plugin
+  the starter wants for `app/core/**` is added here first.
 - **The `nuxt/schema` blocks in `runtime/types/module.ts` augment `PublicRuntimeConfig` and nothing
   else.** Vendoring turns them into project source, where they cause TS2310, and the cli removes a
   block only while it holds that one interface. Type server-only config where it is read.

package/README.md

@@ -567,6 +567,51 @@ against the value it receives, and because this library hashes first, that value
 64-character hex string — the check passes on every path. The form is the only place the rule can
 live.
 
+### First Admin Setup
+
+With `auth.systemSetup.enabled`, a global middleware sends visitors to `setupPath` while the API
+has no user yet, and `useSystemSetup()` creates the first admin.
+
+Since `@lenne.tech/nest-server` 12.4.0 the anonymous `POST /system-setup/init` is open only in
+`local`, `ci` and `e2e`. A deployed API refuses it with 403 (`LTNS_0053`) unless the deployment
+releases it (`systemSetup.httpInit`), optionally behind a setup token. A deployment usually creates
+its first admin from its configuration instead (`systemSetup.initialAdmin`).
+`GET /system-setup/status` reports which applies, and the composable exposes it:
+
+```vue
+<script setup lang="ts">
+const { httpInitEnabled, httpInitTokenRequired, initSetup } = useSystemSetup();
+const { translateError } = useLtErrorTranslation();
+const toast = useToast();
+
+async function onSubmit(data: { email: string; name: string; password: string; token?: string }) {
+  try {
+    // `token` goes out as the X-System-Setup-Token header, unhashed; omit it when not required.
+    await initSetup(data);
+  } catch (error) {
+    // Pass the error itself: the #LTNS_ code is in the response body, not in `error.message`.
+    toast.add({ color: 'error', description: translateError(error), title: 'Setup failed' });
+  }
+}
+</script>
+
+<template>
+  <!-- `false`: the deployment creates its first admin from its configuration — no form. -->
+  <SetupNotice v-if="httpInitEnabled === false" />
+  <SetupForm v-else :with-token="httpInitTokenRequired === true" @submit="onSubmit" />
+</template>
+```
+
+- **Without the HTTP setup the middleware redirects nowhere.** A redirect would hold every visitor
+  on a page whose only action fails. The setup page stays reachable, so it must show the notice
+  itself.
+- **An API before 12.4.0** reports neither field and accepts the HTTP setup, so `httpInitEnabled`
+  reads `true` and `httpInitTokenRequired` `false` — the behaviour before this release.
+- **After a 403 from `initSetup()`** the composable re-reads the status before rethrowing, so a page
+  whose API was restarted with another configuration switches to the notice (`LTNS_0053`) or to the
+  token field (`LTNS_0054`) without a reload.
+- `null` means the status was not read yet, or reading it failed.
+
 ### Custom Better Auth Plugins
 
 You can extend the auth client with additional [Better Auth plugins](https://www.better-auth.com/docs/plugins):
@@ -975,7 +1020,7 @@ The package works **with or without** `@nuxtjs/i18n`:
 | `useLtTusUpload()` | TUS protocol file uploads with pause/resume |
 | `useLtFile()` | File utilities (size formatting, URLs) |
 | `useLtShare()` | Web Share API with clipboard fallback |
-| `useSystemSetup()` | System setup flow for initial admin user creation |
+| `useSystemSetup()` | First admin creation: setup status, HTTP-setup release + token (nest-server >= 12.4.0) |
 | `useLtAi()` | One-shot `prompt()` + streaming `promptStream()` for the nest-server AI module |
 | `useLtAiChat()` | Multi-turn chat state, streaming, budget summary, confirmation gate, `maxMessages` cap |
 | `useLtAiConnections()` | User self-service connection list + `select()` |

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

package/dist/module.mjs

@@ -3,7 +3,7 @@ import { pathToFileURL } from 'node:url';
 import { SECURITY_TXT_DEFAULT_VALID_DAYS, SECURITY_TXT_DEFAULT_LANGUAGES, SECURITY_TXT_DEFAULT_CONTACT, SECURITY_TXT_PATH } from '../dist/runtime/server/lib/security-txt.js';
 
 const name = "@lenne.tech/nuxt-extensions";
-const version = "1.24.0";
+const version = "1.25.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-system-setup.d.ts

@@ -12,13 +12,27 @@ import type { ComputedRef } from 'vue';
 export interface UseSystemSetupReturn {
     /** Whether the system needs initial setup (null = not checked yet) */
     needsSetup: ComputedRef<boolean | null>;
+    /**
+     * Whether the API accepts the setup over HTTP (null = not checked yet). `false` means the
+     * deployment creates its first admin from its configuration, and `initSetup()` would be
+     * refused with 403 (`LTNS_0053`): show a notice instead of the form. An API before
+     * nest-server 12.4.0 does not report it and accepts the HTTP setup, so it reads as `true`.
+     */
+    httpInitEnabled: ComputedRef<boolean | null>;
+    /** Whether `initSetup()` needs a `token` (null = not checked yet). Only an explicit `true` counts. */
+    httpInitTokenRequired: ComputedRef<boolean | null>;
     /** Check setup status from the backend */
     checkSetupStatus: () => Promise<boolean>;
-    /** Initialize the system with the first admin user */
+    /**
+     * Initialize the system with the first admin user. `token` is the setup token, required when
+     * `httpInitTokenRequired` is true. A refusal is rethrown unchanged, so `useLtErrorTranslation()`
+     * reads its code (`LTNS_0053` HTTP setup disabled, `LTNS_0054` wrong token) from the body.
+     */
     initSetup: (params: {
         email: string;
         password: string;
         name: string;
+        token?: string;
     }) => Promise<void>;
 }
 /**
@@ -26,11 +40,11 @@ export interface UseSystemSetupReturn {
  *
  * @example
  * ```typescript
- * const { needsSetup, checkSetupStatus, initSetup } = useSystemSetup();
+ * const { needsSetup, httpInitEnabled, httpInitTokenRequired, checkSetupStatus, initSetup } = useSystemSetup();
  *
  * await checkSetupStatus();
- * if (needsSetup.value) {
- *   await initSetup({ email: 'admin@example.com', password: 'secret', name: 'Admin' });
+ * if (needsSetup.value && httpInitEnabled.value) {
+ *   await initSetup({ email: 'admin@example.com', password: 'secret', name: 'Admin', token });
  * }
  * ```
  */

package/dist/runtime/composables/auth/use-system-setup.js

@@ -8,9 +8,17 @@ function isApiUrlMissing() {
     return true;
   }
 }
+const SETUP_TOKEN_HEADER = "X-System-Setup-Token";
+function isRefusal(error) {
+  const { status, statusCode } = error ?? {};
+  return (statusCode ?? status) === 403;
+}
 export function useSystemSetup() {
   const needsSetupState = useState("lt-needs-setup", () => null);
+  const httpInitState = useState("lt-system-setup-http-init", () => null);
   const needsSetup = computed(() => needsSetupState.value);
+  const httpInitEnabled = computed(() => httpInitState.value?.enabled ?? null);
+  const httpInitTokenRequired = computed(() => httpInitState.value?.tokenRequired ?? null);
   async function checkSetupStatus() {
     if (import.meta.server && isApiUrlMissing()) {
       warnMissingLtApiUrl("server");
@@ -19,6 +27,12 @@ export function useSystemSetup() {
     try {
       const url = buildLtApiUrl("/system-setup/status");
       const data = await $fetch(url);
+      httpInitState.value = {
+        // Missing or malformed reads as released: an API before 12.4.0 accepts the HTTP setup,
+        // and the server's 403 is the boundary, not this flag.
+        enabled: typeof data.httpInitEnabled === "boolean" ? data.httpInitEnabled : true,
+        tokenRequired: data.httpInitTokenRequired === true
+      };
       needsSetupState.value = data.needsSetup;
       return data.needsSetup;
     } catch {
@@ -29,18 +43,29 @@ export function useSystemSetup() {
   async function initSetup(params) {
     const url = buildLtApiUrl("/system-setup/init");
     const hashedPassword = await ltSha256(params.password);
-    await $fetch(url, {
-      method: "POST",
-      body: {
-        email: params.email,
-        password: hashedPassword,
-        name: params.name
+    const token = params.token?.trim();
+    try {
+      await $fetch(url, {
+        method: "POST",
+        body: {
+          email: params.email,
+          password: hashedPassword,
+          name: params.name
+        },
+        ...token ? { headers: { [SETUP_TOKEN_HEADER]: token } } : {}
+      });
+    } catch (error) {
+      if (isRefusal(error)) {
+        await checkSetupStatus();
       }
-    });
+      throw error;
+    }
     needsSetupState.value = false;
   }
   return {
     needsSetup,
+    httpInitEnabled,
+    httpInitTokenRequired,
     checkSetupStatus,
     initSetup
   };

package/dist/runtime/lib/sync-hints.js

@@ -74,15 +74,15 @@ function connectHub(key, hub) {
   hub.close = openLtSyncHints({
     models: models.split(","),
     onConnect: () => {
-      for (const subscriber of [...hub.subscribers]) subscriber.onConnect();
+      for (const subscriber of Array.from(hub.subscribers)) subscriber.onConnect();
     },
     onHint: (model) => {
-      for (const subscriber of [...hub.subscribers]) if (subscriber.model === model) subscriber.onHint();
+      for (const subscriber of Array.from(hub.subscribers)) if (subscriber.model === model) subscriber.onHint();
     },
     onStop: (reason) => {
       hub.close = void 0;
       hub.models = "";
-      for (const subscriber of [...hub.subscribers]) subscriber.onStop?.(reason);
+      for (const subscriber of Array.from(hub.subscribers)) subscriber.onStop?.(reason);
     },
     tenantId: key || void 0
   });

package/dist/runtime/middleware/setup.d.ts

@@ -5,8 +5,15 @@
  * needs initial setup (no admin user exists yet).
  *
  * - needsSetup === null -> calls checkSetupStatus()
- * - needsSetup === true AND route != setupPath -> redirect to setupPath
+ * - needsSetup === true AND HTTP init released AND route != setupPath -> redirect to setupPath
+ * - needsSetup === true AND HTTP init NOT released -> no redirect
  * - needsSetup === false AND route === setupPath -> redirect to loginPath
+ *
+ * Without the HTTP init (nest-server >= 12.4.0 closes it outside `local`, `ci` and `e2e`), the
+ * API refuses `POST /system-setup/init` with 403 and the deployment creates its first admin from
+ * its configuration. A redirect would then hold every visitor on a page whose only action fails,
+ * with the login out of reach. So nothing is redirected; the setup page stays reachable and shows
+ * its notice there (`useSystemSetup().httpInitEnabled === false`).
  */
 import type { RouteMiddleware } from '#app';
 declare const _default: RouteMiddleware;

package/dist/runtime/middleware/setup.js

@@ -5,12 +5,12 @@ export default defineNuxtRouteMiddleware(async (to) => {
   const authConfig = runtimeConfig.public?.ltExtensions?.auth;
   const setupPath = authConfig?.systemSetup?.setupPath || "/auth/setup";
   const loginPath = authConfig?.loginPath || "/auth/login";
-  const { needsSetup, checkSetupStatus } = useSystemSetup();
+  const { needsSetup, httpInitEnabled, checkSetupStatus } = useSystemSetup();
   try {
     if (needsSetup.value === null) {
       await checkSetupStatus();
     }
-    if (needsSetup.value === true && to.path !== setupPath) {
+    if (needsSetup.value === true && httpInitEnabled.value !== false && to.path !== setupPath) {
       return navigateTo(setupPath);
     }
     if (needsSetup.value === false && to.path === setupPath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "description": "Reusable Nuxt 4 composables, components, and Better-Auth integration for lenne.tech projects",
   "repository": {
     "type": "git",
@@ -60,8 +60,8 @@
     "dev:build": "nuxt build playground",
     "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
     "build": "nuxt-module-build build",
-    "lint": "oxlint --type-aware src/ scripts/",
-    "lint:fix": "oxlint --type-aware --fix src/ scripts/",
+    "lint": "oxlint --type-aware --deny-warnings src/ scripts/",
+    "lint:fix": "oxlint --type-aware --deny-warnings --fix src/ scripts/",
     "format": "oxfmt --write src/",
     "format:check": "oxfmt --check src/",
     "version:sync": "node scripts/sync-module-version.mjs",