@xid-kit/astro

정적 및 서버 렌더링 Astro 사이트를 위한 SSR 미들웨어, 서버 헬퍼, island 클라이언트 싱글턴을 갖춘 Astro 통합.

상태

패키지 상태: 현재 패키지. Astro 통합, SSR 미들웨어, 서버 헬퍼, island 클라이언트 싱글턴이 구현되었습니다. 프로덕션 인프라에서의 실제 IdP 왕복 테스트는 아직 수동 검증 대기 중입니다.

통합 설정

astro.config.mjs에 xidIntegration을 등록하세요. 통합은 addMiddleware를 통해 순서 pre에서 인증 미들웨어를 주입하고 클라이언트 island에 공개 키를 제공합니다.

// astro.config.mjs
import { defineConfig } from 'astro/config'
import { xidIntegration } from '@xid-kit/astro'
import node from '@astrojs/node'

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [
    xidIntegration({
      publishableKey: import.meta.env.PUBLIC_XID_PK,
      jwtKey: import.meta.env.XID_JWT_KEY,
      protectedRoutes: ['/dashboard', '/account'],
      signInUrl: '/sign-in',
    }),
  ],
})

수동 미들웨어(대안)

// src/middleware.ts
import { sequence } from 'astro:middleware'
import { createXidMiddleware } from '@xid-kit/astro'

export const onRequest = sequence(
  createXidMiddleware({
    jwtKey: import.meta.env.XID_JWT_KEY,
    issuer: 'https://xid.dev',
    protectedRoutes: ['/dashboard', '/account'],
    signInUrl: '/sign-in',
  }),
)

.astro 페이지의 서버 측 인증

---
// src/pages/dashboard.astro
import { getAuth, currentUser } from '@xid-kit/astro/server'

const auth = getAuth(Astro.locals)
if (!auth.userId) return Astro.redirect('/sign-in')

const user = await currentUser(Astro.locals, {
  secretKey: import.meta.env.XID_SECRET_KEY,
})
---

<h1>Welcome, {user?.primaryEmailAddress}</h1>

클라이언트 island

// src/components/SignOutButton.tsx
import { getClient } from '@xid-kit/astro/client'

export default function SignOutButton() {
  const client = getClient()

  const handleSignOut = async () => {
    await client.signOut()
    window.location.href = '/'
  }

  return <button onClick={handleSignOut}>Sign out</button>
}

Astro.locals 타입 정의

Astro.locals.xidAuth에 대한 완전한 타입 커버리지를 얻으려면 src/env.d.ts에 타입 참조를 추가하세요.

/// <reference path="../node_modules/@xid-kit/astro/src/locals.d.ts" />

내보내진 API

내보내기	종류	모듈
`xidIntegration`	Astro 통합 팩토리	`@xid-kit/astro`
`createXidMiddleware`	미들웨어 팩토리	`@xid-kit/astro`
`getAuth, currentUser, xidClient`	서버 헬퍼	`@xid-kit/astro/server`
`getClient, initClient, resetClient`	island 클라이언트 싱글턴	`@xid-kit/astro/client`

보안 참고 사항

jwtKey는 JWKS 공개 키이므로 네트워크 호출 없는 검증에 안전하게 사용할 수 있으며 개인 키를 포함하지 않습니다.
secretKey(sk_live_xxx)는 반드시 서버 측에서만 사용해야 합니다. island나 클라이언트 번들에 전달하지 마세요.
보호된 라우트는 페이지 핸들러가 실행되기 전에 미들웨어에서 Response.redirect를 통해 리디렉션됩니다. 클라이언트 측 JS가 필요하지 않습니다.
네트워크 호출 없는 JWT 검증 경로를 위해 @xid-kit/backend authenticateRequest를 재내보냅니다.