Gate a route or nav node on a session, not only a permission

examples/plugins/scheduling/README.md

@@ -15,8 +15,9 @@ What it demonstrates:
   `POST /scheduling/shifts` CSRF-verifies it (`ctx.verifyCsrf`) and forwards the create upstream,
   then POST-redirect-GET. The form body lives in the plugin's own `views/partials/shift-form.ejs`,
   reusing the core `field` partial.
-- **Permission-gated nav** — the "Shifts" nav leaf and routes are gated on `scheduling:read` /
-  `scheduling:write`; the whole "Scheduling" section is invisible to anyone without the grant.
+- **All three route gates** — the Overview is `public` (anyone), "My shifts" is `session` (any
+  signed-in visitor, showing only rows assigned to them), and "Shifts" is gated on `scheduling:read` /
+  `scheduling:write`; a leaf whose gate a visitor fails is invisible in the menu.
 - **Its own translations** — every string comes from `i18n/en-US.ts` (`sv-SE.ts` beside it), including
   the nav labels, which are catalog keys in the manifest. `shifts.count` shows a plural message, and
   the views carry the visitor's language onto their links with `localeHref()`.
@@ -50,6 +51,7 @@ cosmetically) — normalise to your backend's format there if it matters.
 
 ## Granting access
 
-A user sees Scheduling once they hold the `scheduling:read` permission in Keto (and `scheduling:write`
-to create). The one-command bootstrap grants both to the demo admin, so the seeded
-`admin@plainpages.local` can use it immediately.
+A user sees the shift list once they hold the `scheduling:read` permission in Keto (and
+`scheduling:write` to create). The one-command bootstrap grants both to the demo admin, so the seeded
+`admin@plainpages.local` can use it immediately. "My shifts" needs no grant at all — signing in is
+its whole gate.

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

@@ -13,6 +13,9 @@ const messages = {
   "scheduling.filter.searchLabel": "Search shifts",
   "scheduling.filter.searchPlaceholder": "Search title or assignee…",
   "scheduling.form.submit": "Create shift",
+  "scheduling.mine.empty": "No shifts are assigned to {{email}}.",
+  "scheduling.mine.title": "My shifts",
+  "scheduling.nav.mine": "My shifts",
   "scheduling.nav.overview": "Overview",
   "scheduling.nav.section": "Scheduling",
   "scheduling.nav.shifts": "Shifts",

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

@@ -9,6 +9,9 @@ const messages: SchedulingMessages = {
   "scheduling.filter.searchLabel": "Sök pass",
   "scheduling.filter.searchPlaceholder": "Sök på namn eller person…",
   "scheduling.form.submit": "Skapa pass",
+  "scheduling.mine.empty": "Inga pass är tilldelade {{email}}.",
+  "scheduling.mine.title": "Mina pass",
+  "scheduling.nav.mine": "Mina pass",
   "scheduling.nav.overview": "Översikt",
   "scheduling.nav.section": "Schemaläggning",
   "scheduling.nav.shifts": "Pass",

examples/plugins/scheduling/plugin.ts

@@ -3,7 +3,7 @@
 // folder, rename it, point it at your own backend. Full contract: README.md → Building plugins.
 
 import { definePlugin } from "@plainpages/plugin-api";
-import { createShift, createUpstream, listShifts, newShiftForm, overview, READ, SCHEDULING_PATH, SHIFTS_PATH, WRITE } from "./shifts.ts";
+import { createShift, createUpstream, listShifts, MINE_PATH, myShifts, newShiftForm, overview, READ, SCHEDULING_PATH, SHIFTS_PATH, WRITE } from "./shifts.ts";
 
 // The upstream this plugin reads/writes — a stand-in for your real backend (the plugin is
 // stateless). Its URL is a declared setting, so it is resolved and validated before onBoot hands it
@@ -25,6 +25,7 @@ export default definePlugin({
   nav: [{
     children: [
       { href: SCHEDULING_PATH, id: "scheduling:overview", label: "scheduling.nav.overview", public: true },
+      { href: MINE_PATH, id: "scheduling:mine", label: "scheduling.nav.mine", session: true },
       { href: SHIFTS_PATH, id: "scheduling:shifts", label: "scheduling.nav.shifts", permission: READ },
     ],
     icon: "i-cal",
@@ -42,6 +43,7 @@ export default definePlugin({
   // (anyone may reach /scheduling, signed in or not); the rest need a permission.
   routes: [
     { handler: overview(), method: "GET", path: "/", public: true },
+    { handler: myShifts(upstream), method: "GET", path: "/mine", session: true },
     { handler: listShifts(upstream), method: "GET", path: "/shifts", permission: READ },
     { handler: newShiftForm(), method: "GET", path: "/shifts/new", permission: WRITE },
     { handler: createShift(upstream), method: "POST", path: "/shifts", permission: WRITE },

examples/plugins/scheduling/shifts.test.ts

@@ -4,21 +4,21 @@ import { Readable } from "node:stream";
 import test from "node:test";
 // Import only from the @plainpages/plugin-api barrel — the same contract boundary shifts.ts uses (the host may
 // refactor any deeper src/* freely behind it); the test models the dev/test story the contract preaches.
-import { englishTranslator, GuardError, Log, type PageChrome, type RequestContext, type RouteResult } from "@plainpages/plugin-api";
+import { englishTranslator, GuardError, Log, type PageChrome, type RequestContext, type RouteResult, type User } from "@plainpages/plugin-api";
 import enUS from "./i18n/en-US.ts";
 import {
-  buildFormModel, createShift, createUpstream, listShifts, newShiftForm, overview, readInput,
+  buildFormModel, createShift, createUpstream, listShifts, myShifts, newShiftForm, overview, readInput,
   SHIFTS_PATH, type Shift, type ShiftInput, type ShiftsUpstream, UpstreamError, validate,
 } from "./shifts.ts";
 
 const t = englishTranslator(enUS); // this plugin's catalog then the host's, as the host would chain them
 const CHROME: PageChrome = { brand: { name: "Test" }, csrfToken: "tok", nav: [], signInHref: "/login", user: { email: "", initials: "T", name: "Tester" } };
 
-function fakeCtx(opts: { body?: string; permissions?: string[]; url?: string; verifyCsrf?: (s: string | null | undefined) => boolean } = {}): RequestContext {
+function fakeCtx(opts: { body?: string; permissions?: string[]; url?: string; user?: User; verifyCsrf?: (s: string | null | undefined) => boolean } = {}): RequestContext {
   const url = new URL(opts.url ?? "http://localhost/scheduling/shifts");
   const req = Readable.from(opts.body != null ? [Buffer.from(opts.body)] : []) as unknown as IncomingMessage;
   return {
-    chrome: CHROME, declaredPermissions: [], declaredSettings: [], user: null, locale: "en-US", localeHref: (href) => href, locales: ["en-US"], log: new Log("none"), params: {},
+    chrome: CHROME, declaredPermissions: [], declaredSettings: [], user: opts.user ?? null, locale: "en-US", localeHref: (href) => href, locales: ["en-US"], log: new Log("none"), params: {},
     query: url.searchParams, req, res: {} as ServerResponse, permissions: opts.permissions ?? [], t, url,
     verifyCsrf: opts.verifyCsrf ?? (() => true),
   };
@@ -171,3 +171,20 @@ test("buildFormModel marks title/assignee required and attaches field errors", (
   assert.equal(title.error, "needed");
   assert.equal(fields.find((f) => f.name === "start")!.required, undefined);
 });
+
+// ---- the session-gated page: the visitor's own rows ----
+
+test("my shifts renders only the signed-in visitor's own rows, and names them in the empty state", async () => {
+  const user: User = { email: "Blair.Mora@example.test", id: "01a06091-baa3-71f4-a068-4879972979ff", permissions: [] };
+  const mine: Shift = { assignee: "blair.mora@example.test", end: "22:00", id: "3", start: "17:00", title: "Evening on-call" };
+  const listed = [...SHIFTS, mine]; // SHIFTS are assigned to other people
+
+  const r = asView(await myShifts(fakeUpstream({ list: async () => listed }))(fakeCtx({ url: "http://localhost/scheduling/mine", user })));
+  assert.equal(r.view, "mine");
+  const table = r.data["table"] as { emptyText: string; rows: { name: string }[] };
+  assert.deepEqual(table.rows.map((row) => row.name), ["Evening on-call"]); // matched case-insensitively
+  assert.match(table.emptyText, /Blair\.Mora@example\.test/); // an empty page still says whose it is
+
+  // The route carries `session: true`, but the handler asserts the session itself rather than trusting it.
+  await assert.rejects(async () => { await myShifts(fakeUpstream())(fakeCtx()); }, GuardError);
+});

examples/plugins/scheduling/shifts.ts

@@ -6,7 +6,7 @@
 // pure functions against a mock upstream with no network (README.md → Local dev & test story).
 
 // One import from the host's @plainpages/plugin-api barrel — the stable author surface (see README.md → Building plugins).
-import { can, CSRF_FIELD, englishTranslator, GuardError, type PageChrome, parseListQuery, readFormBody, type RouteHandler, type Translate, tracedFetch } from "@plainpages/plugin-api";
+import { can, CSRF_FIELD, englishTranslator, GuardError, type PageChrome, parseListQuery, readFormBody, requireSession, type RouteHandler, type Translate, tracedFetch } from "@plainpages/plugin-api";
 import enUS from "./i18n/en-US.ts";
 
 // The plugin's own English (its catalog, then the host's), for a view model built outside a request:
@@ -16,6 +16,7 @@ const EN: Translate = englishTranslator(enUS);
 
 export const SCHEDULING_PATH = "/scheduling"; // the plugin's public overview page
 export const SHIFTS_PATH = "/scheduling/shifts";
+export const MINE_PATH = "/scheduling/mine"; // the visitor's own shifts — a session is the whole gate
 export const READ = "scheduling:read"; // the permission gating the list + nav
 export const WRITE = "scheduling:write"; // the permission gating create
 
@@ -190,6 +191,41 @@ export function newShiftForm(): RouteHandler {
 // gate lets an anonymous visitor through and the menu option shows for everyone. The real data
 // (the shifts list) stays behind `scheduling:read`; a reader gets a link straight to it, anyone
 // else a prompt to sign in. ctx.user may be null here, so read the permission via can() (zero I/O).
+// The `session: true` archetype: the rows are the visitor's own, so there is no distinction a
+// permission could name — anyone signed in sees theirs and only theirs.
+export function myShifts(upstream: ShiftsUpstream): RouteHandler {
+  return async (ctx) => {
+    const user = requireSession(ctx);
+    let shifts: Shift[] = [];
+    let error: string | undefined;
+    try {
+      shifts = await upstream.list();
+    } catch (err) {
+      ctx.log.warn("scheduling upstream unreachable", { error: String(err) });
+      error = ctx.t("scheduling.upstream.list");
+    }
+    const mine = shifts.filter((s) => s.assignee.toLowerCase() === user.email.toLowerCase());
+    return { data: buildMineModel({ chrome: ctx.chrome, email: user.email, ...(error ? { error } : {}), shifts: mine, t: ctx.t }), view: "mine" };
+  };
+}
+
+export function buildMineModel(opts: { chrome: PageChrome; email: string; error?: string; shifts: Shift[]; t?: Translate }) {
+  const t = opts.t ?? EN;
+  return {
+    breadcrumbs: [{ label: t("scheduling.mine.title") }],
+    chrome: opts.chrome,
+    count: t("scheduling.shifts.count", { count: opts.shifts.length }),
+    ...(opts.error ? { error: opts.error } : {}),
+    table: {
+      caption: t("scheduling.mine.title"),
+      columns: [{ label: t("scheduling.table.shift") }, { label: t("scheduling.table.start") }, { label: t("scheduling.table.end") }],
+      emptyText: t("scheduling.mine.empty", { email: opts.email }),
+      rows: opts.shifts.map((s) => ({ cells: [{ rowHeader: { text: s.title } }, s.start, s.end], name: s.title })),
+    },
+    title: t("scheduling.mine.title"),
+  };
+}
+
 export function overview(): RouteHandler {
   return (ctx) => ({
     data: {

examples/plugins/scheduling/views/mine.ejs

@@ -0,0 +1,20 @@
+<%#
+  Scheduling · the visitor's own shifts (reference plugin). Reached behind `session: true`, so
+  ctx.user is always set by the time this renders.
+  Data: chrome, title, breadcrumbs, count, table, error?
+%><%
+  const navHtml = include("partials/nav-tree", { nodes: chrome.nav });
+  const tableHtml = include("partials/data-table", table);
+  const alertHtml = locals.error ? include("partials/alert", { text: locals.error, tone: "neg" }) : "";
+-%>
+<%- include("partials/shell", {
+  body: '<div class="scheduling-page">' + alertHtml + '<p class="shift-count">' + count + '</p>' + tableHtml + '</div>',
+  brand: chrome.brand,
+  breadcrumbs,
+  csrfToken: chrome.csrfToken,
+  nav: navHtml,
+  styles: ["/public/scheduling/scheduling.css"],
+  theme: chrome.theme,
+  title,
+  user: chrome.user,
+}) %>