@meistrari/auth-nuxt 0.1.0

package/README.md

@@ -0,0 +1,271 @@
+# @meistrari/auth-sdk
+
+A Nuxt module that provides authentication and organization management capabilities using Better Auth.
+
+## Installation
+
+```bash
+npm install @meistrari/auth-sdk
+```
+
+## Setup
+
+Add the module to your `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['@meistrari/auth-sdk'],
+  authSdk: {
+    apiUrl: 'https://your-auth-api.com',
+    useJwt: true, // Enable JWT token refresh cycle 
+    jwtCookieName: 'auth-jwt', // Custom JWT cookie name
+    skipServerMiddleware: false, // Skip automatic server middleware
+    isDevelopment: false, // Development mode settings
+  }
+})
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiUrl` | `string` | **Required** | Base URL of your authentication API |
+| `useJwt` | `boolean` | `false` | Enable JWT cookie management and token refresh |
+| `jwtCookieName` | `string` | `'auth-jwt'` | Name of the JWT cookie |
+| `skipServerMiddleware` | `boolean` | `false` | Skip automatic server-side auth context setup |
+| `isDevelopment` | `boolean` | `false` | Enable development-specific features |
+
+## Usage
+
+### Client-side Authentication
+
+The SDK provides the `useMeistrariAuth` composable for managing authentication state:
+
+```vue
+<script setup>
+const { user, session, signOut } = useMeistrariAuth()
+
+// Access current user
+console.log(user.value) // User object or null
+
+// Access current session
+console.log(session.value) // Session object or null
+
+// Sign out
+await signOut(() => {
+  // Optional callback after sign out
+  console.log('User signed out')
+})
+</script>
+
+<template>
+  <div v-if="user">
+    Welcome, {{ user.name }}!
+    <button @click="signOut">Sign Out</button>
+  </div>
+  <div v-else>
+    Please sign in
+  </div>
+</template>
+```
+
+### Authentication Client
+
+Access the underlying Better Auth client through the Nuxt app:
+
+```typescript
+// In a plugin, middleware, or component
+const { $auth } = useNuxtApp()
+
+// Get current session
+const sessionData = await $auth.client.getSession()
+
+// Organization operations
+await $auth.client.organization.create({
+  name: 'My Organization',
+  slug: 'my-org'
+})
+
+// Access custom endpoints
+await $auth.client.customEndpoints.session.token()
+```
+
+### Server-side Usage
+
+The SDK automatically sets up server-side authentication context for API routes:
+
+```typescript
+// server/api/protected.ts
+export default defineEventHandler(async (event) => {
+  // Authentication context is automatically available
+  const { user, session } = event.context.auth
+
+  if (!user) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: 'Unauthorized'
+    })
+  }
+
+  return {
+    message: `Hello, ${user.name}!`,
+    userId: user.id
+  }
+})
+```
+
+### Custom Middleware
+
+You can create custom server middleware using the provided helper:
+
+```typescript
+// server/middleware/custom.ts
+import { meistrariAuthMiddleware } from '@meistrari/auth-sdk/server/middleware/auth'
+
+export default meistrariAuthMiddleware(async (event) => {
+  // Your custom logic here
+  // event.context.auth contains user and session
+})
+```
+
+### JWT Token Management
+
+When `useJwt` is enabled, the SDK automatically:
+
+- Manages JWT tokens in cookies
+- Refreshes tokens before expiration (every 60 seconds)
+- Validates token expiry client-side
+- Provides `getToken()` method for accessing valid tokens
+
+```typescript
+const { $auth } = useNuxtApp()
+
+// Get a valid JWT token (refreshes if needed)
+const token = await $auth.getToken()
+```
+
+## Types
+
+The SDK exports comprehensive TypeScript types:
+
+```typescript
+import type {
+  User,
+  Session,
+  Organization,
+  Workspace,
+  Member,
+  Invitation,
+  Team,
+  TeamMember
+} from '@meistrari/auth-sdk/utils'
+```
+
+### Key Types
+
+- **User**: User account information including email, name, and verification status
+- **Session**: Active session data with expiration and device info
+- **Organization**: Organization entity with basic metadata
+- **Workspace**: Extended organization with settings and statistics
+- **Member**: Organization member with role and team assignments
+- **Team**: Team entity within an organization
+- **Invitation**: Pending organization invitations
+
+## Organization & Team Management
+
+The SDK includes full organization and team management capabilities:
+
+```typescript
+const { $auth } = useNuxtApp()
+
+// Create organization
+await $auth.client.organization.create({
+  name: 'Acme Corp',
+  slug: 'acme-corp'
+})
+
+// Invite members
+await $auth.client.organization.inviteMember({
+  email: 'user@example.com',
+  role: 'org:member',
+  organizationId: 'org-id'
+})
+
+// Create teams
+await $auth.client.organization.createTeam({
+  name: 'Development Team',
+  organizationId: 'org-id'
+})
+
+// Manage member roles
+await $auth.client.organization.updateMemberRole({
+  membershipId: 'member-id',
+  role: 'org:admin'
+})
+```
+
+### Role-based Access Control
+
+The SDK implements role-based access control with three built-in roles:
+
+- **org:admin**: Full organization management permissions
+- **org:reviewer**: Review-only access
+- **org:member**: Basic member access
+
+```typescript
+// Access control is automatically enforced in API calls
+// Roles are validated server-side based on user permissions
+```
+
+## Utilities
+
+### Token Validation
+
+```typescript
+import { isTokenExpired, validateToken } from '@meistrari/auth-sdk/utils'
+
+// Check if token is expired
+if (isTokenExpired(jwtToken)) {
+  // Token needs refresh
+}
+
+// Validate token against JWKS endpoint
+const isValid = await validateToken(jwtToken, 'https://your-api.com')
+```
+
+## Error Handling
+
+The SDK handles common authentication errors automatically:
+
+- Expired tokens are refreshed automatically
+- Invalid sessions redirect to sign-in
+- Network errors are gracefully handled
+- CSRF protection is built-in
+
+```typescript
+try {
+  await $auth.client.getSession()
+} catch (error) {
+  console.error('Authentication failed:', error.message)
+}
+```
+
+## Development
+
+Set `isDevelopment: true` in your config to enable:
+
+- Additional debugging logs
+- Development-specific cookie handling
+- Relaxed security policies for local development
+
+## Security Features
+
+- **CSRF Protection**: Built into all API calls
+- **JWT Validation**: Cryptographic validation using JWKS
+- **Secure Cookies**: HTTP-only, secure cookies in production
+- **Token Refresh**: Automatic token rotation
+- **Session Management**: Secure session handling
+
+## Migration
+
+If upgrading from a previous version, ensure your configuration includes the required `apiUrl` parameter and update any deprecated options.

package/dist/module.d.mts

@@ -0,0 +1,16 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    /** Auth API base URL */
+    apiUrl: string;
+    /** Set JWT cookie and start token refresh cycle */
+    useJwt: boolean;
+    /** Cookie name for authentication token */
+    jwtCookieName: string;
+    skipServerMiddleware: boolean;
+    isDevelopment: boolean;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@meistrari/auth-sdk",
+  "configKey": "authSdk",
+  "version": "0.1.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,46 @@
+import { defineNuxtModule, createResolver, addServerHandler, addImports, addPlugin } from '@nuxt/kit';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "@meistrari/auth-sdk",
+    configKey: "authSdk"
+  },
+  defaults: {
+    apiUrl: "",
+    useJwt: false,
+    jwtCookieName: "auth-jwt",
+    skipServerMiddleware: false,
+    isDevelopment: false
+  },
+  setup(options, nuxt) {
+    if (!options.apiUrl) {
+      console.error("[@meistrari/auth-sdk] error: apiUrl is required in module config");
+    }
+    const resolver = createResolver(import.meta.url);
+    nuxt.options.runtimeConfig.public.auth = options;
+    if (!options.skipServerMiddleware) {
+      addServerHandler({
+        route: "",
+        handler: resolver.resolve("./runtime/server/middleware/auth")
+      });
+    }
+    if (options.isDevelopment) {
+      addServerHandler({
+        route: "",
+        handler: resolver.resolve("./runtime/server/middleware/set-cookies")
+      });
+      addServerHandler({
+        route: "/api/meistrari-auth/sign-out",
+        handler: resolver.resolve("./runtime/server/api/sign-out")
+      });
+    }
+    addImports({
+      name: "useMeistrariAuth",
+      as: "useMeistrariAuth",
+      from: resolver.resolve("runtime/composable")
+    });
+    addPlugin(resolver.resolve("./runtime/plugin"));
+  }
+});
+
+export { module as default };

package/dist/runtime/composable.d.ts

@@ -0,0 +1,5 @@
+export declare function useMeistrariAuth(): {
+    user: import("vue").Ref<any, any>;
+    session: import("vue").Ref<any, any>;
+    signOut: (callback?: () => void) => Promise<void>;
+};

package/dist/runtime/composable.js

@@ -0,0 +1,29 @@
+import { useCookie, useState, useRuntimeConfig, useNuxtApp } from "#app";
+export function useMeistrariAuth() {
+  const user = useState("user", () => null);
+  const session = useState("session", () => null);
+  const { useJwt, jwtCookieName, isDevelopment } = useRuntimeConfig().public.auth;
+  const { $auth } = useNuxtApp();
+  async function signOut(callback) {
+    await $auth.client.signOut({
+      fetchOptions: {
+        onSuccess: async () => {
+          if (useJwt) {
+            useCookie(jwtCookieName).value = null;
+          }
+          if (isDevelopment) {
+            await $fetch("/api/meistrari-auth/sign-out");
+          }
+          user.value = null;
+          session.value = null;
+          callback?.();
+        }
+      }
+    });
+  }
+  return {
+    user,
+    session,
+    signOut
+  };
+}

package/dist/runtime/plugin.d.ts

@@ -0,0 +1,15 @@
+import { createAuthClient } from '@meistrari/auth-core';
+declare const _default: import("#app").Plugin<{
+    auth: {
+        client: ReturnType<typeof createAuthClient>;
+        getToken: () => Promise<string | null | undefined>;
+        refreshToken: () => Promise<string | null | undefined>;
+    };
+}> & import("#app").ObjectPlugin<{
+    auth: {
+        client: ReturnType<typeof createAuthClient>;
+        getToken: () => Promise<string | null | undefined>;
+        refreshToken: () => Promise<string | null | undefined>;
+    };
+}>;
+export default _default;

package/dist/runtime/plugin.js

@@ -0,0 +1,105 @@
+import { defineNuxtPlugin, useCookie, useRequestHeaders, useRuntimeConfig } from "#app";
+import { watch } from "vue";
+import { createAuthClient, isTokenExpired } from "@meistrari/auth-core";
+import { useMeistrariAuth } from "./composable.js";
+export default defineNuxtPlugin({
+  name: "meistrari-auth",
+  parallel: true,
+  async setup() {
+    const config = useRuntimeConfig().public.auth;
+    const authClient = createAuthClient(config.apiUrl);
+    const { user, session } = useMeistrariAuth();
+    async function getToken() {
+      const token = useCookie(config.jwtCookieName);
+      if (token.value) {
+        if (!isTokenExpired(token.value)) {
+          return token.value;
+        }
+      }
+      try {
+        return await refreshToken();
+      } catch (error) {
+        throw new Error("Failed to get token: " + (error instanceof Error ? error.message : String(error)));
+      }
+    }
+    async function refreshToken() {
+      const token = useCookie(config.jwtCookieName);
+      const headers = useRequestHeaders();
+      const session2 = await authClient.getSession({
+        fetchOptions: {
+          // on the client side we include credentials
+          credentials: "include",
+          // on the server side we forward the cookies
+          headers,
+          onSuccess: (ctx) => {
+            const jwt = ctx.response.headers.get("set-auth-jwt");
+            if (jwt) {
+              token.value = jwt;
+            }
+          }
+        }
+      });
+      if (session2.error || !session2.data?.session) {
+        throw new Error("Failed to refresh token");
+      }
+      return token.value;
+    }
+    async function initializeSession() {
+      if (session.value && user.value)
+        return;
+      const token = useCookie(config.jwtCookieName);
+      const headers = import.meta.server ? useRequestHeaders() : void 0;
+      const { data: sessionData, error: sessionError } = await authClient.getSession(
+        {
+          fetchOptions: {
+            // on the client side we include credentials
+            credentials: "include",
+            // on the server side we forward the cookies
+            headers,
+            ...config.useJwt && {
+              onSuccess: (context) => {
+                const jwt = context.response.headers.get("Set-Auth-Jwt");
+                if (jwt) {
+                  token.value = jwt;
+                }
+              }
+            }
+          }
+        }
+      );
+      if (sessionError || !sessionData) {
+        return;
+      }
+      user.value = sessionData.user;
+      session.value = sessionData.session;
+    }
+    await initializeSession();
+    if (import.meta.client) {
+      if (config.useJwt) {
+        let tokenRefreshInterval = null;
+        watch(session, async (newVal) => {
+          if (tokenRefreshInterval) {
+            clearTimeout(tokenRefreshInterval);
+            tokenRefreshInterval = null;
+          }
+          if (newVal) {
+            async function createTokenRefreshInterval() {
+              await refreshToken();
+              tokenRefreshInterval = window.setTimeout(createTokenRefreshInterval, 6e4);
+            }
+            createTokenRefreshInterval();
+          }
+        }, { immediate: true });
+      }
+    }
+    return {
+      provide: {
+        auth: {
+          client: authClient,
+          getToken,
+          refreshToken
+        }
+      }
+    };
+  }
+});

package/dist/runtime/server/api/sign-out.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/api/sign-out.js

@@ -0,0 +1,16 @@
+import { defineEventHandler, deleteCookie, sendNoContent } from "h3";
+export default defineEventHandler(async (event) => {
+  deleteCookie(event, "__Secure-__session", {
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax",
+    path: "/"
+  });
+  deleteCookie(event, "__Secure-__session_data", {
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax",
+    path: "/"
+  });
+  return sendNoContent(event);
+});

package/dist/runtime/server/middleware/auth.d.ts

@@ -0,0 +1,4 @@
+import type { AuthenticatedH3Event } from '../types/h3.js';
+export declare function meistrariAuthMiddleware(callback: (event: AuthenticatedH3Event) => void | Promise<void>): import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/middleware/auth.js

@@ -0,0 +1,35 @@
+import { defineEventHandler, getCookie } from "h3";
+import { useRuntimeConfig } from "nitropack/runtime/config";
+import { createAuthClient } from "@meistrari/auth-core";
+async function setAuthContext(event) {
+  event.context.auth = {
+    session: null,
+    user: null
+  };
+  const sessionCookie = getCookie(event, "__Secure-__session");
+  if (!sessionCookie)
+    return;
+  const authConfig = useRuntimeConfig(event).public.auth;
+  const authClient = createAuthClient(authConfig.apiUrl);
+  const { data: sessionData, error: sessionError } = await authClient.getSession({
+    fetchOptions: {
+      headers: event.headers
+    }
+  });
+  if (sessionError || !sessionData) {
+    return;
+  }
+  event.context.auth.session = sessionData.session;
+  event.context.auth.user = sessionData.user;
+}
+export function meistrariAuthMiddleware(callback) {
+  return defineEventHandler(async (event) => {
+    await setAuthContext(event);
+    await callback(event);
+  });
+}
+export default defineEventHandler(async (event) => {
+  if (!event.path.startsWith("/api"))
+    return;
+  await setAuthContext(event);
+});

package/dist/runtime/server/middleware/set-cookies.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/middleware/set-cookies.js

@@ -0,0 +1,42 @@
+import { defineEventHandler, getQuery, setCookie, sendRedirect, getRequestURL } from "h3";
+export default defineEventHandler(async (event) => {
+  const query = getQuery(event);
+  const hasSessionParam = query.session && typeof query.session === "string";
+  const hasSessionDataParam = query.session_data && typeof query.session_data === "string";
+  if (hasSessionParam || hasSessionDataParam) {
+    if (hasSessionParam) {
+      setCookie(event, "__Secure-__session", query.session, {
+        httpOnly: true,
+        secure: true,
+        sameSite: "lax",
+        path: "/",
+        maxAge: 60 * 60 * 24 * 7
+        // 1 week in seconds
+      });
+    }
+    if (hasSessionDataParam) {
+      setCookie(event, "__Secure-__session_data", query.session_data, {
+        httpOnly: true,
+        secure: true,
+        sameSite: "lax",
+        path: "/",
+        maxAge: 60 * 60 * 24 * 7
+        // 1 week in seconds
+      });
+    }
+    const url = getRequestURL(event);
+    const newQuery = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (key !== "session" && key !== "session_data" && value !== void 0 && value !== null) {
+        if (Array.isArray(value)) {
+          value.forEach((v) => newQuery.append(key, String(v)));
+        } else {
+          newQuery.append(key, String(value));
+        }
+      }
+    }
+    const queryString = newQuery.toString();
+    const redirectUrl = `${url.pathname}${queryString ? `?${queryString}` : ""}`;
+    return sendRedirect(event, redirectUrl, 302);
+  }
+});

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

package/dist/runtime/server/types/h3.d.ts

@@ -0,0 +1,22 @@
+import type { User, Session } from '@meistrari/auth-core'
+import type { H3Event, H3EventContext } from 'h3'
+
+declare module 'h3' {
+  interface H3EventContext {
+    auth?: {
+      user: User | null
+      session: Session | null
+    }
+  }
+}
+
+export interface AuthenticatedH3EventContext extends H3EventContext {
+  auth: {
+    user: User | null
+    session: Session | null
+  }
+}
+
+export interface AuthenticatedH3Event extends H3Event {
+  context: AuthenticatedH3EventContext
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@meistrari/auth-nuxt",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./server/middleware/auth": {
+      "types": "./dist/runtime/server/middleware/auth.d.ts",
+      "import": "./dist/runtime/server/middleware/auth.js"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt-module-build build"
+  },
+  "dependencies": {
+    "@meistrari/auth-core": "0.1.1"
+  },
+  "peerDependencies": {
+    "nuxt": "^3.0.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "2.6.3",
+    "@nuxt/eslint-config": "1.9.0",
+    "@nuxt/kit": "4.0.3",
+    "@nuxt/module-builder": "1.0.2",
+    "@nuxt/schema": "4.0.3",
+    "@nuxt/test-utils": "3.19.2",
+    "@types/node": "latest",
+    "changelogen": "0.6.2",
+    "eslint": "9.34.0",
+    "nuxt": "4.0.3",
+    "typescript": "5.9.2",
+    "unbuild": "3.6.1",
+    "vitest": "3.2.4",
+    "vue-tsc": "3.0.6"
+  }
+}