@flytedesk/app-kit 6.0.0 → 7.0.0

package/dist/auth/plugin.js

@@ -4,14 +4,45 @@ import fastifyCookie from "@fastify/cookie";
 import { AuthStoreError, IdpAccessRevokedError, IdpUnavailableError, classifyIdpError, } from "./errors.js";
 import { createOidcClient, DEFAULT_OIDC_SCOPES } from "./oidc-client.js";
 import { generatePkce, randomState } from "./pkce.js";
-import { AUTH_REQUEST_DEADLINE_MS, AUTH_ROUTE_PREFIX, authRoutePath, SIGNIN_ERROR_QUERY_PARAM, } from "./shared-types.js";
+import { AUTH_REQUEST_DEADLINE_MS, AUTH_ROUTE_PREFIX, authRoutePath, RETURN_TO_QUERY_PARAM, SIGNIN_ERROR_QUERY_PARAM, } from "./shared-types.js";
 import { requireAuth } from "./guards.js";
-import { renderSilentAuthPage } from "./silentAuthPage.js";
+import { safeReturnTarget } from "./returnTarget.js";
 import { sendAuthUnavailable } from "./unavailable.js";
 import { generateRefreshToken, hashRefreshToken, MIN_ACCESS_TOKEN_SECRET_BYTES, refreshSuccessorKey, signAccessToken, successorRefreshToken, verifyAccessToken, } from "./tokens.js";
 const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 900;
 const DEFAULT_REFRESH_TOKEN_TTL_SECONDS = 2_592_000;
 const DEFAULT_LOGIN_ATTEMPT_TTL_SECONDS = 600;
+/**
+ * The largest `Set-Cookie` a sign-in attempt may produce (AK-35). A browser keeps at
+ * most 4096 bytes per cookie and silently drops a larger one, which would fail that
+ * sign-in's callback as "expired"; this leaves headroom under that for the attributes.
+ * `safeReturnTarget` already bounds the target, but JSON-escaping inside the cookie value
+ * can grow it again (a backslash doubles), so the serialized cookie itself is checked.
+ */
+const MAX_LOGIN_ATTEMPT_COOKIE_BYTES = 3800;
+/**
+ * A login-attempt `state` as `randomState()` produces it (24 random bytes, base64url)
+ * — checked before a callback builds a cookie NAME from the `state` it was handed, so an
+ * attacker-chosen `state` can never shape a cookie name.
+ */
+const LOGIN_STATE_PATTERN = /^[A-Za-z0-9_-]{32}$/;
+function parseLoginAttempt(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const { verifier, returnTo, issuedAt } = parsed;
+    if (typeof verifier !== "string" || typeof issuedAt !== "number")
+        return null;
+    if (returnTo !== null && typeof returnTo !== "string")
+        return null;
+    return { verifier, returnTo, issuedAt };
+}
 /**
  * Runs one `AuthStore` call, wrapping anything it throws in `AuthStoreError` named after
  * the method (AK-23) — so every route can tell a storage failure apart from an IdP
@@ -53,7 +84,6 @@ const REQUIRED_STRING_OPTIONS = [
     "redirectUri",
     "appId",
     "postLoginRedirect",
-    "signInUrl",
     "accessTokenSecret",
 ];
 function assertRequiredOptions(options) {
@@ -87,12 +117,9 @@ const flytedeskAuthPlugin = async (fastify, options) => {
     // See FlytedeskAuthOptions.refreshReuseGraceMs's doc comment (AK-14, gap 3; MP-127)
     // for why 2x the client's own request deadline is the right default.
     const refreshReuseGraceMs = options.refreshReuseGraceMs ?? 2 * AUTH_REQUEST_DEADLINE_MS;
-    // The origin a silent (`prompt=none`) callback's postMessage targets — see
-    // sendSilentResult below. Reuses postLoginRedirect's origin (the SPA a hidden iframe's
-    // parent page is running) rather than a new, redundant option: every consumer of the
-    // silent flow already has to set postLoginRedirect to that same origin for the
-    // interactive flow to land anywhere sensible.
-    const silentAuthTargetOrigin = new URL(options.postLoginRedirect).origin;
+    // The app's own web origin (AK-35): every return target resolves against it, and it is
+    // the only Origin POST {routePrefix}/logout accepts.
+    const appOrigin = new URL(options.postLoginRedirect).origin;
     const store = options.store;
     // The key refresh-token rotation derives successors with (see successorRefreshToken).
     const successorKey = refreshSuccessorKey(options.accessTokenSecret);
@@ -124,7 +151,14 @@ const flytedeskAuthPlugin = async (fastify, options) => {
     // would just make the browser silently refuse to set the cookie.
     const useHostPrefix = options.secureCookies;
     const refreshCookieName = useHostPrefix ? "__Host-fd_refresh" : "fd_refresh";
-    const loginCookieName = useHostPrefix ? "__Host-fd_login_attempt" : "fd_login_attempt";
+    // AK-35: one login-attempt cookie PER ATTEMPT, named after its `state`, so two tabs
+    // signing in at once never overwrite each other's PKCE verifier (one shared name made
+    // the second `/login` fail the first callback's state check).
+    const loginCookiePrefix = useHostPrefix ? "__Host-fd_login_" : "fd_login_";
+    // AK-35: set by an explicit sign-out, cleared by the next successful sign-in. While it
+    // is present, `/login` asks flytedesk-id for `prompt=login`, so a signed-out browser
+    // can never be signed straight back in by a still-live flytedesk-id session.
+    const signedOutCookieName = useHostPrefix ? "__Host-fd_signed_out" : "fd_signed_out";
     // fastify-plugin (fp, below) keeps this plugin's routes in the SAME encapsulation
     // context as whatever it's registered under — so if a consumer nests it inside an
     // outer `{ prefix: "/api/v1" }` context, `fastify.prefix` here is already "/api/v1"
@@ -136,30 +170,28 @@ const flytedeskAuthPlugin = async (fastify, options) => {
     // scoping; Fastify's own `inject()` test helper doesn't, which is why this only
     // surfaced against a real browser (see the nested-prefix test below).
     const cookiePath = useHostPrefix ? "/" : `${fastify.prefix}${routePrefix}`;
-    function refreshCookieOptions(maxAgeSeconds) {
-        return {
-            httpOnly: true,
-            sameSite: "lax",
-            secure: options.secureCookies,
-            path: cookiePath,
-            maxAge: maxAgeSeconds,
-        };
+    /**
+     * The attributes every cookie this plugin sets carries: httpOnly, SameSite=Lax, Secure
+     * per `secureCookies`, scoped to `cookiePath`. The ONE definition, so a set and its
+     * later clear can never disagree.
+     */
+    const cookieAttributes = {
+        httpOnly: true,
+        sameSite: "lax",
+        secure: options.secureCookies,
+        path: cookiePath,
+    };
+    function cookieOptions(maxAgeSeconds, signed = false) {
+        return { ...cookieAttributes, maxAge: maxAgeSeconds, signed };
     }
     /**
-     * The postMessage page a silent (`prompt=none`) `{routePrefix}/callback` answers with
-     * (AK-14, gap 2), read by `./client/silentAuth.ts`'s hidden-iframe listener. Hardened
-     * against a hostile `detail` (AK-23, the silent-callback XSS): see
-     * `./silentAuthPage.ts` for the allowlist, the script-context escaping, and the
-     * hash-pinned CSP set here, whose `frame-ancestors` is the same app origin the message
-     * targets.
+     * Deletes one of this plugin's cookies with the SAME attributes it was set with —
+     * `Secure` above all: a browser refuses any `__Host-` Set-Cookie without `Secure`, the
+     * expiring one that deletes it included, so a bare `clearCookie(name, { path })` would
+     * leave the cookie in place on every HTTPS deployment.
      */
-    function sendSilentResult(reply, status, detailCode) {
-        const page = renderSilentAuthPage(status, detailCode, silentAuthTargetOrigin);
-        return reply
-            .header("Content-Security-Policy", page.contentSecurityPolicy)
-            .header("X-Content-Type-Options", "nosniff")
-            .type("text/html")
-            .send(page.html);
+    function clearOwnCookie(reply, name) {
+        reply.clearCookie(name, cookieAttributes);
     }
     const authorizationCache = new Map();
     const EXPIRY_SKEW_MS = 5_000;
@@ -415,183 +447,150 @@ const flytedeskAuthPlugin = async (fastify, options) => {
      *  cookie and mints this service's own short-lived access token for the session. */
     async function completeSession(reply, refreshToken, userId, idpSessionId) {
         const { token: accessToken, expiresAt } = await signAccessToken(options.accessTokenSecret, accessTokenTtlSeconds, userId, idpSessionId);
-        reply.setCookie(refreshCookieName, refreshToken, refreshCookieOptions(refreshTokenTtlSeconds));
+        reply.setCookie(refreshCookieName, refreshToken, cookieOptions(refreshTokenTtlSeconds));
         return { accessToken, accessTokenExpiresAt: expiresAt.toISOString() };
     }
+    /** Where the browser lands for `returnTo` (null: `postLoginRedirect` itself), plus any
+     *  extra query parameters. Re-validates the target and asserts the result stays on the
+     *  app's origin — the stored target was validated at `/login` already, so a mismatch
+     *  here means a bug, and it throws rather than redirect anywhere else. */
+    function appUrl(returnTo, params = {}) {
+        const target = returnTo === null ? null : safeReturnTarget(returnTo);
+        const url = new URL(target ?? options.postLoginRedirect, options.postLoginRedirect);
+        if (url.origin !== appOrigin) {
+            throw new Error(`@flytedesk/app-kit/auth: return target resolved off the app origin (${url.origin})`);
+        }
+        for (const [key, value] of Object.entries(params))
+            url.searchParams.set(key, value);
+        return url.toString();
+    }
+    /** The names of every login-attempt cookie this request carries. */
+    function loginAttemptCookieNames(request) {
+        return Object.keys(request.cookies).filter((name) => name.startsWith(loginCookiePrefix));
+    }
+    /** Clears every login-attempt cookie on this request except the newest one (by its
+     *  `issuedAt`), and every one that fails verification — see `/login`'s doc comment. */
+    function clearStaleLoginAttempts(request, reply) {
+        const attempts = loginAttemptCookieNames(request).map((name) => {
+            const unsigned = request.unsignCookie(request.cookies[name]);
+            const attempt = unsigned.valid && unsigned.value ? parseLoginAttempt(unsigned.value) : null;
+            return { name, issuedAt: attempt?.issuedAt ?? null };
+        });
+        const newest = attempts
+            .filter((a) => a.issuedAt !== null)
+            .sort((a, b) => b.issuedAt - a.issuedAt)[0];
+        for (const { name } of attempts) {
+            if (name !== newest?.name)
+                clearOwnCookie(reply, name);
+        }
+    }
     /**
-     * GET {routePrefix}/login — starts the flytedesk-id sign-in. A plain redirect meant
-     * to be hit via full-page navigation, not fetch/XHR (except for the `?prompt=none`
-     * silent case below, which is driven from a hidden iframe — same route, same
-     * redirect, just never shown). Generates a PKCE verifier/challenge (S256 —
-     * flytedesk-id makes PKCE mandatory) and a CSRF `state`, stashes both (plus whether
-     * this attempt is silent) in a short-lived signed cookie tied to this browser, then
-     * redirects to flytedesk-id's own /auth endpoint.
+     * GET {routePrefix}/login — starts a flytedesk-id sign-in. A plain redirect meant to
+     * be hit by a full-page navigation (the browser client's `authSession` does that;
+     * never fetch/XHR). Generates a PKCE verifier/challenge (S256 — flytedesk-id makes
+     * PKCE mandatory) and a CSRF `state`, stashes the verifier and the return target in a
+     * short-lived signed cookie NAMED AFTER that `state`, then redirects to flytedesk-id's
+     * own /auth endpoint.
      *
-     * `?prompt=none` (AK-14, gap 2; OIDC Core 3.1.2.1) is the silent-resume flow
-     * `./client/silentAuth.ts` drives from a hidden iframe: `prompt` is passed straight
-     * through to flytedesk-id, which answers from its own existing end-user session
-     * cookie with no visible UI at all — a fresh `code` if that session is live,
-     * `error=login_required` back to redirect_uri if it's not. Everything else about this
-     * route is identical to an interactive sign-in; only the stashed `silent` flag (which
-     * routes the callback's response — see GET {routePrefix}/callback below) and the
-     * `prompt` passed to buildAuthorizeUrl differ.
+     * `returnTo` (AK-35) is where the visitor was — `path?query#hash` on the app's origin.
+     * It is kept only when `safeReturnTarget` accepts it and the resulting cookie fits
+     * (`MAX_LOGIN_ATTEMPT_COOKIE_BYTES`). An unsafe or oversize target is DROPPED and
+     * logged, never answered with a 400: a raw error page on a top-level navigation is a
+     * dead end, and the visitor still signs in, landing on `postLoginRedirect`.
      *
-     * `prompt` is schema-validated to the literal `"none"` (AK-20, gap 4) — the only
-     * value this route's silent-resume handling actually understands; anything else (a
-     * typo, or some other OIDC prompt semantics this plugin never implements) is rejected
-     * with a 400 by Fastify's own schema validation rather than being passed straight
-     * through to flytedesk-id's `/auth` endpoint unexamined.
+     * At most two attempt cookies exist at once (AK-35): every older attempt cookie this
+     * browser still carries is cleared except the newest, before the new one is set. With
+     * the `__Host-` prefix these cookies ride on every API request (`Path=/`), so
+     * abandoned attempts (a closed tab, Back at flytedesk-id, Try again, repeated) would
+     * otherwise pile up past the server's header limit and fail every request with a 431.
      */
-    fastify.get(authRoutePath(routePrefix, "login"), {
-        schema: {
-            querystring: {
-                type: "object",
-                properties: {
-                    prompt: { type: "string", enum: ["none"] },
-                },
-            },
-        },
-    }, async (request, reply) => {
+    fastify.get(authRoutePath(routePrefix, "login"), async (request, reply) => {
         const { verifier, challenge } = generatePkce();
         const state = randomState();
-        const prompt = request.query.prompt;
-        const silent = prompt === "none";
-        reply.setCookie(loginCookieName, JSON.stringify({ verifier, state, silent }), {
-            httpOnly: true,
-            sameSite: "lax",
-            secure: options.secureCookies,
-            path: cookiePath,
-            maxAge: loginAttemptTtlSeconds,
-            signed: true,
-        });
-        // AK-33: `prompt` here is what THIS route was asked for (only ever "none", for
-        // the silent flow) — never what flytedesk-id itself is told. flytedesk-id's real
-        // oidc-provider strips `offline_access` from the granted scope set whenever the
-        // authorize request's own `prompt` doesn't include "consent" (its
-        // check_scope.js), regardless of any previously-saved Grant — so an ordinary
-        // interactive sign-in that never asks for consent NEVER gets a refresh token,
-        // even though DEFAULT_OIDC_SCOPES already requests offline_access (SMS-44: every
-        // session then dies the moment its ~1h IdP access token expires). flytedesk-id
-        // auto-grants any consent prompt server-side with no user-visible screen at all
-        // (every registered client is first-party flytedesk software), so asking for it
-        // costs nothing here. Silent (`prompt=none`) is unaffected — an offline_access
-        // grant obtained through the ordinary interactive flow that preceded it already
-        // covers the resumed session either way.
-        const upstreamPrompt = silent ? "none" : requestsOfflineAccess ? "consent" : undefined;
-        return reply.redirect(oidc.buildAuthorizeUrl({ state, challenge, prompt: upstreamPrompt }));
+        const requested = request.query[RETURN_TO_QUERY_PARAM];
+        let returnTo = requested === undefined ? null : safeReturnTarget(requested);
+        if (requested !== undefined && returnTo === null) {
+            request.log.warn({ returnToLength: requested.length }, "@flytedesk/app-kit/auth: /login — unsafe or oversize returnTo dropped; landing on postLoginRedirect");
+        }
+        const cookieName = `${loginCookiePrefix}${state}`;
+        const attemptCookie = cookieOptions(loginAttemptTtlSeconds, true);
+        const issuedAt = Date.now();
+        const attemptValue = (target) => JSON.stringify({ verifier, returnTo: target, issuedAt });
+        if (returnTo !== null &&
+            fastify.serializeCookie(cookieName, fastify.signCookie(attemptValue(returnTo)), attemptCookie).length >
+                MAX_LOGIN_ATTEMPT_COOKIE_BYTES) {
+            request.log.warn({ returnToLength: returnTo.length }, "@flytedesk/app-kit/auth: /login — returnTo too large for the attempt cookie, dropped; landing on postLoginRedirect");
+            returnTo = null;
+        }
+        clearStaleLoginAttempts(request, reply);
+        reply.setCookie(cookieName, attemptValue(returnTo), attemptCookie);
+        // AK-33: flytedesk-id's real oidc-provider strips `offline_access` from the granted
+        // scope set whenever the authorize request's own `prompt` doesn't include
+        // "consent" (its check_scope.js), regardless of any previously-saved Grant — so a
+        // sign-in that never asks for consent NEVER gets a refresh token and the session
+        // dies with its ~1h IdP access token (SMS-44). flytedesk-id auto-grants consent
+        // server-side with no screen (every registered client is first-party).
+        // AK-35: after an explicit sign-out (the signed-out marker), `login` is added so
+        // flytedesk-id must interact even if its own session is somehow still alive — an
+        // explicit sign-out never bounces straight back in.
+        const prompts = [
+            ...(request.cookies[signedOutCookieName] ? ["login"] : []),
+            ...(requestsOfflineAccess ? ["consent"] : []),
+        ];
+        const prompt = prompts.length > 0 ? prompts.join(" ") : undefined;
+        return reply.redirect(oidc.buildAuthorizeUrl({ state, challenge, prompt }));
     });
     /**
-     * AK-19: where every INTERACTIVE (non-silent) callback failure below redirects, with
-     * a normalized `SignInErrorCode` — never the raw internal failure code and never any
-     * human-readable detail (see `fail` below) — so the app's own sign-in page can render
-     * a specific message from one query param, without each app parsing the callback's
-     * internal error taxonomy. `options.signInUrl` is required (see its doc comment in
-     * ./types.ts): there is no fallback to `postLoginRedirect` or any other guessed path,
-     * so a consumer that forgets to configure it fails registration loudly instead of
-     * shipping this exact dead end unnoticed.
-     */
-    function redirectToSignIn(reply, signInErrorCode) {
-        const target = new URL(options.signInUrl);
-        target.searchParams.set(SIGNIN_ERROR_QUERY_PARAM, signInErrorCode);
-        return reply.redirect(target.toString());
-    }
-    /**
-     * GET {routePrefix}/callback — flytedesk-id's redirect_uri for this client. Validates
-     * `state`, exchanges `code` + the stashed PKCE verifier at flytedesk-id's /token
-     * (Basic auth — the one place client_secret is used), verifies the returned
-     * id_token's signature via flytedesk-id's JWKS, fetches profile claims from
-     * userinfo, then mints this service's own session.
+     * GET {routePrefix}/callback — flytedesk-id's redirect_uri for this client. Reads the
+     * ONE login-attempt cookie named after the returned `state` (so a sibling tab's
+     * attempt is never touched), exchanges `code` + its PKCE verifier at flytedesk-id's
+     * /token (Basic auth — the one place client_secret is used), verifies the returned
+     * id_token's signature via flytedesk-id's JWKS, fetches profile claims from userinfo,
+     * then mints this service's own session and sends the browser to its return target.
+     *
+     * Every failure is logged here, server-side only, and the browser is redirected to its
+     * return target (or `postLoginRedirect`, when the attempt cookie is gone) with
+     * `signin_error=<SignInErrorCode>` — never the raw failure code or any detail. The
+     * browser client shows that as its sign-in-failed state with a manual retry, never
+     * another automatic redirect, which is what keeps a failing sign-in from looping.
      */
     fastify.get(authRoutePath(routePrefix, "callback"), async (request, reply) => {
         const { code, state, error } = request.query;
-        const raw = request.cookies[loginCookieName];
-        reply.clearCookie(loginCookieName, { path: cookiePath });
-        // Recover `silent` before any failure branch below runs, including ones that
-        // never get as far as validating the rest of the stash — a `prompt=none` attempt
-        // that fails (e.g. `error=login_required`, the expected outcome when the
-        // IdP-side session is genuinely gone too) still needs to answer through
-        // sendSilentResult, or the hidden iframe's listener would wait out its full
-        // timeout for a postMessage that was never going to arrive (AK-14, gap 2).
-        //
-        // AK-19, missing-cookie decision: when the login-attempt cookie itself is gone
-        // (expired past its loginAttemptTtlSeconds, or never arrived), `stash` stays
-        // undefined and `silent` below is deliberately `false` — this callback has no way
-        // to recover the `silent` flag that lived only in that cookie, so it can't answer
-        // through sendSilentResult even for an attempt that actually was silent. That's
-        // a deliberate, documented choice, not an oversight: a silent (`prompt=none`)
-        // attempt runs in a hidden iframe and flytedesk-id answers it within seconds, so
-        // in practice an EXPIRED cookie (the 10-minute loginAttemptTtlSeconds) can only
-        // mean an interactive attempt. Treating this case as interactive is also harmless
-        // for the vanishingly unlikely case it's wrong: a redirect delivered inside a
-        // hidden iframe is invisible to the user, and the parent page's own listener
-        // simply times out exactly as it would have if this callback had never answered
-        // at all. The same reasoning — and the same fallback to `silent = false` — applies
-        // identically below whenever `stash` can't be recovered for any other reason
-        // (the cookie's signature fails, or its JSON payload is malformed).
-        let stash;
+        // The CSRF `state` check IS this lookup: the only attempt cookie that can be read
+        // is the one this browser was given for exactly this `state` at `/login`. A
+        // callback carrying any other `state` (a forged or replayed one) finds no cookie
+        // and fails as an expired attempt.
+        const cookieName = state && LOGIN_STATE_PATTERN.test(state) ? `${loginCookiePrefix}${state}` : null;
+        const raw = cookieName ? request.cookies[cookieName] : undefined;
+        if (cookieName)
+            clearOwnCookie(reply, cookieName);
+        let attempt = null;
         if (raw) {
             const unsigned = request.unsignCookie(raw);
-            if (unsigned.valid && unsigned.value) {
-                try {
-                    stash = JSON.parse(unsigned.value);
-                }
-                catch {
-                    stash = undefined;
-                }
-            }
+            if (unsigned.valid && unsigned.value)
+                attempt = parseLoginAttempt(unsigned.value);
         }
-        const silent = stash?.silent === true;
-        /**
-         * Answers ONE callback failure. Silent (AK-14): the hardened postMessage page
-         * (`sendSilentResult` above), whose `detail` is `code` mapped onto the fixed
-         * `SILENT_AUTH_DETAIL_CODES` set — never `code` itself, which for an `idp_error`
-         * is the attacker-reachable `error` query parameter (AK-23). Interactive (AK-19):
-         * redirects (302) to the app's own sign-in page via `redirectToSignIn`, carrying
-         * only the normalized `signInErrorCode` — never `code`, never `message`, never a
-         * response body at all. `message` (and `err`, when the failure came from an
-         * upstream call) is logged server-side ONLY, exactly once, right here — the one
-         * place every failure branch below funnels through. A silent `login_required` is the
-         * routine "no flytedesk-id session to resume" answer, not a failure, so it alone is
-         * not logged.
-         */
-        function fail(code, message, signInErrorCode, err) {
-            if (silent) {
-                if (code !== "login_required") {
-                    request.log.error({ err, code }, `@flytedesk/app-kit/auth: silent callback failed — ${message}`);
-                }
-                return sendSilentResult(reply, "error", code);
-            }
-            // Always .error, not .warn: every one of these is the "fail loudly" pattern
-            // this file uses throughout (AK-16) — the ONLY place the real detail (and, for
-            // an upstream failure, the actual err) is ever recorded, since the redirect
-            // below carries neither.
-            request.log.error({ err, code }, `@flytedesk/app-kit/auth: interactive callback failed — ${message}`);
-            return redirectToSignIn(reply, signInErrorCode);
+        const returnTo = attempt?.returnTo ?? null;
+        function fail(failureCode, message, signInErrorCode, err) {
+            request.log.error({ err, code: failureCode }, `@flytedesk/app-kit/auth: callback failed — ${message}`);
+            return reply.redirect(appUrl(returnTo, { [SIGNIN_ERROR_QUERY_PARAM]: signInErrorCode }));
         }
         if (error) {
             // access_denied: the user declined at flytedesk-id — "cancelled". Every other
-            // idp_error (including login_required reaching here on an INTERACTIVE attempt,
-            // which is unexpected but not impossible) collapses to "other" — see
-            // SignInErrorCode's doc comment on why this stays a closed, three-way set.
-            const signInErrorCode = error === "access_denied" ? "cancelled" : "other";
-            return fail(error, `flytedesk-id sign-in failed: ${error}`, signInErrorCode);
+            // idp_error collapses to "other" (see SignInErrorCode's doc comment).
+            return fail(error, `flytedesk-id sign-in failed: ${error}`, error === "access_denied" ? "cancelled" : "other");
         }
         if (!code || !state || !raw) {
-            // Missing cookie specifically means the 10-minute login-attempt window elapsed
-            // before flytedesk-id redirected back — "expired" (see the missing-cookie
-            // decision above). Missing code/state with the cookie still present is a
-            // different, much rarer malformed-request shape — "other".
-            const signInErrorCode = !raw ? "expired" : "other";
-            return fail("invalid_callback", "Missing code/state, or the login attempt expired", signInErrorCode);
-        }
-        if (!stash) {
-            return fail("invalid_login_cookie", "Login attempt cookie failed verification", "other");
+            // A missing attempt cookie means the attempt window (loginAttemptTtlSeconds)
+            // elapsed before flytedesk-id redirected back, or the cookie never arrived —
+            // "expired". Missing code/state with the cookie present is a malformed request.
+            return fail("invalid_callback", "Missing code/state, or the login attempt expired", !raw ? "expired" : "other");
         }
-        if (stash.state !== state) {
-            return fail("invalid_state", "State mismatch", "other");
+        if (!attempt) {
+            return fail("invalid_login_cookie", "Login attempt cookie failed verification", "other");
         }
         try {
-            const tokens = await oidc.exchangeCodeForTokens(code, stash.verifier);
+            const tokens = await oidc.exchangeCodeForTokens(code, attempt.verifier);
             // Confirms WHO signed in (sub) via a local signature check — aud/iss are
             // verified inside verifyIdToken against options.clientId/options.issuer.
             const idToken = await oidc.verifyIdToken(tokens.id_token);
@@ -603,13 +602,14 @@ const flytedeskAuthPlugin = async (fastify, options) => {
                 return fail("email_not_verified", "flytedesk-id account email is not verified", "other");
             }
             if (options.onSignIn) {
-                await options.onSignIn(profile, request, { mode: silent ? "silent" : "interactive" });
+                await options.onSignIn(profile, request);
             }
             const name = profile.name ?? profile.email.split("@")[0];
             const idpSession = await store.createIdpSession({
                 subject: profile.sub,
                 name,
                 email: profile.email,
+                idToken: tokens.id_token,
                 idpAccessToken: tokens.access_token,
                 idpAccessTokenExpiresAt: idpAccessTokenExpiresAt(tokens),
                 idpRefreshToken: tokens.refresh_token ?? null,
@@ -619,16 +619,10 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             const first = newRefreshToken(request, { familyId: randomUUID(), userId: profile.sub, idpSessionId: idpSession.id }, generateRefreshToken());
             await store.createRefreshToken(first.row);
             await completeSession(reply, first.token, profile.sub, idpSession.id);
-            if (silent) {
-                // No top-level navigation at all — completeSession() above already set the real
-                // refresh cookie on this (the API's) origin as a side effect of this same
-                // response, which is the only thing that actually needed to happen. This page
-                // just tells the hidden iframe's listener it can stop waiting; the parent page
-                // picks the new session up via its own regular {routePrefix}/refresh + /me,
-                // exactly like any other reload would (AK-14, gap 2).
-                return sendSilentResult(reply, "success");
-            }
-            return reply.redirect(options.postLoginRedirect);
+            // A completed sign-in ends the signed-out state (AK-35).
+            if (request.cookies[signedOutCookieName])
+                clearOwnCookie(reply, signedOutCookieName);
+            return reply.redirect(appUrl(returnTo));
         }
         catch (err) {
             return fail("idp_exchange_failed", "Sign-in with flytedesk-id failed", "other", err);
@@ -642,14 +636,14 @@ const flytedeskAuthPlugin = async (fastify, options) => {
      *  response can land after it and delete the fresh token. */
     function rejectRefresh(reply, { clearCookie }) {
         if (clearCookie)
-            reply.clearCookie(refreshCookieName, { path: cookiePath });
+            clearOwnCookie(reply, refreshCookieName);
         return reply.code(401).send({ error: "Refresh token expired or revoked", code: "unauthenticated" });
     }
     /** Revokes the family behind a refresh the authorization pipeline rejected, and 401s
      *  with the cookie cleared. */
     async function rejectFamily(reply, row) {
         await storeCall("revokeFamily", () => store.revokeFamily(row.familyId, { type: "authorization_rejected" }, new Date()));
-        reply.clearCookie(refreshCookieName, { path: cookiePath });
+        clearOwnCookie(reply, refreshCookieName);
         reply.code(401).send({ error: "Authorization rejected", code: "unauthenticated" });
     }
     /** The request's own client fields, as the reuse audit and the resume log record them. */
@@ -678,7 +672,7 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             request.log.error({ err, ...context }, "@flytedesk/app-kit/auth: refresh token reuse detected but revoking the family FAILED — family still live");
             throw err;
         }
-        reply.clearCookie(refreshCookieName, { path: cookiePath });
+        clearOwnCookie(reply, refreshCookieName);
         reply.code(401).send({ error: "Refresh token reuse detected", code: "token_reuse_detected" });
     }
     /**
@@ -755,7 +749,7 @@ const flytedeskAuthPlugin = async (fastify, options) => {
     async function refreshSession(request, reply, token, now) {
         const stored = await storeCall("findRefreshTokenByHash", () => store.findRefreshTokenByHash(hashRefreshToken(token)));
         if (!stored) {
-            reply.clearCookie(refreshCookieName, { path: cookiePath });
+            clearOwnCookie(reply, refreshCookieName);
             reply.code(401).send({ error: "Refresh token not recognized", code: "unauthenticated" });
             return;
         }
@@ -764,7 +758,7 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             return;
         }
         if (stored.expiresAt < now) {
-            reply.clearCookie(refreshCookieName, { path: cookiePath });
+            clearOwnCookie(reply, refreshCookieName);
             reply.code(401).send({ error: "Refresh token expired", code: "unauthenticated" });
             return;
         }
@@ -858,7 +852,7 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             return;
         }
         if (head.revocation || head.expiresAt < now) {
-            reply.clearCookie(refreshCookieName, { path: cookiePath });
+            clearOwnCookie(reply, refreshCookieName);
             reply.code(401).send({ error: "Refresh token expired or revoked", code: "unauthenticated" });
             return;
         }
@@ -938,7 +932,7 @@ const flytedeskAuthPlugin = async (fastify, options) => {
      * per-request authorization check the `onRequest` hook above already ran (AK-18). Every
      * `@flytedesk/app-kit/auth` consumer was hand-writing this exact route against its own
      * `request.authUser` (sms-app's `apps/api/src/app.ts`, before this card) — extracting it
-     * here means the client (`./client/useAuthSession.js`) can bootstrap from ONE route the
+     * here means the client (`./client/authSession.js`) can bootstrap from ONE route the
      * plugin actually serves, at the path `../shared-types.js`'s route contract says it
      * does, instead of every app re-declaring the same three lines and the same response
      * shape by hand.
@@ -947,34 +941,57 @@ const flytedeskAuthPlugin = async (fastify, options) => {
         return reply.send({ user: request.authUser });
     });
     /**
-     * POST {routePrefix}/logout — revokes the whole refresh-token family (not just the
-     * presented cookie) and the IdpSession row, and best-effort revokes the IdP-side
-     * refresh token if flytedesk-id's discovery document advertises a revocation endpoint
-     * (flytedesk-id currently documents NOT having one, so that step is expected to no-op;
-     * `revokeIdpToken` never throws either way).
+     * POST {routePrefix}/logout — an explicit sign-out (AK-35). Same-origin only: the
+     * request's `Origin` must be the app's own (`postLoginRedirect`'s origin), or it is
+     * answered 403 `forbidden_origin` and nothing is touched — otherwise any site could
+     * sign a visitor out with a cross-site form POST.
+     *
+     * Ends this app's session: revokes the whole refresh-token family
+     * (not just the presented cookie) and the IdpSession row, and best-effort revokes the
+     * IdP-side refresh token if flytedesk-id's discovery document advertises a revocation
+     * endpoint (flytedesk-id currently has none, so that step is expected to no-op;
+     * `revokeIdpToken` never throws either way). Each store step is attempted
+     * independently (`endSignedInSession`): a failed family revoke does not stop the
+     * IdpSession delete, which on its own already makes the family unusable (`/refresh`
+     * revokes a family whose IdP session is gone).
+     *
+     * In a `finally`, on EVERY outcome past the Origin check: the refresh cookie is cleared
+     * (AK-23) and the signed-out marker is set (AK-35), so the next `/login` from this
+     * browser asks flytedesk-id for `prompt=login` — an explicit sign-out never bounces
+     * straight back in, however the rest of the sign-out went.
      *
-     * AK-23: the refresh cookie is cleared in `finally`, so it is cleared on EVERY
-     * outcome — 3.x cleared it only on the happy path, so a throwing store call answered a
-     * raw 500 that left the browser holding a cookie for an unrevoked family. Each store
-     * step is attempted independently (`endSignedInSession`): a failed family revoke does
-     * not stop the IdpSession delete, which on its own already makes the family unusable
-     * (`/refresh` revokes a family whose IdP session is gone). Any failed step answers
-     * 502 `logout_store_failed`, logged — never a silent, fully-clean "signed out".
+     * Answers `{ endSessionUrl }` — flytedesk-id's RP-initiated logout, carrying the
+     * session's id_token as `id_token_hint` and `postLoginRedirect` as the
+     * `post_logout_redirect_uri` — which the browser client navigates to so flytedesk-id
+     * ends ITS session too. 200 when every step succeeded; 502 `logout_store_failed`
+     * (logged, and still carrying `endSessionUrl`, since this browser's session is over
+     * either way) when a store step failed.
      */
     fastify.post(authRoutePath(routePrefix, "logout"), async (request, reply) => {
+        if (request.headers.origin !== appOrigin) {
+            request.log.warn({ origin: request.headers.origin ?? null }, "@flytedesk/app-kit/auth: /logout refused — Origin is not the app's own");
+            return reply.code(403).send({ error: "Sign-out must come from the app itself", code: "forbidden_origin" });
+        }
         const token = request.cookies[refreshCookieName];
-        let complete = true;
+        let ended = { complete: true, idToken: null };
         try {
             if (token)
-                complete = await endSignedInSession(request, token);
+                ended = await endSignedInSession(request, token);
         }
         finally {
-            reply.clearCookie(refreshCookieName, { path: cookiePath });
+            clearOwnCookie(reply, refreshCookieName);
+            reply.setCookie(signedOutCookieName, "1", cookieOptions(refreshTokenTtlSeconds));
         }
-        if (!complete) {
-            return reply.code(502).send({ error: "Sign-out did not fully complete", code: "logout_store_failed" });
+        const endSessionUrl = oidc.buildEndSessionUrl({
+            idTokenHint: ended.idToken,
+            postLogoutRedirectUri: options.postLoginRedirect,
+        });
+        if (!ended.complete) {
+            return reply
+                .code(502)
+                .send({ error: "Sign-out did not fully complete", code: "logout_store_failed", endSessionUrl });
         }
-        return reply.send({ loggedOut: true });
+        return reply.send({ endSessionUrl });
     });
     /**
      * Runs one logout store step, logging (never throwing) its failure. Returns the step's
@@ -989,22 +1006,24 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             return { ok: false };
         }
     }
-    /** Ends the sign-in behind one refresh cookie; true when every step succeeded (or
-     *  there was nothing to end). */
+    /** Ends the sign-in behind one refresh cookie. */
     async function endSignedInSession(request, token) {
         const found = await logoutStep(request, "findRefreshTokenByHash", () => store.findRefreshTokenByHash(hashRefreshToken(token)));
         if (!found.ok)
-            return false;
+            return { complete: false, idToken: null };
         const stored = found.value;
         if (!stored)
-            return true;
+            return { complete: true, idToken: null };
         const revoked = await logoutStep(request, "revokeFamily", () => store.revokeFamily(stored.familyId, { type: "signed_out" }, new Date()));
         const session = await logoutStep(request, "findIdpSession", () => store.findIdpSession(stored.idpSessionId));
         if (session.ok && session.value?.idpRefreshToken) {
             await oidc.revokeIdpToken(session.value.idpRefreshToken);
         }
         const deleted = await logoutStep(request, "deleteIdpSession", () => store.deleteIdpSession(stored.idpSessionId));
-        return revoked.ok && session.ok && deleted.ok;
+        return {
+            complete: revoked.ok && session.ok && deleted.ok,
+            idToken: session.ok ? (session.value?.idToken ?? null) : null,
+        };
     }
 };
 export const flytedeskAuth = fp(flytedeskAuthPlugin, {