@xid-kit/nuxt

Nuxt 3 module with H3/Nitro server middleware and auto-imported Vue composables for SSR and full-stack apps.

Status

Package status is Current package. The Nuxt module, H3/Nitro server middleware, and auto-imported composables are implemented. A real IdP round-trip on production infrastructure is still pending manual verification.

Module setup

Add @xid-kit/nuxt to the modules array. The module auto-imports all @xid-kit/vue composables and registers a client-only plugin that installs XidPlugin.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@xid-kit/nuxt'],

  runtimeConfig: {
    public: {
      xidApiUrl: '', // optional: omit for same-origin deployment
    },
  },
})

Composables (auto-imported)

<script setup lang="ts">
// No import needed -- Nuxt auto-imports from @xid-kit/vue
const auth = useAuth()
const userRef = useUser()
const orgRef = useOrganization()
const sessionRef = useSession()
</script>

<template>
  <div v-if="auth.isSignedIn">
    Signed in as {{ auth.userId }}
    <button @click="auth.signOut()">Sign out</button>
  </div>
</template>

Server middleware (JWT auth)

createXidServerMiddleware returns an H3 event handler that verifies the JWT networklessly and writes event.context.xidAuth. Place the file in server/middleware/. Nitro registers files in that directory as global middleware.

// server/middleware/xid.ts
import { createXidServerMiddleware } from '@xid-kit/nuxt'

export default createXidServerMiddleware({
  jwtKey: JSON.parse(process.env.XID_JWKS_PUBLIC_KEY!),
  issuer: 'https://acme.xid.dev',
  protectedRoutes: ['/api/admin'],
})

Reading auth in server routes

// server/routes/api/me.get.ts
import { getXidAuth } from '@xid-kit/nuxt'

export default defineEventHandler((event) => {
  const auth = getXidAuth(event)
  if (!auth.userId) {
    throw createError({ statusCode: 401, message: 'Unauthorized' })
  }
  return { userId: auth.userId, orgId: auth.orgId }
})

Exported API

Export	Kind	Purpose
`createXidServerMiddleware`	function	H3 event handler factory: verifies JWT, writes event.context.xidAuth, protects routes
`getXidAuth`	function	Read AuthResult from event.context.xidAuth in server routes and handlers
`XID_AUTH_CONTEXT_KEY`	string constant	Context key used to store auth result (‘xidAuth’)
`XidServerMiddlewareOptions`	type	jwtKey, issuer, authorizedParties, cookieName, protectedRoutes, onUnauthenticated

Security notes

event.context.xidAuth is server-side only and is never sent to the browser.
The middleware strips any client-supplied auth tokens and re-injects only the verified result.
Place the middleware file in server/middleware/ to ensure it covers all routes as a global Nitro middleware.