@xid-kit/astro

Integración con Astro: middleware SSR, utilidades de servidor y singleton de cliente isla para sitios Astro estáticos y renderizados en servidor.

Estado

Estado del registro: UNPUBLISHED. Instala este SDK únicamente desde el checkout del código fuente del repositorio; no uses un registro de paquetes externo.

El estado del paquete es Paquete actual. La integración con Astro, el middleware SSR, las utilidades de servidor y el singleton de cliente isla están implementados. Una prueba de ida y vuelta real contra un IdP en infraestructura de producción está pendiente de verificación manual.

Configuración de integración

Registre xidIntegration en astro.config.mjs. La integración inyecta middleware de servidor con addMiddleware en el orden pre, mantiene el material de verificación en el servidor y solo expone la configuración serializable del modo de navegador que necesitan las islas de cliente.

// 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',
    }),
  ],
})

Middleware manual (alternativa)

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

Autenticación en el servidor en páginas .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>

Isla de cliente

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

Tipado de Astro.locals

Añade la referencia de tipos en src/env.d.ts para obtener cobertura de tipos completa sobre Astro.locals.xidAuth.

import '@xid-kit/astro/locals'

API exportada

Exportar	Tipo	Módulo
`xidIntegration`	Fábrica de integración para Astro	`@xid-kit/astro`
`createXidMiddleware`	fábrica de middleware	`@xid-kit/astro`
`getAuth, currentUser, xidClient`	utilidades de servidor	`@xid-kit/astro/server`
`getClient, initClient, resetClient`	singleton de cliente isla	`@xid-kit/astro/client`

Notas de seguridad

jwtKey es una clave pública JWKS; es apta para verificación sin llamadas de red y no contiene clave privada.
secretKey (sk_live_xxx) debe permanecer exclusivamente en el servidor; nunca lo pases a una isla ni al bundle del cliente.
Las rutas protegidas redirigen mediante Response.redirect en el middleware antes de que se ejecute cualquier manejador de página; no se requiere JS del lado del cliente.
Reenvía las cookies opacas de Core solo a un endpoint session-token del mismo origen exacto; el valor nunca se verifica localmente