Release the gate change as 0.3.0, and start a changelog

CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+The release version **is** the plugin contract version (`HOST_API_VERSION`), so a minor is a
+contract break: a plugin's `apiVersion` must match the host's `major.minor` or discovery refuses it
+at boot. Entries start at 0.3.0.
+
+## 0.3.0
+
+**Breaking.** Set `apiVersion: "0.3.0"`, and name a gate on every route and nav node.
+
+### A session is a gate of its own
+
+`session: true` takes any signed-in user, with no grant to hold — for a page whose data is the
+visitor's own (their upstream account, their own tokens), where there is no distinction a permission
+could name. An anonymous visitor is bounced to `/login` with the page as `return_to`, exactly as a
+permission gate does.
+
+Every route and nav node now names **exactly one** of `public: true`, `session: true` or
+`permission: "<resource>:<action>"`, and a gate is spelled `true`:
+
+- Naming **none** is refused. It used to mean public, so a forgotten gate published a page; it now
+  fails the boot instead.
+- Naming **two** is refused, as before.
+- Spelling one anything but `true` is refused — `public: false` and `session: "yes"` both set no gate
+  while reading as if they set one.
+
+A section header gates nothing itself, so it takes `public: true` and lets each child decide; the
+host still drops a header whose children all filtered out.
+
+`Gate` is exported from `@plainpages/plugin-api`, and `Route` and `NavNode` extend it.
+
+### Filter bars take a multi-select
+
+The `filter-bar` partial gains a `multiselect` control — the same checkboxes on the same query
+parameter as `chips`, but behind a button once the list is too long to lay on the bar. Config is
+`{ name, legend?, note?, value?, options }`, and the panel says what a capped list left out.
+
+### Fixed
+
+- An identity carrying no email no longer yields a session at all. Login used to mint a JWT for one,
+  which every later request then rejected as anonymous — leaving the browser holding a dead cookie
+  and no way to tell why.
+
+### Dependencies
+
+- Node 24.20.0.
+
+### Upgrading a plugin
+
+1. Set `apiVersion: "0.3.0"`.
+2. Give every route and nav node a gate. Anything that relied on omitting one was public — say
+   `public: true` outright.
+
+A page that scopes rows to the signed-in visitor should join on `ctx.user.id`. An email address is
+user-changeable and can be reassigned to someone else, who would then inherit the previous holder's
+rows. The reference plugin's new `/scheduling/mine` page shows the shape.

README.md

@@ -47,7 +47,7 @@ folder under `plugins/` goes live after a restart. Create `plugins/hello/plugin.
 import { definePlugin } from "@plainpages/plugin-api";
 
 export default definePlugin({
-  apiVersion: "0.4.0",
+  apiVersion: "0.3.0",
   nav: [{ href: "/hello", id: "hello", label: "Hello", public: true }],
   routes: [
     { method: "GET", path: "/", public: true, handler: () => ({ html: "<h1>Hello from my plugin</h1>" }) },
@@ -350,7 +350,7 @@ import { definePlugin } from "@plainpages/plugin-api";
 import { listThings, createThings } from "./handlers.ts";
 
 export default definePlugin({
-  apiVersion: "0.4.0",                // semver string of the host contract this plugin was built against (see Versioning)
+  apiVersion: "0.3.0",                // semver string of the host contract this plugin was built against (see Versioning)
 
   // Nav fragment, merged into the global menu and gate-filtered per user.
   // `icon` is a Lucide icon by its sprite id (src/ui/icons.ts).
@@ -471,7 +471,7 @@ import { definePlugin } from "@plainpages/plugin-api";
 import { landing, board } from "./pages.ts";
 
 export default definePlugin({
-  apiVersion: "0.4.0",
+  apiVersion: "0.3.0",
   home: landing,     // owns "/" — the public front page
   dashboard: board,  // owns "/dashboard" — the post-login app home
 });
@@ -626,6 +626,7 @@ provider/consumer semantics in `checkApiVersion`:
 The plugin pins one exact version (no ranges, per the project's pinning rules); the *host* supplies
 the compatibility. One digit carries the whole release, so a **minor** means either the plugin
 contract changed or a dependency moved far enough to warrant one.
+[`CHANGELOG.md`](CHANGELOG.md) is what a minor sends you to: what broke, and what to change.
 
 
 ### Conflict rules
@@ -756,7 +757,7 @@ camel humps both becoming underscores — so `upstream` on the `scheduling` plug
 
 ```ts
 export default definePlugin({
-  apiVersion: "0.4.0",
+  apiVersion: "0.3.0",
   settings: [
     { key: "upstream", type: "url", required: true, description: "Base URL of the backend" },
     { key: "pageSize", type: "number", default: 25 },
@@ -810,7 +811,7 @@ import { definePlugin } from "@plainpages/plugin-api";
 let sql: ReturnType<typeof postgres>;
 
 export default definePlugin({
-  apiVersion: "0.4.0",
+  apiVersion: "0.3.0",
   storage: true,
   hooks: {
     onBoot: async (boot) => {
@@ -1730,6 +1731,7 @@ e2e-tests/           Playwright specs + their Dockerfile and compose.{visual,aut
 release-tooling/     Everything the release runs: next-version (the bump math), contract-version
                      (the HOST_API_VERSION↔tag gate), dockerhub-overview (+ its .md.tmpl)
 registry-cleanup/    Nightly image pruning — the Gitea client plus what survives (select-versions.ts)
+CHANGELOG.md         What changed per release, and how to upgrade a plugin across a minor
 ci.sh                The full gate: typecheck → unit tests → every E2E suite on a fresh stack
 .gitea/workflows/    Gitea Actions — see CI/CD
 ```

examples/plugins/admin/plugin.ts

@@ -28,7 +28,7 @@ const clients = on("oauth2-clients");
 const pluginSettings = on("plugin-settings");
 
 export default definePlugin({
-  apiVersion: "0.4.0", // the host contract this was built against — a literal, never HOST_API_VERSION
+  apiVersion: "0.3.0", // the host contract this was built against — a literal, never HOST_API_VERSION
 
   nav: [ADMIN_NAV],
 

examples/plugins/scheduling/README.md

@@ -45,6 +45,11 @@ Your backend must expose two routes; the plugin treats any non-2xx as a recovera
 | `GET /shifts` | `Accept: application/json`, optional `?assigneeId=<id>` | `200` | JSON array of `{ id, title, assignee, assigneeId, start, end }` (all strings; missing fields coerce to `""`). With `assigneeId`, only that person's rows |
 | `POST /shifts` | JSON body `{ title, assignee, start, end }` | `2xx` | ignored (the plugin POST-redirect-GETs back to the list) |
 
+`POST /shifts` carries the assignee as a **display name only**, so a shift created through this
+plugin's form belongs to nobody and surfaces on no one's "My shifts" — don't go hunting for it
+there. Resolving a name to an identity id needs a directory this demo has none of; a real backend
+does that join at create time and stores the `assigneeId` alongside the name.
+
 Domain rules (overlap, capacity, time ordering) live in your backend — reject with a 4xx and the
 form re-renders. The plugin only validates that `title` and `assignee` are non-empty.
 

examples/plugins/scheduling/i18n/en-US.ts

@@ -22,6 +22,7 @@ const messages = {
   "scheduling.new.title": "New shift",
   "scheduling.overview.lead":
     "Scheduling coordinates shifts across your team. Anyone can read this overview; the shift list itself is available to people with the <code>scheduling:read</code> permission.",
+  "scheduling.overview.mine": "See my shifts",
   "scheduling.overview.signIn": "Sign in to view shifts",
   "scheduling.overview.title": "Scheduling",
   "scheduling.overview.view": "View shifts",

examples/plugins/scheduling/i18n/sv-SE.ts

@@ -18,6 +18,7 @@ const messages: SchedulingMessages = {
   "scheduling.new.title": "Nytt pass",
   "scheduling.overview.lead":
     "Schemaläggningen samordnar teamets pass. Alla kan läsa den här översikten; själva passlistan kräver behörigheten <code>scheduling:read</code>.",
+  "scheduling.overview.mine": "Visa mina pass",
   "scheduling.overview.signIn": "Logga in för att se passen",
   "scheduling.overview.title": "Schemaläggning",
   "scheduling.overview.view": "Visa pass",

examples/plugins/scheduling/plugin.ts

@@ -12,7 +12,7 @@ let upstreamUrl = "";
 const upstream = createUpstream(() => upstreamUrl);
 
 export default definePlugin({
-  apiVersion: "0.4.0", // the host contract this was built against — a literal, never HOST_API_VERSION
+  apiVersion: "0.3.0", // the host contract this was built against — a literal, never HOST_API_VERSION
 
   // onBoot runs after discovery, before the server listens — where a plugin receives its resolved
   // settings. A malformed URL already failed the boot by then; the host validated the declared type.

examples/plugins/scheduling/shifts.test.ts

@@ -115,14 +115,21 @@ test("listShifts degrades to a recoverable error page when the upstream is down
 
 // ---- public overview handler (a page anyone can reach, gated data stays behind the permission) ----
 
-test("overview renders a public page for anyone; it links straight to Shifts only for a reader", async () => {
+test("overview renders a public page for anyone, and its CTA names the best gate the visitor passes", async () => {
   const anon = asView(await overview()(fakeCtx())); // user null, no permissions
   assert.equal(anon.view, "overview");
   assert.equal(anon.data["chrome"], CHROME);
   assert.equal(anon.data["canRead"], false); // anonymous → prompt to sign in, no shifts link
+  assert.equal(anon.data["signedIn"], false);
 
   const reader = asView(await overview()(fakeCtx({ permissions: ["scheduling:read"] })));
   assert.equal(reader.data["canRead"], true); // a reader gets a link straight to the shifts list
+
+  // Signed in but ungranted: the page must not invite them to sign in again.
+  const member = asView(await overview()(fakeCtx({ user: { email: "m@example.test", id: "01a06091-baa3-7a1f-9c62-0e3ab6d2f5c1", permissions: [] } })));
+  assert.equal(member.data["canRead"], false);
+  assert.equal(member.data["signedIn"], true);
+  assert.equal(member.data["mineHref"], "/scheduling/mine");
 });
 
 // ---- create handler ----

examples/plugins/scheduling/shifts.ts

@@ -236,7 +236,9 @@ export function overview(): RouteHandler {
       breadcrumbs: [{ label: ctx.t("scheduling.nav.overview") }],
       canRead: can(ctx, READ),
       chrome: ctx.chrome,
+      mineHref: ctx.localeHref(MINE_PATH),
       shiftsHref: ctx.localeHref(SHIFTS_PATH), // a plugin carries the visitor's locale onto its own links
+      signedIn: ctx.user !== null,
       signInHref: ctx.localeHref(`/login?return_to=${encodeURIComponent(ctx.localeHref(SHIFTS_PATH))}`),
       title: ctx.t("scheduling.overview.title"),
     },

examples/plugins/scheduling/views/overview.ejs

@@ -3,12 +3,16 @@
   nav node are marked `public`, so an anonymous visitor is let through and the menu option shows for
   everyone. The actual shifts data stays behind `scheduling:read`: a reader gets a link straight to
   it, anyone else a prompt to sign in. Rendered in the native shell via ctx.chrome.
-  Data: chrome, title, breadcrumbs, canRead, shiftsHref, signInHref
+  Data: chrome, title, breadcrumbs, canRead, mineHref, shiftsHref, signedIn, signInHref
 %><%
   const navHtml = include("partials/nav-tree", { nodes: chrome.nav });
+  // One CTA per gate the visitor passes: the list needs the permission, "My shifts" only a session,
+  // and sign-in is offered to nobody who already has one.
   const cta = canRead
     ? '<a class="btn btn-primary" href="' + shiftsHref + '">' + t("scheduling.overview.view") + '</a>'
-    : '<a class="btn btn-primary" href="' + signInHref + '">' + t("scheduling.overview.signIn") + '</a>';
+    : signedIn
+      ? '<a class="btn btn-primary" href="' + mineHref + '">' + t("scheduling.overview.mine") + '</a>'
+      : '<a class="btn btn-primary" href="' + signInHref + '">' + t("scheduling.overview.signIn") + '</a>';
 -%>
 <%- include("partials/shell", {
   actions: "",

release-tooling/contract-version.test.ts

@@ -12,7 +12,7 @@ test("readHostApiVersion pulls the constant out of the real source, and returns
 test("bumping HOST_API_VERSION is a deliberate act, so pin the shipped value", () => {
   // Not a substitute for the release gate — this test cannot see a tag. It is the tripwire that
   // makes an accidental edit fail here rather than at release time.
-  assert.equal(readHostApiVersion(readFileSync("src/plugin-host/plugin.ts", "utf8")), "0.4.0");
+  assert.equal(readHostApiVersion(readFileSync("src/plugin-host/plugin.ts", "utf8")), "0.3.0");
 });
 
 test("every author-facing apiVersion sample matches the shipped contract", () => {

release-tooling/dockerhub-overview.md.tmpl

@@ -182,7 +182,7 @@ into the app. Create `plugins/hello/plugin.ts`:
 import { definePlugin } from "@plainpages/plugin-api";
 
 export default definePlugin({
-  apiVersion: "0.4.0",
+  apiVersion: "0.3.0",
   nav: [{ href: "/hello", id: "hello", label: "Hello", public: true }],
   routes: [
     { method: "GET", path: "/", public: true, handler: () => ({ html: "<h1>Hello from my plugin</h1>" }) },

src/plugin-host/plugin.ts

@@ -11,7 +11,7 @@ import { envName, type SettingDecl, type SettingsOf } from "./settings.ts";
 import type { StorageCredentials } from "./storage.ts";
 
 // The Plainpages release this contract ships in — see README → Contract versioning.
-export const HOST_API_VERSION = "0.4.0";
+export const HOST_API_VERSION = "0.3.0";
 
 export type HttpMethod = "DELETE" | "GET" | "HEAD" | "PATCH" | "POST" | "PUT";
 

todo.md

@@ -20,6 +20,7 @@
 - [ ] Decide what `ICON_NAMES` (`src/ui/icons.ts`) actually is. `i-chart`, `i-copy`, `i-download` and `i-sliders` have no caller anywhere — so either they go, or the comment should say the palette is curated and may carry an id ahead of its first use. Not cosmetic: the sprite is inlined into every page, and the rule decides whether a future removal is routine cleanup or a plugin-facing regression.
 - [ ] Decide (once) whether the CSRF token staying unbound to `sub`/session is accepted. `src/auth/csrf.ts` signs `<nonce>.<HMAC(secret, nonce)>` with no session binding, so any validly-signed token passes for any user — an attacker who can write cookies on the origin can fix a token they know. Standard for unbound signed double-submit and plausibly fine behind `SameSite=Lax` + HSTS. Accepted ⇒ record it in AGENTS.md and README → Security model; not accepted ⇒ bind the nonce to `sub`.
 - [ ] Verify the documented Docker commands on macOS and fix whatever misbehaves — **macOS is a supported dev host**, but nothing here has been run on one. Two suspects, both from the `--user "$(id -u):$(id -g)"` idiom: a macOS `id -g` is `20`, which is `dialout` inside the noble image rather than a user group, and Docker Desktop remaps bind-mount ownership in its own VM layer. The same question covers rootless Docker, where README already says to *drop* the flag.
+- [ ] Map Kratos' 401 on a self-service flow init, so an anonymous `GET /settings` with no `?flow` renders instead of 500ing. `flowPage` (`src/auth/routes.ts`) maps 403/404/410 → restart the flow, 400 `session_already_available` → `/auth/complete`, and ≥500 → the themed 503, then rethrows everything else — and Kratos answers the settings-flow init with 401 when there is no session. `/settings` is correctly `public` (the recovery flow lands there with a live Kratos session but no app JWT), so the gate is not the fix: a 401 should redirect to `/login` with the page as `return_to`. No E2E covers an anonymous hit on a flow page that needs a session.
 
 ### Architectural review findings (2026-07-02)
 

views/index.ejs

@@ -14,7 +14,7 @@
         <p>${t("dashboard.starter.intro")}</p>
         <p>${t("dashboard.starter.replace")}</p>
 <pre class="code-block"><code>export default definePlugin({
-  apiVersion: "0.4.0",
+  apiVersion: "0.3.0",
   // view names plugins/&lt;id&gt;/views/&lt;view&gt;.ejs, rendered in this same shell
   dashboard: (ctx) =&gt; ({ view: "dashboard", data: { /* … */ } }),
 });</code></pre>