@xid-kit/nuxt

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

Status

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

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'],
  xid: {
    browser: {
      mode: 'oidc',
      issuer: 'https://xid.dev',
      clientId: 'client_abc123',
      redirectUri: 'https://app.example.com/auth/callback',
    },
  },
})

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 handler that verifies a Bearer or explicit application JWT and writes event.context.xidAuth. Configure same-origin Core sessions through sessionTokenExchange; H3 v1 relative URLs also require a trusted requestOrigin. Place the file in server/middleware/ for global Nitro registration.

// 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',
  sessionTokenExchange: { endpoint: '/v1/sessions/token' },
  requestOrigin: process.env.XID_APP_ORIGIN!,
  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, jwtCookieName, sessionTokenExchange, requestOrigin, 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.