Astro

The @authdog/astro SDK provides cookie-reading middleware, userinfo-backed server validation, logout, and a browser token bootstrap for SSR-capable Astro sites.

Install

npm install @authdog/astro

yarn add @authdog/astro

pnpm add @authdog/astro

bun add @authdog/astro

deno add npm:@authdog/astro

Requires Astro ^5 or ^6 with SSR enabled (output: "server" or "hybrid"). The package ships @authdog/astro/server and @authdog/astro/client.

Add the middleware

authdogMiddleware populates Astro.locals.authdog ({ session, isAuthenticated }) on every request. session is the raw authdog-session cookie, and isAuthenticated means only that this cookie exists:

// src/middleware.ts
import { defineMiddleware } from "astro:middleware"
import { authdogMiddleware } from "@authdog/astro/server"

export const onRequest = defineMiddleware(
  authdogMiddleware({
    publicKey: import.meta.env.PUBLIC_AUTHDOG_PUBLIC_KEY ?? "",
  }),
)

Declare the locals type in src/env.d.ts:

declare namespace App {
  interface Locals {
    authdog: import("@authdog/astro/server").AuthdogLocals
  }
}

Read the user in a page

createAuthdogServer().getUser() validates the cookie through Authdog userinfo. Use that result, not the middleware boolean, as the authentication decision:

---
import { createAuthdogServer } from "@authdog/astro/server"

const authdog = createAuthdogServer({
  publicKey: import.meta.env.PUBLIC_AUTHDOG_PUBLIC_KEY ?? "",
})

const profile = await authdog.getUser(Astro.request).catch(() => null)
if (!profile) {
  return Astro.redirect("/sign-in")
}
---

<p>Signed in as {profile.user.emails?.[0]?.value}</p>

Sign out

Expose an endpoint that calls authdog.logout, which clears the cookie and redirects:

// src/pages/api/logout.ts
import type { APIRoute } from "astro"
import { createAuthdogServer } from "@authdog/astro/server"

const authdog = createAuthdogServer({
  publicKey: import.meta.env.PUBLIC_AUTHDOG_PUBLIC_KEY ?? "",
})

export const GET: APIRoute = ({ request }) => authdog.logout(request)

Client bootstrap

Run initAuthdog() once on the client to shape-check ?token=, store it in localStorage, remove it from the URL, and reload:

<script>
  import { initAuthdog } from "@authdog/astro/client"
  initAuthdog()
</script>

This browser bootstrap does not create the server's authdog-session cookie. Your callback/backend must validate the token and set that cookie as HttpOnly, Secure, and SameSite; the package does not include that exchange. Pair validated identity with authorization.

Next steps

• Sign up & sign in: the flows behind the redirect.
• Backend requests: the verification model, in depth.
• Handbook: runnable example for this stack.