@xenterprises/nuxt-x-auth-nile

@xenterprises/nuxt-x-auth-nile

Nuxt 4 authentication layer providing client-only (SPA) authentication against a Nile Auth API via @niledatabase/client (^5.3.1). Includes built-in auth pages, multi-tenancy management, email verification gate, two-factor authentication (TOTP & email), magic links, OAuth/SSO buttons, route guard, and cross-component shared state.

ssr: false — The browser talks to a Nile Auth API. There are no Nitro/server handlers in this layer; mount endpoints on same-origin /api via @xenterprises/fastify-xauth-nile (or an equivalent proxy).

Features

• Multi-Tenancy: Organization creation, switching, settings, and member management. Active tenant state automatically synchronizes with cookie (nile.tenant-id) and request headers (x-tenant-id).
• Email Verification Gate: Built-in route gate (enabled by default) protecting authenticated routes until email verification is confirmed against authoritative /me.
• Two-Factor Authentication (MFA): Authenticator setup with QR code and secret key, sign-in challenge handling, and MFA removal flow.
• Magic Links: Passwordless email sign-in using Nile's email provider.
• Shared State: Built with persistent Nuxt useState refs across layout, pages, and components with automatic probe deduplication.
• Aggregator Parity: Compatible with workspace conventions ($getAuthToken, $getCurrentUser, $logout, $xTenantId, $xTenantHeaders()).
• Branded Layouts: Grizzly photo card with glassmorphism or split hero layouts.

Installation

npm install @xenterprises/nuxt-x-auth-nile

Add the layer to your nuxt.config.ts:

export default defineNuxtConfig({
  extends: ["@xenterprises/nuxt-x-auth-nile"],
});

Consumer Quickstart

Consuming applications configure the layer via app/app.config.ts and environment variables.

1. Configure Environment (.env)

# API origin (empty = same origin as the frontend)
NUXT_PUBLIC_NILE_BASE_URL=

# Base path prefix on that origin (default /api)
NUXT_PUBLIC_NILE_BASE_PATH=/api

2. Configure app/app.config.ts

export default defineAppConfig({
  xAuth: {
    redirects: {
      afterLogin: "/dashboard",
    },
    features: {
      oauth: true,
      mfa: true,
      magicLink: true,
      requireEmailVerified: true,
      signup: true,
    },
    tenant: {
      enabled: true,
      required: false,
      signup: {
        collectName: "optional", // "off" | "optional" | "required"
      },
    },
    oauthProviders: [
      { id: "google", label: "Google", icon: "i-simple-icons-google" },
      { id: "github", label: "GitHub", icon: "i-simple-icons-github" },
    ],
  },
});

Backend Contract (Fastify / Proxy)

Browser requests talk to a same-origin /api prefix mounted by @xenterprises/fastify-xauth-nile (or backend proxy).

Host Requirements

1. Cookie Path: Configure cookiePath: "/" on the xAuthNile instance (or host proxy) so Path=/ is returned to the client and session cookies cover non-API routes.
2. Tenant Context: Pass the nile.tenant-id cookie and x-tenant-id header into Nile's server context.
3. Tenants Mount: Mount GET /tenants (part of the standard nile-auth surface; resolves userId from session itself).
4. SMTP: Configure SMTP in the Nile console for email verification, magic link, and password reset emails.
5. Auto-send Verification: Fastify plugin handles auto-sending verification emails on signup 400 verification-required; this layer expects that and does not POST /api/auth/verify-email after signup.

Configuration Reference (xAuth)

Composables

useXAuth()

High-level authentication composable with toast notifications, shared reactive state, and automatic routing.

const {
  user,                 // Ref<NileUser | null>
  isAuthenticated,      // Ref<boolean>
  isLoading,            // Ref<boolean>
  login,                // (email, password) => Promise<NileUser | null>
  signup,               // (email, password, options?) => Promise<NileUser | null>
  loginWithMagicLink,   // (email) => Promise<boolean>
  logout,               // () => Promise<boolean>
  restore,              // ({ force? }) => Promise<NileUser | null>
  refresh,              // () => Promise<NileUser | null>
  updateProfile,        // ({ name }) => Promise<{ ok: boolean } | { error: string }>
  getAuthHeaders,       // () => Promise<Record<string, string>>
  authorizer,           // Raw @niledatabase/client Authorizer singleton
} = useXAuth();

useXTenant()

Multi-tenancy composable managing user organizations, active selection, and member access.

const {
  tenants,              // Ref<NileTenant[]>
  activeTenantId,       // Ref<string | null>
  activeTenant,         // ComputedRef<NileTenant | null>
  setActiveTenant,      // (id: string | null) => void
  fetchTenants,         // () => Promise<NileTenant[]>
  createTenant,         // (name: string) => Promise<{ status: "ok", data: NileTenant } | ...>
  renameTenant,         // (id: string, name: string) => Promise<...>
  deleteTenant,         // (id: string) => Promise<...>
  fetchMembers,         // (tenantId: string) => Promise<NileMember[]>
  addMember,            // (tenantId: string, userId: string) => Promise<...>
  removeMember,         // (tenantId: string, userId: string) => Promise<...>
  leaveTenant,          // (tenantId: string, userId: string) => Promise<...>
} = useXTenant();

useXNileApi()

Authenticated HTTP client built on ofetch rooted at getApiRoot() (runtimeConfig.public.nile) with credentials inclusion, CSRF helper, and error normalization.

Plugin Injections

The layer provides standard global helpers:

• nuxtApp.$getAuthToken: Returns null (Nile sessions use cookies).
• nuxtApp.$getCurrentUser: Returns the active NileUser object (id, name, email, avatar, picture, emailVerified, multiFactor).
• nuxtApp.$logout: Signs out the user, resets state, and redirects.
• nuxtApp.$xTenantId: Reactive Ref<string | null> with the active organization ID.
• nuxtApp.$xTenantHeaders(): Returns { [headerName]: activeTenantId } when an organization is active.

In consuming apps utilizing nuxt-x-app, inject tenant headers into API requests:

// app.config.ts
export default defineAppConfig({
  xApp: {
    defaultHeaders: () => useNuxtApp().$xTenantHeaders(),
  },
});

License

See LICENSE in repository.