@cavuno/board 1.26.0 → 1.28.0

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/cavuno-board-sitemap/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: cavuno-board-sitemap
+description: Build the board's sitemap with @cavuno/board/sitemap — the hosted 8-bucket model (marketing, jobs taxonomies, job details, companies, salaries, blog), 45k chunking, XML rendering, and the buildBucketUrls walker that enumerates a board's content through the BoardSdk with the hosted SEO rules built in (feature gating, ≥5-job thin-content floor, pagination backstops). Use when adding /sitemap.xml and /sitemap/:file routes to a custom board frontend.
+---
+
+# Sitemap: the 8-bucket model
+
+`@cavuno/board/sitemap` ships the hosted board's sitemap architecture: a
+sitemap INDEX at `/sitemap.xml` pointing at one file per content bucket,
+each an ordinary `<urlset>`. The XML byte layout and the bucket rules are
+golden-tested against the hosted implementation, so a custom frontend's
+sitemap corpus lines up bucket-for-bucket with what cavuno.com would emit.
+
+Two tiers, use both:
+
+- **XML primitives** (pure, no I/O): `SITEMAP_BUCKETS`,
+  `SITEMAP_CHUNK_SIZE` (45,000), `chunk`, `bucketFilename` /
+  `parseBucketFilename`, `renderUrlset`, `renderSitemapIndex`.
+- **The walker** (opinionated, injected I/O): `listedBuckets(board)` and
+  `buildBucketUrls(board, origin, bucket)` take your `BoardSdk` instance
+  and return plain URL strings with the hosted rules applied — you never
+  re-derive the SEO policy.
+
+## When to use
+
+- Adding `/sitemap.xml` + `/sitemap/:file` routes to a board frontend.
+- Deciding which listing pages deserve indexing (the walker already does).
+
+## When not to use
+
+- Structured data / meta tags — `cavuno-board-seo`.
+- Feeds (RSS/Atom) — app-owned.
+
+## The two routes
+
+The index lists one entry per bucket; each bucket route parses its filename
+back to a bucket + chunk and renders a urlset. Empty buckets render a valid
+empty urlset — only `blog` is dropped from the index when the feature is
+off (`listedBuckets` handles that).
+
+```ts snippet
+import {
+  SITEMAP_CHUNK_SIZE,
+  buildBucketUrls,
+  bucketFilename,
+  chunk,
+  listedBuckets,
+  parseBucketFilename,
+  renderSitemapIndex,
+  renderUrlset,
+} from '@cavuno/board/sitemap';
+
+// GET /sitemap.xml — one <sitemap> per listed bucket (plus -2, -3… chunks).
+const origin = 'https://jobs.example.com';
+const buckets = await listedBuckets(board);
+const locs: string[] = [];
+for (const bucket of buckets) {
+  const urls = await buildBucketUrls(board, origin, bucket);
+  const chunks = chunk(urls, SITEMAP_CHUNK_SIZE);
+  for (let i = 0; i < Math.max(chunks.length, 1); i += 1) {
+    locs.push(`${origin}/sitemap/${bucketFilename(bucket, i)}`);
+  }
+}
+return xmlResponse(renderSitemapIndex(locs));
+```
+
+```ts snippet
+// GET /sitemap/:file — parse, enumerate, slice, render. Unknown file → 404.
+const parsed = parseBucketFilename(params.file);
+if (!parsed) return notFound();
+const urls = await buildBucketUrls(board, origin, parsed.bucket);
+const page = chunk(urls, SITEMAP_CHUNK_SIZE)[parsed.chunkIndex] ?? [];
+return xmlResponse(renderUrlset(page));
+```
+
+`renderUrlset` also accepts `{ url, lastModified?, images? }` entries when
+you have per-URL dates (a `Date` serializes to ISO 8601). `changefreq` and
+`priority` are deliberately unsupported — the hosted board never emits them.
+
+## robots.txt
+
+Point crawlers at the index — one line, at the site root:
+
+```txt
+Sitemap: https://jobs.example.com/sitemap.xml
+```
+
+## The rules the walker enforces (don't re-implement)
+
+- **Thin-content floor**: a category/skill/location listing page is emitted
+  only with ≥5 distinct jobs (`MIN_JOBS_PER_INDEXED_PAGE`) — below that,
+  the page is thin content that wastes crawl budget.
+- **Feature gating**: `/impressum`, `/talent`, `/employers` appear in the
+  marketing bucket only when `context().features` enables them; the blog
+  bucket exists only when `features.blog` is on.
+- **Board language**: salary-index reads pass `context().language`, so a
+  non-English board emits board-language canonical salary slugs (jobs,
+  companies, and blog slugs arrive canonical on the wire already). No
+  locale parameter to thread.
+- **Pagination backstops**: offset enumeration runs in parallel when the
+  envelope carries `count` (capped at the API's 10,000-offset window);
+  cursor walks cap at 200 pages. Both warn on truncation instead of
+  hanging a build.
+
+## Stable order caveat (cursor walks)
+
+Cursor and offset enumeration order can shift between requests on a large,
+churning board — two chunk requests may see slightly different orderings.
+That is harmless for a sitemap (URLs dedupe and the ≥5 counts are a
+heuristic), but do NOT reuse the walker as a general "export all jobs in
+order" tool; for stable ordering, pass an explicit sort/query to
+`board.jobs.list` yourself.
+
+## Named exclusions (v1 API gap — not bugs)
+
+Two URL families the HOSTED sitemap emits are deliberately absent, because
+v1 exposes them only per-slug and a bulk-pairs endpoint doesn't exist yet
+(per-slug N+1 is ~1k+ calls per build):
+
+- Cross-axis salary pages (title×location, skill×location,
+  company×category, and the per-entity `/locations` · `/titles` ·
+  `/skills` salary index pages).
+- Jobs place×category / place×skill combination listings.
+
+Both stay reachable through internal links. When the bulk endpoint lands,
+the walker picks them up additively — don't hand-enumerate them.
+
+## Anti-patterns
+
+```ts snippet
+// NEVER emit every taxonomy page unconditionally — the ≥5-job floor exists
+// to keep thin pages out of the index:
+for (const c of allCategories) urls.push(`${origin}/jobs/${c.slug}`); // wrong
+// NEVER hand-build the XML with a template string per route — use
+// renderUrlset/renderSitemapIndex (escaping + byte-parity with hosted).
+// NEVER fetch every salary detail page to discover cross-axis pairs (N+1).
+```
+
+## Verify
+
+- [ ] `/sitemap.xml` lists one file per bucket (no `blog` entry when the
+      feature is off) and every listed file returns valid XML.
+- [ ] A category with 4 jobs is absent from `jobs-categories.xml`; one with
+      5 is present.
+- [ ] `jobs-details-2.xml` style chunk names round-trip through
+      `parseBucketFilename` and unknown filenames 404.
+- [ ] robots.txt points at `/sitemap.xml`.

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.26.0",
+  "version": "1.28.0",
   "skills": [
     {
       "name": "cavuno-board-account",
@@ -106,6 +106,20 @@
       "framework": null,
       "category": "core"
     },
+    {
+      "name": "cavuno-board-seo",
+      "description": "Structured data + head builders for board frontends with @cavuno/board/seo — Google for Jobs JobPosting JSON-LD, breadcrumbs, blog Article/ProfilePage, salary-page Occupation/FAQ structured data, and listing <head> descriptors. Use when building a job-detail, listing, blog, or salary page and it needs JSON-LD or SEO meta tags, or whenever \"structured data\", \"rich results\", or \"Google for Jobs\" comes up.",
+      "path": "skills/cavuno-board-seo/SKILL.md",
+      "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.",
@@ -113,6 +127,13 @@
       "framework": null,
       "category": "core"
     },
+    {
+      "name": "cavuno-board-sitemap",
+      "description": "Build the board's sitemap with @cavuno/board/sitemap — the hosted 8-bucket model (marketing, jobs taxonomies, job details, companies, salaries, blog), 45k chunking, XML rendering, and the buildBucketUrls walker that enumerates a board's content through the BoardSdk with the hosted SEO rules built in (feature gating, ≥5-job thin-content floor, pagination backstops). Use when adding /sitemap.xml and /sitemap/:file routes to a custom board frontend.",
+      "path": "skills/cavuno-board-sitemap/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
     {
       "name": "cavuno-board-smoke-test",
       "description": "Runtime verification for a wired Cavuno board frontend — literal curl probes against the Board API plus per-surface behavioral checks and a mandatory production-build pass. Run after cavuno-board-setup finishes, after upgrading @cavuno/board, or whenever board wiring is suspect. Type checks are not enough for board wiring.",