SSR sessions

Own token cookies and refresh concurrency safely in server-rendered applications.

Use @cavuno/board/server for session-cookie encoding and single-flight refresh patterns. The app, not the shared SDK client, owns each user’s tokens.

Why the server client uses `nostore`

A module-scoped server client can serve many users. It must never persist one user’s access token in shared SDK storage. Configure storage: 'nostore', keep the bearer pair in Cavuno’s httpOnly session cookie, and pass the current access token on each private call.

1// src/lib/cavuno.server.ts
2import { createBoardClient } from '@cavuno/board';
3import { createSessionRefresher } from '@cavuno/board/server';
4
5export const board = createBoardClient({
6  board: process.env.PUBLIC_CAVUNO_BOARD!,
7  auth: { storage: 'nostore' },
8});
9
10export const refreshSession = createSessionRefresher(board);

createSessionRefresher fails during construction when a server client uses persistent storage. That failure prevents a cross-user token leak rather than silently accepting an unsafe configuration.

Read and refresh a session

The helpers consume and return cookie header strings, so the same logic can be connected to Next.js, TanStack Start, Remix, or a Worker response.

1// src/lib/load-board-user.ts
2import { isUnauthorized } from '@cavuno/board';
3import {
4  clearSessionCookie,
5  isExpiringSoon,
6  parseSessionCookie,
7  serializeSessionCookie,
8} from '@cavuno/board/server';
9
10import { board, refreshSession } from './cavuno.server';
11
12export async function loadBoardUser(cookieHeader: string | null) {
13  let session = parseSessionCookie(cookieHeader);
14  if (!session) return { user: null, setCookie: null };
15  let setCookie: string | null = null;
16
17  if (isExpiringSoon(session, Date.now())) {
18    session = await refreshSession(session);
19    if (!session) {
20      return { user: null, setCookie: clearSessionCookie() };
21    }
22    setCookie = serializeSessionCookie(session);
23  }
24
25  const options = {
26    cache: 'no-store' as const,
27    headers: { authorization: `Bearer ${session.accessToken}` },
28  };
29
30  try {
31    const user = await board.me.retrieve(undefined, options);
32    return { user, setCookie };
33  } catch (error) {
34    if (!isUnauthorized(error)) throw error;
35
36    const rotated = await refreshSession(session);
37    if (!rotated) {
38      return { user: null, setCookie: clearSessionCookie() };
39    }
40
41    const user = await board.me.retrieve(undefined, {
42      ...options,
43      headers: { authorization: `Bearer ${rotated.accessToken}` },
44    });
45    return { user, setCookie: serializeSessionCookie(rotated) };
46  }
47}

Attach setCookie to the framework response only when it is non-null. In a multi-board host, pass the same { board: identifier } option to parseSessionCookie, serializeSessionCookie, and clearSessionCookie so sessions cannot collide.

Verify the flow

Log in, reload, and confirm the account remains authenticated.
Force the access token near expiry and issue concurrent private reads. They must share one in-process refresh and receive the rotated cookie.
Revoke or corrupt the refresh token. The next request must clear the cookie and continue signed out without a refresh loop.
Confirm private responses use Cache-Control: private or no-store at every shared cache.

Production notes

The SDK cookie codec emits Path=/; HttpOnly; Secure; SameSite=Lax and uses the __Host- prefix.
Single-flight refresh is per process or isolate. Proactive refresh reduces cross-instance races but cannot eliminate them.
Refresh tokens rotate on use. Presenting the same refresh token again within 30 seconds returns the same rotated pair, so concurrent refreshes from separate instances converge; after that it returns 401. Retry a protected request at most once after rotation.
Never serialize a refresh token into HTML, client props, logs, or analytics.

Continue with Caching to keep authenticated responses out of shared caches.

Why the server client uses nostore

Read and refresh a session

Verify the flow

Production notes

Why the server client uses `nostore`