nuxt-bearer-auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enoch Tetteh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# Nuxt Bearer Auth
+
+Reusable Nuxt authentication for APIs that issue bearer tokens. It is designed for Laravel-style auth responses by default, but it is not Laravel-specific: any backend that returns a bearer token and a user object can work through response path mapping.
+
+## Features
+
+- Nuxt module install experience
+- Redis-backed server sessions
+- Secure HTTP-only session cookie
+- `nuxt-csurf` integration
+- Generic bearer-token API adapter
+- Email/Mobile and password login
+- Social login
+- Registration
+- OTP verification and resend
+- Forgot/reset password
+- `/me` session hydration
+- Token refresh route
+- Logout
+- Active session listing
+- Session revocation
+- SSR auth hydration
+- Global route middleware
+- `useBearerAuth()` composable
+- `useAuth()` alias for convenience
+
+## Install
+
+```bash
+npm install nuxt-bearer-auth redis nuxt-csurf
+```
+
+```ts
+export default defineNuxtConfig({
+  modules: ["nuxt-bearer-auth"],
+
+  bearerAuth: {
+    apiBaseUrl: process.env.API_BASE_URL,
+    redisUrl: process.env.REDIS_URL,
+
+    redirects: {
+      login: "/login",
+      authenticated: "/dashboard",
+      logout: "/",
+      unauthorized: "/auth/not-allowed",
+    },
+
+    routes: {
+      public: ["/", "/login", "/forgot-password", "/reset-password"],
+      authPages: ["/login", "/forgot-password", "/reset-password"],
+    },
+  },
+});
+```
+
+## Environment
+
+```bash
+API_BASE_URL=https://api.example.com
+REDIS_URL=redis://127.0.0.1:6379
+APP_ENV=local
+```
+
+## Default Backend Endpoints
+
+The module exposes local Nuxt endpoints under `/api/auth/*` and proxies them to your backend.
+
+| Local endpoint                          | Backend endpoint              |
+| --------------------------------------- | ----------------------------- |
+| `POST /api/auth/login`                  | `auth/login`                  |
+| `POST /api/auth/social-login`           | `auth/social-login`           |
+| `POST /api/auth/logout`                 | `auth/logout`                 |
+| `GET /api/auth/me`                      | `auth/account/me`             |
+| `POST /api/auth/refresh`                | `auth/refresh`                |
+| `POST /api/auth/forgot-password`        | `auth/forgot-password`        |
+| `POST /api/auth/reset-password`         | `auth/reset-password`         |
+| `POST /api/auth/otp-verification`       | `auth/verify-otp`             |
+| `POST /api/auth/resend-otp/:identifier` | `auth/resend-otp/:identifier` |
+| `POST /api/auth/register`               | `auth/register`               |
+
+Override any endpoint:
+
+```ts
+export default defineNuxtConfig({
+  bearerAuth: {
+    endpoints: {
+      login: "v1/session",
+      me: "v1/me",
+      socialLogin: "v1/oauth/login",
+    },
+  },
+});
+```
+
+## Backend Response Shape
+
+The default response parser supports common bearer-token responses:
+
+```json
+{
+  "success": true,
+  "message": "Login successful",
+  "data": {
+    "token": "plain-bearer-token",
+    "refresh_token": "optional-refresh-token",
+    "user": {
+      "id": 1,
+      "email": "person@example.com"
+    }
+  }
+}
+```
+
+It also checks top-level fallbacks like `token`, `access_token`, and `user`.
+
+For a different API shape, map paths:
+
+```ts
+export default defineNuxtConfig({
+  bearerAuth: {
+    responsePaths: {
+      token: ["auth.accessToken"],
+      refreshToken: ["auth.refreshToken"],
+      user: ["account"],
+      userId: ["id"],
+      message: ["message"],
+      success: ["ok"],
+    },
+  },
+});
+```
+
+## Social Login
+
+On the client:
+
+```ts
+const auth = useBearerAuth();
+
+await auth.socialLogin({
+  provider: "google",
+  jwt: googleCredential,
+});
+```
+
+Your backend should validate the provider token and return the same bearer-token response shape as normal login.
+
+## Client Usage
+
+```vue
+<script setup lang="ts">
+const auth = useBearerAuth();
+
+async function submit() {
+  await auth.login({
+    identifier: "person@example.com",
+    password: "secret",
+  });
+}
+</script>
+```
+
+`identifier` could be any string that identifies a user in your bacend. it could email, phone numder, username etc.
+
+Available composable state and methods:
+
+- `user`
+- `status`
+- `ready`
+- `error`
+- `loading`
+- `isAuthenticated`
+- `login`
+- `socialLogin`
+- `register`
+- `verifyOtp`
+- `fetchUser`
+- `refresh`
+- `logout`
+- `forgotPassword`
+- `resetPassword`
+- `resendOtp`
+- `clearAuthState`
+
+## Redis Sessions
+
+The backend token is stored server-side in Redis. The browser only receives a secure HTTP-only session id cookie. Nuxt server routes can read the hydrated session from:
+
+```ts
+event.context.auth;
+```
+
+## CSRF
+
+`nuxt-csurf` is installed by default. You can customize it:
+
+```ts
+export default defineNuxtConfig({
+  bearerAuth: {
+    csrf: {
+      enabled: true,
+      cookieKey: "my_app_csrf",
+      devCookieKey: "my_app_csrf_dev",
+      headerName: "x-csrf-token",
+    },
+  },
+});
+```
+
+To manage `nuxt-csurf` yourself:
+
+```ts
+export default defineNuxtConfig({
+  modules: ["nuxt-csurf", "nuxt-bearer-auth"],
+  bearerAuth: {
+    installCsurf: false,
+  },
+});
+```
+
+## Route Protection
+
+```ts
+export default defineNuxtConfig({
+  bearerAuth: {
+    routes: {
+      public: ["/", "/login", "/pricing"],
+      authPages: ["/login"],
+      protectedApiPrefixes: ["/api"],
+      publicApiPrefixes: [
+        "/api/auth/login",
+        "/api/auth/register",
+        "/api/_csrf",
+      ],
+    },
+  },
+});
+```
+
+Disable the global client middleware:
+
+```ts
+export default defineNuxtConfig({
+  bearerAuth: {
+    routes: {
+      middleware: false,
+    },
+  },
+});
+```
+
+## Community Direction
+
+Planned extension points:
+
+- first-party adapters for popular backend response shapes
+- optional refresh-token rotation strategies
+- role/permission hooks
+- multi-tenant active context headers
+- session analytics and device naming
+- test fixtures for module consumers
+
+## License
+
+MIT

package/dist/module.cjs

@@ -0,0 +1,5 @@
+module.exports = function(...args) {
+  return import('./module.mjs').then(m => m.default.call(this, ...args))
+}
+const _meta = module.exports.meta = require('./module.json')
+module.exports.getMeta = () => Promise.resolve(_meta)

package/dist/module.d.mts

@@ -0,0 +1,134 @@
+declare const module = defineNuxtModule({
+  meta: {
+    name: "nuxt-bearer-auth",
+    configKey: "bearerAuth",
+    compatibility: {
+      nuxt: "^3.12.0 || ^4.0.0"
+    }
+  },
+  defaults: defaultOptions,
+  async setup(moduleOptions, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const options = defu(moduleOptions, defaultOptions);
+    nuxt.options.runtimeConfig.bearerAuth = defu(
+      nuxt.options.runtimeConfig.bearerAuth,
+      {
+        apiBaseUrl: options.apiBaseUrl,
+        redisUrl: options.redisUrl,
+        sessionSecret: options.sessionSecret,
+        appEnv: options.appEnv,
+        endpoints: options.endpoints,
+        responsePaths: options.responsePaths,
+        sessionCookie: options.sessionCookie,
+        verificationRequiredActions: options.verificationRequiredActions,
+        twoFactorRequiredActions: options.twoFactorRequiredActions
+      }
+    );
+    nuxt.options.runtimeConfig.public.bearerAuth = defu(
+      nuxt.options.runtimeConfig.public.bearerAuth,
+      {
+        redirects: options.redirects,
+        routes: options.routes
+      }
+    );
+    if (options.installCsurf && options.csrf?.enabled) {
+      await installModule("nuxt-csurf", {
+        https: options.csrf.https,
+        cookieKey: options.appEnv === "local" || options.appEnv === "development" ? options.csrf.devCookieKey : options.csrf.cookieKey,
+        cookie: options.csrf.cookie,
+        methods: options.csrf.methods,
+        methodsToProtect: options.csrf.methodsToProtect,
+        encryptAlgorithm: "aes-256-cbc",
+        addCsrfTokenToEventCtx: true,
+        headerName: options.csrf.headerName
+      });
+    }
+    addImports([
+      {
+        name: "useBearerAuth",
+        from: resolver.resolve("runtime/composables/useBearerAuth")
+      },
+      {
+        name: "useBearerAuth",
+        as: "useAuth",
+        from: resolver.resolve("runtime/composables/useBearerAuth")
+      }
+    ]);
+    addPlugin(resolver.resolve("runtime/plugins/bearer-auth.server"));
+    if (options.routes?.middleware !== false) {
+      addRouteMiddleware({
+        name: "bearer-auth",
+        path: resolver.resolve("runtime/middleware/bearer-auth.global"),
+        global: true
+      });
+    }
+    addServerPlugin(resolver.resolve("runtime/server/plugins/redis"));
+    addServerHandler({
+      middleware: true,
+      handler: resolver.resolve("runtime/server/middleware/auth")
+    });
+    const prefix = options.routes?.localApiPrefix || "/api/auth";
+    addServerHandler({
+      route: `${prefix}/login`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/login.post")
+    });
+    addServerHandler({
+      route: `${prefix}/social-login`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/social-login.post")
+    });
+    addServerHandler({
+      route: `${prefix}/logout`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/logout.post")
+    });
+    addServerHandler({
+      route: `${prefix}/me`,
+      method: "get",
+      handler: resolver.resolve("runtime/server/api/auth/me.get")
+    });
+    addServerHandler({
+      route: `${prefix}/refresh`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/refresh.post")
+    });
+    addServerHandler({
+      route: `${prefix}/forgot-password`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/forgot-password.post")
+    });
+    addServerHandler({
+      route: `${prefix}/reset-password`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/reset-password.post")
+    });
+    addServerHandler({
+      route: `${prefix}/otp-verification`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/otp-verification.post")
+    });
+    addServerHandler({
+      route: `${prefix}/resend-otp/:identifier`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/resend-otp/[identifier].post")
+    });
+    addServerHandler({
+      route: `${prefix}/register`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/register.post")
+    });
+    addServerHandler({
+      route: `${prefix}/sessions`,
+      method: "get",
+      handler: resolver.resolve("runtime/server/api/auth/sessions.get")
+    });
+    addServerHandler({
+      route: `${prefix}/sessions/:id`,
+      method: "delete",
+      handler: resolver.resolve("runtime/server/api/auth/sessions/[id].delete")
+    });
+  }
+});
+
+export { module as default };

package/dist/module.d.ts

@@ -0,0 +1,134 @@
+declare const module = defineNuxtModule({
+  meta: {
+    name: "nuxt-bearer-auth",
+    configKey: "bearerAuth",
+    compatibility: {
+      nuxt: "^3.12.0 || ^4.0.0"
+    }
+  },
+  defaults: defaultOptions,
+  async setup(moduleOptions, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const options = defu(moduleOptions, defaultOptions);
+    nuxt.options.runtimeConfig.bearerAuth = defu(
+      nuxt.options.runtimeConfig.bearerAuth,
+      {
+        apiBaseUrl: options.apiBaseUrl,
+        redisUrl: options.redisUrl,
+        sessionSecret: options.sessionSecret,
+        appEnv: options.appEnv,
+        endpoints: options.endpoints,
+        responsePaths: options.responsePaths,
+        sessionCookie: options.sessionCookie,
+        verificationRequiredActions: options.verificationRequiredActions,
+        twoFactorRequiredActions: options.twoFactorRequiredActions
+      }
+    );
+    nuxt.options.runtimeConfig.public.bearerAuth = defu(
+      nuxt.options.runtimeConfig.public.bearerAuth,
+      {
+        redirects: options.redirects,
+        routes: options.routes
+      }
+    );
+    if (options.installCsurf && options.csrf?.enabled) {
+      await installModule("nuxt-csurf", {
+        https: options.csrf.https,
+        cookieKey: options.appEnv === "local" || options.appEnv === "development" ? options.csrf.devCookieKey : options.csrf.cookieKey,
+        cookie: options.csrf.cookie,
+        methods: options.csrf.methods,
+        methodsToProtect: options.csrf.methodsToProtect,
+        encryptAlgorithm: "aes-256-cbc",
+        addCsrfTokenToEventCtx: true,
+        headerName: options.csrf.headerName
+      });
+    }
+    addImports([
+      {
+        name: "useBearerAuth",
+        from: resolver.resolve("runtime/composables/useBearerAuth")
+      },
+      {
+        name: "useBearerAuth",
+        as: "useAuth",
+        from: resolver.resolve("runtime/composables/useBearerAuth")
+      }
+    ]);
+    addPlugin(resolver.resolve("runtime/plugins/bearer-auth.server"));
+    if (options.routes?.middleware !== false) {
+      addRouteMiddleware({
+        name: "bearer-auth",
+        path: resolver.resolve("runtime/middleware/bearer-auth.global"),
+        global: true
+      });
+    }
+    addServerPlugin(resolver.resolve("runtime/server/plugins/redis"));
+    addServerHandler({
+      middleware: true,
+      handler: resolver.resolve("runtime/server/middleware/auth")
+    });
+    const prefix = options.routes?.localApiPrefix || "/api/auth";
+    addServerHandler({
+      route: `${prefix}/login`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/login.post")
+    });
+    addServerHandler({
+      route: `${prefix}/social-login`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/social-login.post")
+    });
+    addServerHandler({
+      route: `${prefix}/logout`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/logout.post")
+    });
+    addServerHandler({
+      route: `${prefix}/me`,
+      method: "get",
+      handler: resolver.resolve("runtime/server/api/auth/me.get")
+    });
+    addServerHandler({
+      route: `${prefix}/refresh`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/refresh.post")
+    });
+    addServerHandler({
+      route: `${prefix}/forgot-password`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/forgot-password.post")
+    });
+    addServerHandler({
+      route: `${prefix}/reset-password`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/reset-password.post")
+    });
+    addServerHandler({
+      route: `${prefix}/otp-verification`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/otp-verification.post")
+    });
+    addServerHandler({
+      route: `${prefix}/resend-otp/:identifier`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/resend-otp/[identifier].post")
+    });
+    addServerHandler({
+      route: `${prefix}/register`,
+      method: "post",
+      handler: resolver.resolve("runtime/server/api/auth/register.post")
+    });
+    addServerHandler({
+      route: `${prefix}/sessions`,
+      method: "get",
+      handler: resolver.resolve("runtime/server/api/auth/sessions.get")
+    });
+    addServerHandler({
+      route: `${prefix}/sessions/:id`,
+      method: "delete",
+      handler: resolver.resolve("runtime/server/api/auth/sessions/[id].delete")
+    });
+  }
+});
+
+export { module as default };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-bearer-auth",
+  "configKey": "bearerAuth",
+  "compatibility": {
+    "nuxt": "^3.12.0 || ^4.0.0"
+  },
+  "version": "0.1.0",
+  "builder": {
+    "@nuxt/module-builder": "0.8.4",
+    "unbuild": "2.0.0"
+  }
+}