@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

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

Registra xidIntegration en astro.config.mjs. La integración inyecta el middleware de autenticación mediante addMiddleware en el orden pre y proporciona la clave publicable a las islas de cliente.

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

Middleware manual (alternativa)

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

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 () => {
    await client.signOut()
    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.

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

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.
Re-exporta @xid-kit/backend authenticateRequest para la ruta de verificación JWT sin llamadas de red.