@svgrid/create 2.7.0 → 3.0.0

package/templates/pivot-dashboard/src/routes/+page.svelte

@@ -0,0 +1,138 @@
+<script lang="ts">
+  /**
+   * Pivot dashboard: one cube, one chart, one drill rail, all over the same
+   * facts.
+   *
+   * The point of the layout is that the three panes cannot disagree. The pivot
+   * summarises `facts`; the chart re-aggregates the same array along the first
+   * row dimension; the drill rail filters it back down to the rows behind one
+   * clicked cell. Change the layout in the designer and all three follow.
+   */
+  import { SvPivotDesigner, setLicenseKey, type PivotField, type PivotLayout, type PivotRow } from '@svgrid/enterprise'
+  import { drillThrough, type Drill } from '$lib/drill'
+  import type { Fact } from '$lib/facts'
+  import DrillRail from './DrillRail.svelte'
+  import TrendChart from './TrendChart.svelte'
+
+  // Swap for your own key. Unlicensed use still runs - it just nudges.
+  setLicenseKey('SVENTERPRISE-DEV-DEMO')
+
+  let { data } = $props()
+  const facts = $derived(data.facts as Fact[])
+
+  const fields: PivotField[] = [
+    { field: 'region', kind: 'dimension', label: 'Region' },
+    { field: 'country', kind: 'dimension', label: 'Country' },
+    { field: 'city', kind: 'dimension', label: 'City' },
+    { field: 'channel', kind: 'dimension', label: 'Channel' },
+    { field: 'customer', kind: 'dimension', label: 'Customer' },
+    { field: 'year', kind: 'dimension', label: 'Year' },
+    { field: 'quarter', kind: 'dimension', label: 'Quarter' },
+    { field: 'revenue', kind: 'measure', label: 'Revenue' },
+    { field: 'units', kind: 'measure', label: 'Units' },
+  ]
+
+  let layout = $state<PivotLayout>({
+    rows: ['region', 'country'],
+    cols: ['year'],
+    values: [{ field: 'revenue', agg: 'sum' }],
+    // Required by PivotLayout. Empty means every fact passes.
+    filters: [],
+  })
+
+  // The designer hands back the rows it rendered. Drill-through needs them to
+  // walk a clicked row up to its ancestors.
+  let pivotRows = $state<PivotRow[]>([])
+  let drill = $state<Drill | null>(null)
+
+  const money = (n: number) => n.toLocaleString(undefined, { style: 'currency', currency: 'USD', maximumFractionDigits: 0 })
+  const plain = (n: number) => n.toLocaleString()
+  const measure = $derived(layout.values[0]?.field ?? 'revenue')
+  const format = $derived(measure === 'units' ? plain : money)
+
+  /** Chart series: the active measure totalled by the first row dimension. */
+  const series = $derived.by(() => {
+    const dimension = layout.rows[0]
+    if (!dimension) return []
+    const totals = new Map<string, number>()
+    for (const fact of facts) {
+      const key = String((fact as unknown as Record<string, unknown>)[dimension])
+      const value = Number((fact as unknown as Record<string, unknown>)[measure] ?? 0)
+      totals.set(key, (totals.get(key) ?? 0) + value)
+    }
+    return [...totals].map(([label, value]) => ({ label, value })).sort((a, b) => b.value - a.value)
+  })
+
+  /** The chart highlights whichever top-level value the drill is inside. */
+  const activeBar = $derived(drill && layout.rows[0] ? (drill.filter[layout.rows[0]] ?? null) : null)
+
+  function onCellClick(event: { row: PivotRow; columnId: string }) {
+    // The row-header column is a label, not an aggregation - nothing to drill.
+    if (event.columnId === '__pivotRowHeader') return
+    drill = drillThrough(facts, event.row, event.columnId, pivotRows, layout)
+  }
+
+  /** Clicking a bar drills the whole of that dimension value. */
+  function onBarSelect(label: string) {
+    const dimension = layout.rows[0]
+    if (!dimension) return
+    const matched = facts.filter((f) => String((f as unknown as Record<string, unknown>)[dimension]) === label)
+    drill = {
+      rowLabel: label,
+      filter: { [dimension]: label },
+      facts: matched,
+      measure,
+      total: matched.reduce((sum, f) => sum + Number((f as unknown as Record<string, unknown>)[measure] ?? 0), 0),
+    }
+  }
+</script>
+
+<svelte:head><title>Pivot dashboard</title></svelte:head>
+
+<h1>Sales cube</h1>
+<p class="lede">
+  {plain(facts.length)} facts, summarised on the server and pivoted in the browser.
+  Click any aggregated cell to see the rows behind it.
+</p>
+
+<div class="layout" class:has-drill={drill !== null}>
+  <section class="cube" aria-label="Pivot">
+    <SvPivotDesigner
+      data={facts}
+      {fields}
+      bind:layout
+      expandable
+      panelPosition="right"
+      onPivot={(rows: PivotRow[]) => (pivotRows = rows)}
+      {onCellClick}
+    />
+  </section>
+
+  <section class="chart" aria-label="Totals by {layout.rows[0] ?? 'dimension'}">
+    <h2>Total {measure} by {layout.rows[0] ?? 'dimension'}</h2>
+    <TrendChart {series} {format} active={activeBar} onSelect={onBarSelect} />
+  </section>
+
+  {#if drill}
+    <DrillRail {drill} {format} onClose={() => (drill = null)} />
+  {/if}
+</div>
+
+<style>
+  h1 { margin: 0 0 0.25rem; font-size: 1.4rem; }
+  .lede { margin: 0 0 1.25rem; color: var(--sg-muted, #64748b); }
+  .layout { display: grid; gap: 1rem; grid-template-columns: 1fr; }
+  .cube { min-width: 0; height: 460px; }
+  .chart {
+    min-width: 0; padding: 1rem;
+    border: 1px solid var(--sg-border, #e2e8f0); border-radius: var(--sg-radius, 8px);
+  }
+  .chart h2 { margin: 0 0 0.75rem; font-size: 0.95rem; text-transform: capitalize; }
+  /* Side by side once there is room. Below this the panes stack, which keeps
+     the pivot usable on a phone instead of squeezing three columns in. */
+  @media (min-width: 60rem) {
+    .layout { grid-template-columns: minmax(0, 2fr) minmax(0, 1fr); }
+    .cube { grid-column: 1 / -1; }
+    .layout.has-drill .cube { grid-column: 1 / -1; }
+  }
+</style>

package/templates/pivot-dashboard/src/routes/DrillRail.svelte

@@ -0,0 +1,82 @@
+<script lang="ts">
+  /**
+   * The drill-through rail: the facts behind one clicked pivot cell.
+   *
+   * The KPI at the top is recomputed from the same rows the grid below lists,
+   * so it always matches the cell that was clicked. If it ever did not, the
+   * drill filter and the pivot aggregation would have drifted apart.
+   */
+  import { SvGrid, type GridColumns } from '@svgrid/grid'
+  import type { Drill } from '$lib/drill'
+  import { drillBreadcrumb } from '$lib/drill'
+  import type { Fact } from '$lib/facts'
+
+  type Props = {
+    drill: Drill
+    format: (value: number) => string
+    onClose: () => void
+  }
+
+  let { drill, format, onClose }: Props = $props()
+
+  const columns: GridColumns<Fact> = [
+    { field: 'customer', header: 'Customer' },
+    { field: 'city', header: 'City' },
+    { field: 'channel', header: 'Channel' },
+    { field: 'quarter', header: 'Qtr' },
+    { field: 'revenue', header: 'Revenue', align: 'right' },
+    { field: 'units', header: 'Units', align: 'right' },
+  ]
+
+  const average = $derived(drill.facts.length ? drill.total / drill.facts.length : 0)
+</script>
+
+<aside class="rail" aria-label="Drill-through">
+  <header>
+    <div>
+      <p class="eyebrow">Drill-through</p>
+      <h2>{drillBreadcrumb(drill)}</h2>
+    </div>
+    <button type="button" onclick={onClose} aria-label="Close drill-through">&times;</button>
+  </header>
+
+  <dl class="kpis">
+    <div><dt>{drill.measure}</dt><dd>{format(drill.total)}</dd></div>
+    <div><dt>Facts</dt><dd>{drill.facts.length.toLocaleString()}</dd></div>
+    <div><dt>Average</dt><dd>{format(Math.round(average))}</dd></div>
+  </dl>
+
+  <div class="grid">
+    <SvGrid data={drill.facts} {columns} sortable containerHeight={340} />
+  </div>
+</aside>
+
+<style>
+  .rail {
+    display: flex; flex-direction: column; gap: 1rem; min-width: 0;
+    border: 1px solid var(--sg-border, #e2e8f0); border-radius: var(--sg-radius, 8px);
+    background: var(--sg-bg, #fff); padding: 1rem;
+  }
+  header { display: flex; align-items: start; justify-content: space-between; gap: 1rem; }
+  .eyebrow {
+    margin: 0 0 0.15rem; font-size: 0.6875rem; text-transform: uppercase;
+    letter-spacing: 0.06em; color: var(--sg-muted, #64748b);
+  }
+  h2 { margin: 0; font-size: 1rem; }
+  header button {
+    font: inherit; font-size: 1.25rem; line-height: 1; padding: 0.1rem 0.4rem; cursor: pointer;
+    background: none; border: 1px solid var(--sg-border, #e2e8f0);
+    border-radius: var(--sg-radius, 8px); color: var(--sg-fg, #0f172a);
+  }
+  .kpis { display: grid; grid-template-columns: repeat(3, 1fr); gap: 0.5rem; margin: 0; }
+  .kpis div {
+    border: 1px solid var(--sg-border, #e2e8f0); border-radius: var(--sg-radius, 8px);
+    padding: 0.5rem 0.6rem;
+  }
+  dt {
+    font-size: 0.6875rem; text-transform: uppercase; letter-spacing: 0.05em;
+    color: var(--sg-muted, #64748b);
+  }
+  dd { margin: 0.15rem 0 0; font-size: 1rem; font-weight: 650; font-variant-numeric: tabular-nums; }
+  .grid { min-width: 0; }
+</style>

package/templates/pivot-dashboard/src/routes/TrendChart.svelte

@@ -0,0 +1,62 @@
+<script lang="ts">
+  /**
+   * A bar chart over whatever slice the dashboard is currently showing.
+   *
+   * Inline SVG on purpose: a starter should not pull a charting library in for
+   * one chart, and this way the bars are plain DOM you can style with the same
+   * `--sg-*` tokens as the grid.
+   */
+  type Props = {
+    /** Bars to draw, already aggregated. */
+    series: { label: string; value: number }[]
+    /** Formats the value in the tooltip and the axis. */
+    format: (value: number) => string
+    /** Highlighted bar, e.g. the one being drilled. */
+    active?: string | null
+    onSelect?: (label: string) => void
+  }
+
+  let { series, format, active = null, onSelect }: Props = $props()
+
+  const max = $derived(Math.max(1, ...series.map((s) => s.value)))
+</script>
+
+{#if series.length === 0}
+  <p class="empty">No data in this slice.</p>
+{:else}
+  <ul class="bars">
+    {#each series as bar (bar.label)}
+      <li class="row" class:is-active={active === bar.label}>
+        <button
+          type="button"
+          onclick={() => onSelect?.(bar.label)}
+          title="{bar.label}: {format(bar.value)}"
+        >
+          <span class="label">{bar.label}</span>
+          <span class="track">
+            <!-- Width is the only inline style here: it is data, not design. -->
+            <span class="fill" style="width: {(bar.value / max) * 100}%"></span>
+          </span>
+          <span class="value">{format(bar.value)}</span>
+        </button>
+      </li>
+    {/each}
+  </ul>
+{/if}
+
+<style>
+  .bars { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 2px; }
+  button {
+    display: grid; grid-template-columns: 8rem 1fr 6rem; align-items: center; gap: 0.75rem;
+    width: 100%; padding: 0.3rem 0.4rem; font: inherit; text-align: left;
+    background: none; border: 0; border-radius: var(--sg-radius, 8px); cursor: pointer;
+    color: var(--sg-fg, #0f172a);
+  }
+  button:hover { background: var(--sg-row-hover-bg, rgba(0, 0, 0, 0.04)); }
+  .row.is-active button { background: color-mix(in srgb, var(--sg-accent, #2563eb) 14%, transparent); }
+  .label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 0.875rem; }
+  .track { background: var(--sg-border, #e2e8f0); border-radius: 999px; height: 0.7rem; overflow: hidden; }
+  .fill { display: block; height: 100%; background: var(--sg-accent, #2563eb); border-radius: 999px; }
+  .value { font-variant-numeric: tabular-nums; font-size: 0.8125rem; text-align: right; color: var(--sg-muted, #64748b); }
+  .empty { color: var(--sg-muted, #64748b); font-size: 0.875rem; margin: 0; }
+</style>

package/templates/pivot-dashboard/tsconfig.json

@@ -0,0 +1,20 @@
+{
+	"extends": "./.svelte-kit/tsconfig.json",
+	"compilerOptions": {
+		"rewriteRelativeImportExtensions": true,
+		"allowJs": true,
+		"checkJs": true,
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"sourceMap": true,
+		"strict": true,
+		"moduleResolution": "bundler"
+	}
+	// Path aliases are handled by https://svelte.dev/docs/kit/configuration#alias
+	// except $lib which is handled by https://svelte.dev/docs/kit/configuration#files
+	//
+	// To make changes to top-level options such as include and exclude, we recommend extending
+	// the generated config; see https://svelte.dev/docs/kit/configuration#typescript
+}

package/templates/pivot-dashboard/vite.config.ts

@@ -0,0 +1,20 @@
+import adapter from '@sveltejs/adapter-auto';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [
+		sveltekit({
+			compilerOptions: {
+				// Force runes mode for the project, except for libraries. Can be removed in svelte 6.
+				runes: ({ filename }) =>
+					filename.split(/[/\\]/).includes('node_modules') ? undefined : true
+			},
+
+			// adapter-auto only supports some environments, see https://svelte.dev/docs/kit/adapter-auto for a list.
+			// If your environment is not supported, or you settled on a specific environment, switch out the adapter.
+			// See https://svelte.dev/docs/kit/adapters for more information about adapters.
+			adapter: adapter()
+		})
+	]
+});

package/templates/sveltekit/README.md

@@ -1,8 +1,8 @@
 # SvGrid + SvelteKit sample
 
-A grid whose rows are loaded on the server, sorted from the URL, and edited
-through a form action - the three things that are different about running a grid
-in SvelteKit rather than a plain Vite SPA.
+A grid whose rows are loaded on the server, sorted from the URL, edited through
+a form action, and gated behind a cookie session with roles - the things that
+are different about running a grid in SvelteKit rather than a plain Vite SPA.
 
 ```bash
 npm install
@@ -19,6 +19,16 @@ npm run dev     # http://localhost:5173/people
    light and dark, applied live.
 4. **`curl localhost:5173/people`.** The rows are in the HTML, not injected by
    JS afterwards. That is what a crawler sees.
+5. **Sign in as each user.** `admin@example.com` can edit names;
+   `viewer@example.com` cannot, and the column is not editable for them.
+   The password is `password` for both.
+6. **Try to bypass the gate.** Sign in as the viewer, then post the action by
+   hand. It comes back 403, because the check is on the server and hiding the
+   button was only cosmetic:
+
+   ```bash
+   curl -i -X POST 'localhost:5173/people?/rename' -F id=1 -F name=Nope
+   ```
 
 ## Where things are
 
@@ -27,9 +37,29 @@ npm run dev     # http://localhost:5173/people
 | `src/lib/people.ts` | Stands in for your database. Swap for real queries. |
 | `src/routes/people/+page.server.ts` | `load` sorts from the query string; the `rename` action takes the edit. |
 | `src/routes/people/+page.svelte` | The grid. `externalSort` because the server owns the ordering. |
+| `src/lib/server/auth.ts` | Password hashing (PBKDF2 via Web Crypto), sessions, roles. Swap the arrays for your database. |
+| `src/hooks.server.ts` | Resolves the session once per request and gates routes from one list. |
+| `src/routes/login/+page.server.ts` | Login action. Rejects open redirects; one message for every failure. |
+| `src/routes/logout/+server.ts` | POST-only sign out. Drops the session server-side, not just the cookie. |
 | `src/lib/theme.svelte.ts` | Runtime theme switching via `resolveThemeTokens`. |
 | `src/app.css` | Imports one preset so the first paint is themed before JS runs. |
 
+## Auth
+
+The scaffold is the real shape, with the storage stubbed:
+
+- Passwords are hashed with PBKDF2-HMAC-SHA256 through Web Crypto, so the same
+  code runs on Node and on the edge runtimes `adapter-auto` may pick.
+- The session cookie is `httpOnly` (an XSS bug cannot read it) and
+  `SameSite=Lax` (a cross-site POST cannot ride it).
+- Sign out drops the session server-side, so a copied id stops working.
+- Route gating lives in one list in `hooks.server.ts`, so adding a protected
+  route is an entry rather than a check you have to remember.
+
+The users and sessions are in-memory, like `src/lib/people.ts`. Move both to
+your database before this goes anywhere real - in particular, an in-memory
+session map does not survive a restart or a second instance.
+
 ## Themes
 
 Pick a starting theme when you scaffold:

package/templates/sveltekit/_package.json

@@ -21,6 +21,6 @@
     "vite": "^8.0.16"
   },
   "dependencies": {
-    "@svgrid/grid": "^2.6.8"
+    "@svgrid/grid": "^3.0.0"
   }
 }

package/templates/sveltekit/src/app.d.ts

@@ -1,10 +1,18 @@
 // See https://svelte.dev/docs/kit/types#app.d.ts
 // for information about these interfaces
+import type { User } from '$lib/server/auth'
+
 declare global {
 	namespace App {
 		// interface Error {}
-		// interface Locals {}
-		// interface PageData {}
+		interface Locals {
+			/** Set by hooks.server.ts on every request; null when signed out. */
+			user: User | null
+		}
+		interface PageData {
+			/** Returned by the root layout load, so every page can read it. */
+			user?: User | null
+		}
 		// interface PageState {}
 		// interface Platform {}
 	}

package/templates/sveltekit/src/hooks.server.ts

@@ -0,0 +1,49 @@
+/**
+ * Server hooks: resolve the session once per request, then gate routes.
+ *
+ * Doing it here rather than in each `+page.server.ts` is what makes the gate
+ * hard to forget - a new protected route is one entry in PROTECTED, not a
+ * check you have to remember to copy into every load function.
+ */
+import { redirect, type Handle } from '@sveltejs/kit'
+import { SESSION_COOKIE, userForSession } from '$lib/server/auth'
+import type { Role } from '$lib/server/auth'
+
+/**
+ * Route prefixes that need a session, and the role they need.
+ *
+ * `null` means any signed-in user. Longest prefix wins, so a specific child
+ * route can require more than its parent.
+ */
+const PROTECTED: { prefix: string; role: Role | null }[] = [
+  { prefix: '/people', role: null },
+  { prefix: '/admin', role: 'admin' },
+]
+
+function requirementFor(pathname: string): Role | null | undefined {
+  const match = PROTECTED.filter((r) => pathname === r.prefix || pathname.startsWith(r.prefix + '/')).sort(
+    (a, b) => b.prefix.length - a.prefix.length,
+  )[0]
+  return match ? match.role : undefined
+}
+
+export const handle: Handle = async ({ event, resolve }) => {
+  event.locals.user = await userForSession(event.cookies.get(SESSION_COOKIE))
+
+  const required = requirementFor(event.url.pathname)
+  if (required !== undefined) {
+    if (!event.locals.user) {
+      // Carry where they were going, so login can send them back rather than
+      // dumping everyone on the home page.
+      const from = encodeURIComponent(event.url.pathname + event.url.search)
+      redirect(303, `/login?redirectTo=${from}`)
+    }
+    if (required && event.locals.user.role !== required) {
+      // Signed in but not allowed: 403, not a redirect to login. Bouncing an
+      // authenticated user to a login form reads as a broken app.
+      redirect(303, '/people?error=forbidden')
+    }
+  }
+
+  return resolve(event)
+}

package/templates/sveltekit/src/lib/server/auth.ts

@@ -0,0 +1,177 @@
+/**
+ * Auth scaffold: password hashing, sessions, and role lookup.
+ *
+ * Everything here runs on the server only - `$lib/server` is a folder SvelteKit
+ * enforces, so importing this from a component is a build error rather than a
+ * leaked password hash.
+ *
+ * Like `$lib/people.ts`, the stores are module-level and in-memory: they stand
+ * in for your database so the starter runs with no setup. Swap the two arrays
+ * for real queries and nothing else has to change. What is *not* a placeholder
+ * is the hashing and the cookie handling - those are the real patterns, because
+ * getting them wrong is the expensive kind of wrong.
+ *
+ * Built on Web Crypto rather than `node:crypto`, so the same code runs on Node,
+ * Deno, Bun and the edge runtimes `adapter-auto` may select. Nothing here needs
+ * a dependency.
+ */
+
+export type Role = 'admin' | 'viewer'
+export type User = { id: number; email: string; role: Role }
+
+/** A user plus the credential we never hand to the client. */
+type StoredUser = User & { passwordHash: string }
+
+/** Name of the session cookie. */
+export const SESSION_COOKIE = 'sid'
+
+/** How long a session stays valid. Refreshed on each request. */
+const SESSION_TTL_MS = 1000 * 60 * 60 * 24 * 7 // 7 days
+
+/** PBKDF2 rounds. OWASP's floor for PBKDF2-HMAC-SHA256 is 600k; this is the
+ *  knob to raise as hardware gets faster. Stored alongside each hash so old
+ *  hashes keep verifying after you raise it. */
+const PBKDF2_ROUNDS = 600_000
+
+const encoder = new TextEncoder()
+
+function toHex(bytes: Uint8Array): string {
+  return [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+function fromHex(hex: string): Uint8Array {
+  const out = new Uint8Array(hex.length / 2)
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
+  return out
+}
+
+async function derive(password: string, salt: Uint8Array, rounds: number): Promise<Uint8Array> {
+  const key = await crypto.subtle.importKey('raw', encoder.encode(password), 'PBKDF2', false, ['deriveBits'])
+  const bits = await crypto.subtle.deriveBits(
+    { name: 'PBKDF2', salt: salt as BufferSource, iterations: rounds, hash: 'SHA-256' },
+    key,
+    256,
+  )
+  return new Uint8Array(bits)
+}
+
+/** Format: rounds:salt:hash, so the work factor travels with the hash. */
+async function hashPassword(password: string): Promise<string> {
+  const salt = crypto.getRandomValues(new Uint8Array(16))
+  const hash = await derive(password, salt, PBKDF2_ROUNDS)
+  return `${PBKDF2_ROUNDS}:${toHex(salt)}:${toHex(hash)}`
+}
+
+/** Compare without an early exit, so the time taken does not reveal how many
+ *  leading bytes matched. */
+function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) diff |= a[i]! ^ b[i]!
+  return diff === 0
+}
+
+async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const [rounds, salt, hash] = stored.split(':')
+  if (!rounds || !salt || !hash) return false
+  const actual = await derive(password, fromHex(salt), Number(rounds))
+  return constantTimeEqual(actual, fromHex(hash))
+}
+
+// --- users -----------------------------------------------------------------
+
+/**
+ * Seeded lazily: hashing is async, and 600k PBKDF2 rounds twice at import would
+ * stall the first request. `getUsers()` awaits the same promise every time, so
+ * the work happens once.
+ */
+let usersPromise: Promise<StoredUser[]> | null = null
+
+function getUsers(): Promise<StoredUser[]> {
+  usersPromise ??= (async () => [
+    { id: 1, email: 'admin@example.com', role: 'admin' as const, passwordHash: await hashPassword('password') },
+    { id: 2, email: 'viewer@example.com', role: 'viewer' as const, passwordHash: await hashPassword('password') },
+  ])()
+  return usersPromise
+}
+
+/** Hashed once so an unknown email costs the same work as a known one. Without
+ *  it, a fast "no such user" reply enumerates your user list. */
+let dummyHashPromise: Promise<string> | null = null
+function getDummyHash(): Promise<string> {
+  dummyHashPromise ??= hashPassword(crypto.randomUUID())
+  return dummyHashPromise
+}
+
+/** Public shape - never includes the hash. */
+function publicUser(u: StoredUser): User {
+  return { id: u.id, email: u.email, role: u.role }
+}
+
+/**
+ * Check an email/password pair. Returns the user, or null.
+ *
+ * The same null comes back for an unknown email and a wrong password, and a
+ * verify runs either way, so the response neither confirms which emails exist
+ * nor answers faster for one case than the other.
+ */
+export async function verifyCredentials(email: string, password: string): Promise<User | null> {
+  const users = await getUsers()
+  const found = users.find((u) => u.email.toLowerCase() === email.trim().toLowerCase())
+  const ok = await verifyPassword(password, found?.passwordHash ?? (await getDummyHash()))
+  return ok && found ? publicUser(found) : null
+}
+
+// --- sessions --------------------------------------------------------------
+
+type Session = { userId: number; expires: number }
+
+const sessions = new Map<string, Session>()
+
+/** Start a session and return its id, to be set as the cookie value. */
+export function createSession(userId: number): string {
+  // randomUUID is a CSPRNG. A guessable session id is as good as no auth.
+  const id = crypto.randomUUID()
+  sessions.set(id, { userId, expires: Date.now() + SESSION_TTL_MS })
+  return id
+}
+
+/** Resolve a session id to its user, sliding the expiry forward. Returns null
+ *  for an unknown or expired id, and drops the expired entry. */
+export async function userForSession(id: string | undefined): Promise<User | null> {
+  if (!id) return null
+  const session = sessions.get(id)
+  if (!session) return null
+  if (session.expires < Date.now()) {
+    sessions.delete(id)
+    return null
+  }
+  session.expires = Date.now() + SESSION_TTL_MS
+  const users = await getUsers()
+  const user = users.find((u) => u.id === session.userId)
+  return user ? publicUser(user) : null
+}
+
+/** Invalidate a session server-side. Clearing the cookie alone would leave a
+ *  stolen id working until it expired. */
+export function destroySession(id: string | undefined): void {
+  if (id) sessions.delete(id)
+}
+
+/**
+ * Cookie options for the session.
+ *
+ * `httpOnly` keeps the id away from JavaScript, so an XSS bug cannot read it.
+ * `sameSite: 'lax'` blocks the cookie on cross-site POSTs, which is what stops
+ * CSRF against the form actions. `secure` is on outside dev, where there is no
+ * HTTPS to require.
+ */
+export function sessionCookieOptions(secure: boolean) {
+  return {
+    path: '/',
+    httpOnly: true,
+    sameSite: 'lax',
+    secure,
+    maxAge: Math.floor(SESSION_TTL_MS / 1000),
+  } as const
+}

package/templates/sveltekit/src/routes/+layout.server.ts

@@ -0,0 +1,10 @@
+import type { LayoutServerLoad } from './$types'
+
+/**
+ * Publish the signed-in user to every page.
+ *
+ * `locals.user` is server-only; returning it from a layout load is what makes
+ * it available to components as `data.user`. Only the public shape crosses
+ * that boundary - `$lib/server/auth` never puts the password hash on it.
+ */
+export const load: LayoutServerLoad = ({ locals }) => ({ user: locals.user })