@meistrari/auth-nuxt 2.3.1 → 3.0.0

package/README.md

@@ -1,421 +1,16 @@
 # @meistrari/auth-nuxt
 
-A Nuxt module that provides comprehensive authentication, organization management, and API key capabilities.
+A Nuxt module for authentication, organization management, and API key capabilities.
 
-## Installation
-
-```bash
-npm install @meistrari/auth-nuxt
-```
-
-## Setup
-
-Add the module to your `nuxt.config.ts`:
-
-```typescript
-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.
-
-```vue
-<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:**
-```typescript
-await signInWithEmailAndPassword({
-    email: 'user@example.com',
-    password: 'secure-password',
-})
-```
-
-**Social Authentication:**
-```typescript
-await signInWithSocialProvider({
-    provider: 'google', // or 'microsoft'
-    callbackURL: '/',
-    errorCallbackURL: '/login?error=true'
-})
-```
-
-**SAML SSO:**
-```typescript
-await signInWithSaml({
-    email: 'user@example.com',
-    callbackURL: '/',
-    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>
-
-<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:**
-```typescript
-await updateOrganization({
-    name: 'New Organization Name',
-    logo: 'https://example.com/logo.png',
-    settings: { /* custom settings */ }
-})
-```
-
-**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')
+## Auth Types
 
-// 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, 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:
-
-```typescript
-// 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:
+This SDK supports two authentication models:
 
-```typescript
-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
-
-```typescript
-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')
+- **Application Authentication (recommended)**: Use this for product applications that need end-user authentication and authorization scoped to a specific application. See [Application Authentication Guide](./docs/APPLICATION_AUTH.md).
+- **First-Party Authentication**: Use this only for trusted first-party tools that interact directly with the Auth API in an administrative way, such as the Auth Dashboard and Backoffice. See [First-Party Authentication Guide](./docs/FIRST_PARTY_AUTH.md).
 
-// 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
-
-```typescript
-import { APIError } from '@meistrari/auth-nuxt/core'
+## Installation
 
-try {
-    await signInWithEmailAndPassword({
-        email: 'user@example.com',
-        password: 'wrong-password',
-    })
-}
-catch (error) {
-    if (error instanceof APIError) {
-        console.error('Authentication failed:', error.message, error.status)
-    }
-}
+```bash
+npm install @meistrari/auth-nuxt
 ```
-
-## 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)

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@meistrari/auth-nuxt",
   "configKey": "telaAuth",
-  "version": "2.3.1",
+  "version": "2.1.3",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/composables/application-auth.d.ts

@@ -40,6 +40,7 @@ export declare function useTelaApplicationAuth(): {
     getAvailableOrganizations: () => Promise<FullOrganization[]>;
     switchOrganization: (organizationId: string) => Promise<void>;
     refreshToken: () => Promise<void>;
+    getToken: () => Promise<string | null | undefined>;
     user: import("vue").Ref<{
         id: string;
         createdAt: Date;

package/dist/runtime/composables/application-auth.js

@@ -1,6 +1,7 @@
 import { navigateTo, useCookie, useRuntimeConfig } from "#app";
 import { AuthorizationFlowError, isTokenExpired, RefreshTokenExpiredError, UserNotLoggedInError } from "@meistrari/auth-core";
 import { useApplicationSessionState } from "./state.js";
+import { willTokenExpireIn } from "../helpers/token.js";
 const FIFTEEN_MINUTES = 60 * 15;
 const ONE_MINUTE = 60 * 1e3;
 export function useTelaApplicationAuth() {
@@ -87,6 +88,13 @@ export function useTelaApplicationAuth() {
       throw error;
     }
   }
+  async function getToken() {
+    const shouldRefresh = accessTokenCookie.value ? willTokenExpireIn(accessTokenCookie.value, ONE_MINUTE * 2) : true;
+    if (shouldRefresh) {
+      await refreshToken();
+    }
+    return accessTokenCookie.value;
+  }
   return {
     ...state,
     login,
@@ -94,6 +102,7 @@ export function useTelaApplicationAuth() {
     initSession,
     getAvailableOrganizations,
     switchOrganization,
-    refreshToken
+    refreshToken,
+    getToken
   };
 }

package/dist/runtime/composables/state.d.ts

@@ -100,13 +100,12 @@ export declare function useSessionState(): {
 export declare function useOrganizationState(): {
     activeOrganization: import("vue").Ref<FullOrganization | null, FullOrganization | null>;
     activeMember: import("vue").Ref<{
-        [x: string]: string | number | boolean | string[] | Record<string, any> | (string & Record<never, never>) | Date | number[] | undefined;
         id: string;
         organizationId: string;
         role: "org:admin" | "org:member" | "org:reviewer";
         createdAt: Date;
         userId: string;
-        teamId?: string | undefined | undefined;
+        teamId?: string | undefined | undefined | undefined;
         user: {
             id: string;
             email: string;
@@ -114,13 +113,12 @@ export declare function useOrganizationState(): {
             image?: string | undefined;
         };
     } | null, {
-        [x: string]: string | number | boolean | string[] | Record<string, any> | (string & Record<never, never>) | Date | number[] | undefined;
         id: string;
         organizationId: string;
         role: "org:admin" | "org:member" | "org:reviewer";
         createdAt: Date;
         userId: string;
-        teamId?: string | undefined | undefined;
+        teamId?: string | undefined | undefined | undefined;
         user: {
             id: string;
             email: string;

package/dist/runtime/helpers/token.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Parses a JWT token to extract its expiration time
+ *
+ * @param token - The JWT token string
+ * @returns The expiration timestamp in milliseconds, or null if parsing fails
+ */
+export declare function parseTokenExpiry(token: string): number | null;
+/**
+ * Checks if a JWT token will expire within a certain time window, or if it is already expired
+ *
+ * @param token - The JWT token string
+ * @param timeWindow - The time window in milliseconds
+ * @returns True if the token will expire within the time window, false otherwise
+ */
+export declare function willTokenExpireIn(token: string, timeWindow: number): boolean | 0;

package/dist/runtime/helpers/token.js

@@ -0,0 +1,19 @@
+import { decodeJwt } from "jose";
+export function parseTokenExpiry(token) {
+  try {
+    const payload = decodeJwt(token);
+    if (!payload.exp)
+      return null;
+    return payload.exp * 1e3;
+  } catch {
+    return null;
+  }
+}
+export function willTokenExpireIn(token, timeWindow) {
+  const now = Date.now();
+  const expiry = parseTokenExpiry(token);
+  if (expiry === null) {
+    return true;
+  }
+  return expiry && expiry - timeWindow <= now;
+}

package/dist/runtime/plugins/application-token-refresh.js

@@ -1,22 +1,12 @@
 import { defineNuxtPlugin, useCookie, useRuntimeConfig } from "#app";
 import { isTokenExpired } from "@meistrari/auth-core";
-import { decodeJwt } from "jose";
 import { useTelaApplicationAuth } from "../composables/application-auth.js";
 import { useApplicationSessionState } from "../composables/state.js";
 import { createNuxtAuthClient } from "../shared.js";
+import { parseTokenExpiry } from "../helpers/token.js";
 const SEVEN_DAYS = 60 * 60 * 24 * 7;
 const FIFTEEN_MINUTES = 60 * 15;
 const TWO_MINUTES = 2 * 60 * 1e3;
-function parseTokenExpiry(token) {
-  try {
-    const payload = decodeJwt(token);
-    if (!payload.exp)
-      return null;
-    return payload.exp * 1e3;
-  } catch {
-    return null;
-  }
-}
 export default defineNuxtPlugin({
   name: "tela-application-token-refresh",
   enforce: "post",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/auth-nuxt",
-  "version": "2.3.1",
+  "version": "3.0.0",
   "type": "module",
   "exports": {
     ".": {
@@ -27,12 +27,9 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt-module-build build"
-  },
   "dependencies": {
-    "@meistrari/auth-core": "1.11.1",
-    "jose": "6.1.3"
+    "jose": "6.1.3",
+    "@meistrari/auth-core": "1.11.3"
   },
   "peerDependencies": {
     "nuxt": "^3.0.0 || ^4.0.0",
@@ -52,5 +49,8 @@
     "unbuild": "3.6.1",
     "vitest": "3.2.4",
     "vue-tsc": "3.0.6"
+  },
+  "scripts": {
+    "build": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt-module-build build"
   }
-}
+}