@xid-kit/astro

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

상태

Registry 상태: UNPUBLISHED. 이 SDK는 저장소 소스 checkout에서만 설치하고 외부 package registry를 사용하지 마세요.

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

통합 설정

astro.config.mjs에 xidIntegration을 등록합니다. 이 integration은 addMiddleware를 사용해 pre 순서로 server middleware를 주입하고 verification material을 server-side에 유지하며 client islands에 필요한 직렬화 가능한 browser mode configuration만 노출합니다.

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

const jwtKeyJson = process.env.XID_JWKS_PUBLIC_KEY
if (!jwtKeyJson) throw new Error('Missing XID_JWKS_PUBLIC_KEY')

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [
    xidIntegration({
      // This combined SSR setup requires Core routes on the application's exact origin.
      browser: { mode: 'same-origin' },
      jwtKey: JSON.parse(jwtKeyJson),
      issuer: 'https://app.example.com',
      sessionTokenExchange: { endpoint: '/v1/sessions/token' },
      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: JSON.parse(import.meta.env.XID_JWKS_PUBLIC_KEY),
    issuer: 'https://xid.dev',
    sessionTokenExchange: { endpoint: '/v1/sessions/token' },
    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 () => {
    const result = await client.signOut()
    if (!result.ok) throw new Error(result.error.message)
    window.location.href = '/'
  }

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

Astro.locals 타입 정의

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

import '@xid-kit/astro/locals'

내보내진 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가 필요하지 않습니다.
Core opaque cookie는 exact same-origin session-token endpoint로만 전달되며 값을 로컬에서 검증하지 않습니다