Authdog Logo

@authdog/hono resolves Authdog sessions for Hono. Its middleware stores session context on the Hono context and exposes an authentication guard.

Availability

Unreleased: @authdog/hono is not on npm at the time of writing (the registry returns 404). bun add @authdog/hono will fail until it is published. Source lives in the `packages/hono` 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/hono hono

yarn add @authdog/hono hono

pnpm add @authdog/hono hono

bun add @authdog/hono hono

deno add npm:@authdog/hono npm:hono

hono is a peer dependency (^4); @authdog/node-commons installs automatically. Hono runs on Bun, Node.js, Cloudflare Workers, and Deno.

Configure

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

12345import { Hono } from "hono"
import { createAuthdog } from "@authdog/hono"

const app = new Hono()
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

Mount attachSession() before routes:

1app.use(authdog.attachSession())

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 stored as c.get("authdog"):

123456{
  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 is the security boundary and returns 401 {"error":"Unauthorized"} unless isAuthenticated is true:

1app.get("/me", authdog.requireAuth, (c) => c.json(c.get("authdog")!.user))

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

1app.get("/logout", authdog.logout)

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

Hono quickstart