@meistrari/auth-nuxt

A Nuxt module that provides comprehensive authentication, organization management, and API key capabilities.

Installation

npm install @meistrari/auth-nuxt

Prerequisites

Before setting up the SDK, make sure the following are configured in the Auth API:

1. Allowed Origins: Your application URL (e.g., https://your-app.com) must be added to the allowed origins list in the Auth API. This ensures the Auth API accepts requests from your application.
2. Allowed Email Domains: The email domains of users who will access the application must be added to the allowed email domains list in the Auth API. For example, if your users sign in with @company.com emails, that domain must be whitelisted.

Setup

Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
    modules: ['@meistrari/auth-nuxt'],
    telaAuth: {
        apiUrl: 'https://your-auth-api.com',
        jwtCookieName: 'tela-jwt', // Optional: custom JWT cookie name
        skipServerMiddleware: false, // Optional: skip automatic server middleware
    }
})

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiUrl | string | Required | Base URL of your authentication API | | jwtCookieName | string | 'tela-jwt' | Name of the JWT cookie | | skipServerMiddleware | boolean | false | Skip automatic server-side auth context setup |

Composables

The SDK provides three main composables for different aspects of authentication and organization management:

useTelaSession

Manages user sessions, authentication, and sign-in/sign-out operations.

<script setup>
const { user, session, signOut, getToken } = useTelaSession()

// Access current user
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(() => {
    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>

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

Password Management:

• requestPasswordReset(email, callbackURL) - Initiates password reset
• resetPassword(token, password) - Completes password reset

Sign-In Examples

Email and Password:

await signInWithEmailAndPassword({
    email: '[email protected]',
    password: 'secure-password',
})

Social Authentication:

await signInWithSocialProvider({
    provider: 'google', // or 'microsoft'
    callbackURL: '/',
    errorCallbackURL: '/login?error=true'
})

SAML SSO:

await signInWithSaml({
    email: '[email protected]',
    callbackURL: '/',
    errorCallbackURL: '/login?error=true'
})

useTelaOrganization

Manages organizations, members, invitations, and teams.

<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: '[email protected]',
    role: 'member'
})
</script>

<template>
    <div v-if="activeOrganization">
        <h2>{{ activeOrganization.name }}</h2>
        <p>{{ activeOrganization.members.length }} members</p>
    </div>
</template>

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:

await updateOrganization({
    name: 'New Organization Name',
    logo: 'https://example.com/logo.png',
    settings: { /* custom settings */ }
})

Invite Member:

await inviteUserToOrganization({
    userEmail: '[email protected]',
    role: 'admin', // or 'member', 'reviewer'
    teamId: 'team-id', // optional
    resend: false // optional: resend if invitation exists
})

Create and Manage Teams:

// 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.

<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

// server/api/protected.ts
export default defineEventHandler(async (event) => {
    // Authentication context is automatically available
    const { user, workspace } = event.context.auth

    if (!user) {
        throw createError({
            statusCode: 401,
            statusMessage: 'Unauthorized'
        })
    }

    return {
        message: `Hello, ${user.email}!`,
        userId: user.id
    }
})

Custom Middleware

Create custom server middleware using the provided helper:

// server/middleware/custom.ts
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
    if (user) {
        console.log(`Authenticated user: ${user.email}`)
    }
})

Types

The SDK exports comprehensive TypeScript types from the core package:

import type {
    User,
    Session,
    Organization,
    FullOrganization,
    Member,
    Invitation,
    Team,
    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 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

JWT Token Management

The SDK automatically manages JWT tokens:

• 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

The handshake flow ensures secure authentication:

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

import { isTokenExpired, validateToken, extractTokenPayload } from '@meistrari/auth-nuxt/core'

// 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')

// 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 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

import { APIError } from '@meistrari/auth-nuxt/core'

try {
    await signInWithEmailAndPassword({
        email: '[email protected]',
        password: 'wrong-password',
    })
}
catch (error) {
    if (error instanceof APIError) {
        console.error('Authentication failed:', error.message, error.status)
    }
}

Migration

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)