@xid-kit/nuxt

SSR およびフルスタックアプリ向けの H3/Nitro サーバーミドルウェアと自動インポート Vue コンポーザブルを備えた Nuxt 3 モジュール。

状態

パッケージステータス：現行パッケージ。Nuxt モジュール、H3/Nitro サーバーミドルウェア、自動インポートコンポーザブルが実装済みです。本番インフラでの実際の IdP ラウンドトリップはまだ手動検証待ちです。

モジュールセットアップ

modules 配列に @xid-kit/nuxt を追加します。モジュールはすべての @xid-kit/vue コンポーザブルを自動インポートし、XidPlugin をインストールするクライアント専用プラグインを登録します。

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

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

コンポーザブル（自動インポート）

<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/ に配置します。