nuxt-feathers-zod 0.2.3 → 0.2.5

package/README.md

@@ -1,357 +1,193 @@
-# nuxt-feathers-zod
+# nuxt-feathers-zod 
+[guide](https://vevedh.github.io/nuxt-feathers-zod/)
 
-Nuxt 4 module that embeds a **FeathersJS v5 (Dove)** server directly into **Nitro** and exposes Feathers services to your Nuxt application, with **Zod-first validation** and an optional **Swagger (legacy) integration**.
+### Guide officiel d’initialisation – Nuxt 4 (Bun, Feathers v5, Zod)
 
-This module lets you run Feathers **without a separate backend process**, while keeping strong typing, shared schemas, and a clean DX.
+Ce guide décrit **la seule procédure valide et supportée** pour initialiser correctement **nuxt-feathers-zod** dans un projet **Nuxt 4**, en se basant **strictement sur le comportement réel du module**.
 
----
+Il évite volontairement toute “magie implicite” ou création manuelle non supportée.
 
-## ✨ Features
+---
 
-- FeathersJS v5 (Dove) running **inside Nitro**
-- REST transport (Koa or Express)
-- Optional Socket.io transport (WebSocket)
-- **Zod schemas** for data + query validation (server-side)
-- Typed Feathers client injected into Nuxt (`$api`)
-- Optional Pinia integration via `feathers-pinia`
-- CLI to generate services and middleware
-- **Swagger UI (legacy)** support via `feathers-swagger`
+## 1. Objectif du module
 
----
+`nuxt-feathers-zod` permet d’embarquer un **backend FeathersJS v5 (Dove)** directement dans **Nitro**, avec :
 
-## 📦 Requirements
+* API REST (`/feathers/*`)
+* WebSocket (Socket.IO)
+* Validation **Zod-first**
+* Authentification **Local + JWT**
+* Adapters (MongoDB, Memory, etc.)
+* Swagger legacy (optionnel)
+* Composables client (`useService`, `useAuth`, stores Pinia)
 
-- Node.js **18+** (or **Bun** recommended)
-- Nuxt **4**
-- FeathersJS **v5 (Dove)**
+👉 Il **n’y a pas de backend séparé** : Feathers est monté **dans Nuxt**.
 
 ---
 
-## 🚀 Using nuxt-feathers-zod in a new Nuxt 4 project (step by step)
+## 2. Pré-requis
 
-This section explains **from zero** how to use `nuxt-feathers-zod` in a fresh Nuxt 4 project.
+* **Bun** (recommandé et supporté)
+* **Node.js ≥ 18**
+* **Nuxt 4**
+* MongoDB (optionnel mais recommandé)
 
 ---
 
-## 1️⃣ Create a new Nuxt 4 project
+## 3. Création du projet Nuxt 4
 
 ```bash
-bunx nuxi@latest init my-nuxt-feathers-app
-cd my-nuxt-feathers-app
+bunx nuxi@latest init my-site
+cd my-site
 bun install
-```
-
-Run once to verify:
-
-```bash
 bun run dev
 ```
 
----
-
-## 2️⃣ Install nuxt-feathers-zod
-
-```bash
-bun add nuxt-feathers-zod feathers-pinia
-```
-
-(Optional – for Swagger legacy support)
-
-```bash
-bun add feathers-swagger
-```
-
----
-
-## 3️⃣ Enable the module
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['nuxt-feathers-zod'],
-})
-```
-
-At this point, Nuxt will start with an **embedded FeathersJS server inside Nitro**.
-
----
-
-Parfait 👍
-Voici un **bloc prêt à intégrer dans ton `README.md`**, qui :
-
-1. **explique précisément le rôle de `playground/server/feathers/dummy.ts`**
-2. **explique pourquoi le premier service à créer doit être `users`**
-3. **donne le raisonnement Feathers + Auth + Swagger + DX**
-
-Tu peux l’insérer tel quel (par exemple après la section _Minimal Feathers configuration_).
+➡️ Vérifie que Nuxt démarre **avant toute intégration Feathers**.
 
 ---
 
-## 🧪 Playground – rôle du fichier `playground/server/feathers/dummy.ts`
-
-Le fichier :
-
-```ts
-playground / server / feathers / dummy.ts
-```
-
-est **volontairement simple** et joue un rôle fondamental dans le module `nuxt-feathers-zod`.
-
-### 🎯 Objectif principal
-
-👉 **Fournir un backend Feathers minimal mais fonctionnel**, utilisable immédiatement dans le playground Nuxt, sans dépendre d’un vrai projet métier.
-
-Il permet de :
+## 4. Installation des dépendances
 
-- vérifier que **Feathers démarre correctement dans Nitro**
-- valider le **routing REST** (`/feathers/*`)
-- tester **Swagger UI**
-- servir de **service de test (smoke test)** pour le module
-
----
-
-### 🧩 Que fait concrètement `dummy.ts` ?
-
-Typiquement, ce fichier :
-
-- crée une application Feathers
-- enregistre **au moins un service**
-- expose une route REST simple (ex: `/dummy`)
-- ne dépend pas d’authentification ni de base de données
-
-Exemple conceptuel :
-
-```ts
-export function dummy(app: Application) {
-  app.use('dummy', {
-    async find() {
-      return [{ ok: true }]
-    },
-  })
-}
-```
-
-Ce service permet de tester immédiatement :
+### 4.1 Module principal
 
 ```bash
-curl http://localhost:3000/feathers/dummy
+bun add nuxt-feathers-zod feathers-pinia
 ```
 
----
-
-### 🧠 Pourquoi ce fichier est important ?
-
-Sans `dummy.ts` :
-
-- Feathers démarre **sans aucun service**
-- Swagger UI peut être vide ou trompeur
-- les tests d’intégration sont plus complexes
-- le playground ne démontre rien visuellement
+### 4.2 (Optionnel) Swagger legacy
 
-👉 **`dummy.ts` est un point d’ancrage pédagogique et technique**, pas un service métier.
-
----
-
-## 👤 Pourquoi créer immédiatement un service `users` (et pas un autre) ?
-
-Dans un projet Feathers **avec authentification**, le **premier vrai service à créer doit toujours être `users`**.
-
-Ce n’est **pas un choix arbitraire**.
-
----
-
-### 🔐 Raison n°1 — Feathers Auth repose sur `users`
-
-Le système d’authentification Feathers (v5 Dove) repose sur :
-
-- le service **`authentication`**
-- une **stratégie locale ou JWT**
-- un **service utilisateur** (`users`)
-
-➡️ **Sans service `users`**, ces endpoints ne peuvent pas fonctionner :
-
-```http
-POST /feathers/authentication
-POST /feathers/users
+```bash
+bun add feathers-swagger swagger-ui-dist
 ```
 
----
-
-### 🔑 Raison n°2 — `users` est la source de vérité sécurité
-
-Le service `users` contient :
-
-- les identifiants (email, username, etc.)
-- le mot de passe hashé
-- les rôles (`admin`, `editor`, etc.)
-- les règles d’accès (RBAC)
-
-C’est sur `users` que reposent ensuite :
-
-- `authenticate('jwt')`
-- `requireRole(...)`
-- les hooks de sécurité
-- Swagger `securitySchemes`
-
----
-
-### 🧠 Raison n°3 — Swagger dépend fortement de `users`
-
-Si tu actives Swagger (`feathers.swagger = true`) :
-
-- le **flux d’authentification JWT** est documenté
-- le bouton **Authorize** apparaît
-- les routes sécurisées sont visibles
-
-👉 **Sans `users`, Swagger est incomplet ou trompeur**.
-
----
-
-### 🧪 Raison n°4 — DX et tests automatisés
-
-Dans `nuxt-feathers-zod`, le service `users` permet :
-
-- de tester immédiatement :
-
-  ```bash
-  curl -X POST /feathers/users
-  curl -X POST /feathers/authentication
-  ```
-
-- de valider :
-  - JWT
-  - guards
-  - hooks
-  - swagger.json
-
-- d’avoir un **socle stable pour tous les autres services**
-
----
-
-## ✅ Ordre recommandé des services dans un projet Nuxt + Feathers
-
-Toujours respecter cet ordre :
-
-1. **`dummy`** (playground / smoke test)
-2. **`users`** ← indispensable
-3. `authentication` (auto-géré)
-4. services métier (`articles`, `projects`, `tickets`, etc.)
+> ⚠️ `swagger-ui-dist` est requis si `feathers.swagger = true`
 
 ---
 
-## 🧭 Résumé
-
-- `dummy.ts` :
-  - service minimal
-  - sert de **preuve de fonctionnement**
-  - facilite debug, Swagger et onboarding
-
-- `users` :
-  - **service fondamental**
-  - requis pour l’authentification
-  - point central de la sécurité
-  - base de Swagger, JWT et RBAC
-
-👉 **Sans `users`, un projet Feathers n’est pas réellement exploitable.**
+## 5. Configuration **obligatoire** (`nuxt.config.ts`)
 
-## 4️⃣ Minimal Feathers configuration
+> ⚠️ **Cette configuration est critique**.
+> Une mauvaise initialisation provoque des erreurs bloquantes au démarrage.
 
 ```ts
-// nuxt.config.ts
 export default defineNuxtConfig({
   modules: ['nuxt-feathers-zod'],
 
   feathers: {
+    /**
+     * RÈGLE D’OR :
+     * Le module scanne UNIQUEMENT ces dossiers
+     */
     servicesDirs: ['services'],
 
+    /**
+     * Transports
+     */
     transports: {
       rest: {
         path: '/feathers',
         framework: 'koa',
       },
+      websocket: true,
     },
 
+    /**
+     * Base de données (MongoDB recommandé)
+     */
     database: {
       mongo: {
-        url: 'mongodb://127.0.0.1:27017/nuxt-feathers-zod',
+        url: 'mongodb://127.0.0.1:27017/my-site',
       },
     },
+
+    /**
+     * Authentification
+     */
+    auth: true,
+
+    /**
+     * Swagger legacy (optionnel)
+     */
+    swagger: false,
   },
 })
 ```
 
-Start Nuxt:
+---
 
-```bash
-bun run dev
-```
+## 6. RÈGLE FONDAMENTALE – À NE JAMAIS VIOLER
 
-Test:
+> ❌ **Ne jamais créer un service manuellement**
+> ✅ **Toujours utiliser la CLI officielle**
 
-```bash
-curl http://localhost:3000/feathers
-```
+Cette règle est **imposée par le code interne du module**.
 
 ---
 
-## 5️⃣ Generate your first service
+## 7. Création du premier service : `users` (OBLIGATOIRE)
 
 ```bash
-bunx nuxt-feathers-zod add service articles \
+bunx nuxt-feathers-zod add service users \
   --adapter mongodb \
   --auth \
   --idField _id \
   --docs
 ```
 
-This generates:
+### Structure générée (attendue)
 
 ```
-services/articles/
-├─ articles.class.ts
-├─ articles.schema.ts
-├─ articles.ts
-└─ articles.shared.ts
+services/users/
+  users.ts
+  users.class.ts
+  users.schema.ts
+  users.shared.ts
 ```
 
----
+### Pourquoi `users` est obligatoire ?
 
-## 6️⃣ Example: Articles service (server)
+* Le module **résout l’authentification** via une `entityClass` nommée **`User`**
+* Cette classe est **recherchée dynamiquement** dans les exports scannés
+* Sans ce service :
 
-```ts
-// services/articles/articles.ts
-export function articles(app: Application) {
-  app.use('articles', new ArticlesService(getOptions(app)), {
-    methods: ['find', 'get', 'create', 'patch', 'remove'],
-    docs: {
-      description: 'Articles API',
-      idType: 'string',
-    },
-  })
-}
-```
+  * `Services typeExports []`
+  * `Entity class User not found in services imports`
+  * **Boot impossible**
+
+👉 Le service `users` est la **clé de voûte** de tout projet `nuxt-feathers-zod`.
 
 ---
 
-## 7️⃣ Use the service in Nuxt (client)
+## 8. Création d’un service métier (exemple : `articles`)
 
-```vue
-<script setup lang="ts">
-const { $api } = useNuxtApp()
+```bash
+bunx nuxt-feathers-zod add service articles \
+  --adapter mongodb \
+  --auth \
+  --idField _id \
+  --docs
+```
 
-const articles = await $api.service('articles').find()
-</script>
+Structure :
 
-<template>
-  <pre>{{ articles }}</pre>
-</template>
+```
+services/articles/
+  articles.ts
+  articles.class.ts
+  articles.schema.ts
+  articles.shared.ts
 ```
 
 ---
 
-## 8️⃣ Authentication example
+## 9. Démarrage et tests REST
+
+```bash
+bun run dev
+```
 
-Create a user:
+### 9.1 Création d’un utilisateur
 
 ```bash
 curl -X POST http://localhost:3000/feathers/users \
@@ -359,7 +195,7 @@ curl -X POST http://localhost:3000/feathers/users \
   -d '{"userId":"demo","password":"demo123"}'
 ```
 
-Authenticate:
+### 9.2 Authentification
 
 ```bash
 curl -X POST http://localhost:3000/feathers/authentication \
@@ -367,7 +203,7 @@ curl -X POST http://localhost:3000/feathers/authentication \
   -d '{"strategy":"local","userId":"demo","password":"demo123"}'
 ```
 
-Use JWT:
+### 9.3 Accès à un service protégé
 
 ```bash
 curl http://localhost:3000/feathers/articles \
@@ -376,51 +212,101 @@ curl http://localhost:3000/feathers/articles \
 
 ---
 
-## 9️⃣ Swagger (legacy) – complete example
+## 10. Swagger legacy (optionnel)
 
-Enable Swagger:
+### 10.1 Activer Swagger
 
 ```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  feathers: {
-    swagger: true,
-  },
-})
+feathers: {
+  swagger: true,
+}
 ```
 
-Access:
+### 10.2 Accès
 
-- UI: http://localhost:3000/feathers/docs/
-- Spec: http://localhost:3000/feathers/swagger.json
+* UI :
+  `http://localhost:3000/feathers/docs/`
+* Spec :
+  `http://localhost:3000/feathers/swagger.json`
+
+### ⚠️ Important
+
+Dans l’UI Swagger, la spec doit être définie manuellement à :
+
+```
+../swagger.json
+```
 
-⚠️ In Swagger UI, **replace `/swagger.json` with `../swagger.json`**.
+(C’est un comportement connu et assumé du module.)
 
 ---
 
-## 🔟 Project layout recap
+## 11. Plugins serveur Feathers (seed, hooks globaux)
 
+### Exemple : `server/feathers/dummy.ts`
+
+```ts
+import { defineFeathersServerPlugin } from 'nuxt-feathers-zod/server'
+
+export default defineFeathersServerPlugin((app) => {
+  app.hooks({
+    setup: [
+      async (context, next) => {
+        await context.app.service('users').create({
+          userId: 'admin',
+          password: 'admin123',
+        })
+        await next()
+      },
+    ],
+  })
+})
 ```
-my-nuxt-feathers-app/
-├─ app/
-├─ server/
-├─ services/
-│  └─ articles/
-├─ nuxt.config.ts
-└─ package.json
-```
+
+➡️ Ces fichiers sont des **plugins Feathers**, pas des services.
 
 ---
 
-## 🧠 Credits
+## 12. Erreurs courantes et causes réelles
+
+### ❌ `Services typeExports []`
+
+Causes :
+
+* `servicesDirs` incorrect
+* services créés manuellement
+* fichiers mal nommés (`users.ts` manquant)
+
+### ❌ `Entity class User not found in services imports`
+
+Cause exacte :
+
+* le service `users` n’existe pas ou n’a pas été généré via la CLI
+
+✅ Solution universelle :
+
+```bash
+bunx nuxt-feathers-zod add service users
+```
+
+---
 
-Inspired by:
+## 13. Bonnes pratiques figées
 
-- https://github.com/GaborTorma/feathers-nitro-adapter
-- FeathersJS v5 (Dove)
+* ✅ **Toujours** générer les services avec la CLI
+* ✅ `services/<name>/<name>.ts` obligatoire
+* ✅ Zod-first (`*.schema.ts`)
+* ❌ Pas de création manuelle
+* ❌ Pas de renommage arbitraire de `User`
+* ❌ Pas de déplacement hors `servicesDirs`
 
 ---
 
-## ✅ Status
+## 14. Résumé express (checklist)
 
-**Stable – reference version frozen**
+1. `bunx nuxi init`
+2. `bun add nuxt-feathers-zod feathers-pinia`
+3. `servicesDirs: ['services']`
+4. `bunx nuxt-feathers-zod add service users`
+5. `bunx nuxt-feathers-zod add service <business>`
+6. `bun run dev`

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^4.0.0"
   },
-  "version": "0.2.3",
+  "version": "0.2.5",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -75,7 +75,7 @@ const module$1 = defineNuxtModule({
       const require = createRequire(import.meta.url);
       try {
         require.resolve("feathers-swagger", { paths: [nuxt.options.rootDir] });
-      } catch {
+      } catch (e) {
         consola.warn(
           "feathers.swagger is enabled but 'feathers-swagger' could not be resolved from this Nuxt project. Install it in your app (root) dependencies: bun add feathers-swagger swagger-ui-dist"
         );
@@ -111,6 +111,12 @@ const module$1 = defineNuxtModule({
           addImports({ from: resolver.resolve("./runtime/stores/auth"), name: "useAuthStore" });
           addPlugin({ order: 1, src: resolver.resolve("./runtime/plugins/feathers-auth") });
         }
+        if (resolvedOptions.keycloak) {
+          addPlugin({ order: 1, src: resolver.resolve("./runtime/plugins/keycloak-sso"), mode: "client" });
+        } else if (resolvedOptions.auth) {
+          addImports({ from: resolver.resolve("./runtime/stores/auth"), name: "useAuthStore" });
+          addPlugin({ order: 1, src: resolver.resolve("./runtime/plugins/feathers-auth") });
+        }
       }
       let clientPluginDst;
       for (const clientTemplate of getClientTemplates(resolvedOptions, resolver)) {
@@ -118,7 +124,7 @@ const module$1 = defineNuxtModule({
         if (clientTemplate.filename?.endsWith("client/plugin.ts") || clientTemplate.filename?.endsWith("client/plugin"))
           clientPluginDst = tpl.dst;
       }
-      addPlugin({ order: 0, src: clientPluginDst ?? resolver.resolve(resolvedOptions.templateDir, "client/plugin.ts"), mode: "client" });
+      addPlugin({ order: 0, src: clientPluginDst ?? resolver.resolve(resolvedOptions.templateDir, "client/plugin.ts") });
     }
     nuxt.hook("mcp:setup", ({ mcp }) => {
       mcp.tool("get-feathers-config", "Get the Feathers config", {}, async () => {

package/dist/runtime/composables/pinia.d.ts

@@ -1 +1 @@
-export { createPiniaClient, defineGetters, defineSetters, defineValues, useAuth, useBackup, useDataStore, useInstanceDefaults, useServiceInstance, } from 'feathers-pinia';
+export { createPiniaClient, defineGetters, defineSetters, defineValues, useAuth as usePiniaAuth, useBackup, useDataStore, useInstanceDefaults, useServiceInstance, } from 'feathers-pinia';

package/dist/runtime/composables/pinia.js

@@ -3,7 +3,7 @@ export {
   defineGetters,
   defineSetters,
   defineValues,
-  useAuth,
+  useAuth as usePiniaAuth,
   useBackup,
   useDataStore,
   useInstanceDefaults,

package/dist/runtime/composables/useAuth.d.ts

@@ -0,0 +1,13 @@
+type AuthProvider = 'keycloak' | 'local' | 'none';
+export declare function useAuth(): {
+    provider: import("vue").ComputedRef<AuthProvider>;
+    ready: import("vue").Ref<boolean, boolean>;
+    isAuthenticated: import("vue").ComputedRef<boolean>;
+    user: import("vue").ComputedRef<any>;
+    permissions: import("vue").ComputedRef<any>;
+    token: import("vue").ComputedRef<string | null>;
+    init: () => Promise<void>;
+    login: (options?: any) => Promise<any>;
+    logout: (options?: any) => Promise<any>;
+};
+export {};

package/dist/runtime/composables/useAuth.js

@@ -0,0 +1,99 @@
+import { useNuxtApp, useRuntimeConfig } from "#imports";
+import { computed, ref } from "vue";
+import { useAuthStore } from "../stores/auth.js";
+export function useAuth() {
+  const nuxtApp = useNuxtApp();
+  const rc = useRuntimeConfig();
+  const pub = rc.public;
+  const provider = computed(() => {
+    if (pub?._feathers?.keycloak)
+      return "keycloak";
+    if (pub?._feathers?.auth)
+      return "local";
+    return "none";
+  });
+  const ready = ref(false);
+  const keycloak = computed(() => nuxtApp.$keycloak);
+  const authStore = computed(() => {
+    try {
+      return useAuthStore();
+    } catch (e) {
+      return null;
+    }
+  });
+  const isAuthenticated = computed(() => {
+    if (provider.value === "keycloak")
+      return Boolean(keycloak.value?.authenticated);
+    if (provider.value === "local")
+      return Boolean(authStore.value?.authenticated || authStore.value?.isAuthenticated);
+    return false;
+  });
+  const user = computed(() => {
+    if (provider.value === "keycloak")
+      return keycloak.value?.user ?? null;
+    if (provider.value === "local")
+      return authStore.value?.user ?? null;
+    return null;
+  });
+  const permissions = computed(() => {
+    if (provider.value === "keycloak")
+      return keycloak.value?.permissions ?? [];
+    return [];
+  });
+  const token = computed(() => {
+    if (provider.value === "keycloak")
+      return keycloak.value?.token?.() ?? null;
+    if (provider.value === "local")
+      return authStore.value?.accessToken ?? null;
+    return null;
+  });
+  async function init() {
+    if (import.meta.server)
+      return;
+    if (ready.value) {
+      if (provider.value !== "keycloak")
+        return;
+      if (!isAuthenticated.value)
+        return;
+      if (user.value)
+        return;
+    }
+    if (provider.value === "keycloak") {
+      const kc = keycloak.value;
+      if (kc?.authenticated && typeof kc.whoami === "function") {
+        await kc.whoami().catch(() => null);
+      }
+    }
+    if (provider.value === "local") {
+      const s = authStore.value;
+      if (s?.restore) {
+        await s.restore().catch(() => {
+        });
+      }
+    }
+    ready.value = true;
+  }
+  async function login(options) {
+    if (provider.value === "keycloak")
+      return keycloak.value?.login?.(options);
+    if (provider.value === "local")
+      return authStore.value?.login?.(options);
+  }
+  async function logout(options) {
+    if (provider.value === "keycloak")
+      return keycloak.value?.logout?.(options);
+    if (provider.value === "local")
+      return authStore.value?.logout?.(options);
+  }
+  return {
+    provider,
+    ready,
+    isAuthenticated,
+    user,
+    permissions,
+    token,
+    init,
+    login,
+    logout
+  };
+}

package/dist/runtime/options/index.d.ts

@@ -3,6 +3,7 @@ import type { AuthOptions, PublicAuthOptions, ResolvedAuthOptions, ResolvedAuthO
 import type { ClientOptions, ResolvedClientOptionsOrDisabled } from './client/index.js';
 import type { PiniaOptions } from './client/pinia.js';
 import type { DataBaseOptions, ResolvedDataBaseOptions } from './database/index.js';
+import type { KeycloakOptions, ResolvedKeycloakOptions, ResolvedKeycloakOptionsOrDisabled } from './keycloak.js';
 import type { ResolvedServerOptions, ServerOptions } from './server.js';
 import type { ServicesDir, ServicesDirs } from './services.js';
 import type { ResolvedSwaggerOptionsOrDisabled, SwaggerOptionsOrDisabled } from './swagger.js';
@@ -14,6 +15,7 @@ export interface ModuleOptions {
     servicesDirs: ServicesDir | ServicesDirs;
     server: ServerOptions;
     auth: AuthOptions | boolean;
+    keycloak?: KeycloakOptions | boolean;
     client: ClientOptions | boolean;
     validator: ValidatorOptions;
     loadFeathersConfig: boolean;
@@ -26,6 +28,7 @@ export interface ResolvedOptions {
     servicesDirs: ServicesDirs;
     server: ResolvedServerOptions;
     auth: ResolvedAuthOptionsOrDisabled;
+    keycloak: ResolvedKeycloakOptionsOrDisabled;
     client: ResolvedClientOptionsOrDisabled;
     validator: ResolvedValidatorOptions;
     loadFeathersConfig: boolean;
@@ -33,11 +36,19 @@ export interface ResolvedOptions {
 }
 export interface FeathersRuntimeConfig {
     auth?: ResolvedAuthOptions;
+    keycloak?: ResolvedKeycloakOptions;
 }
 export interface FeathersPublicRuntimeConfig {
     transports: ResolvedTransportsOptions;
     auth?: PublicAuthOptions;
     pinia?: PiniaOptions;
+    keycloak?: {
+        serverUrl: string;
+        realm: string;
+        clientId: string;
+        authServicePath: string;
+        onLoad: 'check-sso' | 'login-required';
+    };
 }
 export type ModuleConfig = Partial<Omit<ModuleOptions, 'auth'> & {
     auth: Omit<AuthOptions, 'entityImport'> | boolean;

package/dist/runtime/options/index.js

@@ -3,6 +3,7 @@ import { getServicesImports } from "../services.js";
 import { resolveAuthOptions } from "./authentication/index.js";
 import { resolveClientOptions } from "./client/index.js";
 import { resolveDataBaseOptions } from "./database/index.js";
+import { resolveKeycloakOptions } from "./keycloak.js";
 import { resolveServerOptions } from "./server.js";
 import { resolveServicesDirs } from "./services.js";
 import { resolveSwaggerOptions } from "./swagger.js";
@@ -20,7 +21,8 @@ export async function resolveOptions(options, nuxt) {
   const validator = resolveValidatorOptions(options.validator);
   const swagger = resolveSwaggerOptions(options.swagger, transports);
   const servicesImports = await getServicesImports(servicesDirs);
-  const auth = resolveAuthOptions(options.auth, !!client, servicesImports, appDir);
+  const keycloak = resolveKeycloakOptions(options.keycloak);
+  const auth = keycloak ? false : resolveAuthOptions(options.auth, !!client, servicesImports, appDir);
   const loadFeathersConfig = options.loadFeathersConfig;
   const resolvedOptions = {
     templateDir,
@@ -31,6 +33,7 @@ export async function resolveOptions(options, nuxt) {
     client,
     validator,
     auth,
+    keycloak,
     loadFeathersConfig,
     swagger
   };
@@ -42,6 +45,11 @@ export function resolveRuntimeConfig(options) {
   if (options.auth) {
     runtimeConfig.auth = options.auth;
   }
+  if (options.keycloak) {
+    runtimeConfig.keycloak = {
+      authServicePath: options.keycloak.authServicePath
+    };
+  }
   return runtimeConfig;
 }
 export function resolvePublicRuntimeConfig(options) {
@@ -62,5 +70,14 @@ export function resolvePublicRuntimeConfig(options) {
   if (client?.pinia) {
     publicRuntimeConfig.pinia = client.pinia;
   }
+  if (options.keycloak) {
+    publicRuntimeConfig.keycloak = {
+      serverUrl: options.keycloak.serverUrl,
+      realm: options.keycloak.realm,
+      clientId: options.keycloak.clientId,
+      authServicePath: options.keycloak.authServicePath,
+      onLoad: options.keycloak.onLoad
+    };
+  }
   return publicRuntimeConfig;
 }

package/dist/runtime/options/keycloak.d.ts

@@ -0,0 +1,41 @@
+export interface KeycloakOptions {
+    /**
+     * Keycloak base URL, e.g. https://sso.example.com
+     */
+    serverUrl: string;
+    realm: string;
+    clientId: string;
+    /**
+     * Keycloak init onLoad mode (client-side).
+     * - 'check-sso': do not force redirect, just check existing SSO session (recommended for Option A)
+     * - 'login-required': force login redirect if not authenticated
+     */
+    onLoad?: 'check-sso' | 'login-required';
+    /**
+     * Optional: client secret (only needed for UMA permissions flow)
+     */
+    secret?: string;
+    /**
+     * Optional: override issuer/audience checks.
+     * If omitted, issuer defaults to `${serverUrl}/realms/${realm}`
+     * and audience defaults to clientId.
+     */
+    issuer?: string;
+    audience?: string | string[];
+    /**
+     * Map Keycloak subject (`sub`) to a Feathers users service field.
+     */
+    userService?: string;
+    serviceIdField?: string;
+    /**
+     * Path for the bridge service (avoid '/auth' collisions).
+     */
+    authServicePath?: string;
+    /**
+     * Enable UMA permissions (requires secret).
+     */
+    permissions?: boolean;
+}
+export type ResolvedKeycloakOptions = Required<Pick<KeycloakOptions, 'serverUrl' | 'realm' | 'clientId' | 'userService' | 'serviceIdField' | 'authServicePath' | 'permissions' | 'onLoad'>> & Omit<KeycloakOptions, 'userService' | 'serviceIdField' | 'authServicePath' | 'permissions' | 'onLoad'>;
+export type ResolvedKeycloakOptionsOrDisabled = ResolvedKeycloakOptions | false;
+export declare function resolveKeycloakOptions(keycloak: KeycloakOptions | boolean | undefined): ResolvedKeycloakOptionsOrDisabled;

package/dist/runtime/options/keycloak.js

@@ -0,0 +1,19 @@
+export function resolveKeycloakOptions(keycloak) {
+  if (!keycloak)
+    return false;
+  if (keycloak === true)
+    throw new Error("[nuxt-feathers-zod] feathers.keycloak=true is not supported; please provide an object config.");
+  return {
+    serverUrl: keycloak.serverUrl,
+    realm: keycloak.realm,
+    clientId: keycloak.clientId,
+    issuer: keycloak.issuer,
+    audience: keycloak.audience,
+    secret: keycloak.secret,
+    userService: keycloak.userService || "users",
+    serviceIdField: keycloak.serviceIdField || "keycloakId",
+    authServicePath: keycloak.authServicePath || "/_keycloak",
+    permissions: !!keycloak.permissions,
+    onLoad: keycloak.onLoad || "check-sso"
+  };
+}

package/dist/runtime/plugins/feathers-auth.js

@@ -8,6 +8,6 @@ export default defineNuxtPlugin(async (nuxtApp) => {
   const auth = useAuthStore();
   try {
     await auth.reAuthenticate();
-  } catch {
+  } catch (e) {
   }
 });

package/dist/runtime/plugins/keycloak-sso.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugins/keycloak-sso.js

@@ -0,0 +1,147 @@
+import { defineNuxtPlugin, useRuntimeConfig } from "#app";
+import Keycloak from "keycloak-js";
+export default defineNuxtPlugin(async (nuxtApp) => {
+  if (import.meta.server)
+    return;
+  const rc = useRuntimeConfig();
+  const pub = rc.public;
+  const kcPub = pub?._feathers?.keycloak ?? {};
+  const serverUrl = kcPub.serverUrl ?? pub.KC_URL;
+  const realm = kcPub.realm ?? pub.KC_REALM;
+  const clientId = kcPub.clientId ?? pub.KC_CLIENT_ID;
+  if (!serverUrl || !realm || !clientId) {
+    console.warn("[nuxt-feathers-zod][keycloak-sso] Missing Keycloak config. Expected feathers.keycloak.{serverUrl,realm,clientId} to be exposed in runtimeConfig.public._feathers.keycloak (or legacy KC_URL/KC_REALM/KC_CLIENT_ID).");
+    nuxtApp.provide("keycloak", {
+      instance: null,
+      authenticated: false,
+      token: () => void 0,
+      login: async () => {
+      },
+      logout: async () => {
+      },
+      updateToken: async () => false,
+      whoami: async () => null,
+      user: void 0,
+      permissions: []
+    });
+    return;
+  }
+  const keycloak = new Keycloak({
+    url: String(serverUrl),
+    realm: String(realm),
+    clientId: String(clientId)
+  });
+  const onLoad = pub?._feathers?.keycloak?.onLoad === "login-required" ? "login-required" : "check-sso";
+  const initResult = await keycloak.init({
+    onLoad,
+    checkLoginIframe: false,
+    silentCheckSsoRedirectUri: `${window.location.origin}/silent-check-sso.html`
+  }).catch(() => ({ authenticated: false }));
+  const authenticated = keycloak.authenticated === true && initResult?.authenticated !== false;
+  const userid = keycloak?.tokenParsed?.preferred_username;
+  const authServicePath = pub?._feathers?.keycloak?.authServicePath || "/_keycloak";
+  let refreshTimer;
+  let lastWhoamiAt = 0;
+  async function safeWhoami(reason) {
+    const now = Date.now();
+    if (now - lastWhoamiAt < 1e4)
+      return;
+    lastWhoamiAt = now;
+    try {
+      await whoami();
+    } catch (e) {
+      console.warn("[nuxt-feathers-zod][keycloak-sso] whoami refresh failed:", reason, e);
+    }
+  }
+  function startTokenRefreshLoop() {
+    if (refreshTimer)
+      window.clearInterval(refreshTimer);
+    const minValidity = 60;
+    const intervalMs = 3e4;
+    refreshTimer = window.setInterval(async () => {
+      try {
+        const refreshed = await keycloak.updateToken(minValidity);
+        if (refreshed)
+          await safeWhoami("updateToken(refreshed)");
+      } catch (e) {
+        console.warn("[nuxt-feathers-zod][keycloak-sso] updateToken failed:", e);
+      }
+    }, intervalMs);
+    nuxtApp.hook("app:beforeUnmount", () => {
+      if (refreshTimer)
+        window.clearInterval(refreshTimer);
+    });
+  }
+  const provided = {
+    instance: keycloak,
+    authenticated,
+    userid,
+    tokenParsed: keycloak.tokenParsed,
+    token: () => keycloak.token,
+    login: async (opts) => {
+      await keycloak.login(opts);
+    },
+    logout: async (opts) => {
+      await keycloak.logout(opts);
+    },
+    updateToken: async (minValidity = 30) => {
+      const refreshed = await keycloak.updateToken(minValidity);
+      if (refreshed)
+        await safeWhoami("provided.updateToken(refreshed)");
+      return refreshed;
+    },
+    // Fallback user (will be replaced by whoami() when $api is ready)
+    user: keycloak.tokenParsed ? { ...keycloak.tokenParsed, userid } : userid ? { userid } : void 0,
+    permissions: [],
+    whoami: async () => null
+  };
+  async function whoami() {
+    if (!provided.authenticated)
+      return null;
+    if (!("$api" in nuxtApp) || !nuxtApp.$api)
+      return null;
+    const token = keycloak.token;
+    if (!token)
+      return null;
+    try {
+      const res = await nuxtApp.$api.service(authServicePath).create({ access_token: token });
+      provided.user = res?.user;
+      provided.permissions = res?.permissions || [];
+      return res;
+    } catch (e) {
+      return null;
+    }
+  }
+  if ("$api" in nuxtApp && nuxtApp.$api) {
+    nuxtApp.$api.hooks({
+      before: [
+        async (ctx) => {
+          await keycloak.updateToken(30).catch(() => {
+          });
+          const t = keycloak.token;
+          if (!t)
+            return ctx;
+          ctx.params ||= {};
+          ctx.params.headers ||= {};
+          ctx.params.headers.Authorization = `Bearer ${t}`;
+          return ctx;
+        }
+      ]
+    });
+  }
+  provided.whoami = whoami;
+  nuxtApp.provide("keycloak", provided);
+  if (provided.authenticated) {
+    await safeWhoami("post-init");
+    keycloak.onTokenExpired = async () => {
+      try {
+        const refreshed = await keycloak.updateToken(60);
+        if (refreshed)
+          await safeWhoami("onTokenExpired(refreshed)");
+      } catch (e) {
+        console.warn("[nuxt-feathers-zod][keycloak-sso] token expired and refresh failed:", e);
+      }
+    };
+    startTokenRefreshLoop();
+  }
+});

package/dist/runtime/stores/auth.js

@@ -25,7 +25,7 @@ export const useAuthStore = defineStore("auth", () => {
       state.accessToken = result.accessToken;
       state.user = result.user;
       state.authenticated = true;
-    } catch {
+    } catch (e) {
       logout();
     }
   }

package/dist/runtime/templates/server/index.js

@@ -1,4 +1,5 @@
 import { getServerAuthContents } from "./authentication.js";
+import { getServerKeycloakContents } from "./keycloak.js";
 import { getServerMongodbContents } from "./mongodb.js";
 import { getServerPluginContents } from "./plugin.js";
 import { getServerContents } from "./server.js";
@@ -29,5 +30,12 @@ export function getServerTemplates(options) {
       write: true
     });
   }
+  if (options.keycloak) {
+    serverTemplates.push({
+      filename: "feathers/server/keycloak.ts",
+      getContents: getServerKeycloakContents(options),
+      write: true
+    });
+  }
   return serverTemplates;
 }

package/dist/runtime/templates/server/keycloak.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedOptions } from '../../../runtime/options/index.js';
+export declare function getServerKeycloakContents(options: ResolvedOptions): () => Promise<string>;

package/dist/runtime/templates/server/keycloak.js

@@ -0,0 +1,96 @@
+export function getServerKeycloakContents(options) {
+  return async () => {
+    return `// ! Generated by nuxt-feathers-zod - do not change manually
+import type { HookContext, Application } from '@feathersjs/feathers'
+import { createRemoteJWKSet, jwtVerify } from 'jose'
+
+export type KeycloakConfig = {
+  serverUrl: string
+  realm: string
+  clientId: string
+  secret?: string
+  userService: string
+  serviceIdField: string
+  authServicePath: string
+  permissions?: boolean
+}
+
+function getBearer(headers?: Record<string, any>) {
+  const auth = headers?.authorization || headers?.Authorization
+  if (!auth || typeof auth !== 'string') return null
+  if (!auth.startsWith('Bearer ')) return null
+  return auth.slice(7)
+}
+
+async function safeResolveUser(app: Application, cfg: KeycloakConfig, payload: any) {
+  const sub = payload?.sub as string | undefined
+  if (!sub) return payload
+
+  try {
+    const users = app.service(cfg.userService)
+    const found = await users.find({ query: { [cfg.serviceIdField]: sub }, paginate: false } as any)
+    const first = Array.isArray(found) ? found[0] : (found?.data?.[0] ?? null)
+    if (first) return first
+
+    // Minimal create data to avoid schema conflicts
+    const created = await users.create({ [cfg.serviceIdField]: sub } as any)
+    return created
+  }
+  catch (e) {
+    // Fallback: no DB user service or schema mismatch -> return token payload as user
+    return { [cfg.serviceIdField]: sub, ...payload }
+  }
+}
+
+export function keycloakAuthorizationHook(app: Application, cfg: KeycloakConfig) {
+  const issuer = \`\${cfg.serverUrl}/realms/\${cfg.realm}\`
+  const jwks = createRemoteJWKSet(new URL(\`\${issuer}/protocol/openid-connect/certs\`))
+
+  return async (context: HookContext) => {
+    // Only external calls
+    if (!context.params?.provider) return context
+
+    const token = getBearer(context.params.headers as any)
+    if (!token) return context
+
+    const { payload } = await jwtVerify(token, jwks, {
+      issuer,
+      audience: cfg.clientId,
+    })
+
+    context.params.client = payload
+    context.params.user = await safeResolveUser(app, cfg, payload)
+    context.params.permissions = []
+
+    return context
+  }
+}
+
+export function keycloakBridgeService(app: Application, cfg: KeycloakConfig) {
+  return {
+    async create(data: { access_token: string }) {
+      const fakeCtx = {
+        app,
+        params: { headers: { Authorization: \`Bearer \${data.access_token}\` }, provider: 'rest' },
+      } as unknown as HookContext
+
+      await keycloakAuthorizationHook(app, cfg)(fakeCtx)
+
+      return {
+        user: (fakeCtx.params as any).user,
+        permissions: (fakeCtx.params as any).permissions,
+      }
+    },
+
+    async patch(_: any, data: { access_token: string }) {
+      return (this as any).create(data)
+    },
+
+    async remove() {
+      return { ok: true }
+    },
+  }
+}
+`;
+  };
+}

package/dist/runtime/templates/server/plugin.js

@@ -23,6 +23,8 @@ export function getServerPluginContents(options) {
     const mongo = !!options.database?.mongo;
     const authStrategies = options?.auth?.authStrategies;
     const auth = (authStrategies || []).length > 0;
+    const keycloakEnabled = !!options.keycloak;
+    const keycloak = options.keycloak;
     const authService = options?.auth?.service;
     const restPath = transports?.rest?.path;
     const websocketPath = transports?.websocket?.path;
@@ -65,10 +67,27 @@ export function getServerPluginContents(options) {
     },
     ui: swagger.swaggerUI({ docsPath: '${docsPath}' }),
   }))
+` : "";
+    const keycloakInitBlock = keycloakEnabled ? `  // Init Keycloak-only SSO (global hook + bridge service)
+  const keycloakConfig = ${JSON.stringify({
+      serverUrl: keycloak.serverUrl,
+      realm: keycloak.realm,
+      clientId: keycloak.clientId,
+      issuer: keycloak.issuer || `${keycloak.serverUrl.replace(/\/$/, "")}/realms/${keycloak.realm}`,
+      audience: keycloak.audience || keycloak.clientId,
+      secret: keycloak.secret,
+      userService: keycloak.userService || "users",
+      serviceIdField: keycloak.serviceIdField || "keycloakId",
+      authServicePath: keycloak.authServicePath || "/_keycloak",
+      permissions: !!keycloak.permissions
+    })}
+  app.hooks({ before: [keycloakAuthorizationHook(app, keycloakConfig)] })
+  app.use(keycloakConfig.authServicePath, keycloakBridgeService(app, keycloakConfig) as any)
 ` : "";
     return `// ! Generated by nuxt-feathers-zod - do not change manually
 import type { NitroApp } from 'nitropack'
 import type { Application } from './server.js'
+${put(keycloakEnabled, `import { keycloakAuthorizationHook, keycloakBridgeService } from './keycloak.js'`)}
 ${put(options.loadFeathersConfig, `import configuration from '@feathersjs/configuration'`)}
 import { feathers } from '@feathersjs/feathers'
 ${puts([
@@ -94,6 +113,7 @@ ${put(options.loadFeathersConfig, `
   app.configure(configuration())
 `)}
 ${put(swaggerEnabled, swaggerInitBlock)}
+${put(keycloakEnabled, keycloakInitBlock)}
   // Add nitroApp to feathers app
   app.nitroApp = nitroApp;
 ${put(rest, `${put(koa, `

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-feathers-zod",
   "type": "module",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "packageManager": "bun@1.3.6",
   "description": "Feathers API integration for Nuxt",
   "author": "Herve de CHAVIGNY",
@@ -57,7 +57,10 @@
     "release": "bunx release-it",
     "release:patch": "bunx release-it patch",
     "release:minor": "bunx release-it minor",
-    "release:major": "bunx release-it major"
+    "release:major": "bunx release-it major",
+    "docs:dev": "cd docs && bun install && bunx vitepress dev . --host",
+    "docs:build": "cd docs && bun install && bunx vitepress build .",
+    "docs:preview": "cd docs && bun install && bunx vitepress preview ."
   },
   "peerDependencies": {
     "nuxt": "^4.0.0"
@@ -85,6 +88,8 @@
     "consola": "latest",
     "defu": "latest",
     "feathers-pinia": "latest",
+    "jose": "^5.10.0",
+    "keycloak-js": "^24.0.5",
     "mongodb": "^6.21.0",
     "pinia": "latest",
     "socket.io-client": "latest",
@@ -105,7 +110,6 @@
     "dotenv-cli": "latest",
     "eslint": "^9.39.2",
     "nuxt": "^4.3.0",
-    "nuxt-mcp": "latest",
     "release-it": "latest",
     "typescript": "latest",
     "vitest": "latest",

package/src/cli/index.ts

@@ -261,7 +261,7 @@ async function ensureFeathersSwaggerSupport(projectRoot: string, io: { dry: bool
       )
     }
   }
-  catch {
+  catch (e) {
     // ignore
   }
 }
@@ -319,7 +319,7 @@ function relativeToCwd(p: string) {
   try {
     return p.replace(`${resolve(process.cwd())}/`, '')
   }
-  catch {
+  catch (e) {
     return p
   }
 }