@xid-kit/astro

Astro integration with SSR middleware, server helpers, and island client singleton for static and server-rendered Astro sites.

Status

Package status is Current package. The Astro integration, SSR middleware, server helpers, and island client singleton are implemented. A real IdP round-trip on production infrastructure is still pending manual verification.

Integration setup

Register xidIntegration in astro.config.mjs. The integration injects the auth middleware via addMiddleware at order pre and provides the publishable key to client islands.

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

Manual middleware (alternative)

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

Server-side auth in .astro pages

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

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

Add the type reference to src/env.d.ts to get full type coverage on Astro.locals.xidAuth.

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

Exported API

Export	Kind	Module
`xidIntegration`	Astro integration factory	`@xid-kit/astro`
`createXidMiddleware`	middleware factory	`@xid-kit/astro`
`getAuth, currentUser, xidClient`	server helpers	`@xid-kit/astro/server`
`getClient, initClient, resetClient`	island client singleton	`@xid-kit/astro/client`

Security notes

jwtKey is a JWKS public key; it is safe for networkless verification and does not contain a private key.
secretKey (sk_live_xxx) must stay server-side only; never pass it to an island or client bundle.
Protected routes redirect via Response.redirect in middleware before any page handler runs; no client-side JS is required.
Re-exports @xid-kit/backend authenticateRequest for the networkless JWT verification path.