Logout (todo §4); GET /logout clears plainpages_jwt + revokes the Kratos session (createLogoutFlow → redirect to Kratos logout URL → /login); wire shell Sign out link

README.md

@@ -504,7 +504,7 @@ src/static.ts        Static file serving (path-traversal protection) + routePubl
 src/jwt.ts           JWS signature verify via node:crypto, no jose (decode + verify a compact JWS against one JWK)
 src/jwt-middleware.ts resolveSession()/authenticate(): per-request session-JWT verify — key by kid → signature → exp/nbf/iss/aud (clock skew) → ctx.user/roles; flags a lapsed token for re-mint (§4)
 src/jwks.ts          JwksProvider — resolve the verify key by kid; createJwksProvider() picks by scheme: staticJwks (base64) or cachingJwks (file/http: TTL cache + rotation-on-miss reload)
-src/kratos-public.ts createKratosPublic(): Kratos public-API fetch client — self-service flow init/get/submit, whoami, session→JWT tokenize (§4)
+src/kratos-public.ts createKratosPublic(): Kratos public-API fetch client — self-service flow init/get/submit, browser logout, whoami, session→JWT tokenize (§4)
 src/kratos-admin.ts  createKratosAdmin(): Kratos admin-API fetch client — identity CRUD + surgical metadata_public update (login role projection, §4)
 src/keto-client.ts   createKetoClient(): Keto fetch client — check / list / expand relations (read API) + write / delete tuples (write API) (§4)
 src/flow-view.ts     buildFlowView(): Kratos self-service Flow → themed view model (fields, hidden csrf, buttons, tone-mapped messages) for views/auth.ejs (§4)

src/app.test.ts

@@ -314,6 +314,7 @@ const loginFlow = (id: string): Flow => ({
 
 function mockKratos(getFlow: KratosPublic["getFlow"]): KratosPublic {
   return {
+    createLogoutFlow: async () => null,
     getFlow,
     initBrowserFlow: async (_t: FlowType) => ({ flow: { id: "new1", ui: { action: "", method: "post", nodes: [] } }, setCookie: ["csrf_token=abc; Path=/; HttpOnly"] }),
     submitFlow: async () => { throw new Error("unused"); },
@@ -408,6 +409,27 @@ test("login completion with no Kratos session redirects to /login and sets no co
   assert.equal(res.headers.get("set-cookie"), null);
 });
 
+test("logout: bounces to Kratos to revoke the session and clears our JWT cookie; no session → /login", async (t) => {
+  const logoutUrl = "http://127.0.0.1:4433/self-service/logout?token=lt";
+  const kratos: KratosPublic = { ...mockKratos(async () => { throw new Error("unused"); }), createLogoutFlow: async (o) => (o?.cookie ? { logoutToken: "lt", logoutUrl } : null) };
+  const app = createApp({ kratos });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+
+  // Active session → redirect to Kratos' logout URL (it revokes + clears plainpages_session, then → /login).
+  const out = await fetch(url + "/logout", { headers: { cookie: `${SESSION_COOKIE}=x; plainpages_session=s` }, redirect: "manual" });
+  assert.equal(out.status, 303);
+  assert.equal(out.headers.get("location"), logoutUrl);
+  assert.match(out.headers.get("set-cookie") ?? "", /^plainpages_jwt=;.*Max-Age=0/);
+
+  // No active Kratos session → clear our cookie and land on /login ourselves.
+  const none = await fetch(url + "/logout", { redirect: "manual" });
+  assert.equal(none.status, 303);
+  assert.equal(none.headers.get("location"), "/login");
+  assert.match(none.headers.get("set-cookie") ?? "", /^plainpages_jwt=;.*Max-Age=0/);
+});
+
 test("resolveStaticPath blocks traversal and control chars, allows nested files", () => {
   assert.equal(resolveStaticPath("/srv/public", "../app.ts"), null);
   assert.equal(resolveStaticPath("/srv/public", "a\x00b"), null);

src/app.ts

@@ -13,7 +13,7 @@ import { resolveSession, type VerifyOptions } from "./jwt-middleware.ts";
 import type { KetoClient } from "./keto-client.ts";
 import type { KratosAdmin } from "./kratos-admin.ts";
 import { KratosError, type KratosPublic } from "./kratos-public.ts";
-import { completeLogin, remintSession, sessionCookie } from "./login.ts";
+import { clearSessionCookie, completeLogin, remintSession, sessionCookie } from "./login.ts";
 import { DEFAULT_MENU, type MenuConfig } from "./menu-config.ts";
 import type { Plugin, RouteResult } from "./plugin.ts";
 import { allowedMethods, isAuthorized, matchRoute } from "./router.ts";
@@ -157,6 +157,16 @@ export function createApp(options: AppOptions = {}): Server {
         return;
       }
 
+      // Logout: clear our local JWT and revoke the Kratos session. Kratos' own cookie lives on
+      // its origin, so we can't clear it here — redirect the browser to Kratos' logout URL (it
+      // revokes the session, clears plainpages_session, then lands on /login per kratos.yml).
+      // No active session ⇒ just clear our cookie and go to /login.
+      if (pathname === "/logout" && (method === "GET" || method === "HEAD") && kratos) {
+        const flow = await kratos.createLogoutFlow(req.headers.cookie ? { cookie: req.headers.cookie } : {});
+        res.writeHead(303, { location: flow?.logoutUrl ?? "/login", "set-cookie": clearSessionCookie() }).end();
+        return;
+      }
+
       if (pathname === "/" && (method === "GET" || method === "HEAD")) {
         // Roles from the verified JWT (anonymous ⇒ []); branding/override come from config/menu.ts.
         sendHtml(res, 200, await render("index", { model: buildDashboardModel(ctx.url, ctx.roles, menu) }));

src/kratos-public.test.ts

@@ -109,3 +109,13 @@ test("whoami throws on an unexpected upstream error", async () => {
   const { fetchImpl } = recorder(() => res(500, { error: "boom" }));
   await assert.rejects(createKratosPublic({ baseUrl: BASE, fetchImpl }).whoami(), KratosError);
 });
+
+test("createLogoutFlow returns the logout URL/token on 200 (cookie forwarded) and null on 401 (no session)", async () => {
+  const flow = { logout_token: "lt", logout_url: `${BASE}/self-service/logout?token=lt` };
+  const { calls, fetchImpl } = recorder((url) => (url.endsWith("/self-service/logout/browser") ? res(200, flow) : res(401)));
+  const out = await createKratosPublic({ baseUrl: BASE, fetchImpl }).createLogoutFlow({ cookie: "plainpages_session=s" });
+  assert.deepEqual(out, { logoutToken: "lt", logoutUrl: flow.logout_url });
+  assert.match(calls[0]!.url, /\/self-service\/logout\/browser$/);
+  assert.equal(calls[0]!.headers.get("cookie"), "plainpages_session=s");
+  assert.equal(await createKratosPublic({ baseUrl: BASE, fetchImpl: (async () => res(401)) as typeof fetch }).createLogoutFlow(), null);
+});

src/kratos-public.ts

@@ -1,6 +1,6 @@
 // Kratos public-API client (todo §4): typed `fetch` wrappers over Ory Kratos' public
-// endpoints — self-service flow init/get/submit, session `whoami`, and the session→JWT
-// tokenizer (`whoami?tokenize_as`). Built-in `fetch` only, no SDK dep (AGENTS.md). The
+// endpoints — self-service flow init/get/submit, browser logout, session `whoami`, and the
+// session→JWT tokenizer (`whoami?tokenize_as`). Built-in `fetch` only, no SDK dep (AGENTS.md). The
 // themed flow pages and login completion (§4) build on this; rendering flow `ui.nodes`
 // and mapping field errors is the renderer's job (§4), so we keep those types loose.
 
@@ -46,6 +46,11 @@ export interface FlowInit {
   setCookie: string[]; // Kratos' CSRF cookie(s) to relay to the browser
 }
 
+export interface LogoutFlow {
+  logoutToken: string; // CSRF token Kratos embeds in logoutUrl
+  logoutUrl: string; // send the browser here to revoke the session + clear Kratos' cookie
+}
+
 export interface FlowSubmission {
   body: unknown; // parsed JSON: the re-rendered flow on 400, the success payload on 200
   location: string | null; // redirect target (Location header, or a 422 redirect_browser_to)
@@ -67,6 +72,7 @@ export class KratosError extends Error {
 }
 
 export interface KratosPublic {
+  createLogoutFlow(opts?: { cookie?: string }): Promise<LogoutFlow | null>; // null ⇒ no active session (401)
   getFlow(type: FlowType, id: string, opts?: { cookie?: string }): Promise<Flow>;
   initBrowserFlow(type: FlowType, opts?: { cookie?: string; returnTo?: string }): Promise<FlowInit>;
   submitFlow(action: string, opts: { body: string; contentType?: string; cookie?: string }): Promise<FlowSubmission>;
@@ -99,6 +105,15 @@ export function createKratosPublic(config: { baseUrl: string; fetchImpl?: typeof
   }
 
   return {
+    async createLogoutFlow(opts = {}) {
+      // Browser logout: get the logout URL (carrying a CSRF token) to send the browser to.
+      const res = await http(new URL(`${base}/self-service/logout/browser`), { headers: headers(opts.cookie), redirect: "manual" });
+      if (res.status === 401) return null; // no active session to revoke
+      if (res.status !== 200) throw new KratosError(`Kratos logout flow failed (${res.status})`, res.status, await res.text());
+      const body = (await res.json()) as { logout_token: string; logout_url: string };
+      return { logoutToken: body.logout_token, logoutUrl: body.logout_url };
+    },
+
     async initBrowserFlow(type, opts = {}) {
       const url = new URL(`${base}/self-service/${type}/browser`);
       if (opts.returnTo) url.searchParams.set("return_to", opts.returnTo);

src/login.test.ts

@@ -31,6 +31,7 @@ const adminStub = (over: Partial<KratosAdmin> = {}): KratosAdmin => ({
 });
 
 const publicStub = (over: Partial<KratosPublic> = {}): KratosPublic => ({
+  createLogoutFlow: async () => null,
   getFlow: async () => { throw new Error("unused"); },
   initBrowserFlow: async () => { throw new Error("unused"); },
   submitFlow: async () => { throw new Error("unused"); },

src/shell.test.ts

@@ -30,6 +30,9 @@ test("app shell renders sidebar, topbar and the content slot", async () => {
   assert.match(html, /<section id="body-marker">page<\/section>/); // content slot
   assert.match(html, /<button id="action-marker"/); // topbar actions slot
 
+  // Sign out is wired to the logout route (the side-footer profile menu).
+  assert.match(html, /<a class="menu-item danger" href="\/logout">/);
+
   // Branding, document title, and the inlined icon sprite (so <use> resolves).
   assert.match(html, /Acme Console/);
   assert.match(html, /<title>People<\/title>/);

todo.md

@@ -85,7 +85,7 @@ everything via Docker.
 - [x] JWKS fetch + cache + rotation handling. → `src/jwks.ts`: `cachingJwks(load, opts)` self-refreshing provider behind the existing `JwksProvider.getKey` seam (drop-in, callers untouched) — holds keys for `ttlMs` (5m), reloads on the next lookup past TTL, and on a `kid` miss reloads **once more** (rotation-on-miss → a freshly-prepended key verifies without a restart, README zero-downtime rotation), throttled by `minRefetchMs` (60s) so a stream of bogus kids can't hammer the source. A reload failure keeps the last-good set (transient resilience); only a cold cache propagates the error (→ middleware fails closed). Concurrent loads coalesce on one in-flight promise. `createJwksProvider(jwksUrl)` routes by scheme + primes at boot (fail loud): `base64://` → immutable `staticJwks`; `file://` → re-readable cache (rotation by remount/edit); `http(s)://` → new `fetchJwks` (Accept JSON, non-2xx throws). `server.ts` now `await createJwksProvider(config.jwksUrl)` (top-level await already present) — replaces `staticJwks(loadJwks(...))`. Tests-first (`jwks.test.ts`: TTL cache+expiry, rotation-on-miss + throttle, last-good-on-error vs cold-load-propagates, scheme routing + http prime/cache + fail-loud on non-2xx/missing-file/bad-scheme). README **Layout** line updated; the **JWT signing key & rotation** + flow-diagram cache notes already described this. typecheck + 203 units green; boot-smoked the file:// prime path. Guards/re-mint/logout/CSRF are the next §4 items.
 - [x] Guards: `requireSession` (validate JWT), `can(role)` (claim, in-process), `check(relation, object)` (live Keto). → `src/guards.ts`: in-handler authorization (imperative counterpart to the §2 declarative route `permission` gate; the JWT was already verified once by the §4 middleware → `ctx.user`/`ctx.roles`, so these never call Ory for the coarse tiers). `requireSession(ctx)` asserts a session → returns the `User`, else throws `GuardError(401, location:/login)`; `can(ctx, role)` is the coarse zero-I/O JWT-claim predicate (anonymous ⇒ false); `check(keto, ctx, {namespace, object, relation})` is the one live Keto call (fine-grained relationship tier, README) — subject = `user:<id>`, anonymous ⇒ false fail-closed (no call). New `GuardError {status, location?}`; `app.ts`'s request catch maps it (location ⇒ 303 redirect, else render the 403 page) **before** the 500 path, so a guard thrown anywhere in handling becomes the right response, never a 500. Tests-first: `guards.test.ts` (requireSession return/throw, `can` matrix, `check` subject + fail-closed) + an `app.test.ts` HTTP integration (anonymous → `/login`, `can`/`check` pass → 200 / fail → 403). README **Building blocks** + `docs/plugin-contract.md` Routes document them (dropped the "land with §4" marker). typecheck + 207 units green. Session re-mint / logout / CSRF are the next §4 items.
 - [x] Session re-mint on TTL expiry (re-read roles from Keto). → "stay signed in": the ~10m JWT lapses but the 30d Kratos session lives, so the hot path silently re-mints instead of dropping to anonymous. `jwt-middleware.ts` now classifies the cookie via `resolveSession` → `{user, expired}` (`TokenError.expired` set only on a lapsed-but-intact token); `authenticate` delegates to it. `login.ts` adds `remintSession` (reuses `completeLogin`: whoami → re-read roles from Keto → re-project → re-tokenize → fresh cookie + refreshed user — the one moment authz recomputes) + `clearSessionCookie` (Max-Age=0). `app.ts` hot path: only when the token is *expired* (not absent/garbage) **and** the Ory clients are wired does it re-mint, setting the cookie via `res.setHeader` so it rides whatever response follows; a dead Kratos session clears the stale cookie so later requests fall straight through to anonymous (no per-request Ory hit). Tests-first: `jwt-middleware.test.ts` (resolveSession lapsed-vs-absent/tampered matrix), `login.test.ts` (remintSession live→fresh / dead→clearing), `app.test.ts` (expired+live session → gated route runs + fresh cookie; expired+dead session → 403 + cleared cookie). typecheck + 210 units green. Live-stack token-timeout/refresh Playwright E2E is the §4 line 90 item.
-- [ ] Logout: revoke Kratos session + clear cookie.
+- [x] Logout: revoke Kratos session + clear cookie. → `GET /logout` (`app.ts`): clears our local `plainpages_jwt` (`clearSessionCookie`, Max-Age=0) **and** revokes the Kratos session. Kratos' own cookie lives on its origin, so we can't expire it from here — instead `kratos.createLogoutFlow(cookie)` (new `KratosPublic` method, `GET /self-service/logout/browser` → `{logoutToken, logoutUrl}`, 401⇒null) and 303 the browser to `logoutUrl`; Kratos revokes the session, clears `plainpages_session`, and lands on `/login` (`kratos.yml` `logout.after`, already configured). No active session ⇒ just clear our cookie + 303 `/login`. Wired the inert shell "Sign out" button → `<a href="/logout">` (zero-JS, matches the menu's existing link items). Tests-first: `kratos-public.test.ts` (logout flow 200→urls / 401→null + cookie forwarded), `app.test.ts` integration (active session → Kratos logout URL + cleared JWT; no session → `/login` + cleared JWT), `shell.test.ts` (sign-out link wired). typecheck + 212 units green. Boot-verified live: admin login → `/logout` 303s to the real `…/self-service/logout?token=ory_lo_…` with `plainpages_jwt` cleared, following it revokes the session (`whoami` 200→401) and redirects to `/login`; no-session `/logout` → `/login`; torn down.
 - [ ] Secure cookie flags; CSRF for our own POST forms.
 - [ ] Make sure we have E2E tests for token timeouts and refresh (maybe by shorten the token lifetime to very low or something).
 - [ ] Run the architecture _and_ the stability reviewer agents on the _whole_ project, not just the latest changes, and address their issues.

views/partials/shell.ejs

@@ -53,7 +53,7 @@
               <div class="menu-pop left up" style="min-width:220px">
                 <div class="menu-head">Signed in as <%= user.name %></div>
                 <button class="menu-item" type="button"><svg class="ico"><use href="#i-user" /></svg>Profile</button>
-                <button class="menu-item danger" type="button"><svg class="ico"><use href="#i-logout" /></svg>Sign out</button>
+                <a class="menu-item danger" href="/logout"><svg class="ico"><use href="#i-logout" /></svg>Sign out</a>
               </div>
             </details>