@panaversity/ksor 0.0.34 → 0.0.35

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @panaversity/ksor
 
+## 0.0.35
+
+### Patch Changes
+
+- 0fc6bce: Name the reader on the website
+
+  The scaffolded site can now sign a reader in and show who they are in the
+  navbar. It is off until three variables are set — the control does not render at
+  all without them, which stays the default.
+
+  The flow is OAuth 2.0 Authorization Code with PKCE against a public client, with
+  no secret anywhere in a build that ships to browsers. Endpoints are discovered
+  (RFC 8414, then OIDC), so no vendor is named in the code or in configuration;
+  verified end to end against Auth0 and against a Better Auth deployment. The
+  session lives in `sessionStorage` for the tab, and no refresh token is requested
+  or stored — a token that unlocks nothing on this site should not outlive the
+  visit.
+
+  What it does NOT do is restrict reading, and the documentation leads with that.
+  The site is a static export: every published document is a file the host serves
+  to whoever asks, so keeping people out is still the origin gate or a per-audience
+  build, both unchanged. This names an already-authenticated reader; it is not a
+  step toward access control, and treating it as one would be the mistake the
+  "Keeping people out of the site" section exists to prevent.
+
+  Also fixes a real gap it exposed: the site build never read the repository-root
+  `.env`, so following the scaffold's own instructions would have set variables
+  that silently never reached the bundle.
+
+- 4b431b2: Trim the shell-retirement revision in AGENTS.md from 222 words to 129, keeping
+  what an agent must act on and moving the reasoning to the commit that carried
+  it.
+
+  Working rule 6 requires a reversed decision to keep its entry and gain a
+  revision note, so removing it is not available — and it is not irrelevant
+  either: without it an agent looks for a deleted directory with no explanation,
+  or restores two-shell assertions thinking they were lost by accident, or reads
+  decision 9, sees no obstacle, and treats dropping `output: "export"` as
+  unblocked. That last one is the reason it stays.
+
+  But coding principle 1 applies to this file too — context is liability, and
+  AGENTS.md loads every session. The narrative half was 90 words explaining why
+  the proof had been valuable, which the commit already records.
+
+  Also documents the thing that was missing entirely: **how to keep people out of
+  the site.** The door's auth had four recipes; the site had nothing, and the
+  most common requirement — "everyone signs in before reading anything" — is also
+  the easiest, needs no ksor change, and was written down nowhere.
+
+  Three shapes, separated because they had been muddled: a host-level gate in
+  front of the origin (protects every byte, holds against `curl`, and makes a
+  site sign-in button redundant rather than complementary); per-audience builds
+  for a restricted subset (enforcement by absence, already built); and the
+  per-request case, which a static export cannot express and which issue #130
+  records rather than implements. Plus what does not work — hiding rendered
+  content behind a browser check, which presents rather than protects.
+
+  The per-request case gets three answers rather than a deferral: **read through
+  the door** (already applies audience scope per request and logs an actor per
+  read — per-person governance with an audit trail a static site cannot have),
+  **split the record** (content needing per-person confidentiality inside one tier
+  usually belongs in its own record), or **fork the site**, which an adopter owns
+  outright under decision 4.
+
+  The fork is offered with what it costs stated: ksor's guarantee is enforcement
+  by ABSENCE, asserted against a positive control; a request-time filter is a
+  different guarantee and becomes the adopter's to test. A filter that is bypassed
+  serves the document; an absent file cannot be.
+
 ## 0.0.34
 
 ### Patch Changes

package/docs/authorization.md

@@ -32,8 +32,11 @@ Read this before spending an afternoon on a provider's console.
 **It protects the MCP door, not the website.** Everything on this page is a
 bearer token on `POST /mcp`. Your static site is a separate surface, served by
 whatever hosts it, and configuring auth here leaves it exactly as public as it
-was. If people must not read the record at all, the site needs its own access
-control — or must not be published.
+was. Keeping people out of the SITE is a different mechanism and is not on this
+page — see "Keeping people out of the site" in
+[deploying.md](./deploying.md), which covers the three shapes: a host-level gate
+in front of everything, per-audience builds for a restricted subset, and why the
+per-request case needs a decision first.
 
 **It is one gate, not per-user rules.** The door checks that a token was signed
 by the issuer you named and audienced at this record. It reads no scopes, no

package/docs/deploying.md

@@ -246,6 +246,148 @@ a row) and reaches the site at its next build (it reads a file), so a site built
 without the DSN would keep publishing what the door already refuses. Set
 `KSOR_DB_URL` on the site build as well as on the door.
 
+## Keeping people out of the site
+
+The door has auth ([authorization.md](./authorization.md)). The **site** is
+static files, so it has none — and the way to protect it is not to add code, it
+is to put something in front of it.
+
+Three requirements, three different answers. Pick the row you actually have.
+
+### "Everyone must sign in before reading anything"
+
+**Put a gate in front of the origin.** Nothing in ksor changes, and it protects
+every byte — HTML, `llms.txt`, images, the search index — because the request
+never reaches the files.
+
+| host          | what to turn on                                                                                      |
+| ------------- | ---------------------------------------------------------------------------------------------------- |
+| Vercel        | Deployment Protection (password, or SSO on paid plans)                                               |
+| Cloudflare    | Cloudflare Access in front of the deployment                                                         |
+| anything else | an authenticating reverse proxy — nginx with `auth_request`, oauth2-proxy, Caddy with `forward_auth` |
+
+This is the strongest gate available to a static site, and the only one that
+holds against `curl`. It is coarse — whole deployment, all or nothing — which is
+exactly right when the answer is "this record is internal".
+
+**A sign-in button on the site is not an alternative to this.** The gate has
+already authenticated the reader before a page renders; a second login inside it
+would ask the same person to sign in twice, and on its own would protect
+nothing.
+
+### "Some documents are restricted, most are not"
+
+**Build per audience.** `KSOR_AUDIENCE=<tier> pnpm build` stages only what that
+tier may see, so restricted documents are **never written into the artifact** —
+enforcement by absence, which is the only kind a static host can honour. Publish
+the public artifact openly and the wider one behind the gate above.
+
+Plain `pnpm build` is always the public tier, so the safe thing is the default.
+
+### "Different readers see different documents, decided per request"
+
+Two supported answers, and a third that is yours.
+
+**Read through the door instead.** This is the one ksor is built for. The MCP
+surface already applies the audience scope **per request** and writes a
+`retrieval_log` row carrying the actor for every read — per-person governance
+with an audit trail, which a static site cannot have at any price. If the
+requirement is "who read what, and were they allowed to", that is the door, not
+the website.
+
+**Or split the record.** Content needing per-person confidentiality inside one
+tier is usually content that belongs in its own record, with its own gate. That
+is what the audience model and the second-record design anticipate.
+
+**Or fork the site — you already own it.** `system/site` is yours outright
+(decision 4). Nothing stops you removing `output: "export"` and filtering per
+request in your own repository. ksor's contract is unaffected; this is a
+directory you own, changed the way you want it.
+
+What you take on if you do:
+
+> ksor's guarantee is **enforcement by absence** — a restricted document is
+> never written into the artifact, and a conformance suite asserts that against
+> a positive control that proves the check is not blind. A request-time filter
+> is a **different** guarantee, and it becomes yours to test, because those
+> suites will no longer be testing it for you. A filter that is bypassed serves
+> the document; an absent file cannot be.
+
+That is the whole trade. It is a reasonable thing to do with your eyes open, and
+a bad thing to drift into because a login button suggested it.
+
+### What does NOT work
+
+**Hiding rendered content behind a signed-in check in the browser.** If the page
+was built with the content in it, the content is in the response before any
+JavaScript runs — `curl` and every crawler see it. A component that blurs or
+collapses it is presenting, not protecting. If you build one, say so in its own
+comment, or the next reader will take it for a gate.
+
+## Naming the reader — the sign-in control
+
+The site ships an optional sign-in control. Read the section above before you
+turn it on, because the one thing it does not do is the thing its name suggests.
+
+**What it does:** signs the reader in against your authorization server and puts
+their name in the navbar. That is the whole feature.
+
+**What it does not do:** restrict anything. The site is a static export — every
+published document is a file the host hands to whoever asks, and no amount of
+browser JavaScript changes that. If the requirement is "keep people out", the
+answer is the origin gate above, and the sign-in control is not a step toward it.
+
+So the honest use is a record already behind a gate, where the reader is
+authenticated but anonymous to the page, and you want the navbar to say who they
+are and offer a way out. That is worth having. It is not access control.
+
+### Turning it on
+
+Register a **public** client — PKCE, no secret — at the same authorization
+server the door names in `KSOR_SSO_URL`, then set three variables in the
+repository-root `.env`:
+
+```sh
+NEXT_PUBLIC_KSOR_SSO_URL=https://your-sso.example.com
+NEXT_PUBLIC_KSOR_OAUTH_CLIENT_ID=your-client-id
+NEXT_PUBLIC_KSOR_OAUTH_REDIRECT_URI=https://your-site.example.com/auth/callback
+```
+
+All three or none: with any of them missing the control does not render, which
+is the default and is not an error.
+
+They are `NEXT_PUBLIC_`, so they are **inlined at build time**. Set them before
+`pnpm build`; setting them on a running site changes nothing. This also means
+they are public — which is correct, because a public client has nothing secret
+to leak, and it is the reason none of these is a secret.
+
+Two things to get exactly right at the provider:
+
+- **The redirect URI must match byte for byte**, including the scheme and any
+  trailing slash. This is the failure everyone hits first, and providers report
+  it as a generic callback mismatch.
+- **Add the site's origin to the allowed web origins** (Auth0 calls it that;
+  others call it CORS). The token exchange is a browser `fetch`, so a missing
+  origin fails as CORS, not as auth.
+
+For local work, both values are `http://localhost:3000` — and the callback is
+`http://localhost:3000/auth/callback`.
+
+Endpoints are **discovered**, not configured: the control reads
+`/.well-known/oauth-authorization-server`, then OIDC discovery. Any provider
+publishing either one works, which is why there is no vendor setting here.
+Verified against Auth0 and against a Better Auth deployment.
+
+### What it stores, and for how long
+
+The session lives in `sessionStorage` — this tab, until it closes. No refresh
+token is requested and none is stored.
+
+That is deliberate, and it is a smaller footprint than the obvious alternative.
+A token that unlocks nothing on this site should not outlive the visit; the
+blast radius should match the benefit. If you need a longer session, you need
+the gate, not a longer-lived token in a browser.
+
 ## Authorization, or the deliberate absence of it
 
 `ksor serve` **refuses to boot unauthenticated on a public bind.** There is no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.34",
+  "version": "0.0.35",
   "description": "Knowledge System of Record — compile governed markdown into a static site for people and an MCP server for AI agents, with citations and measured abstention.",
   "keywords": [
     "abstention",

package/templates/scaffold/README.md

@@ -233,6 +233,13 @@ put it behind access control you already trust (VPN, SSO proxy,
 authenticated host). The tiers govern what a build contains; where each
 build may be served is yours to enforce.
 
+The site can also show a **sign-in control** that names the reader in the
+navbar. It is off until you set three variables (see `.env.example`), and it
+names people rather than keeping them out — a static export cannot gate itself,
+so it is worth having on a record already behind one of the answers above, and
+is not a substitute for them. Setup and the honest limits:
+`node_modules/@panaversity/ksor/docs/deploying.md`.
+
 ## Ownership
 
 Everything here is yours. The scaffold was generated by

package/templates/scaffold/env.example

@@ -41,6 +41,23 @@ GEMINI_API_KEY=
 #   KSOR_JWKS_URL=https://your-sso.example.com/.well-known/jwks.json
 KSOR_AUTH=disabled-local
 
+# ── Sign-in on the WEBSITE (optional) ───────────────────────────────────────
+# Names the reader in the navbar. It does NOT restrict reading: the site is a
+# static export, so every published document is a file the host serves to
+# whoever asks. To actually keep people out, see docs/deploying.md →
+# "Keeping people out of the site".
+#
+# All three are required together, and are inlined at BUILD time — set them
+# before `pnpm build`, not on the running site. Leave them unset and the
+# sign-in control does not render at all.
+#
+# The issuer is the same authorization server the door names in KSOR_SSO_URL.
+# Register a PUBLIC client (PKCE, no secret) whose redirect list contains the
+# callback URL below, written out literally.
+# NEXT_PUBLIC_KSOR_SSO_URL=https://your-sso.example.com
+# NEXT_PUBLIC_KSOR_OAUTH_CLIENT_ID=
+# NEXT_PUBLIC_KSOR_OAUTH_REDIRECT_URI=https://your-site.example.com/auth/callback
+
 # ── Production knobs ────────────────────────────────────────────────────────
 # Unset is fine for a local run; each one matters once this serves for real.
 

package/templates/scaffold/system/site/app/auth/callback/page.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+/**
+ * Where the issuer sends the reader back.
+ *
+ * A PAGE, not a route handler. Under `output: "export"` a route handler cannot
+ * share a segment with a page, and more to the point there is no server to run
+ * one — the whole exchange happens in the browser, which is what lets a static
+ * site be an OAuth client at all.
+ */
+
+import { useEffect, useState } from "react";
+
+import { completeSignIn } from "@/lib/auth/flow";
+
+export default function CallbackPage(): React.ReactElement {
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      const result = await completeSignIn(new URLSearchParams(window.location.search));
+      if (cancelled) return;
+      if (result.ok) {
+        // replace(), not assign(): the callback URL carries a spent
+        // authorization code, and leaving it in history means Back re-runs a
+        // flow that can only fail the second time.
+        window.location.replace(result.returnTo || "/");
+        return;
+      }
+      setError(result.reason);
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return (
+    <main className="mx-auto flex min-h-[60vh] max-w-md flex-col justify-center gap-3 px-6 text-center">
+      {error === null ? (
+        <p className="text-muted-foreground text-sm">Signing you in…</p>
+      ) : (
+        <>
+          <h1 className="text-lg font-semibold">Sign-in did not complete</h1>
+          <p className="text-muted-foreground text-sm">{error}</p>
+          <a className="text-sm underline underline-offset-4" href="/">
+            Back to the record
+          </a>
+        </>
+      )}
+    </main>
+  );
+}

package/templates/scaffold/system/site/components/sign-in.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+/**
+ * The navbar's sign-in control.
+ *
+ * Renders NOTHING when this record does not configure an issuer, so a scaffold
+ * that never sets one looks exactly as it does today — no placeholder, no
+ * disabled button, no hint that a feature is missing.
+ *
+ * What it does NOT do, said here because a sign-in control implies it: gate
+ * anything. The record's pages are static files the host serves to whoever
+ * asks. This names a reader; it does not decide what they may read.
+ */
+
+import { LogIn, LogOut, User } from "lucide-react";
+import { useEffect, useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { authConfig } from "@/lib/auth/config";
+import { beginSignIn } from "@/lib/auth/flow";
+import { clearSession, readSession, type Session } from "@/lib/auth/session";
+
+export function SignIn(): React.ReactElement | null {
+  // Read AFTER mount, never during render: the session lives in sessionStorage,
+  // which the prerender has no access to. Reading it during render would make
+  // the server-rendered HTML and the first client render disagree, and React
+  // would blow the tree away with a hydration error.
+  const [session, setSession] = useState<Session | null>(null);
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    setSession(readSession());
+    setReady(true);
+  }, []);
+
+  if (authConfig === null) return null;
+
+  // Hold the space until mounted, so the navbar does not jump when the session
+  // resolves one frame later.
+  if (!ready) return <div className="h-8 w-20" aria-hidden />;
+
+  if (session === null) {
+    return (
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={() => {
+          void beginSignIn(window.location.pathname + window.location.search);
+        }}
+      >
+        <LogIn className="size-4" aria-hidden />
+        Sign in
+      </Button>
+    );
+  }
+
+  const label = session.name ?? session.email ?? "Signed in";
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="ghost" size="sm" aria-label={`Signed in as ${label}`}>
+          <User className="size-4" aria-hidden />
+          <span className="max-w-32 truncate">{label}</span>
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-56">
+        <DropdownMenuLabel className="font-normal">
+          <span className="block truncate text-sm font-medium">{label}</span>
+          {session.email !== null && session.email !== label ? (
+            <span className="text-muted-foreground block truncate text-xs">{session.email}</span>
+          ) : null}
+        </DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem
+          onClick={() => {
+            clearSession();
+            setSession(null);
+          }}
+        >
+          <LogOut className="size-4" aria-hidden />
+          Sign out
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/templates/scaffold/system/site/lib/auth/config.ts

@@ -0,0 +1,53 @@
+/**
+ * Whether this record's site offers sign-in, and against whom.
+ *
+ * Sign-in is ABSENT unless an issuer is configured. There is no half-state and
+ * no localhost fallback: a build with no issuer renders no control, and every
+ * function here returns null rather than guessing. That is the same posture the
+ * door takes (`ksor serve` refuses to boot rather than serve an undeclared
+ * auth state) expressed in the only way a static build can — by not existing.
+ *
+ * What this buys, stated once so nobody has to infer it: a VERIFIED reader
+ * identity, rather than a guessed one. It protects nothing the site publishes,
+ * and nothing in the browser calls the door yet — the flow requests `openid
+ * profile email` and no audience, so the access token it receives is the
+ * issuer's own and is not something the door would accept. Making the browser
+ * a door client means requesting this record's resource (RFC 8707) and is a
+ * new read surface, not a config change. Under `output: "export"` every document is a file the host serves
+ * to whoever asks; see `docs/deploying.md` → "Keeping people out of the site"
+ * for the three mechanisms that actually restrict reading.
+ */
+
+/** Values are inlined at BUILD time, so they must be NEXT_PUBLIC_ to exist. */
+export interface AuthConfig {
+  /** The authorization server's base URL — the same issuer the door names. */
+  readonly issuer: string;
+  /** This site's public OAuth client. No secret: PKCE proves the caller. */
+  readonly clientId: string;
+  /**
+   * The callback URL, written out LITERALLY.
+   *
+   * Never derived from `window.location`. A derivation has to guess whether the
+   * first path segment is a base path, and guesses wrong under `KSOR_BASE_PATH`
+   * — producing a `redirect_uri` the issuer rejects, with an error that names
+   * the URI and not the guess that built it.
+   */
+  readonly redirectUri: string;
+}
+
+const issuer = process.env["NEXT_PUBLIC_KSOR_SSO_URL"]?.trim() ?? "";
+const clientId = process.env["NEXT_PUBLIC_KSOR_OAUTH_CLIENT_ID"]?.trim() ?? "";
+const redirectUri = process.env["NEXT_PUBLIC_KSOR_OAUTH_REDIRECT_URI"]?.trim() ?? "";
+
+/**
+ * The configuration, or null when this record does not offer sign-in.
+ *
+ * All three are required together. Two out of three is a misconfiguration that
+ * would otherwise surface as a failed redirect on the reader's screen, so it
+ * resolves to "no sign-in" and the control never renders.
+ */
+export const authConfig: AuthConfig | null =
+  issuer !== "" && clientId !== "" && redirectUri !== "" ? { issuer, clientId, redirectUri } : null;
+
+/** Where the record's own scopes end: identity only, and no refresh token. */
+export const OAUTH_SCOPE = "openid profile email";

package/templates/scaffold/system/site/lib/auth/discovery.ts

@@ -0,0 +1,53 @@
+/**
+ * Where the issuer's endpoints actually are — asked, never assumed.
+ *
+ * Hardcoding `/authorize` and `/oauth/token` would work against one vendor and
+ * fail against the next, which is the opposite of what this project claims.
+ * Every standards-compliant authorization server publishes a metadata document
+ * naming its own endpoints, and the door already reads exactly these two
+ * (`gateway-kit/src/jwks-discovery.ts`): RFC 8414 first, then OpenID Discovery.
+ *
+ * So the site and the door discover the same issuer the same way, and pointing
+ * both at a different provider stays an environment change.
+ */
+
+export interface Endpoints {
+  readonly authorization_endpoint: string;
+  readonly token_endpoint: string;
+}
+
+const PATHS = ["/.well-known/oauth-authorization-server", "/.well-known/openid-configuration"];
+
+function isEndpoints(value: unknown): value is Endpoints {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v["authorization_endpoint"] === "string" && typeof v["token_endpoint"] === "string";
+}
+
+let cached: Endpoints | null = null;
+
+/**
+ * The issuer's endpoints, or null if it publishes no usable metadata.
+ *
+ * Memoized for the page's lifetime: the flow reads it twice (once to leave,
+ * once to come back) and those are separate page loads, so this saves a request
+ * only within one of them. Correctness does not depend on it.
+ */
+export async function discover(issuer: string): Promise<Endpoints | null> {
+  if (cached !== null) return cached;
+  const base = issuer.replace(/\/+$/, "");
+  for (const path of PATHS) {
+    try {
+      const response = await fetch(`${base}${path}`);
+      if (!response.ok) continue;
+      const document: unknown = await response.json();
+      if (isEndpoints(document)) {
+        cached = document;
+        return document;
+      }
+    } catch {
+      /* try the next document; a provider publishing neither is the null case */
+    }
+  }
+  return null;
+}

package/templates/scaffold/system/site/lib/auth/flow.ts

@@ -0,0 +1,158 @@
+/**
+ * The two halves of an authorization-code flow, as plain functions.
+ *
+ * Everything is `fetch` and `window.location`. Nothing here needs a server on
+ * this origin, which is why a static export can do it at all.
+ */
+
+import { authConfig, OAUTH_SCOPE, type AuthConfig } from "./config";
+import { discover } from "./discovery";
+import { createPkcePair, createState } from "./pkce";
+import { writeSession, type Session } from "./session";
+
+/**
+ * The verifier and state, held across the redirect.
+ *
+ * `sessionStorage`, not a variable: the browser leaves this origin entirely and
+ * comes back to a fresh page load, so anything in memory is gone. It is also
+ * not `localStorage` — this is single-flow, single-tab state that should not
+ * outlive the tab that started it.
+ */
+const PENDING = "ksor.oauth.pending";
+
+interface Pending {
+  readonly verifier: string;
+  readonly state: string;
+  /** Where the reader was, so sign-in returns them there. */
+  readonly returnTo: string;
+}
+
+/** Send the reader to the issuer. Returns only if it could not start. */
+export async function beginSignIn(returnTo: string): Promise<void> {
+  const config: AuthConfig | null = authConfig;
+  if (config === null) return;
+
+  const { verifier, challenge } = await createPkcePair();
+  const state = createState();
+  const pending: Pending = { verifier, state, returnTo };
+  sessionStorage.setItem(PENDING, JSON.stringify(pending));
+
+  const endpoints = await discover(config.issuer);
+  if (endpoints === null) return;
+
+  const url = new URL(endpoints.authorization_endpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", config.clientId);
+  url.searchParams.set("redirect_uri", config.redirectUri);
+  url.searchParams.set("scope", OAUTH_SCOPE);
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  window.location.assign(url.toString());
+}
+
+export type CallbackResult =
+  | { readonly ok: true; readonly returnTo: string }
+  | { readonly ok: false; readonly reason: string };
+
+interface TokenResponse {
+  readonly access_token?: unknown;
+  readonly id_token?: unknown;
+  readonly expires_in?: unknown;
+}
+
+/** Claims this site reads. Everything else in the token is ignored. */
+interface IdClaims {
+  readonly sub?: unknown;
+  readonly name?: unknown;
+  readonly email?: unknown;
+}
+
+/** Decode a JWT payload WITHOUT verifying it. Read the caveat before using. */
+function decodeClaims(idToken: string): IdClaims | null {
+  try {
+    const payload = idToken.split(".")[1];
+    if (payload === undefined) return null;
+    const json = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
+    const parsed: unknown = JSON.parse(json);
+    return typeof parsed === "object" && parsed !== null ? (parsed as IdClaims) : null;
+  } catch {
+    return null;
+  }
+}
+
+const str = (value: unknown): string | null => (typeof value === "string" ? value : null);
+
+/**
+ * Redeem the code the issuer sent back, and store the session.
+ *
+ * The id_token's claims are decoded, NOT verified, and that is deliberate: they
+ * are used only to render a name in this browser's own navbar. A forged token
+ * would let a reader lie to themselves about their own display name and nothing
+ * else — no content is gated on it, and the ACCESS token is verified by the
+ * server that actually accepts it (the door checks signature, issuer and
+ * audience per request). Verifying here would mean shipping a JWKS client to
+ * defend against the reader's own devtools.
+ */
+export async function completeSignIn(params: URLSearchParams): Promise<CallbackResult> {
+  const config: AuthConfig | null = authConfig;
+  if (config === null) return { ok: false, reason: "This record does not offer sign-in." };
+
+  const issuerError = params.get("error");
+  if (issuerError !== null) {
+    return { ok: false, reason: params.get("error_description") ?? issuerError };
+  }
+
+  const raw = sessionStorage.getItem(PENDING);
+  sessionStorage.removeItem(PENDING);
+  if (raw === null) {
+    return { ok: false, reason: "This sign-in did not start here. Try again from the site." };
+  }
+  const pending = JSON.parse(raw) as Pending;
+
+  // CSRF: the state must be the one this browser generated. Checked before the
+  // code is sent anywhere, so a planted code is never redeemed.
+  if (params.get("state") !== pending.state) {
+    return { ok: false, reason: "Sign-in could not be verified. Try again." };
+  }
+  const code = params.get("code");
+  if (code === null) return { ok: false, reason: "The issuer returned no authorization code." };
+
+  // No `credentials: "include"`: a public PKCE client sends no cookies, and
+  // sending them is refused outright by browsers against a wildcard CORS origin.
+  const endpoints = await discover(config.issuer);
+  if (endpoints === null) {
+    return { ok: false, reason: "The authorization server published no metadata document." };
+  }
+
+  const response = await fetch(endpoints.token_endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: config.redirectUri,
+      client_id: config.clientId,
+      code_verifier: pending.verifier,
+    }),
+  });
+  if (!response.ok) {
+    return { ok: false, reason: `The issuer refused the exchange (${response.status}).` };
+  }
+
+  const token = (await response.json()) as TokenResponse;
+  const accessToken = str(token.access_token);
+  if (accessToken === null) return { ok: false, reason: "The issuer returned no access token." };
+
+  const claims = typeof token.id_token === "string" ? decodeClaims(token.id_token) : null;
+  const lifetime = typeof token.expires_in === "number" ? token.expires_in : 3600;
+  const session: Session = {
+    subject: str(claims?.sub) ?? "unknown",
+    name: str(claims?.name),
+    email: str(claims?.email),
+    accessToken,
+    expiresAt: Date.now() + lifetime * 1000,
+  };
+  writeSession(session);
+  return { ok: true, returnTo: pending.returnTo };
+}

package/templates/scaffold/system/site/lib/auth/pkce.ts

@@ -0,0 +1,42 @@
+/**
+ * RFC 7636 (PKCE, S256) using the Web Crypto API — no dependency.
+ *
+ * PKCE is what lets a browser be an OAuth client with NO SECRET. The client
+ * generates a random verifier, sends only its SHA-256 hash to start the flow,
+ * and presents the verifier when redeeming the code. An attacker who steals the
+ * authorization code cannot redeem it without the verifier, which never left
+ * the browser that started the flow.
+ *
+ * That is the whole reason this site needs no server: there is nothing to keep
+ * secret, so there is nothing that must live somewhere the reader cannot see.
+ */
+
+/** Base64url without padding — RFC 7636 §4.2 requires exactly this alphabet. */
+function base64url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function randomBase64url(byteLength: number): string {
+  const bytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(bytes);
+  return base64url(bytes);
+}
+
+export interface PkcePair {
+  readonly verifier: string;
+  readonly challenge: string;
+}
+
+/** A verifier and its S256 challenge. 32 bytes → 43 chars, the RFC's minimum. */
+export async function createPkcePair(): Promise<PkcePair> {
+  const verifier = randomBase64url(32);
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return { verifier, challenge: base64url(new Uint8Array(digest)) };
+}
+
+/** CSRF state, bound to this flow and checked when the issuer redirects back. */
+export function createState(): string {
+  return randomBase64url(16);
+}

package/templates/scaffold/system/site/lib/auth/session.ts

@@ -0,0 +1,81 @@
+/**
+ * The reader's identity, for as long as the tab is open.
+ *
+ * Storage is `sessionStorage`, deliberately, and it is the one decision here
+ * worth arguing about. The alternative — `localStorage` with long-lived tokens
+ * — is what the predecessor did and is what NOT to copy: a token readable by
+ * any script on the origin, surviving for days, for a feature that grants no
+ * access to anything on this site. The blast radius should match the benefit.
+ *
+ * So: per-tab, gone when the tab closes, and no refresh token is requested at
+ * all. Signing in again is one redirect through an issuer that already knows
+ * the reader; it is not worth holding a long-lived credential to avoid.
+ */
+
+const KEY = "ksor.session";
+
+export interface Session {
+  /** The `sub` claim — the issuer's stable identifier for this reader. */
+  readonly subject: string;
+  readonly name: string | null;
+  readonly email: string | null;
+  /**
+   * The issuer's access token. Held because a session without one is not a
+   * session — NOT because anything here calls an API with it yet. No audience
+   * is requested, so it is the issuer's own token and the door would refuse it.
+   */
+  readonly accessToken: string;
+  /** Epoch milliseconds. A session past this is treated as absent. */
+  readonly expiresAt: number;
+}
+
+function isSession(value: unknown): value is Session {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v["subject"] === "string" &&
+    typeof v["accessToken"] === "string" &&
+    typeof v["expiresAt"] === "number" &&
+    (v["name"] === null || typeof v["name"] === "string") &&
+    (v["email"] === null || typeof v["email"] === "string")
+  );
+}
+
+/**
+ * The stored session, or null.
+ *
+ * Every failure returns null rather than throwing: storage can be unavailable
+ * (private windows, blocked site data), the value can be another version's
+ * shape, and none of those are worth breaking a page render over.
+ */
+export function readSession(): Session | null {
+  try {
+    const raw = sessionStorage.getItem(KEY);
+    if (raw === null) return null;
+    const parsed: unknown = JSON.parse(raw);
+    if (!isSession(parsed)) return null;
+    if (Date.now() >= parsed.expiresAt) {
+      sessionStorage.removeItem(KEY);
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function writeSession(session: Session): void {
+  try {
+    sessionStorage.setItem(KEY, JSON.stringify(session));
+  } catch {
+    /* storage unavailable: the reader stays signed out, which is honest */
+  }
+}
+
+export function clearSession(): void {
+  try {
+    sessionStorage.removeItem(KEY);
+  } catch {
+    /* nothing to do — a session that cannot be read cannot be used */
+  }
+}

package/templates/scaffold/system/site/lib/layout.shared.tsx

@@ -1,4 +1,6 @@
 import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
+
+import { SignIn } from "@/components/sign-in";
 import { appTitle } from "./shared";
 
 export function baseOptions(): BaseLayoutProps {
@@ -13,5 +15,9 @@ export function baseOptions(): BaseLayoutProps {
         </span>
       ),
     },
+    // `secondary` puts it at the navbar's trailing edge, beside the theme
+    // toggle. SignIn renders null when no issuer is configured, so a record
+    // that does not offer sign-in shows nothing rather than an empty slot.
+    links: [{ type: "custom", secondary: true, children: <SignIn /> }],
   };
 }

package/templates/scaffold/system/site/next.config.mjs

@@ -1,4 +1,5 @@
 import { createMDX } from "fumadocs-mdx/next";
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -10,6 +11,28 @@ const withMDX = createMDX();
 // resolved from this file's own location so it holds wherever the repo lands.
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
+// The record keeps ONE .env, at the repo root, because that is where `ksor`
+// reads it. This build runs in system/site, so Next would never see it — and an
+// adopter following the scaffold's own instructions would set NEXT_PUBLIC_*
+// variables that silently never reach the bundle (found live). Read the root
+// file here, and let a real environment variable win, which is the same
+// precedence the CLI states.
+function loadRootEnv() {
+  let contents;
+  try {
+    contents = readFileSync(path.join(repoRoot, ".env"), "utf8");
+  } catch {
+    return; // no .env is the normal case — only .env.example ships
+  }
+  for (const line of contents.split("\n")) {
+    const match = /^\s*(NEXT_PUBLIC_[A-Z0-9_]+)\s*=\s*(.*)$/.exec(line);
+    if (match?.[1] !== undefined && process.env[match[1]] === undefined) {
+      process.env[match[1]] = (match[2] ?? "").trim().replace(/^["']|["']$/g, "");
+    }
+  }
+}
+loadRootEnv();
+
 /** @type {import('next').NextConfig} */
 const config = {
   reactStrictMode: true,