h3 adapters

import { H3 } from "h3";
import { defineJWESession, generateJWK } from "unjwt/adapters/h3v2";

const key = await generateJWK("A256GCM"); // load a persisted key in production

const useSession = defineJWESession({ key, maxAge: "7D" });

export const app = new H3()
  .post("/login", async (event) => {
    const session = await useSession.use(event);
    await session.update({ userId: "u_123" });
    return { id: session.id }; // { id: "0f2c686c-…" }
  })
  .get("/me", async (event) => {
    const session = await useSession.use(event);
    return { id: session.id ?? null, data: session.data }; // { id: "0f2c686c-…", data: { userId: "u_123" } }
  });

Set-Cookie: h3-jwe=eyJraWQiOiJfNnlmWXJwNFc…; Path=/; Expires=Thu, 22 Oct 2026 12:49:03 GMT; HttpOnly; Secure; SameSite=Lax

#Which entry

:

unjwt/adapters/h3 resolves to unjwt/adapters/h3v2. Both entries export the same functions and types. h3 is an optional peer dependency, so install it only if your framework does not already. Each entry also re-exports generateJWK, thumbprint, importPEM, exportPEM and deriveJWKFromPassword.

#Signature

function defineJWSSession<
  T extends Record<string, any> = SessionClaims,
  MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined,
  TEvent extends HTTPEvent = HTTPEvent,
>(config: SessionConfigJWS<T, MaxAge, TEvent>): SessionDefinition<T, MaxAge, TEvent>;

function defineJWESession<
  T extends Record<string, any> = SessionClaims,
  MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined,
  TEvent extends HTTPEvent = HTTPEvent,
>(config: SessionConfigJWE<T, MaxAge, TEvent>): SessionDefinition<T, MaxAge, TEvent>;

interface SessionDefinition<T, MaxAge, TEvent> {
  use(event: TEvent): Promise<SessionManager<T, MaxAge>>;
  token(event: TEvent): string | undefined;
  issue(data?: Partial<SessionData<T>>, options?: { maxAge?: ExpiresIn }): Promise<string>;
  open(token: string): Promise<OpenedSessionState<T, MaxAge>>; // { id, createdAt, expiresAt, data }
}

Define the session once, at module scope. The definition validates and reads nothing until one of its methods runs. use(event) reads the request's token and returns the session manager. token(), issue() and open() work with the token alone: see the definition.

T types session.data: defineJWSSession<{ userId: string; role: "admin" | "user" }>(config). With maxAge in the config, session.expiresAt is typed number. TEvent is the event use() accepts and every hook receives. It defaults to the bound, HTTPEvent on h3 v2 and CompatEvent | H3Event on h3 v1 (a request-like event), because a definition is written once and cannot know which handlers will call use(). Narrow it to H3Event only in a project that never passes anything else: defineJWSSession<T, MaxAge, H3Event>(config).

#Options

A jws option only exists on SessionConfigJWS and a jwe option only on SessionConfigJWE.

#The session manager

The members are live getters, so a manager opened before update() reads the new values afterwards. update() takes three forms:

await session.update({ role: "admin" }); // merge into data
await session.update((data) => ({ visits: (data.visits ?? 0) + 1 })); // derive from the current data
await session.update(); // rotate: new jti, iat and exp, same data
await session.update({ step: "mfa" }, { maxAge: "5m" }); // this token lives 5 minutes

If issuing or the cookie write fails, update() throws and the session rolls back to its previous state. Every JWS use() (or every JWE use()) with the same name in one request shares one session: the first call reads the token with its config, and later calls get that state back, from the same definition or another one, whatever key or maxAge it carries. Two sessions with different keys need different names. A JWS and a JWE session may not share a name on the same request (ERR_SESSION_CONFIG_INVALID).

#In Nuxt and Nitro

Frameworks shows Nuxt, Nitro and bare h3 on unjwt/session. With this entry, define the session once in server/utils/ behind a wrapper that takes the event:

// server/utils/session.ts
import type { H3Event } from "h3";
import { defineJWESession } from "unjwt/adapters/h3";

const session = defineJWESession<{ userId: string }, "7D">({
  key: JSON.parse(process.env.NUXT_SESSION_KEY!),
  maxAge: "7D",
});

export function useSession(event: H3Event) {
  return session.use(event);
}

The wrapper's parameter is where a project narrows the event; widen it to HTTPEvent (v2) or CompatEvent | H3Event (v1) when WebSocket hooks call it too. NUXT_SESSION_KEY holds a JWK saved from generateJWK("A256GCM").

This is the Nuxt 5 (h3 v2) variant, where a route imports defineHandler and HTTPError from "h3" instead of relying on auto-imports:

// server/api/me.get.ts
import { defineHandler, HTTPError } from "h3";

export default defineHandler(async (event) => {
  const session = await useSession(event);
  if (!session.id) throw new HTTPError({ status: 401 });
  return session.data;
});

Keep the definition, and its key object, created once at module scope. The adapter imports a JWK once per key object, so a JWK rebuilt on each request is imported on each request.

#Reading the token from a header

For clients that cannot keep cookies, read the token from Authorization:

const apiSession = defineJWSSession({
  key,
  sessionHeader: "authorization", // "Bearer <token>" or the bare token
  cookie: false, // header only; update() writes no cookie
});

const session = await apiSession.use(event);

With cookie: false the client needs the token some other way. Return session.token after update(), or mint one with issue().

#WebSockets

A WebSocket route reads its session twice: once in upgrade, before the socket opens, and again in message. Nitro hands those hooks a request without a response:

• The upgrade object cannot take a cookie. update() throws ERR_SESSION_READONLY_EVENT on it, while clear() empties the session for the rest of the connection and leaves the cookie to the next HTTP request. A revocation check in onRead clears the same way on every event:

  const chat = defineJWSSession<{ userId: string }>({
    key,
    maxAge: "1h",
    hooks: {
      async onRead({ session }) {
        if (await revoked.has(session.id)) await session.clear();
      },
    },
  });

  A hook that needs event.node or event.res gates on isEvent(event) from h3 (both majors export it).

• upgrade answers the refusal itself. Wrap use() in try/catch and return a Response with status 401. crossws rethrows anything that is not a Response, so the client gets the runtime's error answer instead of a 401, and on Node with h3 v1 the socket is never answered at all.

• message reuses the upgrade's read. On h3 v1 peer.context is the same object the upgrade saw, so use({ headers: peer.request.headers, context: peer.context }) is a cache hit and onRead does not fire again. Pass context: {} to re-read the token on every message. On h3 v2 peer.request is the same Request as at upgrade, so use({ req: peer.request }) is a cache hit too. The defineWebSocketHandler((event) => hooks) factory hands the upgrade a full H3Event as well, on which isEvent(event) is true.

• A token-only session is not read by use(). A session with cookie: false, sessionHeader: false has no request to read. Over a socket, exchange its tokens with open() and issue() in message, with no event involved.

On h3 v1:

import { defineWebSocketHandler } from "h3";

export default defineWebSocketHandler({
  async upgrade(request) {
    try {
      const session = await chat.use(request);
      if (!session.id) return new Response("Unauthorized", { status: 401 });
    } catch {
      return new Response("Unauthorized", { status: 401 });
    }
  },
  async message(peer, message) {
    const session = await chat.use({ headers: peer.request.headers, context: peer.context });
    peer.send(`${session.data.userId}: ${message.text()}`);
  },
});

On h3 v2:

import { defineWebSocketHandler } from "h3";

export default defineWebSocketHandler({
  async upgrade(request) {
    try {
      const session = await chat.use({ req: request });
      if (!session.id) return new Response("Unauthorized", { status: 401 });
    } catch {
      return new Response("Unauthorized", { status: 401 });
    }
  },
  async message(peer, message) {
    const session = await chat.use({ req: peer.request });
    peer.send(`${session.data.userId}: ${message.text()}`);
  },
});

#Events without a response

Only an h3 event can take a Set-Cookie: on h3 v1 any object isEvent() accepts, on h3 v2 one that carries res, as in h3's own useSession. On any other object update() throws ERR_SESSION_READONLY_EVENT and clear() only empties the session for the request. On h3 v1 a response that was already sent (event.handled) refuses both and leaves the session as it was:

event.node.res.end("done"); // h3 v1
await session.clear();
// JWTError ERR_SESSION_READONLY_EVENT: [unjwt/h3] Cannot update/clear session: the response was already sent.

h3 v1 refuses a write once the response was sent. h3 v2 has no such signal: a write made after the handler returned is accepted and never sent, which is why a session is written inside the handler, before it returns. A read on such an event only observes: an expired token is reported to onExpire without its cookie being dropped, and rolling does not reissue. Both happen on the next request, which carries the same token.

On h3 v2, a handler that throws after update() or clear() still sends the session cookie. The adapter copies it into res.errHeaders, the headers h3 sends with an error response:

await session.update({ a: 1 });
throw new HTTPError({ status: 409, message: "conflict" });
// 409, Set-Cookie: h3-jws=eyJraWQiOiIxT…

An app-level onError that returns its own Response replaces those headers.

#Request-like events on h3 v1

The h3 v1 entry also accepts an object that is not an h3 event, as long as it carries context and either headers or request.headers. The default TEvent, CompatEvent | H3Event, already takes it. Reading works. Such an object has no response, so update() throws and clear() empties the session without a cookie:

import { defineJWSSession } from "unjwt/adapters/h3v1";

const useSession = defineJWSSession(config);

const event = { headers: new Headers({ cookie: `h3-jws=${token}` }), context: {} };
const session = await useSession.use(event);
session.id; // "76755fff-…"

await session.update({ a: 1 });
// JWTError ERR_SESSION_READONLY_EVENT: [unjwt/h3] Cannot update session on read-only event.

await session.clear();
session.id; // undefined

#Errors

An unreadable incoming token throws nothing. It goes to onError as ERR_SESSION_TOKEN_INVALID and its cookie is dropped; an expired one goes to onExpire, its cookie dropped too. All codes are listed on Errors.

#See also

• The definition for reading, minting and opening session tokens by hand.
• Authentication basics and the refresh token pattern.