Elysia

@authdog/elysia resolves Authdog sessions for Elysia. Its plugin injects session context into handlers and exposes an authentication guard.

Availability

Unreleased: @authdog/elysia is not on npm at the time of writing (the registry returns 404). bun add @authdog/elysia will fail until it is published. Source lives in the `packages/elysia` directory of the web SDK repository (version 0.3.0, configured to publish to npm with public access). Vendor a repository checkout until a release ships.

Install

npm install @authdog/elysia elysia

yarn add @authdog/elysia elysia

pnpm add @authdog/elysia elysia

bun add @authdog/elysia elysia

deno add npm:@authdog/elysia npm:elysia

elysia is a peer dependency (^1.0.0); @authdog/node-commons installs automatically. The SDK is aimed at Bun-first Elysia apps; logout returns a Web Response, so it is not tied to one runtime.

Configure

Create one instance with your environment's public key (pk_...):

import { Elysia } from "elysia"
import { createAuthdog } from "@authdog/elysia"

const authdog = createAuthdog({ publicKey: process.env.PK_AUTHDOG! })

The key is safe to expose. It is parsed once at startup; a missing key throws Public key is not defined, and malformed keys or identity hosts outside the trusted HTTPS allowlist fail immediately. createAuthdog also accepts an optional secretKey, which is reserved and currently unused.

Attach the session

Apply the plugin on the root app before routes:

const app = new Elysia().use(authdog.attachSession())

attachSession() returns an Elysia plugin that derives a global authdog property into every handler context. It prefers the authdog-session cookie, then reads Authorization: Bearer <token>. A valid token requires a successful userinfo response (meta.code === 200 with a user). Missing, invalid, or unverifiable tokens never fail the request or return a 500; they yield anonymous context:

{
  token: string | null,
  user: unknown | null,
  isAuthenticated: boolean,
  userInfo?: UserInfoResponse | null,
}

attachSession({ fetchUser: false }) only surfaces the unverified token. It leaves user null and isAuthenticated false, so requireAuth rejects the request with 401. Use this option only when separate server-side validation and enforcement replace Authdog's gate.

Protect a route

requireAuth (a beforeHandle hook in Elysia) is the security boundary and returns 401 {"error":"Unauthorized"} unless isAuthenticated is true:

new Elysia()
  .use(authdog.attachSession())
  .get("/me", ({ authdog: ctx }) => ctx.user, {
    beforeHandle: authdog.requireAuth,
  })

Authentication identifies a caller; it does not authorize actions. Apply your authorization checks after requireAuth. Client-side checks never protect server routes.

Sign out

logout expires the authdog-session cookie (HttpOnly, SameSite=Lax, Secure when NODE_ENV is production) and redirects (302) to a sanitized same-origin redirect_uri, falling back to /:

new Elysia().use(authdog.attachSession()).get("/logout", authdog.logout)

This does not revoke a bearer token or end an upstream identity-provider session.

Next steps

• Backend requests
• Fastify
• Express
• Calling the REST API