@cavuno/board 1.27.0 → 1.28.0

package/dist/server.mjs

@@ -0,0 +1,176 @@
+// src/server/cookie.ts
+var COOKIE_ATTRIBUTES = "Path=/; HttpOnly; Secure; SameSite=Lax";
+function buildCookie(name, value, maxAgeSeconds) {
+  return `${name}=${value}; Max-Age=${maxAgeSeconds}; ${COOKIE_ATTRIBUTES}`;
+}
+function buildClearCookie(name) {
+  return `${name}=; Max-Age=0; ${COOKIE_ATTRIBUTES}`;
+}
+function readCookie(header, name) {
+  if (!header) return null;
+  const pair = header.split(";").map((part) => part.trim()).find((part) => part.startsWith(`${name}=`));
+  if (!pair) return null;
+  const raw = pair.slice(name.length + 1);
+  if (!raw) return null;
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return null;
+  }
+}
+function cookieScope(board) {
+  return board.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+// src/server/session.ts
+var SESSION_COOKIE_NAME = "__Host-cavuno_board_session";
+function sessionCookieName(board) {
+  return board ? `${SESSION_COOKIE_NAME}_${cookieScope(board)}` : SESSION_COOKIE_NAME;
+}
+var COOKIE_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+var EXPIRY_WINDOW_MS = 5 * 60 * 1e3;
+function serializeSessionCookie(session, options) {
+  return buildCookie(
+    sessionCookieName(options?.board),
+    encodeURIComponent(JSON.stringify(session)),
+    COOKIE_MAX_AGE_SECONDS
+  );
+}
+function clearSessionCookie(options) {
+  return buildClearCookie(sessionCookieName(options?.board));
+}
+function parseSessionCookie(cookieHeader, options) {
+  const raw = readCookie(cookieHeader, sessionCookieName(options?.board));
+  if (!raw) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const session = parsed;
+  if (!session || typeof session.accessToken !== "string" || typeof session.refreshToken !== "string" || typeof session.expiresAt !== "number") {
+    return null;
+  }
+  return {
+    accessToken: session.accessToken,
+    refreshToken: session.refreshToken,
+    expiresAt: session.expiresAt
+  };
+}
+function isExpiringSoon(session, now, windowMs = EXPIRY_WINDOW_MS) {
+  return session.expiresAt - now < windowMs;
+}
+
+// src/server/board-access.ts
+var BOARD_ACCESS_COOKIE_NAME = "__Host-cavuno_board_access";
+function grantCookieName(board) {
+  return board ? `${BOARD_ACCESS_COOKIE_NAME}_${cookieScope(board)}` : BOARD_ACCESS_COOKIE_NAME;
+}
+var COOKIE_MAX_AGE_SECONDS2 = 24 * 60 * 60;
+function serializeGrantCookie(token, options) {
+  return buildCookie(
+    grantCookieName(options?.board),
+    encodeURIComponent(token),
+    COOKIE_MAX_AGE_SECONDS2
+  );
+}
+function clearGrantCookie(options) {
+  return buildClearCookie(grantCookieName(options?.board));
+}
+function parseGrantCookie(cookieHeader, options) {
+  return readCookie(cookieHeader, grantCookieName(options?.board));
+}
+
+// src/server/redirect-guard.ts
+function safeRedirectPath(path, defaultPath = "/") {
+  if (!path || !path.startsWith("/") || path.startsWith("//")) {
+    return defaultPath;
+  }
+  if (path.includes("://")) return defaultPath;
+  try {
+    const SENTINEL_ORIGIN = "https://redirect.invalid";
+    if (new URL(path, SENTINEL_ORIGIN).origin !== SENTINEL_ORIGIN) {
+      return defaultPath;
+    }
+  } catch {
+    return defaultPath;
+  }
+  return path;
+}
+function currentPathFromReferer(referer) {
+  if (!referer) return "/";
+  try {
+    const url = new URL(referer);
+    return safeRedirectPath(url.pathname + url.search);
+  } catch {
+    return "/";
+  }
+}
+
+// src/errors.ts
+function isBoardApiError(e) {
+  return e instanceof Error && e.name === "BoardApiError";
+}
+function isUnauthorized(e) {
+  return isBoardApiError(e) && e.status === 401;
+}
+
+// src/storage.ts
+var NOSTORE_BRAND = /* @__PURE__ */ Symbol.for("@cavuno/board:nostore");
+function isNoStore(storage) {
+  return storage[NOSTORE_BRAND] === true;
+}
+var NOSTORE = {
+  [NOSTORE_BRAND]: true,
+  getItem: () => null,
+  setItem: () => {
+  },
+  removeItem: () => {
+  }
+};
+
+// src/server/refresher.ts
+function createSessionRefresher(board) {
+  if (typeof globalThis.document === "undefined" && !isNoStore(board.client.storage)) {
+    throw new Error(
+      "createSessionRefresher requires the server client to use storage: 'nostore' \u2014 a shared persistent store would leak rotated tokens across requests. Keep the session in the httpOnly cookie and pass tokens per call."
+    );
+  }
+  const inflight = /* @__PURE__ */ new Map();
+  return async function refresh(session) {
+    const key = session.refreshToken;
+    const existing = inflight.get(key);
+    if (existing) return existing;
+    const attempt = board.auth.refresh({ refreshToken: key }).then(
+      (rotated) => ({
+        accessToken: rotated.accessToken,
+        refreshToken: rotated.refreshToken,
+        expiresAt: rotated.expiresAt
+      })
+    ).catch((error) => {
+      if (isUnauthorized(error)) return null;
+      throw error;
+    }).finally(() => {
+      inflight.delete(key);
+    });
+    inflight.set(key, attempt);
+    return attempt;
+  };
+}
+export {
+  BOARD_ACCESS_COOKIE_NAME,
+  SESSION_COOKIE_NAME,
+  clearGrantCookie,
+  clearSessionCookie,
+  createSessionRefresher,
+  currentPathFromReferer,
+  grantCookieName,
+  isExpiringSoon,
+  parseGrantCookie,
+  parseSessionCookie,
+  safeRedirectPath,
+  serializeGrantCookie,
+  serializeSessionCookie,
+  sessionCookieName
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavuno/board",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "description": "Typed isomorphic client for the Cavuno Board API",
   "license": "MIT",
   "type": "commonjs",
@@ -80,6 +80,16 @@
         "default": "./dist/sitemap.js"
       }
     },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.mts",
+        "default": "./dist/server.mjs"
+      },
+      "require": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      }
+    },
     "./skills": {
       "import": {
         "types": "./dist/skills.d.mts",

package/skills/cavuno-board-auth/SKILL.md

@@ -41,20 +41,21 @@ session.accessToken;     // bearer; never expose to the browser bundle on SSR
 
 ## Storage modes
 
-`auth.storage` is `'memory'` | `'nostore'` | a `CustomStorage`. Defaults: **`memory` in the browser, `nostore` on the server**. Browser login works out of the box; shared SSR instances stay stateless.
+`auth.storage` is `'memory'` | `'nostore'` | `'local'` | `'session'` | a `CustomStorage`. Defaults: **`memory` in the browser, `nostore` on the server**. Browser login works out of the box; shared SSR instances stay stateless.
 
 ```ts
 import { createBoardClient } from '@cavuno/board';
 
-// Browser/SPA: token held in memory on the instance.
+// Browser/SPA: 'local' persists the pair across tabs + reloads via
+// localStorage; 'session' scopes it to the tab; 'memory' drops it on reload.
 const board = createBoardClient({
   baseUrl: 'https://api.cavuno.com',
   board: 'pk_a8f3...',
-  auth: { storage: 'memory' },
+  auth: { storage: 'local' },
 });
 ```
 
-A `CustomStorage` implements async `getItem`/`setItem`/`removeItem` — back it with `localStorage`, IndexedDB, Redis, or your own store.
+`'local'`/`'session'` are **browser-only** — off-browser they throw loudly at client creation (`storage mode 'local' is browser-only — use 'nostore' + per-call headers on the server`). A `CustomStorage` implements async `getItem`/`setItem`/`removeItem` — back it with IndexedDB, Redis, or your own store.
 
 ## No auto-refresh on 401 — handle it explicitly
 
@@ -87,7 +88,7 @@ await board.auth.logout({ refreshToken });    // revokes server-side, clears sto
 
 ## Server-side pattern (keep tokens out of the browser)
 
-On SSR, do not hold the session on a shared instance. Keep the token pair in an httpOnly cookie owned by your app and pass it per call:
+On SSR, do not hold the session on a shared instance. Keep the token pair in an httpOnly cookie owned by your app and pass it per call. `@cavuno/board/server` ships the cookie codec + the single-flight refresh helper for exactly this (see `cavuno-board-server`):
 
 ```ts snippet
 // `accessToken` comes from your httpOnly cookie, read in server code.

package/skills/cavuno-board-server/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: cavuno-board-server
+description: SSR session plumbing with @cavuno/board/server — the __Host- httpOnly session-cookie codec (BoardSession serialize/parse/clear + the 5-minute isExpiringSoon window), the board-password grant-cookie codec with the open-redirect guards (safeRedirectPath, currentPathFromReferer), and createSessionRefresher, the single-flight rotation helper for the single-use refresh token. Use when wiring board-user auth or the board-password gate into any server-rendered frontend (TanStack Start, Next.js, Remix, Workers).
+---
+
+# Server session plumbing
+
+`@cavuno/board/server` ships the pieces every SSR board frontend re-invents
+around auth: cookie codecs and the refresh-rotation helper. Everything is
+pure and platform-neutral — helpers take and return cookie **strings**
+(`Set-Cookie` values, `Cookie` headers), never framework request/response
+objects. The middleware objects themselves stay framework-owned: you write
+~20 lines of glue per framework (the `cavuno-board-tanstack-start` flavor
+skill has the reference wiring), and everything inside the glue comes from
+here.
+
+## When to use
+
+- Holding a board-user session (bearer pair) in an httpOnly cookie on SSR.
+- Refreshing the single-use refresh token safely under concurrency.
+- Wiring the board-password gate (`board.password.verify()` grant) with a
+  safe `?redirect=` round-trip.
+
+## When not to use
+
+- Browser-only SPAs with no server — use `auth.storage: 'local'` /
+  `'session'` / `'memory'` instead (see `cavuno-board-auth`).
+- Framework middleware objects, CSRF protection, cookie encryption — all
+  app-owned. The session cookie is httpOnly + JSON; if you want an encrypted
+  cookie, wrap the codec output yourself.
+
+## The session cookie
+
+The SDK never sees server storage (create the client with no `auth.storage`
+→ `nostore`). The bearer pair lives in ONE `__Host-` httpOnly cookie owned
+by your app; `BoardSession` is `{ accessToken, refreshToken, expiresAt }`.
+
+```ts snippet
+import {
+  clearSessionCookie,
+  parseSessionCookie,
+  serializeSessionCookie,
+} from '@cavuno/board/server';
+
+// After login: persist the pair (BoardAuthSession already carries expiresAt).
+const session = await board.auth.login({ email, password });
+setCookieHeader = serializeSessionCookie({
+  accessToken: session.accessToken,
+  refreshToken: session.refreshToken,
+  expiresAt: session.expiresAt,
+});
+
+// On every request: parse the Cookie header your framework hands you.
+const current = parseSessionCookie(request.headers.get('cookie'));
+
+// On logout (after board.auth.logout({ refreshToken })): expire it.
+setCookieHeader = clearSessionCookie();
+```
+
+`serializeSessionCookie` locks the attributes (`__Host-` prefix, `Path=/`,
+`HttpOnly`, `Secure`, `SameSite=Lax`, 30-day `Max-Age` matching the refresh
+token's server-side lifetime). `parseSessionCookie` returns `null` for
+absent, malformed, or wrong-shape cookies — treat `null` as signed out.
+
+## Single-flight refresh in a session middleware
+
+Refresh tokens are single-use: two concurrent requests that both refresh
+burn the pair — the loser 401s and the user is signed out mid-session.
+`createSessionRefresher` dedupes concurrent rotations per refreshToken, and
+`isExpiringSoon` gives you the proactive 5-minute window so the old access
+token still works while you rotate.
+
+```ts snippet
+import {
+  clearSessionCookie,
+  createSessionRefresher,
+  isExpiringSoon,
+  parseSessionCookie,
+  serializeSessionCookie,
+} from '@cavuno/board/server';
+
+// Module scope: ONE refresher per board client, shared by all requests —
+// that sharing IS the single-flight guarantee — WITHIN one process/isolate. Across instances (serverless/multi-pod) simultaneous refreshes can still race; the proactive isExpiringSoon window keeps that rare, it does not eliminate it.
+const refreshSession = createSessionRefresher(board);
+
+async function resolveSession(cookieHeader: string | null) {
+  const session = parseSessionCookie(cookieHeader);
+  if (!session) return { session: null, setCookie: null };
+  if (!isExpiringSoon(session, Date.now())) {
+    return { session, setCookie: null };
+  }
+  const next = await refreshSession(session);
+  return next
+    ? { session: next, setCookie: serializeSessionCookie(next) }
+    : { session: null, setCookie: clearSessionCookie() }; // burned/revoked → signed out
+}
+```
+
+The contract: a rotated `BoardSession` on success (write it back to the
+cookie), `null` on a 401 (the token is burned or the session revoked —
+clear the cookie and continue signed out, **never retry**), and anything
+else (network error, 5xx, 429) rethrows for your error handling. Calls with
+the SAME refreshToken while one rotation is in flight await that same
+rotation; after it settles, the next call starts fresh.
+
+Pass the access token per SDK call — the client itself stays stateless:
+
+```ts snippet
+const me = await board.me.retrieve(undefined, {
+  headers: { authorization: `Bearer ${session.accessToken}` },
+});
+```
+
+## The board-password grant cookie
+
+On password-protected boards, `board.password.verify({ password })` returns
+an HMAC grant token; gated reads take it as the `X-Board-Access` header.
+Same codec pattern, 24-hour cookie (hosted parity):
+
+```ts snippet
+import {
+  clearGrantCookie,
+  parseGrantCookie,
+  serializeGrantCookie,
+} from '@cavuno/board/server';
+
+const { token } = await board.password.verify({ password });
+setCookieHeader = serializeGrantCookie(token);
+
+// Thread it to gated reads:
+const grant = parseGrantCookie(request.headers.get('cookie'));
+const jobs = await board.jobs.list(undefined, {
+  headers: grant ? { 'X-Board-Access': grant } : {},
+});
+```
+
+When a read still fails with `isBoardPasswordRequired` (grant expired or
+the password rotated), send the visitor to your `/password` page and clear
+the stale cookie with `clearGrantCookie()`.
+
+## Open-redirect guards
+
+The `/password?redirect=` round-trip is the classic open-redirect hole.
+`safeRedirectPath` transcribes the hosted board's guard (golden-tested
+against it): same-origin absolute paths pass through, everything else —
+`//evil.com`, full URLs, `javascript:`, backslash and control-character
+normalization bypasses — collapses to `'/'`.
+
+```ts snippet
+import {
+  currentPathFromReferer,
+  safeRedirectPath,
+} from '@cavuno/board/server';
+
+// Where to send the visitor after a correct password:
+redirect(safeRedirectPath(query.redirect));
+
+// Building the challenge link: derive the come-back path from the Referer
+// your framework read for you (already guarded internally).
+const backTo = currentPathFromReferer(request.headers.get('referer'));
+redirect(`/password?redirect=${encodeURIComponent(backTo)}`);
+```
+
+## Thread derivations (core entry, not /server)
+
+The messaging thread's pure rules ship on the main entry — they're
+client-safe view logic, not server plumbing:
+
+```ts snippet
+import { isColdRule, isOwnMessage, lastOwnMessageId } from '@cavuno/board';
+
+const mine = isOwnMessage(message, counterpartyId); // bubble side + actions
+const composerLocked = isColdRule(messages, counterpartyId); // cold-message cap
+const seenTargetId = lastOwnMessageId(messages, counterpartyId); // "Seen" row
+```
+
+`isColdRule` mirrors the server gate (`messaging_cold_rule` 403) so the
+composer can disable itself instead of surfacing the error — the server
+stays authoritative.
+
+## Multi-board origins
+
+One origin serving MULTIPLE boards must scope its cookies and storage per
+board — otherwise one board's login clobbers another's (hosted scopes its
+grant cookie per account for exactly this reason). Pass the board
+identifier to the codecs; the browser storage modes scope automatically via
+`createBoardClient`'s own `board`:
+
+```ts snippet
+import {
+  serializeSessionCookie,
+  parseSessionCookie,
+  sessionCookieName,
+} from '@cavuno/board/server';
+
+const scope = { board: 'pk_boardA' };
+const cookie = serializeSessionCookie(session, scope);
+const restored = parseSessionCookie(cookieHeader, scope);
+```
+
+Single-board deployments (one board per hostname — the starter model) omit
+the scope; the cookie names stay stable.
+
+## Anti-patterns
+
+```ts no-check
+// NEVER auto-retry a null refresh — the token is single-use; a retry loop
+// hammers the API with burned tokens:
+while (!(await refreshSession(session))) {} // wrong
+
+// NEVER create a refresher per request — per-request instances can't
+// dedupe, which defeats the single-flight design:
+const refreshSession = createSessionRefresher(board); // must be module scope
+
+// NEVER redirect to the raw query param:
+redirect(query.redirect); // open redirect — use safeRedirectPath
+
+// NEVER put the session in auth.storage on the server — auth.refresh persists the rotated pair into client.storage, so a shared persistent store bleeds one user's tokens into other requests (cross-user session leak). 'nostore' + per-call headers is the contract — a shared instance
+// leaks one user's tokens into another's request. Cookie + per-call header.
+```
+
+## Checklist
+
+- [ ] Session cookie parsed on every request; `null` treated as signed out.
+- [ ] `createSessionRefresher` instance is module-scoped (shared across
+      requests) and its `null` result clears the cookie without retrying.
+- [ ] Rotated sessions are written back with `serializeSessionCookie`.
+- [ ] Every `?redirect=` consumer goes through `safeRedirectPath`.
+- [ ] Bearer tokens ride per-call headers; the shared client has no storage.

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.27.0",
+  "version": "1.28.0",
   "skills": [
     {
       "name": "cavuno-board-account",
@@ -113,6 +113,13 @@
       "framework": null,
       "category": "core"
     },
+    {
+      "name": "cavuno-board-server",
+      "description": "SSR session plumbing with @cavuno/board/server — the __Host- httpOnly session-cookie codec (BoardSession serialize/parse/clear + the 5-minute isExpiringSoon window), the board-password grant-cookie codec with the open-redirect guards (safeRedirectPath, currentPathFromReferer), and createSessionRefresher, the single-flight rotation helper for the single-use refresh token. Use when wiring board-user auth or the board-password gate into any server-rendered frontend (TanStack Start, Next.js, Remix, Workers).",
+      "path": "skills/cavuno-board-server/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
     {
       "name": "cavuno-board-setup",
       "description": "End-to-end orchestrator for building a headless Cavuno job board with the @cavuno/board SDK. Start here after `npx @cavuno/board setup` copies the skills — detect the framework, wire the client, render board context, jobs browsing and detail, board-user auth and saved jobs, handle errors and access gating, then verify.",