@meistrari/auth-nuxt 0.1.0 → 1.0.0-beta.1

package/README.md

@@ -1,11 +1,11 @@
-# @meistrari/auth-sdk
+# @meistrari/auth-nuxt
 
-A Nuxt module that provides authentication and organization management capabilities using Better Auth.
+A Nuxt module that provides comprehensive authentication, organization management, and API key capabilities.
 
 ## Installation
 
 ```bash
-npm install @meistrari/auth-sdk
+npm install @meistrari/auth-nuxt
 ```
 
 ## Setup
@@ -14,13 +14,11 @@ Add the module to your `nuxt.config.ts`:
 
 ```typescript
 export default defineNuxtConfig({
-  modules: ['@meistrari/auth-sdk'],
-  authSdk: {
+  modules: ['@meistrari/auth-nuxt'],
+  telaAuth: {
     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
+    jwtCookieName: 'tela-jwt', // Optional: custom JWT cookie name
+    skipServerMiddleware: false, // Optional: skip automatic server middleware
   }
 })
 ```
@@ -30,20 +28,20 @@ export default defineNuxtConfig({
 | 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 |
+| `jwtCookieName` | `string` | `'tela-jwt'` | Name of the JWT cookie |
 | `skipServerMiddleware` | `boolean` | `false` | Skip automatic server-side auth context setup |
-| `isDevelopment` | `boolean` | `false` | Enable development-specific features |
 
-## Usage
+## Composables
 
-### Client-side Authentication
+The SDK provides three main composables for different aspects of authentication and organization management:
 
-The SDK provides the `useMeistrariAuth` composable for managing authentication state:
+### useTelaSession
+
+Manages user sessions, authentication, and sign-in/sign-out operations.
 
 ```vue
 <script setup>
-const { user, session, signOut } = useMeistrariAuth()
+const { user, session, signOut, getToken } = useTelaSession()
 
 // Access current user
 console.log(user.value) // User object or null
@@ -51,9 +49,11 @@ console.log(user.value) // User object or null
 // Access current session
 console.log(session.value) // Session object or null
 
+// Get a valid JWT token
+const token = await getToken()
+
 // Sign out
 await signOut(() => {
-  // Optional callback after sign out
   console.log('User signed out')
 })
 </script>
@@ -69,36 +69,202 @@ await signOut(() => {
 </template>
 ```
 
-### Authentication Client
+#### Available Methods
+
+**Session Management:**
+- `getSession()` - Retrieves the current user session
+- `getToken()` - Retrieves a valid JWT token (refreshes if needed)
+- `signOut(callback?)` - Signs out the user
+
+**Authentication Methods:**
+- `signInWithEmailAndPassword(options)` - Email/password authentication
+- `signInWithSocialProvider(options)` - Social authentication (Google, Microsoft)
+- `signInWithSaml(options)` - SAML-based SSO authentication
 
-Access the underlying Better Auth client through the Nuxt app:
+**Password Management:**
+- `requestPasswordReset(email, callbackURL)` - Initiates password reset
+- `resetPassword(token, password)` - Completes password reset
 
+#### Sign-In Examples
+
+**Email and Password:**
 ```typescript
-// In a plugin, middleware, or component
-const { $auth } = useNuxtApp()
+await signInWithEmailAndPassword({
+  email: 'user@example.com',
+  password: 'secure-password',
+  callbackURL: '/dashboard',
+  errorCallbackURL: '/login?error=true'
+})
+```
 
-// Get current session
-const sessionData = await $auth.client.getSession()
+**Social Authentication:**
+```typescript
+await signInWithSocialProvider({
+  provider: 'google', // or 'microsoft'
+  callbackURL: '/dashboard',
+  errorCallbackURL: '/login?error=true'
+})
+```
 
-// Organization operations
-await $auth.client.organization.create({
-  name: 'My Organization',
-  slug: 'my-org'
+**SAML SSO:**
+```typescript
+await signInWithSaml({
+  email: 'user@example.com',
+  callbackURL: '/dashboard',
+  errorCallbackURL: '/login?error=true'
 })
+```
+
+### useTelaOrganization
+
+Manages organizations, members, invitations, and teams.
+
+```vue
+<script setup>
+const {
+  activeOrganization,
+  activeMember,
+  getActiveOrganization,
+  setActiveOrganization,
+  inviteUserToOrganization
+} = useTelaOrganization()
+
+// Get the active organization
+await getActiveOrganization()
+
+// Switch organizations
+await setActiveOrganization('org-id')
+
+// Invite a user
+await inviteUserToOrganization({
+  userEmail: 'user@example.com',
+  role: 'member'
+})
+</script>
 
-// Access custom endpoints
-await $auth.client.customEndpoints.session.token()
+<template>
+  <div v-if="activeOrganization">
+    <h2>{{ activeOrganization.name }}</h2>
+    <p>{{ activeOrganization.members.length }} members</p>
+  </div>
+</template>
 ```
 
-### Server-side Usage
+#### Available Methods
+
+**Organization Management:**
+- `getActiveOrganization()` - Gets the current active organization with members, invitations, and teams
+- `listOrganizations()` - Lists all organizations for the user
+- `setActiveOrganization(id)` - Sets the active organization
+- `updateOrganization(payload)` - Updates organization details (name, logo, settings)
+
+**Member Management:**
+- `listMembers(options?)` - Lists organization members with pagination
+- `getActiveMember()` - Gets the current user's member record
+- `inviteUserToOrganization(options)` - Invites a user to the organization
+- `removeUserFromOrganization(options)` - Removes a user from the organization
+- `updateMemberRole(options)` - Updates a member's role
+- `acceptInvitation(id)` - Accepts an organization invitation
+- `cancelInvitation(id)` - Cancels a pending invitation
+
+**Team Management:**
+- `createTeam(payload)` - Creates a new team
+- `updateTeam(id, payload)` - Updates team details
+- `deleteTeam(id)` - Deletes a team
+- `listTeams()` - Lists all teams
+- `listTeamMembers(id)` - Lists members of a specific team
+- `addTeamMember(teamId, userId)` - Adds a user to a team
+- `removeTeamMember(teamId, userId)` - Removes a user from a team
+
+#### Organization Examples
+
+**Update Organization:**
+```typescript
+await updateOrganization({
+  name: 'New Organization Name',
+  logo: 'https://example.com/logo.png',
+  settings: { /* custom settings */ }
+})
+```
 
-The SDK automatically sets up server-side authentication context for API routes:
+**Invite Member:**
+```typescript
+await inviteUserToOrganization({
+  userEmail: 'user@example.com',
+  role: 'admin', // or 'member', 'reviewer'
+  teamId: 'team-id', // optional
+  resend: false // optional: resend if invitation exists
+})
+```
+
+**Create and Manage Teams:**
+```typescript
+// Create team
+const team = await createTeam({
+  name: 'Development Team'
+})
+
+// Add member to team
+await addTeamMember(team.id, 'user-id')
+
+// List team members
+const members = await listTeamMembers(team.id)
+```
+
+### useTelaApiKey
+
+Manages API keys for programmatic access.
+
+```vue
+<script setup>
+const {
+  listApiKeys,
+  createApiKey,
+  deleteApiKey
+} = useTelaApiKey()
+
+// List all API keys
+const apiKeys = await listApiKeys()
+
+// Create a new API key
+const newKey = await createApiKey({
+  name: 'Production API Key',
+  expiresIn: '90d',
+  prefix: 'prod',
+  metadata: { environment: 'production' }
+})
+
+// Delete an API key
+await deleteApiKey('key-id')
+</script>
+
+<template>
+  <div v-for="key in apiKeys" :key="key.id">
+    <span>{{ key.name }}</span>
+    <button @click="deleteApiKey(key.id)">Delete</button>
+  </div>
+</template>
+```
+
+#### Available Methods
+
+- `listApiKeys()` - Lists all API keys for the current user
+- `getApiKey(id)` - Retrieves a specific API key
+- `createApiKey(payload)` - Creates a new API key
+- `updateApiKey(payload)` - Updates an API key (name)
+- `deleteApiKey(id)` - Deletes an API key
+
+## Server-Side Usage
+
+The SDK automatically sets up server-side authentication context for API routes.
+
+### Using Authentication Context
 
 ```typescript
 // server/api/protected.ts
 export default defineEventHandler(async (event) => {
   // Authentication context is automatically available
-  const { user, session } = event.context.auth
+  const { user, workspace } = event.context.auth
 
   if (!user) {
     throw createError({
@@ -108,7 +274,7 @@ export default defineEventHandler(async (event) => {
   }
 
   return {
-    message: `Hello, ${user.name}!`,
+    message: `Hello, ${user.email}!`,
     userId: user.id
   }
 })
@@ -116,113 +282,82 @@ export default defineEventHandler(async (event) => {
 
 ### Custom Middleware
 
-You can create custom server middleware using the provided helper:
+Create custom server middleware using the provided helper:
 
 ```typescript
 // server/middleware/custom.ts
-import { meistrariAuthMiddleware } from '@meistrari/auth-sdk/server/middleware/auth'
+import { meistrariAuthMiddleware } from '@meistrari/auth-nuxt/server/middleware/auth'
 
 export default meistrariAuthMiddleware(async (event) => {
+  // event.context.auth contains user and workspace
+  const { user, workspace } = event.context.auth
+
   // Your custom logic here
-  // event.context.auth contains user and session
+  if (user) {
+    console.log(`Authenticated user: ${user.email}`)
+  }
 })
 ```
 
-### 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:
+The SDK exports comprehensive TypeScript types from the core package:
 
 ```typescript
 import type {
   User,
   Session,
   Organization,
-  Workspace,
+  FullOrganization,
   Member,
   Invitation,
   Team,
-  TeamMember
-} from '@meistrari/auth-sdk/utils'
+  TeamMember,
+  ApiKey,
+  CreateApiKeyPayload,
+  UpdateApiKeyPayload,
+  CreateTeamPayload,
+  UpdateTeamPayload,
+  InviteUserToOrganizationOptions,
+  RemoveUserFromOrganizationOptions,
+  UpdateMemberRoleOptions,
+  UpdateOrganizationPayload
+} from '@meistrari/auth-nuxt/core'
 ```
 
 ### 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
+- **Session**: Active session data with expiration and organization info
+- **Organization**: Basic organization entity
+- **FullOrganization**: Organization with members, invitations, and teams
 - **Member**: Organization member with role and team assignments
 - **Team**: Team entity within an organization
 - **Invitation**: Pending organization invitations
+- **ApiKey**: API key entity with metadata
 
-## 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'
-})
+## JWT Token Management
 
-// Create teams
-await $auth.client.organization.createTeam({
-  name: 'Development Team',
-  organizationId: 'org-id'
-})
+The SDK automatically manages JWT tokens:
 
-// 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:
+- Stores JWT tokens in cookies (configurable name)
+- Refreshes tokens before expiration (every 60 seconds)
+- Validates tokens client-side and server-side
+- Provides `getToken()` method for accessing valid tokens
 
-- **org:admin**: Full organization management permissions
-- **org:reviewer**: Review-only access
-- **org:member**: Basic member access
+The handshake flow ensures secure authentication:
 
-```typescript
-// Access control is automatically enforced in API calls
-// Roles are validated server-side based on user permissions
-```
+1. On initial visit without a token, redirects to auth API for handshake
+2. Auth API validates the session and redirects back with a nonce
+3. SDK exchanges the nonce for a JWT token
+4. Token is stored in a cookie and used for subsequent requests
 
 ## Utilities
 
 ### Token Validation
 
 ```typescript
-import { isTokenExpired, validateToken } from '@meistrari/auth-sdk/utils'
+import { isTokenExpired, validateToken, extractTokenPayload } from '@meistrari/auth-nuxt/core'
 
 // Check if token is expired
 if (isTokenExpired(jwtToken)) {
@@ -231,41 +366,54 @@ if (isTokenExpired(jwtToken)) {
 
 // Validate token against JWKS endpoint
 const isValid = await validateToken(jwtToken, 'https://your-api.com')
+
+// Extract token payload (without validation)
+const payload = extractTokenPayload(jwtToken)
+console.log(payload.user, payload.workspace)
 ```
 
+## Security Features
+
+- **JWT Validation**: Cryptographic validation using JWKS
+- **Secure Cookies**: HTTP-only, secure cookies in production
+- **Token Refresh**: Automatic token rotation every 60 seconds
+- **Session Management**: Secure session handling with handshake flow
+- **Server-Side Validation**: Middleware validates tokens on every API request
+
 ## 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
+- Expired tokens trigger sign-out when refresh fails
+- Invalid tokens result in `null` user/session values
+- Network errors are handled gracefully
+- API errors can be caught and handled in your code
 
 ```typescript
+import { APIError } from '@meistrari/auth-nuxt/core'
+
 try {
-  await $auth.client.getSession()
+  await signInWithEmailAndPassword({
+    email: 'user@example.com',
+    password: 'wrong-password',
+    callbackURL: '/dashboard'
+  })
 } catch (error) {
-  console.error('Authentication failed:', error.message)
+  if (error instanceof APIError) {
+    console.error('Authentication failed:', error.message, error.status)
+  }
 }
 ```
 
-## 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.
+If upgrading from a previous version:
+
+1. Update package name to `@meistrari/auth-nuxt`
+2. Change config key from `authSdk` to `telaAuth`
+3. Replace `useMeistrariAuth()` with appropriate composable:
+   - `useTelaSession()` for authentication
+   - `useTelaOrganization()` for organization management
+   - `useTelaApiKey()` for API key management
+4. Update cookie name if using custom value (default is now `tela-jwt`)
+5. Remove `useJwt` and `isDevelopment` options (no longer needed)

package/dist/core.d.mts

@@ -0,0 +1 @@
+export * from '@meistrari/auth-core';

package/dist/core.mjs

@@ -0,0 +1 @@
+export * from '@meistrari/auth-core';

package/dist/module.d.mts

@@ -3,12 +3,10 @@ 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;
+    /** Skip default server middleware */
     skipServerMiddleware: boolean;
-    isDevelopment: boolean;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
-  "name": "@meistrari/auth-sdk",
-  "configKey": "authSdk",
-  "version": "0.1.0",
+  "name": "@meistrari/auth-nuxt",
+  "configKey": "telaAuth",
+  "version": "1.0.0-beta.1",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,46 +1,40 @@
 import { defineNuxtModule, createResolver, addServerHandler, addImports, addPlugin } from '@nuxt/kit';
 
-const module = defineNuxtModule({
+const module$1 = defineNuxtModule({
   meta: {
-    name: "@meistrari/auth-sdk",
-    configKey: "authSdk"
+    name: "@meistrari/auth-nuxt",
+    configKey: "telaAuth"
   },
   defaults: {
-    apiUrl: "",
-    useJwt: false,
-    jwtCookieName: "auth-jwt",
-    skipServerMiddleware: false,
-    isDevelopment: false
+    jwtCookieName: "tela-jwt",
+    skipServerMiddleware: 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;
+    nuxt.options.runtimeConfig.public.telaAuth = 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")
+      name: "useTelaSession",
+      as: "useTelaSession",
+      from: resolver.resolve("runtime/composables/session")
+    });
+    addImports({
+      name: "useTelaOrganization",
+      as: "useTelaOrganization",
+      from: resolver.resolve("runtime/composables/organization")
+    });
+    addImports({
+      name: "useTelaApiKey",
+      as: "useTelaApiKey",
+      from: resolver.resolve("runtime/composables/api-key")
     });
     addPlugin(resolver.resolve("./runtime/plugin"));
   }
 });
 
-export { module as default };
+export { module$1 as default };

package/dist/runtime/composables/api-key.d.ts

@@ -0,0 +1,13 @@
+import type { CreateApiKeyPayload, UpdateApiKeyPayload } from '@meistrari/auth-core';
+/**
+ * Composable for managing API keys.
+ *
+ * @returns An object containing API key management functions.
+ */
+export declare function useTelaApiKey(): {
+    createApiKey: (payload: CreateApiKeyPayload) => Promise<any>;
+    updateApiKey: (payload: UpdateApiKeyPayload) => Promise<any>;
+    deleteApiKey: (id: string) => Promise<any>;
+    listApiKeys: () => Promise<any>;
+    getApiKey: (id: string) => Promise<any>;
+};

package/dist/runtime/composables/api-key.js

@@ -0,0 +1,29 @@
+import { useCookie, useRuntimeConfig } from "#app";
+import { createNuxtAuthClient } from "../shared.js";
+export function useTelaApiKey() {
+  const { jwtCookieName, apiUrl } = useRuntimeConfig().public.telaAuth;
+  const tokenCookie = useCookie(jwtCookieName);
+  const authClient = createNuxtAuthClient(apiUrl, () => tokenCookie.value ?? null);
+  async function createApiKey(payload) {
+    return authClient.apiKey.createApiKey(payload);
+  }
+  async function updateApiKey(payload) {
+    return authClient.apiKey.updateApiKey(payload);
+  }
+  async function deleteApiKey(id) {
+    return authClient.apiKey.deleteApiKey(id);
+  }
+  async function listApiKeys() {
+    return authClient.apiKey.listApiKeys();
+  }
+  async function getApiKey(id) {
+    return authClient.apiKey.getApiKey(id);
+  }
+  return {
+    createApiKey,
+    updateApiKey,
+    deleteApiKey,
+    listApiKeys,
+    getApiKey
+  };
+}