@xid-kit/nuxt

SSR 및 풀스택 앱을 위한 H3/Nitro 서버 미들웨어와 자동 가져오기 Vue composable이 있는 Nuxt 3 모듈.

상태

패키지 상태: 현재 패키지. Nuxt 모듈, H3/Nitro 서버 미들웨어, 자동 가져오기 composable이 구현되었습니다. 프로덕션 인프라에서의 실제 IdP 왕복 테스트는 아직 수동 검증 대기 중입니다.

모듈 설정

modules 배열에 @xid-kit/nuxt를 추가하세요. 이 모듈은 모든 @xid-kit/vue composable을 자동으로 가져오고 XidPlugin을 설치하는 클라이언트 전용 플러그인을 등록합니다.

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

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

Composables (자동 가져오기)

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

서버 미들웨어(JWT 인증)

createXidServerMiddleware는 JWT를 네트워크 호출 없이 검증하고 event.context.xidAuth에 결과를 기록하는 H3 이벤트 핸들러를 반환합니다. Nitro가 전역 미들웨어로 등록할 수 있도록 파일을 server/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'],
})

서버 라우트에서 인증 읽기

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

내보내진 API

내보내기	종류	목적
`createXidServerMiddleware`	function	H3 이벤트 핸들러 팩토리: JWT를 검증하고 event.context.xidAuth에 기록하며 라우트를 보호합니다
`getXidAuth`	function	서버 라우트와 핸들러의 event.context.xidAuth에서 AuthResult를 읽습니다
`XID_AUTH_CONTEXT_KEY`	문자열 상수	인증 결과를 저장하는 데 사용되는 컨텍스트 키(‘xidAuth’)
`XidServerMiddlewareOptions`	type	jwtKey, issuer, authorizedParties, cookieName, protectedRoutes, onUnauthenticated

보안 참고 사항

event.context.xidAuth는 서버 전용이며 브라우저로 전송되지 않습니다.
미들웨어는 클라이언트가 제공한 인증 토큰을 제거하고 검증된 결과만 다시 주입합니다.
모든 라우트를 전역 Nitro 미들웨어로 커버할 수 있도록 미들웨어 파일을 server/middleware/에 배치하세요.