@xid-kit/nuxt

带 H3/Nitro 服务端 middleware 和自动导入 Vue composable 的 Nuxt 3 模块，适用于 SSR 和全栈应用。

状态

包状态为 当前包。Nuxt 模块、H3/Nitro 服务端 middleware 和自动导入 composable 已实现。在真实生产基础设施上的 IdP 往返验证仍待人工核实。

模块配置

将 @xid-kit/nuxt 添加到 modules 数组。该模块自动导入所有 @xid-kit/vue composable，并注册安装 XidPlugin 的仅客户端插件。

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

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

Composable（自动导入）

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

服务端 middleware（JWT 认证）

createXidServerMiddleware 返回一个 H3 事件处理器，以 networkless 方式验证 JWT 并写入 event.context.xidAuth。将文件放在 server/middleware/ 中，使 Nitro 将其注册为全局 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`	字符串常量	用于存储认证结果的上下文 key（‘xidAuth’）
`XidServerMiddlewareOptions`	type	jwtKey、issuer、authorizedParties、cookieName、protectedRoutes、onUnauthenticated

安全注意事项

event.context.xidAuth 仅限服务端使用，不会发送到浏览器。
middleware 会剥离客户端提供的任何认证 token，并重新注入已验证的结果。
将 middleware 文件放在 server/middleware/ 中，以确保它作为全局 Nitro middleware 覆盖所有路由。