Hono

SSR auth for Hono with HttpOnly cookie sessions — one middleware is the whole server surface.

@vortex-api/convex-auth/hono is the Hono server adapter. Sessions live in app-origin HttpOnly cookies; a middleware lands OAuth/magic-link redirects, refreshes sessions near expiry, and serves the intent-based /api/auth proxy. It implements the SSR auth contract.

Because Hono is fetch-shaped, the same adapter works on @hono/node-server, Bun, Deno, and Workers-style runtimes.

A working example lives in examples/hono.

Install

pnpm add @vortex-api/convex-auth hono

Point the server at your Convex deployment and wire the backend (component mount, convex/auth.ts, convex/http.ts) per Installation:

echo 'CONVEX_URL=https://<your-deployment>.convex.cloud' >> .env.local

Hono serves the server surface — middleware, the /api/auth proxy, and session helpers. Your sign-in UI lives wherever your frontend does (a SPA hitting the proxy, Hono-rendered pages, or a mobile app); it calls the same React client or plain fetch against /api/auth.

Middleware

Register convexAuthMiddleware once at the app level:

// src/index.ts
import { Hono } from "hono";
import { convexAuthMiddleware } from "@vortex-api/convex-auth/hono";
import { api } from "../convex/_generated/api";

const app = new Hono();
app.use("*", convexAuthMiddleware({ actions: api.auth }));

The middleware intercepts POST /api/auth itself and the boundary pass covers every other request — no separate route wiring is needed.

Options

Session helpers

All helpers take the Hono context; only getConvexAuthSession and getAuthServerState call Convex — the cookie helpers are local reads:

import {
  getConvexAuthSession,
  getConvexAuthToken,
  convexAuthCookieState,
  getAuthServerState,
} from "@vortex-api/convex-auth/hono";

app.get("/me", async (c) => {
  const session = await getConvexAuthSession(c, { actions: api.auth });
  if (session === null) return c.json({ error: "Unauthorized" }, 401);
  return c.json(session.user);
});

Helpers see the post-boundary session: when the middleware rotated tokens mid-request, they resolve the fresh tokens, not the stale cookie.

Standalone proxy route

Prefer owning the route file instead of the middleware intercept:

import { convexAuthProxyHandler } from "@vortex-api/convex-auth/hono";

app.post("/api/auth", convexAuthProxyHandler({ actions: api.auth }));

Convex wiring

The backend is the standard consumer setup — component mount in convex/convex.config.ts, convexAuth({...}) in convex/auth.ts, auth.addHttpRoutes(http) in convex/http.ts. See Installation.

Example apps

• examples/hono — the packaged adapter demo: convexAuthMiddleware, the /api/auth proxy, and getConvexAuthSession against a real Hono app.

  cd examples/hono
  pnpm install
  pnpm run dev

• examples/server — the same Hono shape in token mode using ConvexHttpClient directly. The reference for servers that do not need cookie sessions (scripting, CLIs, service-to-service).

  cd examples/server
  pnpm install
  pnpm run dev

Next steps