nuxt-auth-utils 0.0.25 → 0.1.0

package/README.md

@@ -14,12 +14,13 @@ Minimalist Authentication module for Nuxt exposing Vue composables and server ut
 
 ## Features
 
+- Support for Hybrid Rendering (SSR / CSR / SWR / Prerendering)
 - Secured & sealed cookies sessions
 - [OAuth Providers](#supported-oauth-providers)
 
 ## Requirements
 
-This module only works with SSR (server-side rendering) enabled as it uses server API routes. You cannot use this module with `nuxt generate`.
+This module only works with the Nuxt server running as it uses server API routes. This means that you cannot use this module with `nuxt generate`.
 
 ## Quick Setup
 
@@ -72,7 +73,7 @@ The following helpers are auto-imported in your `server/` directory.
 
 ```ts
 // Set a user session, note that this data is encrypted in the cookie but can be decrypted with an API call
-// Only store the data that allow you to recognize an user, but do not store sensitive data
+// Only store the data that allow you to recognize a user, but do not store sensitive data
 // Merges new data with existing data using defu()
 await setUserSession(event, {
   user: {
@@ -118,7 +119,7 @@ All helpers are exposed from the `oauth` global variable and can be used in your
 
 The pattern is `oauth.<provider>EventHandler({ onSuccess, config?, onError? })`, example: `oauth.githubEventHandler`.
 
-The helper returns an event handler that automatically redirects to the provider authorization page and then call `onSuccess` or `onError` depending on the result.
+The helper returns an event handler that automatically redirects to the provider authorization page and then calls `onSuccess` or `onError` depending on the result.
 
 The `config` can be defined directly from the `runtimeConfig` in your `nuxt.config.ts`:
 
@@ -186,7 +187,7 @@ Make sure to set the callback URL in your OAuth app settings as `<your-domain>/a
 
 ### Extend Session
 
-We leverage hooks to let you extend the session data with your own data or to log when the user clear its session.
+We leverage hooks to let you extend the session data with your own data or log when the user clears the session.
 
 ```ts
 // server/plugins/session.ts
@@ -206,6 +207,69 @@ export default defineNitroPlugin(() => {
 })
 ```
 
+## Server-Side Rendering
+
+You can make authenticated requests both from the client and the server. However, you must use `useRequestFetch()` to make authenticated requests during SSR if you are not using `useFetch()`
+
+```vue
+<script setup lang="ts">
+// When using useAsyncData
+const { data } = await useAsyncData('team', () => useRequestFetch()('/api/protected-endpoint'))
+
+// useFetch will automatically use useRequestFetch during SSR
+const { data } = await useFetch('/api/protected-endpoint')
+</script>
+```
+
+> There's [an open issue](https://github.com/nuxt/nuxt/issues/24813) to include credentials in `$fetch` in Nuxt.
+
+## Hybrid Rendering
+
+When using [Nuxt `routeRules`](https://nuxt.com/docs/guide/concepts/rendering#hybrid-rendering) to prerender or cache your pages, Nuxt Auth Utils will not fetch the user session during prerendering but instead fetch it on the client-side (after hydration).
+
+This is because the user session is stored in a secure cookie and cannot be accessed during prerendering.
+
+**This means that you should not rely on the user session during prerendering.**
+
+### `<AuthState>` component
+
+You can use the `<AuthState>` component to safely display auth-related data in your components without worrying about the rendering mode.
+
+One common use case if the Login button in the header:
+
+```vue
+<template>
+  <header>
+    <AuthState v-slot="{ loggedIn, clear }">
+      <button v-if="loggedIn" @click="clear">Logout</button>
+      <NuxtLink v-else to="/login">Login</NuxtLink>
+    </AuthState>
+  </header>
+</template>
+```
+
+If the page is cached or prerendered, nothing will be rendered until the user session is fetched on the client-side.
+
+You can use the `placeholder` slot to show a placeholder on server-side and while the user session is being fetched on client-side for the prerendered pages:
+
+```vue
+<template>
+  <header>
+    <AuthState>
+      <template #default="{ loggedIn, clear }">
+        <button v-if="loggedIn" @click="clear">Logout</button>
+        <NuxtLink v-else to="/login">Login</NuxtLink>
+      </template>
+      <template #placeholder>
+        <button disabled>Loading...</button>
+      </template>
+    </AuthState>
+  </header>
+</template>
+```
+
+If you are caching your routes with `routeRules`, please make sure to use [`nitro-nightly`](https://nitro.unjs.io/guide/nightly) or Nitro >= `2.10.0` to support the client-side fetching of the user session.
+
 ## Configuration
 
 We leverage `runtimeConfig.session` to give the defaults option to [h3 `useSession`](https://h3.unjs.io/examples/handle-session).
@@ -237,6 +301,10 @@ Our defaults are:
 
 Checkout the [`SessionConfig`](https://github.com/unjs/h3/blob/c04c458810e34eb15c1647e1369e7d7ef19f567d/src/utils/session.ts#L20) for all options.
 
+## More
+
+- [nuxt-authorization](https://github.com/barbapapazes/nuxt-authorization): Authorization module for managing permissions inside a Nuxt app, compatible with `nuxt-auth-utils`
+
 ## Development
 
 ```bash

package/dist/module.json

@@ -1,9 +1,9 @@
 {
   "name": "auth-utils",
   "configKey": "auth",
-  "version": "0.0.25",
+  "version": "0.1.0",
   "builder": {
-    "@nuxt/module-builder": "0.6.0",
+    "@nuxt/module-builder": "0.7.1",
     "unbuild": "2.0.0"
   }
 }

package/dist/module.mjs

@@ -1,5 +1,5 @@
 import { readFile, writeFile } from 'node:fs/promises';
-import { defineNuxtModule, createResolver, addImportsDir, addPlugin, addServerPlugin, addServerHandler } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addComponentsDir, addImportsDir, addPlugin, addServerPlugin, addServerImportsDir, addServerHandler } from '@nuxt/kit';
 import { join } from 'pathe';
 import { defu } from 'defu';
 import { randomUUID } from 'uncrypto';
@@ -14,30 +14,12 @@ const module = defineNuxtModule({
   async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
     nuxt.options.alias["#auth-utils"] = resolver.resolve("./runtime/types/index");
-    addImportsDir(resolver.resolve("./runtime/composables"));
-    addPlugin(resolver.resolve("./runtime/plugins/session.server"));
-    if (nuxt.options.nitro.imports !== false) {
-      nuxt.options.nitro.imports = defu(nuxt.options.nitro.imports, {
-        presets: [
-          {
-            from: resolver.resolve("./runtime/server/utils/oauth"),
-            imports: ["oauth"]
-          },
-          {
-            from: resolver.resolve("./runtime/server/utils/session"),
-            imports: [
-              "sessionHooks",
-              "getUserSession",
-              "setUserSession",
-              "replaceUserSession",
-              "clearUserSession",
-              "requireUserSession"
-            ]
-          }
-        ]
-      });
-    }
+    addComponentsDir({ path: resolver.resolve("./runtime/app/components") });
+    addImportsDir(resolver.resolve("./runtime/app/composables"));
+    addPlugin(resolver.resolve("./runtime/app/plugins/session.server"));
+    addPlugin(resolver.resolve("./runtime/app/plugins/session.client"));
     addServerPlugin(resolver.resolve("./runtime/server/plugins/oauth"));
+    addServerImportsDir(resolver.resolve("./runtime/server/utils"));
     addServerHandler({
       handler: resolver.resolve("./runtime/server/api/session.delete"),
       route: "/api/_auth/session",

package/dist/runtime/app/components/AuthState.vue

@@ -0,0 +1,17 @@
+<script setup>
+import { useUserSession } from '#imports'
+
+const userSession = useUserSession()
+const { ready } = userSession
+</script>
+
+<template>
+  <slot
+    v-if="ready"
+    v-bind="userSession"
+  />
+  <slot
+    v-else
+    name="placeholder"
+  />
+</template>

package/dist/runtime/{composables → app/composables}/session.d.ts

@@ -1,2 +1,6 @@
 import type { UserSessionComposable } from '#auth-utils';
+/**
+ * Composable to get back the user session and utils around it.
+ * @see https://github.com/atinux/nuxt-auth-utils
+ */
 export declare function useUserSession(): UserSessionComposable;

package/dist/runtime/{composables/session.mjs → app/composables/session.js}

@@ -1,8 +1,11 @@
 import { useState, computed, useRequestFetch } from "#imports";
 const useSessionState = () => useState("nuxt-session", () => ({}));
+const useAuthReadyState = () => useState("nuxt-auth-ready", () => false);
 export function useUserSession() {
   const sessionState = useSessionState();
+  const authReadyState = useAuthReadyState();
   return {
+    ready: computed(() => authReadyState.value),
     loggedIn: computed(() => Boolean(sessionState.value.user)),
     user: computed(() => sessionState.value.user || null),
     session: sessionState,
@@ -11,12 +14,16 @@ export function useUserSession() {
   };
 }
 async function fetch() {
+  const authReadyState = useAuthReadyState();
   useSessionState().value = await useRequestFetch()("/api/_auth/session", {
     headers: {
       Accept: "text/json"
     },
     retry: false
   }).catch(() => ({}));
+  if (!authReadyState.value) {
+    authReadyState.value = true;
+  }
 }
 async function clear() {
   await $fetch("/api/_auth/session", { method: "DELETE" });

package/dist/runtime/app/plugins/session.client.js

@@ -0,0 +1,8 @@
+import { defineNuxtPlugin, useUserSession } from "#imports";
+export default defineNuxtPlugin(async (nuxtApp) => {
+  if (!nuxtApp.payload.serverRendered || Boolean(nuxtApp.payload.prerenderedAt) || Boolean(nuxtApp.payload.isCached)) {
+    nuxtApp.hook("app:mounted", async () => {
+      await useUserSession().fetch();
+    });
+  }
+});

package/dist/runtime/app/plugins/session.server.js

@@ -0,0 +1,11 @@
+import { defineNuxtPlugin, useRequestEvent, useUserSession } from "#imports";
+export default defineNuxtPlugin({
+  name: "session-fetch-plugin",
+  enforce: "pre",
+  async setup(nuxtApp) {
+    nuxtApp.payload.isCached = Boolean(useRequestEvent()?.context.cache);
+    if (nuxtApp.payload.serverRendered && !nuxtApp.payload.prerenderedAt && !nuxtApp.payload.isCached) {
+      await useUserSession().fetch();
+    }
+  }
+});

package/dist/runtime/server/api/{session.delete.mjs → session.delete.js}

@@ -1,5 +1,5 @@
 import { eventHandler } from "h3";
-import { clearUserSession } from "../utils/session.mjs";
+import { clearUserSession } from "../utils/session.js";
 export default eventHandler(async (event) => {
   await clearUserSession(event);
   return { loggedOut: true };

package/dist/runtime/server/api/{session.get.mjs → session.get.js}

@@ -1,5 +1,5 @@
 import { eventHandler } from "h3";
-import { requireUserSession, sessionHooks } from "../utils/session.mjs";
+import { requireUserSession, sessionHooks } from "../utils/session.js";
 export default eventHandler(async (event) => {
   const session = await requireUserSession(event);
   await sessionHooks.callHookParallel("fetch", session, event);

package/dist/runtime/server/utils/oauth.d.ts

@@ -1,15 +1,15 @@
-import { githubEventHandler } from '../lib/oauth/github';
-import { googleEventHandler } from '../lib/oauth/google';
-import { spotifyEventHandler } from '../lib/oauth/spotify';
-import { twitchEventHandler } from '../lib/oauth/twitch';
-import { auth0EventHandler } from '../lib/oauth/auth0';
-import { microsoftEventHandler } from '../lib/oauth/microsoft';
-import { discordEventHandler } from '../lib/oauth/discord';
-import { battledotnetEventHandler } from '../lib/oauth/battledotnet';
-import { keycloakEventHandler } from '../lib/oauth/keycloak';
-import { linkedinEventHandler } from '../lib/oauth/linkedin';
-import { cognitoEventHandler } from '../lib/oauth/cognito';
-import { facebookEventHandler } from '../lib/oauth/facebook';
+import { githubEventHandler } from '../lib/oauth/github.js';
+import { googleEventHandler } from '../lib/oauth/google.js';
+import { spotifyEventHandler } from '../lib/oauth/spotify.js';
+import { twitchEventHandler } from '../lib/oauth/twitch.js';
+import { auth0EventHandler } from '../lib/oauth/auth0.js';
+import { microsoftEventHandler } from '../lib/oauth/microsoft.js';
+import { discordEventHandler } from '../lib/oauth/discord.js';
+import { battledotnetEventHandler } from '../lib/oauth/battledotnet.js';
+import { keycloakEventHandler } from '../lib/oauth/keycloak.js';
+import { linkedinEventHandler } from '../lib/oauth/linkedin.js';
+import { cognitoEventHandler } from '../lib/oauth/cognito.js';
+import { facebookEventHandler } from '../lib/oauth/facebook.js';
 export declare const oauth: {
     githubEventHandler: typeof githubEventHandler;
     spotifyEventHandler: typeof spotifyEventHandler;

package/dist/runtime/server/utils/oauth.js

@@ -0,0 +1,26 @@
+import { githubEventHandler } from "../lib/oauth/github.js";
+import { googleEventHandler } from "../lib/oauth/google.js";
+import { spotifyEventHandler } from "../lib/oauth/spotify.js";
+import { twitchEventHandler } from "../lib/oauth/twitch.js";
+import { auth0EventHandler } from "../lib/oauth/auth0.js";
+import { microsoftEventHandler } from "../lib/oauth/microsoft.js";
+import { discordEventHandler } from "../lib/oauth/discord.js";
+import { battledotnetEventHandler } from "../lib/oauth/battledotnet.js";
+import { keycloakEventHandler } from "../lib/oauth/keycloak.js";
+import { linkedinEventHandler } from "../lib/oauth/linkedin.js";
+import { cognitoEventHandler } from "../lib/oauth/cognito.js";
+import { facebookEventHandler } from "../lib/oauth/facebook.js";
+export const oauth = {
+  githubEventHandler,
+  spotifyEventHandler,
+  googleEventHandler,
+  twitchEventHandler,
+  auth0EventHandler,
+  microsoftEventHandler,
+  discordEventHandler,
+  battledotnetEventHandler,
+  keycloakEventHandler,
+  linkedinEventHandler,
+  cognitoEventHandler,
+  facebookEventHandler
+};

package/dist/runtime/server/utils/session.d.ts

@@ -13,26 +13,38 @@ export interface SessionHooks {
     clear: (session: UserSession, event: H3Event) => void | Promise<void>;
 }
 export declare const sessionHooks: import("hookable").Hookable<SessionHooks, import("hookable").HookKeys<SessionHooks>>;
+/**
+ * Get the user session from the current request
+ * @param event The Request (h3) event
+ * @returns The user session
+ */
 export declare function getUserSession(event: H3Event): Promise<UserSession>;
 /**
  * Set a user session
- * @param event
+ * @param event The Request (h3) event
  * @param data User session data, please only store public information since it can be decoded with API calls
+ * @see https://github.com/atinux/nuxt-auth-utils
  */
 export declare function setUserSession(event: H3Event, data: UserSession): Promise<UserSession>;
 /**
  * Replace a user session
- * @param event
+ * @param event The Request (h3) event
  * @param data User session data, please only store public information since it can be decoded with API calls
  */
 export declare function replaceUserSession(event: H3Event, data: UserSession): Promise<UserSession>;
+/**
+ * Clear the user session and removing the session cookie
+ * @param event The Request (h3) event
+ * @returns true if the session was cleared
+ */
 export declare function clearUserSession(event: H3Event): Promise<boolean>;
 /**
- * Require a user session
+ * Require a user session, throw a 401 error if the user is not logged in
  * @param event
  * @param opts Options to customize the error message and status code
  * @param opts.statusCode The status code to use for the error (defaults to 401)
  * @param opts.message The message to use for the error (defaults to Unauthorized)
+ * @see https://github.com/atinux/nuxt-auth-utils
  */
 export declare function requireUserSession(event: H3Event, opts?: {
     statusCode?: number;

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

@@ -1,2 +1,2 @@
-export type { User, UserSession, UserSessionRequired, UserSessionComposable } from './session';
-export type { OAuthConfig } from './oauth-config';
+export type { User, UserSession, UserSessionRequired, UserSessionComposable } from './session.js';
+export type { OAuthConfig } from './oauth-config.js';

package/dist/runtime/types/session.d.ts

@@ -8,9 +8,28 @@ export interface UserSessionRequired extends UserSession {
     user: User;
 }
 export interface UserSessionComposable {
+    /**
+     * Computed indicating if the auth session is ready
+     */
+    ready: ComputedRef<boolean>;
+    /**
+     * Computed indicating if the user is logged in.
+     */
     loggedIn: ComputedRef<boolean>;
+    /**
+     * The user object if logged in, null otherwise.
+     */
     user: ComputedRef<User | null>;
+    /**
+     * The session object.
+     */
     session: Ref<UserSession>;
+    /**
+     * Fetch the user session from the server.
+     */
     fetch: () => Promise<void>;
+    /**
+     * Clear the user session and remove the session cookie.
+     */
     clear: () => Promise<void>;
 }

package/dist/types.d.mts

@@ -2,6 +2,7 @@
 import type { ModuleOptions } from './module.js'
 
 
+
 declare module '@nuxt/schema' {
   interface NuxtConfig { ['auth']?: Partial<ModuleOptions> }
   interface NuxtOptions { ['auth']?: ModuleOptions }

package/dist/types.d.ts

@@ -2,6 +2,7 @@
 import type { ModuleOptions } from './module'
 
 
+
 declare module '@nuxt/schema' {
   interface NuxtConfig { ['auth']?: Partial<ModuleOptions> }
   interface NuxtOptions { ['auth']?: ModuleOptions }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "nuxt-auth-utils",
-  "version": "0.0.25",
+  "version": "0.1.0",
   "description": "Minimalist Auth module for Nuxt with SSR",
   "repository": "Atinux/nuxt-auth-utils",
   "license": "MIT",
   "type": "module",
+  "packageManager": "pnpm@9.1.3",
   "exports": {
     ".": {
       "types": "./dist/types.d.ts",
@@ -30,7 +31,7 @@
     "test:watch": "vitest watch"
   },
   "dependencies": {
-    "@nuxt/kit": "^3.11.2",
+    "@nuxt/kit": "^3.12.2",
     "defu": "^6.1.4",
     "hookable": "^5.5.3",
     "ofetch": "^1.3.4",
@@ -39,20 +40,20 @@
     "uncrypto": "^0.1.3"
   },
   "devDependencies": {
-    "@iconify-json/simple-icons": "^1.1.99",
+    "@iconify-json/simple-icons": "^1.1.106",
     "@nuxt/devtools": "latest",
-    "@nuxt/eslint-config": "^0.3.8",
-    "@nuxt/module-builder": "^0.6.0",
-    "@nuxt/schema": "^3.11.2",
-    "@nuxt/test-utils": "^3.12.1",
-    "@nuxt/ui": "^2.15.2",
-    "@nuxt/ui-pro": "^1.1.0",
-    "@types/node": "^20.12.7",
+    "@nuxt/eslint-config": "^0.3.13",
+    "@nuxt/module-builder": "^0.7.1",
+    "@nuxt/schema": "^3.12.2",
+    "@nuxt/test-utils": "^3.13.1",
+    "@nuxt/ui": "^2.17.0",
+    "@nuxt/ui-pro": "^1.3.0",
+    "@types/node": "^20.14.4",
     "changelogen": "^0.5.5",
-    "eslint": "^9.0.0",
-    "nuxt": "^3.11.2",
+    "eslint": "^9.5.0",
+    "nuxt": "^3.12.2",
     "typescript": "^5.4.5",
-    "vitest": "^1.5.0",
-    "vue-tsc": "^2.0.13"
+    "vitest": "^1.6.0",
+    "vue-tsc": "^2.0.21"
   }
 }

package/dist/runtime/plugins/session.server.d.ts

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

package/dist/runtime/plugins/session.server.mjs

@@ -1,9 +0,0 @@
-import { defineNuxtPlugin } from "#app";
-import { useUserSession } from "#imports";
-export default defineNuxtPlugin({
-  name: "session-fetch-plugin",
-  enforce: "pre",
-  async setup() {
-    await useUserSession().fetch();
-  }
-});

package/dist/runtime/server/utils/oauth.mjs

@@ -1,26 +0,0 @@
-import { githubEventHandler } from "../lib/oauth/github.mjs";
-import { googleEventHandler } from "../lib/oauth/google.mjs";
-import { spotifyEventHandler } from "../lib/oauth/spotify.mjs";
-import { twitchEventHandler } from "../lib/oauth/twitch.mjs";
-import { auth0EventHandler } from "../lib/oauth/auth0.mjs";
-import { microsoftEventHandler } from "../lib/oauth/microsoft.mjs";
-import { discordEventHandler } from "../lib/oauth/discord.mjs";
-import { battledotnetEventHandler } from "../lib/oauth/battledotnet.mjs";
-import { keycloakEventHandler } from "../lib/oauth/keycloak.mjs";
-import { linkedinEventHandler } from "../lib/oauth/linkedin.mjs";
-import { cognitoEventHandler } from "../lib/oauth/cognito.mjs";
-import { facebookEventHandler } from "../lib/oauth/facebook.mjs";
-export const oauth = {
-  githubEventHandler,
-  spotifyEventHandler,
-  googleEventHandler,
-  twitchEventHandler,
-  auth0EventHandler,
-  microsoftEventHandler,
-  discordEventHandler,
-  battledotnetEventHandler,
-  keycloakEventHandler,
-  linkedinEventHandler,
-  cognitoEventHandler,
-  facebookEventHandler
-};